template < class T >
class CComControl : public CComControlBase, CWindowImpl< T >
Parameters
T The class implementing the control.
CComControl is a set of useful control helper functions and essential data members for ATL controls. When you create a full control or an Internet Explorer control using the ATL Object Wizard, the wizard will automatically derive your class from CComControl.
For more information about creating controls, see the ATL Tutorial. For more information about the ATL Object Wizard, see the article Creating an ATL Project.
For a demonstration of CComControl methods and data members, see the CIRC sample.
#include <atlctl.h>
See Also CWindowImpl
Methods
CComControlBase Methods
GetAmbient Property Methods
Data Members
Stock Property Data Members
Methods | |
CComControl | Constructor. |
ControlQueryInterface | Retrieves a pointer to the requested interface. |
CreateControlWindow | Creates a window for the control. |
FireOnChanged | Notifies the container's sink that a control property has changed. |
FireOnRequestEdit | Notifies the container's sink that a control property is about to change. |
CComControlBase Methods | |
CComControlBase | Initializes the control data and sets a default control size. |
DoesVerbActivate | Checks that the iVerb parameter used by IOleObjectImpl::DoVerb activates the control. |
DoesVerbUIActivate | Checks that the iVerb parameter used by IOleObjectImpl::DoVerb causes the control's user interface to activate. |
DoVerbProperties | Tells the control to display its property sheet. |
FireViewChange | Tells the control to discard any undo the state it is maintaining. |
GetDirty | Retrieves the value of the flag indicating whether the control's properties have changed since it was last saved. |
GetZoomInfo | Retrieves information about the zoom factor and stores it in the ATL_DRTAWINFO structure. |
InPlaceActivate | Determines that the control can be in-place activated, informs the container the control is going in-place active, and activates the control. |
OnDraw | Draws the control. |
OnDrawAdvanced | Normalizes the device context, then calls the control class's OnDraw method. |
OnGetDlgCode | Called in response to a WM_GETDLGCODE mesage. Override to have the control process TAB keys and arrow keys. |
OnKillFocus | Informs the container the control has lost focus. |
OnPaint | Prepares the container for painting, gets information about the control size, and calls your control class's OnDraw method. |
OnSetFocus | Informs the container the control has gained focus. |
SendOnClose | Called by the server to notify the control's advise sinks the control has changed from the running to the loaded state. |
SendOnDataChange | Called by the server to notify the control's advise sinks that data in the control has changed. |
SendOnRename | Called by the server to notify the control's advise sinks the control has been renamed. |
SendOnSave | Called by the server to notify the control's advise sinks the control has been saved. |
SendOnViewChange | Notifies the control's advise sinks its view has changed. |
SetControlFocus | Sets or removes keyboard focus to or from the control. |
SetDirty | Sets the value of the flag indicating that the control's properties have changed since it was last saved. |
GetAmbient Property Methods | |
GetAmbientAppearance | Gets the container's APPEARANCE property. |
GetAmbientAutoClip | Gets the container's AUTOCLIP property. |
GetAmbientBackColor | Gets the container's BACKCOLOR property. |
GetAmbientDisplayAsDefault | Gets the container's DISPLAYASDEFAULT property. |
GetAmbientDisplayName | Gets the container's DISPLAYNAME property. |
GetAmbientFont | Gets the container's FONT properties. |
GetAmbientForeColor | Gets the container's FORECOLOR property. |
GetAmbientLocaleID | Gets the container's LOCALEID property. |
GetAmbientMessageReflect | Gets the container's MESSAGEREFLECT property. |
GetAmbientPalette | Gets the container's PALETTE property. |
GetAmbientProperty | Retrieves the specified container property. |
GetAmbientScaleUnits | Gets the container's SCALEUNITS property. |
GetAmbientShowGrabHandles | Gets the container's SHOWGRABHANDLES property. |
GetAmbientShowHatching | Gets the container's SHOWHATCHING property. |
GetAmbientSupportsMnemonics | Gets the container's SUPPORTSMNEMONICS property. |
GetAmbientTextAlign | Gets the container's TEXTALIGN property. |
GetAmbientUIDead | Gets the container's UIDEAD property. |
GetAmbientUserMode | Gets the container's USERMODE property. |
Data Members | |
m_bAutoSize | Flag indicating the control cannot be any other size, and SetExtent should fail. |
m_bDrawFromNatural | Flag indicating GetData should use the control's actual size and not its current extent when drawing. |
m_bDrawGetDataInHimetric | Flag indicating that GetData should use HIMETRIC units and not pixels when drawing. |
m_bEnabled | Flag indicating the control is enabled. |
m_bInPlaceActive | Flag indicating the control is in-place active. |
m_bInPlaceSiteEx | Flag indicating the container supports OCX96 control features, such as windowless and flicker-free controls. |
m_bNegotiatedWnd | Flag indicating whether or not the control has negotiated with the container about being windowless or windowed. |
m_bRecomposeOnResize | Flag indicating the control wants to recompose its presentation when the container changes the control's display size. |
m_bRequiresSave | Flag indicating the control has changed since it was last saved. |
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. |
m_bUIActive | Flag indicating the control's user interface is active. |
m_bUsingWindowRgn | Flag indicating the control is using the container-supplied window region. |
m_bWasOnceWindowless | Flag indicating the control has been windowless, but may or may not be windowless now. |
m_bWindowOnly | Flag indicating the control should be windowed even if the container supports windowless controls. |
m_bWndless | Flag indicating the control is windowless. |
m_hWndCD | A reference to the window handle associated with the control. |
m_nFreezeEvents | A count of the number of times the container has refused to accept events (a freeze of events) without an intervening acceptance of events (a thaw of events). |
m_phWndCD | A pointer to the window handle associated with the control. |
m_rcPos | The RECT position of the control. |
m_sizeExtent | The SIZE of the control in on a particular display in HIMETRIC units (each logical unit is 0.01 millimeter). This size is scaled by the display. |
m_sizeNatural | The fixed physical SIZE of the control in HIMETRIC units (each logical unit is 0.01 millimeter). This size is not scaled by the display. |
m_spAdviseSink | A COM interface pointer of type IAdviseSink. |
m_spAmbientDispatch | A CComDispatchDriver obhject used to set and get properties through IDispatch. |
m_spClientSite | A COM interface pointer of type IOleClientSite. |
m_spDataAdviseHolder | A COM interface pointer of type IDataAdviseHolder. |
m_spInPlaceSite | A pointer to the container's IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless COM interface. |
m_spOleAdviseHolder | A COM interface pointer of type IOleAdviseHolder. |
Stock Property Data Members | |
m_bAutoSize | Stores the AUTOSIZE stock property. |
m_bBorderVisible | Stores the BORDERVISIBLE stock property. |
m_bEnabled | Stores the ENABLED stock property. |
m_bstrCaption | Stores the CAPTION stockproperty. |
m_bstrText | Stores the TEXT stock property. |
m_bTabStop | Stores the TABSTOP stock property. |
m_bValid | Stores the VALID stock property. |
m_clrBackColor | Stores the BACKCOLOR stock property. |
m_clrBorderColor | Stores the BORDERCOLOR stock property. |
m_clrFillColor | Stores the FILLCOLOR stock property. |
m_clrForeColor | Stores the FORECOLOR stock property. |
m_nAppearance | Stores the APPEARANCE stock property. |
m_nBackStyle | Stores the BACKSTYLEstock property. |
m_nBorderStyle | Stores the BORDERSTYLE stock property. |
m_nBorderWidth | Stores the BORDERWIDTH stock property. |
m_nDrawMode | Stores the DRAWMODE stock property. |
m_nDrawStyle | Stores the DRAWSTYLE stock property. |
m_nDrawWidth | Stores the DRAWWIDTH stock property. |
m_nFillStyle | Stores the FILLSTYLE stock property. |
m_nMousePointer | Stores the MOUSEPOINTER stock property. |
m_nReadyState | Stores the READYSTATE stock property. |
m_pFont | Stores the FONT stock property. |
m_pMouseIcon | Stores the MOUSEICON stock property. |
m_pPicture | Stores the PICTURE stock property. |
CComControl( );
Remarks
The constructor. Calls the CComControlBase constructor, passing the m_hWnd data member inherited through CWindowImpl.
CComControl Overview | Class Members
See Also CComControl::CComControlBase, CWindow::m_hWnd
CComControlBase( HWND h );
Parameters
h [in] The handle to the window associated with the control.
Remarks
The constructor. Stores a pointer to the window handle in the data member m_phWndCD. Initializes the control size to 5080X5080 HIMETRIC units (2"X2") and initializes the CComControlBase data member values to NULL or FALSE.
CComControl Overview | Class Members
See Also CComControl::m_sizeExtent, CComControl::m_phWndCD
virtual HRESULT ControlQueryInterface( const IID& iid, void** ppv );
Parameters
iid [in] The GUID of the interface being requested.
ppv [out] A pointer to the interface pointer identified by iid, or NULL if the interface is not found.
Remarks
Retrieves a pointer to the requested interface. Only handles interfaces in the COM map table.
CComControl Overview | Class Members
See Also CComObjectRootEx::InternalQueryInterface
virtual HWND CreateControlWindow( HWND hWndParent, RECT& rcPos );
Parameters
hWndParent [in] Handle to the parent or owner window. A valid window handle must be supplied. The control window is confined to the area of its parent window.
rcPos [in] The initial size and position of the window to be created.
Remarks
By default, creates a window for the control by calling CWindowImpl::Create. Override this method if you want to do something other than create a single window, for example, to create two windows, one of which becomes a toolbar for your control.
CComControl Overview | Class Members
See Also CWindowImpl::Create
BOOL DoesVerbActivate( LONG iVerb );
Return Value
Returns TRUE if iVerb equals OLEIVERB_UIACTIVATE, OLEIVERB_PRIMARY, OLEIVERB_SHOW, or OLEIVERB_INPLACEACTIVE; otherwise, returns FALSE.
Parameters
iVerb [in] Value indicating the action to be performed by DoVerb.
Remarks
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_PRIMARY). You can override this method to define your own activation verb.
CComControl Overview | Class Members
See Also IOleObjectImpl::DoVerb, CComControl::DoesUIVerbActivate
BOOL DoesVerbUIActivate( LONG iVerb );
Return Value
Returns TRUE if iVerb equals OLEIVERB_UIACTIVATE or OLEIVERB_PRIMARY. Also returns TRUE if the control is not active and iVerb equals OLEIVERB_UIACTIVATE, OLEIVERB_PRIMARY, OLEIVERB_SHOW, or OLEIVERB_INPLACEACTIVE. Otherwise, the method returns FALSE.
Parameters
iVerb [in] Value indicating the action to be performed by DoVerb.
Remarks
Checks that the iVerb parameter used by IOleObjectImpl::DoVerb causes the control's user interface to activate and returns TRUE.
DoesVerbUIActivate also checks whether the control is in-place active. If it is not, and the value of iVerb causes the control to go active, then DoesVerbUIActivate returns TRUE. This handles older containers that must activate the control and its user interface together.
CComControl Overview | Class Members
See Also IOleObjectImpl::DoVerb, CComControl::DoesVerbActivate
HRESULT DoVerbProperties( LPCRECT prcPosRect, HWND hwndParent );
Return Value
One of the standard HRESULT values.
Parameters
prcPosRec [in] Pointer to the rectangle the container wants the control to draw into.
hwndParent [in] Handle of the window containing the control. Not used in the ATL implementation.
Remarks
Displays the control's property pages. By default, this is set as the action taken when the user double-clicks the control. You can change this to another action by overriding IOleObjectImpl::DoVerbPrimary.
CComControl Overview | Class Members
See Also IOleObjectImpl::DoVerbPrimary
HRESULT FireOnChanged( DISPID dispID );
Return Value
One of the standard HRESULT values.
Parameters
dispID [in] Identifier of the property that has changed.
Remarks
If your control class derives from IPropertyNotifySink this method calls CFirePropNotifyEvent::FireOnChanged to notify all connected IPropertyNotifySink interfaces that the specified control property has changed. If your control class does not derive from IPropertyNotifySink, this method returns S_OK.
This function is safe to call even if your control doesn't support connection points.
CComControl Overview | Class Members
See Also CComControl::FireOnRequestEdit
HRESULT FireOnRequestEdit( DISPID dispID );
Return Value
One of the standard HRESULT values.
Parameters
dispID [in] Identifier of the property about to change.
Remarks
If your control class derives from IPropertyNotifySink, this method calls CFirePropNotifyEvent::FireOnRequestEdit to notify all connected IPropertyNotifySink interfaces that the specified control property is about to change. If your control class does not derive from IPropertyNotifySink, this method returns S_OK.
This function is safe to call even if your control doesn't support connection points.
CComControl Overview | Class Members
See Also CComControl::FireOnChanged
HRESULT FireViewChange( );
Return Value
One of the standard HRESULT values.
Remarks
If the control is active (the control class data member 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 m_spAdviseSink) that the control's view has changed.
CComControl Overview | Class Members
HRESULT GetAmbientAppearance( short& nAppearance );
Return Value
One of the standard HRESULT values.
Parameters
nAppearance [out] The property DISPID_AMBIENT_APPEARANCE.
Remarks
Retrieves DISPID_AMBIENT_APPEARANCE, the current appearance setting for the control: 0 for flat and 1 for 3D.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientAutoClip( BOOL& bAutoClip );
Return Value
One of the standard HRESULT values.
Parameters
bAutoClip [out] The property DISPID_AMBIENT_AUTOCLIP.
Remarks
Retrieves DISPID_AMBIENT_AUTOCLIP, a flag indicating whether the container supports automatic clipping of the control display area.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientBackColor( OLE_COLOR& BackColor );
Return Value
One of the standard HRESULT values.
Parameters
BackColor [out] The property DISPID_AMBIENT_BACKCOLOR.
Remarks
Retrieves DISPID_AMBIENT_BACKCOLOR, the ambient background color for all controls, defined by the container.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientDisplayAsDefault( BOOL& bDisplayAsDefault );
Return Value
One of the standard HRESULT values.
Parameters
bDisplayAsDefault [out] The property DISPID_AMBIENT_DISPLAYASDEFAULT.
Remarks
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.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientDisplayName( BSTR& bstrDisplayName );
Return Value
One of the standard HRESULT values.
Parameters
bstrDisplayName [out] The property DISPID_AMBIENT_DISPLAYNAME.
Remarks
Retrieves DISPID_AMBIENT_DISPLAYNAME, the name the container has supplied to the control.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientFont( IFont** ppFont );
Return Value
One of the standard HRESULT values.
Parameters
ppFont [out] The property DISPID_AMBIENT_FONT.
Remarks
Retrieves DISPID_AMBIENT_FONT, a pointer to the container's ambient IFont dispatch interface. If the property is NULL, the pointer is NULL. If the pointer is not NULL, the caller must release the pointer.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientForeColor( OLE_COLOR& ForeColor );
Return Value
One of the standard HRESULT values.
Parameters
ForeColor [out] The property DISPID_AMBIENT_FORECOLOR.
Remarks
Retrieves DISPID_AMBIENT_FORECOLOR, the ambient foreground color for all controls, defined by the container.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientLocaleID( LCID& lcid );
Return Value
One of the standard HRESULT values.
Parameters
lcid [out] The property DISPID_AMBIENT_LOCALEID.
Remarks
Retrieves DISPID_AMBIENT_LOCALEID, the identifier of the language used by the container. The control can use this identifier to adapt its user interface to different languages.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientMessageReflect( BOOL& bMessageReflect );
Return Value
One of the standard HRESULT values.
Parameters
bMessageReflect [out] The property DISPID_AMBIENT_MESSAGEREFLECT.
Remarks
Retrieves DISPID_AMBIENT_MESSAGEREFLECT, a flag indicating wether the container wants to receive window messages (such as WM_DRAWITEM) as events.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientPalette( HPALETTE& hPalette );
Return Value
One of the standard HRESULT values.
Parameters
hPalette [out] The property DISPID_AMBIENT_PALETTE.
Remarks
Retrieves DISPID_AMBIENT_PALETTE, used to access the container's HPALETTE.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientProeprty( DISPID dispid, VARIANT& var );
Return Value
One of the standard HRESULT values.
Parameters
dispid [in] Identifier of the container property to be retrieved.
var [in] Variable to receive the property.
Remarks
Retrieves the container property specified by id.
ATL has provided a set of helper functions to retrieve specific properties, for example, GetAmbientBackColor. These functions take no parameters and return the property type.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientScaleUnits( BSTR& bstrScaleUnits );
Return Value
One of the standard HRESULT values.
Parameters
bstrScaleUnits [out] The property DISPID_AMBIENT_SCALEUNITS.
Remarks
Retrieves DISPID_AMBIENT_SCALEUNITS, the container's ambient units (such as inches or centimeters) for labeling displays.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientShowGrabHandles( BOOL& bShowGrabHandles );
Return Value
One of the standard HRESULT values.
Parameters
bShowGrabHandles [out] The property DISPID_AMBIENT_SHOWGRABHANDLES.
Remarks
Retrieves DISPID_AMBIENT_SHOWGRABHANDLES, a flag indicating whether the container allows the control to display grab handles for itself when active.
CComControl Overview | Class Members
See Also GetAmbientProperty Methods
HRESULT GetAmbientShowHatching( BOOL& bShowHatching );
Return Value
One of the standard HRESULT values.
Parameters
bShowHatching [out] The property DISPID_AMBIENT_SHOWHATCHING.
Remarks
Retrieves DISPID_AMBIENT_SHOWHATCHING, a flag indicating whether the container allows the control to display itself with a hatched pattern when UI active.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientSupportsMnemonics( BOOL& bSupportsMnemonics );
Return Value
One of the standard HRESULT values.
Parameters
bSupportsMnemonics [out] The property DISPID_AMBIENT_SUPPORTSMNEMONICS.
Remarks
Retrieves DISPID_AMBIENT_SUPPORTSMNEMONICS, a flag indicating whether the container supports keyboard mnemonics.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientTextAlign( short& nTextAlign );
Return Value
One of the standard HRESULT values.
Parameters
nTextAlign [out] The property DISPID_AMBIENT_TEXTALIGN.
Remarks
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.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientUIDead( BOOL& bUIDead );
Return Value
One of the standard HRESULT values.
Parameters
bUIDead [out] The property DISPID_AMBIENT_UIDEAD.
Remarks
Retrieves DISPID_AMBIENT_UIDEAD, a flag indicating whether the container wants the control to respond to user-interface actions. If TRUE, the control should not respond. This flag applies regardless of the DISPID_AMBIENT_USERMODE flag.
CComControl Overview | Class Members
See Also GetAmbient Property Methods
HRESULT GetAmbientUserMode( BOOL& bUserMode );
Return Value
One of the standard HRESULT values.
Parameters
bUserMode [out] The property DISPID_AMBIENT_USERMODE.
Remarks
Retrieves DISPID_AMBIENT_USERMODE, a flag indicating whether the container is in run-mode (TRUE) or design-mode (FALSE).
CComControl Overview | Class Members
See Also GetAmbient Property Methods
BOOL GetDirty( );
Return Value
Returns the value of data member m_bRequiresSave.
Remarks
Returns the value of data member m_bRequiresSave. This value is set in SetDirty.
CComControl Overview | Class Members
See Also CComControl::SetDirty
void GetZoomInfo( ATL_DRAWINFO& di );
Parameters
di [out] The structure that will hold the zoom factor's numerator and denominator.
Remarks
Retrieves the x and y values of the numerator and denominator of the zoom factor for a control activated for in-place editing. The zoom factor is the proportion of the control's natural size to its current extent.
CComControl Overview | Class Members
See Also CComControl::m_sizeNatural, CComControl::m_sizeExtent
HRESULT InPlaceActivate( LONG iVerb, const RECT* prcPosRect = NULL );
Return Value
One of the standard HRESULT values.
Parameters
iVerb [in] Value indicating the action to be performed by DoVerb.
prcPosRect [in] Pointer to the position of the in-place control.
Remarks
Causes the control to transition form the inactive state to whatever state the verb in iVerb indicates. 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 function also retrieves an IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer for the control and stores it in the control class's data member m_spInPlaceSite. The control class data members m_bInPlaceSiteEx, m_bWndless, m_bWasOnceWindowless, and m_bNegotiatedWnd are set to TRUE as appropriate.
CComControl Overview | Class Members
See Also IOleInPlaceObjectWindowlessImpl::InPlaceDeactivate
virtual HRESULT OnDraw( ATL_DRAWINFO& di );
Return Value
A standard HRESULT value.
Parameters
di [in] 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.
Remarks
Override this method to draw your control.
The default OnDraw deletes or restores the device context or does nothing, depending on flags set in OnDrawAdvanced.
An OnDraw method is automatically added to your control class when you create your control with the ATL Object Wizard. The wizard's default OnDraw draws a rectangle with the label "ATL 2.0".
CComControl Overview | Class Members
See Also CComControl::OnDrawAdvanced, IViewObjectExImpl::Draw
virtual HRESULT OnDrawAdvanced( ATL_DRAWINFO& di );
Return Value
A standard HRESULT value.
Parameters
di [in] 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.
Remarks
The default OnDrawAdvanced prepares a normalized device context for drawing, then calls your control class's OnDraw method to draw the control. Override this method if you want to accept the device context passed by the container without normalizing it.
A default OnDraw method is automatically added to your control class when you create your control with the ATL Object Wizard. The wizard's default OnDraw draws a rectangle with the label "ATL 2.0".
CComControl Overview | Class Members
See Also CComControl::OnDraw
LRESULT OnGetDlgCode( UINT nMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled );
Return Value
The result of message processing. 0 if successful.
Parameters
nMsg [in] The window message identifier. Not used in the default ATL implementation
wParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
lParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
bHandled [in, out] Flag that indicates whether the window message was successfully handled. The default is TRUE.
Remarks
Called in response to a WM_GETDLGCODE window message. The message is sent to the dialog box associated with the control. Override this method to let the control process the input of arrow keys and TAB keys. The default ATL implementation simply returns 0.
CComControl Overview | Class Members
See Also WM_GETDLGCODE in the Win32 SDK
LRESULT OnKillFocus( UINT nMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled );
Return Value
Always returns 0.
Parameters
nMsg [in] The window message identifier. Not used in the default ATL implementation
wParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
lParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
bHandled [in, out] Flag that indicates whether the window message was successfully handled. The default is TRUE.
Remarks
Checks that the control is in-place active and has a valid control site, then informs the container the control has lost focus.
CComControl Overview | Class Members
See Also CComControl::m_bInPlaceActive, CComControl::m_spClientSite
LRESULT OnPaint( UINT nMsg, WPARAM wParam, LPARAM lParam, BOOL& lResult );
Return Value
Returns zero.
Parameters
nMsg [in] Specifies the message. Not used in the default ATL implementation.
wParam [in] Additional message information. Depends on the value of nMsg. Not used in the default ATL implementation.
lParam [in] Additional message information. Depends on the value of nMsg. Not used in the default ATL implementation.
lResult [in, out] A boolean value. Not used in the default ATL implementation. See MESSAGE_HANDLER for more information.
Remarks
Prepares the container for painting, gets the control's client area, then calls the control class's OnDraw method.
A default OnDraw method is automatically added to your control class when you create your control with the ATL Object Wizard. The wizard's default OnDraw draws a rectangle with the label "ATL 2.0".
CComControl Overview | Class Members
See Also CComControl::OnDraw
LRESULT OnSetFocus( UINT nMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled );
Return Value
Always returns 0.
Parameters
nMsg [in] The window message identifier. Not used in the default ATL implementation
wParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
lParam [in] A 32-bit message parameter. Not used in the default ATL implementation.
bHandled [in, out] Flag that indicates whether the window message was successfully handled. The default is TRUE.
Remarks
Checks that the control is in-place active and has a valid control site, then informs the container the control has gained focus.
CComControl Overview | Class Members
See Also CComControl::m_bInPlaceActive, CComControl::m_spClientSite
HRESULT SendOnClose( );
Return Value
One of the standard HRESULT values.
Remarks
Notifies all advisory sinks registered with the advise holder that the control has been closed.
CComControl Overview | Class Members
See Also CComControl::m_spOleAdviseHolder
HRESULT SendOnDataChange( DWORD advf = 0);
Return Value
One of the standard HRESULT values.
Parameters
advf [in] Advise flags that specify how the call to IAdviseSink::OnDataChange is made. Values are from the ADVF enumeration.
Remarks
Notifies all advisory sinks registered with the advise holder that the control data has changed.
CComControl Overview | Class Members
See Also CComControl::m_spDataAdviseHolder
HRESULT SendOnRename( IMoniker* pmk );
Return Value
One of the standard HRESULT values.
Parameters
pmk [in] Pointer to the new moniker of the control.
Remarks
Notifies all advisory sinks registered with the advise holder that the control has a new moniker.
CComControl Overview | Class Members
See Also CComControl::m_spOleAdviseHolder
HRESULT SendOnSave( );
Return Value
One of the standard HRESULT values.
Remarks
Notifies all advisory sinks registered with the advise holder that the control has been saved.
CComControl Overview | Class Members
See Also CComControl::m_spOleAdviseHolder
HRESULT SendOnViewChange( DWORD dwAspect, LONG lindex = -1 );
Return Value
One of the standard HRESULT values.
Parameters
dwAspect [in] The aspect or view of the control.
lindex [in] The portion of the view that has changed. Only -1 is valid.
Remarks
Notifies all registered advisory sinks that the control's view has changed.
CComControl Overview | Class Members
See Also CComControl::m_spAdviseSink
BOOL SetControlFocus( BOOL bGrab );
Return Value
Returns TRUE if the control successfully receives focus; otherwise, FALSE.
Parameters
bGrab [in] 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.
Remarks
Sets or removes the keyboard focus to or from the control. 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.
CComControl Overview | Class Members
void SetDirty( BOOL bDirty );
Parameters
bDirty [in] Value of the data member m_bRequiresSave.
Remarks
Sets the data member m_bRequiresSave to the value in bDirty. You should call SetDirty(TRUE) to flag that the control has changed since it was last saved. The value of m_bRequiresSave is retreived with GetDirty.
CComControl Overview | Class Members
unsigned m_bAutoSize:1;
Remarks
Flag indicating the control cannot be any other size. This flag is checked by IOleObjectImpl::SetExtent and, if TRUE, causes the function to return E_FAIL.
If you choose the AUTOSIZE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also IOleObjectImpl::SetExtent
BOOL m_bBorderVisible;
Remarks
The data member in your control class that flags whether the control's border should be visible or not. If you choose the BORDERVISIBLE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nBorderStyle, CComControl::m_clrBorderColor, CComControl::m_nBorderWidth
unsigned m_bDrawFromNatural:1;
Remarks
Flag indicating that IDataObjectImpl::GetData should retrieve the control size from m_sizeNatural rather than from m_sizeExtent.
CComControl Overview | Class Members
See Also IDataObjectImpl::GetData, CComControl::m_sizeNatural, CComControl::m_sizeExtent
unsigned m_bDrawGetDataInHimetric:1;
Remarks
Flag indicating that IDataObjectImpl::GetData should use HIMETRIC units and not pixels when drawing. Each logical HIMETRIC unit is 0.01 millimeter.
CComControl Overview | Class Members
See Also IDataObjectImpl::GetData
unsigned m_bEnabled:1;
Remarks
Flag indicating the control is enabled. The m_bInPlaceActive flag indicates that the control is in-place active, while the m_bUIActive flag indicates the control's user interface (menus and toolbars) is also active.
If you choose the ENABLED option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_bInPlaceActive, CComControl::m_bUIActive
unsigned m_bInPlaceActive:1;
Remarks
Flag indicating the control is in-place active. 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 that the control's user interface, such as menus, is also active.
CComControl Overview | Class Members
See Also CComControl::m_bEnabled, CComControl::m_bUIActive
unsigned m_bInPlaceSiteEx:1;
Remarks
Flag indicating the container supports the IOleInPlaceSiteEx interface and OCX96 control features, such as windowless and flicker-free controls.
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. See m_spInPlaceSite for a table showing the relationship among these three data members.
CComControl Overview | Class Members
See Also CComControl::m_spInPlaceSite, CComControl::m_bWndless, CComControl::m_bNegotiatedWnd
unsigned m_bNegotiatedWnd:1;
Remarks
Flag indicating whether or not the control has negotiated with the container about support for OCX96 features (such as flicker-free and windowless controls) and whether the control is windowed or windowless. The m_bNegotiatedWnd flag must be TRUE for the m_spInPlaceSite pointer to be valid.
CComControl Overview | Class Members
See Also CComControl::m_bWndless, CComControl::m_spInPlaceSite
unsigned m_bRecomposeOnResize:1;
Remarks
Flag indicating the control wants to recompose its presentation when the container changes the control's display size. 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.
CComControl Overview | Class Members
See Also IOleObjectImpl::SetExtent
unsigned m_bRequiresSave:1;
Remarks
Flag indicating the control has changed since it was last saved. The value of m_bRequiresSave can be set with SetDirty and retrieved with GetDirty.
CComControl Overview | Class Members
See Also CComControl::SetDirty, CComControl::GetDirty
unsigned m_bResizeNatural:1;
Remarks
Flag indicating the control wants to resize its natural extent (its unscaled physical size) when the container changes the control's display size. 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.
CComControl Overview | Class Members
See Also IOleObjectImpl::SetExtent, CComControl::m_sizeNatural, CComControl::m_sizeExtent
BSTR m_bstrCaption;
Remarks
The data member in your control class that holds text to be displayed with the control. If you choose the CAPTION option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_bstrText
BSTR m_bstrCaption;
Remarks
The data member in your control class that holds text to be displayed with the control. If you choose the TEXT option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_bstrCaption
BOOL m_bTabStop;
Remarks
The data member in your control class that flags whether the control is a tab stop or not. If you choose the TABSTOP option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
unsigned m_bUIActive:1;
Remarks
Flag indicating the control's user interface, such as menus and toolbars, is active. The m_bInPlaceActive flag indicates that the control is active, but not that its user interface is active.
CComControl Overview | Class Members
See Also CComControl::m_bEnabled, CComControl::m_bInPlaceActive
unsigned m_bUsingWindowRgn:1;
Remarks
Flag indicating the control is using the container-supplied window region.
CComControl Overview | Class Members
BOOL m_bValid;
Remarks
The data member in your control class that flags whether the control is a valid or not. If you choose the VALID option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
unsigned m_bWasOnceWindowless:1;
Remarks
Flag indicating the control has been windowless, but may or may not be windowless now.
CComControl Overview | Class Members
See Also CComControl::m_bWndless
unsigned m_bWindowOnly:1;
Remarks
Flag indicating the control should be windowed, even if the container supports windowless controls.
CComControl Overview | Class Members
See Also CComControl::m_bWndless
unsigned m_bWndless:1;
Remarks
Flag indicating the control is windowless.
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 TRUE, m_spInPlaceSite is an IOleInPlaceSiteWindowless interface. See m_spInPlaceSite for a table showing the relationship among these three data members.
CComControl Overview | Class Members
See Also CComControl::m_spInPlaceSite, CComControl::m_bInPlaceSiteEx, CComControl::m_bNegotiatedWnd, CComControl::m_bWasOnceWindowless, CComControl::m_bWindowOnly
OLE_COLOR m_clrBackColor;
Remarks
The data member in your control class that holds the control's background color. If you choose the BACKCOLOR option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_clrBorderColor, CComControl::m_clrFillColor, CComControl::m_clrForeColor
OLE_COLOR m_clrBorderColor;
Remarks
The data member in your control class that holds the control's border color. If you choose the BORDERCOLOR option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_clrBackColor, CComControl::m_clrFillColor, CComControl::m_clrForeColor
OLE_COLOR m_clrFillColor;
Remarks
The data member in your control class that holds the control's fill color. If you choose the FILLCOLOR option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_clrBackColor, CComControl::m_clrBorderColor, CComControl::m_clrForeColor
OLE_COLOR m_clrForeColor;
Remarks
The data member in your control class that holds the control's foreground color. If you choose the FORECOLOR option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_clrBackColor, CComControl::m_clrBorderColor, CComControl::m_clrFillColor
HWND& m_hWndCD;
Remarks
Contains a reference to the window handle associated with the control. Part of a union with m_phWndCD.
CComControl Overview | Class Members
See Also CComControl::CComControl, CComControl::m_phWndCD
long m_nAppearance;
Remarks
The data member in your control class that stores the paint style used by the control, for example, flat or 3D. If you choose the APPEARANCE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nDrawMode
long m_nBackStyle;
Remarks
The data member in your control class that stores the control's background style, either transparent or opaque. If you choose the BACKSTYLE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nFillStyle
long m_nBorderStyle;
Remarks
The data member in your control class that stores the control's border style. If you choose the BORDERSTYLE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_bBorderVisible, CComControl::m_clrBorderColor, CComControl::m_nBorderWidth
long m_nBorderWidth;
Remarks
The data member in your control class that stores the control's border width. If you choose the BORDERWIDTH option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_bBorderVisible, CComControl::m_clrBorderColor, CComControl::m_nBorderStyle
long m_nDrawMode;
Remarks
The data member in your control class that stores the appearance of output from the control's graphics methods, for example, XOR Pen or Invert Colors. If you choose the DRAWMODE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nDrawWidth, CComControl::m_nDrawStyle
long m_nDrawStyle;
Remarks
The data member in your control class that stores the line style used by the control's drawing methods, for example, solid, dashed, or dotted. If you choose the DRAWSTYLE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nDrawWidth, CComControl::m_nDrawMode
long m_nDrawWidth;
Remarks
The data member in your control class that stores the line width (in pixels) used by the control's drawing methods. If you choose the DRAWWIDTH option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nDrawStyle, CComControl::m_nDrawMode
long m_nFillStyle;
Remarks
The data member in your control class that stores the control's fill style, for example, solid, transparent, or cross-hatched. If you choose the FILLSTYLE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_nBackStyle
short m_nFreezeEvents;
Remarks
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).
CComControl Overview | Class Members
See Also IOleControl::FreezeEvents in the Win32 SDK
long m_nMousePointer;
Remarks
The data member in your control class that stores the type of mouse pointer displayed when the mouse is over the control, for example, arrow, cross, or hourglass. If you choose the MOUSEPOINTER option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_pMouseIcon
long m_nReadyState;
Remarks
The data member in your control class that stores the control's readiness state, for example, loading or loaded. If you choose the READYSTATE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
IFontDisp* m_pFont;
Remarks
The data member in your control class that stores a pointer to IFontDisp font properties. If you choose the FONT option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
HWND* m_phWndCD;
Remarks
Contains a pointer to the window handle associated with the control. Initialized in the CComControl constructor. Part of a union with m_hWndCD.
CComControl Overview | Class Members
See Also CComControl::CComControl, CComControl::m_hWndCD
IPictureDisp* m_pMouseIcon;
Remarks
The data member that stores a pointer to IPictureDisp picture properties of the graphic (icon, bitmap, or metafile) to be displayed when the mouse is over the control. The properties include the handle of the picture. If you choose the MOUSEICON option from the Stock Properties tab in the ATL Object Wizard, the wizardautomatically 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.
CComControl Overview | Class Members
See Also CComControl::m_nMousePointer
IPictureDisp* m_pPicture;
Remarks
The data member that stores a pointer to IPictureDisp picture properties of a graphic (icon, bitmap, or metafile) to be displayed. The properties include the handle of the picture. If you choose the PICTURE option from the Stock Properties tab in the ATL Object 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.
CComControl Overview | Class Members
See Also CComControl::m_pMouseIcon
RECT m_rcPos;
Remarks
The position in pixels of the control, expressed in the coordinates of the container.
CComControl Overview | Class Members
See Also CComControl::m_sizeExtent, CComControl::m_sizeNatural, RECT in the Win32 SDK
SIZE m_sizeExtent;
Remarks
The extent of the control in HIMETRIC units (each unit is 0.01 millimeters) on a particular display. This size is scaled by the display. The control's physical size is specified in the m_bsizeNatural data member and is not scaled.
You can convert size from HIMETRIC units to pixels with the global function AtlHiMetricToPixel.
CComControl Overview | Class Members
See Also CComControl::m_sizeNatural, CComControl::m_rcPos, SIZE in the Win32 SDK
SIZE m_sizeNatural;
Remarks
The physical size of the control in HIMETRIC units (each unit is 0.01 millimeters). This size is not scaled, while the size in the m_sizeExtent is scaled by the display.
You can convert size in HIMETRIC units to size in pixels with the global function AtlHiMetricToPixel.
CComControl Overview | Class Members
See Also CComControl::m_sizeExtent, CComControl::m_rcPos, SIZE in the Win32 SDK
CComPtr<IAdviseSink> m_spAdviseSink;
Remarks
A direct pointer to the advisory connection on the container (the container's IAdviseSink).
CComControl Overview | Class Members
See Also CComPtr
CComDispatchDriver m_spAmbientDispatch;
Remarks
A CComDispatchDriver object that lets you retrieve or set an object's properties through an IDispatch pointer.
CComControl Overview | Class Members
See Also CComDispatchDriver
CComPtr<IOleClientSite> m_spClientSite;
Remarks
A pointer to the control's client site within the container.
CComControl Overview | Class Members
See Also CComPtr, IOleClientSite in the Win32 SDK
CComPtr<IDataAdviseHolder> m_spDataAdviseHolder;
Remarks
Provides a standard means to hold advisory connection between data objects and advise sinks. (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.
CComControl Overview | Class Members
See Also CComPtr
CComPtr<IOleInPlaceSiteWindowless> m_spInPlaceSite;
Remarks
A pointer to the container's IOleInPlaceSite, IOleInPlaceSiteEx, or IOleInPlaceSiteWindowless interface pointer.
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_bInPlaceSite data member flags:
m_spInPlaceSite Type | m_bWndless Value | m_bInPlaceSite Value |
IOleInPlaceSiteWindowless | TRUE | TRUE or FALSE |
IOleInPlaceSiteEx | FALSE | TRUE |
IOleInPlaceSite | FALSE | FALSE |
CComControl Overview | Class Members
See Also CComPtr
CComPtr<IOleAdviseHolder> m_spOleAdviseHolder;
Remarks
Provides a standard implementation of a way to hold advisory connections. 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.
CComControl Overview | Class Members
See Also CComPtr