CComControlBase Class

 

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

This class provides methods for creating and managing ATL controls.

System_CAPS_ICON_important.jpg Important

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

class ATL_NO_VTABLE CComControlBase

Public Typedefs

NameDescription
CComControlBase::AppearanceTypeOverride if your m_nAppearance stock property isn't of type short.

Public Constructors

NameDescription
CComControlBase::CComControlBaseThe constructor.
CComControlBase::~CComControlBaseThe destructor.

Public Methods

NameDescription
CComControlBase::ControlQueryInterfaceRetrieves a pointer to the requested interface.
CComControlBase::DoesVerbActivateChecks 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::DoesVerbUIActivateChecks that the iVerb parameter used by IOleObjectImpl::DoVerb causes the control's user interface to activate and returns TRUE.
CComControlBase::DoVerbPropertiesDisplays the control's property pages.
CComControlBase::FireViewChangeCall this method to tell the container to redraw the control, or notify the registered advise sinks that the control's view has changed.
CComControlBase::GetAmbientAppearanceRetrieves DISPID_AMBIENT_APPEARANCE, the current appearance setting for the control: 0 for flat and 1 for 3D.
CComControlBase::GetAmbientAutoClipRetrieves DISPID_AMBIENT_AUTOCLIP, a flag indicating whether the container supports automatic clipping of the control display area.
CComControlBase::GetAmbientBackColorRetrieves DISPID_AMBIENT_BACKCOLOR, the ambient background color for all controls, defined by the container.
CComControlBase::GetAmbientCharSetRetrieves DISPID_AMBIENT_CHARSET, the ambient character set for all controls, defined by the container.
CComControlBase::GetAmbientCodePageRetrieves DISPID_AMBIENT_CODEPAGE, the ambient character set for all controls, defined by the container.
CComControlBase::GetAmbientDisplayAsDefaultRetrieves 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::GetAmbientDisplayNameRetrieves DISPID_AMBIENT_DISPLAYNAME, the name the container has supplied to the control.
CComControlBase::GetAmbientFontRetrieves a pointer to the container's ambient IFont interface.
CComControlBase::GetAmbientFontDispRetrieves a pointer to the container's ambient IFontDisp dispatch interface.
CComControlBase::GetAmbientForeColorRetrieves DISPID_AMBIENT_FORECOLOR, the ambient foreground color for all controls, defined by the container.
CComControlBase::GetAmbientLocaleIDRetrieves DISPID_AMBIENT_LOCALEID, the identifier of the language used by the container.
CComControlBase::GetAmbientMessageReflectRetrieves DISPID_AMBIENT_MESSAGEREFLECT, a flag indicating whether the container wants to receive window messages (such as WM_DRAWITEM) as events.
CComControlBase::GetAmbientPaletteRetrieves DISPID_AMBIENT_PALETTE, used to access the container's HPALETTE.
CComControlBase::GetAmbientPropertyRetrieves the container property specified by id.
CComControlBase::GetAmbientRightToLeftRetrieves DISPID_AMBIENT_RIGHTTOLEFT, the direction in which content is displayed by the container.
CComControlBase::GetAmbientScaleUnitsRetrieves DISPID_AMBIENT_SCALEUNITS, the container's ambient units (such as inches or centimeters) for labeling displays.
CComControlBase::GetAmbientShowGrabHandlesRetrieves DISPID_AMBIENT_SHOWGRABHANDLES, a flag indicating whether the container allows the control to display grab handles for itself when active.
CComControlBase::GetAmbientShowHatchingRetrieves 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::GetAmbientSupportsMnemonicsRetrieves DISPID_AMBIENT_SUPPORTSMNEMONICS, a flag indicating whether the container supports keyboard mnemonics.
CComControlBase::GetAmbientTextAlignRetrieves 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::GetAmbientTopToBottomRetrieves DISPID_AMBIENT_TOPTOBOTTOM, the direction in which content is displayed by the container.
CComControlBase::GetAmbientUIDeadRetrieves DISPID_AMBIENT_UIDEAD, a flag indicating whether the container wants the control to respond to user-interface actions.
CComControlBase::GetAmbientUserModeRetrieves DISPID_AMBIENT_USERMODE, a flag indicating whether the container is in run-mode ( TRUE) or design-mode ( FALSE).
CComControlBase::GetDirtyReturns the value of data member m_bRequiresSave.
CComControlBase::GetZoomInfoRetrieves the x and y values of the numerator and denominator of the zoom factor for a control activated for in-place editing.
CComControlBase::InPlaceActivateCauses the control to transition from the inactive state to whatever state the verb in iVerb indicates.
CComControlBase::InternalGetSiteCall this method to query the control site for a pointer to the identified interface.
CComControlBase::OnDrawOverride this method to draw your control.
CComControlBase::OnDrawAdvancedThe default OnDrawAdvanced prepares a normalized device context for drawing, then calls your control class's OnDraw method.
CComControlBase::OnKillFocusChecks that the control is in-place active and has a valid control site, then informs the container that the control has lost focus.
CComControlBase::OnMouseActivateChecks that the UI is in user mode, then activates the control.
CComControlBase::OnPaintPrepares the container for painting, gets the control's client area, then calls the control class's OnDraw method.
CComControlBase::OnSetFocusChecks that the control is in-place active and has a valid control site, then informs the container the control has gained focus.
CComControlBase::PreTranslateAcceleratorOverride this method to provide your own keyboard accelerator handlers.
CComControlBase::SendOnCloseNotifies all advisory sinks registered with the advise holder that the control has been closed.
CComControlBase::SendOnDataChangeNotifies all advisory sinks registered with the advise holder that the control data has changed.
CComControlBase::SendOnRenameNotifies all advisory sinks registered with the advise holder that the control has a new moniker.
CComControlBase::SendOnSaveNotifies all advisory sinks registered with the advise holder that the control has been saved.
CComControlBase::SendOnViewChangeNotifies all registered advisory sinks that the control's view has changed.
CComControlBase::SetControlFocusSets or removes the keyboard focus to or from the control.
CComControlBase::SetDirtySets the data member m_bRequiresSave to the value in bDirty.

