--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/uidesigner/com.nokia.sdt.series60.componentlibrary/components/CommonMacros.inc Fri Apr 03 23:33:03 2009 +0100
@@ -0,0 +1,361 @@
+<defineMacro id="DeclareMethod"
+ help="Declares a method, e.g., the prototype.">
+
+ <macroArgument name="DeclLocation" optional="true" default=""
+ help="name of location into which to add the prototype (either this or DeclPhase must be defined)" />
+
+ <macroArgument name="DeclPhase" optional="true" default=""
+ help="name of phase into which to add the prototype (either this or DeclLocation must be defined)" />
+
+ <macroArgument name="FunctionName"
+ help="name of function" />
+
+ <macroArgument name="FunctionArgs"
+ help="canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")"/>
+
+ <macroArgument name="ReturnType" optional="true" default="void"
+ help="return type for function" />
+
+ <macroArgument name="IsStatic" optional="true" default="false"
+ help="is the function static?" />
+
+ <macroArgument name="IsVirtual" optional="true" default="false"
+ help="is the function virtual? (ignored if IsStatic)" />
+
+ <macroArgument name="IsConst" optional="true" default="false"
+ help="add 'const' modifier to function?" />
+
+ <!-- N.B.: only one of location or phase will be non-empty -->
+ <template location="$(DeclLocation)" phase="$(DeclPhase)" >
+${($(IsStatic) ? "static " : ($(IsVirtual) ? "virtual " : "")
+)}$(ReturnType::append-space-unless-empty)$(FunctionName)($(FunctionArgs::as-function-declaration-args::split-and-indent::add-spaces-unless-empty))${($(IsConst) ? " const" : "")};
+ </template>
+</defineMacro>
+
+<defineMacro id="GenerateDefaultFunctionBody"
+ help="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." >
+
+ <macroArgument name="FunctionLocationId"
+ help="name of the function location to define; body is named id+_BODY" />
+
+ <macroArgument name="DefaultReturn" optional="true"
+ help="default value to return; overridden if FunctionBody is specified" />
+
+ <macroArgument name="ReturnType" optional="true" default="void"
+ help="return type for function" />
+
+ <macroArgument name="FunctionBody" optional="true" default=""
+ help="text inside function body (comment and/or code)" />
+
+ <template location="$(FunctionLocationId)"><![CDATA[<%
+if ($(FunctionBody::is-defined)) {
+%>$(FunctionBody)<% }
+if ($(DefaultReturn::is-defined) && $(ReturnType::as-string) != "void" && $(ReturnType::as-string) != "") {
+%>return $(DefaultReturn);
+<% } %>]]></template>
+
+</defineMacro>
+
+
+<defineMacro id="DefineMethod"
+ help="Defines a method to one location, optionally generating body text,
+or a default return statement.
+The generated function is owned by default." >
+
+ <importArguments macroName="GenerateDefaultFunctionBody" />
+
+ <macroArgument name="IsOwned" optional="true" default="true"
+ help="is the function body owned?" />
+
+ <macroArgument name="DefnLocation"
+ help="name of location into which to add the function" />
+
+ <macroArgument name="FunctionName"
+ help="name of function" />
+
+ <macroArgument name="FunctionArgs"
+ help="canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")"/>
+
+ <macroArgument name="IsConst" optional="true" default="false"
+ help="add 'const' modifier to function?" />
+
+ <macroArgument name="ClassName" optional="true" default="${className}"
+ help="the class name" />
+
+ <macroArgument name="FunctionComment" optional="true"
+ help="comment appearing before function defn" />
+
+ <macroArgument name="IsEventHandler" optional="true" default="false"
+ help="is the function body the user event handler?" />
+
+ <macroArgument name="Initializers" optional="true" default=""
+ help="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" />
+
+ <macroArgument name="Realize" optional="true" default="false"
+ help="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." />
+
+ <defineLocation id="$(FunctionLocationId)"
+ baseLocation="$(DefnLocation)"
+ owned="$(IsOwned)"
+ isEventHandler="$(IsEventHandler)"
+ realize="$(Realize)"
+ location="function($(ClassName)::$(FunctionName)($(FunctionArgs::as-function-location-args)))">
+ <template><![CDATA[<%
+if ($(FunctionComment::is-defined)) {
+%>$(FunctionComment)<% }
+%>$(ReturnType::append-space-unless-empty)$(ClassName)::$(FunctionName)($(FunctionArgs::as-function-definition-args::split-and-indent::add-spaces-unless-empty))${($(IsConst) ? " const" : "")}<%
+if ($(Initializers::as-string) != "") {
+%>
+ : $(Initializers)<% } %>
+ {
+ }
+]]>
+ </template>
+ </defineLocation>
+
+ <expandMacro name="GenerateDefaultFunctionBody" />
+
+</defineMacro>
+
+
+
+<defineMacro id="GenerateMethod"
+ help="Declares and defines a method to one location
+and adds the prototype to another location." >
+
+ <importArguments macroName="DeclareMethod" />
+
+ <importArguments macroName="DefineMethod" />
+
+ <expandMacro name="DeclareMethod" />
+
+ <expandMacro name="DefineMethod" />
+
+</defineMacro>
+
+<defineMacro id="DefineMethodWithOwnedBody"
+ help="Defines a method with an owned body section.
+$p$
+The generated function is not owned by default, unlike Method.
+There may be uses for an owned function with a named owned region, though.
+$p$
+Also, no default function code is generated, so the provided
+StartFunctionBody, FunctionBody, and EndFunctionBody must account for
+any return statements." >
+
+ <importArguments macroName="DefineMethod" />
+
+ <macroArgument name="OwnedRegionLocationId" optional="true" default="$(FunctionLocationId)_BODY"
+ help="location id for enclosed body" />
+
+ <macroArgument name="OwnedRegionName" optional="true" default="Generated Contents"
+ help="region name for enclosed body" />
+
+ <macroArgument name="StartFunctionBody" optional="true" default=""
+ help="text inside function body (comment and/or code) before the owned section" />
+
+ <macroArgument name="FunctionBody" optional="true" default=""
+ help="text inside owned part of function body" />
+
+ <macroArgument name="EndFunctionBody" optional="true" default=""
+ help="text inside function body (comment and/or code) after the owned section" />
+
+ <expandMacro name="DefineMethod"
+ dontPassArguments="DefaultReturn FunctionBody"
+ help="make a method first: does not pass DefaultReturn
+ since either FunctionBody or EndFunctionBody should be
+ handling the return"
+ />
+
+ <template location="$(FunctionLocationId)">$(StartFunctionBody)
+ </template>
+
+ <defineLocation id="$(OwnedRegionLocationId)" baseLocation="$(FunctionLocationId)"
+ location="region($(OwnedRegionName))" realize="true">
+ <template>$(FunctionBody)
+ </template>
+ </defineLocation>
+
+ <template location="$(FunctionLocationId)">$(EndFunctionBody)
+ </template>
+
+</defineMacro>
+
+<defineMacro id="GenerateMethodWithOwnedBody"
+ help="Declares and defines a method with an owned body section to one location
+and adds the prototype to another location.
+$p$
+The generated function is not owned by default, unlike Method.
+There may be uses for an owned function with a named owned region, though.">
+
+ <importArguments macroName="DefineMethodWithOwnedBody" />
+
+ <importArguments macroName="DeclareMethod" />
+
+ <expandMacro name="DeclareMethod" />
+
+ <expandMacro name="DefineMethodWithOwnedBody" />
+
+</defineMacro>
+
+<defineMacro id="GenerateMethodWithVariantArguments"
+ help="
+Declares and defines an owned method with variant arguments to one location
+and adds the prototype to another location.
+$p$
+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.
+$p$
+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.
+ ">
+ <importArguments macroName="GenerateMethod"
+ exceptArguments="FunctionArgs IsOwned"
+
+ help="use all the same arguments from Method,
+ excluding FunctionArgs, whose semantics are different,
+ and IsOwned, which changes defaults"/>
+
+ <macroArgument name="IsOwned" optional="true" default="true"
+ help="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." />
+
+ <macroArgument name="FunctionArgs"
+ help="canonical leading static argument list (e.g. "const TInt& aArg, TInt aFoo = 3")
+ Do not include a trailing comma" />
+
+ <macroArgument name="FunctionVarArgsAllowEmpty" optional="false"
+ help="tell whether the varargs may be empty"/>
+
+ <macroArgument name="FunctionVarArgsDeclExpr"
+ help="generator for the variable arguments as appearing in the declaration
+ (a Javascript expression);
+ if FunctionVarArgsAllowEmpty==false, do not generate a leading comma"/>
+
+ <macroArgument name="FunctionVarArgsDefnExpr"
+ help="generator for the variable arguments as appearing in the definition
+ (a Javascript expression);
+ if FunctionVarArgsAllowEmpty==false, do not generate a leading comma" />
+
+ <!-- make a method declaration first -->
+ <template location="$(DeclLocation)" phase="$(DeclPhase)" >
+${($(IsStatic) ? "static " : ($(IsVirtual) ? "virtual " : "")
+)}$(ReturnType::append-space-unless-empty)$(FunctionName)( $(FunctionArgs::as-function-declaration-args::split-and-indent)${($(FunctionVarArgsAllowEmpty) ? "" : ", ")}${$(FunctionVarArgsDefnExpr::split-and-indent)} )${($(IsConst) ? " const" : "")};
+ </template>
+
+ <!-- now define the function -->
+ <defineLocation id="$(FunctionLocationId)"
+ baseLocation="$(DefnLocation)"
+ owned="$(IsOwned)"
+ location="function($(ClassName)::$(FunctionName)($(FunctionArgs::as-function-location-args),...))">
+ <template><![CDATA[<%
+if ($(FunctionComment::is-defined)) {
+%>$(FunctionComment)<% }
+%>$(ReturnType::append-space-unless-empty)$(ClassName)::$(FunctionName)( $(FunctionArgs::as-function-definition-args::split-and-indent)${($(FunctionVarArgsAllowEmpty) ? "" : ", ")}${$(FunctionVarArgsDefnExpr::split-and-indent)} )${($(IsConst) ? " const" : "")}
+ {
+ }
+]]>
+ </template>
+ </defineLocation>
+
+ <!-- and define the body -->
+ <expandMacro name="GenerateDefaultFunctionBody" />
+
+</defineMacro>
+
+<defineMacro id="GenerateVirtualMethodOverrideForEventHandler"
+ help="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. ">
+ <importArguments macroName="GenerateMethodWithOwnedBody"
+ exceptArguments="IsVirtual IsStatic" />
+
+ <macroArgument name="ClassName" optional="true" default="${handlerClassName}"
+ help="the name of the class" />
+
+ <macroArgument name="UserHandlerFunctionArgs" optional="true"
+ help="the arguments passed to the user handler function (== FunctionArgs by default)"/>
+
+ <!-- declare the virtual function override -->
+ <expandMacro name="GenerateMethodWithOwnedBody"
+ IsStatic="false"
+ IsVirtual="false"
+ />
+
+ <!-- generate a call to the user handler -->
+ <template location="$(OwnedRegionLocationId)"><![CDATA[<%
+if ($(UserHandlerFunctionArgs::is-defined)) {
+%>${event.handlerName}($(UserHandlerFunctionArgs::as-function-call-args::add-spaces-unless-empty));
+<% } else { %>${event.handlerName}($(FunctionArgs::as-function-call-args::add-spaces-unless-empty));
+<% } %>]]></template>
+
+
+</defineMacro>
+
+
+<defineMacro id="GenerateUserEventHandlerFunction"
+ help="
+Define a user handler declaration and function.
+ $p$
+Provides a default header comment and body comment.
+ $p$
+This is NOT conditional, so include it in a <templateGroup ifEvents="..." />
+ " >
+ <!-- extends GenerateMethod, but excludes
+ IsVirtual
+ IsStatic
+ and overrides:
+ FunctionBody
+ FunctionComment
+ FunctionName
+ FunctionLocationId
+ -->
+ <importArguments macroName="GenerateMethod"
+ exceptArguments="IsVirtual IsStatic" />
+
+ <macroArgument name="ClassName" optional="true" default="${handlerClassName}"
+ help="the name of the class that receives the handler" />
+
+ <macroArgument name="FunctionName" optional="true" default="${event.handlerName}"
+ help="the name of the function/method for the handler;
+ generally the default should be used (the name specified in the Events view)" />
+
+ <macroArgument name="FunctionLocationId"
+ help="the id for the event handler function" />
+
+ <macroArgument name="FunctionComment" optional="true"
+ help="the comment for the function" >
+/**
+ * Handle the ${event.eventName} event
+ */
+ </macroArgument>
+
+ <!-- -->
+ <macroArgument name="FunctionBody" optional="true"
+ help="the body of the function, which by default is a TODO comment" >
+// TODO: implement ${event.eventName} event handler
+ </macroArgument>
+
+ <!-- declare the user handler method -->
+ <expandMacro name="GenerateMethod"
+ passArguments="DeclLocation DeclPhase
+ FunctionName FunctionArgs ReturnType IsConst
+ DefnLocation ClassName FunctionLocationId
+ FunctionComment
+ FunctionBody DefaultReturn"
+ IsStatic="false"
+ IsVirtual="false"
+ IsEventHandler="true"
+ IsOwned="false"
+ />
+
+</defineMacro>