Share via


CComControlBase Class

 

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

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

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.

CComControlBase::GetAmbientForeColor

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.

CComControlBase::GetAmbientLocaleID

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.

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

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.

CComControlBase::GetAmbientRightToLeft

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.

CComControlBase::GetAmbientScaleUnits

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.

CComControlBase::GetAmbientShowGrabHandles

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.

CComControlBase::GetAmbientShowHatching

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.

CComControlBase::GetAmbientSupportsMnemonics

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.

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.

HRESULT GetAmbientTextAlign(short& nTextAlign);

Parameters

nTextAlign
The property DISPID_AMBIENT_TEXTALIGN.

Return Value

One of the standard HRESULT values.

CComControlBase::GetAmbientTopToBottom

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.

CComControlBase::GetAmbientUIDead

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

CComControlBase::m_bUsingWindowRgn

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

unsigned m_bUsingWindowRgn:1;

Remarks

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.

CComControlBase::m_bWasOnceWindowless

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

unsigned m_bWasOnceWindowless:1;

Remarks

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.

CComControlBase::m_bWindowOnly

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

unsigned m_bWindowOnly:1;

Remarks

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.

CComControlBase::m_bWndLess

Flag indicating the control is windowless.

unsigned m_bWndLess:1;

Remarks

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.

CComControlBase::m_hWndCD

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

HWND& m_hWndCD;

Remarks

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.

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

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.

CComControlBase::m_rcPos

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

RECT m_rcPos;

Remarks

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.

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

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.

CComControlBase::m_sizeNatural

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

SIZE m_sizeNatural;

Remarks

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.

CComControlBase::m_spAdviseSink

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

CComPtr<IAdviseSink>
    m_spAdviseSink;

Remarks

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.

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

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.

CComControlBase::m_spClientSite

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

CComPtr<IOleClientSite>
    m_spClientSite;

Remarks

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.

CComControlBase::m_spDataAdviseHolder

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

CComPtr<IDataAdviseHolder>
    m_spDataAdviseHolder;

Remarks

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.

CComControlBase::m_spInPlaceSite

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

CComPtr<IOleInPlaceSiteWindowless>
    m_spInPlaceSite;

Remarks

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

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.

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.

See Also

CComControl Class
Class Overview