Public Data Members

NameDescription
CComControlBase::m_bAutoSizeFlag indicating the control cannot be any other size.
CComControlBase::m_bDrawFromNaturalFlag indicating that IDataObjectImpl::GetData and CComControlBase::GetZoomInfo should set the control size from m_sizeNatural rather than from m_sizeExtent.
CComControlBase::m_bDrawGetDataInHimetricFlag indicating that IDataObjectImpl::GetData should use HIMETRIC units and not pixels when drawing.
CComControlBase::m_bInPlaceActiveFlag indicating the control is in-place active.
CComControlBase::m_bInPlaceSiteExFlag indicating the container supports the IOleInPlaceSiteEx interface and OCX96 control features, such as windowless and flicker-free controls.
CComControlBase::m_bNegotiatedWndFlag 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_bRecomposeOnResizeFlag indicating the control wants to recompose its presentation when the container changes the control's display size.
CComControlBase::m_bRequiresSaveFlag indicating the control has changed since it was last saved.
CComControlBase::m_bResizeNaturalFlag indicating the control wants to resize its natural extent (its unscaled physical size) when the container changes the control's display size.
CComControlBase::m_bUIActiveFlag indicating the control's user interface, such as menus and toolbars, is active.
CComControlBase::m_bUsingWindowRgnFlag indicating the control is using the container-supplied window region.
CComControlBase::m_bWasOnceWindowlessFlag indicating the control has been windowless, but may or may not be windowless now.
CComControlBase::m_bWindowOnlyFlag indicating the control should be windowed, even if the container supports windowless controls.
CComControlBase::m_bWndLessFlag indicating the control is windowless.
CComControlBase::m_hWndCDContains a reference to the window handle associated with the control.
CComControlBase::m_nFreezeEventsA 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_rcPosThe position in pixels of the control, expressed in the coordinates of the container.
CComControlBase::m_sizeExtentThe extent of the control in HIMETRIC units (each unit is 0.01 millimeters) for a particular display.
CComControlBase::m_sizeNaturalThe physical size of the control in HIMETRIC units (each unit is 0.01 millimeters).
CComControlBase::m_spAdviseSinkA direct pointer to the advisory connection on the container (the container's IAdviseSink).
CComControlBase::m_spAmbientDispatchA CComDispatchDriver object that lets you retrieve and set the container's properties through an IDispatch pointer.
CComControlBase::m_spClientSiteA pointer to the control's client site within the container.
CComControlBase::m_spDataAdviseHolderProvides a standard means to hold advisory connections between data objects and advise sinks.
CComControlBase::m_spInPlaceSiteA pointer to the container's IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer.
CComControlBase::m_spOleAdviseHolderProvides a standard implementation of a way to hold advisory connections.

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.

Header: atlctl.h

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.

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.

The destructor.

~CComControlBase();

Remarks

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

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);

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.

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.

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)

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;
}

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;
   }

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.

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.

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.

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.

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.

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.

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.

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

