Help for Macros in FileAndClassMacros.inc

# Table of contents

SourceFileTemplate

HeaderFileTemplate

ClassTemplate

AddCppIncludes

ResolvePhases

## SourceFileTemplate

Defines the basic structure for a source file. This defines a file with system includes, user includes, and constants.

### Arguments

Argument | Req'd? | Default | Description
Dir | no | ${src} | Project-relative directory for file
FileName | no | ${instanceName$title}.cpp | Filename, inside $(Dir), to create
HeaderFileName | no | ${instanceName$title}.h | Filename of associated header to #include, or blank for no #include
LocationPrefix | no | SOURCE | String which is prefixed to the location ids defined by this macro.
InitialFileHeadContent | no |  | optional stock text for the source file (before system includes, user includes, constants). NOTE: one-time text, should not depend on modifiable properties NOTE: does not need to specify default source file template (comments), which is automatic.
RealizeSystemIncludes | no | true | flag that can be used to avoid generating the system includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no system includes ever defined, otherwise, the section will appear out of order when generated.
SystemIncludesRegionName | no | Generated System Includes | name of the generated section for system includes
InitialSystemIncludesContent | no |  | optional stock text for the system includes
RealizeUserIncludes | no | true | flag that can be used to avoid generating the user includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no user includes ever defined, otherwise, the section will appear out of order when generated.
UserIncludesRegionName | no | Generated User Includes | name of the generated section for user includes
InitialUserIncludesContent | no |  | optional stock text for the user includes
RealizeConstants | no | true | flag that can be used to avoid generating the constants section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no constants ever defined, otherwise, the section will appear out of order when generated.
ConstantsRegionName | no | Generated Constants | name of the generated section for constants
InitialConstantsContent | no |  | optional stock text for the constants
InitialFileTailContent | no |  | optional stock text for the source file (after system includes, user includes, constants) which appears at the very end of the file. NOTE: one-time text, should not depend on modifiable properties NOTE: this really comes at the very end during initial file generation (unless you emit other templates with mode="at-end"), so if you simply want content after these sections but before other templates you add, just create templates for location="$(LocationPrefix)_FILE".
Dir | no | ${src} | Project-relative directory for file
FileName | no | ${instanceName$title}.cpp | Filename, inside $(Dir), to create
HeaderFileName | no | ${instanceName$title}.h | Filename of associated header to #include, or blank for no #include
LocationPrefix | no | SOURCE | String which is prefixed to the location ids defined by this macro.
InitialFileHeadContent | no |  | optional stock text for the source file (before system includes, user includes, constants). NOTE: one-time text, should not depend on modifiable properties NOTE: does not need to specify default source file template (comments), which is automatic.
RealizeSystemIncludes | no | true | flag that can be used to avoid generating the system includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no system includes ever defined, otherwise, the section will appear out of order when generated.
SystemIncludesRegionName | no | Generated System Includes | name of the generated section for system includes
InitialSystemIncludesContent | no |  | optional stock text for the system includes
RealizeUserIncludes | no | true | flag that can be used to avoid generating the user includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no user includes ever defined, otherwise, the section will appear out of order when generated.
UserIncludesRegionName | no | Generated User Includes | name of the generated section for user includes
InitialUserIncludesContent | no |  | optional stock text for the user includes
RealizeConstants | no | true | flag that can be used to avoid generating the constants section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no constants ever defined, otherwise, the section will appear out of order when generated.
ConstantsRegionName | no | Generated Constants | name of the generated section for constants
InitialConstantsContent | no |  | optional stock text for the constants
InitialFileTailContent | no |  | optional stock text for the source file (after system includes, user includes, constants) which appears at the very end of the file. NOTE: one-time text, should not depend on modifiable properties NOTE: this really comes at the very end during initial file generation (unless you emit other templates with mode="at-end"), so if you simply want content after these sections but before other templates you add, just create templates for location="$(LocationPrefix)_FILE".

## HeaderFileTemplate

Defines the basic structure for a header file.

This defines a file with an include guard, system includes, user includes, event handler includes (non-owned but modifiable), constants, and forward declarations.

### Arguments

