IOleDocumentSite::ActivateMe method (docobj.h)

Article
10/13/2021

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.

Syntax

HRESULT ActivateMe(
  [in] IOleDocumentView *pViewToActivate
);

Parameters

[in] pViewToActivate

A pointer to an IOleDocumentView interface pointer that represents the document view to be used in activating the document object. This parameter can be NULL, in which case the container should call IOleDocument::CreateView to obtain a document view pointer.

Return value

This method returns S_OK on success.

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 IOleDocumentSite::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 IOleDocumentView::SetInPlaceSite with a call to IUnknown::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.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	docobj.h