HRESULT GetAmbientFontDisp(IFontDisp** ppFont);

Parameters

ppFont
A pointer to the container's ambient IFontDisp dispatch interface.

Return Value

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

Remarks

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

Retrieves DISPID_AMBIENT_FORECOLOR, the ambient foreground color for all controls, defined by the container.

HRESULT GetAmbientForeColor(OLE_COLOR& ForeColor);

Parameters

ForeColor
The property DISPID_AMBIENT_FORECOLOR.

Return Value

One of the standard HRESULT values.

Retrieves DISPID_AMBIENT_LOCALEID, the identifier of the language used by the container.

HRESULT GetAmbientLocaleID(LCID& lcid);

Parameters

lcid
The property DISPID_AMBIENT_LOCALEID.

Return Value

One of the standard HRESULT values.

Remarks

The control can use this identifier to adapt its user interface to different languages.

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.

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.

Retrieves the container property specified by dispid.

HRESULT GetAmbientProperty(DISPID dispid, VARIANT& var);

Parameters

dispid
Identifier of the container property to be retrieved.

var
Variable to receive the property.

Return Value

One of the standard HRESULT values.

Remarks

ATL has provided a set of helper functions to retrieve specific properties, for example, CComControlBase::GetAmbientBackColor. If there is no suitable method available, use GetAmbientProperty.

Retrieves DISPID_AMBIENT_RIGHTTOLEFT, the direction in which content is displayed by the container.

HRESULT GetAmbientRightToLeft(BOOL& bRightToLeft);

Parameters

bRightToLeft
The property DISPID_AMBIENT_RIGHTTOLEFT. Set to TRUE if content is displayed right to left, FALSE if it is displayed left to right.

Return Value

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

Retrieves DISPID_AMBIENT_SCALEUNITS, the container's ambient units (such as inches or centimeters) for labeling displays.

HRESULT GetAmbientScaleUnits(BSTR& bstrScaleUnits);

Parameters

bstrScaleUnits
The property DISPID_AMBIENT_SCALEUNITS.

Return Value

One of the standard HRESULT values.

Retrieves DISPID_AMBIENT_SHOWGRABHANDLES, a flag indicating whether the container allows the control to display grab handles for itself when active.

HRESULT GetAmbientShowGrabHandles(BOOL& bShowGrabHandles);

Parameters

bShowGrabHandles
The property DISPID_AMBIENT_SHOWGRABHANDLES.

Return Value

One of the standard HRESULT values.

Retrieves DISPID_AMBIENT_SHOWHATCHING, a flag indicating whether the container allows the control to display itself with a hatched pattern when the control's user interface is active.

HRESULT GetAmbientShowHatching(BOOL& bShowHatching);

Parameters

bShowHatching
The property DISPID_AMBIENT_SHOWHATCHING.

