Mercurial Mercurial > oss > FCL > sftools > dev > ide > carbidecpp / annotate
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_05.htm
author fturovic <frank.turovich@nokia.com>
Tue, 27 Jul 2010 15:28:19 -0500
changeset 1704 24ac5a5cf80c
parent 0 fb279309251b
permissions -rw-r--r--
updated copyright dates and fixed some css issues
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1704
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     1
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     2
 
<html>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     3
 
<head>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     4
 
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     5
 
<meta http-equiv="Content-Style-Type" content="text/css" />
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     6
 
<title>XML-Based Component File</title>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     7
 
<link rel="StyleSheet" href="../../../../book.css" type="text/css"/>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     8
 
</head>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
     9
 
<body bgcolor="#FFFFFF">
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    10
 
<h2>Tutorial: Vertical Label Component - XML Details</h2>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    11
 
<p>The tutorial consists of two versions of the VerticalLabel  component. VerticalLabel1 is the bare minimum needed to make a  functioning component. VerticalLabel2 uses JavaScript to display the component in the UI Designer when designing your user interface.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    12
 
The  following information explains what is relevant to the tutorial. Refer to the XML component schema documentation for all the details.
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    13
 
<h3>Component Definition</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    14
 
<p>The root element for defining a custom component begins with the &lt;componentDefinition&gt; element as shown in the VerticalLabel1.component and VerticalLabel2.component files. It contains the necessary name space attributes,  making the component schema namespace the default.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    15
 
<h3>Component</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    16
 
<p>The component element defines the majority of the component properties, attributes, source mapping and souce generation declarations. The following snippet is from the example .component files:</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    17
 
<pre>&lt;component friendlyName=&quot;%friendlyName&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    18
 
   &nbsp;&nbsp;&nbsp;  qualifiedName=&quot;com.example.uiq.VerticalLabel1&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    19
 
   &nbsp;&nbsp;&nbsp;  baseComponent=&quot;com.nokia.carbide.uiq.ControlCollectionItemBase&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    20
 
   &nbsp;&nbsp;&nbsp;  category=&quot;Custom Controls&quot; version=&quot;1.0&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    21
 
   &nbsp;&nbsp;&nbsp;  instanceNameRoot=&quot;vlabel&quot;&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    22
 
   &nbsp;&nbsp;&nbsp;  &lt;symbian
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    23
 
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;  sdkName=&quot;com.uiq&quot; minSDKVersion=&quot;3.0&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    24
 
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;  className=&quot;CVerticalLabel&quot;/&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    25
 
<p>Strings prefixed with % are localized strings that are  automatically looked up in the accompanying properties files, such as VerticalLabel1.properties.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    26
 
<p>Note  that this component derives from ControlCollectionItemBase, which is a component included  with Carbide.c++. It provides some of the source code generation, as well as allowing it to behave like the other UIQ controls in the UI designer in that they are used in a design's different layout configurations as references in the control collection.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    27
 
<h3>Symbian Element</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    28
 
<p>The &lt;symbian&gt; element specifies that this component is compatible with all SDKs from 3.0 forward and the class name in the VerticalLabel.cpp file used to draw the component at run time is CVerticalLabel.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    29
 
<pre>&lt;symbian sdkName=&quot;com.uiq&quot; minSDKVersion=&quot;3.0&quot;  className=&quot;CVerticalLabel&quot;/&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    30
 
<p>The sdkName property identifies the Symbian OS variant with which the component is compatible. Currently the only recognized SDK name for UIQ is &quot;com.uiq&quot;.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    31
 
<p class="note"><strong>TIP</strong> Enter <strong>devices</strong> at a command prompt (C:\&gt;devices) to display a list of installed and properly configured SDKs.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    32
 
<h3>Designer Images</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    33
 
