Help for Macros in CommonMacros.inc

# Table of contents

DeclareMethod

GenerateDefaultFunctionBody

DefineMethod

GenerateMethod

DefineMethodWithOwnedBody

GenerateMethodWithOwnedBody

GenerateMethodWithVariantArguments

GenerateVirtualMethodOverrideForEventHandler

GenerateUserEventHandlerFunction

## DeclareMethod

Declares a method, e.g., the prototype.

### Arguments

Argument | Req'd? | Default | Description
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
ReturnType | no | void | return type for function
IsStatic | no | false | is the function static?
IsVirtual | no | false | is the function virtual? (ignored if IsStatic)
IsConst | no | false | add 'const' modifier to function?
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
ReturnType | no | void | return type for function
IsStatic | no | false | is the function static?
IsVirtual | no | false | is the function virtual? (ignored if IsStatic)
IsConst | no | false | add 'const' modifier to function?

## GenerateDefaultFunctionBody

Create the default body for a function. If FunctionBody is set, emits that. If ReturnType is not void and DefaultReturn is set, create a return statement using its value.

### Arguments

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
FunctionBody | no |  | text inside function body (comment and/or code)
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
FunctionBody | no |  | text inside function body (comment and/or code)

## DefineMethod

Defines a method to one location, optionally generating body text, or a default return statement. The generated function is owned by default.

### Arguments

Argument | Req'd? | Default | Description
DefnLocation | yes |  | name of location into which to add the function
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DefnLocation | yes |  | name of location into which to add the function
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
IsOwned | no | true | is the function body owned?
IsConst | no | false | add 'const' modifier to function?
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.
IsOwned | no | true | is the function body owned?
IsConst | no | false | add 'const' modifier to function?
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.

Inherited from GenerateDefaultFunctionBody:

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
FunctionBody | no |  | text inside function body (comment and/or code)

## GenerateMethod

Declares and defines a method to one location and adds the prototype to another location.

### Arguments

Argument | Req'd? | Default | Description

Inherited from DeclareMethod:

Argument | Req'd? | Default | Description
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
ReturnType | no | void | return type for function
IsStatic | no | false | is the function static?
IsVirtual | no | false | is the function virtual? (ignored if IsStatic)
IsConst | no | false | add 'const' modifier to function?

Inherited from DefineMethod:

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefnLocation | yes |  | name of location into which to add the function
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
FunctionBody | no |  | text inside function body (comment and/or code)
IsOwned | no | true | is the function body owned?
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.

## DefineMethodWithOwnedBody

Defines a method with an owned body section.

The generated function is not owned by default, unlike Method. There may be uses for an owned function with a named owned region, though.

Also, no default function code is generated, so the provided StartFunctionBody, FunctionBody, and EndFunctionBody must account for any return statements.

### Arguments

Argument | Req'd? | Default | Description
FunctionBody | no |  | text inside owned part of function body
OwnedRegionLocationId | no | $(FunctionLocationId)_BODY | location id for enclosed body
OwnedRegionName | no | Generated Contents | region name for enclosed body
StartFunctionBody | no |  | text inside function body (comment and/or code) before the owned section
EndFunctionBody | no |  | text inside function body (comment and/or code) after the owned section
FunctionBody | no |  | text inside owned part of function body
OwnedRegionLocationId | no | $(FunctionLocationId)_BODY | location id for enclosed body
OwnedRegionName | no | Generated Contents | region name for enclosed body
StartFunctionBody | no |  | text inside function body (comment and/or code) before the owned section
EndFunctionBody | no |  | text inside function body (comment and/or code) after the owned section

Inherited from DefineMethod:

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefnLocation | yes |  | name of location into which to add the function
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
IsOwned | no | true | is the function body owned?
IsConst | no | false | add 'const' modifier to function?
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.

## GenerateMethodWithOwnedBody

Declares and defines a method with an owned body section to one location and adds the prototype to another location.

The generated function is not owned by default, unlike Method. There may be uses for an owned function with a named owned region, though.

### Arguments

Argument | Req'd? | Default | Description

Inherited from DefineMethodWithOwnedBody:

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefnLocation | yes |  | name of location into which to add the function
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
FunctionBody | no |  | text inside owned part of function body
IsOwned | no | true | is the function body owned?
IsConst | no | false | add 'const' modifier to function?
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.
OwnedRegionLocationId | no | $(FunctionLocationId)_BODY | location id for enclosed body
OwnedRegionName | no | Generated Contents | region name for enclosed body
StartFunctionBody | no |  | text inside function body (comment and/or code) before the owned section
EndFunctionBody | no |  | text inside function body (comment and/or code) after the owned section

Inherited from DeclareMethod:

Argument | Req'd? | Default | Description
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
IsStatic | no | false | is the function static?
IsVirtual | no | false | is the function virtual? (ignored if IsStatic)

## GenerateMethodWithVariantArguments

Declares and defines an owned method with variant arguments to one location and adds the prototype to another location.

Variant arguments means design-time variable (not C varargs). The function has a non-empty list of fixed arguments followed by a non-empty list of variable arguments which are generated by a Javascript expression.

The generated function is owned by default. It doesn't make sense to use this non-owned, since this will introduce compile errors when the prototype changes and the old body remains behind.

### Arguments

