Asks a document site to activate the document making the call as a document object rather than an in-place-active object and, optionally, specifies which view of the object document to activate.
HRESULT ActivateMe(
IOleDocumentView
* pViewToActivate // Pointer to the view to be activated
);
Parameters
pViewToActivate
[in] Pointer to the document view to be used in activating the document object. Can be NULL, in which case the container should call IOleDocument::CreateView to obtain a document view pointer.
Return Value
S_OK
The container activated the view successfully.
E_OUTOFMEMORY
pViewToActivate is NULL and the containerÆs call to IOleDocument::CreateView failed with E_OUTOFMEMORY.
E_FAIL
Another error occurred in either view creation or activation.
Remarks
When a container calls IOleObject::DoVerb to request a document to activate, a document object bypasses the usual in-place activation sequence by calling IOleDocumentSite::ActivateMe.
When calling IOleObject::DoVerb on a document object, containers will usually find OLEIVERB_SHOW to be the most appropriate activation verb. Other allowable verbs include OLEIVERB_PRIMARY and OLEIVERB_UIACTIVATE. OLEIVERB_OPEN is discouraged because it implies opening an embedded object in a separate window, which is contrary to the intent of document object activation.
Notes to Callers
Only OLE document objects should call this method. A normal in-place active OLE document should respond to a container's call to IOleObject::DoVerb by calling IOleInPlaceSite.
A document object should initiate its activation by calling IOleDocumentSite::ActivateMe. If the container does not implement IOleDocumentSite, then the document should default to the normal in-place activation sequence.
A document object that supports more than one view of its data can specify which view to activate by passing a pointer to that view's IOleDocumentView interface in pViewToActivate.
However the IOleDocumentView pointer is obtained, the container should release the pointer when it is no longer needed.
Notes to Implementers
This function must be completely implemented in a document object container; E_NOTIMPL is not an acceptable return value.
If a document object passes an IOleDocumentView pointer in pViewToActivate, the container's implementation of ActivateMe should call IOleDocumentView::SetInPlaceSite and pass a pointer to its IOleInPlaceSite interface back to the document. If the container is holding onto the IOleDocumentView pointer, which will normally be the case, it should follow the call to SetInPlaceSite with a call to AddRef.
If a document object sets the value of pViewToActivate to NULL, the container can obtain a pointer to a document view by querying the document for IOleDocument, then calling IOleDocument::CreateView and passing its IOleInPlaceSite pointer.
See Also
IOleClientSite, IOleDocument::CreateView, IOleDocumentView::SetInPlaceSite, IOleInPlaceSite, IOleObject::DoVerb