|
1 <defineMacro id="DeclareMethod" |
|
2 help="Declares a method, e.g., the prototype."> |
|
3 |
|
4 <macroArgument name="DeclLocation" optional="true" default="" |
|
5 help="name of location into which to add the prototype (either this or DeclPhase must be defined)" /> |
|
6 |
|
7 <macroArgument name="DeclPhase" optional="true" default="" |
|
8 help="name of phase into which to add the prototype (either this or DeclLocation must be defined)" /> |
|
9 |
|
10 <macroArgument name="FunctionName" |
|
11 help="name of function" /> |
|
12 |
|
13 <macroArgument name="FunctionArgs" |
|
14 help="canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")"/> |
|
15 |
|
16 <macroArgument name="ReturnType" optional="true" default="void" |
|
17 help="return type for function" /> |
|
18 |
|
19 <macroArgument name="IsStatic" optional="true" default="false" |
|
20 help="is the function static?" /> |
|
21 |
|
22 <macroArgument name="IsVirtual" optional="true" default="false" |
|
23 help="is the function virtual? (ignored if IsStatic)" /> |
|
24 |
|
25 <macroArgument name="IsConst" optional="true" default="false" |
|
26 help="add 'const' modifier to function?" /> |
|
27 |
|
28 <!-- N.B.: only one of location or phase will be non-empty --> |
|
29 <template location="$(DeclLocation)" phase="$(DeclPhase)" > |
|
30 ${($(IsStatic) ? "static " : ($(IsVirtual) ? "virtual " : "") |
|
31 )}$(ReturnType::append-space-unless-empty)$(FunctionName)($(FunctionArgs::as-function-declaration-args::split-and-indent::add-spaces-unless-empty))${($(IsConst) ? " const" : "")}; |
|
32 </template> |
|
33 </defineMacro> |
|
34 |
|
35 <defineMacro id="GenerateDefaultFunctionBody" |
|
36 help="Create the default body for a function. If FunctionBody is set, |
|
37 emits that. If ReturnType is not void and DefaultReturn is set, |
|
38 create a return statement using its value." > |
|
39 |
|
40 <macroArgument name="FunctionLocationId" |
|
41 help="name of the function location to define; body is named id+_BODY" /> |
|
42 |
|
43 <macroArgument name="DefaultReturn" optional="true" |
|
44 help="default value to return; overridden if FunctionBody is specified" /> |
|
45 |
|
46 <macroArgument name="ReturnType" optional="true" default="void" |
|
47 help="return type for function" /> |
|
48 |
|
49 <macroArgument name="FunctionBody" optional="true" default="" |
|
50 help="text inside function body (comment and/or code)" /> |
|
51 |
|
52 <template location="$(FunctionLocationId)"><![CDATA[<% |
|
53 if ($(FunctionBody::is-defined)) { |
|
54 %>$(FunctionBody)<% } |
|
55 if ($(DefaultReturn::is-defined) && $(ReturnType::as-string) != "void" && $(ReturnType::as-string) != "") { |
|
56 %>return $(DefaultReturn); |
|
57 <% } %>]]></template> |
|
58 |
|
59 </defineMacro> |
|
60 |
|
61 |
|
62 <defineMacro id="DefineMethod" |
|
63 help="Defines a method to one location, optionally generating body text, |
|
64 or a default return statement. |
|
65 The generated function is owned by default." > |
|
66 |
|
67 <importArguments macroName="GenerateDefaultFunctionBody" /> |
|
68 |
|
69 <macroArgument name="IsOwned" optional="true" default="true" |
|
70 help="is the function body owned?" /> |
|
71 |
|
72 <macroArgument name="DefnLocation" |
|
73 help="name of location into which to add the function" /> |
|
74 |
|
75 <macroArgument name="FunctionName" |
|
76 help="name of function" /> |
|
77 |
|
78 <macroArgument name="FunctionArgs" |
|
79 help="canonical argument list (e.g. "const TInt& aArg, TInt aFoo = 3")"/> |
|
80 |
|
81 <macroArgument name="IsConst" optional="true" default="false" |
|
82 help="add 'const' modifier to function?" /> |
|
83 |
|
84 <macroArgument name="ClassName" optional="true" default="${className}" |
|
85 help="the class name" /> |
|
86 |
|
87 <macroArgument name="FunctionComment" optional="true" |
|
88 help="comment appearing before function defn" /> |
|
89 |
|
90 <macroArgument name="IsEventHandler" optional="true" default="false" |
|
91 help="is the function body the user event handler?" /> |
|
92 |
|
93 <macroArgument name="Initializers" optional="true" default="" |
|
94 help="provide any initializer expressions, e.g. for constructors, appearing |
|
95 on a separate line after the argument list and before the function body. |
|
96 Do not provide the leading colon (':') as this is added automatically" /> |
|
97 |
|
98 <macroArgument name="Realize" optional="true" default="false" |
|
99 help="If true, force the function to be generated. Otherwise, the |
|
100 function is generated only if the FunctionBody is non-empty or if |
|
101 another template contributions to the FunctionLocationId." /> |
|
102 |
|
103 <defineLocation id="$(FunctionLocationId)" |
|
104 baseLocation="$(DefnLocation)" |
|
105 owned="$(IsOwned)" |
|
106 isEventHandler="$(IsEventHandler)" |
|
107 realize="$(Realize)" |
|
108 location="function($(ClassName)::$(FunctionName)($(FunctionArgs::as-function-location-args)))"> |
|
109 <template><![CDATA[<% |
|
110 if ($(FunctionComment::is-defined)) { |
|
111 %>$(FunctionComment)<% } |
|
112 %>$(ReturnType::append-space-unless-empty)$(ClassName)::$(FunctionName)($(FunctionArgs::as-function-definition-args::split-and-indent::add-spaces-unless-empty))${($(IsConst) ? " const" : "")}<% |
|
113 if ($(Initializers::as-string) != "") { |
|
114 %> |
|
115 : $(Initializers)<% } %> |
|
116 { |
|
117 } |
|
118 ]]> |
|
119 </template> |
|
120 </defineLocation> |
|
121 |
|
122 <expandMacro name="GenerateDefaultFunctionBody" /> |
|
123 |
|
124 </defineMacro> |
|
125 |
|
126 |
|
127 |
|
128 <defineMacro id="GenerateMethod" |
|
129 help="Declares and defines a method to one location |
|
130 and adds the prototype to another location." > |
|
131 |
|
132 <importArguments macroName="DeclareMethod" /> |
|
133 |
|
134 <importArguments macroName="DefineMethod" /> |
|
135 |
|
136 <expandMacro name="DeclareMethod" /> |
|
137 |
|
138 <expandMacro name="DefineMethod" /> |
|
139 |
|
140 </defineMacro> |
|
141 |
|
142 <defineMacro id="DefineMethodWithOwnedBody" |
|
143 help="Defines a method with an owned body section. |
|
144 $p$ |
|
145 The generated function is not owned by default, unlike Method. |
|
146 There may be uses for an owned function with a named owned region, though. |
|
147 $p$ |
|
148 Also, no default function code is generated, so the provided |
|
149 StartFunctionBody, FunctionBody, and EndFunctionBody must account for |
|
150 any return statements." > |
|
151 |
|
152 <importArguments macroName="DefineMethod" /> |
|
153 |
|
154 <macroArgument name="OwnedRegionLocationId" optional="true" default="$(FunctionLocationId)_BODY" |
|
155 help="location id for enclosed body" /> |
|
156 |
|
157 <macroArgument name="OwnedRegionName" optional="true" default="Generated Contents" |
|
158 help="region name for enclosed body" /> |
|
159 |
|
160 <macroArgument name="StartFunctionBody" optional="true" default="" |
|
161 help="text inside function body (comment and/or code) before the owned section" /> |
|
162 |
|
163 <macroArgument name="FunctionBody" optional="true" default="" |
|
164 help="text inside owned part of function body" /> |
|
165 |
|
166 <macroArgument name="EndFunctionBody" optional="true" default="" |
|
167 help="text inside function body (comment and/or code) after the owned section" /> |
|
168 |
|
169 <expandMacro name="DefineMethod" |
|
170 dontPassArguments="DefaultReturn FunctionBody" |
|
171 help="make a method first: does not pass DefaultReturn |
|
172 since either FunctionBody or EndFunctionBody should be |
|
173 handling the return" |
|
174 /> |
|
175 |
|
176 <template location="$(FunctionLocationId)">$(StartFunctionBody) |
|
177 </template> |
|
178 |
|
179 <defineLocation id="$(OwnedRegionLocationId)" baseLocation="$(FunctionLocationId)" |
|
180 location="region($(OwnedRegionName))" realize="true"> |
|
181 <template>$(FunctionBody) |
|
182 </template> |
|
183 </defineLocation> |
|
184 |
|
185 <template location="$(FunctionLocationId)">$(EndFunctionBody) |
|
186 </template> |
|
187 |
|
188 </defineMacro> |
|
189 |
|
190 <defineMacro id="GenerateMethodWithOwnedBody" |
|
191 help="Declares and defines a method with an owned body section to one location |
|
192 and adds the prototype to another location. |
|
193 $p$ |
|
194 The generated function is not owned by default, unlike Method. |
|
195 There may be uses for an owned function with a named owned region, though."> |
|
196 |
|
197 <importArguments macroName="DefineMethodWithOwnedBody" /> |
|
198 |
|
199 <importArguments macroName="DeclareMethod" /> |
|
200 |
|
201 <expandMacro name="DeclareMethod" /> |
|
202 |
|
203 <expandMacro name="DefineMethodWithOwnedBody" /> |
|
204 |
|
205 </defineMacro> |
|
206 |
|
207 <defineMacro id="GenerateMethodWithVariantArguments" |
|
208 help=" |
|
209 Declares and defines an owned method with variant arguments to one location |
|
210 and adds the prototype to another location. |
|
211 $p$ |
|
212 Variant arguments means design-time variable (not C varargs). |
|
213 The function has a non-empty list of fixed arguments followed by a |
|
214 non-empty list of variable arguments which are generated by a Javascript expression. |
|
215 $p$ |
|
216 The generated function is owned by default. It doesn't make sense to use |
|
217 this non-owned, since this will introduce compile errors when the prototype |
|
218 changes and the old body remains behind. |
|
219 "> |
|
220 <importArguments macroName="GenerateMethod" |
|
221 exceptArguments="FunctionArgs IsOwned" |
|
222 |
|
223 help="use all the same arguments from Method, |
|
224 excluding FunctionArgs, whose semantics are different, |
|
225 and IsOwned, which changes defaults"/> |
|
226 |
|
227 <macroArgument name="IsOwned" optional="true" default="true" |
|
228 help="tell whether the function is owned. In general, it should be, |
|
229 otherwise compile errors will be introduced when the |
|
230 method's signature changes and the old version is left behind." /> |
|
231 |
|
232 <macroArgument name="FunctionArgs" |
|
233 help="canonical leading static argument list (e.g. "const TInt& aArg, TInt aFoo = 3") |
|
234 Do not include a trailing comma" /> |
|
235 |
|
236 <macroArgument name="FunctionVarArgsAllowEmpty" optional="false" |
|
237 help="tell whether the varargs may be empty"/> |
|
238 |
|
239 <macroArgument name="FunctionVarArgsDeclExpr" |
|
240 help="generator for the variable arguments as appearing in the declaration |
|
241 (a Javascript expression); |
|
242 if FunctionVarArgsAllowEmpty==false, do not generate a leading comma"/> |
|
243 |
|
244 <macroArgument name="FunctionVarArgsDefnExpr" |
|
245 help="generator for the variable arguments as appearing in the definition |
|
246 (a Javascript expression); |
|
247 if FunctionVarArgsAllowEmpty==false, do not generate a leading comma" /> |
|
248 |
|
249 <!-- make a method declaration first --> |
|
250 <template location="$(DeclLocation)" phase="$(DeclPhase)" > |
|
251 ${($(IsStatic) ? "static " : ($(IsVirtual) ? "virtual " : "") |
|
252 )}$(ReturnType::append-space-unless-empty)$(FunctionName)( $(FunctionArgs::as-function-declaration-args::split-and-indent)${($(FunctionVarArgsAllowEmpty) ? "" : ", ")}${$(FunctionVarArgsDefnExpr::split-and-indent)} )${($(IsConst) ? " const" : "")}; |
|
253 </template> |
|
254 |
|
255 <!-- now define the function --> |
|
256 <defineLocation id="$(FunctionLocationId)" |
|
257 baseLocation="$(DefnLocation)" |
|
258 owned="$(IsOwned)" |
|
259 location="function($(ClassName)::$(FunctionName)($(FunctionArgs::as-function-location-args),...))"> |
|
260 <template><![CDATA[<% |
|
261 if ($(FunctionComment::is-defined)) { |
|
262 %>$(FunctionComment)<% } |
|
263 %>$(ReturnType::append-space-unless-empty)$(ClassName)::$(FunctionName)( $(FunctionArgs::as-function-definition-args::split-and-indent)${($(FunctionVarArgsAllowEmpty) ? "" : ", ")}${$(FunctionVarArgsDefnExpr::split-and-indent)} )${($(IsConst) ? " const" : "")} |
|
264 { |
|
265 } |
|
266 ]]> |
|
267 </template> |
|
268 </defineLocation> |
|
269 |
|
270 <!-- and define the body --> |
|
271 <expandMacro name="GenerateDefaultFunctionBody" /> |
|
272 |
|
273 </defineMacro> |
|
274 |
|
275 <defineMacro id="GenerateVirtualMethodOverrideForEventHandler" |
|
276 help="Override a virtual method with a non-owned function with an owned body. |
|
277 This must be invoked in a templateGroup that has an ifEvents="..." attribute, |
|
278 so the 'event' variable is available. "> |
|
279 <importArguments macroName="GenerateMethodWithOwnedBody" |
|
280 exceptArguments="IsVirtual IsStatic" /> |
|
281 |
|
282 <macroArgument name="ClassName" optional="true" default="${handlerClassName}" |
|
283 help="the name of the class" /> |
|
284 |
|
285 <macroArgument name="UserHandlerFunctionArgs" optional="true" |
|
286 help="the arguments passed to the user handler function (== FunctionArgs by default)"/> |
|
287 |
|
288 <!-- declare the virtual function override --> |
|
289 <expandMacro name="GenerateMethodWithOwnedBody" |
|
290 IsStatic="false" |
|
291 IsVirtual="false" |
|
292 /> |
|
293 |
|
294 <!-- generate a call to the user handler --> |
|
295 <template location="$(OwnedRegionLocationId)"><![CDATA[<% |
|
296 if ($(UserHandlerFunctionArgs::is-defined)) { |
|
297 %>${event.handlerName}($(UserHandlerFunctionArgs::as-function-call-args::add-spaces-unless-empty)); |
|
298 <% } else { %>${event.handlerName}($(FunctionArgs::as-function-call-args::add-spaces-unless-empty)); |
|
299 <% } %>]]></template> |
|
300 |
|
301 |
|
302 </defineMacro> |
|
303 |
|
304 |
|
305 <defineMacro id="GenerateUserEventHandlerFunction" |
|
306 help=" |
|
307 Define a user handler declaration and function. |
|
308 $p$ |
|
309 Provides a default header comment and body comment. |
|
310 $p$ |
|
311 This is NOT conditional, so include it in a <templateGroup ifEvents="..." /> |
|
312 " > |
|
313 <!-- extends GenerateMethod, but excludes |
|
314 IsVirtual |
|
315 IsStatic |
|
316 and overrides: |
|
317 FunctionBody |
|
318 FunctionComment |
|
319 FunctionName |
|
320 FunctionLocationId |
|
321 --> |
|
322 <importArguments macroName="GenerateMethod" |
|
323 exceptArguments="IsVirtual IsStatic" /> |
|
324 |
|
325 <macroArgument name="ClassName" optional="true" default="${handlerClassName}" |
|
326 help="the name of the class that receives the handler" /> |
|
327 |
|
328 <macroArgument name="FunctionName" optional="true" default="${event.handlerName}" |
|
329 help="the name of the function/method for the handler; |
|
330 generally the default should be used (the name specified in the Events view)" /> |
|
331 |
|
332 <macroArgument name="FunctionLocationId" |
|
333 help="the id for the event handler function" /> |
|
334 |
|
335 <macroArgument name="FunctionComment" optional="true" |
|
336 help="the comment for the function" > |
|
337 /** |
|
338 * Handle the ${event.eventName} event |
|
339 */ |
|
340 </macroArgument> |
|
341 |
|
342 <!-- --> |
|
343 <macroArgument name="FunctionBody" optional="true" |
|
344 help="the body of the function, which by default is a TODO comment" > |
|
345 // TODO: implement ${event.eventName} event handler |
|
346 </macroArgument> |
|
347 |
|
348 <!-- declare the user handler method --> |
|
349 <expandMacro name="GenerateMethod" |
|
350 passArguments="DeclLocation DeclPhase |
|
351 FunctionName FunctionArgs ReturnType IsConst |
|
352 DefnLocation ClassName FunctionLocationId |
|
353 FunctionComment |
|
354 FunctionBody DefaultReturn" |
|
355 IsStatic="false" |
|
356 IsVirtual="false" |
|
357 IsEventHandler="true" |
|
358 IsOwned="false" |
|
359 /> |
|
360 |
|
361 </defineMacro> |