|
2
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
|
|
|
5 |
<title>Creating Wizard Templates</title>
|
|
|
6 |
<style>
|
|
|
7 |
<!--
|
|
|
8 |
.00BodyText
|
|
|
9 |
{font-size:11.0pt;
|
|
|
10 |
font-family:Arial;}
|
|
|
11 |
.11BodyText
|
|
|
12 |
{font-size:11.0pt;
|
|
|
13 |
font-family:Arial;}
|
|
|
14 |
.Heading1a
|
|
|
15 |
{text-indent:0in;
|
|
|
16 |
border:none;
|
|
|
17 |
padding:0in;
|
|
|
18 |
font-size:11.0pt;
|
|
|
19 |
font-family:Arial;
|
|
|
20 |
text-transform:uppercase;
|
|
|
21 |
font-weight:bold;}
|
|
|
22 |
.DocumentTitle
|
|
|
23 |
{font-size:18.0pt;
|
|
|
24 |
font-family:Arial;
|
|
|
25 |
font-weight:bold;}
|
|
|
26 |
.Section1
|
|
|
27 |
{page:Section1;}
|
|
|
28 |
div.listing
|
|
|
29 |
{line-height:100%;}
|
|
|
30 |
span.attr
|
|
|
31 |
{color:green}
|
|
|
32 |
-->
|
|
|
33 |
</style>
|
|
|
34 |
<link rel="StyleSheet" href="../../book.css" type="text/css"/>
|
|
|
35 |
</head>
|
|
|
36 |
<body>
|
|
|
37 |
|
|
|
38 |
<h2>Creating Wizard Templates</h2>
|
|
|
39 |
|
|
|
40 |
<p class=Heading1a>1.<span
|
|
|
41 |
style='font:7.0pt "Times New Roman"'> </span>ABOUT THIS DOCUMENT</p>
|
|
|
42 |
|
|
|
43 |
<p class=11BodyText>This document describes how to create a wizard template for Carbide.c++. </p>
|
|
|
44 |
|
|
|
45 |
<h3>1.1<span style='font:7.0pt "Times New Roman"'> </span>Scope</h3>
|
|
|
46 |
<p class=11BodyText>This document describes the wizardTemplate extension, the xml template format and post-wizard processing model. Some familiarity with XML, Eclipse plugins and extensions and, for custom process creation, the Java programming language, is assumed. This document will not cover instruction in these areas.</p>
|
|
|
47 |
<div style='border:none;border-top:solid #057C00 1.5pt;padding:10.0pt 0in 0in 0in'>
|
|
|
48 |
<p class=Heading1a>2.<span
|
|
|
49 |
style='font:7.0pt "Times New Roman"'> </span>Introduction</p>
|
|
|
50 |
</div>
|
|
|
51 |
<p class=11BodyText>Wizards collect data from users and automate tasks. They tend to be UI intensive and can be difficult and tedious to create. For this reason, Carbide.c++ supports wizards generated from xml descriptions. Specifically, Carbide.c++ exposes two such wizards, one for creating projects and one for adding class files to an existing project.</p>
|
|
|
52 |
<p class=11BodyText>Carbide.c++ exposes the <span class="code">com.nokia.carbide.templatewizard.wizardTemplate</span> extension point for this purpose. Using this extension point allows you to create a plug-in where you can add as many custom templates as necessary to support your development efforts. </p>
|
|
|
53 |
<h3>2.1<span style='font:7.0pt "Times New Roman"'> </span>General Nomenclature</h3>
|
|
|
54 |
<p class=11BodyText><span
|
|
|
55 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><b>Wizard Template extension</b>: an Eclipse extension in a plugin extending the <i>com.nokia.carbide.templatewizard.wizardTemplate</i> extension point.</p>
|
|
|
56 |
<blockquote>
|
|
|
57 |
<p class="note"><span class="note"><strong> NOTE</strong></span> Do not add custom templates to the default Carbide.c++ plug-in as updates will overwrite your changes. </p>
|
|
|
58 |
</blockquote>
|
|
|
59 |
<p class=11BodyText><span
|
|
|
60 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><b>Extension element</b>: a child element in an Eclipse extension. In the current document, the only extension element is the <template> extension element. This is one of the <template> elements declared in the wizard template extension. Each template extension element defines the specific characteristics of one wizard configuration. A plugin may define more than one wizard template extension, and each extension can have more than one template extension element.</p>
|
|
|
61 |
<p class=11BodyText><span
|
|
|
62 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><b>Template xml file</b>: an xml file referenced by a template extension element, which describes some number of wizard pages and post-wizard processes in xml.</p>
|
|
|
63 |
<p class=11BodyText><span
|
|
|
64 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><b>Elements in a template xml file</b>: As the template file is also in xml, it is also made up of elements and child elements. Much of the document will be devoted to explaining the significance of these elements.</p>
|
|
|
65 |
<br clear=all
|
|
|
66 |
style='page-break-before:always'>
|
|
|
67 |
<div style='border:none;border-top:solid #057C00 1.5pt;padding:10.0pt 0in 0in 0in'>
|
|
|
68 |
<p class=Heading1a>3.<span
|
|
|
69 |
style='font:7.0pt "Times New Roman"'> </span><span
|
|
|
70 |
style='font:7.0pt "Times New Roman"'> </span>The Wizard Template Extension Point</p>
|
|
|
71 |
</div>
|
|
|
72 |
<p class=11BodyText>Starting with a new Plug-in Project created to house your templates (using <strong>File > New > Project... > Plug-in Project</strong>), here is an example of a wizard template extension with a single template element that should be added to the <span class="code">plugin.xml</span> file:</p>
|
|
|
73 |
|
|
|
74 |
<pre class="listing">
|
|
|
75 |
<extension point=<span class="attr">"com.nokia.carbide.templatewizard.wizardTemplate"></span>
|
|
|
76 |
<template
|
|
|
77 |
templateId=<span class="attr">"com.nokia.cdt.templates.s60.controlapplication"</span>
|
|
|
78 |
location=<span class="attr">"templates/projecttemplates/S60-ControlApplication/template.xml"</span>
|
|
|
79 |
wizardId=<span class="attr">"com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppProjectWizard" </span>
|
|
|
80 |
groupLabel=<span class="attr">"S60"</span>
|
|
|
81 |
filterArguments=<span class="attr">"S60:1.2;2.0-2.9"</span>
|
|
|
82 |
image=<span class="attr">"icons/icon_S60.png"</span>
|
|
|
83 |
/>
|
|
|
84 |
</extension>
|
|
|
85 |
</pre>
|
|
|
86 |
|
|
|
87 |
<p class=11BodyText>The template wizard extension point has the identifier: <span class="code">com.nokia.carbide.templatewizard.wizardTemplate</span><i>.</i> </p>
|
|
|
88 |
<p class=11BodyText>Extensions of the template wizard extension point must specify the following required attributes:</p>
|
|
|
89 |
<p class=11BodyText>1.<span
|
|
|
90 |
style='font:7.0pt "Times New Roman"'> </span><b>templateId</b>: the unique identifier for this template</p>
|
|
|
91 |
<p class=11BodyText>2.<span
|
|
|
92 |
style='font:7.0pt "Times New Roman"'> </span><b>location</b>: the plugin-relative path to the template xml file</p>
|
|
|
93 |
<p class=11BodyText>3.<span
|
|
|
94 |
style='font:7.0pt "Times New Roman"'> </span><b>wizardId</b>: the id of the wizard in which this template is used</p>
|
|
|
95 |
<p class=11BodyText>The two template wizards provided by Carbide.c++ are:</p>
|
|
|
96 |
<blockquote>
|
|
|
97 |
<p class="11BodyText">a.<span
|
|
|
98 |
style='font:7.0pt "Times New Roman"'> </span>The Symbian OS C++ project wizard with wizard id: <span class="code">com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppProjectWizard</span></p>
|
|
|
99 |
<p class="11BodyText">b.<span
|
|
|
100 |
style='font:7.0pt "Times New Roman"'> </span>The Symbian OS C++ class wizard with wizard id: <span class="code">com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppClassWizard</span></p>
|
|
|
101 |
</blockquote>
|
|
|
102 |
<p class=11BodyText>4.<span
|
|
|
103 |
style='font:7.0pt "Times New Roman"'> </span><b>groupLabel</b>: the group label under which this template will appear in the template choice page of the appropriate template wizard</p>
|
|
|
104 |
<p class=11BodyText>Groups are created from group labels that are available from the filtered or unfiltered list of templates for a specific wizard. Anyone creating new templates is free to use an existing group label, or create a new one as needed.</p>
|
|
|
105 |
<p class=note><strong>NOTE</strong> The <span class="code">groupLabel</span> attribute, as with all attributes in the plugin.xml, can be localized simply by using a % -prefixed key and a standard Java properties file.</p>
|
|
|
106 |
<p class=11BodyText>For example, the attribute in the template extension element could use the key “S60.label” prefixed with a % character: </p>
|
|
|
107 |
<p><span style='font-size:10.0pt;
|
|
|
108 |
font-family:"Courier New";color:navy'>groupLabel=</span><span style='font-size:
|
|
|
109 |
10.0pt;font-family:"Courier New";color:green'>"%S60.label"</span></p>
|
|
|
110 |
<p class=11BodyText>The plugin.properties file in the same directory as the plugin.xml would contain the entry:</p>
|
|
|
111 |
<p class=11BodyText><span style='font-size:10.0pt;
|
|
|
112 |
font-family:"Courier New"'>S60.label=<span style='color:blue'>S60</span></span></p>
|
|
|
113 |
<p class=11BodyText>Additionally, extensions can specify the following optional attributes:</p>
|
|
|
114 |
<p class=11BodyText>5.<span
|
|
|
115 |
style='font:7.0pt "Times New Roman"'> </span><b>filterArguments</b>: the optional wizard-specific data which is available to the filtering mechanism activated by the “filter templates” checkbox, which is optionally shown in some template wizards; no filter arguments signifies to always show this template</p>
|
|
|
116 |
<p class=11BodyText>The filter is provided by the wizard and the argument for the filter is specified optionally by each template, in order to work with its intended wizard (see wizardId attribute).</p>
|
|
|
117 |
<p class=11BodyText>Both the Symbian OS C++ project and class wizards filter templates against Symbian Sdks. Both wizards require the filter arguments to be of the form: [sdk family][:sdk versions]. Sdk family is either S60, S80, UIQ or TechView. Sdk versions can be lists of versions separated by semicolon and/or ranges separated by hyphens. Here are some examples of valid filter argument attributes:</p>
|
|
|
118 |
<blockquote>
|
|
|
119 |
<p class="11BodyText"><span
|
|
|
120 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><i>S60:1.2;2.0-2.9</i> allows all S60 sdks version 1.2 and 2<sup>nd</sup> edition.</p>
|
|
|
121 |
<p class="11BodyText"><span
|
|
|
122 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><i>S60:3.0-3.9</i> allows all S60 3<sup>rd</sup> edition sdks.</p>
|
|
|
123 |
<p class="11BodyText"><span
|
|
|
124 |
style='font-family:Symbol'>·<span style='font:7.0pt "Times New Roman"'> </span></span><i>S80</i> allows all Series 80 sdks.</p>
|
|
|
125 |
</blockquote>
|
|
|
126 |
<p class=11BodyText>6.<span
|
|
|
127 |
style='font:7.0pt "Times New Roman"'> </span><b>image</b>: the optional plugin-relative location of a 16x16 pixel image file to be used when showing this template in the choose template wizard selection page</p>
|
|
|
128 |
<p class=11BodyText>7.<span
|
|
|
129 |
style='font:7.0pt "Times New Roman"'> </span><b>extraPagesProvider</b>: an optional provider of extra wizard pages </p>
|
|
|
130 |
<p class=11BodyText>This class must have a 0-argument public constructor and must implement the <i>com.nokia.carbide.templatewizard.ui.IExtraPagesProvider</i> interface (see javadoc). The class is only constructed once per template per Eclipse session. However, it will be initialized and used as many times as the template is chosen by the users.</p>
|
|
|
131 |
<br clear=all
|
|
|
132 |
style='page-break-before:always'>
|
|
|
133 |
<div style='border:none;border-top:solid #057C00 1.5pt;padding:10.0pt 0in 0in 0in'>
|
|
|
134 |
<p class=Heading1a>4.<span
|
|
|
135 |
style='font:7.0pt "Times New Roman"'> </span>The Template XML Format</p>
|
|
|
136 |
</div>
|
|
|
137 |
<h3>4.1<span style='font:7.0pt "Times New Roman"'> </span>The template element</h3>
|
|
|
138 |
<p class=11BodyText>This is an example <b>template</b> element with a description:</p>
|
|
|
139 |
|
|
|
140 |
<pre class="listing">
|
|
|
141 |
<template
|
|
|
142 |
version=<span class="attr">"1.0"</span>
|
|
|
143 |
label=<span class="attr">"S60 2.x Control based GUI application"</span>>
|
|
|
144 |
<description><span class="attr">A S60 Control is a rectangular area of the screen that \
|
|
|
145 |
may respond to user input and events. You can use this template for all S60 2.x and 1.2 SDKs.</span>
|
|
|
146 |
...
|
|
|
147 |
</template>
|
|
|
148 |
</pre>
|
|
|
149 |
|
|
|
150 |
<p class=11BodyText>The template xml file has one required top-level element, the <b>template</b> element. </p>
|
|
|
151 |
<p class=11BodyText>The <b>template</b> element has these required attributes:</p>
|
|
|
152 |
<ul>
|
|
|
153 |
<li><b>version</b>: a version string (e.g., 1.0)</li>
|
|
|
154 |
<li><b>label</b>: the label string used to denote this template in the choose template wizard selection page</li>
|
|
|
155 |
</ul>
|
|
|
156 |
<h3>4.2<span style='font:7.0pt "Times New Roman"'> </span>The description element</h3>
|
|
|
157 |
<p class=11BodyText>The <b>template</b> element has an optional <b>description</b> child element whose text content is used in the description area of the choose template wizard selection page. When a specific template is selected, its description is displayed. </p>
|
|
|
158 |
<p class=note><strong>NOTE</strong> The description strings are elements and not attributes, in order to allow return characters to be easily specified for formatting purposes. Descriptions may be broken for readability without specifying a return character in the actual description by terminating a line with a backslash. All description strings in the template xml format use this pattern.</p>
|
|
|
159 |
<p class=11BodyText><i>ADDITIONAL NOTE: </i>All <b>label</b> attributes and <b>description</b> elements in the template xml format are localizable using the %-prefixed key method described above for plugin.xml files. In the case of localization, the <b>label</b> attribute’s value and/or <b>description</b> element’s content consists of a %-prefixed key instead of the actual value, and a properties file for the template xml exists in the same directory as the template xml file containing the localized strings for these keys.</p>
|
|
|
160 |
<p class=11BodyText>The <b>template</b> element can have any number of children of type <b>wizardPage</b> elements and <b>process</b> elements.</p>
|
|
|
161 |
<h3>4.3<span style='font:7.0pt "Times New Roman"'> </span>The wizardPage element</h3>
|
|
|
162 |
<p class=11BodyText>This is an example of a <b>wizardPage</b> element:</p>
|
|
|
163 |
|
|
|
164 |
<pre class="listing">
|
|
|
165 |
<wizardPage
|
|
|
166 |
id=<span class="attr">"basics"</span>
|
|
|
167 |
label=<span class="attr">"Basic Settings"</span>
|
|
|
168 |
<description><span class="attr">Basic properties of a project</span>
|
|
|
169 |
<textField
|
|
|
170 |
id=<span class="attr">"Author:"</span>
|
|
|
171 |
label=<span class="attr">"myLabel"</span>
|
|
|
172 |
persist=<span class="attr">"true"</span>
|
|
|
173 |
<description><span class="attr">Name of the author</span></description>
|
|
|
174 |
</textField>
|
|
|
175 |
<textField
|
|
|
176 |
id=<span class="attr">"copyright"</span>
|
|
|
177 |
label=<span class="attr">"Copyright notice:"</span>
|
|
|
178 |
multiline=<span class="attr">"true"</span>
|
|
|
179 |
default=<span class="attr">"Your copyright notice"</span>
|
|
|
180 |
persist=<span class="attr">"true"</span>
|
|
|
181 |
<description><span class="attr">Your copyright notice</span>
|
|
|
182 |
</textField>
|
|
|
183 |
<uidField
|
|
|
184 |
id=<span class="attr">"uid3"</span>
|
|
|
185 |
label=<span class="attr">"Application UID:"</span>
|
|
|
186 |
min=<span class="attr">"0x00000001"</span>
|
|
|
187 |
max=<span class="attr">"0x01ffffff"</span>
|
|
|
188 |
mandatory=<span class="attr">"true"</span>
|
|
|
189 |
persist=<span class="attr">"true"</span>
|
|
|
190 |
<description><span class="attr">The Application UID is the project identifier</span></description>
|
|
|
191 |
</uidField>
|
|
|
192 |
<filenameField
|
|
|
193 |
id=<span class="attr">"groupDir"</span>
|
|
|
194 |
label=<span class="attr">"Group:"</span>
|
|
|
195 |
default=<span class="attr">"group"</span>
|
|
|
196 |
mandatory=<span class="attr">"true"</span>
|
|
|
197 |
persist=<span class="attr">"true"</span>
|
|
|
198 |
<description><span class="attr">The directory for project files</span></description>
|
|
|
199 |
</filenameField>
|
|
|
200 |
</wizardPage>
|
|
|
201 |
</pre>
|
|
|
202 |
|
|
|
203 |
<p class=11BodyText>Each <b>wizardPage</b> element declaratively specifies one page in the wizard. The child ordering of <b>wizardPage</b> elements in the <b>template</b> element is the order that the pages will appear. </p>
|
|
|
204 |
<p class=note><strong>NOTE</strong> Ordering is important and is a common theme in the template xml format. This is true of wizard pages, ui elements within a wizard page, as well as processes. The order is preserved in the context in which child elements are defined.</p>
|
|
|
205 |
<p class=11BodyText>The <b>wizardPage</b> element has these required attributes:</p>
|
|
|
206 |
<ul>
|
|
|
207 |
<li><b class="11BodyText">id</b>: a unique identifier for this wizard page within a template</li>
|
|
|
208 |
<li><b class="11BodyText">label</b>: the label string used as the title of the wizard page</li>
|
|
|
209 |
</ul>
|
|
|
210 |
<p class=11BodyText>The <b>wizardPage</b> element has an optional <b>description</b> child element whose text content is used as the description of the wizard page – just below the title. This element behaves like all <b>description</b> elements in the template xml format (see above).</p>
|
|
|
211 |
<p class=11BodyText>The <b>wizardPage</b> element can have any number of children elements of type <b>textField</b>, <b>uidField</b> or <b>filenameField</b>. These represent user input fields in a wizard page, and although any number can be specified, in practice, only a reasonable number should exist on a given wizard page. The fields are laid out one below the other in the child order in which they are declared in the <b>wizardPage</b> element.</p>
|
|
|
212 |
<p class=11BodyText>All field elements have these required attributes:</p>
|
|
|
213 |
<ul>
|
|
|
214 |
<li><b class="11BodyText">id</b>: a unique identifier for this field that is used for persistence and for value access by processes</li>
|
|
|
215 |
<li><b class="11BodyText">label</b>: the label string used as the label for the input field</li>
|
|
|
216 |
</ul>
|
|
|
217 |
<p class=11BodyText>All field elements have an optional <b>description</b> child element whose text content is used as the tooltip text for the field, which behaves like all <b>description</b> elements in the template xml format (see above).</p>
|
|
|
218 |
<p class=11BodyText>Additionally, fields have these optional attributes:</p>
|
|
|
219 |
<ul>
|
|
|
220 |
<li><b class="11BodyText">persist</b>: a boolean value defaulting to false, indicating whether the value in this field should be persisted and used as a default the next time a field with this id is used</li>
|
|
|
221 |
<li><b class="11BodyText">mandatory</b>: a boolean value defaulting to false, indicating that the user can’t leave this field empty</li>
|
|
|
222 |
</ul>
|
|
|
223 |
<p class=11BodyText>In addition to these attributes, each field type has its own additional attributes.</p>
|
|
|
224 |
<p class=11BodyText>The <b>textField</b> element specifies a text field that can be validated by a regular expression pattern and that can be specified to be single or multiple lines.</p>
|
|
|
225 |
<p class=11BodyText>The <b>textField</b> element has these optional attributes:</p>
|
|
|
226 |
<ul>
|
|
|
227 |
<li><b class="11BodyText">default</b>: the initial value this field should contain, unless a persisted value exists to override it</li>
|
|
|
228 |
<li><b class="11BodyText">pattern</b>: the Java style regular expression used for validation of user input</li>
|
|
|
229 |
<li><b class="11BodyText">multiline</b>: a boolean value defaulting to false, indicating that the text field should allow input in multiple lines</li>
|
|
|
230 |
</ul>
|
|
|
231 |
<p class=11BodyText>The <b>uidField</b> element specifies a text field that must contain a hexadecimal number in the range of a Java long, beginning with the prefix 0x (e.g., 0x0). The uid field has a button to the right labeled “random” that changes the current value of the field to a random value within a specified range. The specified range is also used to validate values input by the user.</p>
|
|
|
232 |
<p class=11BodyText><i>NOTE: Each uid field adds 2 values to the template for use by processes. The one indexed by the id of the uid field is exactly what is shown in the field, and the other indexed by the id with the suffix -WITHOUT_0X, is the value without the 0x prefix.</i></p>
|
|
|
233 |
<p class=11BodyText>The <b>uidField</b> element has these required attributes:</p>
|
|
|
234 |
<ul>
|
|
|
235 |
<li><b class="11BodyText">min</b>: the minimum value allowed by the field specified in hexadecimal starting with the prefix 0x</li>
|
|
|
236 |
<li><b class="11BodyText">max</b>: the maximum value allowed by the field specified in hexadecimal starting with the prefix 0x</li>
|
|
|
237 |
</ul>
|
|
|
238 |
<p class=11BodyText>The <b>filenameField</b> element specifies a text field that is validated to be a valid OS file name composed of only alpha-numeric, hyphen or underscore characters. The additional restrictions exist to avoid path problems with build tools.</p>
|
|
|
239 |
<p class=11BodyText>The <b>filenameField</b> element has the optional attribute:</p>
|
|
|
240 |
<ul>
|
|
|
241 |
<li><b class="11BodyText">default</b>: the initial value this field should contain, unless there exists a persisted value to override it</li>
|
|
|
242 |
</ul>
|
|
|
243 |
<h3>4.4<span style='font:7.0pt "Times New Roman"'> </span>The process element</h3>
|
|
|
244 |
<p class=11BodyText>This is an example of a <b>process</b> element with a single <b>parameter</b> child: </p>
|
|
|
245 |
|
|
|
246 |
<pre class="listing">
|
|
|
247 |
<process
|
|
|
248 |
class=<span class="attr">"com.nokia.carbide.cpp.project.core.processes.NewProject"</span>
|
|
|
249 |
bundle=<span class="attr">"com.nokia.carbide.cpp.project.core"</span>
|
|
|
250 |
<parameter
|
|
|
251 |
name=<span class="attr">"project"</span>
|
|
|
252 |
projectName=<span class="attr">"$(projectName)"</span>
|
|
|
253 |
</process>
|
|
|
254 |
</pre>
|
|
|
255 |
|
|
|
256 |
<p class=11BodyText>The <b>process</b> elements, like those for wizard pages, are declared in the template xml file as children elements of the <b>template</b> element. Each <b>process</b> element declares the execution of the <i>process</i> method of a class implementing the interface <i>com.nokia.carbide.templatewizard.process.IProcess</i> after the user finishes running a template wizard. </p>
|
|
|
257 |
<p class=11BodyText>Execution of processes occurs in the order in which the <b>process</b> elements appear in the template xml file, so it is fully acceptable that some processes will be dependent on the successful execution of previous processes. Failure in the execution of any processes is reported to the user and logged to the error log, but remaining processes are executed.</p>
|
|
|
258 |
<p class=11BodyText>The <b>process</b> element has these required attributes:</p>
|
|
|
259 |
<ul>
|
|
|
260 |
<li><b class="11BodyText">class</b>: the fully qualified class name of the class implementing <i>com.nokia.carbide.templatewizard.process.IProcess</i> </li>
|
|
|
261 |
</ul>
|
|
|
262 |
<p class=11BodyText>This class should have a 0-argument public constructor. An instance of this class will be created and its <i>process</i> method will be called for each <b>process</b> element appearing in the template xml file.</p>
|
|
|
263 |
<p class=11BodyText>To assist implementation of the process class, an abstract base class is provided. <i>com.nokia.carbide.templatewizard.process.AbstractProcess</i> has members that encapsulate initialization, failure with <i>CoreException</i> and accessing process parameters. </p>
|
|
|
264 |
<p class=11BodyText>See javadoc for class details.</p>
|
|
|
265 |
<ul>
|
|
|
266 |
<li><b class="11BodyText">bundle</b>: the bundle id for the bundle in which the process class resides</li>
|
|
|
267 |
</ul>
|
|
|
268 |
<p class=11BodyText>The <b>process</b> element has any number of children elements of type <b>parameter</b>.</p>
|
|
|
269 |
<p class=11BodyText>The <b>parameter</b> element has the required attribute:</p>
|
|
|
270 |
<ul>
|
|
|
271 |
<li><b class="11BodyText">name</b>: a unique name for the type of parameter expected by the specific process</li>
|
|
|
272 |
</ul>
|
|
|
273 |
<p class=11BodyText>In addition, <b>parameter</b> elements can have any additional attributes required by the process. These will be accessible via the <i>com.nokia.carbide.templatewizard.process.IParameter</i> interface list provided to processes (see javadoc).</p>
|
|
|
274 |
<p class=11BodyText>Values collected from the user by the wizard are available to processes via the <i>com.nokia.carbide.template.engine.ITemplate</i> interface provided to processes (see attached javadoc). The method <i>getTemplateValues</i> returns a <i>java.util.Map<String, Object></i> containing the values indexed by the field ids specified in the field element children of <b>wizardPage</b> elements, as well as values from built in pages. </p>
|
|
|
275 |
<p class=11BodyText>The template’s map can also be used to communicate state between processes. For example, one process may add a value to the map which is then read by a subsequent process.</p>
|
|
|
276 |
<p class=11BodyText>These are the built in page value ids:</p>
|
|
|
277 |
<ul>
|
|
|
278 |
<li><b class="11BodyText">projectName</b>: the name of the project</li>
|
|
|
279 |
<li><b class="11BodyText">baseName</b>: for new projects, the name of the project changed into a legal c++ identifier</li>
|
|
|
280 |
<li><b class="11BodyText">baseNameUpper</b>: for new projects, baseName uppercased</li>
|
|
|
281 |
<li><b class="11BodyText">baseNameLower</b>: for new projects, baseName lowercased</li>
|
|
|
282 |
<li><b class="11BodyText">location</b>: for new projects, the location of the project as a portable path string</li>
|
|
|
283 |
<li><b class="11BodyText">useDefaultLocation</b>: for new projects, whether the default location checkbox was checked in the new project page – whether the project was in the workspace</li>
|
|
|
284 |
</ul>
|
|
|
285 |
<p class=11BodyText>Additionally, values from the template map are substituted into the parameter attributes specified in the template xml, whenever the attributes contain the pattern <span style='color:green'>$(<i>id</i>)</span> in the value.</p>
|
|
|
286 |
<h3>4.5<span style='font:7.0pt "Times New Roman"'> </span>Built in processes</h3>
|
|
|
287 |
<p class=11BodyText>There are a number of built in processes, provided by Carbide.c++</p>
|
|
|
288 |
<p class=11BodyText>1.<span
|
|
|
289 |
style='font:7.0pt "Times New Roman"'> </span><b>New Project</b>:</p>
|
|
|
290 |
<ul>
|
|
|
291 |
<li><b class="11BodyText">class</b>: com.nokia.carbide.cpp.project.core.processes.NewProject</li>
|
|
|
292 |
<li><b class="11BodyText">bundle</b>: com.nokia.carbide.cpp.project.core</li>
|
|
|
293 |
</ul>
|
|
|
294 |
<blockquote>
|
|
|
295 |
<p class="11BodyText">Requires one parameter with name <b>project</b>, attribute <b>projectName</b>.</p>
|
|
|
296 |
<p class="11BodyText">Creates a new Carbide.c++ project.</p>
|
|
|
297 |
</blockquote>
|
|
|
298 |
<p class=11BodyText>2.<span
|
|
|
299 |
style='font:7.0pt "Times New Roman"'> </span><b>Create Folders</b>:</p>
|
|
|
300 |
<ul>
|
|
|
301 |
<li><b class="11BodyText">class</b>: com.nokia.carbide.templatewizard.processes.CreateFolders</li>
|
|
|
302 |
<li><b class="11BodyText">bundle</b>: com.nokia.carbide.templatewizard</li>
|
|
|
303 |
</ul>
|
|
|
304 |
<blockquote>
|
|
|
305 |
<p class="11BodyText">Requires one parameter with name <b>project</b>, attribute <b>projectName</b>.</p>
|
|
|
306 |
<p class="11BodyText">Any number of parameters with name <b>folder</b>, attribute <b>path</b>.</p>
|
|
|
307 |
<p class="11BodyText">Creates new folders in a project.</p>
|
|
|
308 |
</blockquote>
|
|
|
309 |
<p class=11BodyText>3.<span
|
|
|
310 |
style='font:7.0pt "Times New Roman"'> </span><b>Create 4 character resource ID</b>:</p>
|
|
|
311 |
<ul>
|
|
|
312 |
<li><b class="11BodyText">class</b>: com.nokia.carbide.cpp.project.core.processes.CreateRezId</li>
|
|
|
313 |
<li><b class="11BodyText">bundle</b>: com.nokia.carbide.cpp.project.core</li>
|
|
|
314 |
</ul>
|
|
|
315 |
<blockquote>
|
|
|
316 |
<p class="11BodyText">Requires one parameter with name <b>project</b>, attribute <b>projectName</b>.</p>
|
|
|
317 |
<p class="11BodyText">Creates a 4 character string based on the project name, which is used in the main resource file in the NAME statement.</p>
|
|
|
318 |
</blockquote>
|
|
|
319 |
<p class=11BodyText>4.<span
|
|
|
320 |
style='font:7.0pt "Times New Roman"'> </span><b>Copy Files</b>:</p>
|
|
|
321 |
<ul>
|
|
|
322 |
<li><b class="11BodyText">class</b>: com.nokia.carbide.templatewizard.processes.CopyFiles</li>
|
|
|
323 |
<li><b class="11BodyText">bundle</b>: com.nokia.carbide.templatewizard</li>
|
|
|
324 |
</ul>
|
|
|
325 |
<p class=11BodyText>Requires one parameter with name <b>project</b>, attribute <b>projectName</b>.</p>
|
|
|
326 |
<p class=11BodyText>Any number of parameters with name <b>file</b>, attributes <b>sourcePath</b> and <b>targetPath</b> and optionally, the boolean attribute <b>substitute</b>, which says whether this file is parameterized and needs to be substituted (defaults to “true”).</p>
|
|
|
327 |
<p class=11BodyText>Copies files from the sourcePath (relative to the location of the template xml file) to the targetPath (relative to the project) and optionally substitutes variables using the $(<i>id</i>) pattern. Unrecognized variables are left intact.</p>
|
|
|
328 |
<p class=11BodyText>Optionally, any of three operators can be used to automatically uppercase, lowercase and titlecase (uppercase only the first character) the value prior to substitution. The syntax for using the operators is $(<i>id</i>$upper), $(<i>id</i>$lower) or $(<i>id</i>$title).</p>
|
|
|
329 |
<p class=11BodyText>5.<span
|
|
|
330 |
style='font:7.0pt "Times New Roman"'> </span>Project Initialization:</p>
|
|
|
331 |
<ul>
|
|
|
332 |
<li><b class="11BodyText">class</b>: com.nokia.carbide.cpp.project.ui.processes.ProjectCreatedTasks</li>
|
|
|
333 |
<li><b class="11BodyText">bundle</b>: com.nokia.carbide.cpp.project.ui</li>
|
|
|
334 |
</ul>
|
|
|
335 |
<p class=11BodyText>Requires one parameter with name <b>project</b>, attributes <b>projectName, bldInfPath</b> and <b>targetMMPFileName</b>.</p>
|
|
|
336 |
<p class=11BodyText>Initializes Symbian OS c++ projects with build configurations and other required project data, and tries to expand the project tree in the Project Explorer view.</p>
|
|
|
337 |
<br clear=all
|
|
|
338 |
style='page-break-before:always'>
|
|
|
339 |
<div style='border:none;border-top:solid #057C00 1.5pt;padding:10.0pt 0in 0in 0in'>
|
|
|
340 |
<p class=Heading1a>5.<span
|
|
|
341 |
style='font:7.0pt "Times New Roman"'> </span>Conclusion</p>
|
|
|
342 |
</div>
|
|
|
343 |
<p class=11BodyText>The wizard template extension, along with template xml files and other associated data files provides a rich environment for creating customized project and class wizards declaratively. New project and class wizards for Symbian OS can be created easily and with little or no programming.</p>
|
|
|
344 |
<h5>Related Information</h5>
|
|
|
345 |
<p><a href="../reference/extension-points/templatewizard_wizardTemplate.html">Wizard Template</a></p>
|
|
|
346 |
<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>
|
|
|
347 |
</div></body>
|
|
|
348 |
</html>
|