Argument | Req'd? | Default | Description
Dir | no | ${inc} | Project-relative directory for file
FileName | no | ${instanceName$title}.h | Filename, inside $(Dir), to create
IncludeGuardMacro | no | ${instanceName$upper}_H | Include guard macro (#ifndef ...) to use
LocationPrefix | no | HEADER | String which is prefixed to the location ids defined by this macro.
InitialFileHeadContent | no |  | optional stock text for the top of the header file. NOTE: one-time text, should not depend on modifiable properties NOTE: does not need to specify header file template (comments) or #ifdef guards.
RealizeEventHandlerIncludes | no | true | flag that can be used to avoid generating the section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no event handler includes ever defined, otherwise, the section will appear out of order when generated.
InitialEventHandlerIncludesContent | no |  | optional stock text for the event handler includes. NOTE: one-time text, should not depend on modifiable properties
RealizeOwnedSystemIncludes | no | true | flag that can be used to avoid generating the system includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no system includes ever defined, otherwise, the section will appear out of order when generated.
OwnedSystemIncludesRegionName | no | Generated System Includes | name of the generated section for system includes
RealizeOwnedUserIncludes | no | true | flag that can be used to avoid generating the user includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no user includes ever defined, otherwise, the section will appear out of order when generated.
OwnedUserIncludesRegionName | no | Generated User Includes | name of the generated section for user includes
InitialOwnedSystemIncludesContent | no |  | optional stock text for the added system includes
InitialOwnedUserIncludesContent | no |  | optional stock text for the user includes.
RealizeOwnedConstants | no | true | flag that can be used to avoid generating the constants section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no constants ever defined, otherwise, the section will appear out of order when generated.
InitialOwnedConstantsContent | no |  | optional stock text for the constants
RealizeOwnedForwardDeclarations | no | true | flag that can be used to avoid generating the forward declarations section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no forward decls ever defined, otherwise, the section will appear out of order when generated.
InitialOwnedForwardDeclarationsContent | no |  | optional stock text for the forward declarations
RealizeOwnedTypedefs | no | true | flag that can be used to avoid generating the typedefs section unless it is used. NOTE: due to issues with the source generator, this should't be set 'false' unless you really expect there to be no typedefs ever defined, otherwise, the section will appear out of order when generated.
OwnedTypedefsRegionName | no | Generated Typedefs | name of the generated section for owned typedefs
InitialOwnedTypedefsContent | no |  | optional stock text for the initial typedefs
InitialFileTailContent | no |  | optional stock text for the end of the header file. NOTE: one-time text, should not depend on modifiable properties NOTE: this really comes at the very end during initial file generation (unless you emit other templates with mode="at-end"), so if you simply want content after these sections but before other templates you add, just create templates for location="$(LocationPrefix)HEADER_FILE".
Dir | no | ${inc} | Project-relative directory for file
FileName | no | ${instanceName$title}.h | Filename, inside $(Dir), to create
IncludeGuardMacro | no | ${instanceName$upper}_H | Include guard macro (#ifndef ...) to use
LocationPrefix | no | HEADER | String which is prefixed to the location ids defined by this macro.
InitialFileHeadContent | no |  | optional stock text for the top of the header file. NOTE: one-time text, should not depend on modifiable properties NOTE: does not need to specify header file template (comments) or #ifdef guards.
RealizeEventHandlerIncludes | no | true | flag that can be used to avoid generating the section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no event handler includes ever defined, otherwise, the section will appear out of order when generated.
InitialEventHandlerIncludesContent | no |  | optional stock text for the event handler includes. NOTE: one-time text, should not depend on modifiable properties
RealizeOwnedSystemIncludes | no | true | flag that can be used to avoid generating the system includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no system includes ever defined, otherwise, the section will appear out of order when generated.
OwnedSystemIncludesRegionName | no | Generated System Includes | name of the generated section for system includes
RealizeOwnedUserIncludes | no | true | flag that can be used to avoid generating the user includes section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no user includes ever defined, otherwise, the section will appear out of order when generated.
OwnedUserIncludesRegionName | no | Generated User Includes | name of the generated section for user includes
InitialOwnedSystemIncludesContent | no |  | optional stock text for the added system includes
InitialOwnedUserIncludesContent | no |  | optional stock text for the user includes.
RealizeOwnedConstants | no | true | flag that can be used to avoid generating the constants section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no constants ever defined, otherwise, the section will appear out of order when generated.
InitialOwnedConstantsContent | no |  | optional stock text for the constants
RealizeOwnedForwardDeclarations | no | true | flag that can be used to avoid generating the forward declarations section unless it is used. NOTE: due to issues with the source generator, this shouldn't be set 'false' unless you really expect there to be no forward decls ever defined, otherwise, the section will appear out of order when generated.
InitialOwnedForwardDeclarationsContent | no |  | optional stock text for the forward declarations
RealizeOwnedTypedefs | no | true | flag that can be used to avoid generating the typedefs section unless it is used. NOTE: due to issues with the source generator, this should't be set 'false' unless you really expect there to be no typedefs ever defined, otherwise, the section will appear out of order when generated.
OwnedTypedefsRegionName | no | Generated Typedefs | name of the generated section for owned typedefs
InitialOwnedTypedefsContent | no |  | optional stock text for the initial typedefs
InitialFileTailContent | no |  | optional stock text for the end of the header file. NOTE: one-time text, should not depend on modifiable properties NOTE: this really comes at the very end during initial file generation (unless you emit other templates with mode="at-end"), so if you simply want content after these sections but before other templates you add, just create templates for location="$(LocationPrefix)HEADER_FILE".

## ClassTemplate

Defines the basic structure for a class with public, protected, and private regions, with owned sections therein for common purposes.

### Arguments

Argument | Req'd? | Default | Description
BaseClassName | yes |  | name of the base class, from which this class derives
BaseClassName | yes |  | name of the base class, from which this class derives
LocationPrefix | no |  | String which is prefixed to the location ids defined by this macro. Useful when one component defines multiple files.
BaseLocation | no | HEADER_FILE | name of the base location in which to place the class, defaults to HEADER_FILE
ClassName | no | ${className} | name of the class to generate
BaseClassAccessor | no | public | accessor for the base class, from which this class derives
ExtraBaseClasses | no |  | extra interface classes, separated by commas
ClassComment | no |  | optional text for the class comment
InitialClassHeadContent | no |  | optional text for the start of the class NOTE: one-time code, should not depend on modifiable properties
InitialPublicHeadContent | no |  | optional text for the start of the public section (follows "public:") NOTE: one-time code, should not depend on modifiable properties
RealizePublicOwnedTypes | no | true | flag that can be used to avoid generating the public types section unless it is used. NOTE: if InitialPublicOwnedTypesContent is set, this flag is ignored.
InitialPublicOwnedTypesContent | no |  | optional text for the public owned types section
RealizePublicOwnedMethods | no | true | flag that can be used to avoid generating the public owned methods section unless it is used. NOTE: if InitialPublicOwnedMethodsContent is set, this flag is ignored.
InitialPublicOwnedMethodsContent | no |  | optional text for the public owned methods section
InitialPublicTailContent | no |  | optional text for the end of the public section (follows "public:") NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated public content.
InitialProtectedHeadContent | no |  | optional text for the start of the protected section (follows "protected:") NOTE: one-time code, should not depend on modifiable properties
RealizeProtectedOverriddenMethods | no | true | flag that can be used to avoid generating the protected overridden methods section unless it is used.
InitialProtectedOverriddenMethodsContent | no |  | optional text for the the protected overridden methods section
RealizeProtectedUserHandlers | no | true | flag that can be used to avoid generating the protected user handlers section unless it is used. This is used for the prototypes for the user-editable event handler methods.
InitialProtectedUserHandlersContent | no |  | optional text for the protected user handlers section
InitialProtectedTailContent | no |  | optional text for the end of the protected section NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated protected content.
InitialPrivateHeadContent | no |  | optional text for the start of the private section (follows "private:") NOTE: one-time code, should not depend on modifiable properties
RealizePrivateOwnedTypes | no | true | flag that can be used to avoid generating the private owned types section unless it is used. NOTE: if InitialPrivateOwnedTypesContent is set, this flag is ignored.
InitialPrivateOwnedTypesContent | no |  | optional text for the the private types section
RealizePrivateOwnedInstanceVariables | no | true | flag that can be used to avoid generating the private instance variables section unless it is used.
InitialPrivateOwnedInstanceVariablesContent | no |  | optional text for the the private instance variables section
RealizePrivateOwnedMethods | no | true | flag that can be used to avoid generating the private owned methods section unless it is used.
InitialPrivateOwnedMethodsContent | no |  | optional text for the the private methods section
InitialPrivateTailContent | no |  | optional text for the end of the private section NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated private content.
InitialClassTailContent | no |  | optional text for the end of the class NOTE: one-time code, should not depend on modifiable properties
LocationPrefix | no |  | String which is prefixed to the location ids defined by this macro. Useful when one component defines multiple files.
BaseLocation | no | HEADER_FILE | name of the base location in which to place the class, defaults to HEADER_FILE
ClassName | no | ${className} | name of the class to generate
BaseClassAccessor | no | public | accessor for the base class, from which this class derives
ExtraBaseClasses | no |  | extra interface classes, separated by commas
ClassComment | no |  | optional text for the class comment
InitialClassHeadContent | no |  | optional text for the start of the class NOTE: one-time code, should not depend on modifiable properties
InitialPublicHeadContent | no |  | optional text for the start of the public section (follows "public:") NOTE: one-time code, should not depend on modifiable properties
RealizePublicOwnedTypes | no | true | flag that can be used to avoid generating the public types section unless it is used. NOTE: if InitialPublicOwnedTypesContent is set, this flag is ignored.
InitialPublicOwnedTypesContent | no |  | optional text for the public owned types section
RealizePublicOwnedMethods | no | true | flag that can be used to avoid generating the public owned methods section unless it is used. NOTE: if InitialPublicOwnedMethodsContent is set, this flag is ignored.
InitialPublicOwnedMethodsContent | no |  | optional text for the public owned methods section
InitialPublicTailContent | no |  | optional text for the end of the public section (follows "public:") NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated public content.
InitialProtectedHeadContent | no |  | optional text for the start of the protected section (follows "protected:") NOTE: one-time code, should not depend on modifiable properties
RealizeProtectedOverriddenMethods | no | true | flag that can be used to avoid generating the protected overridden methods section unless it is used.
InitialProtectedOverriddenMethodsContent | no |  | optional text for the the protected overridden methods section
RealizeProtectedUserHandlers | no | true | flag that can be used to avoid generating the protected user handlers section unless it is used. This is used for the prototypes for the user-editable event handler methods.
InitialProtectedUserHandlersContent | no |  | optional text for the protected user handlers section
InitialProtectedTailContent | no |  | optional text for the end of the protected section NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated protected content.
InitialPrivateHeadContent | no |  | optional text for the start of the private section (follows "private:") NOTE: one-time code, should not depend on modifiable properties
RealizePrivateOwnedTypes | no | true | flag that can be used to avoid generating the private owned types section unless it is used. NOTE: if InitialPrivateOwnedTypesContent is set, this flag is ignored.
InitialPrivateOwnedTypesContent | no |  | optional text for the the private types section
RealizePrivateOwnedInstanceVariables | no | true | flag that can be used to avoid generating the private instance variables section unless it is used.
InitialPrivateOwnedInstanceVariablesContent | no |  | optional text for the the private instance variables section
RealizePrivateOwnedMethods | no | true | flag that can be used to avoid generating the private owned methods section unless it is used.
InitialPrivateOwnedMethodsContent | no |  | optional text for the the private methods section
InitialPrivateTailContent | no |  | optional text for the end of the private section NOTE: one-time code, should not depend on modifiable properties NOTE: content appears at the end of all initially generated private content.
InitialClassTailContent | no |  | optional text for the end of the class NOTE: one-time code, should not depend on modifiable properties

## AddCppIncludes

Generate #includes for a space-separated list of headers.

Note: you cannot use variable substitution, script escapes, etc. in the list. Instead, just write explicit contributions for the include, e.g. <template location="MAIN_OWNED_SYSTEM_INCLUDES"> ...

### Arguments

Argument | Req'd? | Default | Description
Headers | yes |  | a space-separated list of header files
Headers | yes |  | a space-separated list of header files
Location | no |  | location where includes should go (either this or Phase should be set)
Phase | no |  | phase where includes should go (either this or Location should be set)
IsUser | no | false | "User" or <system> includes?
Location | no |  | location where includes should go (either this or Phase should be set)
Phase | no |  | phase where includes should go (either this or Location should be set)
IsUser | no | false | "User" or <system> includes?

## ResolvePhases

This macro fixes up phase -> location mappings on the current contributions, or optionally, another list.

The mappings are Phase=Location pairs separated by spaces.

This may be called multiple times.

### Arguments

Argument | Req'd? | Default | Description
Mappings | yes |  | A space-separated list of Phase=Location mappings.
Mappings | yes |  | A space-separated list of Phase=Location mappings.
ContribsList | no | contribs | The array or list of IContribution upon which to apply the fixups.
ContribsList | no | contribs | The array or list of IContribution upon which to apply the fixups.