Return Value

One of the standard HRESULT values.

Retrieves DISPID_AMBIENT_SUPPORTSMNEMONICS, a flag indicating whether the container supports keyboard mnemonics.

HRESULT GetAmbientSupportsMnemonics(BOOL& bSupportsMnemonics);

Parameters

bSupportsMnemonics
The property DISPID_AMBIENT_SUPPORTSMNEMONICS.

Return Value

One of the standard HRESULT values.

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.

HRESULT GetAmbientTextAlign(short& nTextAlign);

Parameters

nTextAlign
The property DISPID_AMBIENT_TEXTALIGN.

Return Value

One of the standard HRESULT values.

Retrieves DISPID_AMBIENT_TOPTOBOTTOM, the direction in which content is displayed by the container.

HRESULT GetAmbientTopToBottom(BOOL& bTopToBottom);

Parameters

bTopToBottom
The property DISPID_AMBIENT_TOPTOBOTTOM. Set to TRUE if text is displayed top to bottom, FALSE if it is displayed bottom to top.

Return Value

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

Retrieves DISPID_AMBIENT_UIDEAD, a flag indicating whether the container wants the control to respond to user-interface actions.

HRESULT GetAmbientUIDead(BOOL& bUIDead);

Parameters

bUIDead
The property DISPID_AMBIENT_UIDEAD.

Return Value

One of the standard HRESULT values.

Remarks

If TRUE, the control should not respond. This flag applies regardless of the DISPID_AMBIENT_USERMODE flag. See 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.

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.

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.

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.

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.

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.

System_CAPS_ICON_note.jpg 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.

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

System_CAPS_ICON_note.jpg 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.

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.

System_CAPS_ICON_note.jpg 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.

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.

System_CAPS_ICON_note.jpg 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.

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

unsigned m_bInPlaceSiteEx:1;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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

System_CAPS_ICON_note.jpg 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.

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

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

unsigned m_bRecomposeOnResize:1;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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.

System_CAPS_ICON_note.jpg 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.

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.

System_CAPS_ICON_note.jpg 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.

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.

System_CAPS_ICON_note.jpg 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.

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

unsigned m_bUsingWindowRgn:1;

Remarks

System_CAPS_ICON_note.jpg 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.

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

unsigned m_bWasOnceWindowless:1;

Remarks

System_CAPS_ICON_note.jpg 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.

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

unsigned m_bWindowOnly:1;

Remarks

System_CAPS_ICON_note.jpg 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.

Flag indicating the control is windowless.

unsigned m_bWndLess:1;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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

HWND& m_hWndCD;

Remarks

System_CAPS_ICON_note.jpg 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.

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

System_CAPS_ICON_note.jpg 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.

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

RECT m_rcPos;

Remarks

System_CAPS_ICON_note.jpg 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.

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

SIZE m_sizeExtent;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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

SIZE m_sizeNatural;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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

CComPtr<IAdviseSink>
    m_spAdviseSink;

Remarks

System_CAPS_ICON_note.jpg 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.

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

CComDispatchDriver m_spAmbientDispatch;

Remarks

System_CAPS_ICON_note.jpg 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.

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

CComPtr<IOleClientSite>
    m_spClientSite;

Remarks

System_CAPS_ICON_note.jpg 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.

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

CComPtr<IDataAdviseHolder>
    m_spDataAdviseHolder;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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

CComPtr<IOleInPlaceSiteWindowless>
    m_spInPlaceSite;

Remarks

System_CAPS_ICON_note.jpg 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.

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 Typem_bWndLess Valuem_bInPlaceSiteEx Value
IOleInPlaceSiteWindowlessTRUETRUE or FALSE
IOleInPlaceSiteExFALSETRUE
IOleInPlaceSiteFALSEFALSE

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

CComPtr<IOleAdviseHolder>
    m_spOleAdviseHolder;

Remarks

System_CAPS_ICON_note.jpg 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

CComControl Class
Class Overview

Show: