IOleDocumentView::Open

Asks a document view to display itself in a separate pop-up window with semantics equivalent to IOleObject::DoVerb(OLEIVERB_OPEN).

HRESULT Open(Void);

Return Values

S_OK

The view successfully created its separate window.

E_OUTOFMEMORY

There was not enough memory to activate the view in a separate window.

E_FAIL

Some other error occurred that prevented success.

E_NOTIMPL

The document object that owns this view does not support separate window activation.

E_UNEXPECTED

This method was called before a call to IOleDocumentView::SetInPlaceSite.

Remarks

A user viewing a document object in a container application such as a browser or “binder” may want to see two or more views or documents at once. Because the browser displays only one view at a time, the container needs a way to instruct the other views or documents to display themselves, as required, in separate windows. The IOleDocumentView::Open method provides that way.

Notes to Callers

A successful call to IOleDocumentView::Open should be followed by a call to IOleDocumentView::Show(FALSE) to hide the window or IOleDocumentView::Show(TRUE) to show the window and bring it to the foreground. While the view is active in its separate window, a container can show or hide the window as many times as it may require.

Notes to Implementers

A document object that does not support activation in a separate window indicates as much by setting DOCMISC_CANTOPENEDIT in its DOCMISC enumeration and returning E_NOTIMPL to containers that nevertheless call this method in an attempt to open it. Objects that have a limited interface for activation purposes should be sure to set DOCMISC_CANTOPENEDIT.

Otherwise, implementation generally consists of calling the view’s own interface, in response to which the view shows its separate pop-up window and brings that window to the foreground.

When the separate window is no longer needed, the container calls IOleDocumentView::Close, whereupon the view releases its site pointer to the separate window and destroys the window. Contrary to the normal in-place deactivation sequence for OLE Documents, however, a document view continues to hold the IOleInPlaceSite, pointer that it obtained from the container’s call to IOleDocumentView::SetInPlaceSite. This pointer is only released when the view's container calls IOleDocumentView::SetInPlaceSite and sets pIPSite to NULL or calls IOleDocumentView::CloseView.

When a user closes a view’s separate window, the view should not shut itself down. Instead, it should call IOleInPlaceSite::OnInPlaceActivate. The view site then decides whether to call IOleDocumentView::UIActivate(FALSE) immediately or later. In this way, a document view displayed in a separate window remains available for activation in the container's own window.

See Also

IOleDocumentView::Close, IOleDocumentView::Show, IOleDocumentView::UIActivate, IOleInPlaceObject::InPlaceDeactivate, IOleInPlaceSite, IOleInPlaceSite::OnInPlaceActivate