IOleObjectImpl Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at IOleObjectImpl Class.

This class implements IUnknown and is the principal interface through which a container communicates with a control.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

template<class T>  
class ATL_NO_VTABLE IOleObjectImpl : public IOleObject

Parameters

T
Your class, derived from IOleObjectImpl.

Members

Public Methods

Name	Description
IOleObjectImpl::Advise	Establishes an advisory connection with the control.
IOleObjectImpl::Close	Changes the control state from running to loaded.
IOleObjectImpl::DoVerb	Tells the control to perform one of its enumerated actions.
IOleObjectImpl::DoVerbDiscardUndo	Tells the control to discard any undo state it is maintaining.
IOleObjectImpl::DoVerbHide	Tells the control to remove its user interface from view.
IOleObjectImpl::DoVerbInPlaceActivate	Runs the control and installs its window, but does not install the control's user interface.
IOleObjectImpl::DoVerbOpen	Causes the control to be open-edited in a separate window.
IOleObjectImpl::DoVerbPrimary	Performs the specified action when the user double-clicks the control. The control defines the action, usually to activate the control in-place.
IOleObjectImpl::DoVerbShow	Shows a newly inserted control to the user.
IOleObjectImpl::DoVerbUIActivate	Activates the control in-place and shows the control's user interface, such as menus and toolbars.
IOleObjectImpl::EnumAdvise	Enumerates the control's advisory connections.
IOleObjectImpl::EnumVerbs	Enumerates actions for the control.
IOleObjectImpl::GetClientSite	Retrieves the control's client site.
IOleObjectImpl::GetClipboardData	Retrieves data from the Clipboard. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::GetExtent	Retrieves the extent of the control's display area.
IOleObjectImpl::GetMiscStatus	Retrieves the status of the control.
IOleObjectImpl::GetMoniker	Retrieves the control's moniker. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::GetUserClassID	Retrieves the control's class identifier.
IOleObjectImpl::GetUserType	Retrieves the control's user-type name.
IOleObjectImpl::InitFromData	Initializes the control from selected data. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::IsUpToDate	Checks if the control is up to date. The ATL implementation returns `S_OK`.
IOleObjectImpl::OnPostVerbDiscardUndo	Called by DoVerbDiscardUndo after the undo state is discarded.
IOleObjectImpl::OnPostVerbHide	Called by DoVerbHide after the control is hidden.
IOleObjectImpl::OnPostVerbInPlaceActivate	Called by DoVerbInPlaceActivate after the control is activated in place.
IOleObjectImpl::OnPostVerbOpen	Called by DoVerbOpen after the control has been opened for editing in a separate window.
IOleObjectImpl::OnPostVerbShow	Called by DoVerbShow after the control has been made visible.
IOleObjectImpl::OnPostVerbUIActivate	Called by DoVerbUIActivate after the control's user interface has been activated.
IOleObjectImpl::OnPreVerbDiscardUndo	Called by DoVerbDiscardUndo before the undo state is discarded.
IOleObjectImpl::OnPreVerbHide	Called by DoVerbHide before the control is hidden.
IOleObjectImpl::OnPreVerbInPlaceActivate	Called by DoVerbInPlaceActivate before the control is activated in place.
IOleObjectImpl::OnPreVerbOpen	Called by DoVerbOpen before the control has been opened for editing in a separate window.
IOleObjectImpl::OnPreVerbShow	Called by DoVerbShow before the control has been made visible.
IOleObjectImpl::OnPreVerbUIActivate	Called by DoVerbUIActivate before the control's user interface has been activated.
IOleObjectImpl::SetClientSite	Tells the control about its client site in the container.
IOleObjectImpl::SetColorScheme	Recommends a color scheme to the control's application, if any. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::SetExtent	Sets the extent of the control's display area.
IOleObjectImpl::SetHostNames	Tells the control the names of the container application and container document.
IOleObjectImpl::SetMoniker	Tells the control what its moniker is. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::Unadvise	Deletes an advisory connection with the control.
IOleObjectImpl::Update	Updates the control. The ATL implementation returns `S_OK`.

Remarks

The IOleObject interface is the principal interface through which a container communicates with a control. Class IOleObjectImpl provides a default implementation of this interface and implements IUnknown by sending information to the dump device in debug builds.

Related Articles ATL Tutorial, Creating an ATL Project

Inheritance Hierarchy

IOleObject

IOleObjectImpl

Requirements

Header: atlctl.h

