carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/reference/CustomComponents/cc_source_mapping.htm
<!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 Mapping</title>
<link rel="StyleSheet" href="../../../book.css" type="text/css"/>
</head>
<body bgcolor="#FFFFFF">
<h2>RSS Source Mapping</h2>
<p>The UI Designer supports source generation and updating of Symbian resource (RSS) files, including LOC/Lxx/RLS localized string files and HRH headers shared between a class of C/C++ files. C++ files are handled by a one-way template expansion process. RSS files are handled by a two-way process using an RSS DOM. The <sourceMapping> element in a component definition file (.component) drives the process.</p>
<p>The source mapping engine maintains enough information to allow in-place modifications to RSS and related files. Also, it allows for user edits to be retained, as long as they are not also handled by the component.</p>
<h3>General Concepts</h3>
<p>Visualize RSS source mapping as walking down two parallel hierarchies. One is the hierarchy of component instances, properties, compound properties, arrays, and component reference properties. The other is the hierarchy of RSS RESOURCE definitions, field initializers, nested resource expressions, array initializers, and LLINK field initializers.</p>
<p>The hierarchies outlined here are not strictly parallel. For example, you may map something other than a component reference property to an LLINK field. If you map a compound property or another instance to an LLINK, the source mapping engine will take care of automatically generating a resource to satisfy the link. Conversely, a component reference property may be mapped to a resource expression; no standalone resource needs to exist in RSS.</p>
<p>At the leaf of the tree, where properties are mapped to field initializers, types needn't be mapped strictly. Usually, integer properties are mapped to WORD or BYTE RSS fields, but you may map enumerator properties or even literal text (corresponding to no property) to such fields as well.</p>
<p>XML elements in the <sourceMapping> element are driven from the RSS side of the picture (e.g. "map a resource", "map a field", etc.). The structure and nesting of these elements drive the structure of the generated RSS. Generally, a <mapResource...> element creates a new resource or resource expression, and <map...Member> elements map into a member or field initializer named by the "member" attribute.</p>
<p>The source mapping engine automatically generates names for resources which are guaranteed to be unique within the scope of a project and its designs. You may influence this only by supplying a fixed name for a resource using "rsrcName" in <mapResource>.</p>
<p>The "property" attribute inside the <map...Member> elements depicts how to walk the component instance and property hierarchy. This attribute specifies a "property path", which is a tiny language for navigating the data model.</p>
<ul>
<li> path := "." | path-element [ dot-or-arrow-or-at path ]</li>
<li>path-element := read-property | find-child | goto-parent</li>
<li>read-property := <property name> (find property of the given name)</li>
<li>find-child := "[" <component id> "]" (find child component with given id)</li>
<li>goto-parent := "[parent]" (find parent)</li>
<li>dot-or-arrow-or-at := "." (enter compound property) | "->" (dereference reference property) | "@" (attribute)</li>
</ul>
<p>For example, property="location.x" will read the "x" property inside the compound property named "location". The statement "holder.reference->value" will read the "value" property inside the "reference" component reference property inside the "holder" compound property. Usually a property attribute is a simple name. Note that you may target a compound property (e.g. "location") or a component instance (e.g. "holder.reference->") itself with a property path.</p>
<p>In both cases, the movement is one-way as nesting increases further into the RSS hierarchy or into the component instance hierarchy. The only way to go up the hierarchy is to map into an RSS LLINK field or read across a component reference property.</p>
<p> The following table lists supported mappings. See the following sections for details on the XML elements.</p>
<table width="378" border="1" align="center">
<caption>
Supported Mappings
</caption>
<tr>
<th width="169" scope="col">Mapping</th>
<th width="193" scope="col">XML Element</th>
</tr>
<tr>
<td>Component instance</td>
<td><mapResource> <mapResourceMember><br />
<mapInstanceMember></td>
</tr>
<tr>
<td>Compound property</td>
<td><mapResource> <mapResourceMember></td>
</tr>
<tr>
<td>Simple leaf property</td>
<td><mapSimpleMember> <mapIdentifierMember><br />
<mapEnumMember></td>
</tr>
<tr>
<td>Component reference property</td>
<td><mapReferenceMember> <mapInstanceMember> <br />
<mapResourceMember></td>
</tr>
<tr>
<td>Set of boolean properties</td>
<td><mapBitmaskMember></td>
</tr>
<tr>
<td>Constant</td>
<td><mapFixedMember></td>
</tr>
</table>
<p><br />
</p>
<h3><a name="mappings"></a>Mappings</h3>
<p>Source mapping elements appear in the <sourceMapping> element of the component definition file.</p>
<h4>Resource</h4>
<p>The <mapResource> element defines a mapping from a property source to a resource. Attributes include:</p>
<ul>
<li><strong>struct</strong> — the name of the STRUCT defining the resource type</li>
<li><strong>headers</strong> — a space-separated list of *.rh filenames that declare the struct</li>
</ul>
<h5>Member Mappings</h5>
<p>The following elements map individual properties to resource members:</p>
<ul>
<li>mapSimpleMember</li>
<li>mapEnumMember</li>
<li>mapIdentifierMember</li>
<li>mapInstanceMember</li>
<li>mapReferenceMember</li>
<li>mapBitmaskMember</li>
<li>mapArrayMember</li>
<li>mapResourceMember</li>
</ul>
<p>Each element takes these attributes:</p>
<ul>
<li><strong>property</strong> — Name of the property to map. The named property is in the scope of the current property source. A dotted syntax may be used to choose subproperties (bounds.width). In the <mapResourceMember> element, use “.” to stay in the current property source.</li>
<li><strong>member</strong> — Name of the resource member. This may include an array element dereference (for example, <span class="code">foo[0]</span>) to target a given element. If used to write into an RSS array initializer, the index must be the terminal index (for example, the current length of the array). It cannot rewrite an existing element or add past the end of the array. </li>
</ul>
<p>Examples of Property and Member mapping:</p>
<p>Given a current property source PS and a struct declaration STR:</p>
<ul>
<li> <span class="code"><mapSimpleMember property=“text” member=“buf” /></span><br />
Takes the “text” property of PS and maps it with the “buf” member of STR.</li>
<li><span class="code"><mapSimpleMember property=“bounds.width” member=“width” /></span><br />
Takes the “width” property of the “bounds” compound property of PS and maps it with the “width” of STR.</li>
<li><span class="code"><mapResourceMember property=“data” member=“embed” struct=“INNER” ...></span><br />
Opens a scope where properties from the compound property “data” are mapped memberwise with the “embed” member (which is of type “STRUCT INNER”) of STR.</li>
<li><span class="code"><mapResourceMember property=“.” member=“embed” struct=“INNER” ... ></span><br />
Opens a scope where properties from PS are mapped memberwise with the “embed” member (which is of type “STRUCT INNER”) of STR.</li>
<li><span class="code"><mapResourceMember property=“.” member=“items[0]” struct=“INNER”></span><br />
Opens a scope where properties from PS are mapped memberwise with the first element of the “items” array member (which is of type “STRUCT INNER”) of STR.</li>
</ul>
<h4><a name="resource"></a>Resource Member Mapping</h4>
<p>Aside from property and member, the <mapResourceMember> element has the same syntax and semantics as the <mapResource> element. This element maps a compound property to a resource expression or statement. Mappings inside the element use the compound property as the property source. If the member is of STRUCT type, the mapping corresponds to that member. Otherwise, the member must be of LLINK type. In this case a uniquely-named resource holds the mapped data, which is referenced from the LLINK.</p>
<p>To map properties from the current property source into a STRUCT, use the property=“.” form and appropriate mapXYZMember. To map a compound property to members of the current resource, use the property=“bounds.width” form and appropriate mapXYZMember.</p>
<p>Example syntax:</p>
<pre><mapResourceMember property=... member=... struct=“...” headers=“...” ></pre>
<p>Resource Generation Example:</p>
<blockquote>
<p>myheader.rh file:</p>
<pre class="listing">STRUCT RSRC {
STRUCT theStruct;
WORD ckSum;
}</pre>
<pre class="listing">STRUCT FOO {
BUF buf;
WORD type;
LONG count;
}</pre>
<p>Component file:</p>
<pre class="listing"><compoundPropertyDeclaration qualifiedName=“Foo">
<property name=“text" type="localizedString" />
<enumProperty name=“type" type=“..." />
<property name=“count" type=“integer“ />
</compoundPropertyDeclaration></pre>
<pre class="listing"><properties>
<property name="name" type="uniqueName"/>
<compoundProperty name=“foo" type=“Foo"/>
<property name=“checksum" type=“integer"/>
</properties></pre>
<pre class="listing"><sourcemapping>
<mapResource struct=“RSRC” headers=“myheader.rh”>
<mapResourceMember property=“foo” member=“theStruct” struct=“FOO” headers=“myheader.rh” />
<mapSimpleMember property=“text” member=“buf”/>
<mapEnumMember property=“type” member=“type”/>
<mapSimpleMember property=“count” member=“count”/>
</mapResourceMember>
<mapSimpleMember property=“checksum” member=“ckSum”/>
</mapResource>
</sourcemapping></pre>
</blockquote>
<h4><a name="simple"></a>Simple Member Mapping</h4>
<p>The <mapSimpleMember> element is allowed within the mapResource, mapResourceElement, or mapResourceMember element. It is used to map a value to a struct member by specifying the property path that provides the value. For example:</p>
<pre class="listing"><mapSimpleMember property="lineWidth" member="line_size"/></pre>
<p>This element allows you to map an integer, float, string, or reference members. Macros and localized strings are handled automatically. Anything in the data model can be represented in the resource file, and any form of string can be stored in the data model. There is no need for different actions based on the state of a string.</p>
<p>Component references are handled automatically. The resource for the target component instance is located or a stub resource is created. An error results under the following conditions:</p>
<ul>
<li>If the instance doesn’t exist</li>
<li>The instance has a missing component</li>
<li>The instance has no source mapping</li>
<li>The instance’s resource header and struct cannot be found.</li>
</ul>
<p>Compound properties are mapped by using IPropertySource#getEditableValue().</p>
<h4><a name="enum"></a>Enum Member Mapping</h4>
<p>The <mapEnumMember> element is allowed within the mapResource, mapResourceElement, or mapResourceMember element. It maps a given property with a resource member and converts enumerator names from one representation to another. This element may be used alone if proper style is followed. All the enumerator values in the data model should be the same as the value used in the resource (RSS) file. The “value” attributes under enumPropertyDeclaration should match the RSS enumerators. Otherwise, the enumerator mapping must be spelled out in subelements. Compound properties are mapped using IPropertySource#getEditableValue().</p>
<p>Attributes:</p>
<ul>
<li><strong>enumeration</strong> — If specified, this is the enumeration declaring the enumerators (optional).</li>
<li><strong>headers</strong> — The space-separated list of header files that define the enumeration constants (optional).</li>
<li><strong>uniqueValue</strong> — If set, this denotes an enumerator value whose RSS mapping is a unique identifier. If “*” is specified, each mapping is given a unique value (optional).</li>
<li><strong>nameAlgorithm</strong> — This is optional unless uniqueValue is set. If set, it is the symbolic name of the generator. If set to "false", eliminates warnings that occur if you map an enum for a macro or for a value that does not appear in any included files.</li>
</ul>
<p>Example syntax:</p>
<pre><mapEnumMember property=... member=... [enumeration=“...” headers=“...”] [uniqueValue=“...” nameAlgorithm=“...”]> </pre>
<p>If the data model uses different enumerators than RSS, the <mapEnumMember> element must contain a list of <mapEnum value=... enum=... /> declarations.</p>
<p>Attributes:</p>
<ul>
<li><strong>value</strong> — The value from the enumPropertyDeclaration’s enumElement.</li>
<li><strong>enum</strong> — The enumerator name used in RSS.</li>
</ul>
<p>Note that using the uniqueValue attribute does NOT force the use of this table. All possible enumerator values must be listed in <mapEnum> elements, otherwise a warning is emitted and no mapping is performed. The UI Designer will warn if a mapped enumerator cannot be resolved by means of headers (either those in <enumMemberMapping> or those brought in by surrounding <mapResource> elements).</p>
<p>Example:</p>
<pre class="listing"><mapEnumMember property=“font” member=“fontName” header=“aknfonts.hrh”>
<mapEnum value=“SYSTEM” enum=“EAknFontSystem”/>
<mapEnum value=“TITLE” enum=“EAknFontTitle”/>
</mapEnumMember> </pre>
<h4><a name="identifier"></a>Identifier Member Mapping</h4>
<p>The <mapIdentifierMember> element maps a string property to an identifier in RSS. This places an unquoted string in RSS, as opposed to the <mapSimpleMember> element which always converts strings to literal string constants. Compound properties are mapped using IPropertySource#getEditableValue().</p>
<p>Example syntax:</p>
<pre><mapIdentifierMember property=“...” member=“...” /></pre>
<h4><a name="instance"></a>Instance Mapping</h4>
<p>The <mapInstanceMember> element maps an instance to an LLINK member or a STRUCT member of a resource. The <mapInstanceElement> does the same for array elements. This is rarely used but may be useful in a complex case of mapping selective elements of arrays, as follows:</p>
<pre class="listing"><mapArrayMember property="." member="structs">
<select attribute="is-emitted">
<choice value="true">
<mapInstanceElement />
</choice>
<choice />
</select>
</mapArrayMember></pre>
<h4><a name="reference"></a>Reference Mapping</h4>
<p>The <mapReferenceMember> and <mapReferenceElement> elements map a component reference property to an LLINK field in RSS. This will place the name of the generated resource for the referenced component instance into the field initializer in RSS.</p>
<h4><a name="bitmask"></a>Bitmask Mapping</h4>
<p>The <mapBitmaskMember> and <mapBitmaskElement> elements are used to map a set of boolean properties to a single integer field in RSS. For example, the component may contain two boolean flags which are expressed as a logical OR of enumerators in RSS.</p>
<p>This mapping is powerful since it allows not only simple one-to-one mapping of properties to enumerators, but also allows groups of properties to be mapped to a single enumerator (e.g. "EAllFlags") and also allows a default value when no properties are set (e.g. "ENoFlags" or "EDefaultFlags").</p>
<p>First, this element has an "includedProperties" attribute specifying a space-separated list of properties which are involved in the mapping. This is used for two reasons:<br />
(1) to allow you to map flags from a larger set of properties and<br />
(2) to validate that you remembered to account for every combination of flags when mapping.</p>
<p>Generally, the latter constraint is not difficult to follow if you include one-to-one mappings for every flag property involved.</p>
<p>This element contains <mapBitmaskValue> elements that describe how a set of "true" properties can be mapped to an enumerator. For example: <span class="code"><mapBitmaskValue properties="myflag" value="EMyFlag" /></span><br />
is a simple one-to-one mapping which maps "EMyFlag" if the "myflag" property is "true".</p>
<p>A more complex example is:<br />
<span class="code"><mapBitmaskValue properties="part1Flag part2Flag" value="EPart1AndPart2Flag" /></span><br />
which maps the "EPart1AndPart2Flag" only if both "part1Flag" and "part2Flag" are "true".</p>
<p>The <mapBitmaskValue> elements are iterated in order until all the "includedProperties" have been accounted for. Thus, specify the more complex mappings first, and then the one-to-one mappings, and finally an empty mapping, which is used only if no properties have been found to be "true". For example:</p>
<pre class="listing"><mapBitmaskMember property="flagSet" member="flags"
includedProperties="allowEdit allowCursorMovement compatibility">
<mapBitmaskValue properties="allowEdit allowCursorMovement" value="EFullEditing" />
<mapBitmaskValue properties="allowEdit " value="EAllowEditing" />
<mapBitmaskValue properties="allowCursorMovement" value="EAllowCursorMovement" />
<mapBitmaskValue properties="compatibility" value="ECompatibilitySetting" />
<mapBitmaskValue properties="" value="ENoFlags" />
</mapBitmaskMember></pre>
<p>In a model, if both "allowEdit" and "allowCursorMovement" are "true", but "compatibility" is false, then the RSS initializer generated would be:</p>
<pre> flags = EFullEditing;</pre>
<p>If "allowEdit" is "true" and "compatibility" is true, then the initializer would be:</p>
<pre> flags = EAllowEditing | ECompatibilitySetting;</pre>
<p>If none of these properties is true, then the initializer would be:</p>
<pre> flags = ENoFlags;</pre>
<h4><a name="array"></a>Array Member Mapping</h4>
<p>The <mapArrayMember> element maps a sequence to an array-typed member of a struct. It contains one subelement to describe how to map each array element.</p>
<ul>
<li>mapSimpleElement</li>
<li>mapEnumElement</li>
<li>mapIdentifierElement</li>
<li>mapResourceElement</li>
</ul>
<p>The < mapArrayElement> is not allowed in RSS. Syntax and semantics mirror those of mapXYZMember, except no member/property attributes are provided. Element mapping uses the current element as the property source. Do not use this to map non-sequence properties to RSS array elements. Use the <span class="code">member=“field[index]”</span> syntax and the appropriate mapXYZMember.</p>
<p>Array Member Mapping Example:</p>
<blockquote>
<p>RSS file:</p>
<pre>STRUCT NUMBER_LIST { WORD items[]; }</pre>
<p>Component file:</p>
<pre class="listing"><arrayProperty name=“itemList” type=“integer”/></pre>
<pre class="listing"><sourceMapping>
<mapResource struct=“NUMBER_LIST” header=“...”>
<mapArrayMember property=“itemList” member=“items”>
<mapSimpleElement/>
</mapArrayMember>
</mapResource>
</sourceMapping></pre>
</blockquote>
<h4><a name="fixed"></a>Fixed Mapping</h4>
<p>This mapping maps a constant value to a member or array element. It is used strictly to override the default value specified in RSS.</p>
<p>No "property" attribute is provided. Instead, set the "value" attribute to the literal text to inject into the initializer. This is not type-checked in any way.<br />
</p>
<h4><a name="type"></a>Type Mapping</h4>
<p>Some mappings are quite lengthy and completely associated with a given compound type. Instead of repeatedly specifying the mapping rules for every use of the property (in different components or in different conditions), you may place the type's source mapping inside the <compoundPropertyDeclaration> element and invoke it with the <mapMemberFromType> and <mapElementFromType> elements.</p>
<p>Place a <sourceTypeMapping> element in <compoundPropertyDeclaration> to associate mappings with the compound type. The only difference from normal RSS source mapping is, the top-level element is a <map...Type> element, which is just like <map...Member> or <map...Element> except that no specific member or array element is implied. For example:</p>
<pre class="listing"><compoundPropertyDeclaration qualifiedName="com.nokia.test.TRgb">
<property name="r" type="integer"/>
<property name="g" type="integer"/>
<property name="b" type="integer"/>
<sourceTypeMapping>
<mapResourceType struct="RGB" headers="basicheader.rh" >
<mapSimpleMember property="r" member="r" />
<mapSimpleMember property="g" member="g" />
<mapSimpleMember property="b" member="b" />
</mapResourceType>
</sourceTypeMapping>
</compoundPropertyDeclaration>
</pre>
<p>When mapping this type, simply reference the property that uses the type, in <mapMemberFromType> or <mapElementFromType>. For example, assuming the "colors" property is of type "com.nokia.test.TRgb", then this will map its elements to a new RGB resource expression in the member "colors":</p>
<pre> <mapMemberFromType property="colors" member="colors" /></pre>
<p>A compound type may map to more than one pattern in RSS. In such a case, specify multiple <map...Type> elements in the type declaration, and give each a unique "typeId" attribute. Specify the same "typeId" attribute in the <mapMemberFromType> or <mapElementFromType> mappings. If typeId is missing from both the type declaration or the mapping, this mapping matches.</p>
<h3><a name="conditional"></a>Conditional Mapping</h3>
<p>In some cases, property values require a component to be mapped in a different way. An enumeration may indicate use of a built-in resource or a flag may indicate another property is ignored. Such a model makes two-way mapping more difficult. A point of selection should resolve to mutually exclusive states in the data model and RSS. Thus, conditional generation must work on the basis of equality and simple property values.</p>
<p>The <select property=“...”> element encloses a set of alternate mapping groups. The "property" attribute is a path to a property of interest (such as, name or struct.member). The <choice [value=“...”]> element encloses a set of mapping elements. The "value" attribute is the value to compare with the property value. If unspecified, it acts as the “default”. The first matching <choice> is applied and all others ignored. The <select> element can appear inside <sourceMapping> and <mapResource*> elements.</p>
<p>A <select> operation may test whether an instance of a given component type exists in a component. The value of the match is non-empty if an instance of the type is found, otherwise it is empty, so structure the comparison in a negative fashion where a valueless choice always matches. For example:</p>
<pre class="listing"><select property="[com.nokia.sdt.series60.MenuPane]">
<choice value=“”>
<!-- no match -->
</choice>
<choice>
<!-- default match -->
</choice></pre>
<p>General node paths can be used here, including parent navigation. For example:</p>
<pre class="listing"><select property=“[parent].isEnabled”>
<choice value=“true”><br /> ... </pre>
<p>A <select> operation may be made against attribute values. For example:</p>
<pre class="listing"><select attribute="is-dialog-content">
<choice value=“true”><br /> ...
</choice>
<choice><br /> ...
</choice>
</select> </pre>
<p>A <select> operation may test the length of an array (empty vs. non-empty) to avoid emitting illegal resources (CAknPopupFieldText.component). For example:</p>
<pre class="listing"><select property="items">
<choice value="0">
<!-- don't emit for 0 items: this causes a panic -->
</choice>
<choice>
<mapResourceMember ...>
</choice>
</select> </pre>
<p>A <select> operation may also match the existence of a property, which matters, for instance, to tell if a given property extender has supplied it. For example:</p>
<pre class="listing"><select propertyExists="foo.bar">
<choice value="true">
...
</choice>
<choice/>
</select></pre>
<p>A <select> operation may also check whether the current component instance is derived from a certain type. Obviously, a component knows its own type, but this is useful for checking component references or children in an array mapping. For example:</p>
<pre class="listing"><mapArrayMember>
<select isComponentInstanceOf="com.nokia.test.ArrayChildItem">
<choice value="true">
...
</choice>
<choice/>
</select>
</mapArrayMember></pre>
<p>Following is an example of generating a control button in a top level component.</p>
<blockquote>
<p>Section of a component definition file:</p>
<pre class="listing"><compoundPropertyDeclaration qualifiedName="com.nokia.sdt.series60.CBAProperty">
<property name="leftText" type="localizedString" />
<enumProperty name="leftId" type=“..." />
</compoundPropertyDeclaration>
<br /><properties>
<property category="Basic" name="name" type="uniqueName"/>
<compoundProperty name="CBA" type="com.nokia.sdt.series60.CBAProperty"/>
</properties> </pre>
<p>Section of a resource file:</p>
<pre class="listing">STRUCT CBA {
STRUCT buttons[]; // of CBA_BUTTON
}
<br />STRUCT CBA_BUTTON {
WORD id;<br /> BUF txt;
} </pre>
<p>Section of a component definition file:</p>
<pre class="listing"><sourcemapping>
<select property=“CBA”>
<choice value=“CUSTOM”>
<mapResource struct=“CBA” headers=“...”>
<mapResourceMember property=“CBA” member=“buttons[0]” struct=“CBA_BUTTON” headers=“...”>
<mapEnumMember property=“leftId” member=“id” uniqueValue=“UNIQUE” />
<mapSimpleMember property=“leftText” member=“txt”/>
</mapResourceMember>
</mapResource>
</choice>
<choice>
<mapSimpleMember property=“CBA” member=“cba” />
</choice> <!-- here, the value of CBA should be the same as the resource name -->
</select>
</sourcemapping> </pre>
</blockquote>
<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>