carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/reference/CustomComponents/cc_definetransientcomp.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>Defining Transient Component</title>
<link rel="StyleSheet" href="../../../book.css" type="text/css"/>
</head>
<body bgcolor="#FFFFFF">
<h2>Defining a Transient Component</h2>
<p>The following information describes how to define a transient component by using a simple transient S60 component as an example. For example, the Note component. When requested, a note appears briefly to provide a message. Notes come in four basic types: confirmation, information, warning and error. They differ by icon and the message displayed. Each is implemented as a different c++ class.</p>
<p>However, since they all have basically the same properties, they are good candidates for implementation as a single component, with an additional selector property to determine which one the developer wants. Since the developer will probably want to activate the note dynamically given the right conditions (for example, if a requested action succeeds or fails), the source code output of a note component should probably be a routine that can be called when the condition warrants displaying the note.</p>
<h3>Component Implementation</h3>
<p>First, the selector property type should be declared. Since this property is not a basic type, and very much specific to this component, its type should be declared with the component. This property will be able to take one of the four possible note types (confirmation, information, warning and error). Therefore, this should be declared as an enumeration property.</p>
<p>Following is an example of the selector property type declaration:</p>
<pre class="listing"><enumPropertyDeclaration qualifiedName="com.nokia.sdt.series60.StandardNote.type">
<enumElement value="CAknConfirmationNote"/>
<enumElement value="CAknInformationNote"/>
<enumElement value="CAknWarningNote"/>
<enumElement value="CAknErrorNote"/>
</enumPropertyDeclaration> </pre>
<p>The display name for an enum element may be specified two ways. In the fully-specified form, the displayValue attribute is a literal string or a percent-prefixed key (%<em>name</em>) to look up in the .properties file. In the form used here, the displayValue is not specified and the value itself is used as the key for the .properties file.</p>
<h4>Attributes and properties</h4>
<p>To have transient component behavior (icon in the non-layout area and transient appearance in the layout area), the component must declare itself to be a non-layout component as well as a transient component. These declarations are achieved by attributes. Since attributes are inherited, the StandardNote component can inherit from the NonLayoutBase component to get its non-layout behavior as well as its required unique “name” property.</p>
<pre class="listing"><attributes>
<attribute key="is-layout-object">false</attribute>
<attribute key="is-non-layout-object">true</attribute>
</attributes>
<br /><properties>
<property category="Design" name="name" type="uniqueName"/>
</properties> </pre>
<p>Specific transient attributes can be declared directly. It declares itself to be a transient object as well as one that can’t be resized or moved.</p>
<pre class="listing"><attributes>
<attribute key="is-non-resizable-or-moveable-layout-object">true</attribute>
<attribute key="is-transient-object">true</attribute>
</attributes> </pre>
<p>Finally, its own specific properties can be declared. Standard location and size properties are set in order to behave correctly in the editor. Developers do not need to see these properties because they do not represent anything in the source code. These properties can be hidden from developers by declaring the special category “Hidden.” A text property is declared to hold the message of the note, and the selector property, “type” is declared with the enumeration type declared previously.</p>
<pre class="listing"><properties>
<compoundProperty category="Hidden" name="location"
type="com.nokia.sdt.series60.locationProperty"
editorClass="com.nokia.sdt.symbian.ui.editors.ReadOnlySummaryEditorFactory"/>
<compoundProperty category="Hidden" name="size"
type="com.nokia.sdt.series60.sizeProperty"
editorClass="com.nokia.sdt.symbian.ui.editors.ReadOnlySummaryEditorFactory"/>
<property category="Data" name="text" type="localizedString" default="Note" />
<enumProperty category="Appearance" name="type"
type="com.nokia.sdt.series60.StandardNote.type"
default="CAknConfirmationNote"/>
</properties></pre>
<h4>JavaScript implementations</h4>
<p>After adding all the static features to the component, some dynamic features can be added to provide design time rendering, layout, and other behavior. This is done by writing JavaScript code that implements specific interfaces that are known to the editor. The StandardNote component will implement various interfaces. It will implement IVisualAppearance to allow it to render itself in the editor and change the rendering when its properties change. It implements ILayout to allow it to exist in various layout sizes. IDirectLabelEdit allows developers to enter label text directly on the editor rather than through the properties view and IComponentPropertyListener allows it to resize if necessary as its text grows.</p>
<pre class="listing"><implementations>
<implementation>
<interface id="com.nokia.sdt.datamodel.adapter.IVisualAppearance"/>
<interface id="com.nokia.sdt.datamodel.adapter.IDirectLabelEdit"/>
<script file="StandardNote_visual.js" prototype="StandardNoteVisual"/>
</implementation>
<implementation>
<interface id="com.nokia.sdt.datamodel.adapter.ILayout"/>
<interface id="com.nokia.sdt.datamodel.adapter.IComponentInstancePropertyListener"/>
<script file="StandardNote_layout.js" prototype="StandardNoteLayout"/>
</implementation>
</implementations></pre>
<p>In the StandardNote component, two prototypes are used, each one in its own JavaScript file. StandardNoteVisual implements IVisualAppearance and IDirectLabelEdit since these implementations are related. One is drawing the text while the other allows the text to be edited in place.</p>
<p>StandardNoteLayout implements ILayout and IComponentInstancePropertyListener since these implementations are also related. One gives the instance its size and location, while the other forces it to layout when the text property changes.</p>
<h4>Source generation</h4>
<p>The output of any component is the source code it generates into the developer’s project. As mentioned earlier, the StandardNote component generates a routine into the owning class that can be called to display the note at runtime.</p>
<p>Because its text property should be localizable, it is placed in a TBUF resource, so the component needs to map the text property to the resource. The sourceMapping element describes this mapping, while the sourceGen element encapsulates the template for generating source code into the owning class.</p>
<h5>Related Reference</h5>
<ul>
<li><a href="cc_source_mapping.htm">Source Mapping</a></li>
<li><a href="cc_source_generation.htm">Source Generation</a></li>
</ul>
<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>