DOCUMENT:Q179385 10-JUN-2002 [visualc] TITLE :HOWTO: Add Custom ATL Objects to the ATL Object Wizard PRODUCT :Microsoft C Compiler PROD/VER::1.0,1.1,2.0,2.1,3.0,5.0,6.0 OPER/SYS: KEYWORDS:kbwizard kbATL200 kbATL210 kbAutomation kbide kbVC500 kbVC600 kbATL300 MSGRAPH kbATL100 ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - The Microsoft Active Template Library (ATL), versions 1.0, 1.1, 2.0, 2.1, 3.0, used with: - Microsoft Visual C++, 32-bit Enterprise Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Professional Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Learning Edition, version 6.0 ------------------------------------------------------------------------------- IMPORTANT: This article contains information about editing the registry. Before you edit the registry, make sure you understand how to restore it if a problem occurs. For information about how to do this, view the "Restoring the Registry" Help topic in Regedit.exe or the "Restoring a Registry Key" Help topic in Regedt32.exe. SUMMARY ======= Starting with version 5.0, Visual C++ contains an ATL Object Wizard to insert stock ATL objects into an ATL project. It is possible to add custom configurable ATL objects to the ATL Object Wizard dialog box. This information is documented in Visual C++ 6.0 in the file Template.txt, which is located in the following directory: \Common\MsDev98\Template\Atl. This article supplements that documentation; however, these techniques are unsupported and are subject to change in future versions of the product. This information is supplied as a courtesy for developers who may wish to extend the functionality of the standard objects. MORE INFORMATION ================ In a Visual C++ ATL project, clicking New ATL Object on the Insert menu displays a dialog box titled "ATL Object Wizard." This dialog box normally contains several categories of predefined ATL objects with configurable properties. It is also possible to add custom-configurable ATL objects to this dialog box. The following sections develop these general steps for creating and installing a custom ATL object: - Create Property Pages - Create a Custom ATL Object Template - Create an ATL Object Wizard Control Script (.CTL) File - Register the Custom ATL Object with the ATL Object Wizard The Wizard looks in the \Template\Atl folder for the control script (.ctl) file; the other files created in these steps may be placed there also. NOTE: In Visual C++ 5.0, the base directory for folders referenced herein is \SharedIde; in version 6.0 it is \Common\MsDev98. Create Property Pages --------------------- Property pages allow the user to customize the object being inserted by setting symbol values (the Wizard substitutes symbols with their values when it processes the object's template). The Wizard creates a property sheet dialog box with OleCreatePropertyFrame(), passing it the list of property pages specified in the control script (the [!Dialog(...)] directive lists property pages' ProgIDs, which the Wizard uses to determine their CLSIDs). Property pages implement the IPropertyPage interface. Where appropriate, your custom ATL object may use standard property pages (found in \bin\ide); one useful general purpose property page is "Names" (implemented in Atlobj.dll). The ATL Object Wizard implements an interface called ISymbolMap. Using ISymbolMap methods, property pages set symbol values in the Wizard and get current symbol settings. The Wizard replaces symbol references in the object's template with these values. To obtain the ISymbolMap interface, query the IUnknown pointer passed into IPropertyPage's SetObjects method. See "ISymbolMap Interface Definition for C/C++" below for the text of a header file that defines the ISymbolMap interface. To create and register custom property pages: 1. Make sure the standard ATL wizard registration template (.rgs) files include a CLSID value under the version-independent ProgID entry, as described in Q167654 question 18. For additional information, please see the following article in the Microsoft Knowledge Base: Q167654 HOWTO: Visual C++ 5.0 (Professional & Enterprise) Support FAQ 2. Create an ATL project that contains an ATL "Property Page" object (from the "Controls" category in the ATL Object Wizard). See References for more information about creating ATL projects. 3. In this project, implement the Apply method with calls to the Wizard using the ISymbolMap interface. 4. Build the project. 5. Register the page. Copy the file (usually a .dll) to the computer where it will be used, then run "REGSVR32 ". The following code illustrates how to use the ISymbolMap interface: Sample Code ----------- #include "atlbase.h" // For smart pointer definitions. #include "SymMap.h" // Text for SymMap.h is in this article--see below. HRESULT MyPropPage::Apply(void) { for (UINT i = 0; i < m_nObjects; i++) { CComQIPtr pSymMap( m_ppUnk[i] ); // Use smart pointer /* Equivalent code: ISymbolMap* pSymMap = NULL; m_ppUnk[i]->QueryInterface( &__uuidof(ISymbolMap), (LPVOID *)&pSymMap ); ... if (pSymMap != NULL) pSymMap->Release(); */ // Call the ATL Object Wizard. if (pSymMap != NULL) { // pSymMap->... } } m_bDirty = FALSE; return S_OK; }; ISymbolMap defines the following methods, in addition to the standard IUnknown methods: - Set: Adds the symbol string pair to the internal map of the wizard: HRESULT Set(/* [in] */ LPCOLESTR strSymbol, /* [in] */ LPCOLESTR strValue); Returns S_OK - Get: Retrieves the value associated with the specified symbol. If the call is successful, pstrValue will point to a BSTR which is allocated using SysAllocString. The caller should free this string using SysFreeString. HRESULT Get(/* [in] */ LPCOLESTR strSymbol, /* [retval][out] */ BSTR *pstrValue); Returns S_OK if the symbol exists; E_FAIL otherwise - Clear: Clears the wizard's internal map of all symbols. HRESULT Clear(void); Returns S_OK - SetStatus: Allows individual property pages to enable/disable the OK button so the user can accept the page; use when the OK button should be disabled until the user has entered required values. HRESULT SetStatus(/* [in] */ const CLSID *pclsid, /* [in] */ BOOL bEnableOK); pclsid: pointer to CLSID of property page calling this method bEnableOK: TRUE enables the OK button; FALSE disables Returns S_OK Create a Custom ATL Object Template ----------------------------------- An ATL object template is a set of files that include (at a minimum) a C++ implementation (.cpp) file, a corresponding header (.h) file to define the object's interface, as well as a registrar script (.rgs) file used to set up the object into a system's registry (see References for information on creating registrar scripts). Though these files are similar to standard C++ source files, they become templates with the addition of symbols and directives. The Wizard replaces the symbols with text that the control script (.ctl file) specifies or collects, creating new source files for the object being inserted. Directives control how the Wizard generates text into the current project. To indicate symbols and directives, put brackets around them and lead them with an exclamation mark, as follows: [!] or [!] For example, if the script sets a symbol named "MySymbol" to "Subst Text", the Wizard replaces "[!MySymbol]" with "Subst Text" wherever it occurs in the template files. Examine the .cpp, .h and .rgs files in "\SharedIde\Template\atl" for examples of ATL object templates. Directives are reserved words that control text generation into the current project. The table below lists directives that may be used in a template file. Symbols referenced inside directives have no special marking. Directives and symbols are case-sensitive. This example uses directives to add a blank line to the current output file if the symbol "MySymbol" has been set to "BlankMe"; otherwise, they add a comment: [!if=(MySymbol, "BlankMe")] [!crlf] [!else] // Here is a comment, instead [!endif] Directives Used in ATL Object Template Files -------------------------------------------- Directive* Effect ------------------------------------------------------------------------ crlf Inserts a new line in the output file if() If exists in Wizard's symbol map, uses following directives and output; value of the symbol is irrelevant if!() If does not exist in Wizard's symbol map, uses following directives and output; symbol value is ignored if=(, ) If exists and its setting matches exactly, uses following directives and output if!=(, ) If does not exist or its setting does not match exactly, uses following directives and output else When an [!if...] tests false, uses following directives and output instead endif Marks the end of scope of an [!if...] and optional [else] outputoff Halts adding to output file until [!outputon] outputon Resumes adding to output file after [!outputoff] * In this table, denotes a symbol name and denotes text enclosed in double-quotes. The following tables list some standard symbols and describe how they get their values. The Template.txt file documents more symbols and their explanations. Symbol names are case-sensitive. Symbols Set by the Wizard Prior to Processing the Control Script ---------------------------------------------------------------- Symbol Predefined Value -------------------------------------------------------- ConnectionPointInterface "NULL" GalleryPath String specifying location of \Template\Atl LibGUID GUID of the typelib in the project's .IDL file LibName Name of the typelib in the project's .IDL file ProjectAppID If EXE project, its local server AppId; else not set ProjectName Name of the current project ProjectNameCPP Name of the project's main .cpp file ProjectNameHeader Name of the project's header (.h) file ProjectNameRC Name of the project's resource (RC) file ProjectNameSafe Project name stripped of characters invalid for identifiers ProjectType Type of project: "EXE" or "DLL" Symbols Set by User in "Names" Property Page Fields --------------------------------------------------- Symbol Field Name in "Names" ------------------------------------------------------------------- ClassName "Class" CoClassName "CoClass" CPPName ".CPP File" HeaderName ".H File" InterfaceName "Interface" ObjectGUID None - a new GUID is generated and its value is used ProgID "ProgID" with .1 appended ShortName "Short Name" TypeName "Type" VersionIndependentProgID "ProgId" Create an ATL Object Wizard Control Script (.CTL) File ------------------------------------------------------ The control script (.CTL file) specifies symbol values implicitly or collects them during user property page dialog boxes. It directs the Wizard to create or update various project files to create the ATL object. As with template files, control script directives have a leading exclamation mark and surrounding brackets, as follows: [!] Symbols used inside directives have no special marking. Examine the .ctl files in \Template\atl, such as "Addin.ctl," for examples of control scripts. The Wizard processes the control script directives sequentially. The table below lists the directives used in control scripts. Here is a simple script that opens the "Names" dialog box, creates a header file based on the "Addin.h" template, and adds it to the current project: [!Dialog("Names")] [!strcpy(UpperShortName, ShortName)] [!toupper(UpperShortName)] [!AddStringToSymbol(HeaderTemplate, GalleryPath, "Addin.h")] [!target(HeaderName)] [!include(HeaderTemplate)] [!target()] [!AddFileToProject(HeaderName)] Directives Used in ATL Object Wizard Control Script Files --------------------------------------------------------- This is a list of directives used by Visual C++ 5.0. The Template.txt file documents more directives recognized by Visual C++ 6.0 and their explanations. Directive* Effect ---------------------------------------------------------------------- AddCoClassToIDL(, ) Adds contents of to , assuming that the contents are a CoClass specification AddFileToProject() Adds to the project with default build settings AddImportFile(, ) Inserts an import statement line to , with appended as the import specifier; inserts after any existing import statements in AddIncludeFile(, ) Inserts a #include preprocessor directive to , with specifying the text following "#include"; inserts after any existing #include directives in AddInterfaceToIDL(, ) Adds contents of to , assuming that the contents are an Interface specification AddRegistryToRC(, ) Adds into the resources as type REGISTRY with the ID AddResourceFromFile(, , ) Adds contents of to the project resource (.RC) file as resource type with ID AddStringResource(, ) Adds a string resource with ID to the project resource (.RC) file; specifies the string's value AddStringToSymbol(, , ) Sets in the result of appending to AddSymbolToString(, ) Sets in the result of appending to AddToObjectMap(, ) Associates with in the project's object map CopyFile(, ) Copies existing to a new DeleteFile() Deletes Dialog([, [, ...]]) Displays property page dialogs to make symbol settings; the control script uses the symbols to customize templates for the object being inserted. Each is the ProgID of a registered property page, up to a maximum of 9 pages per directive. Please refer to the section on property pages for information about registering property pages and communicating with the wizard from the property page. DoubleSlash() Adds a '\' after each existing '\' in GetTemporaryFileName() Creates a temporary file and sets its name in include(