Adding Objects and Controls

You can use the ATL Object Wizard to add an object or a control to your ATL or MFC-based projects. For each COM object or control you add, the wizard generates CPP and H files, as well as an RGS file for script-based registry support.

If you are attempting to add a simple COM object to an MFC project, you will need to add ATL support to the existing project. For more information on this feature, see Adding ATL Support to Your MFC Project.

Note   The ATL Object Wizard adds the object to the active project. If you wish to add the control to another project on the workspace, you must first make it the active project.

To add an object or a control using the ATL Object Wizard

• With your project open, select New ATL Object from the Insert menu.

  -or-

• From ClassView, click the right mouse button on the project-level folder, and select New ATL Object from the pop-up menu.

  The ATL Object Wizard opens.

Note   If this is an MFC project to which you have not previously added an ATL object, you'll be prompted to specify whether you want ATL support added to your project. Clicking Yes opens the ATL Object Wizard.

The ATL Object Wizard displays the categories of objects on the left and the icons of the objects in each category on the right. Choose a category; the wizard displays the icons of the objects in that category.

ATL Objects

• Simple Object adds a minimal COM object.
  
  
• Add-in Object adds a COM object that extends the Visual C++ shell with your own toolbar button and event handling. This object offers the same functionality as the one added by the DevStudio Add-in Wizard on the Visual C++ File menu, New Projects tab.
  
  
• Internet Explorer Object adds an object that supports the interfaces needed by Internet Explorer, but without support for a user interface.
  
  
• Active Server Component adds an object that can be used by the Active Server Pages feature of Internet Information Server (IIS).
  
  
• MMC SnapIn creates a framework for a Microsoft Management Console Snap-In object. See MMC Snap-In Wizard and Microsoft Management Console in the Platform SDK for more information.
  
  
• MS Transaction Server Component includes the header files needed by the Microsoft Transaction Server and defines the object as nonaggregatable.
  
  
• Component Registrar Object adds an object that implements the IComponentRegistrar interface. This object can be used to register any objects in your in-process server that declare the DECLARE_OBJECT_DESCRIPTION macro. Using this object you can register and/or unregister objects individually, unlike DllRegisterServer and DllUnregisterServer which register and unregister all objects in your server. You may also get a list of objects in the server and their descriptions with the IComponentRegistrar::GetComponents method.

ATL Controls

• Full Control adds an object that supports the interfaces for all containers.
  
  
• Lite Control adds an object that supports the interfaces needed by Internet Explorer, including support for a user interface.
  
  
• Property Page adds an object that implements a property page.
  
  
• Composite Control adds a control that can host many other controls.
  
  
• HTML Control adds a control with DHTML functionality and displays an HTML web page in its user interface.
  
  
• Lite Composite Control adds a composite control that can host other controls, but it supports only the interfaces needed by Internet Explorer.
  
  
• Lite HTML Control adds a control with DHTML functionality and displays an HTML web page in its user interface, but it supports only the interfaces needed by Internet Explorer.

ATL Miscellaneous

• Dialog adds an object that implements a dialog box.

Data Access

• Provider adds code to support OLE DB provider templates.
  
  
• Consumer adds code to support OLE DB consumer templates.

Double-click the control or object you want to insert. The ATL Object Wizard displays a dialog box showing options that apply to your object or control.

Note   Depending on the type of object or control you select, some of the pages and options described below may not be available.

In the Names page, enter class and file names. By default, the name you enter for Short name becomes the root for all other names in this page. You can enter your own names rather than accept these defaults.

• Class is the name of the class implementing your object.
  
  
• CoClass is the name of the component class that contains a list of interfaces supported by the object.
  
  
• Interface is the name of the interface you create for your object. This interface contains your custom methods. For Full Controls, Internet Explorer Controls, Simple Objects, Internet Explorer Objects, Add-in Objects, Active Server Components, and Microsoft Transaction Server Components, the wizard creates an interface with the name you specify. For Property Page objects, no custom interface is created, and the wizard assigns IUnknown as the object interface. Dialog objects do not create an interface.
  
  
• Type is a description string for the object that goes into the registry.
  
  
• ProgID is a name that containers can use instead of the CLSID of the object.

In the Attributes page, select a threading model, interface type, and aggregation support:

• Choose Dual Interfaces if you want the object's interfaces to derive from IDispatch as well as support your custom functions (the vtable has custom interface functions plus late-binding IDispatch methods). This allows both COM clients and Automation controllers to access your object.
  
  
• Choose Custom Interfaces to derive the object's interfaces from IUnknown (the vtable has custom interface functions and not IDispatch methods). A custom interface can be faster than a dual interface, especially across process boundaries.
  
  
• Choose Only for aggregation if you want the object to be instantiated only if it is being aggregated.
  
  
• Check the Support ISupportErrorInfo check box to have your object implement the ISupportErrorInfo interface for error reporting.
  
  
• Check the Support Connection Points check box to add support for connection points to the object. The wizard will automatically derive the object's class from IConnectionPointContainerImpl.
  
  
• Check the Free Threaded Marshaler check box to create a free-threaded marshaler object to efficiently marshal interface pointers between threads in the same process.

In the Miscellaneous page, choose the features for the object.

• Choose Opaque to make your control completely opaque, so that none of the container shows behind the control boundaries. This helps the container draw the control more quickly. The entire control rectangle passes to your control class's OnDraw method. This option sets the VIEWSTATUS_OPAQUE bit in the VIEWSTATUS enumeration.
  
  
• Choose Solid Background to make the control's background a solid color and not a pattern. This option is meaningful only if the Opaque is option is also selected. This option sets the VIEWSTATUS_SOLIDBKGND bit in the VIEWSTATUS enumeration.
  
  
• Choose Invisible at runtime to make your control invisible at run time. You can use invisible controls to perform operations in the background, such as firing events at timed intervals.
  
  
• Choose Acts like button to enable your control to act like a button, in particular to display itself as the default button based on the ambient property DisplayAsDefault.
  
  
• Choose Acts like label to enable your control to replace the container's native label.
  
  
• Choose Add control based on to superclass one of the standard window classes. The drop-down list contains window class names defined by Windows. When you choose one of these, the wizard adds a CContainedWindow member variable to your control's class. CContainedWindow::Create will superclass the window class you specify.
  
  
• Choose Normalize DC to have your control create a normalized device context when it is called to draw itself. This standardizes the control's appearance, but is less efficient.
  
  
• Choose Insertable to have your control appear in the Insert Object dialog box of applications such as Microsoft Word and Microsoft Excel. Your control can then be inserted by any application that supports embedded objects through the Insert Object dialog box.
  
  
• Choose Windowed Only to force your control to be windowed, even in containers that support windowless objects. If you do not select this option, your control will automatically be windowless in containers that support windowless objects, and automatically be windowed in containers that do not support windowless objects.

In the Stock Properties page, select the stock properties you want the object to support, such as Caption or Border Color. You can select all the stock properties at once by clicking the >> button.

In the Strings page, enter names for the property page object.

• Title is the text that appears on the property page's tab.
  
  
• Doc String is a text string describing the page. The property frame could use the description in a status line or tool tip. The standard property frame currently does not use this string.
  
  
• Helpfile is the name of the associated help file. The help file name should be the simple name without a path. When the user presses Help, the frame opens the help file in the directory named in the value of the HelpDir key in the property page registry entries under its CLSID.

In the Add-in page, choose features for the Add-in object.

• Provide Toolbar creates a toolbar button the user can click to carry out a command added by your Add-in object.
  
  
• Command Name is the name of the command added to Visual C++ by your Add-in object. This name appears in the list on the Add-ins and Macro Files tab of the Tools menu, Customize option.
  
  
• Method Name is the name of the method that implements the command.
  
  
• Toolbar Text is the text that you want to appear on the button you add to the toolbar to carry out your command.
  
  
• Status bar Text is the text you want to appear on the status line when your command is executing.
  
  
• Tooltips Text is the text you want to appear in the tooltip message for your toolbar button when the user's mouse hovers over the button.
  
  
• Application Events allows your Add-in object to catch application events.
  
  
• Debugger Events allows your Add-in object to catch debugger events.

In the ASP page, choose features for the Active Server component.

• OnStartPage/OnEndPage, checked by default, adds the OnStartPage and OnEndPage methods to the object.
  
  
• If OnStartPage/OnEndPage is checked, you can choose which Intrinsic Objects you want to have available as member pointers in the object's class. By default, each intrinsic object is checked.

In the MTX page, choose features for the Microsoft Transaction Server component. Dual and Custom choose the kind of interface implemented, and Support Connection Points adds support for connection points. These options are the same as the ones in the Attributes page for other kinds of objects. In addition, the MTX page has two unique options:

• Support IObjectControl provides access to the three IObjectControl methods: Activate, CanBePooled, and Deactivate.
  
  
• Can be pooled tells the Transaction Server run-time environment that your object should be returned to an instance pool after deactivation, rather than destroyed. This option cannot be selected unless the Support IObjectControl option is also selected.