IOleObjectImpl::Advise

Establishes an advisory connection with the control.

STDMETHOD(Advise)(
    IAdviseSink* pAdvSink,
    DWORD* pdwConnection);

Remarks

See IOleObject::Advise in the Windows SDK.

IOleObjectImpl::Close

Changes the control state from running to loaded.

STDMETHOD(Close)(DWORD dwSaveOption);

Remarks

Deactivates the control and destroys the control window if it exists. If the control class data member CComControlBase::m_bRequiresSave is TRUE and the dwSaveOption parameter is either OLECLOSE_SAVEIFDIRTY or OLECLOSE_PROMPTSAVE, the control properties are saved before closing.

The pointers held in the control class data members CComControlBase::m_spInPlaceSite and CComControlBase::m_spAdviseSink are released, and the data members CComControlBase::m_bNegotiatedWnd, CComControlBase::m_bWndless, and CComControlBase::m_bInPlaceSiteEx are set to FALSE.

See IOleObject::Close in the Windows SDK.

IOleObjectImpl::DoVerb

Tells the control to perform one of its enumerated actions.

STDMETHOD(DoVerb)(
    LONG iVerb,
    LPMSG /* pMsg */,
    IOleClientSite* pActiveSite,
    LONG /* lindex */,
    HWND hwndParent,
    LPCRECT lprcPosRect);

Remarks

Depending on the value of iVerb, one of the ATL DoVerb helper functions is called as follows:

iVerb Value	DoVerb helper function called
OLEIVERB_DISCARDUNDOSTATE	DoVerbDiscardUndo
`OLEIVERB_HIDE`	DoVerbHide
OLEIVERB_INPLACEACTIVATE	DoVerbInPlaceActivate
`OLEIVERB_OPEN`	DoVerbOpen
`OLEIVERB_PRIMARY`	DoVerbPrimary
OLEIVERB_PROPERTIES	CComControlBase::DoVerbProperties
`OLEIVERB_SHOW`	DoVerbShow
`OLEIVERB_UIACTIVATE`	DoVerbUIActivate

See IOleObject::DoVerb in the Windows SDK.

IOleObjectImpl::DoVerbDiscardUndo

Tells the control to discard any undo state it is maintaining.

