IOleDocumentView::UIActivate method (docobj.h)

Article
10/13/2021

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

Syntax

HRESULT UIActivate(
  [in] BOOL fUIActivate
);

Parameters

[in] fUIActivate

If TRUE, the view is to activate its user interface. If FALSE, the view is to deactivate its user interface.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return code	Description
E_FAIL	The operation failed.
E_OUTOFMEMORY	Insufficient memory available for operation.
E_UNEXPECTED	An unexpected error occurred.

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 IOleDocumentView::SetRectComplex, because otherwise the view dimensions would not account for toolbar space.

To deactivate a view, the container should call IOleDocumentView::Show with FALSE, followed by IOleDocumentView::UIActivate with FALSE.

Notes to Implementers

Implementations of this method should embody the following pseudocode.

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.

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

Share via