ATL Object Wizard Options

---

When you develop your controls in ATL, you'll be happy to find that default implementations of these standard COM interfaces are provided for your consumption. Writing a full ActiveX control by hand would be a significant undertaking, and unlike the first 13 chapters of this book, we will not be beginning with a raw C++ example to illustrate building an ActiveX control (thank me later). Rather, we will leverage what you already know about COM and ATL, and jump right into the ATL templates and CASE tools used when building ActiveX objects. On a related note, we will not be examining the details of each and every method of each and every standard COM interface used for an ActiveX control. If you need to see more details than this chapter provides, I will assume you know how to check things out on your own accord. That being said, let's begin seeing how ATL can get the ball rolling and reexamine the options provided by the ATL Object Wizard (Figure 14-6):

Figure 14-6: Available control selections as of ATL 3.0.

In Chapter 6, we took a look at the various types of COM objects you can insert into an ATL workspace using the ATL Object Wizard. In this chapter we will be building a Full Control; however, the available options are:

Object Wizard Control	Meaning in Life
Full Control	This ActiveX control supports all necessary COM interfaces to be used by any ActiveX container.
Lite Control	Supports a subset of the required interfaces necessary to host the control in MS Internet Explorer (and VB).
Composite Control	A control that is able to host other controls as part of its composition. You are provided a dialog template to assemble the GUI of the control.
Lite Composite Control	A composite control supporting only the interfaces necessary for MS Internet Explorer (and VB).
HTML Control	This control is a full control, with the additional ability to display DHTML web pages within its window frame.
Lite HTML Control	You guessed it; this control supports the necessary interfaces for MS IE (and VB), and the ability to support DHTML web pages.
Property Page	Used to represent a single custom property page for use by the control. You are provided with a dialog template to assemble your GUI.

Configuring a Full Control with the ATL Object Wizard

First and foremost, be aware that ActiveX controls are always hosted in-process. This of course means that your initial ATL project workspace must be configured as a DLL. If you have previous experience developing and using controls in other frameworks, you may be used to seeing the *.ocx (OLE control extension) file type. This is just another way to identify in-proc servers, and the fact that ATL picked *.dll over *.ocx is irrelevant. Let's build a DLL server named AXShapesServer.

 On the CD   AXShapesServer is included on your supplemental CD, under the Labs\Chapter 14 subdirectory.

Once you have established your component housing using the ATL COM AppWizard, you are now able to select which type of ActiveX control you wish to place into the DLL. Keep in mind that it is possible for a single DLL to contain any number of ActiveX controls, in the same way that a given DLL can contain any number of Simple Objects (after all, an ActiveX control is just a COM object). This may help ease your distribution issues, given that all controls are contained in a single DLL. On the other hand, this will increase the size of your binary (which may or may not be problematic).

We will insert a single Full Control using the ATL Object Wizard. This new control will be named ShapesControl (Figure 14-7).

Figure 14-7: Setting the names for ShapesControl.

As you can see, Full Controls have two additional configuration tabs above and beyond Names and Attributes. From the Attributes tab (Figure 14-8), be sure to select support for connection points to enable our control to fire events to the container. This example does not need to support COM exceptions; however, if you need to do so, you may enable this support and use the techniques described in Chapter 7. Also note that two of your threading options have been disabled: You cannot enter into the process-wide MTA. This is not a flaw in the wizard, but a requirement of how ActiveX controls operate (they require thread affinity).

Figure 14-8: Enabling connection points for ShapesControl.

Options Provided by the Miscellaneous Tab

The Miscellaneous tab allows you to specify a number of odds and ends about how your ActiveX control should behave. As all of these features help establish the visible capabilities of your control, it should be clear why a Simple Object did not provide this configuration option. The only additional option to check for the ShapesControl is the Insertable selection as seen in Figure 14-9. This allows your control to be accessed by the Insert Object dialog box found in numerous products, such as MS Word.