HRESULT DoVerbDiscardUndo(LPCRECT /* prcPosRect */, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control.

Return Value

Returns S_OK.

IOleObjectImpl::DoVerbHide

Deactivates and removes the control's user interface, and hides the control.

HRESULT DoVerbHide(LPCRECT /* prcPosRect */, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control. Not used in the ATL implementation.

Return Value

Returns S_OK.

IOleObjectImpl::DoVerbInPlaceActivate

Runs the control and installs its window, but does not install the control's user interface.

HRESULT DoVerbInPlaceActivate(LPCRECT prcPosRect, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control. Not used in the ATL implementation.

Return Value

One of the standard HRESULT values.

Remarks

Activates the control in place by calling CComControlBase::InPlaceActivate. Unless the control class's data member m_bWindowOnly is TRUE, DoVerbInPlaceActivate first attempts to activate the control as a windowless control (possible only if the container supports IOleInPlaceSiteWindowless). If that fails, the function attempts to activate the control with extended features (possible only if the container supports IOleInPlaceSiteEx). If that fails, the function attempts to activate the control with no extended features (possible only if the container supports IOleInPlaceSite). If activation succeeds, the function notifies the container the control has been activated.

IOleObjectImpl::DoVerbOpen

Causes the control to be open-edited in a separate window.

HRESULT DoVerbOpen(LPCRECT /* prcPosRect */, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control.

Return Value

Returns S_OK.

IOleObjectImpl::DoVerbPrimary

Defines the action taken when the user double-clicks the control.

HRESULT DoVerbPrimary(LPCRECT prcPosRect, HWND hwndParent);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control.

Return Value

One of the standard HRESULT values.

Remarks

By default, set to display the property pages. You can override this in your control class to invoke a different behavior on double-click; for example, play a video or go in-place active.

IOleObjectImpl::DoVerbShow

Tells the container to make the control visible.

HRESULT DoVerbShow(LPCRECT prcPosRect, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control. Not used in the ATL implementation.

Return Value

One of the standard HRESULT values.

IOleObjectImpl::DoVerbUIActivate

Activates the control's user interface and notifies the container that its menus are being replaced by composite menus.

HRESULT DoVerbUIActivate(LPCRECT prcPosRect, HWND /* hwndParent */);

Parameters

prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.

hwndParent
[in] Handle of the window containing the control. Not used in the ATL implementation.

Return Value

One of the standard HRESULT values.

IOleObjectImpl::EnumAdvise

Supplies an enumeration of registered advisory connections for this control.

STDMETHOD(EnumAdvise)(IEnumSTATDATA** ppenumAdvise);

Remarks

See IOleObject::EnumAdvise in the Windows SDK.

IOleObjectImpl::EnumVerbs

Supplies an enumeration of registered actions (verbs) for this control by calling OleRegEnumVerbs.

STDMETHOD(EnumVerbs)(IEnumOLEVERB** ppEnumOleVerb);

Remarks

You can add verbs to your project's .rgs file. For example, see CIRCCTL.RGS in the CIRC sample.

See IOleObject::EnumVerbs in the Windows SDK.

IOleObjectImpl::GetClientSite

Puts the pointer in the control class data member CComControlBase::m_spClientSite into ppClientSite and increments the reference count on the pointer.

STDMETHOD(GetClientSite)(IOleClientSite** ppClientSite);

Remarks

See IOleObject::GetClientSite in the Windows SDK.

IOleObjectImpl::GetClipboardData

Retrieves data from the Clipboard.

STDMETHOD(GetClipboardData)(    
    DWORD /* dwReserved */,
    IDataObject** /* ppDataObject */);

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::GetClipboardData in the Windows SDK.

IOleObjectImpl::GetExtent

Retrieves a running control's display size in HIMETRIC units (0.01 millimeter per unit).

STDMETHOD(GetExtent)(
    DWORD dwDrawAspect,
    SIZEL* psizel);

Remarks

The size is stored in the control class data member CComControlBase::m_sizeExtent.

See IOleObject::GetExtent in the Windows SDK.

IOleObjectImpl::GetMiscStatus

Returns a pointer to registered status information for the control by calling OleRegGetMiscStatus.

STDMETHOD(GetMiscStatus)(
    DWORD dwAspect,
    DWORD* pdwStatus);

Remarks

The status information includes behaviors supported by the control and presentation data. You can add status information to your project's .rgs file.

See IOleObject::GetMiscStatus in the Windows SDK.

IOleObjectImpl::GetMoniker

Retrieves the control's moniker.

STDMETHOD(GetMoniker)(
    DWORD /* dwAssign */,
    DWORD /* dwWhichMoniker */,
    IMoniker** /* ppmk */);

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::GetMoniker in the Windows SDK.

IOleObjectImpl::GetUserClassID

Returns the control's class identifier.

STDMETHOD(GetUserClassID)(CLSID* pClsid);

Remarks

See IOleObject::GetUserClassID in the Windows SDK.

IOleObjectImpl::GetUserType

Returns the control's user-type name by calling OleRegGetUserType.

STDMETHOD(GetUserType)(
    DWORD dwFormOfType,
    LPOLESTR* pszUserType);

Remarks

The user-type name is used for display in user-interfaces elements such as menus and dialog boxes. You can change the user-type name in your project's .rgs file.

See IOleObject::GetUserType in the Windows SDK.

IOleObjectImpl::InitFromData

Initializes the control from selected data.

STDMETHOD(InitFromData)(
    IDataObject* /* pDataObject */,
    BOOL /* fCreation */,
    DWORD /* dwReserved */);

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::InitFromData in the Windows SDK.

IOleObjectImpl::IsUpToDate

Checks if the control is up to date.

STDMETHOD(IsUpToDate)(void);

Return Value

Returns S_OK.

Remarks

See IOleObject::IsUpToDate in the Windows SDK.

IOleObjectImpl::OnPostVerbDiscardUndo

Called by DoVerbDiscardUndo after the undo state is discarded.

HRESULT OnPostVerbDiscardUndo();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the undo state is discarded.

IOleObjectImpl::OnPostVerbHide

Called by DoVerbHide after the control is hidden.

HRESULT OnPostVerbHide();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the control is hidden.

IOleObjectImpl::OnPostVerbInPlaceActivate

Called by DoVerbInPlaceActivate after the control is activated in place.

HRESULT OnPostVerbInPlaceActivate();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the control is activated in place.

IOleObjectImpl::OnPostVerbOpen

Called by DoVerbOpen after the control has been opened for editing in a separate window.

HRESULT OnPostVerbOpen();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the control has been opened for editing in a separate window.

IOleObjectImpl::OnPostVerbShow

Called by DoVerbShow after the control has been made visible.

HRESULT OnPostVerbShow();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the control has been made visible.

IOleObjectImpl::OnPostVerbUIActivate

Called by DoVerbUIActivate after the control's user interface has been activated.

HRESULT OnPostVerbUIActivate();

Return Value

Returns S_OK.

Remarks

Override this method with code you want executed after the control's user interface has been activated.

IOleObjectImpl::OnPreVerbDiscardUndo

Called by DoVerbDiscardUndo before the undo state is discarded.

HRESULT OnPreVerbDiscardUndo();

Return Value

Returns S_OK.

Remarks

To prevent the undo state from being discarded, override this method to return an error HRESULT.

IOleObjectImpl::OnPreVerbHide

Called by DoVerbHide before the control is hidden.

HRESULT OnPreVerbHide();

Return Value

Returns S_OK.

Remarks

To prevent the control from being hidden, override this method to return an error HRESULT.

IOleObjectImpl::OnPreVerbInPlaceActivate

Called by DoVerbInPlaceActivate before the control is activated in place.

HRESULT OnPreVerbInPlaceActivate();

Return Value

Returns S_OK.

Remarks

To prevent the control from being activated in place, override this method to return an error HRESULT.

IOleObjectImpl::OnPreVerbOpen

Called by DoVerbOpen before the control has been opened for editing in a separate window.

HRESULT OnPreVerbOpen();

Return Value

Returns S_OK.

Remarks

To prevent the control from being opened for editing in a separate window, override this method to return an error HRESULT.

IOleObjectImpl::OnPreVerbShow

Called by DoVerbShow before the control has been made visible.

HRESULT OnPreVerbShow();

Return Value

Returns S_OK.

Remarks

To prevent the control from being made visible, override this method to return an error HRESULT.

IOleObjectImpl::OnPreVerbUIActivate

Called by DoVerbUIActivate before the control's user interface has been activated.

HRESULT OnPreVerbUIActivate();

Return Value

Returns S_OK.

Remarks

To prevent the control's user interface from being activated, override this method to return an error HRESULT.

IOleObjectImpl::SetClientSite

Tells the control about its client site in the container.

STDMETHOD(SetClientSite)(IOleClientSite* pClientSite);

Remarks

The method then returns S_OK.

See IOleObject::SetClientSite in the Windows SDK.

IOleObjectImpl::SetColorScheme

Recommends a color scheme to the control's application, if any.

STDMETHOD(SetColorScheme)(LOGPALETTE* /* pLogPal */);

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::SetColorScheme in the Windows SDK.

IOleObjectImpl::SetExtent

Sets the extent of the control's display area.

STDMETHOD(SetExtent)(
    DWORD dwDrawAspect,
    SIZEL* psizel);

Remarks

Otherwise, SetExtent stores the value pointed to by psizel in the control class data member CComControlBase::m_sizeExtent. This value is in HIMETRIC units (0.01 millimeter per unit).

If the control class data member CComControlBase::m_bResizeNatural is TRUE, SetExtent also stores the value pointed to by psizel in the control class data member CComControlBase::m_sizeNatural.

If the control class data member CComControlBase::m_bRecomposeOnResize is TRUE, SetExtent calls SendOnDataChange and SendOnViewChange to notify all advisory sinks registered with the advise holder that the control size has changed.

See IOleObject::SetExtent in the Windows SDK.

IOleObjectImpl::SetHostNames

Tells the control the names of the container application and container document.

STDMETHOD(SetHostNames)(LPCOLESTR /* szContainerApp */, LPCOLESTR /* szContainerObj */);

Return Value

Returns S_OK.

Remarks

See IOleObject::SetHostNames in the Windows SDK.

IOleObjectImpl::SetMoniker

Tells the control what its moniker is.

STDMETHOD(SetMoniker)(
    DWORD /* dwWhichMoniker */,
    IMoniker** /* pmk */);

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::SetMoniker in the Windows SDK.

IOleObjectImpl::Unadvise

Deletes the advisory connection stored in the control class's m_spOleAdviseHolder data member.

STDMETHOD(Unadvise)(DWORD dwConnection);

Remarks

See IOleObject::Unadvise in the Windows SDK.

IOleObjectImpl::Update

Updates the control.

STDMETHOD(Update)(void);

Return Value

Returns S_OK.

Remarks

See IOleObject::Update in the Windows SDK.