<p>In the VerticalLabel1 example, the &lt;designerImages&gt; element uses one image. This is the static layout image visible in the UI design. This is used in place of writing rendering script in a JavaScript file. You will only see a static graphic in the UI designer and its sizing by the current layout manager will not be defined by the component. Since icon images have also been omitted, default images are displayed in the palette and in the outline view. For example:</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    34
 
<pre>&lt;designerImages layoutImageFile=&quot;layoutImage.png&quot;/&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    35
 
<p>In the VerticalLabel2 example, the &lt;designerImages&gt; element uses custom icon images (.png files) to represent the component in the palette and outline views. The static layout image file can be removed since JavaScript rendering code has been added to display the component in the UI design. For example:</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    36
 
<pre>&lt;designerImages smallIconFile=&quot;VerticalLabel_sm.png&quot;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    37
 
 largeIconFile=&quot;VerticalLabel.png&quot;/&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    38
 
<h4>Image Support</h4>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    39
 
<p>Images are validated and rendered on a per-component basis.  Each component may have different restrictions or guidelines for the type or size of images that appear. Images appearing in forms and lists will be automatically scaled by the platform. This requires a reference to another interface the component system understands (IImagePropertyRenderingInfo); and can be declared as shown in the following code fragment.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    40
 
<pre>&lt;implementations&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    41
 
 &lt;implementation&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    42
 
  &lt;interface id=&quot;com.nokia.sdt.datamodel.adapter.IImagePropertyRenderingInfo&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    43
 
  &lt;script file=&quot;MyComponent.js&quot; prototype=&quot;MyComponent&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    44
 
 &lt;/implementation&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    45
 
&lt;/implementations&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    46
 
<h3>Attributes Element</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    47
 
<p>The Attributes element allows you to declare miscellaneous characteristics about your component. For example, the following snippet is from the example Vertical Label .component files.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    48
 
<pre>&lt;attributes&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    49
 
 &lt;attribute key=&quot;cpp-class-name&quot;&gt;CVerticalLabel&lt;/attribute&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    50
 
 &lt;attribute key=&quot;rss-control-type-enum&quot;&gt;EVerticalLabel&lt;/attribute&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    51
 
&lt;/attributes&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    52
 
<p>The <span class="code">cpp-class-name</span> attribute is used by  the source generation element (&lt;sourceGen&gt;) that is inherited from ControlCollectionItemBase. This allows you to specify the  name of the C++ class to use in the generated source. The <span class="code">rss-control-type-enum</span> attribute specifies the type identifier used in the QIK_CONTROL resource generated for the control in the control collection resource.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    53
 
<h3>Properties Element</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    54
 
<p>Properties are the data values you can define for a component instance.  The text property is the default text drawn by the vertical label component. Note that it is a localized string, so you may provide different values for each language added to the application. The lineWidth property determines the thickness of the border rectangle drawn around the component. A value of zero (0) indicates  no border will be drawn. Note that default, minimum, and maximum values are specified. The <span class="code">default</span> attribute  is optional and provides an initial value. The optional <span class="code">minimum</span> and <span class="code">maximum</span> attributes provide range checking for integer properties.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    55
 
<pre>&lt;properties&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    56
 
 &lt;property name=&quot;text&quot; type=&quot;localizedString&quot; default=&quot;label&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    57
 
 &lt;property name=&quot;lineWidth&quot; type=&quot;integer&quot; default=&quot;1&quot; minValue=&quot;0&quot; maxValue=&quot;5&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    58
 
&lt;/properties&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    59
 
<h3>Implementations Element</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    60
 
<p>The &lt;implementations&gt; element is used in the VerticalLabel2.component example in order to render the component in the UI designer and provide its preferred size to be used by the layout manager. The &lt;implementations&gt; element informs the UI designer that the custom component has code. Implementations can be provided in either JavaScript or Java.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    61
 
<p>Each implementation declaration has a list of one or more interfaces it fulfills. In this case the IVisualAppearance interface is implemented. This allows us to render an image corresponding to the current property values and provide feedback on the appropriate sizing for the component.  The &lt;script&gt; element informs the UI designer which file has the script and the name of the JavaScript prototype object to instantiate, as shown in the following snippet.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    62
 