Figure 14-9: ActiveX controls have additional settings above and beyond a simple coclass.

Again, the options available from the Miscellaneous tab help configure how your control is to behave when rendered by (and used by) a container. As many of these options are not very self-descriptive, here is a rundown of each option.

Miscellaneous Option	Meaning in Life
Opaque	Enable this option if your control is rendered into a full rectangle, as it informs the host it has no need to render a background beneath the object. Other controls render an irregular foreground, and require the host to render a background behind the control.
Solid Background	Opaque controls can select this option to be provided with a default solid background.
Invisible at Runtime	This configures your control to have a visible presence only at design time (like the VB Timer control).
Acts Like a Button	When a host has numerous controls composing its GUI, selecting this option will make your control the "default" item.
Acts Like a Label	This option allows the control to receive focus from the Tab key.
Normalize DC (device context)	Establishes the drawing coordinates used for your control to be (0, 0) based. When this option is deselected, you will need to bypass the OnDraw() function used by default, and override the OnAdvancedDraw() method provided by the framework to establish your own scaling options.
Insertable	This option allows your control to appear as a valid entry from the standard Insert Object dialog box used by containers such as MS Office.
Windowed Only	Determines who is responsible for creating a window to host the control. If selected, the control takes care of things; if not, the container is expected to. Be aware that not all hosts have this capability!
Add Control Based On	ATL provides a way to build your control based on existing window types. For example, you may wish to build a stylized button control which adds additional functionality beyond "being pressed."

Later in the chapter, we will see how some of these selections translate into real code, but for now let's press on and examine the final tab related to ATL ActiveX controls and learn about stock properties in the process.

The Stock Properties Tab

The final configuration option that needs to be made is which (if any) stock properties will be supported by our control. A stock property is simply a standard, well-known property, common across most controls. For example, many controls wish to provide a way to set the background color of the control's view area. Controls that display text may wish to support the Font property. Rather than having each developer create unique properties that do more or less the same thing, COM defines a predefined set of stock properties. ShapesControl will make use of the Font, Background Color, and Caption stock properties (Figure 14-10).

Figure 14-10: Stockproperties of ShapesControl.

Each stock property has a preassigned DISPID, all of which are defined in <olectl.idl>. As well, each stock property operates on a specific type of data. Given this, an ActiveX control container "understands" what these properties are used for, and can integrate them into the development environment, call them at run time, and so forth.

The constant used to refer to a specific stock property can be determined by prefixing "DISPID_" to the capitalized name of the property (for example, DISPID_FONT, DISPID_BACKCOLOR, DISPID_CAPTION, and so on). The following table describes the meaning of each stock property and the underlying data type:

Stock Property	Data Type	Meaning in Life
Appearance	short	Determines how the control is painted (flat or 3D).
AutoSize	Bit flag	Enables or disables sizing capabilities.
BackColor ForeColor	OLE_COLOR	Configures the background and foreground color for the control.
BackStyle	long	Configures the transparent or opaque status of the control.
BorderColor BorderStyle BorderVisible BorderWidth	OLE_COLOR long long long	Used to establish the attributes of the control's border.
Caption Text	BSTR	The caption (and text) used for the control.
DrawMode	long	Configures the GDI drawing mode for the control.
DrawStyle DrawWidth	long long	Configures the style of the pen used to draw lines for this control.
Enabled	BOOL	Enables and disables the control.
FillColor FillStyle	OLE_COLOR long	Configures the color and pattern of the control's brush.
Font	IFontDisp*	Sets and retrieves the font used to render text in the control.
HWND	HWND	Allows access to the control's underlying window handle.
MouseIcon MousePointer	IPictureDisp* long	Configures the icon to use when the mouse is over this control.
Picture	IPictureDisp*	Allows your control to handle icons, bitmaps, and metafiles using a standard property.
TabStop	BOOL	Enables and disables the tab stop support for this control.

---