CComControl 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

template <class T, class WinBase = CWindowImpl<T>>
class ATL_NO_VTABLE CComControl : public CComControlBase,
    public WinBase;

Parameters

T
The class implementing the control.

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

Members

Public Constructors

Name	Description
CComControl::CComControl	Constructor.

Public Methods

Name	Description
CComControl::ControlQueryInterface	Retrieves a pointer to the requested interface.
CComControl::CreateControlWindow	Creates a window for the control.
CComControl::FireOnChanged	Notifies the container's sink that a control property has changed.
CComControl::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.
CComControl::MessageBox	Call this method to create, display, and operate a message box.

Remarks

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

For a demonstration of CComControl methods and data members, see the CIRC sample.

Inheritance Hierarchy

WinBase

CComControlBase

CComControl

Requirements

Header: atlctl.h

CComControl::CComControl

The constructor.

CComControl();

Remarks

Calls the CComControlBase constructor, passing the m_hWnd data member inherited through CWindowImpl.

CComControl::ControlQueryInterface

Retrieves a pointer to the requested interface.

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

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

CComControl::CreateControlWindow

By default, creates a window for the control by calling CWindowImpl::Create.

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

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.

Example

RECT rc = {10,10,210,110};
HWND hwndParent, hwndControl;

// get HWND of control's parent window from IOleInPlaceSite interface
m_spInPlaceSite->GetWindow(&hwndParent);
hwndControl = CreateControlWindow(hwndParent, rc);

CComControl::FireOnChanged

Notifies the container's sink that a control property has changed.

HRESULT FireOnChanged(DISPID dispID);

Parameters

dispID
[in] Identifier of the property that has changed.

Return Value

One of the standard HRESULT values.

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 method is safe to call even if your control doesn't support connection points.

Example

STDMETHODIMP CMyControl::put_MyText(BSTR newVal)
{
   // store newVal in CComBstr member
   m_bstrMyText = newVal;

   // note the DISPID for the MyText property is 3 in this example
   FireOnChanged(3);

   return S_OK;
}

CComControl::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.

HRESULT FireOnRequestEdit(DISPID dispID);

Parameters

dispID
[in] Identifier of the property about to change.

Return Value

One of the standard HRESULT values.

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 method is safe to call even if your control doesn't support connection points.

Example

STDMETHODIMP CMyControl::put_MyTitle(BSTR newVal)
{
   // the DISPID for MyTitle in this example is 4
   DISPID dispID = 4;

   // make sure we can change the property
   if (FireOnRequestEdit(dispID) == S_FALSE)
      return S_FALSE;

   // store newVal in CComBstr member
   m_bstrMyTitle = newVal;

   // signal that the property has been changed
   FireOnChanged(dispID);

   return S_OK;
}

CComControl::MessageBox

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

int MessageBox(
    LPCTSTR lpszText,
    LPCTSTR lpszCaption = _T(""),
    UINT nType = MB_OK);

Parameters

lpszText
The text to be displayed in the message box.

lpszCaption
The dialog box title. If NULL (the default), the title "Error" is used.

nType
Specifies the contents and behavior of the dialog box. See the MessageBox entry in the Windows SDK documentation for a list of the different message boxes available. The default provides a simple OK button.

Return Value

Returns an integer value specifying one of the menu-item values listed under MessageBox in the Windows SDK documentation.

Remarks

MessageBox is useful both during development and as an easy way to display an error or warning message to the user.

See also

CWindowImpl Class
Class Overview
CComControlBase Class
CComCompositeControl Class