<pre>&lt;implementations&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    63
 
 &nbsp; &lt;implementation&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    64
 
 &nbsp;&nbsp;&nbsp; &lt;interface  id=&quot;com.nokia.sdt.datamodel.adapter.IVisualAppearance&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    65
 
 &nbsp;&nbsp;&nbsp;&nbsp;&lt;script file=&quot;VerticalLabel.js&quot;  prototype=&quot;VerticalLabel&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    66
 
 &nbsp; &lt;/implementation&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    67
 
&lt;/implementations&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    68
 
<h4>JavaScript</h4>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    69
 
<p>The example JavaScript file (VerticalLabel.js) contains an empty function to instantiate the JavaScript prototype. Note that the JavaScript file needs to be located as a sibling to the component file that references it.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    70
 
<pre>function VerticalLabel() {
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    71
 
 }</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    72
 
<p>The following code in the JavaScript file declares the draw method. It takes three parameters:</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    73
 
<ul>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    74
 
  <li>instance &ndash; the current component instance used to retrieve property values and other state data.</li>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    75
 
  <li>laf &ndash;  the look and feel object. This has objects and values that vary with the SDK and screen configuration. See the XML documentation on ILookAndFeel for more information.</li>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    76
 
  <li>graphics &ndash; the graphics used for drawing. This is a wrapper around an SWT GC object.</li>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    77
 
</ul>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    78
 
