CComControlBase Class

Article
12/01/2022

This class provides methods for creating and managing ATL controls.

Important

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

Syntax

class ATL_NO_VTABLE CComControlBase

Members

Public Typedefs

Name	Description
CComControlBase::AppearanceType	Override if your `m_nAppearance` stock property isn't of type `short`.

Public Constructors

Name	Description
CComControlBase::CComControlBase	The constructor.
CComControlBase::~CComControlBase	The destructor.

Public Methods

Name	Description
CComControlBase::ControlQueryInterface	Retrieves a pointer to the requested interface.
CComControlBase::DoesVerbActivate	Checks that the iVerb parameter used by `IOleObjectImpl::DoVerb` either activates the control's user interface (iVerb equals OLEIVERB_UIACTIVATE), defines the action taken when the user double-clicks the control (iVerb equals OLEIVERB_PRIMARY), displays the control (iVerb equals OLEIVERB_SHOW), or activates the control (iVerb equals OLEIVERB_INPLACEACTIVATE).
CComControlBase::DoesVerbUIActivate	Checks that the iVerb parameter used by `IOleObjectImpl::DoVerb` causes the control's user interface to activate and returns TRUE.
CComControlBase::DoVerbProperties	Displays the control's property pages.
CComControlBase::FireViewChange	Call this method to tell the container to redraw the control, or notify the registered advise sinks that the control's view has changed.
CComControlBase::GetAmbientAppearance	Retrieves DISPID_AMBIENT_APPEARANCE, the current appearance setting for the control: 0 for flat and 1 for 3D.
CComControlBase::GetAmbientAutoClip	Retrieves DISPID_AMBIENT_AUTOCLIP, a flag indicating whether the container supports automatic clipping of the control display area.
CComControlBase::GetAmbientBackColor	Retrieves DISPID_AMBIENT_BACKCOLOR, the ambient background color for all controls, defined by the container.
CComControlBase::GetAmbientCharSet	Retrieves DISPID_AMBIENT_CHARSET, the ambient character set for all controls, defined by the container.
CComControlBase::GetAmbientCodePage	Retrieves DISPID_AMBIENT_CODEPAGE, the ambient character set for all controls, defined by the container.
CComControlBase::GetAmbientDisplayAsDefault	Retrieves DISPID_AMBIENT_DISPLAYASDEFAULT, a flag that is TRUE if the container has marked the control in this site to be a default button, and therefore a button control should draw itself with a thicker frame.
CComControlBase::GetAmbientDisplayName	Retrieves DISPID_AMBIENT_DISPLAYNAME, the name the container has supplied to the control.
CComControlBase::GetAmbientFont	Retrieves a pointer to the container's ambient `IFont` interface.
CComControlBase::GetAmbientFontDisp	Retrieves a pointer to the container's ambient `IFontDisp` dispatch interface.
CComControlBase::GetAmbientForeColor	Retrieves DISPID_AMBIENT_FORECOLOR, the ambient foreground color for all controls, defined by the container.
CComControlBase::GetAmbientLocaleID	Retrieves DISPID_AMBIENT_LOCALEID, the identifier of the language used by the container.
CComControlBase::GetAmbientMessageReflect	Retrieves DISPID_AMBIENT_MESSAGEREFLECT, a flag indicating whether the container wants to receive window messages (such as WM_DRAWITEM) as events.
CComControlBase::GetAmbientPalette	Retrieves DISPID_AMBIENT_PALETTE, used to access the container's HPALETTE.
CComControlBase::GetAmbientProperty	Retrieves the container property specified by id.
CComControlBase::GetAmbientRightToLeft	Retrieves DISPID_AMBIENT_RIGHTTOLEFT, the direction in which content is displayed by the container.
CComControlBase::GetAmbientScaleUnits	Retrieves DISPID_AMBIENT_SCALEUNITS, the container's ambient units (such as inches or centimeters) for labeling displays.
CComControlBase::GetAmbientShowGrabHandles	Retrieves DISPID_AMBIENT_SHOWGRABHANDLES, a flag indicating whether the container allows the control to display grab handles for itself when active.
CComControlBase::GetAmbientShowHatching	Retrieves DISPID_AMBIENT_SHOWHATCHING, a flag indicating whether the container allows the control to display itself with a hatched pattern when the UI is active.
CComControlBase::GetAmbientSupportsMnemonics	Retrieves DISPID_AMBIENT_SUPPORTSMNEMONICS, a flag indicating whether the container supports keyboard mnemonics.
CComControlBase::GetAmbientTextAlign	Retrieves DISPID_AMBIENT_TEXTALIGN, the text alignment preferred by the container: 0 for general alignment (numbers right, text left), 1 for left alignment, 2 for center alignment, and 3 for right alignment.
CComControlBase::GetAmbientTopToBottom	Retrieves DISPID_AMBIENT_TOPTOBOTTOM, the direction in which content is displayed by the container.
CComControlBase::GetAmbientUIDead	Retrieves DISPID_AMBIENT_UIDEAD, a flag indicating whether the container wants the control to respond to user-interface actions.
CComControlBase::GetAmbientUserMode	Retrieves DISPID_AMBIENT_USERMODE, a flag indicating whether the container is in run-mode (TRUE) or design-mode (FALSE).
CComControlBase::GetDirty	Returns the value of data member `m_bRequiresSave`.
CComControlBase::GetZoomInfo	Retrieves the x and y values of the numerator and denominator of the zoom factor for a control activated for in-place editing.
CComControlBase::InPlaceActivate	Causes the control to transition from the inactive state to whatever state the verb in iVerb indicates.
CComControlBase::InternalGetSite	Call this method to query the control site for a pointer to the identified interface.
CComControlBase::OnDraw	Override this method to draw your control.
CComControlBase::OnDrawAdvanced	The default `OnDrawAdvanced` prepares a normalized device context for drawing, then calls your control class's `OnDraw` method.
CComControlBase::OnKillFocus	Checks that the control is in-place active and has a valid control site, then informs the container that the control has lost focus.
CComControlBase::OnMouseActivate	Checks that the UI is in user mode, then activates the control.
CComControlBase::OnPaint	Prepares the container for painting, gets the control's client area, then calls the control class's `OnDraw` method.
CComControlBase::OnSetFocus	Checks that the control is in-place active and has a valid control site, then informs the container the control has gained focus.
CComControlBase::PreTranslateAccelerator	Override this method to provide your own keyboard accelerator handlers.
CComControlBase::SendOnClose	Notifies all advisory sinks registered with the advise holder that the control has been closed.
CComControlBase::SendOnDataChange	Notifies all advisory sinks registered with the advise holder that the control data has changed.
CComControlBase::SendOnRename	Notifies all advisory sinks registered with the advise holder that the control has a new moniker.
CComControlBase::SendOnSave	Notifies all advisory sinks registered with the advise holder that the control has been saved.
CComControlBase::SendOnViewChange	Notifies all registered advisory sinks that the control's view has changed.
CComControlBase::SetControlFocus	Sets or removes the keyboard focus to or from the control.
CComControlBase::SetDirty	Sets the data member `m_bRequiresSave` to the value in bDirty.

