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.