IOleDocument::CreateView method

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

Syntax

HRESULT CreateView(
  [in]  IOleInPlaceSite  *pIPSite,
  [in]  IStream          *pstm,
  [in]  DWORD            dwReserved,
  [out] IOleDocumentView **ppView
);

Parameters

pIPSite [in]

A pointer to the IOleInPlaceSite interface that represents the view site object to be associated with the new document view object. This parameter can be NULL, for example, when the view is contained in a new, uninitialized document object, in which case the caller must initialize the view with a subsequent call to IOleDocumentView::SetInPlaceSite.

pstm [in]

A pointer to a stream containing data from which the new document view object should initialize itself. If NULL, the document object initializes the new document view object with a default state.

dwReserved [in]

This parameter is reserved and must be zero.

ppView [out]

A pointer to an IOleDocumentView pointer variable that receives the interface pointer to the new document view object. When successful, the caller is responsible for calling IUnknown::Release on the ppview pointer when the view object is no longer needed.

Return value

This method returns S_OK on success. Other possible return values include the following.

Notes to Callers

CreateView is normally called by 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 IUnknown::AddRef. If a document object passes a NULL pointer in its call to IOleDocumentSite::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 used to initialize the requested view. If the container passes a NULL stream pointer, 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; E_NOTIMPL is not an acceptable return value.

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

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

Remarks

A document object container's document site calls CreateView to instruct a document object to create a new view of itself in the container's process, either from default data or using the contents of an existing stream.

Calling CreateView does not cause the new view to display itself. To do so requires a call to either IOleDocumentView::Show or IOleDocumentView::UIActivate.

Requirements

See also

IOleDocument

IOleDocumentSite::ActivateMe

IOleDocumentView::ApplyViewState

IOleDocumentView::SetInPlaceSite

IOleDocumentView::Show

IOleDocumentView::UIActivate