Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

Template Files

Several types of template files go into creating a new AppWizard. These include the special template files newproj.inf and confirm.inf, which play a key role in the creation of a new project, as well as text templates and custom resource templates, which make up the building blocks of the new application.

The newproj.inf Template File

Your AppWizard uses the newproj.inf template file to control how the files of a new project are created from the template files contained in your AppWizard project. This file contains a set of statements that govern how a new project is created, as well as additional directives that can be used for controlling the processing of the file. Here is an example of newproj.inf that was created by the custom AppWizard from an existing project:

$$// newproj.inf = template for list of template files
$$//  format is 'sourceResName'\t 'destFileName'
$$//    The source res name may be preceded by any combination
$$//          of '=', '-',  '!', '?', ':', '#', and/or '*'
$$//       '=' => the resource is binary
$$//       '-' => the file should not be added to the project
$$//                (all files are added to the project by default)
$$//       '!' => the file should be marked exclude from build
$$//       '?' => the file should be treated as a help file
$$//       ':' => the file should be treated as a resource
$$//       '#' => the file should be treated as a template (implies '!')
$$//       '*' => bypass the custom AppWizard's resources when loading
$$//                 if name starts with / => create new subdir

/res

ROOT.CLW    $$root$$.clw
README.TXT  ReadMe.txt
ROOT.H      $$root$$.h
ROOT.CPP    $$root$$.cpp
DIALOG.H    $$root$$Dlg.h
DIALOG.CPP  $$root$$Dlg.cpp
STDAFX.H    StdAfx.h
STDAFX.CPP  StdAfx.cpp
:ROOT.RC2   res\$$root$$.rc2
=:ROOT.ICO  res\$$root$$.ico
RESOURCE.H  resource.h
ROOT.RC     $$root$$.rc

Statements in newproj.inf

The newproj.inf file includes several types of statements. These are comments, directory-creation statements, and file-creation statements.

You can add comments to the file by beginning a line with $$//. Any text on the remainder of the line is ignored and is used only for readability. The comment characters must be on the very beginning of the line. If you begin a line with one of the other directives, however, you can add a comment to the end of the line simply by adding // before the comment text.

You can have the AppWizard create a new subdirectory of the new project simply by adding the new directory name to a line in newproj.inf, as in this line from the preceding code example:

/res

The remainder of the statements in the example are used to create files in the new project, based on the templates contained in your AppWizard project. These statements consist of the name of the source template to be used and the destination for the new file. Take the following statement, for example:

README.TXT  ReadMe.txt

This statement takes the template named README.TXT and processes it, writing the output to a new file named ReadMe.txt in the new project. You also may use macros in the names of the destination files, as in the following line:

ROOT.CPP  $$root$$.cpp

This code creates a new file with a name based on the $$root$$ macro, which resolves to the name of the project. You will look at the other macros that are available, and how they are used, in the next section.

You also may add one or more of several modifiers to the beginning of a line containing a file-creation statement. These modifiers are listed in the opening comments of the newproj.inf file and are described further in Table 18.1.

Table 18.1. Template Name Modifiers

Modifier Description
= Copies the template verbatim, without any processing. Generally is used for binary resources, such as .ico or .bmp files.
+ Adds the file to the makefile for the project. Used for source files, such as .CPP or .ODL files.
* Tells AppWizard to use a standard AppWizard template instead of a custom template specific to your custom AppWizard. In most cases, you won't need this modifier, because if your AppWizard doesn't find a template in your custom AppWizard directory, it tries to grab a standard template.
- Does not add the file to the project, although it does copy it to the project directory.
! Marks the file to be excluded from the build.
? Handles the file as a Help file and adds it to the Help Files folder of the new project.
: Treats the file as a resource file and adds it to the Resource Files folder of the new project.
# Treats the file as a template and adds it to the Template Files folder of the new project.

Macros in Template Files

Earlier, you saw a little coverage on the use of macros, such as $$root$$, in template files. You use macros to represent variable values in your template files. In general, these macros are set based on the user's selections in the AppWizard step dialog boxes. You can use two types of macros: text macros and Boolean macros. Text macros, such as the root macro, evaluate to text values that can be inserted in your templates. Boolean macros, such as those used in conditionals, simply evaluate to Boolean values.

