| C & C++ Programming | MFC Programming | Download | Site Index |


 

 

 

Supplementary notes for MFC Programming Module 29

 

 

 

What do we have in this Module?

  1. CComControl Class information

  2. CComControl Members

  3. Methods

  4. CComControlBase Class

  5. CComControlBase Members

  6. Methods

  7. GetAmbient Property Methods

  8. Data Members

  9. Typedefs

  10. CWindowImpl Class

  11. Remarks

  12. CWindowImpl Members

  13. Methods

  14. CWindowImplBaseT Methods

  15. Static Functions

  16. Data Members

 

 

CComControl Class information

 

Information

Description

The class

CComControl.

The use

This class provides methods for creating and managing ATL controls.

The prototype

template <class T, class WinBase = CWindowImpl< T > >

class ATL_NO_VTABLE CComControl : public CComControlBase, public WinBase;

The parameters

T - The class implementing the control.

WinBase - The base class that implements windowing functions. Defaults to CWindowImpl.

The header file

atlctl.h

Remark

CComControl is a set of useful control helper functions and essential data members for ATL controls. When you create a standard control or a DHTML control using the ATL Control Wizard, the wizard will automatically derive your class from CComControl. CComControl derives most of its methods from CComControlBase. For a demonstration of CComControl methods and data members, see the CIRC sample.

 

Table 1.

 

CComControl 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 and that the object is asking the sink how to proceed.

MessageBox()

Call this method to create, display, and operate a message box.

 

 Table 2.

 

CComControlBase Class

 

Information

Description

The class

CComControlBase.

The use

This class provides methods for creating and managing ATL controls.

The prototype

class ATL_NO_VTABLE CComControlBase

The parameters

None.

The header file

atlctl.h

Remark

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.

 

Table 3

 

CComControlBase Members

 

CComControlBase class members are divided into the following categories:

  1. Methods.

  2. GetAmbient Property Methods.

  3. Data Members.

  4. Typedefs.

Methods

 

CComControlBase()

The constructor.

~CComControlBase()

The destructor.

ControlQueryInterface()

Retrieves a pointer to the requested interface.

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

DoesVerbUIActivate()

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

DoVerbProperties()

Displays the control's property pages.

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.

GetDirty()

Returns the value of data member m_bRequiresSave.

GetZoomInfo()

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

InPlaceActivate()

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

InternalGetSite()

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

OnDraw()

Override this method to draw your control.

OnDrawAdvanced()

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

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.

OnMouseActivate()

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

OnPaint()

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

OnSetFocus()

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

PreTranslateAccelerator()

Override this method to provide your own keyboard accelerator handlers.

SendOnClose()

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

SendOnDataChange()

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

SendOnRename()

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

SendOnSave()

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

SendOnViewChange()

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

SetControlFocus()

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

SetDirty()

Sets the data member m_bRequiresSave to the value in bDirty.

 

Table 4.

 

 

 

 

GetAmbient Property Methods

 

GetAmbientAppearance()

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

GetAmbientAutoClip()

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

GetAmbientBackColor()

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

GetAmbientCharSet()

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

GetAmbientCodePage()

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

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.

GetAmbientDisplayName()

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

GetAmbientFont()

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

GetAmbientFontDisp()

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

GetAmbientForeColor()

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

GetAmbientLocaleID()

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

GetAmbientMessageReflect()

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

GetAmbientPalette()

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

GetAmbientProperty()

Retrieves the container property specified by id.

GetAmbientRightToLeft()

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

GetAmbientScaleUnits()

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

GetAmbientShowGrabHandles()

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

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.

GetAmbientSupportsMnemonics()

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

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.

GetAmbientTopToBottom()

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

GetAmbientUIDead()

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

GetAmbientUserMode()

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

 

Table 5

 

Data Members

 

m_bAutoSize

Flag indicating the control cannot be any other size.

m_bDrawFromNatural

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

m_bDrawGetDataInHimetric

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