Public Data Members

Name	Description
CComControlBase::m_bAutoSize	Flag indicating the control cannot be any other size.
CComControlBase::m_bDrawFromNatural	Flag indicating that `IDataObjectImpl::GetData` and `CComControlBase::GetZoomInfo` should set the control size from `m_sizeNatural` rather than from `m_sizeExtent`.
CComControlBase::m_bDrawGetDataInHimetric	Flag indicating that `IDataObjectImpl::GetData` should use HIMETRIC units and not pixels when drawing.
CComControlBase::m_bInPlaceActive	Flag indicating the control is in-place active.
CComControlBase::m_bInPlaceSiteEx	Flag indicating the container supports the `IOleInPlaceSiteEx` interface and OCX96 control features, such as windowless and flicker-free controls.
CComControlBase::m_bNegotiatedWnd	Flag indicating whether or not the control has negotiated with the container about support for OCX96 control features (such as flicker-free and windowless controls), and whether the control is windowed or windowless.
CComControlBase::m_bRecomposeOnResize	Flag indicating the control wants to recompose its presentation when the container changes the control's display size.
CComControlBase::m_bRequiresSave	Flag indicating the control has changed since it was last saved.
CComControlBase::m_bResizeNatural	Flag indicating the control wants to resize its natural extent (its unscaled physical size) when the container changes the control's display size.
CComControlBase::m_bUIActive	Flag indicating the control's user interface, such as menus and toolbars, is active.
CComControlBase::m_bUsingWindowRgn	Flag indicating the control is using the container-supplied window region.
CComControlBase::m_bWasOnceWindowless	Flag indicating the control has been windowless, but may or may not be windowless now.
CComControlBase::m_bWindowOnly	Flag indicating the control should be windowed, even if the container supports windowless controls.
CComControlBase::m_bWndLess	Flag indicating the control is windowless.
CComControlBase::m_hWndCD	Contains a reference to the window handle associated with the control.
CComControlBase::m_nFreezeEvents	A count of the number of times the container has frozen events (refused to accept events) without an intervening thaw of events (acceptance of events).
CComControlBase::m_rcPos	The position in pixels of the control, expressed in the coordinates of the container.
CComControlBase::m_sizeExtent	The extent of the control in HIMETRIC units (each unit is 0.01 millimeters) for a particular display.
CComControlBase::m_sizeNatural	The physical size of the control in HIMETRIC units (each unit is 0.01 millimeters).
CComControlBase::m_spAdviseSink	A direct pointer to the advisory connection on the container (the container's IAdviseSink).
CComControlBase::m_spAmbientDispatch	A `CComDispatchDriver` object that lets you retrieve and set the container's properties through an `IDispatch` pointer.
CComControlBase::m_spClientSite	A pointer to the control's client site within the container.
CComControlBase::m_spDataAdviseHolder	Provides a standard means to hold advisory connections between data objects and advise sinks.
CComControlBase::m_spInPlaceSite	A pointer to the container's IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer.
CComControlBase::m_spOleAdviseHolder	Provides a standard implementation of a way to hold advisory connections.

Remarks

This class provides methods for creating and managing ATL controls. CComControl Class derives from CComControlBase. When you create a Standard Control or DHTML control using the ATL Control Wizard, the wizard will automatically derive your class from CComControlBase.

For more information about creating a control, see the ATL Tutorial. For more information about the ATL Project Wizard, see the article Creating an ATL Project.

Requirements

Header: atlctl.h

CComControlBase::AppearanceType

Override if your m_nAppearance stock property isn't of type short.

typedef short AppearanceType;

Remarks

The ATL Control Wizard adds m_nAppearance stock property of type short. Override AppearanceType if you use a different data type.

CComControlBase::CComControlBase

The constructor.

CComControlBase(HWND& h);

Parameters

h
The handle to the window associated with the control.

Remarks

Initializes the control size to 5080X5080 HIMETRIC units (2"X2") and initializes the CComControlBase data member values to NULL or FALSE.

CComControlBase::~CComControlBase

The destructor.

~CComControlBase();

Remarks

If the control is windowed, ~CComControlBase destroys it by calling DestroyWindow.

CComControlBase::ControlQueryInterface

Retrieves a pointer to the requested interface.

virtual HRESULT ControlQueryInterface(const IID& iid,
    void** ppv);

Parameters

iid
The GUID of the interface being requested.

ppv
A pointer to the interface pointer identified by iid, or NULL if the interface is not found.

Remarks

Only handles interfaces in the COM map table.

Example

// Retrieve the control's IOleObject interface. Note interface 
// is automatically released when pOleObject goes out of scope

CComPtr<IOleObject> pOleObject;
ControlQueryInterface(IID_IOleObject, (void**)&pOleObject);

CComControlBase::DoesVerbActivate

Checks that the iVerb parameter used by IOleObjectImpl::DoVerb either activates the control's user interface (iVerb equals OLEIVERB_UIACTIVATE), defines the action taken when the user double-clicks the control (iVerb equals OLEIVERB_PRIMARY), displays the control (iVerb equals OLEIVERB_SHOW), or activates the control (iVerb equals OLEIVERB_INPLACEACTIVATE).

BOOL DoesVerbActivate(LONG iVerb);

Parameters

iVerb
Value indicating the action to be performed by DoVerb.

Return Value

Returns TRUE if iVerb equals OLEIVERB_UIACTIVATE, OLEIVERB_PRIMARY, OLEIVERB_SHOW, or OLEIVERB_INPLACEACTIVATE; otherwise, returns FALSE.

Remarks

You can override this method to define your own activation verb.

CComControlBase::DoesVerbUIActivate

Checks that the iVerb parameter used by IOleObjectImpl::DoVerb causes the control's user interface to activate and returns TRUE.

BOOL DoesVerbUIActivate(LONG iVerb);

Parameters

iVerb
Value indicating the action to be performed by DoVerb.

Return Value

Returns TRUE if iVerb equals OLEIVERB_UIACTIVATE, OLEIVERB_PRIMARY, OLEIVERB_SHOW, or OLEIVERB_INPLACEACTIVATE. Otherwise, the method returns FALSE.

CComControlBase::DoVerbProperties

Displays the control's property pages.

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

Parameters

prcPosRec
Reserved.

hwndParent
Handle of the window containing the control.

Return Value

One of the standard HRESULT values.

Example

// The following implementation of the WM_RBUTTONDOWN message handler
// will pop up the ActiveX Control's PropertyPages 
LRESULT CMyComposite::OnRButtonDown(UINT /*uMsg*/, WPARAM /*wParam*/, 
   LPARAM /*lParam*/, BOOL& /*bHandled*/)
{
   DoVerbProperties(NULL, ::GetActiveWindow());
   return 0L;
}

MESSAGE_HANDLER(WM_RBUTTONDOWN, OnRButtonDown)

CComControlBase::FireViewChange

Call this method to tell the container to redraw the control, or notify the registered advise sinks that the control's view has changed.

HRESULT FireViewChange();

Return Value

One of the standard HRESULT values.

Remarks

If the control is active (the control class data member CComControlBase::m_bInPlaceActive is TRUE), notifies the container that you want to redraw the entire control. If the control is inactive, notifies the control's registered advise sinks (through the control class data member CComControlBase::m_spAdviseSink) that the control's view has changed.

Example

STDMETHODIMP CMyControl::put_Shape(int newVal)
{
   // store newVal in m_nShape user-defined member
   m_nShape = newVal;

   // notify container to redraw control
   FireViewChange();
   return S_OK;
}

CComControlBase::GetAmbientAppearance

Retrieves DISPID_AMBIENT_APPEARANCE, the current appearance setting for the control: 0 for flat and 1 for 3D.

HRESULT GetAmbientAppearance(short& nAppearance);

Parameters

nAppearance
The property DISPID_AMBIENT_APPEARANCE.

Return Value

One of the standard HRESULT values.

Example

HRESULT OnDraw(ATL_DRAWINFO& di)
{
   short nAppearance;
   RECT& rc = *(RECT*)di.prcBounds;

   // draw 3D border if AmbientAppearance is not supported or is set to 1 
   HRESULT hr = GetAmbientAppearance(nAppearance);
   if (hr != S_OK || nAppearance==1)
   {
      DrawEdge(di.hdcDraw, &rc, EDGE_SUNKEN, BF_RECT);
   }
   else
   {
      Rectangle(di.hdcDraw, rc.left, rc.top, rc.right, rc.bottom);
   }

   SetTextAlign(di.hdcDraw, TA_CENTER|TA_BASELINE);
   LPCTSTR pszText = _T("ATL 8.0 : MyControl");

   // For security reasons, we recommend that you use the lstrlen function
   // with caution. Here, we can guarantee that pszText is NULL terminated,
   // and therefore it is safe to use this function.
   TextOut(di.hdcDraw, 
      (rc.left + rc.right) / 2, 
      (rc.top + rc.bottom) / 2, 
      pszText, 
      lstrlen(pszText));

   return S_OK;
}

CComControlBase::GetAmbientAutoClip

Retrieves DISPID_AMBIENT_AUTOCLIP, a flag indicating whether the container supports automatic clipping of the control display area.

HRESULT GetAmbientAutoClip(BOOL& bAutoClip);

Parameters

bAutoClip
The property DISPID_AMBIENT_AUTOCLIP.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientBackColor

Retrieves DISPID_AMBIENT_BACKCOLOR, the ambient background color for all controls, defined by the container.

HRESULT GetAmbientBackColor(OLE_COLOR& BackColor);

Parameters

BackColor
The property DISPID_AMBIENT_BACKCOLOR.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientCharSet

Retrieves DISPID_AMBIENT_CHARSET, the ambient character set for all controls, defined by the container.

HRESULT GetAmbientCharSet(BSTR& bstrCharSet);

Parameters

bstrCharSet
The property DISPID_AMBIENT_CHARSET.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

CComControlBase::GetAmbientCodePage

Retrieves DISPID_AMBIENT_CODEPAGE, the ambient code page for all controls, defined by the container.

HRESULT GetAmbientCodePage(ULONG& ulCodePage);

Parameters

ulCodePage
The property DISPID_AMBIENT_CODEPAGE.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

CComControlBase::GetAmbientDisplayAsDefault

Retrieves DISPID_AMBIENT_DISPLAYASDEFAULT, a flag that is TRUE if the container has marked the control in this site to be a default button, and therefore a button control should draw itself with a thicker frame.

HRESULT GetAmbientDisplayAsDefault(BOOL& bDisplayAsDefault);

Parameters

bDisplayAsDefault
The property DISPID_AMBIENT_DISPLAYASDEFAULT.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientDisplayName

Retrieves DISPID_AMBIENT_DISPLAYNAME, the name the container has supplied to the control.

HRESULT GetAmbientDisplayName(BSTR& bstrDisplayName);

Parameters

bstrDisplayName
The property DISPID_AMBIENT_DISPLAYNAME.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientFont

Retrieves a pointer to the container's ambient IFont interface.

HRESULT GetAmbientFont(IFont** ppFont);

Parameters

ppFont
A pointer to the container's ambient IFont interface.

Return Value

One of the standard HRESULT values.

Remarks

If the property is NULL, the pointer is NULL. If the pointer is not NULL, the caller must release the pointer.

CComControlBase::GetAmbientFontDisp

Retrieves a pointer to the container's ambient IFontDisp dispatch interface.

HRESULT GetAmbientFontDisp(IFontDisp** ppFont);

Parameters

CComControlBase::GetAmbientMessageReflect

Retrieves DISPID_AMBIENT_MESSAGEREFLECT, a flag indicating whether the container wants to receive window messages (such as WM_DRAWITEM) as events.

HRESULT GetAmbientMessageReflect(BOOL& bMessageReflect);

Parameters

bMessageReflect
The property DISPID_AMBIENT_MESSAGEREFLECT.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientPalette

Retrieves DISPID_AMBIENT_PALETTE, used to access the container's HPALETTE.

HRESULT GetAmbientPalette(HPALETTE& hPalette);

Parameters

hPalette
The property DISPID_AMBIENT_PALETTE.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientProperty

Retrieves the container property specified by dispid.

HRESULT GetAmbientProperty(DISPID dispid, VARIANT& var);

Remarks

If TRUE, the control should not respond. This flag applies regardless of the DISPID_AMBIENT_USERMODE flag. See CComControlBase::GetAmbientUserMode.

CComControlBase::GetAmbientUserMode

Retrieves DISPID_AMBIENT_USERMODE, a flag indicating whether the container is in run-mode (TRUE) or design-mode (FALSE).

HRESULT GetAmbientUserMode(BOOL& bUserMode);

Parameters

bUserMode
The property DISPID_AMBIENT_USERMODE.

Return Value

One of the standard HRESULT values.

CComControlBase::GetDirty

Returns the value of data member m_bRequiresSave.

BOOL GetDirty();

Return Value

Returns the value of data member m_bRequiresSave.

Remarks

This value is set using CComControlBase::SetDirty.

CComControlBase::GetZoomInfo

Retrieves the x and y values of the numerator and denominator of the zoom factor for a control activated for in-place editing.

void GetZoomInfo(ATL_DRAWINFO& di);

Parameters

di
The structure that will hold the zoom factor's numerator and denominator. For more information, see ATL_DRAWINFO.

Remarks

The zoom factor is the proportion of the control's natural size to its current extent.

CComControlBase::InPlaceActivate

Causes the control to transition from the inactive state to whatever state the verb in iVerb indicates.

HRESULT InPlaceActivate(LONG iVerb, const RECT* prcPosRect = NULL);

Parameters

iVerb
Value indicating the action to be performed by IOleObjectImpl::DoVerb.

prcPosRect
Pointer to the position of the in-place control.

Return Value

One of the standard HRESULT values.

Remarks

Before activation, this method checks that the control has a client site, checks how much of the control is visible, and gets the control's location in the parent window. After the control is activated, this method activates the control's user interface and tells the container to make the control visible.

This method also retrieves an IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer for the control and stores it in the control class's data member CComControlBase::m_spInPlaceSite. The control class data members CComControlBase::m_bInPlaceSiteEx, CComControlBase::m_bWndLess, CComControlBase::m_bWasOnceWindowless, and CComControlBase::m_bNegotiatedWnd are set to true as appropriate.

CComControlBase::InternalGetSite

Call this method to query the control site for a pointer to the identified interface.

HRESULT InternalGetSite(REFIID riid, void** ppUnkSite);

Parameters

riid
The IID of the interface pointer that should be returned in ppUnkSite.

ppUnkSite
Address of the pointer variable that receives the interface pointer requested in riid.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

If the site supports the interface requested in riid, the pointer is returned by means of ppUnkSite. Otherwise, ppUnkSite is set to NULL.

CComControlBase::m_bAutoSize

Flag indicating the control cannot be any other size.

unsigned m_bAutoSize:1;

Remarks

This flag is checked by IOleObjectImpl::SetExtent and, if TRUE, causes the function to return E_FAIL.

Note

To use this data member within your control class, you must declare it as a data member in your control class. Your control class will not inherit this data member from the base class because it is declared within a union in the base class.

If you add the Auto Size option on the Stock Properties tab of the ATL Control Wizard, the wizard automatically creates this data member in your control class, creates put and get methods for the property, and supports IPropertyNotifySink to automatically notify the container when the property changes.

CComControlBase::m_bDrawFromNatural

Flag indicating that IDataObjectImpl::GetData and CComControlBase::GetZoomInfo should set the control size from m_sizeNatural rather than from m_sizeExtent.

unsigned m_bDrawFromNatural:1;

Remarks

Note

CComControlBase::m_bDrawGetDataInHimetric

Flag indicating that IDataObjectImpl::GetData should use HIMETRIC units and not pixels when drawing.

unsigned m_bDrawGetDataInHimetric:1;

Remarks

Each logical HIMETRIC unit is 0.01 millimeter.

Note

CComControlBase::m_bInPlaceActive

Flag indicating the control is in-place active.

unsigned m_bInPlaceActive:1;

Remarks

This means the control is visible and its window, if any, is visible, but its menus and toolbars may not be active. The m_bUIActive flag indicates the control's user interface, such as menus, is also active.

Note

CComControlBase::m_bInPlaceSiteEx

Flag indicating the container supports the IOleInPlaceSiteEx interface and OCX96 control features, such as windowless and flicker-free controls.

unsigned m_bInPlaceSiteEx:1;

Remarks

Note

The data member m_spInPlaceSite points to an IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface, depending on the value of the m_bWndLess and m_bInPlaceSiteEx flags. (The data member m_bNegotiatedWnd must be TRUE for the m_spInPlaceSite pointer to be valid.)

If m_bWndLess is FALSE and m_bInPlaceSiteEx is TRUE, m_spInPlaceSite is an IOleInPlaceSiteEx interface pointer. See m_spInPlaceSite for a table showing the relationship among these three data members.

CComControlBase::m_bNegotiatedWnd

Flag indicating whether or not the control has negotiated with the container about support for OCX96 control features (such as flicker-free and windowless controls), and whether the control is windowed or windowless.

unsigned m_bNegotiatedWnd:1;

Remarks

Note

The m_bNegotiatedWnd flag must be TRUE for the m_spInPlaceSite pointer to be valid.

CComControlBase::m_bRecomposeOnResize

Flag indicating the control wants to recompose its presentation when the container changes the control's display size.

unsigned m_bRecomposeOnResize:1;

Remarks

Note

This flag is checked by IOleObjectImpl::SetExtent and, if TRUE, SetExtent notifies the container of view changes. if this flag is set, the OLEMISC_RECOMPOSEONRESIZE bit in the OLEMISC enumeration should also be set.

CComControlBase::m_bRequiresSave

Flag indicating the control has changed since it was last saved.

unsigned m_bRequiresSave:1;

Remarks

The value of m_bRequiresSave can be set with CComControlBase::SetDirty and retrieved with CComControlBase::GetDirty.

Note

CComControlBase::m_bResizeNatural

Flag indicating the control wants to resize its natural extent (its unscaled physical size) when the container changes the control's display size.

unsigned m_bResizeNatural:1;

Remarks

This flag is checked by IOleObjectImpl::SetExtent and, if TRUE, the size passed into SetExtent is assigned to m_sizeNatural.

The size passed into SetExtent is always assigned to m_sizeExtent, regardless of the value of m_bResizeNatural.

Note

CComControlBase::m_bUIActive

Flag indicating the control's user interface, such as menus and toolbars, is active.

unsigned m_bUIActive:1;

Remarks

The m_bInPlaceActive flag indicates that the control is active, but not that its user interface is active.

Note

CComControlBase::m_bUsingWindowRgn

Flag indicating the control is using the container-supplied window region.

unsigned m_bUsingWindowRgn:1;

Remarks

Note

CComControlBase::m_bWasOnceWindowless

Flag indicating the control has been windowless, but may or may not be windowless now.

unsigned m_bWasOnceWindowless:1;

Remarks

Note

CComControlBase::m_bWindowOnly

Flag indicating the control should be windowed, even if the container supports windowless controls.

unsigned m_bWindowOnly:1;

Remarks

Note

CComControlBase::m_bWndLess

Flag indicating the control is windowless.

unsigned m_bWndLess:1;

Remarks

Note

The data member m_spInPlaceSite points to an IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface, depending on the value of the m_bWndLess and CComControlBase::m_bInPlaceSiteEx flags. (The data member CComControlBase::m_bNegotiatedWnd must be TRUE for the CComControlBase::m_spInPlaceSite pointer to be valid.)

If m_bWndLess is TRUE, m_spInPlaceSite is an IOleInPlaceSiteWindowless interface pointer. See CComControlBase::m_spInPlaceSite for a table showing the complete relationship between these data members.

CComControlBase::m_hWndCD

Contains a reference to the window handle associated with the control.

HWND& m_hWndCD;

Remarks

Note

CComControlBase::m_nFreezeEvents

A count of the number of times the container has frozen events (refused to accept events) without an intervening thaw of events (acceptance of events).

short m_nFreezeEvents;

Remarks

Note

CComControlBase::m_rcPos

The position in pixels of the control, expressed in the coordinates of the container.

RECT m_rcPos;

Remarks

Note

CComControlBase::m_sizeExtent

The extent of the control in HIMETRIC units (each unit is 0.01 millimeters) for a particular display.

SIZE m_sizeExtent;

Remarks

Note

This size is scaled by the display. The control's physical size is specified in the m_sizeNatural data member and is fixed.

You can convert the size to pixels with the global function AtlHiMetricToPixel.

CComControlBase::m_sizeNatural

The physical size of the control in HIMETRIC units (each unit is 0.01 millimeters).

SIZE m_sizeNatural;

Remarks

Note

This size is fixed, while the size in m_sizeExtent is scaled by the display.

You can convert the size to pixels with the global function AtlHiMetricToPixel.

CComControlBase::m_spAdviseSink

A direct pointer to the advisory connection on the container (the container's IAdviseSink).

CComPtr<IAdviseSink>
    m_spAdviseSink;

Remarks

Note

CComControlBase::m_spAmbientDispatch

A CComDispatchDriver object that lets you retrieve and set an object's properties through an IDispatch pointer.

CComDispatchDriver m_spAmbientDispatch;

Remarks

Note

CComControlBase::m_spClientSite

A pointer to the control's client site within the container.

CComPtr<IOleClientSite>
    m_spClientSite;

Remarks

Note

CComControlBase::m_spDataAdviseHolder

Provides a standard means to hold advisory connections between data objects and advise sinks.

CComPtr<IDataAdviseHolder>
    m_spDataAdviseHolder;

Remarks

Note

A data object is a control that can transfer data and that implements IDataObject, whose methods specify the format and transfer medium of the data.

The interface m_spDataAdviseHolder implements the IDataObject::DAdvise and IDataObject::DUnadvise methods to establish and delete advisory connections to the container. The control's container must implement an advise sink by supporting the IAdviseSink interface.

CComControlBase::m_spInPlaceSite

A pointer to the container's IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer.

CComPtr<IOleInPlaceSiteWindowless>
    m_spInPlaceSite;

Remarks

Note

The m_spInPlaceSite pointer is valid only if the m_bNegotiatedWnd flag is TRUE.

The following table shows how the m_spInPlaceSite pointer type depends on the m_bWndLess and m_bInPlaceSiteEx data member flags:

m_spInPlaceSite Type	m_bWndLess Value	m_bInPlaceSiteEx Value
`IOleInPlaceSiteWindowless`	TRUE	TRUE or FALSE
`IOleInPlaceSiteEx`	FALSE	TRUE
`IOleInPlaceSite`	FALSE	FALSE

CComControlBase::m_spOleAdviseHolder

Provides a standard implementation of a way to hold advisory connections.

CComPtr<IOleAdviseHolder>
    m_spOleAdviseHolder;

Remarks

Note

The interface m_spOleAdviseHolder implements the IOleObject::Advise and IOleObject::Unadvise methods to establish and delete advisory connections to the container. The control's container must implement an advise sink by supporting the IAdviseSink interface.

CComControlBase::OnDraw

Override this method to draw your control.

virtual HRESULT OnDraw(ATL_DRAWINFO& di);

Parameters

di
A reference to the ATL_DRAWINFO structure that contains drawing information such as the draw aspect, the control bounds, and whether the drawing is optimized or not.

Return Value

A standard HRESULT value.

Remarks

The default OnDraw deletes or restores the device context or does nothing, depending on flags set in CComControlBase::OnDrawAdvanced.

An OnDraw method is automatically added to your control class when you create your control with the ATL Control Wizard. The wizard's default OnDraw draws a rectangle with the label "ATL 8.0".

Example

See the example for CComControlBase::GetAmbientAppearance.

CComControlBase::OnDrawAdvanced

The default OnDrawAdvanced prepares a normalized device context for drawing, then calls your control class's OnDraw method.

virtual HRESULT OnDrawAdvanced(ATL_DRAWINFO& di);

Parameters

di
A reference to the ATL_DRAWINFO structure that contains drawing information such as the draw aspect, the control bounds, and whether the drawing is optimized or not.

Return Value

A standard HRESULT value.

Remarks

Override this method if you want to accept the device context passed by the container without normalizing it.

See CComControlBase::OnDraw for more details.

CComControlBase::OnKillFocus

Checks that the control is in-place active and has a valid control site, then informs the container that the control has lost focus.

LRESULT OnKillFocus(UINT /* nMsg */,
    WPARAM /* wParam */,
    LPARAM /* lParam */,
    BOOL& bHandled);

Parameters

nMsg
Reserved.

wParam
Reserved.

lParam
Reserved.

bHandled
Flag that indicates whether the window message was successfully handled. The default is FALSE.

Return Value

Always returns 1.

CComControlBase::OnMouseActivate

Checks that the UI is in user mode, then activates the control.

LRESULT OnMouseActivate(UINT /* nMsg */,
    WPARAM /* wParam */,
    LPARAM /* lParam */,
    BOOL& bHandled);

Parameters

nMsg
Reserved.

wParam
Reserved.

lParam
Reserved.

bHandled
Flag that indicates whether the window message was successfully handled. The default is FALSE.

Return Value

Always returns 1.

CComControlBase::OnPaint

Prepares the container for painting, gets the control's client area, then calls the control class's OnDrawAdvanced method.

LRESULT OnPaint(UINT /* nMsg */,
    WPARAM wParam,
    LPARAM /* lParam */,
    BOOL& /* lResult */);

Parameters

nMsg
Reserved.

wParam
An existing HDC.

lParam
Reserved.

lResult
Reserved.

Return Value

Always returns zero.

Remarks

If wParam is not NULL, OnPaint assumes it contains a valid HDC and uses it instead of CComControlBase::m_hWndCD.

CComControlBase::OnSetFocus

Checks that the control is in-place active and has a valid control site, then informs the container the control has gained focus.

LRESULT OnSetFocus(UINT /* nMsg */,
    WPARAM /* wParam */,
    LPARAM /* lParam */,
    BOOL& bHandled);

Parameters

nMsg
Reserved.

wParam
Reserved.

lParam
Reserved.

bHandled
Flag that indicates whether the window message was successfully handled. The default is FALSE.

Return Value

Always returns 1.

Remarks

Sends a notification to the container that the control has received focus.

CComControlBase::PreTranslateAccelerator

Override this method to provide your own keyboard accelerator handlers.

BOOL PreTranslateAccelerator(LPMSG /* pMsg */,
    HRESULT& /* hRet */);

Parameters

pMsg
Reserved.

hRet
Reserved.

Return Value

By default returns FALSE.

CComControlBase::SendOnClose

Notifies all advisory sinks registered with the advise holder that the control has been closed.

HRESULT SendOnClose();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Sends a notification that the control has closed its advisory sinks.

CComControlBase::SendOnDataChange

Notifies all advisory sinks registered with the advise holder that the control data has changed.

HRESULT SendOnDataChange(DWORD advf = 0);

Parameters

advf
Advise flags that specify how the call to IAdviseSink::OnDataChange is made. Values are from the ADVF enumeration.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

CComControlBase::SendOnRename

Notifies all advisory sinks registered with the advise holder that the control has a new moniker.

HRESULT SendOnRename(IMoniker* pmk);

Parameters

pmk
Pointer to the new moniker of the control.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Sends a notification that the moniker for the control has changed.

CComControlBase::SendOnSave

Notifies all advisory sinks registered with the advise holder that the control has been saved.

HRESULT SendOnSave();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Sends a notification that the control has just saved its data.

CComControlBase::SendOnViewChange

Notifies all registered advisory sinks that the control's view has changed.

HRESULT SendOnViewChange(DWORD dwAspect, LONG lindex = -1);

Parameters

dwAspect
The aspect or view of the control.

lindex
The portion of the view that has changed. Only -1 is valid.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

SendOnViewChange calls IAdviseSink::OnViewChange. The only value of lindex currently supported is -1, which indicates that the entire view is of interest.

CComControlBase::SetControlFocus

Sets or removes the keyboard focus to or from the control.

BOOL SetControlFocus(BOOL bGrab);

Parameters

bGrab
If TRUE, sets the keyboard focus to the calling control. If FALSE, removes the keyboard focus from the calling control, provided it has the focus.

Return Value

Returns TRUE if the control successfully receives focus; otherwise, FALSE.

Remarks

For a windowed control, the Windows API function SetFocus is called. For a windowless control, IOleInPlaceSiteWindowless::SetFocus is called. Through this call, a windowless control obtains the keyboard focus and can respond to window messages.

CComControlBase::SetDirty

Sets the data member m_bRequiresSave to the value in bDirty.

void SetDirty(BOOL bDirty);

Parameters

bDirty
Value of the data member CComControlBase::m_bRequiresSave.

Remarks

SetDirty(TRUE) should be called to flag that the control has changed since it was last saved. The value of m_bRequiresSave is retrieved with CComControlBase::GetDirty.