Argument | Req'd? | Default | Description
FunctionArgs | yes |  | canonical leading static argument list (e.g. "const TInt& aArg, TInt aFoo = 3") Do not include a trailing comma
FunctionVarArgsAllowEmpty | yes |  | tell whether the varargs may be empty
FunctionVarArgsDeclExpr | yes |  | generator for the variable arguments as appearing in the declaration (a Javascript expression); if FunctionVarArgsAllowEmpty==false, do not generate a leading comma
FunctionVarArgsDefnExpr | yes |  | generator for the variable arguments as appearing in the definition (a Javascript expression); if FunctionVarArgsAllowEmpty==false, do not generate a leading comma
FunctionArgs | yes |  | canonical leading static argument list (e.g. "const TInt& aArg, TInt aFoo = 3") Do not include a trailing comma
FunctionVarArgsAllowEmpty | yes |  | tell whether the varargs may be empty
FunctionVarArgsDeclExpr | yes |  | generator for the variable arguments as appearing in the declaration (a Javascript expression); if FunctionVarArgsAllowEmpty==false, do not generate a leading comma
FunctionVarArgsDefnExpr | yes |  | generator for the variable arguments as appearing in the definition (a Javascript expression); if FunctionVarArgsAllowEmpty==false, do not generate a leading comma
IsOwned | no | true | tell whether the function is owned. In general, it should be, otherwise compile errors will be introduced when the method's signature changes and the old version is left behind.
IsOwned | no | true | tell whether the function is owned. In general, it should be, otherwise compile errors will be introduced when the method's signature changes and the old version is left behind.

Inherited from GenerateMethod:

Argument | Req'd? | Default | Description
FunctionName | yes |  | name of function
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefnLocation | yes |  | name of location into which to add the function
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
ReturnType | no | void | return type for function
IsStatic | no | false | is the function static?
IsVirtual | no | false | is the function virtual? (ignored if IsStatic)
IsConst | no | false | add 'const' modifier to function?
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
FunctionBody | no |  | text inside function body (comment and/or code)
ClassName | no | ${className} | the class name
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.

## GenerateVirtualMethodOverrideForEventHandler

Override a virtual method with a non-owned function with an owned body. This must be invoked in a templateGroup that has an ifEvents="..." attribute, so the 'event' variable is available.

### Arguments

Argument | Req'd? | Default | Description
ClassName | no | ${handlerClassName} | the name of the class
UserHandlerFunctionArgs | no |  | the arguments passed to the user handler function (== FunctionArgs by default)
ClassName | no | ${handlerClassName} | the name of the class
UserHandlerFunctionArgs | no |  | the arguments passed to the user handler function (== FunctionArgs by default)

Inherited from GenerateMethodWithOwnedBody:

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | name of the function location to define; body is named id+_BODY
DefnLocation | yes |  | name of location into which to add the function
FunctionName | yes |  | name of function
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
ReturnType | no | void | return type for function
FunctionBody | no |  | text inside owned part of function body
IsOwned | no | true | is the function body owned?
IsConst | no | false | add 'const' modifier to function?
FunctionComment | no |  | comment appearing before function defn
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.
OwnedRegionLocationId | no | $(FunctionLocationId)_BODY | location id for enclosed body
OwnedRegionName | no | Generated Contents | region name for enclosed body
StartFunctionBody | no |  | text inside function body (comment and/or code) before the owned section
EndFunctionBody | no |  | text inside function body (comment and/or code) after the owned section
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)

## GenerateUserEventHandlerFunction

Define a user handler declaration and function.

Provides a default header comment and body comment.

This is NOT conditional, so include it in a <templateGroup ifEvents="..." />

### Arguments

Argument | Req'd? | Default | Description
FunctionLocationId | yes |  | the id for the event handler function
FunctionLocationId | yes |  | the id for the event handler function
FunctionName | no | ${event.handlerName} | the name of the function/method for the handler; generally the default should be used (the name specified in the Events view)
FunctionBody | no |  | the body of the function, which by default is a TODO comment
ClassName | no | ${handlerClassName} | the name of the class that receives the handler
FunctionComment | no |  | the comment for the function
FunctionName | no | ${event.handlerName} | the name of the function/method for the handler; generally the default should be used (the name specified in the Events view)
FunctionBody | no |  | the body of the function, which by default is a TODO comment
ClassName | no | ${handlerClassName} | the name of the class that receives the handler
FunctionComment | no |  | the comment for the function

Inherited from GenerateMethod:

Argument | Req'd? | Default | Description
FunctionArgs | yes |  | canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
DefnLocation | yes |  | name of location into which to add the function
DeclLocation | no |  | name of location into which to add the prototype (either this or DeclPhase must be defined)
DeclPhase | no |  | name of phase into which to add the prototype (either this or DeclLocation must be defined)
ReturnType | no | void | return type for function
IsConst | no | false | add 'const' modifier to function?
DefaultReturn | no |  | default value to return; overridden if FunctionBody is specified
IsOwned | no | true | is the function body owned?
IsEventHandler | no | false | is the function body the user event handler?
Initializers | no |  | provide any initializer expressions, e.g. for constructors, appearing on a separate line after the argument list and before the function body. Do not provide the leading colon (':') as this is added automatically
Realize | no | false | If true, force the function to be generated. Otherwise, the function is generated only if the FunctionBody is non-empty or if another template contributions to the FunctionLocationId.