m_bInPlaceActive

Flag indicating the control is in-place active.

m_bInPlaceSiteEx

Flag indicating the container supports the IOleInPlaceSiteEx interface and 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 support for OCX96 control features (such as flicker-free and windowless controls), and whether the control is windowed or windowless.

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, such as menus and toolbars, 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

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

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

m_rcPos

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

m_sizeExtent

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

m_sizeNatural

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

m_spAdviseSink

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

m_spAmbientDispatch

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

m_spClientSite

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

m_spDataAdviseHolder

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

m_spInPlaceSite

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

m_spOleAdviseHolder

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

 

Table 6.

 

Typedefs

 

AppearanceType

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

 

Table 7.

 

CWindowImpl Class

 

Information

Description

The class

CWindowImpl.

The use

This class provides methods for creating or subclassing a window.

The prototype

template <class T, class TBase = CWindow, class TWinTraits = CControlWinTraits>

class ATL_NO_VTABLE CWindowImpl : public CWindowImplBaseT< TBase, TWinTraits >

The parameters

T - Your class, derived from CWindowImpl.

TBase - The base class of your new class. The default base class is CWindow.

TWinTraits - A traits class that defines styles for your window. The default is CControlWinTraits.

The header file

atlwin.h

Remark

See below.

 

Table 8.

 

Remarks

 

CWindowImpl allows you to create a new window or subclass an existing window. CWindowImpl's window procedure uses a message map to direct messages to the appropriate handlers.

CWindowImpl::Create creates a new window based on the window class information managed by CWndClassInfo. CWindowImpl contains the DECLARE_WND_CLASS macro, which means CWndClassInfo will register a new window class. If you want to superclass an existing window class, derive your class from CWindowImpl and include the DECLARE_WND_SUPERCLASS macro. In this case, CWndClassInfo will register a window class that is based on an existing class but uses CWindowImpl::WindowProc. For example:

 

class CMyWindow : CComControl<CMyWindow>, ...// CComControl derives from CWindowImpl

{

public:

   // 1. The NULL parameter means ATL will generate a

   //    name for the superclass

   // 2. The "EDIT" parameter means the superclass is

   //    based on the standard Windows Edit box

   DECLARE_WND_SUPERCLASS(NULL, "EDIT")

   ...

};

 

Note:   Because CWndClassInfo manages the information for a single window class, each window created through an instance of CWindowImpl will be based on the same window class. CWindowImpl also supports window subclassing. The SubclassWindow() method attaches an existing window to the CWindowImpl object and changes the window procedure to CWindowImpl::WindowProc. Each instance of CWindowImpl can subclass a different window. Take note that for any given CWindowImpl object, call either Create() or SubclassWindow(). You should not invoke both methods on the same object. In addition to CWindowImpl, ATL provides CContainedWindow to create a window contained within another object. The base class destructor (~CWindowImplRoot) ensures that the window is gone before the object is destroyed. CWindowImpl derives from CWindowImplBaseT, which derives from CWindowImplRoot, which in turn derives from TBase and CMessageMap.

 

CWindowImpl Members

 

Methods

 

Create()

Creates a window.

 

Table 9.

 

CWindowImplBaseT Methods

 

DefWindowProc()

Provides default message processing.

GetCurrentMessage()

Returns the current message.

GetWindowProc()

Returns the current window procedure.

OnFinalMessage()

Called after receiving the last message (typically WM_NCDESTROY).

SubclassWindow()

Subclasses a window.

UnsubclassWindow()

Restores a previously subclassed window.

 

Table 10.

 

Static Functions

 

GetWndClassInfo()

Returns a static instance of CWndClassInfo, which manages the window class information.

WindowProc()

Processes messages sent to the window.

 

Table 11.

 

Data Members

 

m_pfnSuperWindowProc

Points to the window class's original window procedure.

 

Table 12.

 

 

 


| C & C++ Programming | MFC Programming | Download | Site Index |