IOleObjectImpl Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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

System_CAPS_ICON_important.jpg Important

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

template<class T>  
class ATL_NO_VTABLE IOleObjectImpl : public IOleObject

Parameters

T
Your class, derived from IOleObjectImpl.

Public Methods

NameDescription
IOleObjectImpl::AdviseEstablishes an advisory connection with the control.
IOleObjectImpl::CloseChanges the control state from running to loaded.
IOleObjectImpl::DoVerbTells the control to perform one of its enumerated actions.
IOleObjectImpl::DoVerbDiscardUndoTells the control to discard any undo state it is maintaining.
IOleObjectImpl::DoVerbHideTells the control to remove its user interface from view.
IOleObjectImpl::DoVerbInPlaceActivateRuns the control and installs its window, but does not install the control's user interface.
IOleObjectImpl::DoVerbOpenCauses the control to be open-edited in a separate window.
IOleObjectImpl::DoVerbPrimaryPerforms the specified action when the user double-clicks the control. The control defines the action, usually to activate the control in-place.
IOleObjectImpl::DoVerbShowShows a newly inserted control to the user.
IOleObjectImpl::DoVerbUIActivateActivates the control in-place and shows the control's user interface, such as menus and toolbars.
IOleObjectImpl::EnumAdviseEnumerates the control's advisory connections.
IOleObjectImpl::EnumVerbsEnumerates actions for the control.
IOleObjectImpl::GetClientSiteRetrieves the control's client site.
IOleObjectImpl::GetClipboardDataRetrieves data from the Clipboard. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::GetExtentRetrieves the extent of the control's display area.
IOleObjectImpl::GetMiscStatusRetrieves the status of the control.
IOleObjectImpl::GetMonikerRetrieves the control's moniker. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::GetUserClassIDRetrieves the control's class identifier.
IOleObjectImpl::GetUserTypeRetrieves the control's user-type name.
IOleObjectImpl::InitFromDataInitializes the control from selected data. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::IsUpToDateChecks if the control is up to date. The ATL implementation returns S_OK.
IOleObjectImpl::OnPostVerbDiscardUndoCalled by DoVerbDiscardUndo after the undo state is discarded.
IOleObjectImpl::OnPostVerbHideCalled by DoVerbHide after the control is hidden.
IOleObjectImpl::OnPostVerbInPlaceActivateCalled by DoVerbInPlaceActivate after the control is activated in place.
IOleObjectImpl::OnPostVerbOpenCalled by DoVerbOpen after the control has been opened for editing in a separate window.
IOleObjectImpl::OnPostVerbShowCalled by DoVerbShow after the control has been made visible.
IOleObjectImpl::OnPostVerbUIActivateCalled by DoVerbUIActivate after the control's user interface has been activated.
IOleObjectImpl::OnPreVerbDiscardUndoCalled by DoVerbDiscardUndo before the undo state is discarded.
IOleObjectImpl::OnPreVerbHideCalled by DoVerbHide before the control is hidden.
IOleObjectImpl::OnPreVerbInPlaceActivateCalled by DoVerbInPlaceActivate before the control is activated in place.
IOleObjectImpl::OnPreVerbOpenCalled by DoVerbOpen before the control has been opened for editing in a separate window.
IOleObjectImpl::OnPreVerbShowCalled by DoVerbShow before the control has been made visible.
IOleObjectImpl::OnPreVerbUIActivateCalled by DoVerbUIActivate before the control's user interface has been activated.
IOleObjectImpl::SetClientSiteTells the control about its client site in the container.
IOleObjectImpl::SetColorSchemeRecommends a color scheme to the control's application, if any. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::SetExtentSets the extent of the control's display area.
IOleObjectImpl::SetHostNamesTells the control the names of the container application and container document.
IOleObjectImpl::SetMonikerTells the control what its moniker is. The ATL implementation returns E_NOTIMPL.
IOleObjectImpl::UnadviseDeletes an advisory connection with the control.
IOleObjectImpl::UpdateUpdates the control. The ATL implementation returns S_OK.

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

IOleObject

IOleObjectImpl

Header: atlctl.h

Establishes an advisory connection with the control.

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

Remarks

See IOleObject::Advise in the Windows SDK.

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.

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 ValueDoVerb helper function called
OLEIVERB_DISCARDUNDOSTATEDoVerbDiscardUndo
OLEIVERB_HIDEDoVerbHide
OLEIVERB_INPLACEACTIVATEDoVerbInPlaceActivate
OLEIVERB_OPENDoVerbOpen
OLEIVERB_PRIMARYDoVerbPrimary
OLEIVERB_PROPERTIESCComControlBase::DoVerbProperties
OLEIVERB_SHOWDoVerbShow
OLEIVERB_UIACTIVATEDoVerbUIActivate

See IOleObject::DoVerb in the Windows SDK.

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.

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.

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.

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.

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.

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.

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.

Supplies an enumeration of registered advisory connections for this control.

STDMETHOD(EnumAdvise)(IEnumSTATDATA** ppenumAdvise);

Remarks

See IOleObject::EnumAdvise in the Windows SDK.

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.

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.

Retrieves data from the Clipboard.

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

Return Value

Returns E_NOTIMPL.

Remarks

See IOleObject::GetClipboardData in the Windows SDK.

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.

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.

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.

Returns the control's class identifier.

STDMETHOD(GetUserClassID)(CLSID* pClsid);

Remarks

See IOleObject::GetUserClassID in the Windows SDK.

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.

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.

Checks if the control is up to date.

STDMETHOD(IsUpToDate)(void);

Return Value

Returns S_OK.

Remarks

See IOleObject::IsUpToDate in the Windows SDK.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Updates the control.

STDMETHOD(Update)(void);

Return Value

Returns S_OK.

Remarks

See IOleObject::Update in the Windows SDK.

CComControl Class
ActiveX Controls Interfaces
Class Overview

Show: