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.
template<class T>
class ATL_NO_VTABLE IOleObjectImpl : public IOleObject
T
Your class, derived from IOleObjectImpl.
| 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. |
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);
See IOleObject::Advise in the Windows SDK.
Changes the control state from running to loaded.
STDMETHOD(Close)(DWORD dwSaveOption);
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);
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.
Tells the control to discard any undo state it is maintaining.
HRESULT DoVerbDiscardUndo(LPCRECT /* prcPosRect */, HWND /* hwndParent */);
prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.
hwndParent
[in] Handle of the window containing the control.
Returns S_OK.
Deactivates and removes the control's user interface, and hides the control.
HRESULT DoVerbHide(LPCRECT /* prcPosRect */, HWND /* hwndParent */);
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.
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 */);
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.
One of the standard HRESULT values.
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 */);
prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.
hwndParent
[in] Handle of the window containing the control.
Returns S_OK.
Defines the action taken when the user double-clicks the control.
HRESULT DoVerbPrimary(LPCRECT prcPosRect, HWND hwndParent);
prcPosRec
[in] Pointer to the rectangle the container wants the control to draw into.
hwndParent
[in] Handle of the window containing the control.
One of the standard HRESULT values.
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 */);
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.
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 */);
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.
One of the standard HRESULT values.
Supplies an enumeration of registered advisory connections for this control.
STDMETHOD(EnumAdvise)(IEnumSTATDATA** ppenumAdvise);
See IOleObject::EnumAdvise in the Windows SDK.
Supplies an enumeration of registered actions (verbs) for this control by calling OleRegEnumVerbs.
STDMETHOD(EnumVerbs)(IEnumOLEVERB** ppEnumOleVerb);
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);
See IOleObject::GetClientSite in the Windows SDK.
Retrieves data from the Clipboard.
STDMETHOD(GetClipboardData)(
DWORD /* dwReserved */,
IDataObject** /* ppDataObject */);
Returns E_NOTIMPL.
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);
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);
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 */);
Returns E_NOTIMPL.
See IOleObject::GetMoniker in the Windows SDK.
Returns the control's class identifier.
STDMETHOD(GetUserClassID)(CLSID* pClsid);
See IOleObject::GetUserClassID in the Windows SDK.
Returns the control's user-type name by calling OleRegGetUserType.
STDMETHOD(GetUserType)(
DWORD dwFormOfType,
LPOLESTR* pszUserType);
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 */);
Returns E_NOTIMPL.
See IOleObject::InitFromData in the Windows SDK.
Checks if the control is up to date.
STDMETHOD(IsUpToDate)(void);
Returns S_OK.
See IOleObject::IsUpToDate in the Windows SDK.
Called by DoVerbDiscardUndo after the undo state is discarded.
HRESULT OnPostVerbDiscardUndo();
Returns S_OK.
Override this method with code you want executed after the undo state is discarded.
Called by DoVerbHide after the control is hidden.
HRESULT OnPostVerbHide();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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();
Returns S_OK.
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);
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 */);
Returns E_NOTIMPL.
See IOleObject::SetColorScheme in the Windows SDK.
Sets the extent of the control's display area.
STDMETHOD(SetExtent)(
DWORD dwDrawAspect,
SIZEL* psizel);
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 */);
Returns S_OK.
See IOleObject::SetHostNames in the Windows SDK.
Tells the control what its moniker is.
STDMETHOD(SetMoniker)(
DWORD /* dwWhichMoniker */,
IMoniker** /* pmk */);
Returns E_NOTIMPL.
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);
See IOleObject::Unadvise in the Windows SDK.
Updates the control.
STDMETHOD(Update)(void);
Returns S_OK.
See IOleObject::Update in the Windows SDK.
CComControl Class
ActiveX Controls Interfaces
Class Overview