IOleDocument::CreateView

IOleDocument::CreateView

Creates a document view object in the callerÆs process and returns a pointer to that objectÆs IOleDocumentView interface.

HRESULT CreateView(

    IOleInPlaceSite

 * pIPSite,           // Pointer to containerÆs view-site object

    IStream * pstm,                      // Pointer to a stream object

    DWORD dwReserved,                    // Reserved for future use

    IOleDocumentView * ppView            // Indirect pointer to the new document view object

);

Parameters

pIPSite

[in] Pointer to the view-site object to be associated with the new document view object. May be NULL, as when creating a new, uninitialized document object, in which case the caller must initialize the view with a subsequent call to IOleDocumentView::SetInPlaceSite.

pstm

[in] Pointer to a stream containing data from which the new document view object should initialize itself. Normally will be NULL when the specified view is for a new, uninitialized document object. If NULL, the document object initializes the new document view object with a default state.

dwReserved

[in] Reserved for future use. In the future this parameter could be used to specify the type of view that needs to be created. Currently there are no defined values for this argument.

ppView

[out] Indirect pointer to the new document view object. If CreateView succeeds, the caller is responsible for calling Release through this pointer when the view object is no longer needed.

Return Values

S_OK

The view was created successfully.

E_POINTER

The address in ppView is NULL.

E_OUTOFMEMORY

Out of memory.

E_UNEXPECTED

An unexpected error occurred.

E_FAIL

An unspecified error occurred.

Remarks

A document-object containerÆs document site calls IOleDocumentView::CreateView to instruct a document object to create a new view of itself in the containerÆs process, either from scratch or by using the contents of an existing stream.

Calling CreateView does not cause the new view to display itself. To do so, the view must wait for calls to either IOleDocumentView::Show or IOleDocumentView::UIActivate.

Notes to Callers

The call to CreateView normally occurs in the containerÆs implementation of IOleDocumentSite::ActivateMe. If a document object passes an IOleDocumentView pointer in its call to ActivateMe, the container has no need to call CreateView and instead can call IOleDocumentView::SetInPlaceSite, followed by AddRef. If a document object returns a NULL view pointer in its call to ActivateMe, then the container calls CreateView to retrieve a view pointer.

The container has the option of passing a pointer to a stream containing data to be used to initialize the requested view. If the container passes a NULL stream pointer, then the document object will initialize the new view using its default settings.

Notes to Implementers

This method must be completely implemented for any document object. Therefore E_NOTIMPL is not an acceptable return value.

If pIPSite is non-NULL, then the document object should pass the pointer to the new view through IOleDocumentView::SetInPlaceSite. If pIPSite is NULL, the caller is responsible for making this same call. In addition, if pstm is non-NULL, then the object should initialize the view object by passing pstm to IOleDocumentView::ApplyViewState.

As with all new interface pointers, CreateView should call AddRef on the pointer in *ppView before returning. The caller is responsible for calling Release through this pointer when it is no longer needed.