You may use macros in the destination filenames in newproj.inf as you saw earlier by enclosing the macro name in $$, as in the following statement:

ROOT.CPP  $$root$$.cpp

Similarly, you also may use macro names in any other places in your template text by using the $$ delimiters.

You also will see that you can use macros as parameters to directives, such as conditional directives. When you use macros as parameters to directives, however, you should use them without the $$ delimiters.

You can use several standard macros in your templates. You also may define your own macros, as you will see in the following sections.

Standard Macros

You can set many standard macros by using the standard MFC AppWizard, based on the user's selections in the standard MFC AppWizard step dialog boxes. Some of the more common standard macros are discussed in this section.

The following macros are set according to the user's selections in the New Project dialog box:

In addition, many other standard macros are defined if you are using the standard MFC AppWizard steps. For more information on these macros, see the online documentation.

User-Defined Macros

In addition to the standard macros shown earlier in this chapter, your custom AppWizard can define its own macros to reflect user choices from the custom AppWizard step dialog boxes.

You define your own macros by adding an entry to your AppWizard's dictionary. The dictionary is a mapping of class CMapStringToString, which is a member variable of the CCustomappWiz class in your custom AppWizard's DLL code.

Any custom macros you add to your AppWizard's dictionary may be used in your templates, just like any of the standard macros.

Directives in Template Files

You also may include several different directives in your newproj.inf file, as well as other text template files. You use these directives mostly to control the processing of the template file, based on the user's selections in the AppWizard steps.

Conditional Directives

You may add conditional directives to your template to selectively include or exclude certain statements. You can use a simple conditional with the $$IF and $$ENDIF directives, as shown here:

$$IF(VERBOSE)
readme.txt ReadMe.txt
$$ENDIF

In the preceding example, if the VERBOSE macro is set, a ReadMe.txt file is added to the new project. Otherwise, ReadMe.txt is not created in the new project. You also may add more complex conditionals using the $$ELIF and $$ELSE directives, as in the following example:

$$IF(PROJTYPE_DLL)
dllroot.clw $$root$$.clw
$$ELIF(PROJTYPE_DLG)
dlgroot.clw $$root$$.clw
$$ELSE
root.clw    $$root$$.clw
$$ENDIF //DLG, DLL

Loops

You may repeat a block of statements a certain number of times by using the $$BEGINLOOP directive, which takes a single macro parameter that should indicate the number of times to execute the loop. The end of the loop is indicated with the $$ENDLOOP directive.

$$INCLUDE

You may include additional template files with the $$INCLUDE directive, which takes a macro parameter that should evaluate to the name of a custom template. The text from this custom template then is read into the current file, much like standard C/C++ #include processing.

The Default Language

You may create custom template files that are language-dependent by appending the three-letter code to the name of the template file, such as TEMPLATE_DEU.RC. You may tell the AppWizard to search for templates for a particular language by using the $$SET_DEFAULT_LANG directive, which specifies a macro that evaluates to a three-letter language code. This value is used when searching for template files from your own custom AppWizard directory or from the standard AppWizard templates.

The confirm.inf Template File

When the user completes the step dialog boxes for an AppWizard, the New Project Information dialog box appears, prompting for final approval to create the new project. The text your AppWizard displays in this dialog box is described in the confirm.inf template.

The confirm.inf template file can use conditional directives and text macros, as shown previously, to define the text that will be presented. The resulting text should summarize the options the user selected in the step dialog boxes. The text also can contain additional information about the project to be created, including things such as new classes.

To get a taste of what this file looks like, take a look at the portion of the confirm.inf file shown here:

