Windows support class-CAxWindow

Introduction

Hey, Ninjas! In this blog, we will be discussing Windows support - CAxWindow. This class is designed for developers who want to create and manipulate windows in their applications. With CAxWindow, you can create windows with various styles and properties and handle events such as button clicks and keyboard input. You'll also learn to work with standard controls such as buttons and text boxes.

This blog will give you a solid foundation in Windows programming and will be a valuable addition to your skill set. Let's get started!

CAxWindow Class

The CAxWindow class is a C++ class that provides an easy way to create and manipulate windows in a Windows application. It is a part of the "Atl" (Active Template Library) framework, which is a set of C++ templates that simplify the development of COM (Component Object Model) and Windows applications.

The CAxWindow class is derived from the CWindowImpl base class, which provides the basic functionality for creating and manipulating windows. It also supports handling events through message maps, such as button clicks and keyboard input.

Using the CAxWindow class, developers can create windows with various styles and properties, such as the window's size, position, and caption. It also allows the creation standard controls such as buttons and text boxes and handles their events.

Syntax

Let's see the syntax of the class below.

class CAxWindow: public CWindow

Members

The CAxWindow class has various members that can be used to create and manage windows.

There are two types of members, which are discussed below.

Methods

This member has nine functions, which are described below.

AttachControl
Attaches an existing ActiveX control to the CAxWindow object.
CAxWindow
Constructs a CAxWindow object.
CreateControl
Creates an ActiveX control, initializes it, and hosts it in the CAxWindow window.
CreateControlEx
Creates an ActiveX control and retrieves an interface pointer (or pointers) from the control.
GetWndClassName
Retrieves the predefined class name of the CAxWindow object.
QueryControl
Retrieves the IUnknown of the hosted ActiveX control.
QueryHost
Retrieves the IUnknown pointer of the CAxWindow object.
SetExternalDispatch
Sets the external dispatch interface used by the CAxWindow object.
SetExternalUIHandler
Sets the external IDocHostUIHandler interface used by the CAxWindow object.

Operators

This member has only one type, which is described below.

operator =
Assigns an HWND to an existing CAxWindow object.

Method Name / Operators	Description
AttachControl	Attach an existing ActiveX control to the CAxWindow object.
CAxWindow	Construct a CAxWindow object.
CreateControl	Creates an ActiveX control, initialises it, and hosts it in the CAxWindow window.
CreateControlEx	Creates an ActiveX control and retrieves an interface pointer from the control.
GetWndClassName	Retrieves the predefined class name of the CAxWindow object.
QueryControl	Retrieves the IUnknown of the hosted ActiveX control.
QueryHost	Retrieves the IUnknown pointer of the CAxWindow object.
SetExternalDispatch	Sets the external dispatch interface used by the CAxWindow object.
SetExternalUIHandler	Sets the external IDocHostUIHandler interface used by the CAxWindow object.
operator =	Assigns an HWND to an existing CAxWindow object.

CAxWindow::AttachControl

The AttachControl method attaches the specified control to the host and creates a new host object if one does not already exist. This method is a member function of the CAxWindow class that allows you to attach a control, such as a button or text box, to the window.

For example:

HRESULT AttachControl(
    IUnknown* pControl,
    IUnknown** ppUnkContainer);

Parameters

ppUnkContainer
A pointer to the IUnknown of the host .
pControl
A pointer to the IUnknown of the control.

Return Value

A standard HRESULT value.

Remarks

Before executing AttachControl, the control object that is being attached must be properly initialized.

CAxWindow::CAxWindow

The CAxWindow class has a constructor called CAxWindow(). This constructor is used to create an instance of the CAxWindow class. Using an existing window object handle, this function creates a CAxWindow object.

For example:

CAxWindow(HWND hWnd = NULL);

Parameters

hWnd
A handle to an existing window object.

CAxWindow::CreateControl

The CreateControl() method is a member function of the CAxWindow class that allows you to create a control. This function creates an ActiveX control, initializes it, and hosts it in the specified window.

For example:

HRESULT CreateControl(
    LPCOLESTR lpszName,
    IStream* pStream = NULL,
    IUnknown** ppUnkContainer = NULL);

HRESULT CreateControl(
    DWORD dwResID,
    IStream* pStream = NULL,
    IUnknown** ppUnkContainer = NULL);

Parameters

The CreateControl() method takes the following parameters:

lpszName
A pointer to a string to create the control.
pStream
A pointer to a stream that is used to set the control's settings initially. It may be NULL.
ppUnkContainer
It is the location of a pointer whose value will be the container's IUnknown. It may be NULL.
dwResID
It is the HTML resource's resource ID. The provided resource will be generated and loaded into the WebBrowser control.

Return Value

It will return a standard HRESULT value.

Remarks

If the second version of this method is used, an HTML control is created and bound to the resource identified by dwResID.

CAxWindow::CreateControlEx

The CreateControlEx() method is a member function of the CAxWindow class that allows you to create a control. This will create an ActiveX control, initializes it, and hosts it in the specified window.

For example:

HRESULT CreateControlEx(
    LPCOLESTR lpszName,
    IStream* pStream = NULL,
    IUnknown** ppUnkContainer = NULL,
    IUnknown** ppUnkControl = NULL,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

HRESULT CreateControlEx(
    DWORD dwResID,
    IStream* pStream = NULL,
    IUnknown** ppUnkContainer = NULL,
    IUnknown** ppUnkControl = NULL,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

Parameters

The CreateControlEx() method takes the following parameters:

lpszName
A pointer to a string to create the control.
pStream
This is the address of a pointer that will receive the IUnknown of the container. It can be NULL.
ppUnkContainer
This is the address of a pointer that will receive the IUnknown of the control. It can be NULL.
iidSink
This is the interface identifier of an outgoing interface on the contained object. It can be IID_NULL.
punkSink
This is an identifier for the control, which maps messages from the control to the appropriate message handlers in the window.
dwResID
This is the resource ID of an HTML resource. The WebBrowser control will be created and loaded with the specified resource.

Return Value

It will return a standard HRESULT value.

Remarks

This approach is comparable to CAxWindow::CreateControlEx and differs from that method in that it additionally enables you to set up an event sink to receive events fired by the control and receive an interface pointer to the newly constructed control.

CAxWindow::GetWndClassName

The GetWndClassName() is a member function of the CAxWindow class, that allows you to retrieve the class name of the window. The class name is a string that identifies the window's class and is used by Windows to determine which window procedure should be called to handle messages for the window.

For example:

static LPCTSTR GetWndClassName();

Return Value

A pointer to a string representing the name of the window class that is able to host unlicensed ActiveX components will be returned by this action.

CAxWindow::operator =

The operator = is an overloaded operator of the CAxWindow class, that allows you to assign one instance of the CAxWindow class to another. The operator= is used to copy the window's handle and other properties from one object to another.

For example:

CAxWindow<TBase>& operator=(HWND hWnd);

Parameters

hWnd
This parameter is a handle to an existing window.

Return Value

This method returns a reference to the current CAxWindow object.

CAxWindow::QueryControl

The QueryControl() method retrieves the specified interface of the hosted control. This is a member function of the CAxWindow class that allows you to retrieve an interface pointer to a control that is attached to the window.

For example:

HRESULT QueryControl(REFIID iid, void** ppUnk);
template <class  Q>
HRESULT QueryControl(Q** ppUnk);

Parameters

iid
This parameter specifies the IID of the control's interface.
ppUnk
This parameter is a reference to the control's interface. As long as a typed interface with an associated UUID is given, the reference ID in the template version of this method is not required.
Q
This parameter is the interface that is the subject of the query.

CAxWindow::QueryHost

The QueryHost() method is a member function of the CAxWindow class that allows you to retrieve an interface pointer to the host object that is associated with the window. The host object is typically an instance of a class that implements the IOleClientSite or IAdviseSink interfaces and is used by the window to communicate with the container application.

For example:

HRESULT QueryHost(REFIID iid, void** ppUnk);
template <class  Q>
HRESULT QueryHost(Q** ppUnk);

Parameters

The QueryHost() method takes the following parameters:

iid
This parameter specifies the IID of the control's interface.
ppUnk
This parameter is a pointer to the interface on the host.

Return Value

It will return a standard HRESULT value.

Remarks

The functionality of the window-hosting code, as implemented by AxWin, is accessible through the host interface.

CAxWindow::SetExternalDispatch

The SetExternalDispatch() method is a member function of the CAxWindow class that allows you to associate an IDispatch interface pointer with the window. The IDispatch interface is a COM interface that allows a client to call methods and access properties of an object and is commonly used in Automation and scripting.

Parameters

The SetExternalDispatch() method takes the following parameter:

pDisp
A pointer to an IDispatch interface that represents the external object.

For example:

HRESULT SetExternalDispatch(IDispatch* pDisp);

Return Value

This will return a standard HRESULT value.

CAxWindow::SetExternalUIHandler

The SetExternalUIHandler() method is a member function of the CAxWindow class that allows you to associate an IUIAutomation object with the window. The IUIAutomation interface is a COM interface that allows you to access the user interface (UI) of an application and automate tasks through the Windows UI Automation framework. This object can be used to manipulate the window and its controls by simulating user interactions.

For example:

HRESULT SetExternalUIHandler(IDocHostUIHandlerDispatch* pUIHandler);

Parameters

The SetExternalUIHandler() method takes the following parameter:

pUIHandler
A pointer to an IUIAutomation object that represents the external UI Automation object.

Return Value

This will return a standard HRESULT value.

Remarks

Control that searches the host's website for the IDocHostUIHandlerDispatch interface uses the external IDocHostUIHandlerDispatch interface. One control that accomplishes this is WebBrowser control.

Frequently Asked Questions

What is the CAxWindow class in Windows?

The CAxWindow class is a C++ class that provides a convenient way to work with ActiveX controls in a Windows application.

How do I create a window using the CAxWindow class?

You can create a window using the Create() method of the CAxWindow class, passing in the parent window, position, size, caption, and window style as parameters.

How do I attach a control to a window using the CAxWindow class?

You can attach a control to a window using the AttachControl() method of the CAxWindow class, passing in the control's handle, ID, and whether to sink the control's events to the window's message map.

How can I associate an IDispatch interface pointer with the window?

You can use the SetExternalDispatch() method of the CAxWindow class, passing in the IDispatch interface pointer that represents the external object.

Conclusion

In this blog, we have discussed the Windows support class-CAxWindow, along with members of the Windows support class-CAxWindow with code.

Check out these useful blogs on windows support classes:

If you think this blog has helped you enhance your knowledge about the Windows support class-CContainedWindowT, and if you want to learn more, check out our articles and many more on our Coding Ninjas Studio.

Visit our website to read more such blogs. Make sure that you enroll in the courses we provide, take mock tests, solve problems available, and interview puzzles. Also, you can pay attention to interview stuff- interview experiences and an interview bundle for placement preparations.

Happy Learning!