--- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/reference/CustomComponents/cc_source_generation.htm Tue Jul 27 15:20:28 2010 -0500
+++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/reference/CustomComponents/cc_source_generation.htm Tue Jul 27 15:28:19 2010 -0500
@@ -1,677 +1,677 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
-<meta http-equiv="Content-Style-Type" content="text/css" />
-<title>Source Generation</title>
-<link rel="StyleSheet" href="../../../book.css" type="text/css"/>
-</head>
-<body bgcolor="#FFFFFF">
-<h2>Source Generation</h2>
-<p>The UI Designer supports generating C/C++ source code through a contribution-driven model. A component provides a <sourceGen> element which uses a series of XML elements to define locations, templates, and inline JavaScript code. These elements contribute, eventually, to an ordered list of "contributions" to source. Each component passes its contributions up to its parent, which collates them, and recursively passes them to its parent. The end result is a full set of contributions defining all the generated source.</p>
-<p>A contribution is an association of text and a high-level "location" in the project (for example, the "enum TValues" enumeration inside "class CMyClass" inside the file "inc/MyClass.h"). The text is generated either by template expansion or by explicit JavaScript code, or both. A location is defined relative to other locations and may represent either "unowned" code (which is generated once, when it is missed) or "owned" code (which is always regenerated).</p>
-<p>A contribution may have a "phase" instead of a location. A "phase" is a moniker for a location that will be resolved later, usually by the parent of a component instance. This may be used to collate contributons within a location, or for filtering, or other purposes. Using phases allows a component to target different parents which may have different location hierarchies. In the final list of contributions returned to the source generator, all phases must be resolved to locations.</p>
-<p>The concept of “phases” is intended to alleviate the need for children to know where they are generating code. Thus, a <template> for a child needn’t specify a location if it specifies a phase; the container will supply the location. This implies that the container explicitly “fixes up” child contributions by finding those with a matching phase and setting their locations. Contributions cannot supply their own locations if contributing to a phase.</p>
-<p>If a child wants to contribute code to other locations, it either defines its own location, derives from a known one, or contributes to a new phase that the appropriate parent(s) know how to handle.</p>
-<p>Usually, phases are used to reduce coupling between components that exist in hierarchies where the specific location ids or specific relations of locations to each other should not be hardcoded. For instance, a parent that generates a class may define several phases for children to use to contribute instance members, initialization statements, and #includes. The parent must resolve contribution phases to actual location ids before returning its contributions to its parent (using Engine.assignLocationsForPhase(List, String, String)).</p>
-<p>The internal format of <sourceGen> is a single JavaScript file, which is maintained in memory. The <sourceGen debug="true"> attribute or the <strong>Components > Configure SourceGen Debugging...</strong> dialog may be used to write this content to disk, for debugging.</p>
-<p>The <sourceGen> element may contain the <defineLocation>, <template>, <templateGroup>, <inline>, <useTemplate>, and <useTemplateGroup> elements in any order or number. The strict order of <template>, <useTemplate>, <inline> elements etc. will determine the ordering of contributions in files. Thus, the position of the first template that references the “CLASS” location determines where in “HEADER_FILE” the class will appear.</p>
-<p>The <sourceGen> element’s children are interpreted as a linear list of discrete operations, all of which are executed for each instance of an object in the data model. The ordering of these nodes directly corresponds to the order in which text will initially be generated.</p>
-<h3><a name="contrib"></a>Contributions</h3>
-<p>Each component definition file defines data and code which create contributions. A contribution is a piece of formatted text which is placed into source at a location associated with a domain. Each contribution has a domain and a location describing where to place the text. The complete source generation comes from an algorithm which places the pieces of text in the right locations. A contribution is not complete and cannot be processed by the domain until it has a location. It may exist in a transient state where only a phase is set. At some point (usually in a parent component) the phase is converted to a location. If a location referenced by contributions is missing, then it is created by applying the templates that define the location.</p>
-<p>Source contributions are gathered from the bottom and go up. Parents collate child contributions and the top level (data model) sorts contributions and generates source. The UI Designer backend engine interprets contributions and is familiar with specific languages. Source generation is expanded into JavaScript, defining a single JavaScript object that implements the IComponentSourceGen interface that returns a list of contributions to the parent.</p>
-<p>A contribution consists of:</p>
-<ul>
- <li>A domain — the file-format semantic handler for source (currently, "cpp" is the only implemented domain for C/C++ sourcegen)</li>
- <li>A location — the domain-specific path specifying where source goes</li>
- <li>A phase — a container-specific tag used to collate child contributions</li>
- <li>A form — a container-specific tag used to inform children how to generate source</li>
- <li>A mode — a hint to the source generator about a way to treat the contribution</li>
- <li>Content — the template or text that is inserted</li>
-</ul>
-<h3><a name="locations"></a>Locations</h3>
-<p>Locations are strings that identify a domain-specific location (currently only cpp) where generated source is placed. In the C/C++ domain, locations are paths that are specified structurally, with reference to easy navigation with the CDT DOM. To reference a location use a statement such as <template location=“<em>location-id</em>” ... />. The location must be in the same directory and file it was originally created in for the domain to find it.</p>
-<p>Locations are organized like file paths separated with ‘/’, with more encompassing items on the left, and children of those items on the right.</p>
-<p>Each path entry consists of a specifier and arguments:</p>
-<ul>
- <li>specifier ‘(‘ argument [‘,’argument ...] ‘)’</li>
-</ul>
-<p>For example:</p>
-<blockquote>
- <p> class(MyClass)/region(InstanceVariables) — A special block named “InstanceVariables” inside the class declaration “MyClass”</p>
- <p>function(MyClass::initComponents()) — The function <span class="code">MyClass::initComponents() {}</span> in a file. Not <span class="code">class(MyClass)</span> then <span class="code">function(initComponents())</span> unless actually declaring the function inline.</p>
-</blockquote>
-<p>The identifier used in locations is lexically scoped. It can be resolved either in the current instance’s component or in a parent component that directly or indirectly invoked the contribution phase for this component. The location is not global except in the case of a “library” component. A top-level component can serve as such a library for this case. For example, a common pattern for locations which are intended for use by children could be to name them FILE, CLASS, or METHOD. Anything else can have a more descriptive name to distinguish it from other locations defined in parents.</p>
-<p>Every <template> element must have a phase or a location, but not both. For a phase, the container supplies the location for all matching phases. For a location, the template supplies the location by reference to <defineLocation> (either global or local).</p>
-<p>A location can be defined by a template that builds a location by drilling into a location passed from the parent, or one can be generated from scratch. A location describes a virtual path to actual source. A location is based on another location, such as a class inside a file, or on a file. A root location has no base and is defined by a relative directory and a filename within the current project. A derived location is defined as being contained within the bounds of its base location.</p>
-<p>For example, a base location may be the file foo.cpp in the directory "src". A derived location may be the CFoo::CFoo() function defined within that source file. Another location derived from this may be a local enumeration (TChoices) defined within that function. A derived location cannot provide two segments, such as jump directly from a file to an enum nested within a class. There must be one location defined per segment.</p>
-<p>A location can be created “inside” another, as long as that one is also defined. Defined locations have globally unique identifiers which are attached to contributions to place that contribution at the given location.</p>
-<p>When a parent component asks a child to generate contributions, the child can reference all its parent’s locations. Although, phases can be used instead to reduce coupling. A child may redefine a location that comes from a parent, but this change only has a local effect on the child’s source generation.</p>
-<p>A location is realized in source code when</p>
-<ul>
- <li>its "realize" attribute is set to "true" in <defineLocation>,</li>
- <li>when it is referenced by a <template> with location=”…”,</li>
- <li>when script creates a contribution using <span class="code">Engine.createContributionForLocation()</span>,</li>
- <li>or when a phase is resolved to a location with <span class="code">Engine.assignLocationsForPhase</span>.</li>
-</ul>
-<p>The location and any parent locations are created as needed. If they already exist in source, they are not regenerated. However, if they are owned by the UI Designer, they will be cleared out. Note that root locations will create missing directories and files.</p>
-<p>Locations may have filters that control whether a contribution is emitted to it. This is primarily used to check for unique code, for example, to avoid duplicate #includes, member declarations, and base class entries. Locations may be conditional if an event binding exists. The location would then only be declared if one of a given set of events is bound to an instance.</p>
-<p>Locations can be owned by the UI Designer or not owned. If owned, a “do not modify” comment is added automatically to the generated source. The location’s contents are cleaned out each time the source is generated. For example, source is regenerated for:</p>
-<ul>
- <li>Instance variables for children of a container</li>
- <li>Methods used to initialize child components</li>
-</ul>
-<p>If not owned, no comment is added. The location and its contributions are applied only if the location was created in this source generation phase. For example:</p>
-<ul>
- <li>User-owned stub functions for event handlers, etc.</li>
- <li>Example code copied from template</li>
- <li>Initial file contents</li>
- <li>Top-of-file ownership comments</li>
-</ul>
-<h4><a name="defloc"></a>DefineLocation Element</h4>
-<p>Every location is created in a specific directory and filename. To define a location, create a <defineLocation> element in the <sourceGen> element of a component definition file. All <defineLocation> entries are inherited automatically by derived components. </p>
-<p>The following is an example syntax of defining locations.</p>
-<pre class="listing"><defineLocation [baseLocation=“id” | domain=“...” dir=“...” file=“...” ] id=“...” location=“...” owned=“[true|false]” [ realize="true|false"]>
- <template .... /> / <script ... /> / <inline ... />
-</defineLocation></pre>
-<p>The <strong>dir</strong> and <strong>file</strong> attributes specify the path and filename where the location is initially created; after that, the CDT DOM is used to find the location. The <strong>dir</strong> attribute tells what project-relative directory to use. The template variable may be used to look up a user-configured directory. For example, ${src}, ${inc}, ${resource}, ${build}, or ${aif}. A path may be applied to enter the directory.</p>
-<p>Examples:</p>
-<ul>
- <li>${src} --> “<project>/src”</li>
- <li>${build} --> “<project>/group”</li>
- <li>${inc}/subdir --> “<project>/inc/subdir”</li>
- <li>./data or data --> “<project>/data”</li>
-</ul>
-<p>The filename is specified with the <strong>file</strong> attribute.</p>
-<p>Examples:</p>
-<ul>
- <li>dir=“${src}” file=“fixedname.cpp” --> “<project>/src/fixedname.cpp”</li>
- <li>dir=“${inc}/sys” file=“C${viewName}.h” --> “<project>/inc/sys/CMyView.h”</li>
-</ul>
-<p>The <strong>location</strong> attribute specifies the domain-specific location details. The <strong>owned</strong> attribute defines whether the section of code is owned (rewritten) or not owned by the UI Designer. The <template>, <script>and <inline> nodes provide the code that creates the contents for a referenced location if it is missing.</p>
-<p>The dir, file, and location attributes use a common pattern for handling variable and template-expanded arguments. Arguments are specifed with this syntax: ${variable}.</p>
-<p>Standard variables include:</p>
-<ul>
- <li>${className} — name of component class from XML (e.g. CEikSlider)</li>
- <li>${instanceName} — name of the component instance</li>
- <li>${resourceName} — name of generated resource for instance (e.g. “r_test0”)</li>
-</ul>
-<p>Variables in locations refer to the current component, however locations can be used in child components or other components. A location is expanded with respect to the component that generates a contribution using that location. A child component which sets “phase” does not set location.</p>
-<p>Therefore, the location is expanded relative to the parent which supplied the location to the child. The child can still derive a location from specific location ids in the parent. In such a case, the parts that the child adds are expanded relative to the child.</p>
-<p>For example, the parent sets dir=“${src}”, file=“C${viewName}.h”, and location=“class(C${baseComponentId})”, and passes this to the children for the addInstanceVariables phase. The child gets the fully specified dir/file/location attributes that reference the parent component, but it can derive a location with a custom use of ${baseComponentId}, which will be expanded to its own component base.</p>
-<p>The <defineLocation> element declares and defines locations which may be used by contributions. For example:</p>
-<pre class="listing"><defineLocation id="HEADER_FILE" domain="cpp" dir="${inc}"
- file="${instanceName}.h"
- owned="false"
- location=""><br /></defineLocation></pre>
-<p> This example describes a root location which is a header file. The <strong>domain</strong>, <strong>dir</strong>, and <strong>file</strong> attributes are required for root locations, and the <strong>location </strong>attribute must be empty. The <strong>dir</strong> and <strong>file</strong> attributes are template-expanded by referencing the instance global variables. For instance, “${inc}” defines the directory used for includes, and “${instanceName}” is the name of the current instance, so the file will be named after the instance.</p>
-<p>Following is an example of a derived location where the location is understood as a class definition in the header file.</p>
-<pre class="listing"><defineLocation id="CLASS" baseLocation="HEADER_FILE"
- owned="false"
- location="class(${className})">
- <template>
- …
-</defineLocation></pre>
-<p>Common to any <defineLocation> element are the following attributes:</p>
-<ul>
- <li><strong>id=”<string>”</strong> is used to reference the location. Location ids must be unique in a component. Locations can be overridden in derived components by using the same id.</li>
- <li><strong>location=”<string>” </strong>is the segment of the location added to a base (“” for files). These are interpreted relative to the domain. All together, the segments from the root to a location are considered the “location path.” See <a href="#cpplocseg">cpp location segments</a> for syntax.<br />
- Note that only one location may map a given location path. Otherwise you will get errors to this effect when generating source. In other words, if you use the same location path, use the same location id.</li>
- <li><strong>owned=”<<em>boolean</em>>” </strong>tells whether the given location will be regenerated every time (true) or generated only if missing (false).</li>
-</ul>
-<blockquote>
- <p><span class="note"><strong>NOTE</strong> The user might delete a generated owned location. When it is regenerated, it will <strong>not </strong>go in the original location again, but to the end of the parent location. This is a known limitation.</span></p>
-</blockquote>
-<ul>
- <li><strong>filter=”<<em>filter-name</em>>” </strong>defines the particular filter to apply (either “unique-includes” for regions, “unique-prototypes” for classes, or “unique-bases” for base class lists).</li>
- <li><strong>ifEvents=”<list of events>” </strong>defines the space-separated list of event names; one of which must be defined in order to declare the location. Such locations are conditionally available. Their ids are not available unless a matching event is bound. Thus, any references to event-derived variables like eventHandlerName or eventInstanceName will not trigger errors unless the event is bound.</li>
- <li><strong>isEventHandler=”<<em>boolean</em>>” </strong>is used to locate a particular method when adding events in the editor. This method applies to the <em>user-editable function</em> to edit. It is only used if the <strong>ifEvents </strong>attribute is set.</li>
- <li><strong>realize="<boolean>"</strong> if set to "true", forces a location to be realized in source when it is encountered. Otherwise, the location will not exist in source unless a template contributes to it. (If a location is defined inside conditional sourcegen, guarded by ifEvents="..." or ifExpr="...", then the location will only be realized if the expression is true.)</li>
-</ul>
-<p> A <defineLocation> element may include a number of <template> or <inline> elements. When a location is realized, the contained templates and inline blocks are executed to define it. The templates are responsible for contributing the text that will correctly define the location, optionally populating it with initial content.</p>
-<p>In the example above, the header file location has no templates, since an empty file is a valid file. Although, to define a class, the definition must be provided:</p>
-<pre class="listing"><defineLocation id="CLASS" baseLocation="HEADER_FILE"
- owned="false"
- location="class(${className})">
- <template><br /> <![CDATA[
- /**
- * Container class for ${instanceName}
- *
- * @class ${className} ${instanceName}.h
- */
- class ${className} : public CCoeControl
- {
- public:
- // constructors and destructor
- ${className}();
- virtual ~${className}();
- };
- ]]>
- </template>
-</defineLocation></pre>
-<p>Note that the variable expansion ${className} is used inside the <strong>location</strong> attribute. These same variables are available in the text and substituted using the same syntax, although the semantics are different. See <a href="#template"><template></a> element for more details.</p>
-<h5><a name="cpplocseg" id="cpplocseg"></a>Cpp location segments</h5>
-<p>A location segment in the cpp domain is a string representing a node in a C/C++ parse tree. Each takes the syntax “<name> ‘(‘ <arguments…>‘)’”. Certain nodes may only appear within certain others. This list defines top-level nodes:</p>
-<ul>
- <li><strong>class(<name>)</strong> <strong>— </strong>references the class declaration for the class ‘name’, which may include namespaces (for example, “class(MyClass)” or “class(${className})”)</li>
- <li><strong>function(<name>(<arguments…))</strong> <strong>— </strong>references a function with the given signature. A ‘name’ may include namespaces or represent a destructor. The ‘arguments’ are a comma-separated list of types. This list of arguments must specify the correct type information, for example "const TInt&". This allows overridden methods to be defined and referenced. The arguments list may end in ellipsis (“…”) to indicate that any zero or more arguments are matched. Again, the <template> inside a <defineLocation> really defines the function, which for a class method means that most of the information is repeated a few lines down. Using macros like GenerateMethod may be more succinct. Examples of function locations are: “<span class="code">function(main(int,char**))</span>” or “<span class="code">function(${className}::method(void*))</span>”.</li>
- <li><strong>region(<name>)</strong> <strong>— </strong>a region defines a commented block of text with no other syntactical clues. The block comments and the name are used to identify the block. Usually, regions appear at the top level of the file or inside other locations, typically to provided owned sections therein. These need to be unique in the context of their parent. (For instance, every non-owned method in a file may reuse the name "Generated Code" for their embedded owned blocks.) For example, “region(Generated Includes)”.</li>
- <li><strong>enum(<name>)</strong> <strong>— </strong>an enum declaration with the given name. Name must be non-empty. Locations are used to look up source, so anonymous enums cannot be unambiguously identified. For example, “enum(T${className}Ids)”.</li>
- <li><strong>namespace(<name>)</strong> <strong>— </strong>a namespace declaration with the given name, which may contain colons. For example, “namespace(std::tr1)”.</li>
- <li><strong>to-file()</strong> <strong>— </strong>resolves to the current file of a location, that is, back to the root location.</li>
-</ul>
-<blockquote>
- <p>Inside a class(), namespace() is not allowed, and this additional segment is allowed.</p>
-</blockquote>
-<ul>
- <li><strong>bases()</strong> <strong>— </strong>references the base-class-list within a class declaration. If the class defining text already includes a base, then the defining text for the bases() location may be omitted. If a class defining text does not include a base, the bases() location must include the leading colon in its defining text. Otherwise, contributions are individual class references with leading commas.</li>
-</ul>
-<blockquote>
- <p>In a function(), only class(), region(), enum(), and to-file() are allowed.</p>
- <p>In an enum(), bases() or region(), only region() and to-file() are allowed. </p>
-</blockquote>
-<h3><a name="filterloc"></a>Owned/Non-owned/Filtered Locations</h3>
-<p>The term "owned" refers to a section of code which is always rewritten by the UI Designer. Such sections are either associated with specific C/C++ syntactic elements, such as classes, functions, and enums. These sections may also appear as a region within such an element or at the file level. Any user edits within the comments are lost. These comments look like:</p>
-<blockquote>
- <pre>// [[[ begin generated region: do not modify! [Generated User Includes]
- <strong>#include</strong> "MyForm.h"
- <strong>#include</strong> "My.rsg"
-// ]]] end generated region [Generated User Includes]</pre>
-</blockquote>
-<p><strong></strong>The term "non-owned" refers to anything outside the “owned” comments. In this example, the function is non-owned, since there is no comment around it. The user is allowed to change anything before or after the owned region inside the function.<strong></strong></p>
-<blockquote>
- <pre class="listing">/**
-* Construct the MyForm instance
-* @param aCommandObserver command observer
-*/
-MyForm::MyForm( MEikCommandObserver* aCommandObserver )
- {
- iCommandObserver = aCommandObserver;
- // [[[ begin generated region: do not modify! [Generated Contents]
- // ]]] end generated region [Generated Contents]
- }</pre>
-</blockquote>
-<p>"Filtered" refers to non-owned locations which have the "filter" attribute specified. Even if the location already exists, every contribution will be considered and added if it does not pass the filter.</p>
-<h3>Elements</h3>
-<h4><a name="template" id="template"></a>Template element</h4>
-<p>A <template> element defines text for contributions. Ordering of <template> contributions is retained for the parent. The <template> element attributes include:</p>
-<ul>
- <li>domain — name of contribution domain</li>
- <li>location — domain-specific syntax, optional if phase is set</li>
- <li>mode — optional; used to attach semantics to location</li>
- <li>phase — used for ordering, optional if location is set</li>
- <li>form — optional; used to adapt to parent requirements</li>
- <li>ifEvents=”<list of events>” — optional; if any one of the space-separated event names is bound on the current instance, then the template is emitted.</li>
- <li>ifExpr="<expression>" — if the JavaScript expression evaluates to true, the template is emitted.</li>
- <li>id="<name>" — optional; the unique identifier of the template, within a component or a template group. Only templates with ids, even if included in a templateGroup, may be inherited.</li>
-</ul>
-<p> A <templateGroup> element combines several <template> elements into a named group. Grouping is strictly a convenience and has no impact on generated script. Attributes of <templateGroup> are automatically applied to the contained <template> elements. The attribute “id” may be specified to name the group. Included templates have a unique “id” namespace.</p>
-<p>Example:</p>
-<pre class="listing"><sourceGen>
- <templateGroup form="CAknView"> <!-- group of templates inhheriting form -->
- <template phase=“initcomponents” id=“foo”>
- ${instanceName}->SetName(${instanceName.toString()});
- </template>
- <template phase=“parenting”>
- ${parent.instanceName}->Add(${instanceName});
- </template>
- </templateGroup>
- <template location="INCLUDES"> <!-- standalone template -->
- #include <akndialog.h> <!-- XML needs to be escaped unless in <![CDATA[...]]> -->
- </template>
-</sourceGen></pre>
-<p>The lines in text nodes of templates should be flush left on the line, unless multiple lines are defined, where some of the lines have more indentation. If extra indentation is added, use the tab character only. The source generator will convert tabs to spaces according to the workspace settings. The nesting of a particular location defines the indentation level. The indentation for a contribution may be adjusted with a script escape at the start of the node, for example:</p>
-<pre class="listing"><template location=”CLASS”><![CDATA[
- <% contrib.indentAdjust(-1); %>protected: ]]>
-</template></pre>
-<p>The object “contrib” refers to the IContribution instance currently being generated, which is automatically available for any <template>. The argument specifies the number of levels to adjust. This example outdents the “protected:” line in a class declaration.</p>
-<p>Except for the very beginning and very end, almost every character is used in the template’s text. After the end of the <template> open-element, any spaces and newlines are removed if present before the </template> close-element. Any whitespace on any line before the </template> close-element is also removed. Such line stripping does not occur when escapes are used. Thus, script escapes often need to start at the very end of the previous line or end at the very start of the next line in order to avoid spurious newlines in the generated text.</p>
-<h5>Expression Escapes</h5>
-<p>A <template> element is converted into a small JavaScript function that at runtime generates segments of text into source, in a manner similar to JSP. Initially, the text in a template is converted into code that inserts literal text into source. Placeholders in the form ${expression} may appear in literal text. These resolve to JavaScript expressions whose string representations are inserted into source. If expressions involve complex expressions, enclose them in parentheses.</p>
-<p>Most attributes in <sourceGen> XML also allows for syntax that resembles expression escapes. Such attributes, however, are not evaluated in JavaScript. Such expansions may only reference variable names, not expressions. A set of predefined variables is a subset of that available to script, with some extensions to account for common operations:</p>
-<p><strong>${src}</strong>: the source directory used when creating the project<br />
- <strong>${inc}</strong>: the source directory used when creating the project<br />
- <strong>${build}</strong>: the build directory used when creating the project (e.g. "group")<br />
- <strong>${resource}</strong>: the resource directory used when creating the project (e.g. "data")</p>
-<p><strong>${projectName}</strong>: the name of the generated project<br />
- <strong>${instanceName}</strong>: the name property of the current instance<br />
- <strong>${instanceName$title}</strong>: the titlecased version of the instance name, with the first letter capitalized (e.g. "my_var" becomes "My_var")<br />
- <strong>${instanceName$upper}</strong>: the uppercase version of the instance name<br />
- <strong>${instanceName$lower}</strong>: the lowercase version of the instance name<br />
- <strong>${instanceMemberName}</strong>: the expected name for an instance variable for this component instance: 'i' + the titlecased version of the instance name<br />
- <strong>${className}</strong>: the value of the 'className' property in the nearest enclosing parent (or the current instance) that defines it. May be null. <br />
- <strong>${parentClassName}</strong>: like ${className}, but the className property of the next enclosing instance. Note that this is not related to nesting of classes.<br />
- <strong>${handlerClassName}</strong>: this is the value of the 'className' property for the nearest enclosing parent (or the current instance) which defines the attribute 'event-handler-target' to "true". May be null.<br />
- <strong>${handlerInstanceName}</strong>: this is the value of the 'name' property for the nearest enclosing parent (or the current instance) which defines the attribute 'event-handler-target' to "true". May be null.<br />
-</p>
-<p>These variables are available if the component generates resources (see <a href="cc_source_mapping.htm">RSS Source Mapping</a>):</p>
-<p><strong>${resourceName}</strong>: the name of the primary generated resource for the instance. May be null.<br />
- <strong>${resourceName$upper}</strong>: the uppercase name of the primary generated resource, as used for the macro in the .rsg file. May be null.<br />
- <strong>${resourceFileNameBase}</strong>: the filename, without extension, used for the resources this instance generated. May be null.</p>
-<h5>Script Escapes</h5>
-<p>Script escaped in <%...%> blocks specifies JavaScript code which is inserted directly into the generated function to control the source generation process. This escape usually either surrounds raw text in a condition, adds looping, or creates contributions programmatically. The entire sequence of text, including escapes, is interpreted in order, and expanded into a sequence of script. Raw text should be understood as script that emits the given raw text.</p>
-<p>For example, a loop that iterates properties may be specified like this:</p>
-<pre class="listing"><template>
- <% for (var property in properties) { %>
- ${instanceName}->Set${titleCase(property.name)}
- (${property.value});
- <% } %>
-</template></pre>
-<p>This example shows expressions. Here, the instanceName is expanded and emitted in line with the raw text around it.</p>
-<pre class="listing"><template location="HEADER_FILE"><![CDATA[
- #include "${instanceName}.h"
- ]]>
-</template></pre>
-<p>A more complicated example shows how script interacts with text.</p>
-<pre class="listing"><template location="HEADER_FILE"><![CDATA[
- <% if (properties.contextMenu != "") { %>
- #include <eikmenub.h>
- <% } %><br /> ]]>
-</template></pre>
-<p>Here, the “<%” escape allows entry of script which tests whether a property is non-empty. The JavaScript open block “{“ precedes the close script escape “%>”. Then, raw text is emitted inside the <strong>if</strong>, and then “<% } %>” closes the JavaScript <strong>if</strong> statement.</p>
-<p class="note"><strong>NOTE</strong> The braces are required when wrapping text inside "if" like this. The content outside the script escape is not guaranteed to be a single statement.</p>
-<h5><a name="inline"></a>Inline Element</h5>
-<p>The <inline> element may specify a segment of raw JavaScript.</p>
-<p>An <inline> element allows JavaScript to be embedded within a component definition file. Zero or more <inline> elements can be used to define script snippets. An <inline> element provides functions and properties used by templates and ordering with regard to <template> elements is preserved. The <inline> element defines code which is added to the current function, for example:</p>
-<pre><inline>contribs.clear();</inline></pre>
-<p>The scope=”…” attribute tells whether the script is placed in the current function (“function”) or at the file level (“file”). The scope=“file” attribute redirects content to the file, outside the current function (read: named template). For direct access to the prototype name, use “${jsObject}”. For example, to define an inheritable method in a current JavaScript object, use:</p>
-<pre><inline scope=“prototype”>${jsObject}.prototype.method = function(...) {...}</inline></pre>
-<p>Scripting Example:</p>
-<pre class="listing"><sourceGen>
- <template domain=“cpp” phase=“initcomponents” id=“foo”>
- <!-- references function added to prototype below -->
- ${id}->SetName(${specialFormatter(id.toString())});
- </template>
- <inline>
- <!-- adds method to prototype, which will be inherited -->
- ${jsObject}.prototype.specialFormatter = function(property) { return ... }
- </inline>
- <inline> <!-- standalone function accessible only from this component -->
- function checkFeatureX() { return properties[“hasFeatureX”] == “true”; }
- </inline>
- <template domain=“cpp” location=“#includes”>
- #include &lt;BaseHeader.h&gt;
- <!-- templates can escape to script too -->
- <% if (checkFeatureX()) { %>
- #include &lt;SpecialHeader.h&gt;
- <% } %>
- </template>
-</sourceGen></pre>
-<h5><a name="cdata"></a>CDATA Tag</h5>
-<p>As with any XML, text nodes must be escaped if it contains XML metacharacters like ‘<’, ‘>’, or ‘&’. Since C/C++ source code uses these a lot, it may be easiest and most readable to surround text blocks in “<!CDATA[“ … “]]>”. Everything inside a CDATA section is ignored by the XML parser. If your text contains a lot of "<" or "&" characters, which is common in program code, the XML element can be defined as a CDATA section. A CDATA section starts with "<![CDATA[" and ends with "]]>". For example:</p>
-<pre class="listing"><script>
-<![CDATA[
- function match(a,b) {
- if (a < b && a < 0) then
- {
- return 1
- }
- else<br /> {
- return 0
- }
- }
-]]>
-</script></pre>
-<p>A CDATA section cannot contain the string "]]>", therefore, nested CDATA sections are not allowed. Also make sure there are no spaces or line breaks inside the "]]>" string.</p>
-<h5><a name="forms"></a>Forms</h5>
-<p>A form is used to filter contributions, for the case where a component may have completely different styles of source generation based on its parent. A parent passes a regular expression for permissible forms down to its children when asking for their contributions. Only contributions matching the form's regular expression are generated.</p>
-<p>Therefore, a template’s form attribute (if specified) filters the contribution of the parent container, for example a CEikEdwin is defined differently if hosted in a CCoeComponent versus in a CEikDialog. A form is passed down when a parent generates child contributions. The form may be null if the parent dictates no special child source generation pattern.</p>
-<p>Every template element’s form attribute (either explicit or inherited from templateGroup) determines which parents will see it. If no form is defined, then contribution is always used, no matter what form the parent uses. If form is defined, then use it only if parent’s form matches. If form is defined as “ALL”, then always use, regardless of the parent’s form. If an element defines a form, different elements may share “id” (only one instance will be used). This aids inheritance, but the ids of elements sharing a form must not intersect.</p>
-<p>Form Example:</p>
-<pre class="listing"><sourceGen>
- <templateGroup form=“CEikDialog”>
- <template phase=“initcomponents” id=“foo”>
- ${id} =static_cast&lt;CEikEdwin*&gt; (ControlOrNull(${property[“dialogId”]}));
- </template>
- <template phase=“parenting”> ... </template>
- </templateGroup>
- <templateGroup form=“default”>
- <template phase=“initcomponents” id=“foo”> <!-- note: “id” can be shared in different forms -->
- ${id} = new (ELeave) CEikEdwin;
- ...
- iCoeEnv-&gt;CreateResourceReaderLC (reader, ${property[“rssName”]});
- </template>
- <template phase=“parenting”> ... </template>
- </templateGroup>
-</sourceGen></pre>
-<h3><a name="macros" id="macros"></a>Macros</h3>
-<p>Source generation elements may be packaged in macros and expanded later, allowing for the often complex collection of <defineLocation>, <template> elements to be stored in a pattern once and used multiple times.</p>
-<h4>Defining Macros</h4>
-<p>A macro consists of arguments and common sourcegen elements. A macro may be built from other macros by importing their arguments and expanding them as part of its definition. Macro arguments are untyped strings, which are referenced by name. An argument may be marked as optional, required, having a default value, or having no value at all if unspecified.</p>
-<p>Arguments may be referenced anywhere in the XML of the sourcegen elements that define the macro (attributes or text). They take the form “$(<macro name>)”. The use of parentheses instead of curly braces allows templates to use expression escapes without escaping them. Arguments may take modifiers when they are expanded, to perform common functions like testing them for being defined, converting them to strings, converting case, etc.</p>
-<h4>Macro Expansion</h4>
-<p>Macros may be expanded almost anywhere inside the sourcegen XML. Arguments may be passed as XML attributes named after the argument names, for convenience, or multi-line arguments may be passed as explicit XML sub-elements. The former syntax allows great brevity when using macros. When defining macros built upon other macros, then a macro expansion implicitly passes any arguments it was passed that match the argument list of the one it is calling. There are ways to suppress this behavior, as well. Again, these provisions make for brevity in defining macros as well.</p>
-<h4>XML Syntax</h4>
-<p>Defining macros example:</p>
-<pre class="listing"><defineMacro id="GenerateAssert" help="Generate an assertion call" >
- <macroArgument name="LocationId" help="The location id into which to place the call" />
- <macroArgument name="Expr" help="The expression to test" />
- <macroArgument name="Label" optional="true" default="Assertion failed!" help="The label to emit with an assertion error" />
- <template location="$(LocationId)"><![CDATA[
- if (!($(Expr)))
- {
- printf("%s: %s\\n", $(Label::as-string), $(Expr::as-string));
- }
- >]]><br /> </template>
-</defineMacro> </pre>
-<p>The “id” defines the name of the macro as used in <expandMacro>. The “LocationId” and “Expr” arguments are simple strings which must be provided by the client. The “Label” argument is optional and has a default value.</p>
-<p>The <template> contained in the macro expands the “LocationId” argument in an XML attribute and inside the template text itself. “Expr” is substituted into the template body twice: once, without translation, into the “if”, and again, into the printf() call, after being converted to a literal string (i.e., adding quotes and escaping embedded quotes). “Label” is substituted similarly.</p>
-<h5>Detailed syntax</h5>
-<p>The <defineMacro> element defines a macro consisting of a set of templates and inlines which may be variable-substituted.</p>
-<p>The <defineMacro> element consists of zero or more <importArguments> elements followed by any number of <macroArgument> elements, and finally followed by any number of <template>, <inline>, <defineLocation>, and <expandMacro> elements.<br />
- <br />
- <defineMacro> takes these attributes:</p>
-<ul>
- <li><strong>id</strong> (string) — The name of the macro</li>
- <li><strong>help</strong> (string) — Help text</li>
-</ul>
-<p><importArguments> brings in argument declarations from another macro, including their default values and “required” flag.</p>
-<p><importArguments> takes these attributes:</p>
-<ul type="disc">
- <li><strong>macroName</strong> (string) — The name of the macro to reference.</li>
- <li><strong>arguments</strong> (list of strings) — The space-separated list of argument names to import. This is mutually exclusive with 'exceptArguments'.</li>
- <li><strong>exceptArguments</strong> (list of strings) — The space-separated list of argument names NOT to import. All arguments are imported except these. This is mutually exclusive with 'arguments'.</li>
- <li><strong>help</strong> (string) — Help text</li>
-</ul>
-<p>The <macroArgument> element defines an argument for use with the macro. The default value may be specified in the 'default' attribute or in the text of the element. The text supercedes the attribute.</p>
-<p><macroArgument> takes these attributes:</p>
-<ul type="disc">
- <li><strong>name</strong> (string) — The name of the argument. This must be a legal JavaScript identifier and unique within the macro. Typically, macro argument names are title-cased so they will stand out in the macro definition and also so they may be used without conflict in <expandArgument> attributes (see below).</li>
- <li><strong>optional</strong> (boolean) — Tells whether the argument may be omitted from an expandMacro use. If true, and no default is provided, the variable's value is null.</li>
- <li><strong>default</strong> (string) — The default value of the argument if unspecified. Alternately, the text of this element may be supplied as the default, if formatting or newlines are used.</li>
- <li><strong>help</strong> (string) — Help text</li>
-</ul>
-<p>The included sourceGen elements, <template>, <inline>, and <defineLocation>, act as usual. Note that <templateGroup> is not allowed. Instead, if you need to pass the same parameters to several templates, then wrap the <expandMacro> call inside <templateGroup>. This restriction makes it easier to specify sourcegen inheritance and avoids the disallowed situation of nested <templateGroups>.</p>
-<p><expandMacro> may be used, as well, intermixed with the sourceGen elements mentioned above. By default, all the relevant arguments in the current macro will be passed to the macro named in <expandMacro> (including those taking default values). This allows macros to be safely built from each other without updating all of them if a common macro’s argument list changes. You may suppress this behavior, however. See <expandMacro> for specific details.</p>
-<h4><a name="macarg"></a>Macro argument modifiers</h4>
-<p>When macro arguments are referenced, they may take any number of modifers, which are in the syntax: <macro argument> { ‘::’ <modifier> }.<br />
- For example, “$(myName::to-title::as-string)”.</p>
-<p>Recognized modifiers are:</p>
-<ul>
- <li><strong>to-upper</strong>: convert value to upper case</li>
- <li><strong>to-lower</strong>: convert value to lower case</li>
- <li><strong>to-title</strong>: convert value to title case</li>
- <li><strong>as-string</strong>: convert argument to a string constant by adding double quotes and escaping</li>
- <li><strong>is-defined</strong>: resolves to ‘true’ if the macro is defined (even if empty), else ‘false’</li>
- <li><strong>append-space-unless-empty</strong>: results in the argument value with a trailing space, unless the argument is empty</li>
- <li><strong>add-spaces-unless-empty</strong>: results in the argument value with leading and trailing space, unless the argument is empty</li>
-</ul>
-<p>These modifiers work with argument values taking the canonical form of a function declaration’s argument list in C++, for example, with types, argument names, and optional default values:</p>
-<ul>
- <li><strong>as-function-declaration-args</strong>: identity</li>
- <li><strong>as-function-definition-args</strong>: removes default values</li>
- <li><strong>as-function-location-args</strong>: removes argument names and default values</li>
- <li><strong>as-function-call-args</strong>: removes types and default values</li>
- <li><strong>split-and-indent</strong>: primarily used for formatting argument lists. Converts a multi-item string, separated by commas, into multi-line format, with each line indented with two tabs. Empty or single-item argument lists are not modified.</li>
-</ul>
-<h4><a name="expmac"></a>Expanding macros</h4>
-<h5>Example:</h5>
-<pre class="listing"><expandMacro name="GenerateAssert" LocationId="ID_METHOD" Expr="6+7+'a'" /></pre>
-<p>or</p>
-<pre class="listing"><expandMacro name="GenerateAssert">
- <expandArgument name="LocationId">ID_METHOD</expandArgument>
- <expandArgument name="Expr">6+7+'a'</expandArgument>
-</expandMacro></pre>
-<p>Both of these have the same effect. In the first form, the argument names are used as XML attributes to <expandMacro>. Typically, the macro argument names are capitalized to emphasize the distinction between the fixed attributes in the XML schema and the dynamic attributes allowed for macro expansion. The second form explicitly passes arguments in the text part of the <expandArgument> element. This allows for multi-line arguments to be passed more clearly.</p>
-<p><expandMacro> expands a given macro into the sourceGen of the caller. This has the same effect as inserting the same templates and inlines from the macro's definition at the point of call. Variable references from those templates and inlines are substituted with the values provided in attributes (e.g. variableName="value") or expandArgument child elements. The latter may be preferred for cases where code is substituted, so the formatting may be retained.</p>
-<p><expandMacro> takes these arguments:</p>
-<ul>
- <li><strong>name</strong> (string): the name of the macro (from <defineMacro id=”...”>)</li>
- <li><strong>passArguments</strong> (list of string): A list of arguments defined in the current calling macro to pass unchanged to the called macro, excluding any arguments that are not defined in the current call.</li>
-</ul>
-<p>This attribute is only valid in expandMacro called from a defineMacro. Passing arguments is different from adding attributes argName="$(argName)" because it avoids defining otherwise undefined arguments. A missing optional argument is null, not the empty string. The '::is-defined' modifier can be used to check this.</p>
-<p>Elements in the list of strings are names of arguments, or renames of the form targetArgumentName=hostArgumentName which passes hostArgumentName from the hosting macro with the name targetArgumentName (again, only if the argument is actually defined in the call).</p>
-<p>If this argument is not specified, all arguments in the invoked macro are passed (zero or more may have defaults which are overridden in this macro). </p>
-<ul type="disc">
- <li><strong>dontPassArguments</strong> (list of string): This is primarily used when passArguments is not specified. It specifies which arguments not to pass to the invoked macro, which become undefined in the expansion of that macro. This is useful when this macro takes over the work of one or more arguments from the invoked macro.</li>
- <li><strong>help</strong> (string): help text</li>
-</ul>
-<p>The <expandArgument> element may appear any number of times inside <expandMacro> in place of using attributes to pass arguments. It takes these arguments:</p>
-<ul type="disc">
- <li><strong>name</strong> (string): the argument’s name</li>
- <li><strong>help</strong> (string): help text</li>
-</ul>
-<h3><a name="scriptref"></a>Script Reference</h3>
-<h4>Sourcegen Contribution Variables</h4>
-<p>These variables are available inside functions automatically generated by the <template> element.</p>
-<ul>
- <li><strong>contribs — </strong>The java.util.LinkedList of IContributions</li>
- <li><strong>contribText — </strong>The string containing the current text for the contribution (this is appended piecemeal by the raw text and ${expressions})</li>
- <li><strong>contrib — </strong>The current IContribution created from Engine.createContributionXXX. The contribText is applied to the contrib at the end of the <template></li>
- <li><strong>formrx — </strong>The regular expression string representing the current form passed down by the parent through Engine.createChildContributions().</li>
- <li><strong>properties — </strong>Same as instance.properties, to make property references clearer.</li>
-</ul>
-<h4>Instance Global Variables</h4>
-<p>The following variables are available for use within the sourceGen XML element and scripts. These augment the JavaScript globals.</p>
-<ul>
- <li><strong>src</strong> — the relative path to the primary source directory of the project</li>
- <li><strong>inc — </strong>the relative path to the primary include directory of the project</li>
- <li><strong>build — </strong>the relative path to the primary build directory of the project (e.g. “group”)</li>
- <li><strong>resource — </strong>the relative path to the primary resource directory of the project (e.g. “data”)</li>
- <li><strong>instanceName — </strong>the “name” property of the current instance</li>
- <li><strong>instanceMemberName — </strong>the name used for a member in a class (“i” + instanceName)</li>
- <li><strong>instanceName$title — </strong>title-cased instanceName (e.g. “Listbox”)</li>
- <li><strong>instanceName$upper — </strong>upper-cased instanceName (e.g. “LISTBOX”)</li>
- <li><strong>instanceName$lower — </strong>lower-cased instanceName (e.g. “listbox”)</li>
- <li><strong>resourceName — </strong>If the component defined a resource with the <sourceMapping> element, this is the primary resource name (e.g. “r_myview_listbox”). May be null if no resource is exported.</li>
- <li><strong>resourceName$upper — </strong>upper-cased resourceName (e.g. “R_MYVIEW_LISTBOX”)</li>
- <li><strong>resourceFileNameBase — </strong>base filename used for resources. This is the project name for “application.uidesign” and the design file’s base name otherwise.</li>
- <li><strong>className — </strong>name of the current class, if there is one. This is either the instance's own "className" property or that of the nearest enclosing parent (e.g. “CFoo”)</li>
- <li><strong>parentClassName — </strong>like "className", but the name of the nearest enclosing parent of the instance that provided "className".</li>
- <li><strong>handlerClassName — </strong>Name of the class for event handlers, which is the “className” property of the nearest enclosing component that defines the “event-handler-target” attribute to “true” (e.g. “CContainer”).</li>
- <li><strong>handlerInstanceName — </strong>The name property of the component instance providing handlerClassName (e.g. “container1”)</li>
-</ul>
-<p>When an event handler is being handled, triggered by ifEvents="..." matching a bound event, then the first matching event provides these variables:</p>
-<ul>
- <li><strong>event.eventId — </strong>the internal id of the event</li>
- <li> <strong>event.eventName — </strong>the display name of the event</li>
- <li> <strong>event.handlerName — </strong>the user-provided function name for the user event handler</li>
- <li> <strong>event.handlerSymbol — </strong>internal data for the location of the event handler function (this is currently the directory, filename, and location path to the function)<br />
- </li>
-</ul>
-<h4><a name="coneng"></a>Contribution Engine Routines</h4>
-<p>When generating source inside <sourceGen>, scripts have access to a library of routines related to generating contributions. All these are prefixed with “Engine.”, for example: <span class="code">Engine.createContributionForLocation()</span>.</p>
-<table border="1">
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>assignLocationsForPhase</strong>(contributions, phase, location)</td>
- <td><p>Assign locations to phased contributions without a location. The contributions with the given phase are assigned the given location. Parameters:</p>
- <ul>
- <li>contributions - the list of contributions; modified in place</li>
- <li>phase - the phase to match (must not be null)</li>
- <li>location - the location to assign</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>collateContributionsByPhase</strong>(contributions, phases)</td>
- <td><p>Collate contributions by phase. Takes a list of phase names and orders contributions so that they reflect the ordering of the phases. Note that this will have no effect if a contribution already has a location. Parameters:</p>
- <ul>
- <li>contributions - the list of contributions; modified in place</li>
- <li>phases - list of phases (null may be used to represent un-phased contributions)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>createContribution</strong>()</td>
- <td>Creates a contribution.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>createContributionForLocation</strong>(location)</td>
- <td><p>Create a contribution at a given location. Parameters:</p>
- <ul>
- <li>location - the unique location id, defined either in this location or some calling parent</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>createContributionForPhase</strong>(phase)</td>
- <td><p>Create a contribution for the given phase. Parameters:</p>
- <ul>
- <li>phase - the phase, for parent collation</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>createFromStockFile</strong>(directoryId, filename, stockPath)</td>
- <td><p>Create a stock file in the project from a file relative to the current component or an applicable base, if such file does not already exist. This is preferred to explicitly defining a location and applying a template when the file must not have any user-specified comment at the top or any variable expansion. Parameters:</p>
- <ul>
- <li>directoryId - the directory ID for the target (see INameGenerator#..._DIRECTORY_ID)</li>
- <li>filename - the filename within the directory for the target file</li>
- <li>stockPath - component-relative path to stock file</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>findBuiltinOrGeneratedEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
- <td><p>Find the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. The difference is, this routine does not generate a new enumerator; it returns null if none was generated. Parameters:</p>
- <ul>
- <li>instance</li>
- <li>propertyPath - path to the property @param uniqueValue the enumerator value which indicates a unique value was generated, or "*" if a unique value is always generated</li>
- <li>nameAlg - the unique name algorithm used</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>findDefiningFileForEnumerator</strong>(enumerator)</td>
- <td>Get the filename where this enumerator is declared.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>findGeneratedRssFiles</strong>(regex)</td>
- <td>Get the list of RSS generated files matching the given pattern.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>findLocation</strong>(locationId)</td>
- <td><p>Look up the ILocation for the given location id. Parameter:</p>
- <ul>
- <li>locationId - name of the location</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>findOrCreateEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
- <td><p>Find or create the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. This routine can create new enumerators. Such enumerators will be created in a globally accessible file (i.e. an HRH file for the application). If the enumerator was generated before but not visible in the DOM, this recreates it. Parameters:</p>
- <ul>
- <li>instance</li>
- <li>propertyPath - path to the property</li>
- <li>nameAlg - the unique name algorithm used</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>formMatches</strong>(form, forms)</td>
- <td>Tell whether the given form regex matches any of the forms in the array.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>generateAllViewContributions</strong>(form)</td>
- <td><p>Generate the "glue" contributions for all the view data models. These are the contributions that an application needs to get from a view in order to register it. This automatically filters out contributions not matching the form, with the assumption that the default form templates will never apply to the case of generating from a view. Parameters:</p>
- <ul>
- <li>form - the sourcegen form to pass</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>generateChildContributions</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance child, form)</td>
- <td><p>Generate child contributions. Called by parent on each child. Parameters:</p>
- <ul>
- <li>form - a regular expression matching form names ("" = blank/no form)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>generateChildContributions</strong>(form)</td>
- <td>Generate all child contributions, in order.
- Parameters:
- <ul>
- <li>form - a regular expression matching form names ("" = blank/no form)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>generateRedirectedInstanceContributions</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, form, com.nokia.sdt.datamodel.adapter.IComponentInstance refInstance)</td>
- <td><p>Generate child contributions using a referencing instance for context. This is used when component instance A (refInstance) points to component instance B (instance), and instance B's sourceGen relies on properties and/or events from instance A. This supplies an additional parameter to sourceGen called 'refInstance' that can be queried. Note that none of the predefined variables are defined for refInstance, as they are for instance (e.g. children, properties, instanceName, or instanceMemberName). Parameters:</p>
- <ul>
- <li>instance - the instance to generate</li>
- <li>form - a regular expression matching form names ("" = blank/no form)</li>
- <li>refInstance - the instance holding a reference to this instance</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>generateViewContributions</strong>(viewFilePath, form)</td>
- <td>Generate the "glue" contributions for a view data model. These are the contributions that an application needs to get from a view in order to register it. This automatically filters out contributions not matching the form, with the assumption that the default form templates will never apply to the case of generating from a view.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getAllProjectViewDesigns</strong>()</td>
- <td>Get a list of project-relative paths specifying view designs.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getContributionsForForm</strong>(contributions, form)</td>
- <td><p>Return sublist of contribution matching the given form. Parameters:</p>
- <ul>
- <li>contributions - the list of contributions</li>
- <li>form - regular expression to match form ("" = blank/no form)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getContributionsForLocation</strong>(contributions, locationId)</td>
- <td><p>Return sublist of contribution matching the given location Id. Parameters:</p>
- <ul>
- <li>contributions - the list of contributions</li>
- <li>locationId - the location name (or null to match contributions without location)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getContributionsForPhase</strong>(contributions, phase)</td>
- <td><p>Return sublist of contribution matching the given phase. Parameters:</p>
- <ul>
- <li>contributions - the list of contributions</li>
- <li>phase - the phase (or null to match contributions without a phase)</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getGeneratedResource</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance)</td>
- <td>Get the unnamed resource generated for the given component.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getGeneratedResource</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, rsrcId)</td>
- <td><p>Get the unnamed resource generated for the given component. Parameters:</p>
- <ul>
- <li>instance - the component instance</li>
- <li>rsrcId - the identifier of the generated resource, or null </li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>getGlobalDictionary</strong>()</td>
- <td>Get global dictionary for one sourcegen pass. This is entirely for the use of sourcegen script. It provides common state which is available to all instances in a design when sources are generated; nothing persists past a save of the data model.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>queryEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
- <td><p>Query the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. This routine does not rely on an enumerator having been created and does not uniquify the value, and can possibly return a misleading result. Parameters:</p>
- <ul>
- <li>instance</li>
- <li>propertyPath - path to the property</li>
- <li>nameAlg - the unique name algorithm used</li>
- </ul></td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>removeContributionsForPhase</strong>(contributions, phase)</td>
- <td>Remove contributions with the given phase.</td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>removeDuplicateContributionsForLocation</strong>(contributions, location)</td>
- <td>Remove duplicate contributions based on location. The list is scanned for contributions matching the given location exactly. If such contributions have the same trimmed text, the duplicates are removed. Note that this doesn't account for any contributions implicitly supplied by the current component's <defineLocation> contributions. Either call this function from a caller or do not define possibly duplicatable content in <defineLocation> (you can supply this as <template> appearing at that location). </td>
- </tr>
- <tr bgcolor="white">
- <td align="left" valign="top" width="1%"><strong>titleCase</strong>(text)</td>
- <td> </td>
- </tr>
-</table>
-<p> </p>
-<h4><a name="debugging"></a>Debugging</h4>
-<p>In the <sourceGen> element, set the debug attribute to “true” to generate a dump of the generated JavaScript that is used to generate contributions. Alternately, the <strong>Components > Enable SourceGen Debugging...</strong> dialog may be used to enable debugging and specify the directory for generated JavaScript files.</p>
-<h3><a name="inheritance"></a>Inheritance</h3>
-<p>Source generation behavior allows inheritance by derived components, though it is not automatically inherited. If no <sourceGen> element appears in a derived component instance, the UI Designer automatically iterates the instance’s children and gathers contributions for them. If <sourceGen> does appear in a derived component, and left empty, then no source is generated for that component.</p>
-<p>If <sourceGen> appears in a derived component, it may</p>
-<ul>
- <li>Define entirely new source generation elements and have no interaction with its base</li>
- <li>Inherit as much as possible from the base</li>
- <li>Or mix the contributions, taking some from the base and providing the rest itself.</li>
-</ul>
-<p>A component can inherit from a base. For source generation, this implies automatic inheritance of the JavaScript base object, its locations, and its macros, but not of the behavior, which is explicitly inherited to allow selection and reordering.</p>
-<p class="note"><strong>NOTE</strong> Locations defined with realize="true" are not automatically realized in derived components.</p>
-<p>The <useTemplate> element is used to inherit <template> elements from base.</p>
-<p>The attribute “ids” lists the named <template> elements from the base component (“*” indicates all). A <template> element without an “id” cannot be inherited. This element can be repeated and ordered arbitrarily with other <template> elements. An “id” can only be referenced or defined once per <sourceGen> element.</p>
-<p>The <useTemplateGroup> element is used to inherit <templateGroup> elements from base. A standalone <useTemplateGroup> element inherits all named <template> elements, or can contain <useTemplate> elements to select specific sub-elements.</p>
-<p class="note"> <strong>NOTE</strong> All templates are implicitly named, or given ids, unless otherwise suppressed by specifying id="".</p>
-<p>All <inline> elements may be inherited from the base, if they are given ids. For inlines, on the other hand, ids are not implicitly defined inside <templateGroup>.</p>
-<div id="footer">Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. <br>License: <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a></div>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<title>Source Generation</title>
+<link rel="StyleSheet" href="../../../book.css" type="text/css"/>
+</head>
+<body bgcolor="#FFFFFF">
+<h2>Source Generation</h2>
+<p>The UI Designer supports generating C/C++ source code through a contribution-driven model. A component provides a <sourceGen> element which uses a series of XML elements to define locations, templates, and inline JavaScript code. These elements contribute, eventually, to an ordered list of "contributions" to source. Each component passes its contributions up to its parent, which collates them, and recursively passes them to its parent. The end result is a full set of contributions defining all the generated source.</p>
+<p>A contribution is an association of text and a high-level "location" in the project (for example, the "enum TValues" enumeration inside "class CMyClass" inside the file "inc/MyClass.h"). The text is generated either by template expansion or by explicit JavaScript code, or both. A location is defined relative to other locations and may represent either "unowned" code (which is generated once, when it is missed) or "owned" code (which is always regenerated).</p>
+<p>A contribution may have a "phase" instead of a location. A "phase" is a moniker for a location that will be resolved later, usually by the parent of a component instance. This may be used to collate contributons within a location, or for filtering, or other purposes. Using phases allows a component to target different parents which may have different location hierarchies. In the final list of contributions returned to the source generator, all phases must be resolved to locations.</p>
+<p>The concept of “phases” is intended to alleviate the need for children to know where they are generating code. Thus, a <template> for a child needn’t specify a location if it specifies a phase; the container will supply the location. This implies that the container explicitly “fixes up” child contributions by finding those with a matching phase and setting their locations. Contributions cannot supply their own locations if contributing to a phase.</p>
+<p>If a child wants to contribute code to other locations, it either defines its own location, derives from a known one, or contributes to a new phase that the appropriate parent(s) know how to handle.</p>
+<p>Usually, phases are used to reduce coupling between components that exist in hierarchies where the specific location ids or specific relations of locations to each other should not be hardcoded. For instance, a parent that generates a class may define several phases for children to use to contribute instance members, initialization statements, and #includes. The parent must resolve contribution phases to actual location ids before returning its contributions to its parent (using Engine.assignLocationsForPhase(List, String, String)).</p>
+<p>The internal format of <sourceGen> is a single JavaScript file, which is maintained in memory. The <sourceGen debug="true"> attribute or the <strong>Components > Configure SourceGen Debugging...</strong> dialog may be used to write this content to disk, for debugging.</p>
+<p>The <sourceGen> element may contain the <defineLocation>, <template>, <templateGroup>, <inline>, <useTemplate>, and <useTemplateGroup> elements in any order or number. The strict order of <template>, <useTemplate>, <inline> elements etc. will determine the ordering of contributions in files. Thus, the position of the first template that references the “CLASS” location determines where in “HEADER_FILE” the class will appear.</p>
+<p>The <sourceGen> element’s children are interpreted as a linear list of discrete operations, all of which are executed for each instance of an object in the data model. The ordering of these nodes directly corresponds to the order in which text will initially be generated.</p>
+<h3><a name="contrib"></a>Contributions</h3>
+<p>Each component definition file defines data and code which create contributions. A contribution is a piece of formatted text which is placed into source at a location associated with a domain. Each contribution has a domain and a location describing where to place the text. The complete source generation comes from an algorithm which places the pieces of text in the right locations. A contribution is not complete and cannot be processed by the domain until it has a location. It may exist in a transient state where only a phase is set. At some point (usually in a parent component) the phase is converted to a location. If a location referenced by contributions is missing, then it is created by applying the templates that define the location.</p>
+<p>Source contributions are gathered from the bottom and go up. Parents collate child contributions and the top level (data model) sorts contributions and generates source. The UI Designer backend engine interprets contributions and is familiar with specific languages. Source generation is expanded into JavaScript, defining a single JavaScript object that implements the IComponentSourceGen interface that returns a list of contributions to the parent.</p>
+<p>A contribution consists of:</p>
+<ul>
+ <li>A domain — the file-format semantic handler for source (currently, "cpp" is the only implemented domain for C/C++ sourcegen)</li>
+ <li>A location — the domain-specific path specifying where source goes</li>
+ <li>A phase — a container-specific tag used to collate child contributions</li>
+ <li>A form — a container-specific tag used to inform children how to generate source</li>
+ <li>A mode — a hint to the source generator about a way to treat the contribution</li>
+ <li>Content — the template or text that is inserted</li>
+</ul>
+<h3><a name="locations"></a>Locations</h3>
+<p>Locations are strings that identify a domain-specific location (currently only cpp) where generated source is placed. In the C/C++ domain, locations are paths that are specified structurally, with reference to easy navigation with the CDT DOM. To reference a location use a statement such as <template location=“<em>location-id</em>” ... />. The location must be in the same directory and file it was originally created in for the domain to find it.</p>
+<p>Locations are organized like file paths separated with ‘/’, with more encompassing items on the left, and children of those items on the right.</p>
+<p>Each path entry consists of a specifier and arguments:</p>
+<ul>
+ <li>specifier ‘(‘ argument [‘,’argument ...] ‘)’</li>
+</ul>
+<p>For example:</p>
+<blockquote>
+ <p> class(MyClass)/region(InstanceVariables) — A special block named “InstanceVariables” inside the class declaration “MyClass”</p>
+ <p>function(MyClass::initComponents()) — The function <span class="code">MyClass::initComponents() {}</span> in a file. Not <span class="code">class(MyClass)</span> then <span class="code">function(initComponents())</span> unless actually declaring the function inline.</p>
+</blockquote>
+<p>The identifier used in locations is lexically scoped. It can be resolved either in the current instance’s component or in a parent component that directly or indirectly invoked the contribution phase for this component. The location is not global except in the case of a “library” component. A top-level component can serve as such a library for this case. For example, a common pattern for locations which are intended for use by children could be to name them FILE, CLASS, or METHOD. Anything else can have a more descriptive name to distinguish it from other locations defined in parents.</p>
+<p>Every <template> element must have a phase or a location, but not both. For a phase, the container supplies the location for all matching phases. For a location, the template supplies the location by reference to <defineLocation> (either global or local).</p>
+<p>A location can be defined by a template that builds a location by drilling into a location passed from the parent, or one can be generated from scratch. A location describes a virtual path to actual source. A location is based on another location, such as a class inside a file, or on a file. A root location has no base and is defined by a relative directory and a filename within the current project. A derived location is defined as being contained within the bounds of its base location.</p>
+<p>For example, a base location may be the file foo.cpp in the directory "src". A derived location may be the CFoo::CFoo() function defined within that source file. Another location derived from this may be a local enumeration (TChoices) defined within that function. A derived location cannot provide two segments, such as jump directly from a file to an enum nested within a class. There must be one location defined per segment.</p>
+<p>A location can be created “inside” another, as long as that one is also defined. Defined locations have globally unique identifiers which are attached to contributions to place that contribution at the given location.</p>
+<p>When a parent component asks a child to generate contributions, the child can reference all its parent’s locations. Although, phases can be used instead to reduce coupling. A child may redefine a location that comes from a parent, but this change only has a local effect on the child’s source generation.</p>
+<p>A location is realized in source code when</p>
+<ul>
+ <li>its "realize" attribute is set to "true" in <defineLocation>,</li>
+ <li>when it is referenced by a <template> with location=”…”,</li>
+ <li>when script creates a contribution using <span class="code">Engine.createContributionForLocation()</span>,</li>
+ <li>or when a phase is resolved to a location with <span class="code">Engine.assignLocationsForPhase</span>.</li>
+</ul>
+<p>The location and any parent locations are created as needed. If they already exist in source, they are not regenerated. However, if they are owned by the UI Designer, they will be cleared out. Note that root locations will create missing directories and files.</p>
+<p>Locations may have filters that control whether a contribution is emitted to it. This is primarily used to check for unique code, for example, to avoid duplicate #includes, member declarations, and base class entries. Locations may be conditional if an event binding exists. The location would then only be declared if one of a given set of events is bound to an instance.</p>
+<p>Locations can be owned by the UI Designer or not owned. If owned, a “do not modify” comment is added automatically to the generated source. The location’s contents are cleaned out each time the source is generated. For example, source is regenerated for:</p>
+<ul>
+ <li>Instance variables for children of a container</li>
+ <li>Methods used to initialize child components</li>
+</ul>
+<p>If not owned, no comment is added. The location and its contributions are applied only if the location was created in this source generation phase. For example:</p>
+<ul>
+ <li>User-owned stub functions for event handlers, etc.</li>
+ <li>Example code copied from template</li>
+ <li>Initial file contents</li>
+ <li>Top-of-file ownership comments</li>
+</ul>
+<h4><a name="defloc"></a>DefineLocation Element</h4>
+<p>Every location is created in a specific directory and filename. To define a location, create a <defineLocation> element in the <sourceGen> element of a component definition file. All <defineLocation> entries are inherited automatically by derived components. </p>
+<p>The following is an example syntax of defining locations.</p>
+<pre class="listing"><defineLocation [baseLocation=“id” | domain=“...” dir=“...” file=“...” ] id=“...” location=“...” owned=“[true|false]” [ realize="true|false"]>
+ <template .... /> / <script ... /> / <inline ... />
+</defineLocation></pre>
+<p>The <strong>dir</strong> and <strong>file</strong> attributes specify the path and filename where the location is initially created; after that, the CDT DOM is used to find the location. The <strong>dir</strong> attribute tells what project-relative directory to use. The template variable may be used to look up a user-configured directory. For example, ${src}, ${inc}, ${resource}, ${build}, or ${aif}. A path may be applied to enter the directory.</p>
+<p>Examples:</p>
+<ul>
+ <li>${src} --> “<project>/src”</li>
+ <li>${build} --> “<project>/group”</li>
+ <li>${inc}/subdir --> “<project>/inc/subdir”</li>
+ <li>./data or data --> “<project>/data”</li>
+</ul>
+<p>The filename is specified with the <strong>file</strong> attribute.</p>
+<p>Examples:</p>
+<ul>
+ <li>dir=“${src}” file=“fixedname.cpp” --> “<project>/src/fixedname.cpp”</li>
+ <li>dir=“${inc}/sys” file=“C${viewName}.h” --> “<project>/inc/sys/CMyView.h”</li>
+</ul>
+<p>The <strong>location</strong> attribute specifies the domain-specific location details. The <strong>owned</strong> attribute defines whether the section of code is owned (rewritten) or not owned by the UI Designer. The <template>, <script>and <inline> nodes provide the code that creates the contents for a referenced location if it is missing.</p>
+<p>The dir, file, and location attributes use a common pattern for handling variable and template-expanded arguments. Arguments are specifed with this syntax: ${variable}.</p>
+<p>Standard variables include:</p>
+<ul>
+ <li>${className} — name of component class from XML (e.g. CEikSlider)</li>
+ <li>${instanceName} — name of the component instance</li>
+ <li>${resourceName} — name of generated resource for instance (e.g. “r_test0”)</li>
+</ul>
+<p>Variables in locations refer to the current component, however locations can be used in child components or other components. A location is expanded with respect to the component that generates a contribution using that location. A child component which sets “phase” does not set location.</p>
+<p>Therefore, the location is expanded relative to the parent which supplied the location to the child. The child can still derive a location from specific location ids in the parent. In such a case, the parts that the child adds are expanded relative to the child.</p>
+<p>For example, the parent sets dir=“${src}”, file=“C${viewName}.h”, and location=“class(C${baseComponentId})”, and passes this to the children for the addInstanceVariables phase. The child gets the fully specified dir/file/location attributes that reference the parent component, but it can derive a location with a custom use of ${baseComponentId}, which will be expanded to its own component base.</p>
+<p>The <defineLocation> element declares and defines locations which may be used by contributions. For example:</p>
+<pre class="listing"><defineLocation id="HEADER_FILE" domain="cpp" dir="${inc}"
+ file="${instanceName}.h"
+ owned="false"
+ location=""><br /></defineLocation></pre>
+<p> This example describes a root location which is a header file. The <strong>domain</strong>, <strong>dir</strong>, and <strong>file</strong> attributes are required for root locations, and the <strong>location </strong>attribute must be empty. The <strong>dir</strong> and <strong>file</strong> attributes are template-expanded by referencing the instance global variables. For instance, “${inc}” defines the directory used for includes, and “${instanceName}” is the name of the current instance, so the file will be named after the instance.</p>
+<p>Following is an example of a derived location where the location is understood as a class definition in the header file.</p>
+<pre class="listing"><defineLocation id="CLASS" baseLocation="HEADER_FILE"
+ owned="false"
+ location="class(${className})">
+ <template>
+ …
+</defineLocation></pre>
+<p>Common to any <defineLocation> element are the following attributes:</p>
+<ul>
+ <li><strong>id=”<string>”</strong> is used to reference the location. Location ids must be unique in a component. Locations can be overridden in derived components by using the same id.</li>
+ <li><strong>location=”<string>” </strong>is the segment of the location added to a base (“” for files). These are interpreted relative to the domain. All together, the segments from the root to a location are considered the “location path.” See <a href="#cpplocseg">cpp location segments</a> for syntax.<br />
+ Note that only one location may map a given location path. Otherwise you will get errors to this effect when generating source. In other words, if you use the same location path, use the same location id.</li>
+ <li><strong>owned=”<<em>boolean</em>>” </strong>tells whether the given location will be regenerated every time (true) or generated only if missing (false).</li>
+</ul>
+<blockquote>
+ <p><span class="note"><strong>NOTE</strong> The user might delete a generated owned location. When it is regenerated, it will <strong>not </strong>go in the original location again, but to the end of the parent location. This is a known limitation.</span></p>
+</blockquote>
+<ul>
+ <li><strong>filter=”<<em>filter-name</em>>” </strong>defines the particular filter to apply (either “unique-includes” for regions, “unique-prototypes” for classes, or “unique-bases” for base class lists).</li>
+ <li><strong>ifEvents=”<list of events>” </strong>defines the space-separated list of event names; one of which must be defined in order to declare the location. Such locations are conditionally available. Their ids are not available unless a matching event is bound. Thus, any references to event-derived variables like eventHandlerName or eventInstanceName will not trigger errors unless the event is bound.</li>
+ <li><strong>isEventHandler=”<<em>boolean</em>>” </strong>is used to locate a particular method when adding events in the editor. This method applies to the <em>user-editable function</em> to edit. It is only used if the <strong>ifEvents </strong>attribute is set.</li>
+ <li><strong>realize="<boolean>"</strong> if set to "true", forces a location to be realized in source when it is encountered. Otherwise, the location will not exist in source unless a template contributes to it. (If a location is defined inside conditional sourcegen, guarded by ifEvents="..." or ifExpr="...", then the location will only be realized if the expression is true.)</li>
+</ul>
+<p> A <defineLocation> element may include a number of <template> or <inline> elements. When a location is realized, the contained templates and inline blocks are executed to define it. The templates are responsible for contributing the text that will correctly define the location, optionally populating it with initial content.</p>
+<p>In the example above, the header file location has no templates, since an empty file is a valid file. Although, to define a class, the definition must be provided:</p>
+<pre class="listing"><defineLocation id="CLASS" baseLocation="HEADER_FILE"
+ owned="false"
+ location="class(${className})">
+ <template><br /> <![CDATA[
+ /**
+ * Container class for ${instanceName}
+ *
+ * @class ${className} ${instanceName}.h
+ */
+ class ${className} : public CCoeControl
+ {
+ public:
+ // constructors and destructor
+ ${className}();
+ virtual ~${className}();
+ };
+ ]]>
+ </template>
+</defineLocation></pre>
+<p>Note that the variable expansion ${className} is used inside the <strong>location</strong> attribute. These same variables are available in the text and substituted using the same syntax, although the semantics are different. See <a href="#template"><template></a> element for more details.</p>
+<h5><a name="cpplocseg" id="cpplocseg"></a>Cpp location segments</h5>
+<p>A location segment in the cpp domain is a string representing a node in a C/C++ parse tree. Each takes the syntax “<name> ‘(‘ <arguments…>‘)’”. Certain nodes may only appear within certain others. This list defines top-level nodes:</p>
+<ul>
+ <li><strong>class(<name>)</strong> <strong>— </strong>references the class declaration for the class ‘name’, which may include namespaces (for example, “class(MyClass)” or “class(${className})”)</li>
+ <li><strong>function(<name>(<arguments…))</strong> <strong>— </strong>references a function with the given signature. A ‘name’ may include namespaces or represent a destructor. The ‘arguments’ are a comma-separated list of types. This list of arguments must specify the correct type information, for example "const TInt&". This allows overridden methods to be defined and referenced. The arguments list may end in ellipsis (“…”) to indicate that any zero or more arguments are matched. Again, the <template> inside a <defineLocation> really defines the function, which for a class method means that most of the information is repeated a few lines down. Using macros like GenerateMethod may be more succinct. Examples of function locations are: “<span class="code">function(main(int,char**))</span>” or “<span class="code">function(${className}::method(void*))</span>”.</li>
+ <li><strong>region(<name>)</strong> <strong>— </strong>a region defines a commented block of text with no other syntactical clues. The block comments and the name are used to identify the block. Usually, regions appear at the top level of the file or inside other locations, typically to provided owned sections therein. These need to be unique in the context of their parent. (For instance, every non-owned method in a file may reuse the name "Generated Code" for their embedded owned blocks.) For example, “region(Generated Includes)”.</li>
+ <li><strong>enum(<name>)</strong> <strong>— </strong>an enum declaration with the given name. Name must be non-empty. Locations are used to look up source, so anonymous enums cannot be unambiguously identified. For example, “enum(T${className}Ids)”.</li>
+ <li><strong>namespace(<name>)</strong> <strong>— </strong>a namespace declaration with the given name, which may contain colons. For example, “namespace(std::tr1)”.</li>
+ <li><strong>to-file()</strong> <strong>— </strong>resolves to the current file of a location, that is, back to the root location.</li>
+</ul>
+<blockquote>
+ <p>Inside a class(), namespace() is not allowed, and this additional segment is allowed.</p>
+</blockquote>
+<ul>
+ <li><strong>bases()</strong> <strong>— </strong>references the base-class-list within a class declaration. If the class defining text already includes a base, then the defining text for the bases() location may be omitted. If a class defining text does not include a base, the bases() location must include the leading colon in its defining text. Otherwise, contributions are individual class references with leading commas.</li>
+</ul>
+<blockquote>
+ <p>In a function(), only class(), region(), enum(), and to-file() are allowed.</p>
+ <p>In an enum(), bases() or region(), only region() and to-file() are allowed. </p>
+</blockquote>
+<h3><a name="filterloc"></a>Owned/Non-owned/Filtered Locations</h3>
+<p>The term "owned" refers to a section of code which is always rewritten by the UI Designer. Such sections are either associated with specific C/C++ syntactic elements, such as classes, functions, and enums. These sections may also appear as a region within such an element or at the file level. Any user edits within the comments are lost. These comments look like:</p>
+<blockquote>
+ <pre>// [[[ begin generated region: do not modify! [Generated User Includes]
+ <strong>#include</strong> "MyForm.h"
+ <strong>#include</strong> "My.rsg"
+// ]]] end generated region [Generated User Includes]</pre>
+</blockquote>
+<p><strong></strong>The term "non-owned" refers to anything outside the “owned” comments. In this example, the function is non-owned, since there is no comment around it. The user is allowed to change anything before or after the owned region inside the function.<strong></strong></p>
+<blockquote>
+ <pre class="listing">/**
+* Construct the MyForm instance
+* @param aCommandObserver command observer
+*/
+MyForm::MyForm( MEikCommandObserver* aCommandObserver )
+ {
+ iCommandObserver = aCommandObserver;
+ // [[[ begin generated region: do not modify! [Generated Contents]
+ // ]]] end generated region [Generated Contents]
+ }</pre>
+</blockquote>
+<p>"Filtered" refers to non-owned locations which have the "filter" attribute specified. Even if the location already exists, every contribution will be considered and added if it does not pass the filter.</p>
+<h3>Elements</h3>
+<h4><a name="template" id="template"></a>Template element</h4>
+<p>A <template> element defines text for contributions. Ordering of <template> contributions is retained for the parent. The <template> element attributes include:</p>
+<ul>
+ <li>domain — name of contribution domain</li>
+ <li>location — domain-specific syntax, optional if phase is set</li>
+ <li>mode — optional; used to attach semantics to location</li>
+ <li>phase — used for ordering, optional if location is set</li>
+ <li>form — optional; used to adapt to parent requirements</li>
+ <li>ifEvents=”<list of events>” — optional; if any one of the space-separated event names is bound on the current instance, then the template is emitted.</li>
+ <li>ifExpr="<expression>" — if the JavaScript expression evaluates to true, the template is emitted.</li>
+ <li>id="<name>" — optional; the unique identifier of the template, within a component or a template group. Only templates with ids, even if included in a templateGroup, may be inherited.</li>
+</ul>
+<p> A <templateGroup> element combines several <template> elements into a named group. Grouping is strictly a convenience and has no impact on generated script. Attributes of <templateGroup> are automatically applied to the contained <template> elements. The attribute “id” may be specified to name the group. Included templates have a unique “id” namespace.</p>
+<p>Example:</p>
+<pre class="listing"><sourceGen>
+ <templateGroup form="CAknView"> <!-- group of templates inhheriting form -->
+ <template phase=“initcomponents” id=“foo”>
+ ${instanceName}->SetName(${instanceName.toString()});
+ </template>
+ <template phase=“parenting”>
+ ${parent.instanceName}->Add(${instanceName});
+ </template>
+ </templateGroup>
+ <template location="INCLUDES"> <!-- standalone template -->
+ #include <akndialog.h> <!-- XML needs to be escaped unless in <![CDATA[...]]> -->
+ </template>
+</sourceGen></pre>
+<p>The lines in text nodes of templates should be flush left on the line, unless multiple lines are defined, where some of the lines have more indentation. If extra indentation is added, use the tab character only. The source generator will convert tabs to spaces according to the workspace settings. The nesting of a particular location defines the indentation level. The indentation for a contribution may be adjusted with a script escape at the start of the node, for example:</p>
+<pre class="listing"><template location=”CLASS”><![CDATA[
+ <% contrib.indentAdjust(-1); %>protected: ]]>
+</template></pre>
+<p>The object “contrib” refers to the IContribution instance currently being generated, which is automatically available for any <template>. The argument specifies the number of levels to adjust. This example outdents the “protected:” line in a class declaration.</p>
+<p>Except for the very beginning and very end, almost every character is used in the template’s text. After the end of the <template> open-element, any spaces and newlines are removed if present before the </template> close-element. Any whitespace on any line before the </template> close-element is also removed. Such line stripping does not occur when escapes are used. Thus, script escapes often need to start at the very end of the previous line or end at the very start of the next line in order to avoid spurious newlines in the generated text.</p>
+<h5>Expression Escapes</h5>
+<p>A <template> element is converted into a small JavaScript function that at runtime generates segments of text into source, in a manner similar to JSP. Initially, the text in a template is converted into code that inserts literal text into source. Placeholders in the form ${expression} may appear in literal text. These resolve to JavaScript expressions whose string representations are inserted into source. If expressions involve complex expressions, enclose them in parentheses.</p>
+<p>Most attributes in <sourceGen> XML also allows for syntax that resembles expression escapes. Such attributes, however, are not evaluated in JavaScript. Such expansions may only reference variable names, not expressions. A set of predefined variables is a subset of that available to script, with some extensions to account for common operations:</p>
+<p><strong>${src}</strong>: the source directory used when creating the project<br />
+ <strong>${inc}</strong>: the source directory used when creating the project<br />
+ <strong>${build}</strong>: the build directory used when creating the project (e.g. "group")<br />
+ <strong>${resource}</strong>: the resource directory used when creating the project (e.g. "data")</p>
+<p><strong>${projectName}</strong>: the name of the generated project<br />
+ <strong>${instanceName}</strong>: the name property of the current instance<br />
+ <strong>${instanceName$title}</strong>: the titlecased version of the instance name, with the first letter capitalized (e.g. "my_var" becomes "My_var")<br />
+ <strong>${instanceName$upper}</strong>: the uppercase version of the instance name<br />
+ <strong>${instanceName$lower}</strong>: the lowercase version of the instance name<br />
+ <strong>${instanceMemberName}</strong>: the expected name for an instance variable for this component instance: 'i' + the titlecased version of the instance name<br />
+ <strong>${className}</strong>: the value of the 'className' property in the nearest enclosing parent (or the current instance) that defines it. May be null. <br />
+ <strong>${parentClassName}</strong>: like ${className}, but the className property of the next enclosing instance. Note that this is not related to nesting of classes.<br />
+ <strong>${handlerClassName}</strong>: this is the value of the 'className' property for the nearest enclosing parent (or the current instance) which defines the attribute 'event-handler-target' to "true". May be null.<br />
+ <strong>${handlerInstanceName}</strong>: this is the value of the 'name' property for the nearest enclosing parent (or the current instance) which defines the attribute 'event-handler-target' to "true". May be null.<br />
+</p>
+<p>These variables are available if the component generates resources (see <a href="cc_source_mapping.htm">RSS Source Mapping</a>):</p>
+<p><strong>${resourceName}</strong>: the name of the primary generated resource for the instance. May be null.<br />
+ <strong>${resourceName$upper}</strong>: the uppercase name of the primary generated resource, as used for the macro in the .rsg file. May be null.<br />
+ <strong>${resourceFileNameBase}</strong>: the filename, without extension, used for the resources this instance generated. May be null.</p>
+<h5>Script Escapes</h5>
+<p>Script escaped in <%...%> blocks specifies JavaScript code which is inserted directly into the generated function to control the source generation process. This escape usually either surrounds raw text in a condition, adds looping, or creates contributions programmatically. The entire sequence of text, including escapes, is interpreted in order, and expanded into a sequence of script. Raw text should be understood as script that emits the given raw text.</p>
+<p>For example, a loop that iterates properties may be specified like this:</p>
+<pre class="listing"><template>
+ <% for (var property in properties) { %>
+ ${instanceName}->Set${titleCase(property.name)}
+ (${property.value});
+ <% } %>
+</template></pre>
+<p>This example shows expressions. Here, the instanceName is expanded and emitted in line with the raw text around it.</p>
+<pre class="listing"><template location="HEADER_FILE"><![CDATA[
+ #include "${instanceName}.h"
+ ]]>
+</template></pre>
+<p>A more complicated example shows how script interacts with text.</p>
+<pre class="listing"><template location="HEADER_FILE"><![CDATA[
+ <% if (properties.contextMenu != "") { %>
+ #include <eikmenub.h>
+ <% } %><br /> ]]>
+</template></pre>
+<p>Here, the “<%” escape allows entry of script which tests whether a property is non-empty. The JavaScript open block “{“ precedes the close script escape “%>”. Then, raw text is emitted inside the <strong>if</strong>, and then “<% } %>” closes the JavaScript <strong>if</strong> statement.</p>
+<p class="note"><strong>NOTE</strong> The braces are required when wrapping text inside "if" like this. The content outside the script escape is not guaranteed to be a single statement.</p>
+<h5><a name="inline"></a>Inline Element</h5>
+<p>The <inline> element may specify a segment of raw JavaScript.</p>
+<p>An <inline> element allows JavaScript to be embedded within a component definition file. Zero or more <inline> elements can be used to define script snippets. An <inline> element provides functions and properties used by templates and ordering with regard to <template> elements is preserved. The <inline> element defines code which is added to the current function, for example:</p>
+<pre><inline>contribs.clear();</inline></pre>
+<p>The scope=”…” attribute tells whether the script is placed in the current function (“function”) or at the file level (“file”). The scope=“file” attribute redirects content to the file, outside the current function (read: named template). For direct access to the prototype name, use “${jsObject}”. For example, to define an inheritable method in a current JavaScript object, use:</p>
+<pre><inline scope=“prototype”>${jsObject}.prototype.method = function(...) {...}</inline></pre>
+<p>Scripting Example:</p>
+<pre class="listing"><sourceGen>
+ <template domain=“cpp” phase=“initcomponents” id=“foo”>
+ <!-- references function added to prototype below -->
+ ${id}->SetName(${specialFormatter(id.toString())});
+ </template>
+ <inline>
+ <!-- adds method to prototype, which will be inherited -->
+ ${jsObject}.prototype.specialFormatter = function(property) { return ... }
+ </inline>
+ <inline> <!-- standalone function accessible only from this component -->
+ function checkFeatureX() { return properties[“hasFeatureX”] == “true”; }
+ </inline>
+ <template domain=“cpp” location=“#includes”>
+ #include &lt;BaseHeader.h&gt;
+ <!-- templates can escape to script too -->
+ <% if (checkFeatureX()) { %>
+ #include &lt;SpecialHeader.h&gt;
+ <% } %>
+ </template>
+</sourceGen></pre>
+<h5><a name="cdata"></a>CDATA Tag</h5>
+<p>As with any XML, text nodes must be escaped if it contains XML metacharacters like ‘<’, ‘>’, or ‘&’. Since C/C++ source code uses these a lot, it may be easiest and most readable to surround text blocks in “<!CDATA[“ … “]]>”. Everything inside a CDATA section is ignored by the XML parser. If your text contains a lot of "<" or "&" characters, which is common in program code, the XML element can be defined as a CDATA section. A CDATA section starts with "<![CDATA[" and ends with "]]>". For example:</p>
+<pre class="listing"><script>
+<![CDATA[
+ function match(a,b) {
+ if (a < b && a < 0) then
+ {
+ return 1
+ }
+ else<br /> {
+ return 0
+ }
+ }
+]]>
+</script></pre>
+<p>A CDATA section cannot contain the string "]]>", therefore, nested CDATA sections are not allowed. Also make sure there are no spaces or line breaks inside the "]]>" string.</p>
+<h5><a name="forms"></a>Forms</h5>
+<p>A form is used to filter contributions, for the case where a component may have completely different styles of source generation based on its parent. A parent passes a regular expression for permissible forms down to its children when asking for their contributions. Only contributions matching the form's regular expression are generated.</p>
+<p>Therefore, a template’s form attribute (if specified) filters the contribution of the parent container, for example a CEikEdwin is defined differently if hosted in a CCoeComponent versus in a CEikDialog. A form is passed down when a parent generates child contributions. The form may be null if the parent dictates no special child source generation pattern.</p>
+<p>Every template element’s form attribute (either explicit or inherited from templateGroup) determines which parents will see it. If no form is defined, then contribution is always used, no matter what form the parent uses. If form is defined, then use it only if parent’s form matches. If form is defined as “ALL”, then always use, regardless of the parent’s form. If an element defines a form, different elements may share “id” (only one instance will be used). This aids inheritance, but the ids of elements sharing a form must not intersect.</p>
+<p>Form Example:</p>
+<pre class="listing"><sourceGen>
+ <templateGroup form=“CEikDialog”>
+ <template phase=“initcomponents” id=“foo”>
+ ${id} =static_cast&lt;CEikEdwin*&gt; (ControlOrNull(${property[“dialogId”]}));
+ </template>
+ <template phase=“parenting”> ... </template>
+ </templateGroup>
+ <templateGroup form=“default”>
+ <template phase=“initcomponents” id=“foo”> <!-- note: “id” can be shared in different forms -->
+ ${id} = new (ELeave) CEikEdwin;
+ ...
+ iCoeEnv-&gt;CreateResourceReaderLC (reader, ${property[“rssName”]});
+ </template>
+ <template phase=“parenting”> ... </template>
+ </templateGroup>
+</sourceGen></pre>
+<h3><a name="macros" id="macros"></a>Macros</h3>
+<p>Source generation elements may be packaged in macros and expanded later, allowing for the often complex collection of <defineLocation>, <template> elements to be stored in a pattern once and used multiple times.</p>
+<h4>Defining Macros</h4>
+<p>A macro consists of arguments and common sourcegen elements. A macro may be built from other macros by importing their arguments and expanding them as part of its definition. Macro arguments are untyped strings, which are referenced by name. An argument may be marked as optional, required, having a default value, or having no value at all if unspecified.</p>
+<p>Arguments may be referenced anywhere in the XML of the sourcegen elements that define the macro (attributes or text). They take the form “$(<macro name>)”. The use of parentheses instead of curly braces allows templates to use expression escapes without escaping them. Arguments may take modifiers when they are expanded, to perform common functions like testing them for being defined, converting them to strings, converting case, etc.</p>
+<h4>Macro Expansion</h4>
+<p>Macros may be expanded almost anywhere inside the sourcegen XML. Arguments may be passed as XML attributes named after the argument names, for convenience, or multi-line arguments may be passed as explicit XML sub-elements. The former syntax allows great brevity when using macros. When defining macros built upon other macros, then a macro expansion implicitly passes any arguments it was passed that match the argument list of the one it is calling. There are ways to suppress this behavior, as well. Again, these provisions make for brevity in defining macros as well.</p>
+<h4>XML Syntax</h4>
+<p>Defining macros example:</p>
+<pre class="listing"><defineMacro id="GenerateAssert" help="Generate an assertion call" >
+ <macroArgument name="LocationId" help="The location id into which to place the call" />
+ <macroArgument name="Expr" help="The expression to test" />
+ <macroArgument name="Label" optional="true" default="Assertion failed!" help="The label to emit with an assertion error" />
+ <template location="$(LocationId)"><![CDATA[
+ if (!($(Expr)))
+ {
+ printf("%s: %s\\n", $(Label::as-string), $(Expr::as-string));
+ }
+ >]]><br /> </template>
+</defineMacro> </pre>
+<p>The “id” defines the name of the macro as used in <expandMacro>. The “LocationId” and “Expr” arguments are simple strings which must be provided by the client. The “Label” argument is optional and has a default value.</p>
+<p>The <template> contained in the macro expands the “LocationId” argument in an XML attribute and inside the template text itself. “Expr” is substituted into the template body twice: once, without translation, into the “if”, and again, into the printf() call, after being converted to a literal string (i.e., adding quotes and escaping embedded quotes). “Label” is substituted similarly.</p>
+<h5>Detailed syntax</h5>
+<p>The <defineMacro> element defines a macro consisting of a set of templates and inlines which may be variable-substituted.</p>
+<p>The <defineMacro> element consists of zero or more <importArguments> elements followed by any number of <macroArgument> elements, and finally followed by any number of <template>, <inline>, <defineLocation>, and <expandMacro> elements.<br />
+ <br />
+ <defineMacro> takes these attributes:</p>
+<ul>
+ <li><strong>id</strong> (string) — The name of the macro</li>
+ <li><strong>help</strong> (string) — Help text</li>
+</ul>
+<p><importArguments> brings in argument declarations from another macro, including their default values and “required” flag.</p>
+<p><importArguments> takes these attributes:</p>
+<ul type="disc">
+ <li><strong>macroName</strong> (string) — The name of the macro to reference.</li>
+ <li><strong>arguments</strong> (list of strings) — The space-separated list of argument names to import. This is mutually exclusive with 'exceptArguments'.</li>
+ <li><strong>exceptArguments</strong> (list of strings) — The space-separated list of argument names NOT to import. All arguments are imported except these. This is mutually exclusive with 'arguments'.</li>
+ <li><strong>help</strong> (string) — Help text</li>
+</ul>
+<p>The <macroArgument> element defines an argument for use with the macro. The default value may be specified in the 'default' attribute or in the text of the element. The text supercedes the attribute.</p>
+<p><macroArgument> takes these attributes:</p>
+<ul type="disc">
+ <li><strong>name</strong> (string) — The name of the argument. This must be a legal JavaScript identifier and unique within the macro. Typically, macro argument names are title-cased so they will stand out in the macro definition and also so they may be used without conflict in <expandArgument> attributes (see below).</li>
+ <li><strong>optional</strong> (boolean) — Tells whether the argument may be omitted from an expandMacro use. If true, and no default is provided, the variable's value is null.</li>
+ <li><strong>default</strong> (string) — The default value of the argument if unspecified. Alternately, the text of this element may be supplied as the default, if formatting or newlines are used.</li>
+ <li><strong>help</strong> (string) — Help text</li>
+</ul>
+<p>The included sourceGen elements, <template>, <inline>, and <defineLocation>, act as usual. Note that <templateGroup> is not allowed. Instead, if you need to pass the same parameters to several templates, then wrap the <expandMacro> call inside <templateGroup>. This restriction makes it easier to specify sourcegen inheritance and avoids the disallowed situation of nested <templateGroups>.</p>
+<p><expandMacro> may be used, as well, intermixed with the sourceGen elements mentioned above. By default, all the relevant arguments in the current macro will be passed to the macro named in <expandMacro> (including those taking default values). This allows macros to be safely built from each other without updating all of them if a common macro’s argument list changes. You may suppress this behavior, however. See <expandMacro> for specific details.</p>
+<h4><a name="macarg"></a>Macro argument modifiers</h4>
+<p>When macro arguments are referenced, they may take any number of modifers, which are in the syntax: <macro argument> { ‘::’ <modifier> }.<br />
+ For example, “$(myName::to-title::as-string)”.</p>
+<p>Recognized modifiers are:</p>
+<ul>
+ <li><strong>to-upper</strong>: convert value to upper case</li>
+ <li><strong>to-lower</strong>: convert value to lower case</li>
+ <li><strong>to-title</strong>: convert value to title case</li>
+ <li><strong>as-string</strong>: convert argument to a string constant by adding double quotes and escaping</li>
+ <li><strong>is-defined</strong>: resolves to ‘true’ if the macro is defined (even if empty), else ‘false’</li>
+ <li><strong>append-space-unless-empty</strong>: results in the argument value with a trailing space, unless the argument is empty</li>
+ <li><strong>add-spaces-unless-empty</strong>: results in the argument value with leading and trailing space, unless the argument is empty</li>
+</ul>
+<p>These modifiers work with argument values taking the canonical form of a function declaration’s argument list in C++, for example, with types, argument names, and optional default values:</p>
+<ul>
+ <li><strong>as-function-declaration-args</strong>: identity</li>
+ <li><strong>as-function-definition-args</strong>: removes default values</li>
+ <li><strong>as-function-location-args</strong>: removes argument names and default values</li>
+ <li><strong>as-function-call-args</strong>: removes types and default values</li>
+ <li><strong>split-and-indent</strong>: primarily used for formatting argument lists. Converts a multi-item string, separated by commas, into multi-line format, with each line indented with two tabs. Empty or single-item argument lists are not modified.</li>
+</ul>
+<h4><a name="expmac"></a>Expanding macros</h4>
+<h5>Example:</h5>
+<pre class="listing"><expandMacro name="GenerateAssert" LocationId="ID_METHOD" Expr="6+7+'a'" /></pre>
+<p>or</p>
+<pre class="listing"><expandMacro name="GenerateAssert">
+ <expandArgument name="LocationId">ID_METHOD</expandArgument>
+ <expandArgument name="Expr">6+7+'a'</expandArgument>
+</expandMacro></pre>
+<p>Both of these have the same effect. In the first form, the argument names are used as XML attributes to <expandMacro>. Typically, the macro argument names are capitalized to emphasize the distinction between the fixed attributes in the XML schema and the dynamic attributes allowed for macro expansion. The second form explicitly passes arguments in the text part of the <expandArgument> element. This allows for multi-line arguments to be passed more clearly.</p>
+<p><expandMacro> expands a given macro into the sourceGen of the caller. This has the same effect as inserting the same templates and inlines from the macro's definition at the point of call. Variable references from those templates and inlines are substituted with the values provided in attributes (e.g. variableName="value") or expandArgument child elements. The latter may be preferred for cases where code is substituted, so the formatting may be retained.</p>
+<p><expandMacro> takes these arguments:</p>
+<ul>
+ <li><strong>name</strong> (string): the name of the macro (from <defineMacro id=”...”>)</li>
+ <li><strong>passArguments</strong> (list of string): A list of arguments defined in the current calling macro to pass unchanged to the called macro, excluding any arguments that are not defined in the current call.</li>
+</ul>
+<p>This attribute is only valid in expandMacro called from a defineMacro. Passing arguments is different from adding attributes argName="$(argName)" because it avoids defining otherwise undefined arguments. A missing optional argument is null, not the empty string. The '::is-defined' modifier can be used to check this.</p>
+<p>Elements in the list of strings are names of arguments, or renames of the form targetArgumentName=hostArgumentName which passes hostArgumentName from the hosting macro with the name targetArgumentName (again, only if the argument is actually defined in the call).</p>
+<p>If this argument is not specified, all arguments in the invoked macro are passed (zero or more may have defaults which are overridden in this macro). </p>
+<ul type="disc">
+ <li><strong>dontPassArguments</strong> (list of string): This is primarily used when passArguments is not specified. It specifies which arguments not to pass to the invoked macro, which become undefined in the expansion of that macro. This is useful when this macro takes over the work of one or more arguments from the invoked macro.</li>
+ <li><strong>help</strong> (string): help text</li>
+</ul>
+<p>The <expandArgument> element may appear any number of times inside <expandMacro> in place of using attributes to pass arguments. It takes these arguments:</p>
+<ul type="disc">
+ <li><strong>name</strong> (string): the argument’s name</li>
+ <li><strong>help</strong> (string): help text</li>
+</ul>
+<h3><a name="scriptref"></a>Script Reference</h3>
+<h4>Sourcegen Contribution Variables</h4>
+<p>These variables are available inside functions automatically generated by the <template> element.</p>
+<ul>
+ <li><strong>contribs — </strong>The java.util.LinkedList of IContributions</li>
+ <li><strong>contribText — </strong>The string containing the current text for the contribution (this is appended piecemeal by the raw text and ${expressions})</li>
+ <li><strong>contrib — </strong>The current IContribution created from Engine.createContributionXXX. The contribText is applied to the contrib at the end of the <template></li>
+ <li><strong>formrx — </strong>The regular expression string representing the current form passed down by the parent through Engine.createChildContributions().</li>
+ <li><strong>properties — </strong>Same as instance.properties, to make property references clearer.</li>
+</ul>
+<h4>Instance Global Variables</h4>
+<p>The following variables are available for use within the sourceGen XML element and scripts. These augment the JavaScript globals.</p>
+<ul>
+ <li><strong>src</strong> — the relative path to the primary source directory of the project</li>
+ <li><strong>inc — </strong>the relative path to the primary include directory of the project</li>
+ <li><strong>build — </strong>the relative path to the primary build directory of the project (e.g. “group”)</li>
+ <li><strong>resource — </strong>the relative path to the primary resource directory of the project (e.g. “data”)</li>
+ <li><strong>instanceName — </strong>the “name” property of the current instance</li>
+ <li><strong>instanceMemberName — </strong>the name used for a member in a class (“i” + instanceName)</li>
+ <li><strong>instanceName$title — </strong>title-cased instanceName (e.g. “Listbox”)</li>
+ <li><strong>instanceName$upper — </strong>upper-cased instanceName (e.g. “LISTBOX”)</li>
+ <li><strong>instanceName$lower — </strong>lower-cased instanceName (e.g. “listbox”)</li>
+ <li><strong>resourceName — </strong>If the component defined a resource with the <sourceMapping> element, this is the primary resource name (e.g. “r_myview_listbox”). May be null if no resource is exported.</li>
+ <li><strong>resourceName$upper — </strong>upper-cased resourceName (e.g. “R_MYVIEW_LISTBOX”)</li>
+ <li><strong>resourceFileNameBase — </strong>base filename used for resources. This is the project name for “application.uidesign” and the design file’s base name otherwise.</li>
+ <li><strong>className — </strong>name of the current class, if there is one. This is either the instance's own "className" property or that of the nearest enclosing parent (e.g. “CFoo”)</li>
+ <li><strong>parentClassName — </strong>like "className", but the name of the nearest enclosing parent of the instance that provided "className".</li>
+ <li><strong>handlerClassName — </strong>Name of the class for event handlers, which is the “className” property of the nearest enclosing component that defines the “event-handler-target” attribute to “true” (e.g. “CContainer”).</li>
+ <li><strong>handlerInstanceName — </strong>The name property of the component instance providing handlerClassName (e.g. “container1”)</li>
+</ul>
+<p>When an event handler is being handled, triggered by ifEvents="..." matching a bound event, then the first matching event provides these variables:</p>
+<ul>
+ <li><strong>event.eventId — </strong>the internal id of the event</li>
+ <li> <strong>event.eventName — </strong>the display name of the event</li>
+ <li> <strong>event.handlerName — </strong>the user-provided function name for the user event handler</li>
+ <li> <strong>event.handlerSymbol — </strong>internal data for the location of the event handler function (this is currently the directory, filename, and location path to the function)<br />
+ </li>
+</ul>
+<h4><a name="coneng"></a>Contribution Engine Routines</h4>
+<p>When generating source inside <sourceGen>, scripts have access to a library of routines related to generating contributions. All these are prefixed with “Engine.”, for example: <span class="code">Engine.createContributionForLocation()</span>.</p>
+<table border="1">
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>assignLocationsForPhase</strong>(contributions, phase, location)</td>
+ <td><p>Assign locations to phased contributions without a location. The contributions with the given phase are assigned the given location. Parameters:</p>
+ <ul>
+ <li>contributions - the list of contributions; modified in place</li>
+ <li>phase - the phase to match (must not be null)</li>
+ <li>location - the location to assign</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>collateContributionsByPhase</strong>(contributions, phases)</td>
+ <td><p>Collate contributions by phase. Takes a list of phase names and orders contributions so that they reflect the ordering of the phases. Note that this will have no effect if a contribution already has a location. Parameters:</p>
+ <ul>
+ <li>contributions - the list of contributions; modified in place</li>
+ <li>phases - list of phases (null may be used to represent un-phased contributions)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>createContribution</strong>()</td>
+ <td>Creates a contribution.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>createContributionForLocation</strong>(location)</td>
+ <td><p>Create a contribution at a given location. Parameters:</p>
+ <ul>
+ <li>location - the unique location id, defined either in this location or some calling parent</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>createContributionForPhase</strong>(phase)</td>
+ <td><p>Create a contribution for the given phase. Parameters:</p>
+ <ul>
+ <li>phase - the phase, for parent collation</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>createFromStockFile</strong>(directoryId, filename, stockPath)</td>
+ <td><p>Create a stock file in the project from a file relative to the current component or an applicable base, if such file does not already exist. This is preferred to explicitly defining a location and applying a template when the file must not have any user-specified comment at the top or any variable expansion. Parameters:</p>
+ <ul>
+ <li>directoryId - the directory ID for the target (see INameGenerator#..._DIRECTORY_ID)</li>
+ <li>filename - the filename within the directory for the target file</li>
+ <li>stockPath - component-relative path to stock file</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>findBuiltinOrGeneratedEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
+ <td><p>Find the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. The difference is, this routine does not generate a new enumerator; it returns null if none was generated. Parameters:</p>
+ <ul>
+ <li>instance</li>
+ <li>propertyPath - path to the property @param uniqueValue the enumerator value which indicates a unique value was generated, or "*" if a unique value is always generated</li>
+ <li>nameAlg - the unique name algorithm used</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>findDefiningFileForEnumerator</strong>(enumerator)</td>
+ <td>Get the filename where this enumerator is declared.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>findGeneratedRssFiles</strong>(regex)</td>
+ <td>Get the list of RSS generated files matching the given pattern.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>findLocation</strong>(locationId)</td>
+ <td><p>Look up the ILocation for the given location id. Parameter:</p>
+ <ul>
+ <li>locationId - name of the location</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>findOrCreateEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
+ <td><p>Find or create the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. This routine can create new enumerators. Such enumerators will be created in a globally accessible file (i.e. an HRH file for the application). If the enumerator was generated before but not visible in the DOM, this recreates it. Parameters:</p>
+ <ul>
+ <li>instance</li>
+ <li>propertyPath - path to the property</li>
+ <li>nameAlg - the unique name algorithm used</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>formMatches</strong>(form, forms)</td>
+ <td>Tell whether the given form regex matches any of the forms in the array.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>generateAllViewContributions</strong>(form)</td>
+ <td><p>Generate the "glue" contributions for all the view data models. These are the contributions that an application needs to get from a view in order to register it. This automatically filters out contributions not matching the form, with the assumption that the default form templates will never apply to the case of generating from a view. Parameters:</p>
+ <ul>
+ <li>form - the sourcegen form to pass</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>generateChildContributions</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance child, form)</td>
+ <td><p>Generate child contributions. Called by parent on each child. Parameters:</p>
+ <ul>
+ <li>form - a regular expression matching form names ("" = blank/no form)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>generateChildContributions</strong>(form)</td>
+ <td>Generate all child contributions, in order.
+ Parameters:
+ <ul>
+ <li>form - a regular expression matching form names ("" = blank/no form)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>generateRedirectedInstanceContributions</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, form, com.nokia.sdt.datamodel.adapter.IComponentInstance refInstance)</td>
+ <td><p>Generate child contributions using a referencing instance for context. This is used when component instance A (refInstance) points to component instance B (instance), and instance B's sourceGen relies on properties and/or events from instance A. This supplies an additional parameter to sourceGen called 'refInstance' that can be queried. Note that none of the predefined variables are defined for refInstance, as they are for instance (e.g. children, properties, instanceName, or instanceMemberName). Parameters:</p>
+ <ul>
+ <li>instance - the instance to generate</li>
+ <li>form - a regular expression matching form names ("" = blank/no form)</li>
+ <li>refInstance - the instance holding a reference to this instance</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>generateViewContributions</strong>(viewFilePath, form)</td>
+ <td>Generate the "glue" contributions for a view data model. These are the contributions that an application needs to get from a view in order to register it. This automatically filters out contributions not matching the form, with the assumption that the default form templates will never apply to the case of generating from a view.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getAllProjectViewDesigns</strong>()</td>
+ <td>Get a list of project-relative paths specifying view designs.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getContributionsForForm</strong>(contributions, form)</td>
+ <td><p>Return sublist of contribution matching the given form. Parameters:</p>
+ <ul>
+ <li>contributions - the list of contributions</li>
+ <li>form - regular expression to match form ("" = blank/no form)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getContributionsForLocation</strong>(contributions, locationId)</td>
+ <td><p>Return sublist of contribution matching the given location Id. Parameters:</p>
+ <ul>
+ <li>contributions - the list of contributions</li>
+ <li>locationId - the location name (or null to match contributions without location)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getContributionsForPhase</strong>(contributions, phase)</td>
+ <td><p>Return sublist of contribution matching the given phase. Parameters:</p>
+ <ul>
+ <li>contributions - the list of contributions</li>
+ <li>phase - the phase (or null to match contributions without a phase)</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getGeneratedResource</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance)</td>
+ <td>Get the unnamed resource generated for the given component.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getGeneratedResource</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, rsrcId)</td>
+ <td><p>Get the unnamed resource generated for the given component. Parameters:</p>
+ <ul>
+ <li>instance - the component instance</li>
+ <li>rsrcId - the identifier of the generated resource, or null </li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>getGlobalDictionary</strong>()</td>
+ <td>Get global dictionary for one sourcegen pass. This is entirely for the use of sourcegen script. It provides common state which is available to all instances in a design when sources are generated; nothing persists past a save of the data model.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>queryEnumeratorForAlgorithm</strong>(com.nokia.sdt.datamodel.adapter.IComponentInstance instance, propertyPath, nameAlg)</td>
+ <td><p>Query the enumerator generated by the given name algorithm with the given property value. These match the attributes used in <mapEnumMember>. This routine does not rely on an enumerator having been created and does not uniquify the value, and can possibly return a misleading result. Parameters:</p>
+ <ul>
+ <li>instance</li>
+ <li>propertyPath - path to the property</li>
+ <li>nameAlg - the unique name algorithm used</li>
+ </ul></td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>removeContributionsForPhase</strong>(contributions, phase)</td>
+ <td>Remove contributions with the given phase.</td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>removeDuplicateContributionsForLocation</strong>(contributions, location)</td>
+ <td>Remove duplicate contributions based on location. The list is scanned for contributions matching the given location exactly. If such contributions have the same trimmed text, the duplicates are removed. Note that this doesn't account for any contributions implicitly supplied by the current component's <defineLocation> contributions. Either call this function from a caller or do not define possibly duplicatable content in <defineLocation> (you can supply this as <template> appearing at that location). </td>
+ </tr>
+ <tr bgcolor="white">
+ <td align="left" valign="top" width="1%"><strong>titleCase</strong>(text)</td>
+ <td> </td>
+ </tr>
+</table>
+<p> </p>
+<h4><a name="debugging"></a>Debugging</h4>
+<p>In the <sourceGen> element, set the debug attribute to “true” to generate a dump of the generated JavaScript that is used to generate contributions. Alternately, the <strong>Components > Enable SourceGen Debugging...</strong> dialog may be used to enable debugging and specify the directory for generated JavaScript files.</p>
+<h3><a name="inheritance"></a>Inheritance</h3>
+<p>Source generation behavior allows inheritance by derived components, though it is not automatically inherited. If no <sourceGen> element appears in a derived component instance, the UI Designer automatically iterates the instance’s children and gathers contributions for them. If <sourceGen> does appear in a derived component, and left empty, then no source is generated for that component.</p>
+<p>If <sourceGen> appears in a derived component, it may</p>
+<ul>
+ <li>Define entirely new source generation elements and have no interaction with its base</li>
+ <li>Inherit as much as possible from the base</li>
+ <li>Or mix the contributions, taking some from the base and providing the rest itself.</li>
+</ul>
+<p>A component can inherit from a base. For source generation, this implies automatic inheritance of the JavaScript base object, its locations, and its macros, but not of the behavior, which is explicitly inherited to allow selection and reordering.</p>
+<p class="note"><strong>NOTE</strong> Locations defined with realize="true" are not automatically realized in derived components.</p>
+<p>The <useTemplate> element is used to inherit <template> elements from base.</p>
+<p>The attribute “ids” lists the named <template> elements from the base component (“*” indicates all). A <template> element without an “id” cannot be inherited. This element can be repeated and ordered arbitrarily with other <template> elements. An “id” can only be referenced or defined once per <sourceGen> element.</p>
+<p>The <useTemplateGroup> element is used to inherit <templateGroup> elements from base. A standalone <useTemplateGroup> element inherits all named <template> elements, or can contain <useTemplate> elements to select specific sub-elements.</p>
+<p class="note"> <strong>NOTE</strong> All templates are implicitly named, or given ids, unless otherwise suppressed by specifying id="".</p>
+<p>All <inline> elements may be inherited from the base, if they are given ids. For inlines, on the other hand, ids are not implicitly defined inside <templateGroup>.</p>
+<div id="footer">Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. <br>License: <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a></div>
+</body>
+</html>