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] If TRUE, the view is to activate its user interface. If FALSE, the view is to deactivate its user interface.

Return Value

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

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

Remarks

Notes to Callers

Calling this method before calling IOleDocumentView::SetInPlaceSite returns E_UNEXPECTED, because the view must be associated with a view site before it can activate itself.

When IOleDocumentView::UIActivate is called as part of the activation sequence, the call should precede a call to IOleDocumentView::SetRect or SetRectComplex, because otherwise the view dimensions would not account for toolbar space.

To deactivate 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 can and should participate in extended Help menu merging.

All views of a document object must support in-place activation. E_NOTIMPL is not an acceptable return value.

QuickInfo

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