Help for Macros in CommonMacros.inc

diff -r 000000000000 -r fb279309251b uidesigner/com.nokia.sdt.series60.componentlibrary/components/CommonMacros.inc.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uidesigner/com.nokia.sdt.series60.componentlibrary/components/CommonMacros.inc.html Fri Apr 03 23:33:03 2009 +0100 @@ -0,0 +1,1393 @@ + + + +Help for Macros in CommonMacros.inc + + +

+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 + +
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 + +

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 + +

+ + +

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 + +

+ + +

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 + +
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 + +

+ + +

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 + +
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 + +

+ +

Table of contents

DeclareMethod

Arguments

GenerateDefaultFunctionBody

Arguments

DefineMethod

Arguments

GenerateMethod

Arguments

DefineMethodWithOwnedBody

Arguments

GenerateMethodWithOwnedBody

Arguments

GenerateMethodWithVariantArguments

Arguments

GenerateVirtualMethodOverrideForEventHandler

Arguments

GenerateUserEventHandlerFunction

Arguments