$$// confirm.inf = the text emitted to the confirmation dialog for
$$//    this configuration
$$IF(PROJTYPE_DLL)
$$IF(EXTDLL)
Creating MFC Extension DLL (using a shared copy of MFC) $$Root$$.dll targeting:
$$ELSE //!EXTDLL
$$IF(MFCDLL)
Creating Regular DLL (using a shared copy of MFC) $$Root$$.dll targeting:
$$ELSE //!MFCDLL
Creating Regular DLL (using MFC statically linked) $$Root$$.dll targeting:
$$ENDIF //MFCDLL
$$ENDIF //EXTDLL
$$IF(TARGET_INTEL)
        Win32
$$ELIF(TARGET_MIPS)
        Win32 (MIPS)
$$ELIF(TARGET_ALPHA)
        Win32 (ALPHA)
$$ENDIF //INTEL&MIPS&ALPHA
$$IF(TARGET_68KMAC)
        Macintosh
$$ENDIF
$$IF(TARGET_POWERMAC)
        Power Macintosh
$$ENDIF

Main source code in: $$Root$$.h and $$Root$$.cpp
$$IF(AUTOMATION || SOCKETS)

Features:
$$IF(AUTOMATION)
   + OLE Automation support enabled
$$ENDIF
$$IF(SOCKETS)
   + Windows Sockets Support
$$ENDIF //SOCKETS
$$ENDIF //AUTOMATION || SOCKETS
…

This is just a snippet of the file created for you if you choose to begin with one of the standard MFC AppWizards. If you are creating your AppWizard project based on an existing project or based on your own custom steps, you will need to start from scratch when creating this template.

Text Templates

Your custom AppWizard uses text templates to provide the basis for creating text files in the new projects it creates. These templates are used for any type of text files, including .cpp or .h source code files, as well as other text file types, such as .rc, .rc2, .odl, .rtf, and even .clw.

It is perfectly acceptable to simply add a regular .cpp file as a template for a .cpp file to create in the new project. However, you might want to add to the customization done by your AppWizard by adding conditional processing or text macros within your text templates. You can use the macros and directives that you saw earlier in your text templates, as well as in .INF files.

Macros commonly are used in source code comments, as well as in the names of include files and new classes that are used, as shown in this example:

// $$root$$Dlg.cpp : implementation file
//

#include "stdafx.h"
#include "$$root$$.h"
#include "$$root$$Dlg.h"
$$IF(VERBOSE)
    // Add your source code comments in these blocks.
$$ENDIF
$$IF(OLE_INIT)
struct InitOle {
    InitOle()  { ::CoInitialize(NULL); }
    ~InitOle() { ::CoUninitialize();   }
} _init_InitOle_;
$$ENDIF

You can edit these template files in Developer Studio by double-clicking the filename in the Template Files folder in the Workspace window.

Note

For .rc files, Developer Studio tries to open the file as a resource script that points to existing resource files. These resource files will not exist in your AppWizard project, however—only in the projects it creates. Thus, you generally will see a warning box if you try to open .rc files. You can click the Edit Code button to edit the text of these files.

Binary Resource Templates

Binary resource templates are used by your custom AppWizard in creating new files that do not contain plain text, such as bitmap (.bmp) or icon (.ico) files. These template files are handled a bit differently than text templates, and because they can contain any binary data, they cannot contain the directives or macros you have seen in other templates.

Although binary resource templates are simple resource files, they are stored in your AppWizard project differently than the resources that are used to build your AppWizard DLL, such as any bitmaps used in your custom step dialog boxes.

Creating Binary Templates

To add a new binary template to your custom AppWizard project, you first need to create the file to be used. In most cases, as for icon files, you simply create a new icon in the Developer Studio's Resource Editor. After you create the file you want to use, you can add it to your project with the following steps:

  1. Copy the file to your project's Template directory.
  2. Choose Resource from the Insert menu.
  3. Select the type of resource and click Import.
  4. In the Import Resource dialog box, select the file from the Template directory, select Custom from the Open As list, and click Import.
  5. In the Resource Type dialog box, select TEMPLATE from the Resource Type list and click OK.

Your custom resource template now is added to your AppWizard project. You can edit most common resource file types from within Developer Studio simply by double- clicking the filename in the Template Files folder of the Workspace window. Of course, if you are using your own types of custom binary files, Developer Studio might not know how to edit them.

Share ThisShare This

Informit Network