IOleDocumentSite::ActivateMe

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

This method supports the standard return values E_OUTOFMEMORY and E_FAIL, as well as the following:

S_OK

The container activated the view successfully.

Remarks

When a container calls IOleObject::DoVerb to activate a document, a document object bypasses the usual in-place activation sequence by calling IOleDocumentSite::ActivateMe.

When calling IOleObject::DoVerb on a document object, the most appropriate activation verb is usually OLEIVERB_SHOW. Other allowable verbs include OLEIVERB_PRIMARY and OLEIVERB_UIACTIVATE. OLEIVERB_OPEN is discouraged because it means opening an embedded object in a separate window, which is contrary to the intent of document object activation.

Notes to Callers

Only document objects should call this method. A normal in-place active 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 view object. 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 pViewToActivate is 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

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in docobj.h.