Article ID: 179385 - Last Review: August 18, 2005 - Revision: 3.1 How to add custom ATL objects to the ATL Object wizard in Visual C++This article was previously published under Q179385 Important This article contains information about how to modify the registry. Make sure to back up the registry before you modify it. Make sure that you know how to restore the registry if a problem occurs. For more information about how to back up, restore, and modify the registry, click the following article number to view the article in the Microsoft Knowledge Base: 256986
(http://support.microsoft.com/kb/256986/
)
Description of the Microsoft Windows registry On This PageSUMMARY 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: <Visual Studio Path>\Common\MsDev98\Template\Atl. 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:
Note In Visual C++ 5.0, the base directory for folders referenced herein is <DevStudio path>\SharedIde; in version 6.0 it is <Visual Studio Path>\Common\MsDev98. Create property pagesProperty 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:
Sample code
Create a custom ATL object templateAn 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:[!<symbol>] or [!<directive>] 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(<SYMBOL>) If <SYMBOL> exists in Wizard's symbol map, uses following
directives and output; value of the symbol is irrelevant
if!(<SYMBOL>) If <SYMBOL> does not exist in Wizard's symbol map, uses
following directives and output; symbol value is ignored
if=(<SYMBOL>, <value>)
If <SYMBOL> exists and its setting matches <value>
exactly, uses following directives and output
if!=(<SYMBOL>, <value>)
If <SYMBOL> does not exist or its setting does not match
<value> 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, <SYMBOL> denotes a symbol name and <value> denotes text
enclosed in double-quotes.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) fileThe 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:[!<directive>] 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 filesThis 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(<IDLFILE>, <FILENAME>)
Adds contents of <FILENAME> to <IDLFILE>, assuming that
the contents are a CoClass specification
AddFileToProject(<FILENAME>)
Adds <FILENAME> to the project with default build
settings
AddImportFile(<IDLFILE>, <value>)
Inserts an import statement line to <IDLFILE>, with
<value> appended as the import specifier; inserts after
any existing import statements in <IDLFILE>
AddIncludeFile(<FILENAME>, <DIRECTIVE>)
Inserts a #include preprocessor directive to <FILENAME>,
with <DIRECTIVE> specifying the text following
"#include"; inserts after any existing #include
directives in <FILENAME>
AddInterfaceToIDL(<IDLFILE>, <FILENAME>)
Adds contents of <FILENAME> to <IDLFILE>, assuming that
the contents are an Interface specification
AddRegistryToRC(<RGSFILE>, <RESOURCE_ID>)
Adds <RGSFILE> into the resources as type REGISTRY with
the ID <RESOURCE_ID>
AddResourceFromFile(<FILENAME>, <RESOURCE_ID>, <RESOURCETYPE>)
Adds contents of <FILENAME> to the project resource (.RC)
file as resource type <RESOURCETYPE> with ID
<RESOURCE_ID>
AddStringResource(<STRING_ID>, <SYMBOL>)
Adds a string resource with ID <STRING_ID> to the project
resource (.RC) file; <SYMBOL> specifies the string's
value
AddStringToSymbol(<SYMBOL1>, <SYMBOL2>, <value>)
Sets in <SYMBOL1> the result of appending <value> to
<SYMBOL2>
AddSymbolToString(<SYMBOL>, <value>)
Sets in <SYMBOL> the result of appending <value> to
<SYMBOL>
AddToObjectMap(<COCLASSNAME>, <CLASSNAME>)
Associates <COCLASSNAME> with <CLASSNAME> in the
project's object map
CopyFile(<FILENAME1>, <FILENAME2>)
Copies existing <FILENAME1> to a new <FILENAME2>
DeleteFile(<FILENAME>)
Deletes <FILENAME>
Dialog(<dialog1_progid>[, <dialog2_progid>[, ...]])
Displays property page dialogs to make symbol settings;
the control script uses the symbols to customize
templates for the object being inserted. Each
<dialogX_progid> 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(<SYMBOL>)
Adds a '\' after each existing '\' in <SYMBOL>
GetTemporaryFileName(<FILENAME>)
Creates a temporary file and sets its name in <FILENAME>
include(<TEMPLATE>)
Processes template file <TEMPLATE>; output goes to the
file specified in a previous [!target(<FILENAME>)]
newguid(<SYMBOL>)
Sets <SYMBOL> to a newly created GUID
set(<SYMBOL>, <value>)
Sets <SYMBOL> to <value>; creates <SYMBOL> if it doesn't
already exist
strcpy(<SYMBOL1>, <SYMBOL2>)
Copies the string <SYMBOL2> to <SYMBOL1>
target(<FILENAME>)
Opens <FILENAME> as the current output file; follow with
[!include(...)] directives or literal text to send to
output file
target() Closes the output file; output to file now halted
tolower(<SYMBOL>)
Converts <SYMBOL> to lowercase
toupper(<SYMBOL>)
Converts <SYMBOL> to uppercase
* In this table, uppercase names enclosed in <> (e.g. <SYMBOL>) denotes
a symbol name; lowercase names enclosed in <> (e.g. <value>) denotes
text enclosed in double-quotes.Register the custom ATL Object with the ATL Object WizardWarning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall your operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.Under the registry key: HKEY_LOCAL_MACHINE\Software\Microsoft\DevStudio\ATLWizard\
{6E871954-50AD-11D0-883E-080000185165}Value Name Value Data ---------------------------------------- Category REG_SZ "<Category>" Control REG_SZ "<Control File Name>" Icon REG_SZ "<Icon File Name>" Name REG_SZ "<Object Name>"
ISymbolMap interface definition for C/C++Save the following code into a header file named "SymMap.h" and "#include" it with custom property page source files:Sample codeREFERENCES Visual C++ Books Online: Developer Products; Visual C++;
C/C++ Language and C++ Libraries; Active Template Library; Articles; Creating
an ATL Project Visual C++ Books Online: Developer Products; Visual C++; C/C++ Language and C++ Libraries; Active Template Library; Articles; Creating an ATL Project Adding; Objects and Controls Visual C++ Books Online: Platform, SDK and DDK Documentation; Platform SDK; COM and ActiveX Object Services; COM; Reference; Interfaces; IPropertyPage Visual C++ Books Online: Developer Products; Visual C++; C/C++ Language and C++ Libraries; Active Template Library; Articles; The ATL Registry Component (Registrar); Creating Registrar Scripts APPLIES TO
| Article Translations
|
Back to the top
