IOleDocumentView::UIActivate

IOleDocumentView::UIActivate

Activates or deactivates a document view's user-interface elements, such as menus, toolbars, and accelerators.

HRESULT UIActivate(

    BOOL fUIActivate

// Boolean value specifying whether to activate or deactivate view

);

Parameters

fUIActivate

[in] TRUE instructs the view to activate its user interface; FALSE instructs the view to deactivate its user interface.

Return Value

S_OK

The view's user interface was successfully activated or deactivated.

E_OUTOFMEMORY

There was not enough memory to activate the view's user interface.

E_FAIL

Some other critical error occurred that prevented activation or deactivation of the user interface.

E_UNEXPECTED

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

Remarks

Calling this method is part of the normal activation and deactivation sequences of a document object.

Notes to Callers

Calling this method before calling IOleDocumentView::SetInPlaceSite returns an error because the view must know where it is activating itself before it can proceed to do so. When calling IOleDocumentView::UIActivate as part of the activation sequence, the call should precede one to IOleDocumentView::SetRect (or SetRectComplex) because otherwise the container would send to the view dimensions that would be incorrect because they would not account for toolbar space.

When deactivating a view, the container should call IOleDocumentView::Show(FALSE), followed by IOleDocumentView::UIActivate(FALSE).

Notes to Implementers

Implementations of this method should embody the following pseudo-code:

if (fActivate)

{

UI activate the view (do menu merging, show frame level tools, process accelerators)

Take focus, and bring the view window forward.

}

else

call IOleInPlaceObject::UIDeactivate on this view

In addition, the view may, and should, participate in extended Help menu merging.

All views of a document object must at least support the in-place activation mode. Therefore, E_NOTIMPL is not allowed as a return value.