<pre>VerticalLabel.prototype.draw  = function(instance, laf, graphics) {</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    79
 
<p>The font object is obtained from the look and feel  object. Since this is a  simple example the font is hard-coded to a standard Symbian font.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    80
 
<pre>var font = laf.getFont(&quot;NormalFont&quot;);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    81
 
 graphics.setFont(font);</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    82
 
<p>The background color needs to be set since anti-aliased text with a  transparent background is drawn. In the UI Designer, each component is rendered into a bitmap with 'transparent pixel' support.  The bitmap does not have an alpha channel.  Thus, if the background color is not set, the 'transparent pixel' would be blended with the antialiased text, resulting in an orange border.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    83
 
<pre>graphics.setBackground(laf.getColor(&quot;EEikColorControlBackground&quot;));</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    84
 
<p>Next a rectangular border and the text within the border is drawn. The bounds and position of the text are calculated accordingly.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    85
 
<pre> var properties = instance.properties;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    86
 
 var lineWidth = properties.lineWidth;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    87
 
 var halfLineWidth = lineWidth/2;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    88
 
 var textBounds = new Rectangle(halfLineWidth, halfLineWidth,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    89
 
 properties.size.width - halfLineWidth,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    90
 
 properties.size.height - halfLineWidth);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    91
 
 var x = lineWidth + 1;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    92
 
 var y = properties.size.height - lineWidth - 1;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    93
 
<p>The rotated text is then drawn.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    94
 
<pre>graphics.drawRotatedString(properties.text, textBounds, x, y, -1.57, true);</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    95
 
<p>If requested, the border is drawn.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    96
 
<pre>if (lineWidth &gt; 0) {
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    97
 
 graphics.setLineWidth(lineWidth);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    98
 
 x = y = halfLineWidth;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
    99
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   100
 
 graphics.drawRectangle(x, y,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   101
 
 properties.size.width-lineWidth,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   102
 
 properties.size.height-lineWidth);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   103
 
 }</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   104
 
<p>The getPreferredSize method is called by the layout manager to get the size of the component instance. If its text property is null, it will return an empty size, otherwise it will calculate the width of the text to use as its height, and return its parent's width as its width.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   105
 
<pre>VerticalLabel.prototype.getPreferredSize = function(instance, laf, wHint, hHint) {
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   106
 
	var text = instance.properties.text;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   107
 
	if (text == null)
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   108
 
		return new Point(0, 0);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   109
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   110
 
	var font = laf.getFont("NormalFont");
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   111
 
	var extent = TextRendering.formattedStringExtent(font, text, new Point(1000, 1000), 0, 0);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   112
 
	var lineWidth = instance.properties.lineWidth;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   113
 
	var parentBounds = instance.parent.getLayoutBounds();
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   114
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   115
 
	return new Point(parentBounds.width, extent.x + lineWidth + 1);
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   116
 
}
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   117
 
</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   118
 
<h3>Source Mapping Element</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   119
 
<p>The Vertical Label component uses an RSS include file (example_verticallabel.rh). This file defines a custom resource used to initialize the component. Since our component uses a localized string it is especially important to use a resource. The &lt;sourceMapping&gt; element contains information on how to convert from property values to RSS statements, and from RSS statements back to property values.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   120
 
<p>The &lt;mapResource&gt; element tells the RSS generator to create a resource of type <span class="code">EXAMPLE_VERTICAL_LABEL</span>, and that the <span class="code">example_verticallabel.rh</span> file is needed to create compilable source code. The RSS generator has flexible support for mapping properties to resources. Only simple conversions are needed, which can be done with the &lt;mapSimpleMember&gt; element. This has attributes that indicate a given property should be used to initialize a specific resource member. Refer to the &quot;source mapping&quot; XML schema documentation for details on all available mappings. Detailed documentation on the schema can be  found in the plugins folder of your Carbide.c++ installation, for example, the default location at C:\Program Files\Nokia\Carbide.c++ v1.3\plugins\com.nokia.sdt.component.symbian_1.3.0.3. Also examine the UIQ components included with the UI designer for lots of examples; located at &lt;<em>Carbide installation path</em>&gt;/plugins/com.nokia.carbide.cpp.uiq.components/components.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   121
 
<pre>&lt;sourceMapping&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   122
 
 &lt;mapResource struct=&quot;EXAMPLE_VERTICAL_LABEL&quot; headers=&quot;example_verticallabel.rh&quot;&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   123
 
 &lt;mapSimpleMember property=&quot;text&quot; member=&quot;txt&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   124
 
 &lt;mapSimpleMember property=&quot;lineWidth&quot; member=&quot;line_size&quot;/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   125
 
 &lt;/mapResource&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   126
 
&lt;/sourceMapping&gt;</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   127
 
<h3>Source  Generation Element
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   128
 
</h3>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   129
 
<p>The &lt;sourceGen&gt; element contains all the information needed to generate C++ code. Because this example is deriving from ControlCollectionItemBase, there is a lot of existing infrastructure to leverage. Source code generation is performed by executing JavaScript scripts. There is a layer above raw JavaScript that creates scripts by way of template expansion, like with PHP, JPS, ASP, etc. With templates you can define variables, or escape out to arbitrary script code. The following code snippet is from the Vertical Label .component files.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   130
 
<pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   131
 
&lt;sourceGen&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   132
 
	&lt;useTemplateGroup ids="makeVisible"/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   133
 
	&lt;templateGroup id="0" form="InstanceGen"&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   134
 
	&lt;expandMacro name="SetupControlInstanceVariable"  Type="${this.getCppClassName(instance)}"
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   135
 
		InstanceMemberName="${instanceMemberName}" InstanceTitle="${instanceName$title}"
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   136
 
		Headers="barsread.h eikenv.h"/&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   137
 
	&lt;/templateGroup&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   138
 
	&lt;inline&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   139
 
if (Engine.formMatches(form, [""])) {
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   140
 
	// create files if missing
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   141
 
	Engine.createFromStockFile("inc", "VerticalLabel.h", "VerticalLabel.h");
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   142
 
	Engine.createFromStockFile("src", "VerticalLabel.cpp", "VerticalLabel.cpp");
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   143
 
}
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   144
 
	&lt;/inline&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   145
 
	&lt;template phase="MainUserIncludes"&gt;&lt;![CDATA[
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   146
 
#include "VerticalLabel.h"
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   147
 
#include "example_verticallabel.hrh"
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   148
 
]]&gt;&lt;/template&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   149
 
	&lt;template location="VIEWDIALOGBASE_HEADER_OWNED_SYSTEM_INCLUDES"&gt;&lt;![CDATA[
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   150
 
#include &lt;QikControlProvider.h&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   151
 
]]&gt;&lt;/template&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   152
 
	&lt;templateGroup id="ControlFactory"&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   153
 
	&lt;template id="VerticalLabelControlFactory" phase="ClassPrivateOwnedMethods"&gt;&lt;![CDATA[
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   154
 
class TVerticalLabelControlFactory : public MQikControlFactory
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   155
 
	{
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   156
 
public:
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   157
 
	CCoeControl* CreateByTypeL(
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   158
 
		TInt aType,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   159
 
		TInt& aDefaultFlags )
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   160
 
	{
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   161
 
	if ( aType == EVerticalLabel )
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   162
 
		{
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   163
 
		aDefaultFlags = EQikCtrlFlagIsNonFocusing;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   164
 
		return new(ELeave) CVerticalLabel;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   165
 
		}
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   166
 
	return NULL;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   167
 
	}
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   168
 
	CCoeControl* ConstructCustomControlL(
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   169
 
		TInt aUniqueHandle,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   170
 
		TInt aType,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   171
 
		TInt aResourceId,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   172
 
		TInt aItemFlags,
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   173
 
		const CCoeControl& aParent )
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   174
 
	{
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   175
 
	return NULL;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   176
 
	}
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   177
 
	};
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   178
 
TVerticalLabelControlFactory iVerticalLabelControlFactory;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   179
 
]]&gt;&lt;/template&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   180
 
	&lt;template id="InstallControlFactory" phase="PreConstructFromResourceL"&gt;&lt;![CDATA[
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   181
 
// Install this factory in the control providers list
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   182
 
ControlProvider()-&gt;AddControlFactoryL( iVerticalLabelControlFactory );
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   183
 
]]&gt;&lt;/template&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   184
 
	&lt;template id="RemoveControlFactory" phase="Destroy"&gt;&lt;![CDATA[
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   185
 
// Remove this factory from the control providers list
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   186
 
ControlProvider()-&gt;RemoveControlFactory( iVerticalLabelControlFactory );
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   187
 
]]&gt;&lt;/template&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   188
 
	&lt;/templateGroup&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   189
 
&lt;/sourceGen&gt;
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   190
 
</pre>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   191
 
<p>Since source code generation is very detailed  and specific, deriving from a component does not automatically enable source code generation. The derived component must specify what to generate, either completely  or by referencing existing templates. Templates defined in ControlCollectionItemBase can be reused.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   192
 
<p>The <code>makeVisible</code> template group does some standard initialization. Macros are groups of parametrized templates. The <code>SetupControlInstanceVariable</code> macro generates code to setup a member variable for the vertical label control's instance.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   193
 
<p>The &lt;inline&gt; element inserts  JavaScript code. This example calls a predefined function to copy the stock versions of VerticalLabel.cpp and VerticalLabel.h that contain the runtime code implementing the vertical label control.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   194
 
<p>There is a &lt;template&gt; element in this snippet that is used to define a new template in order to insert the  <span class="code">#include &quot;VerticalLabel.h&quot;</span> and <span class="code">#include &quot;example_verticallabel.hrh&quot;</span> statements for the required header files.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   195
 
<p>The final &lt;templateGroup&gt; element embodies a set of templates used to generate and install a custom control factory to translate the custom control type identifier, <code>EVerticalLabel</code> used in the control collection resource into a CVerticalLabel object.</p>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   196
 
<div id="footer">Copyright &copy; 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>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   197
 
</div>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   198
 
</body>
24ac5a5cf80c updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents: 0
diff changeset 
   199
 
</html>
FCL/sftools/dev/ide/carbidecpp