root / trunk / install / IzPack / doc / izpack / html / node6.html @ 11445
History | View | Annotate | Download (49.5 KB)
1 | 5819 | cesar | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
---|---|---|---|
2 | |||
3 | <!--Converted with LaTeX2HTML 2002-2-1 (1.70)
|
||
4 | original version by: Nikos Drakos, CBLU, University of Leeds
|
||
5 | * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
|
||
6 | * with significant contributions from:
|
||
7 | Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
|
||
8 | <HTML>
|
||
9 | <HEAD>
|
||
10 | <TITLE>Desktop Shortcuts</TITLE> |
||
11 | <META NAME="description" CONTENT="Desktop Shortcuts"> |
||
12 | <META NAME="keywords" CONTENT="izpack-doc"> |
||
13 | <META NAME="resource-type" CONTENT="document"> |
||
14 | <META NAME="distribution" CONTENT="global"> |
||
15 | |||
16 | <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> |
||
17 | <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
||
18 | |||
19 | <LINK REL="STYLESHEET" HREF="izpack-doc.css"> |
||
20 | |||
21 | <LINK REL="next" HREF="node7.html"> |
||
22 | <LINK REL="previous" HREF="node5.html"> |
||
23 | <LINK REL="up" HREF="izpack-doc.html"> |
||
24 | <LINK REL="next" HREF="node7.html"> |
||
25 | </HEAD>
|
||
26 | |||
27 | <BODY > |
||
28 | |||
29 | <DIV CLASS="navigation"><!--Navigation Panel--> |
||
30 | <A NAME="tex2html431" |
||
31 | HREF="node7.html"> |
||
32 | <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
||
33 | <A NAME="tex2html427" |
||
34 | HREF="izpack-doc.html"> |
||
35 | <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
||
36 | <A NAME="tex2html421" |
||
37 | HREF="node5.html"> |
||
38 | <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
||
39 | <A NAME="tex2html429" |
||
40 | HREF="node1.html"> |
||
41 | <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
||
42 | <BR>
|
||
43 | <B> Next:</B> <A NAME="tex2html432" |
||
44 | HREF="node7.html">Creating Your Own Panels</A> |
||
45 | <B> Up:</B> <A NAME="tex2html428" |
||
46 | HREF="izpack-doc.html">izpack-doc</A> |
||
47 | <B> Previous:</B> <A NAME="tex2html422" |
||
48 | HREF="node5.html">Advanced Features</A> |
||
49 | <B> <A NAME="tex2html430" |
||
50 | HREF="node1.html">Contents</A></B> |
||
51 | <BR>
|
||
52 | <BR></DIV> |
||
53 | <!--End of Navigation Panel-->
|
||
54 | <!--Table of Child-Links-->
|
||
55 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> |
||
56 | |||
57 | <UL CLASS="ChildLinks"> |
||
58 | <LI><A NAME="tex2html433" |
||
59 | HREF="node6.html#SECTION00610000000000000000">Defining Shortcuts</A> |
||
60 | <UL>
|
||
61 | <LI><A NAME="tex2html434" |
||
62 | HREF="node6.html#SECTION00611000000000000000">Introduction</A> |
||
63 | <LI><A NAME="tex2html435" |
||
64 | HREF="node6.html#SECTION00612000000000000000">What to Add to the Installer</A> |
||
65 | <LI><A NAME="tex2html436" |
||
66 | HREF="node6.html#SECTION00613000000000000000">Why Native Code to do the Job on Windows?</A> |
||
67 | <LI><A NAME="tex2html437" |
||
68 | HREF="node6.html#SECTION00614000000000000000">The Shortcut Specification</A> |
||
69 | <LI><A NAME="tex2html438" |
||
70 | HREF="node6.html#SECTION00615000000000000000">Shortcut Attributes</A> |
||
71 | <UL>
|
||
72 | <LI><A NAME="tex2html439" |
||
73 | HREF="node6.html#SECTION00615100000000000000">Unix specific shortcut attributes </A> |
||
74 | </UL>
|
||
75 | <LI><A NAME="tex2html440" |
||
76 | HREF="node6.html#SECTION00616000000000000000">Selective Creation of Shortcuts</A> |
||
77 | <LI><A NAME="tex2html441" |
||
78 | HREF="node6.html#SECTION00617000000000000000">Summary</A> |
||
79 | </UL>
|
||
80 | <BR>
|
||
81 | <LI><A NAME="tex2html442" |
||
82 | HREF="node6.html#SECTION00620000000000000000">Shortcut Tips</A> |
||
83 | <UL>
|
||
84 | <LI><A NAME="tex2html443" |
||
85 | HREF="node6.html#SECTION00621000000000000000">The Desktop</A> |
||
86 | <LI><A NAME="tex2html444" |
||
87 | HREF="node6.html#SECTION00622000000000000000">Icons</A> |
||
88 | <LI><A NAME="tex2html445" |
||
89 | HREF="node6.html#SECTION00623000000000000000">Targets</A> |
||
90 | <LI><A NAME="tex2html446" |
||
91 | HREF="node6.html#SECTION00624000000000000000">Command Line</A> |
||
92 | </UL>
|
||
93 | <BR>
|
||
94 | <LI><A NAME="tex2html447" |
||
95 | HREF="node6.html#SECTION00630000000000000000">Trouble Shooting</A> |
||
96 | <UL>
|
||
97 | <LI><A NAME="tex2html448" |
||
98 | HREF="node6.html#SECTION00631000000000000000">Problems You Can Solve</A> |
||
99 | <LI><A NAME="tex2html449" |
||
100 | HREF="node6.html#SECTION00632000000000000000">Problems That Have No Solution (yet)</A> |
||
101 | <LI><A NAME="tex2html450" |
||
102 | HREF="node6.html#SECTION00633000000000000000">A sample shortcut specification file for Unix</A> |
||
103 | </UL></UL> |
||
104 | <!--End of Table of Child-Links-->
|
||
105 | <HR>
|
||
106 | |||
107 | <H1><A NAME="SECTION00600000000000000000"> |
||
108 | Desktop Shortcuts</A>
|
||
109 | </H1> (by Elmar G<SMALL>ROM</SMALL> and Marc E<SMALL>PPELMANN</SMALL>) |
||
110 | <BR>
|
||
111 | <P>
|
||
112 | |||
113 | <H1><A NAME="SECTION00610000000000000000"> |
||
114 | Defining Shortcuts</A>
|
||
115 | </H1>
|
||
116 | |||
117 | <P>
|
||
118 | |||
119 | <H2><A NAME="SECTION00611000000000000000"> |
||
120 | Introduction</A>
|
||
121 | </H2>
|
||
122 | |||
123 | <P>
|
||
124 | On todays GUI oriented operating systems, users are used to launching |
||
125 | applications, view web sites, look at documentation and perform a |
||
126 | variety of other tasks, by simply clicking on an icon on the desktop or |
||
127 | in a menu system located on the desktop. Depending on the operating |
||
128 | system these icons have different names. In this context we will refer to |
||
129 | them collectively as shortcuts. |
||
130 | <BR>
|
||
131 | <P>
|
||
132 | Apart from actually placing an application on the target system, users |
||
133 | routinely expect an installer to create the necessary shortcuts for the |
||
134 | application as well. For you as application developer, this means that |
||
135 | for a professional appearance of your product you should also |
||
136 | consider creating shortcuts. |
||
137 | <BR>
|
||
138 | <P>
|
||
139 | In contrast to the general specification of an IzPack installer, the |
||
140 | specification of shortcuts in IzPack requires a little more effort. In |
||
141 | addition, some of the concepts are a bit more complex and there are some |
||
142 | operating system specific issues to observe. Fortunately, you only need |
||
143 | to worry about operating system specifics if you want to deploy your |
||
144 | application to multiple different operating systems. In any case, it |
||
145 | will pay off to spend some time to study this documentation and the |
||
146 | example spec files before you start to implement your own shortcuts. |
||
147 | <BR>
|
||
148 | <P>
|
||
149 | At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is only |
||
150 | capable to creating shortcuts on |
||
151 | |||
152 | <OL>
|
||
153 | <LI>Microsoft Windows
|
||
154 | <BR>
|
||
155 | and |
||
156 | </LI>
|
||
157 | <LI>Unix and Unix-based operating systems (like Linux), which use the <A NAME="tex2html21" |
||
158 | HREF="http://www.x11.org/">X11</A> |
||
159 | GUI-System and <A NAME="tex2html22" |
||
160 | HREF="http://www.freedesktop.org/">FreeDesktop.org</A> |
||
161 | based shortcut handling (such as <A NAME="tex2html23" |
||
162 | HREF="http://www.kde.org/">KDE</A> |
||
163 | and <A NAME="tex2html24" |
||
164 | HREF="http://www.gnome.org/">Gnome</A>). |
||
165 | |||
166 | <P>
|
||
167 | </LI>
|
||
168 | </OL>
|
||
169 | |||
170 | <P>
|
||
171 | Other operating or GUI systems, such as MacOS <TT><</TT> MacOS-X are |
||
172 | not supported. However, there is a special UI-variant that automatically pops up |
||
173 | on unsupported systems. It informs the user about the intended targets of your shortcuts and allows |
||
174 | the user to save this information to a text file. While this is not an |
||
175 | elegant solution, at least it aids the user in the manual creation of |
||
176 | the shortcuts. |
||
177 | <BR>
|
||
178 | <P>
|
||
179 | If you would like to review what an end user would see if the target |
||
180 | operating system is not supported, you can do the following. Simply |
||
181 | place the tag <TT><notSupported/></TT> in the spec file. This tag requires no |
||
182 | attributes or other data. It must be placed under <TT><shortcuts></TT>, just like |
||
183 | the individual shortcut specifications. Be sure to remove this tag |
||
184 | before getting your application ready for shipment. |
||
185 | <BR>
|
||
186 | <P>
|
||
187 | We expect other operating systems to be supported in the near future and |
||
188 | as always, contributions are very welcome. At present someone is |
||
189 | actively working on Mac support. |
||
190 | |||
191 | <P>
|
||
192 | |||
193 | <H2><A NAME="SECTION00612000000000000000"> |
||
194 | What to Add to the Installer</A>
|
||
195 | </H2>
|
||
196 | |||
197 | <P>
|
||
198 | There are some things that you have to add to your installer to enable |
||
199 | shortcut creation. Obviously you need to add the panel |
||
200 | responsible for creating shortcuts. This panel is aptly enough called |
||
201 | ShortcutPanel. However, in order for the ShortcutPanel to work |
||
202 | properly a number of additional items are required. These must be added |
||
203 | manually to the installer, as all other resourcs, since the front-end will be rewritten. |
||
204 | In this chapter we will explain which of these items are |
||
205 | required and for what reason. |
||
206 | <BR>
|
||
207 | <P>
|
||
208 | First, we would like to discuss items that are supplied with IzPack and |
||
209 | only need to be added to the installer. After that, we move on to the |
||
210 | things you have to prepare yourself before you can add them. The way in |
||
211 | which shortcuts are created varies widely among operating systems. In |
||
212 | some cases it is possible to do this with pure Java code, while |
||
213 | other systems -such as MS-Windows- require native code to accomplish |
||
214 | this task. On the other side, the current implementation, which creates shortcuts on |
||
215 | Unix based systems needs no native library at all, since it works with 'these' pure Java code. |
||
216 | The native library required for the Windows operating |
||
217 | systems are supplied with IzPack is called <TT>ShellLink.dll</TT>. |
||
218 | Note: They will not be automatically added to your installer file. |
||
219 | You need to list them yourself in the XML file for |
||
220 | the installer. A describtion how to do this follows in the next section. |
||
221 | <BR>
|
||
222 | <P>
|
||
223 | Native libraries can be added to the installer by using the |
||
224 | <TT><native></TT> tag. To add the <TT>ShellLink.dll</TT>, you just |
||
225 | have to add the following line to the installer XML file: |
||
226 | <BR><TT><native type="izpack" name="ShellLink.dll"/></TT> |
||
227 | <BR>
|
||
228 | For more details about the use of the <TT><native></TT> tag see the |
||
229 | chapter about the format of the XML file. |
||
230 | <BR>
|
||
231 | <P>
|
||
232 | You have also to add an extra specification file for each platform family to enable shortcut creation on these platforms. |
||
233 | At least one (the default file) is required by the shortcut panel. The format of all spec files is XML and they must be |
||
234 | added to the installer as a resource. The source name of this |
||
235 | specification does not matter, however its resource name (also called id or alias) when added to the |
||
236 | installer must be <TT>(prefix)+shortcutSpec.xml</TT>. |
||
237 | <BR>
|
||
238 | At this release, there are only two prefixes supported: "Win_" for the Windows family and "Unix_" for all Unixes. |
||
239 | If the prefix is ommited the shortcut panel searches for a named resource: <TT>shortcutSpec.xml</TT>. This is the default resource name. |
||
240 | As the default resource name will be used on Windows platforms, the <TT>"Win_shortcutSpec.xml"</TT> can be ommited. |
||
241 | <BR>
|
||
242 | Hint: If the shortcut panel does not find one of these named resources, it will never appears. |
||
243 | So, do not use different resource names and do not add a path to these. |
||
244 | <BR>
|
||
245 | <P>
|
||
246 | <SPAN CLASS="textbf">Example</SPAN> |
||
247 | <BR>
|
||
248 | <P>
|
||
249 | <PRE>
|
||
250 | <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml"
|
||
251 | id="shortcutSpec.xml"/>
|
||
252 | <res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml"
|
||
253 | id="Unix_shortcutSpec.xml"/>
|
||
254 | </PRE>
|
||
255 | <P>
|
||
256 | Why use different shortcut spec files? |
||
257 | <BR>
|
||
258 | <P>
|
||
259 | |||
260 | <OL>
|
||
261 | <LI>The Target filenames are most different.(batch files on Windows vs. shell scripts on Unix.)
|
||
262 | </LI>
|
||
263 | <LI>The Icon file formats are different. ICOs on Windows-, PNGs on Unix-platforms.
|
||
264 | </LI>
|
||
265 | <LI>The Target locations can be different.
|
||
266 | </LI>
|
||
267 | </OL>
|
||
268 | |||
269 | <P>
|
||
270 | This is the simple reason. |
||
271 | <BR>
|
||
272 | <P>
|
||
273 | |||
274 | <H2><A NAME="SECTION00613000000000000000"> |
||
275 | Why Native Code to do the Job on Windows?</A>
|
||
276 | </H2>
|
||
277 | |||
278 | <P>
|
||
279 | by Elmar |
||
280 | <BR>
|
||
281 | <P>
|
||
282 | This little chapter is not strictly part of the documentation but I have |
||
283 | been asked this question sufficiently often that I think it's worth |
||
284 | explaining right here. It is certainly a natural question to ask. After |
||
285 | all IzPack is an application completely written in Java and primarily |
||
286 | targeted for the installation of Java based programs. So why wouldn't we |
||
287 | try to keep everything pure Java and avoid the use of native code |
||
288 | altogether? There must be some personal preference of the developer |
||
289 | hidden behind this approach you might think. Well, not really, but I |
||
290 | admit at first it seems quite feasible to write it all in Java. On |
||
291 | virtually any operating system or GUI surface around, Shortcuts are |
||
292 | simply files on the local file system. Files can be created and accessed |
||
293 | directly from within Java, so why should there be a need for using |
||
294 | native code? |
||
295 | <BR>
|
||
296 | <P>
|
||
297 | Well, it turns out that just creating a file is not good enough, it also |
||
298 | needs to have the right content. Shell Links as they are called in |
||
299 | Windows land are binary files. I actually managed to find documentation |
||
300 | on the format. Naturally this was hacker data, you won't get this sort |
||
301 | of thing from Microsoft (by the way: thanks a lot to Jesse Hager for a |
||
302 | smash job!). Armed with this information I tried to create these files |
||
303 | myself in Java. The problem was that the documentation was not entirely |
||
304 | accurate and had some gaps as well. I tried for over a month to get this |
||
305 | to work but finally I had to give up. Even if I would have succeeded, it |
||
306 | would have been a hack, since a shell link requires some information that |
||
307 | is impossible to obtain from within Java. Usually you can successfully |
||
308 | create a shell link by only filling in the bare minimum information and |
||
309 | then ask Windows to resolve the link. Windows then repairs the shell |
||
310 | link. Unfortunately this was only the beginning, soon I encountered a |
||
311 | host of other problems. For one thing, the installer needs to know the |
||
312 | correct directories for placing the links and it turns out they are |
||
313 | named differently in different countries. In addition, there are ways of |
||
314 | manually modifying them, which some people might actually have done. The |
||
315 | only way to place the shortcut files reliably is through accessing the |
||
316 | Windows Registry. Naturally, this operation also required native code. |
||
317 | Same thing with asking Windows to resolve the link... On the bottom |
||
318 | line, at every step and turn you run into an issue where you just need |
||
319 | to use native code to do the trick. So I decided that I would do it the |
||
320 | proper way all the way through. That is in a nutshell the reason why I |
||
321 | used native code to create shortcuts on MS-Windows. |
||
322 | <BR>
|
||
323 | <P>
|
||
324 | As I am writing this I am at work with a friend to replicate this work |
||
325 | for the Mac and it looks very much like we need to take the same |
||
326 | approach there as well. On the various Unix GUIs on the other hand, we are lucky that we |
||
327 | can do the job without native libraries. |
||
328 | <BR>
|
||
329 | <P>
|
||
330 | |||
331 | <H2><A NAME="SECTION00614000000000000000"> |
||
332 | The Shortcut Specification</A>
|
||
333 | </H2>
|
||
334 | |||
335 | <P>
|
||
336 | As we say above, the specification for shortcuts is provided to the ShortcutPanel in the |
||
337 | XML fileformat. At the time of this writing (for IzPack version 3.7.0-M3) |
||
338 | the front-end will be rewritten. Until these work is in progress |
||
339 | you have to write the specification files manually. For your convenience, there are two annotated sample |
||
340 | specification files in the sample subdirectory of your IzPack installation. At the beginning you might want to experiment with these files. |
||
341 | <BR>
|
||
342 | <P>
|
||
343 | Both specification files have one root element called <TT><shortcuts></TT>. |
||
344 | This root elements recognizes 3 different child elements: |
||
345 | <BR><TT><programGroup></TT>, <TT><skipIfNotSupported/></TT> and <TT><shortcut></TT>. |
||
346 | <BR>
|
||
347 | <P>
|
||
348 | <TT><skipIfNotSupported/></TT> can be used to avoid the panel to show the alternative UI which shows the shortcut information |
||
349 | that would have been created on a system that supports it. In other words, |
||
350 | using this tag will make the panel be silent on non-supported systems. The |
||
351 | default is to show the alternative UI. |
||
352 | <BR>
|
||
353 | <P>
|
||
354 | The <TT><programGroup></TT> tag allows you to specify the name of the |
||
355 | menu, or more precise, the folder in which the shortcuts will be grouped. The exact location and |
||
356 | appearance of the program group depends on the specific target system on |
||
357 | which the application will be installed, however you can partially control it. |
||
358 | Please note that <TT><programGroup></TT> may only appear once |
||
359 | in the specification. If more than one instance occurs, only the first |
||
360 | one will be used. This tag requires two attributes: <TT>defaultName</TT> |
||
361 | and <TT>location</TT>. <TT>defaultName</TT> specifies the name that the |
||
362 | group menu should have on the target system. You should be aware that |
||
363 | the ShortcutPanel will present this name to the user as a choice. The |
||
364 | user can then edit this name or select a group that already exists. As a |
||
365 | result, there is no guarantee that the actual name of the program group |
||
366 | on the target system is identical with your specification. |
||
367 | <TT>location</TT> specifies where the group menu should show up. There |
||
368 | are two choices: <TT>applications</TT> and <TT>startMenu</TT>. If you |
||
369 | use <TT>applications</TT>, then the menu will be placed in the menu that |
||
370 | is ordinarily used for application shortcuts. <TT>applications</TT> is recommended for Unix shortcuts. |
||
371 | If you use <TT>startMenu</TT>, the group menu will be placed at the top most menu |
||
372 | level available on the target system. Depending on the target system, it |
||
373 | might not be possible to honor this specification exactly. In such |
||
374 | cases, the ShortcutPanel will map the choice to the location that most |
||
375 | closely resembles your choice. Unix shortcuts do not need to support the <TT>startMenu</TT>, because the <TT>applications</TT> menu is already on the highest level. This means this has no affect on thess platform. |
||
376 | <BR>
|
||
377 | <P>
|
||
378 | For each shortcut you want to create, you have to add one <TT><shortcut></TT> tag. |
||
379 | Most details about the shortcut are listed as attributes with this tag. |
||
380 | The following sections describe what each attribute does, which |
||
381 | attributes are optional and which ones are required and what the values |
||
382 | are that are accepted for each of the attributes. Note that all |
||
383 | attributes that have a yes/no choice can also be omitted. Doing so has |
||
384 | the same effect as using a value of no. The shortcut attributes can be |
||
385 | divided into two groups |
||
386 | <BR>
|
||
387 | <P>
|
||
388 | |||
389 | <UL>
|
||
390 | <LI>attributes that describe properties of the shortcut
|
||
391 | </LI>
|
||
392 | <LI>attributes that define the location(s) at which a copy of the
|
||
393 | shortcut should be placed. |
||
394 | </LI>
|
||
395 | </UL>
|
||
396 | <P>
|
||
397 | The following attributes are used to define location: |
||
398 | |||
399 | <UL>
|
||
400 | <LI><TT>programGroup</TT> |
||
401 | </LI>
|
||
402 | <LI><TT>desktop</TT> |
||
403 | </LI>
|
||
404 | <LI><TT>applications</TT> |
||
405 | </LI>
|
||
406 | <LI><TT>startMenu</TT> |
||
407 | </LI>
|
||
408 | <LI><TT>startup</TT> |
||
409 | </LI>
|
||
410 | </UL>
|
||
411 | <P>
|
||
412 | |||
413 | <H2><A NAME="SECTION00615000000000000000"> |
||
414 | Shortcut Attributes</A>
|
||
415 | </H2>
|
||
416 | |||
417 | <P>
|
||
418 | There are three classes of attributes. Some are required, most are |
||
419 | completely optional and some are semi-optional. The set of semi-optional |
||
420 | attributes are all the attributes used to define the location of a |
||
421 | shortcut. These are semi-optional because for any individual one it is |
||
422 | your choice if you want to include it or not. However they are not |
||
423 | completely optional. You must specify at least one location. If all were |
||
424 | omitted, the instruction would essentially tell the panel that a copy of |
||
425 | this shortcut is to be placed at no location. In other words no copy is |
||
426 | to be placed anywhere. |
||
427 | |||
428 | <P>
|
||
429 | <SPAN CLASS="textbf">name</SPAN> <TT>- required</TT> |
||
430 | <BR>
|
||
431 | <P>
|
||
432 | The value of this attribute defines the name that the shortcut will |
||
433 | have. This is the text that makes up the menu name if the shortcut is |
||
434 | placed in a menu or the caption that is displayed with the shortcut if |
||
435 | it is placed on the desktop. |
||
436 | <BR>
|
||
437 | <P>
|
||
438 | <SPAN CLASS="textbf">target</SPAN> <TT>- required</TT> |
||
439 | <BR>
|
||
440 | <P>
|
||
441 | The value of this attribute points to the application that should be |
||
442 | launched when the shortcut is clicked. The value is translated through |
||
443 | the variable substitutor. Therefore variables such as |
||
444 | <TT>$INSTALL_PATH</TT> can be used to describe the location. |
||
445 | <SPAN CLASS="textbf">You should be aware that the use of this tag is likely to change |
||
446 | once other operating systems are supported</SPAN>.
|
||
447 | <BR>
|
||
448 | <P>
|
||
449 | <SPAN CLASS="textbf">commandLine</SPAN> <TT>- optional</TT> |
||
450 | <BR>
|
||
451 | <P>
|
||
452 | The value of this attribute will be passed to the application as command |
||
453 | line. I recommend to work without command line arguments, since these are |
||
454 | not supported by all operating systems. As a result, your applications |
||
455 | will not be portable if they depend on command line arguments. Instead, |
||
456 | consider using system properties or configuration files. |
||
457 | <BR>
|
||
458 | <P>
|
||
459 | <SPAN CLASS="textbf">workingDirectory</SPAN> <TT>- optional</TT> |
||
460 | <BR>
|
||
461 | <P>
|
||
462 | This attribute defines the working directory for the application at the |
||
463 | time it is launched. I would recommend some caution in relying on this |
||
464 | too heavily if your application should be portable, since this might not |
||
465 | be supported by all operating systems. At this time I don't have enough |
||
466 | information to make a definite statement one way or the other. The value |
||
467 | is translated through the variable substitutor. Therefore variables such |
||
468 | as <TT>$INSTALL_PATH</TT> can be used to describe the directory. |
||
469 | <BR>
|
||
470 | <P>
|
||
471 | <SPAN CLASS="textbf">description</SPAN> <TT>- optional</TT> |
||
472 | <BR>
|
||
473 | <P>
|
||
474 | The value of this attribute will be visible to the user when a brief |
||
475 | description about associated application is requested. The form of the |
||
476 | request and the way in which this description is displayed varies |
||
477 | between operating systems. On MS-Windows the description is shown as a |
||
478 | tool tip when the mouse cursor hovers over the icon for a few seconds. |
||
479 | On some operating systems this feature might not be supported but I |
||
480 | think it is always a good idea to include a brief description. |
||
481 | <BR>
|
||
482 | <P>
|
||
483 | <SPAN CLASS="textbf">iconFile</SPAN> <TT>- optional</TT> |
||
484 | <BR>
|
||
485 | <P>
|
||
486 | The value of this attribute points to the file that holds the icon that |
||
487 | should be displayed as a symbol for this shortcut. This value is also |
||
488 | translated through the variable substitutor and consequently can contain |
||
489 | variables such as $INSTALL_PATH. If this attribute is omitted, no icon |
||
490 | will be specified for the shortcut. Usually this causes the OS to |
||
491 | display an OS supplied default icon. <SPAN CLASS="textbf">The use of this attribute |
||
492 | is also likely to change once other operating systems are supported. |
||
493 | Read the Section about Icons below, for more information.</SPAN>
|
||
494 | <BR>
|
||
495 | <P>
|
||
496 | <SPAN CLASS="textbf">iconIndex</SPAN> <TT>- optional</TT> |
||
497 | <BR>
|
||
498 | <P>
|
||
499 | If the file type for the icon supports multiple icons in one file, then |
||
500 | this attribute may be used to specify the correct index for the icon. I |
||
501 | would also advise against using this feature, because of operating |
||
502 | system incompatibilities in this area. In file formats that do not |
||
503 | support multiple icons, this values is ignored. |
||
504 | <BR>
|
||
505 | <P>
|
||
506 | <SPAN CLASS="textbf">initialState</SPAN> <TT>- optional</TT> |
||
507 | <BR>
|
||
508 | <P>
|
||
509 | There are four values accepted for this attribute: <TT>noShow</TT>, |
||
510 | <TT>normal</TT>, <TT>maximized</TT> and <TT>minimized</TT>. If the |
||
511 | target operating system supports this feature, then this value will have |
||
512 | the appropriate influence on the initial window state of the |
||
513 | application. <TT>noShow</TT> is particularly useful when launch scripts |
||
514 | are used that cause a command window to open, because the command window |
||
515 | will not be visible with this option. For instance on MS-Windows |
||
516 | starting a batch file that launches a Java application has the less than |
||
517 | pretty side effect that two windows show: the DOS command prompt and the |
||
518 | Java application window. Even if the shortcut is configured to show |
||
519 | minimized, there are buttons for both windows in the task bar. Using |
||
520 | <TT>noShow</TT> will completely eliminate this effect, only the Java |
||
521 | application window will be visible. <SPAN CLASS="textit">On Unix use </SPAN> <TT>normal</TT> |
||
522 | <SPAN CLASS="textit">, because this is not supported</SPAN>. |
||
523 | <BR>
|
||
524 | <P>
|
||
525 | <SPAN CLASS="textbf">programGroup</SPAN> <TT>- semi-optional</TT> |
||
526 | <BR>
|
||
527 | <P>
|
||
528 | The value for this attribute can be either yes or no. Any other value |
||
529 | will be interpreted as no. If the value is yes, then a copy of this |
||
530 | shortcut will be placed in the group menu. |
||
531 | <SPAN CLASS="textit">On Unix (KDE) this will always be placed on the top level.</SPAN> |
||
532 | <BR>
|
||
533 | <P>
|
||
534 | <SPAN CLASS="textbf">desktop</SPAN> <TT>- semi-optional</TT> |
||
535 | <BR>
|
||
536 | <P>
|
||
537 | For this attribute the value should also be yes or no. If the value is |
||
538 | yes, then a copy of the shortcut is placed on the desktop. |
||
539 | <SPAN CLASS="textit">On Unix the shortcuts will only be placed on the (KDE-) desktop |
||
540 | of the user, who currently runs the installer. For Gnome the user can |
||
541 | simply copy the *.desktop files from </SPAN> <TT>/Desktop</TT> <SPAN CLASS="textit"> to </SPAN> |
||
542 | <TT>/gnome-desktop</TT>. |
||
543 | (This is already a TODO for the Unix-shortcut implementation.) |
||
544 | <BR>
|
||
545 | <P>
|
||
546 | <SPAN CLASS="textbf">applications</SPAN> <TT>- semi-optional</TT> |
||
547 | <BR>
|
||
548 | <P>
|
||
549 | This is also a yes/no attribute. If the value is yes, then a copy of the |
||
550 | shortcut is placed in the applications menu (if the target operating |
||
551 | system supports this). This is the same location as the applications |
||
552 | choice for the program group. |
||
553 | <SPAN CLASS="textit">This makes no sense on Unix.</SPAN> |
||
554 | <BR>
|
||
555 | <P>
|
||
556 | <SPAN CLASS="textbf">startMenu</SPAN> <TT>- semi-optional</TT> |
||
557 | <BR>
|
||
558 | <P>
|
||
559 | This is a yes/no attribute as well. If the value is yes, then a copy of |
||
560 | the shortcut is placed directly in the top most menu that is available |
||
561 | for placing application shortcuts. |
||
562 | <SPAN CLASS="textit">This is not supported on Unix. see above.</SPAN> |
||
563 | <BR>
|
||
564 | <P>
|
||
565 | <SPAN CLASS="textbf">startup</SPAN> <TT>- semi-optional</TT> |
||
566 | <BR>
|
||
567 | <P>
|
||
568 | This is also a yes/no attribute. If the value is yes, then a copy of the |
||
569 | shortcut is placed in a location where all applications get automatically |
||
570 | started at OS launch time, if this is available on the target OS. |
||
571 | <SPAN CLASS="textit">This is also not supported on Unix.</SPAN> |
||
572 | <BR>
|
||
573 | <P>
|
||
574 | |||
575 | <H3><A NAME="SECTION00615100000000000000"> |
||
576 | Unix specific shortcut attributes </A>
|
||
577 | </H3>
|
||
578 | |||
579 | <P>
|
||
580 | This extension was programmed by M<SMALL>ARC </SMALL>E<SMALL>PPELMANN</SMALL>. |
||
581 | This is still in development and may be changed in |
||
582 | one of the next releases of IzPack. |
||
583 | <BR>
|
||
584 | <P>
|
||
585 | <SPAN CLASS="textbf">type</SPAN> <TT>- required</TT> |
||
586 | <BR>
|
||
587 | <P>
|
||
588 | This must be one of <TT>Application</TT> or <TT>Link</TT> |
||
589 | <BR>
|
||
590 | <P>
|
||
591 | |||
592 | <UL>
|
||
593 | <LI>Application: To start any application, native, Java or shell-script based,
|
||
594 | the <SPAN CLASS="textbf">type</SPAN> has to be <TT>Application</TT>. The GUI-System will launch |
||
595 | this Application, so as is, thru their native shell or application launcher. |
||
596 | In this case, note that the right <TT>workingDirectory</TT> |
||
597 | is always important on Unix platforms. If the users PATH environment |
||
598 | variable does not contain the path, where the application is located, |
||
599 | this can never be run, until the <TT>workingDirectory</TT> does not contain |
||
600 | these path. The needed current path: ".", this is the case on most |
||
601 | systems, should be in the users PATH environment variable. |
||
602 | Consult the Unix manuals for more details. |
||
603 | |||
604 | <P>
|
||
605 | </LI>
|
||
606 | <LI>Link: If you want to open a URL in the users default Webbrowser,
|
||
607 | you have to set the <SPAN CLASS="textbf">type</SPAN> to <TT>Link</TT>. Note: The <TT>url</TT> attribute |
||
608 | must be set to work properly. |
||
609 | |||
610 | <P>
|
||
611 | </LI>
|
||
612 | <LI>Other: There are more supported types on KDE, like FSDevice,
|
||
613 | but these types makes no sense for IzPack, in my opinion. |
||
614 | </LI>
|
||
615 | </UL>
|
||
616 | |||
617 | <P>
|
||
618 | Without the type the Unix shortcut does not work. |
||
619 | <BR>
|
||
620 | <P>
|
||
621 | <SPAN CLASS="textbf">url</SPAN> <TT>- semi-optional</TT> |
||
622 | <BR>
|
||
623 | <P>
|
||
624 | If you want to create a shortcut as type <SPAN CLASS="textit">Link</SPAN>, then you have |
||
625 | to set the <TT>url</TT> attribute. The value can be a locally installed |
||
626 | html or another document, with a known MIME type, like plain text, |
||
627 | or a WWW Url i.e. 'http://www.izforge.com/izpack'. |
||
628 | <BR>
|
||
629 | <P>
|
||
630 | A local document can be referenced by i.e. "$INSTALL_PATH/doc/index.html". |
||
631 | <BR>
|
||
632 | <P>
|
||
633 | The IzPack variable substitution system is supported by the <SPAN CLASS="textbf">url</SPAN>. |
||
634 | <BR>
|
||
635 | <P>
|
||
636 | <SPAN CLASS="textbf">encoding</SPAN> <TT>- required</TT> |
||
637 | <BR>
|
||
638 | <P>
|
||
639 | This should always set to <SPAN CLASS="textbf">UTF-8</SPAN>. |
||
640 | <BR>
|
||
641 | <P>
|
||
642 | <SPAN CLASS="textbf">terminal</SPAN> <TT>- optional</TT> |
||
643 | <BR>
|
||
644 | <P>
|
||
645 | If you want, the user can see the console output of a program |
||
646 | (in Java applications "System.outs"), set the <TT>terminal</TT> attribute to <SPAN CLASS="textbf">true</SPAN>. |
||
647 | <BR>
|
||
648 | <P>
|
||
649 | <SPAN CLASS="textbf">KdeSubstUID</SPAN> <TT>- unused</TT> |
||
650 | <BR>
|
||
651 | <P>
|
||
652 | This is not fully implemented by IzPack. |
||
653 | I the future this is the sudo option for a shortcut. |
||
654 | <BR>
|
||
655 | <P>
|
||
656 | |||
657 | <H2><A NAME="SECTION00616000000000000000"> |
||
658 | Selective Creation of Shortcuts</A>
|
||
659 | </H2>
|
||
660 | |||
661 | <P>
|
||
662 | Usually all shortcuts that are listed will be created when the user |
||
663 | clicks the 'Next' button. However it is possible to |
||
664 | control to some degree if specific shortcuts should be created or |
||
665 | not. This is based on install conditions. By including one or more |
||
666 | <TT><createForPack name=''a pack name'' /></TT> tags in the |
||
667 | specification for a shortcut, you can direct the ShortcutPanel to |
||
668 | create the shortcut only if any of the listed packs are actually |
||
669 | installed. The 'name' attribute is used to define the name of one of |
||
670 | the packs for which the shortcut should be created. You do not need to |
||
671 | list all packs if a shortcut should always be created. In this case |
||
672 | simply omit this tag altogether. |
||
673 | <BR>
|
||
674 | <P>
|
||
675 | <SPAN CLASS="textbf">A word of caution</SPAN> |
||
676 | <BR>
|
||
677 | <P>
|
||
678 | For any shortcut that is always created, I would recommend to omit this |
||
679 | tag, since I have seen a number of problems related to changing pack |
||
680 | names. You can save yourself some troubleshooting and some Aspirin by |
||
681 | not using this feature if it's not required. On the other hand if you |
||
682 | need it I would advise to be very careful about changing pack names. |
||
683 | <BR>
|
||
684 | <P>
|
||
685 | |||
686 | <H2><A NAME="SECTION00617000000000000000"> |
||
687 | Summary</A>
|
||
688 | </H2>
|
||
689 | |||
690 | <P>
|
||
691 | <SPAN CLASS="textbf">Native Libraries</SPAN> |
||
692 | |||
693 | <UL>
|
||
694 | <LI>ShellLink.dll <TT>- required by Microsoft Windows</TT> |
||
695 | </LI>
|
||
696 | <LI>'Nothing' <TT>- for KDE/Gnome shortcuts</TT> |
||
697 | </LI>
|
||
698 | </UL>
|
||
699 | <P>
|
||
700 | <SPAN CLASS="textbf">Names of the Specification Files</SPAN> |
||
701 | <BR><TT>shortcutSpec.xml</TT> for Windows and as default. |
||
702 | <BR><TT>Unix_shortcutSpec.xml</TT> for Unix. |
||
703 | <BR>
|
||
704 | <P>
|
||
705 | <SPAN CLASS="textbf">Specification File Layout - Windows</SPAN> |
||
706 | |||
707 | <P>
|
||
708 | <PRE>
|
||
709 | <shortcuts> |
||
710 | <skipIfNotSupported/> |
||
711 | <programGroup defaultName="MyOrganization\MyApplication"
|
||
712 | location="applications||startMenu"/>
|
||
713 | <shortcut
|
||
714 | name="Start MyApplication" |
||
715 | target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat" |
||
716 | commandLine="" |
||
717 | workingDirectory="$INSTALL_PATH\Path\to\MyApplication" |
||
718 | description="This starts MyApplication" |
||
719 | iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico" |
||
720 | iconIndex="0" |
||
721 | initialState="noShow||normal||maximized||minimized" |
||
722 | programGroup="yes||no" |
||
723 | desktop="yes||no" |
||
724 | applications="yes||no" |
||
725 | startMenu="yes||no" |
||
726 | startup="yes||no">
|
||
727 | |||
728 | <createForPack name="MyApplication Binaries"/> |
||
729 | <createForPack name="MyApplication Batchfiles"/> |
||
730 | </shortcut> |
||
731 | </shortcuts> |
||
732 | </PRE>
|
||
733 | <P>
|
||
734 | <SPAN CLASS="textbf">A sample Specification File for Unix is at the end of this chapter</SPAN> |
||
735 | |||
736 | <P>
|
||
737 | |||
738 | <H1><A NAME="SECTION00620000000000000000"> |
||
739 | Shortcut Tips</A>
|
||
740 | </H1>
|
||
741 | |||
742 | <P>
|
||
743 | I wrote this section to provide additional information about issues |
||
744 | surrounding the creation of shortcuts. Reading this section is not |
||
745 | necessary to successfully create shortcuts, but it might help you |
||
746 | creating an installation that works more smoothly. In addition, it might |
||
747 | give you some knowledge about operating systems that you don't know so |
||
748 | well. In fact most of the issues described in this section are focused |
||
749 | on differences in operating system specifics. |
||
750 | <BR>
|
||
751 | <P>
|
||
752 | |||
753 | <H2><A NAME="SECTION00621000000000000000"> |
||
754 | The Desktop</A>
|
||
755 | </H2>
|
||
756 | |||
757 | <P>
|
||
758 | You should recognize that the desktop is precious real estate for many |
||
759 | people. They like to keep it uncluttered and keep only the things there |
||
760 | that they use on a regular basis. This is not true for everybody and you |
||
761 | might personally think different about this. Still, the fact remains |
||
762 | that a lot of people might have different feelings about it, so you |
||
763 | should not automatically assume that it is ok to place all of your |
||
764 | shortcuts on the desktop proper. While your application is certainly one |
||
765 | of the most important things for you, for your customers it is probably |
||
766 | one of many applications they use and maybe not even the most important |
||
767 | one. Accordingly, placing more shortcut icons there than they feel they |
||
768 | will use on a regular basis and especially doing this without asking for |
||
769 | permission might trigger some bad temper. |
||
770 | <BR>
|
||
771 | <P>
|
||
772 | Annotation: But even the experienced user should be able to organize their Desktop. |
||
773 | On Linux the users desktop is the only place, which supports any kind of shortcuts. |
||
774 | <BR>
|
||
775 | <P>
|
||
776 | It is common practice to create a program group in the application menu |
||
777 | system of the OS and place all shortcuts that go with an application in |
||
778 | that program group. In addition, only one shortcut to the key access |
||
779 | point of the application is placed directly on the desktop. Many |
||
780 | installers first ask for permission to do so, as does the ShortcutPanel |
||
781 | in IzPack. |
||
782 | <BR>
|
||
783 | <P>
|
||
784 | I would like to recommend that you always create a shortcut in the menu |
||
785 | system, even if your application has only one access point and you are |
||
786 | placing this on the desktop. Note that shortcuts can also be placed directly |
||
787 | in the menu, they don't need to be in a program group. There are two |
||
788 | reasons for doing so. |
||
789 | <BR>
|
||
790 | <P>
|
||
791 | |||
792 | <UL>
|
||
793 | <LI>If the user elects not to create shortcuts on the desktop, they
|
||
794 | will end up with no access point to your application |
||
795 | </LI>
|
||
796 | <LI>Even if this works fine, occasionally people 'clean up' their
|
||
797 | desktop. They might later find that they accidentally deleted the |
||
798 | only access point to your application. For the less technology |
||
799 | savvy users, recreating the shortcut might be a rough experience. |
||
800 | </LI>
|
||
801 | </UL>
|
||
802 | |||
803 | <P>
|
||
804 | |||
805 | <H2><A NAME="SECTION00622000000000000000"> |
||
806 | Icons</A>
|
||
807 | </H2>
|
||
808 | |||
809 | <P>
|
||
810 | Icons are supplied in image files, usually in some kind of bitmap |
||
811 | format. Unfortunately there is no format that is universally recognized |
||
812 | by all operating systems. If you would like to create shortcuts on a |
||
813 | variety of operating systems that use your own icons, you must supply |
||
814 | each icon in a number of different formats. This chapter discusses icon |
||
815 | file formats used on various operating systems. Fortunately there are |
||
816 | good programs available that allow you to convert between these formats, |
||
817 | so that creating the different files is not much of a problem once the |
||
818 | icons themselves are created. |
||
819 | <BR>
|
||
820 | <P>
|
||
821 | <SPAN CLASS="textbf">Microsoft Windows</SPAN> |
||
822 | <BR>
|
||
823 | <P>
|
||
824 | Windows prefers to use its native icon file format. Files of this type |
||
825 | usually use the extension *.ico. These so called ICO files can hold |
||
826 | multiple icons in one file, which can be useful if the same icon is |
||
827 | to be provided in a number of sizes and color-depths. |
||
828 | |||
829 | <P>
|
||
830 | Windows itself selects the icon with the most matching dimensions and displays it. |
||
831 | While the Start menu displays the icon with 16x16 pixel if available, the desktop displays |
||
832 | the 32x32 pixel resolution of the same ICO if this is in. |
||
833 | |||
834 | <P>
|
||
835 | In other words, a ICO file has embedded one or more dimensions of the same Icon. |
||
836 | We recommend to play with <A NAME="tex2html25" |
||
837 | HREF="http://www.microangelo.us">microangelo</A>. |
||
838 | |||
839 | <P>
|
||
840 | Dlls and Exe files on the other side, can store, amongst other things, a collection of different Icons. |
||
841 | You can select your desired Icon by its index. The lowest index is 0. |
||
842 | Use the iconIndex attribute in the spec file to specify this index. |
||
843 | <BR>
|
||
844 | <P>
|
||
845 | As a sample look into |
||
846 | <PRE>
|
||
847 | %SystemRoot%\system32\shell32.dll |
||
848 | </PRE>
|
||
849 | These contains a lot of Windows own icons. |
||
850 | You can use the <A NAME="tex2html26" |
||
851 | HREF="http://www.heaventools.com">PE Explorer</A> |
||
852 | or another Resource Editor to extract or modify |
||
853 | Icons in dlls or exe files. But be warned. You can also destroy a working |
||
854 | application with these kind of tools. |
||
855 | |||
856 | <P>
|
||
857 | At least Windows also supports the use of bitmap files in the *.bmp format as |
||
858 | icons. Note that this format does not support multiple icons. |
||
859 | <BR>
|
||
860 | <P>
|
||
861 | We might have overlooked other file formats that are supported by Windows. |
||
862 | However, we suggest to test other formats for compatibility as they |
||
863 | might not work all the way back to Windows 95 or on the NT/non-NT strain. |
||
864 | Sticking with one of these two formats should keep you out of trouble. |
||
865 | <BR>
|
||
866 | <P>
|
||
867 | <SPAN CLASS="textbf">Apple</SPAN> |
||
868 | <BR>
|
||
869 | <P>
|
||
870 | Apple Macintosh systems use the Macintosh PICT format, extension *.pct. |
||
871 | If you are working with an apple system you know a whole lot more about |
||
872 | this format than I do. If you don't but would like to be able to install |
||
873 | your application on a Mac, simply start with any bitmap format that you |
||
874 | feel comfortable to work with. Then find an application that is capable |
||
875 | of converting this format into a *.pct file. I like to use Paint Shop |
||
876 | Pro (PC based), because it provides conversion capabilities among |
||
877 | several dozen different file formats. |
||
878 | <BR>
|
||
879 | <P>
|
||
880 | <SPAN CLASS="textbf">UNIX flavors</SPAN> |
||
881 | <BR>
|
||
882 | <P>
|
||
883 | by Marc Eppelmann |
||
884 | <BR>
|
||
885 | <P>
|
||
886 | As my knowledge, all X based Unix Window systems supports |
||
887 | the (ASCII-) XBM (X-Bitmap ) and the better XPM (X-PixMap) format. |
||
888 | The modern GUI systems like KDE and Gnome can display additionally |
||
889 | a lot of other ImageIcon formats, such as GIF, JPG, and PNG. |
||
890 | <BR>
|
||
891 | <P>
|
||
892 | I suggest to use PNG, because this can lossless compress like the GIF format, |
||
893 | however this format is absolutely free. And not least, this can store true |
||
894 | transparency informations (It has an alpha channel). |
||
895 | |||
896 | <P>
|
||
897 | |||
898 | <H2><A NAME="SECTION00623000000000000000"> |
||
899 | Targets</A>
|
||
900 | </H2>
|
||
901 | |||
902 | <P>
|
||
903 | So, you thought you could escape the ugly mess of operating system |
||
904 | dependencies at least with the way how your Java application is started? |
||
905 | Sorry but I have just another bad message. The one positive thing is |
||
906 | that here you have a way of escaping, even if doing so has a few less |
||
907 | pretty side effects. At first, I would like to discuss various launching |
||
908 | options you have available on different operating systems. At the end of |
||
909 | the chapter I write about a way to make launching your application OS |
||
910 | independent. |
||
911 | <BR>
|
||
912 | <P>
|
||
913 | <SPAN CLASS="textbf">Microsoft Windows</SPAN> |
||
914 | <BR>
|
||
915 | <P>
|
||
916 | On Microsoft Windows you have a variety of options for launching your |
||
917 | application. Probably the most simple case is directly starting the Java |
||
918 | VM from the command line and typing out all parameters, such as class |
||
919 | path, the class name etc. In principle, this can be placed right in a |
||
920 | shortcut and should work. |
||
921 | <BR>
|
||
922 | <P>
|
||
923 | A little more elegant solution is to place this in a batch file and have |
||
924 | the shortcut point to this batch file. This will also make it more |
||
925 | likely that users can repair or recreate shortcuts. Recreating shortcuts |
||
926 | with sophisticated command lines is practically impossible. |
||
927 | <BR>
|
||
928 | <P>
|
||
929 | Another method is less commonly used but just as possible. Implement a |
||
930 | native executable that launches the VM with your Java application. The |
||
931 | VM comes as DLL and is used by java.exe in just the same way. |
||
932 | As a sample look at the exlipse.exe provided by the <A NAME="tex2html27" |
||
933 | HREF="http://www.eclipse.org">Eclipse-IDE</A> |
||
934 | <BR>
|
||
935 | <P>
|
||
936 | Clearly, even though the first option is a bit ugly and has some |
||
937 | restrictionss, it is the most portable solution among the three. |
||
938 | <BR>
|
||
939 | <P>
|
||
940 | <SPAN CLASS="textbf">Apple</SPAN> |
||
941 | <BR>
|
||
942 | <P>
|
||
943 | We hope, there is a IzPack developer currently researching |
||
944 | for the details for the Mac environment. We expect |
||
945 | an updated chapter in one of the next releases. |
||
946 | <BR>
|
||
947 | <P>
|
||
948 | <SPAN CLASS="textbf">UNIX</SPAN> |
||
949 | <BR>
|
||
950 | <P>
|
||
951 | UNIX provides essentially the same options as Windows. You can simply |
||
952 | use the command line option, you can write a shell script and you can |
||
953 | write a native launcher. Naturally this stuff is in no way compatible |
||
954 | with the equivalent Windows implementations. The native option is even |
||
955 | more problematic in this environment, since the code can not even be |
||
956 | moved from one UNIX platform to another, without recompilation. |
||
957 | <BR>
|
||
958 | <P>
|
||
959 | <SPAN CLASS="textbf">OS Independent Launching</SPAN> |
||
960 | <BR>
|
||
961 | <P>
|
||
962 | So, after all this rather discouraging news, there is actually a |
||
963 | portable way to launch Java applications? You bet! although I have to |
||
964 | admit that it is not necessarily the most pretty way of doing things. |
||
965 | <BR>
|
||
966 | <P>
|
||
967 | This approach is currently used by IzPack. Package your application in a |
||
968 | *.jar file if you don't already do so and make it executable by including the |
||
969 | necessary METAINF/MANIFEST.MF information file. I am not |
||
970 | going into all the details on how exactly to do this, the Java |
||
971 | documentation will have to do. You might have noticed that even though |
||
972 | the instructions to install IzPack say to type : |
||
973 | <PRE>
|
||
974 | java -jar IzPack-install.jar |
||
975 | </PRE>
|
||
976 | |||
977 | <P>
|
||
978 | You can just as well double click on IzPack-install.jar and it will |
||
979 | start up. This procedure will work on all GUI based Java supported operating |
||
980 | systems -though you might have to replace double clicking with dropping |
||
981 | the file on the VM. In just the same way, you can make the *.jar file |
||
982 | itself the target of a shortcut. Note: This works only, if jars are registered |
||
983 | as files, which have to launch by the installed JRE (with: javaw.exe -jar *) |
||
984 | <BR>
|
||
985 | <P>
|
||
986 | The one restriction with this approach is that a *.jar file can only have |
||
987 | one main file. So, if you have multiple targets, they need to be |
||
988 | packaged each into a different *.jar file. They can be in one *.jar file |
||
989 | but then you have to start them explicitly, which gets you back to the |
||
990 | problems that I mentioned before. This brings me to the ugly part. If |
||
991 | you have just one target, then you are all set. If you have multiple |
||
992 | targets, you need to create a *.jar file for each of them. In addition, |
||
993 | you have a much harder time setting the classpath, because each of the |
||
994 | *.jar files that contain supporting code must be listed. In fact, at |
||
995 | present there is no way of setting this during the installation, because |
||
996 | IzPack does not yet (version 3.0) support the setting and modification |
||
997 | of environment variables. |
||
998 | <BR>
|
||
999 | <P>
|
||
1000 | |||
1001 | <H2><A NAME="SECTION00624000000000000000"> |
||
1002 | Command Line</A>
|
||
1003 | </H2>
|
||
1004 | |||
1005 | <P>
|
||
1006 | Before I start to write a lot about the use of command line arguments |
||
1007 | let me state this: If you can avoid using them, do it! Not that there |
||
1008 | is anything wrong with command line arguments as such. The issue is |
||
1009 | simply that if you want your application to be usable cross platform |
||
1010 | (the big Java promise) you should shy away from using command line |
||
1011 | arguments. The problem here is that not all operating systems actually |
||
1012 | support command line arguments. To be more precise, to my knowledge only |
||
1013 | Apple operating systems do not support command line parameters. If you |
||
1014 | don't care for running your application on a Mac, then you might not |
||
1015 | worry about his at all. If you are interested to support the Mac as |
||
1016 | well, read on. |
||
1017 | <BR>
|
||
1018 | <P>
|
||
1019 | In fact the Mac lower than MacOSX supports command line parameters in a way. |
||
1020 | More to the point, it supports a single parameter that your application should |
||
1021 | interpret as the name of a data file to open. You have no way of |
||
1022 | supplying this to your application through the command line attribute. |
||
1023 | The operating system generates this when the user drops the file on your |
||
1024 | application and then passes it as command line argument. That's it. This |
||
1025 | same behavior will probably fly well on pretty much any system and |
||
1026 | should therefore be an ok implementation. |
||
1027 | <BR>
|
||
1028 | <P>
|
||
1029 | So what to do if you want to modify program behavior based on runtime |
||
1030 | switches? For one thing, you could set system properties accordingly. |
||
1031 | The disadvantage here is the same as with the command line parameters: the |
||
1032 | way of setting these might vary between operating systems. The best way |
||
1033 | seems to be using a property file that contains the configuration |
||
1034 | data. |
||
1035 | <BR>
|
||
1036 | <P>
|
||
1037 | |||
1038 | <H1><A NAME="SECTION00630000000000000000"> |
||
1039 | Trouble Shooting</A>
|
||
1040 | </H1>
|
||
1041 | |||
1042 | <P>
|
||
1043 | by Elmar |
||
1044 | |||
1045 | <P>
|
||
1046 | It has been some time since I wrote this chapter during which a good |
||
1047 | number of users had a chance to gather experience. Unfortunately I |
||
1048 | never know how many have used it successfully without much difficulty. I |
||
1049 | only hear from those that have encountered one problem or another. The |
||
1050 | type of problems that I have seen prompted me to write this section, |
||
1051 | because I think it will help you in locating most problems that you might |
||
1052 | encounter or at least give you some idea where the problem might be |
||
1053 | located. |
||
1054 | <BR>
|
||
1055 | <P>
|
||
1056 | |||
1057 | <H2><A NAME="SECTION00631000000000000000"> |
||
1058 | Problems You Can Solve</A>
|
||
1059 | </H2>
|
||
1060 | |||
1061 | <P>
|
||
1062 | If you see an exception that essentially says that a library can not be |
||
1063 | loaded (ShellLink.dll) you have an easy problem to deal with. Your |
||
1064 | installer file is probably missing the native tag that adds the Windows |
||
1065 | dll to the installer or something with this tag is no quite right. Read |
||
1066 | 'What to Add to the Installer' for all details on this topic. |
||
1067 | <BR>
|
||
1068 | <P>
|
||
1069 | Most other problems cause the ShortcutPanel not to show at all during |
||
1070 | the installation process. The reason is simply that the ShortcutPanel |
||
1071 | skips if it does not know what to do or if it has nothing to do (no |
||
1072 | point showing then and confusing the user). The problem is that this is |
||
1073 | not always what you intended. The most simple but not so uncommon |
||
1074 | case is, that the ShortcutPanel cannot find their spec file. This can be caused by |
||
1075 | a number of reasons. The associated resource tag might be missing in the |
||
1076 | installer specification file, the target file name might be misspelled (the |
||
1077 | name you specify for the <TT>id</TT> attribute) or the target file name |
||
1078 | has a path or package name pre-pended. You have only to use |
||
1079 | <TT>shortcutSpec.xml</TT> or <TT>Unix_shortcutSpec.xml</TT> and nothing else, |
||
1080 | just as described in 'What to Add to the Installer'. |
||
1081 | You can always verify if this part is ok by |
||
1082 | inspecting the content of the installer *.jar file. The file |
||
1083 | shortcutSpec.xml should be located in the directory <TT>res</TT>. This |
||
1084 | inspection can be performed with any zip tool. If the file is not there, |
||
1085 | first correct this before proceeding. |
||
1086 | <BR>
|
||
1087 | <P>
|
||
1088 | If the file is there and the panel does not appear, you have a problem |
||
1089 | within the specification file. In most cases that I have seen, it comes |
||
1090 | down to a spelling mistake of an attribute or tag name. You just have to |
||
1091 | carefully make sure that everything is spelled correctly. Don't forget |
||
1092 | that all names are case sensitive! In a few cases it is also happend, |
||
1093 | that required or semi-optional attributes are omitted, so you might want |
||
1094 | to verify if all attributes that you need are actually supplied. |
||
1095 | <BR>
|
||
1096 | <P>
|
||
1097 | If everything is correct up to this point the problem becomes more |
||
1098 | elusive. Most likely the panel will not be displayed, because it is instructed |
||
1099 | not to show. There are be several reasons for this. The simple |
||
1100 | case is that no location has been specified for the shortcuts in your |
||
1101 | installation. This can happen if all five location attributes are |
||
1102 | omitted or if all the ones that are listed are set to <TT>no</TT>. |
||
1103 | Remember, you have to specify at least one location for every shortcut. If |
||
1104 | this is also correct, you might have used the <TT><createForPack></TT> tag. Review |
||
1105 | the details in 'Selective Creation of Shortcuts'. One possibility for |
||
1106 | the panel not to show is that based on the packs that are currently |
||
1107 | selected for installation no shortcut qualifies for creation. In this |
||
1108 | case the panel will not show, this is perfectly normal behavior. More |
||
1109 | likely this condition is true because of some accident and not because |
||
1110 | it's intended. Make sure the packs that you list for the shortcut are |
||
1111 | actually defined in your installation and verify that they are all |
||
1112 | spelled correctly. Remember: case matters! Did the ShortcutPanel use to |
||
1113 | work in your installation and all of a sudden stopped working? Very |
||
1114 | likely you are dealing with the last problem. A package name might have |
||
1115 | been modified and the shortcut spec was not adjusted to stay in sync. |
||
1116 | <BR>
|
||
1117 | <P>
|
||
1118 | |||
1119 | <H2><A NAME="SECTION00632000000000000000"> |
||
1120 | Problems That Have No Solution (yet)</A>
|
||
1121 | </H2>
|
||
1122 | |||
1123 | <P>
|
||
1124 | Unfortunately one problem has been very persistent and only recently one |
||
1125 | user found the reason. The problem occurs when installing on some target |
||
1126 | systems where non-English characters are used in the storage path for |
||
1127 | the shortcuts. The problem is that these characters don't seem to be |
||
1128 | properly translated across the Java Native Interface. This leads to a |
||
1129 | situation where the proper path can not be located and the shortcut |
||
1130 | creation fails. I write 'some target systems' because it does not fail |
||
1131 | everywhere. After much agonizing over this problem, one user found the |
||
1132 | solution: The shortcut creation works fine if a Sun virtual machine is |
||
1133 | installed, but fails if a version from IBM happens to be installed. So |
||
1134 | far I have no solution for this problem but I am trying to find a |
||
1135 | workaround the problem. |
||
1136 | <BR>
|
||
1137 | <P>
|
||
1138 | |||
1139 | <H2><A NAME="SECTION00633000000000000000"> |
||
1140 | A sample shortcut specification file for Unix</A>
|
||
1141 | </H2>
|
||
1142 | |||
1143 | <P>
|
||
1144 | <PRE>
|
||
1145 | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> |
||
1146 | |||
1147 | <shortcuts> |
||
1148 | |||
1149 | <programGroup defaultName="IzForge/IzPack" location="applications"/> |
||
1150 | |||
1151 | <!-- Disabled since there is no Frontend
|
||
1152 | shortcut |
||
1153 | name="IzPack" |
||
1154 | programGroup="yes" |
||
1155 | desktop="yes" |
||
1156 | applications="no" |
||
1157 | startMenu="yes" |
||
1158 | startup="no" |
||
1159 | target="$INSTALL_PATH/bin/izpack-fe.sh" |
||
1160 | commandLine="" |
||
1161 | workingDirectory="$INSTALL_PATH/bin" |
||
1162 | description="Front-End for IzPack installation tool" |
||
1163 | iconFile="$INSTALL_PATH/bin/icons/izpack.png" |
||
1164 | iconIndex="0" |
||
1165 | type="Application" |
||
1166 | encoding="UTF-8" |
||
1167 | terminal="true" |
||
1168 | KdeSubstUID="false" |
||
1169 | initialState="normal">
|
||
1170 | <createForPack name="Core"/> |
||
1171 | </shortcut --> |
||
1172 | |||
1173 | <shortcut
|
||
1174 | name="IzPack Documentation" |
||
1175 | programGroup="yes" |
||
1176 | desktop="yes" |
||
1177 | applications="no" |
||
1178 | startMenu="yes" |
||
1179 | startup="no" |
||
1180 | target="konqueror" |
||
1181 | workingDirectory="" |
||
1182 | commandLine="" |
||
1183 | initialState="noShow" |
||
1184 | iconFile="help" |
||
1185 | iconIndex="0" |
||
1186 | url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html" |
||
1187 | type="Link" |
||
1188 | encoding="UTF-8" |
||
1189 | description="IzPack user documentation (HTML format)">
|
||
1190 | |||
1191 | <createForPack name="Documentation-HTML"/> |
||
1192 | </shortcut> |
||
1193 | |||
1194 | <shortcut
|
||
1195 | name="Documentation" |
||
1196 | programGroup="yes" |
||
1197 | desktop="yes" |
||
1198 | applications="no" |
||
1199 | startMenu="yes" |
||
1200 | startup="no" |
||
1201 | target="acroread" |
||
1202 | workingDirectory="" |
||
1203 | commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
||
1204 | initialState="noShow" |
||
1205 | iconFile="acroread" |
||
1206 | iconIndex="0" |
||
1207 | url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
||
1208 | type="Application" |
||
1209 | encoding="UTF-8" |
||
1210 | description="IzPack user documentation (PDF format)">
|
||
1211 | |||
1212 | <createForPack name="Documentation-PDF"/> |
||
1213 | </shortcut> |
||
1214 | |||
1215 | <shortcut
|
||
1216 | name="Uninstaller" |
||
1217 | programGroup="yes" |
||
1218 | desktop="yes" |
||
1219 | applications="no" |
||
1220 | startMenu="no" |
||
1221 | startup="no" |
||
1222 | target="/usr/lib/java/bin/java" |
||
1223 | commandLine="-jar &quot;$INSTALL_PATH/Uninstaller/uninstaller.jar&quot;" |
||
1224 | initialState="noShow" |
||
1225 | iconFile="trashcan_full" |
||
1226 | iconIndex="0" |
||
1227 | workingDirectory="" |
||
1228 | type="Application" |
||
1229 | encoding="UTF-8" |
||
1230 | description="IzPack uninstaller">
|
||
1231 | <createForPack name="Core" /> |
||
1232 | </shortcut> |
||
1233 | |||
1234 | </shortcuts> |
||
1235 | </PRE>
|
||
1236 | <DIV CLASS="navigation"><HR> |
||
1237 | <!--Navigation Panel-->
|
||
1238 | <A NAME="tex2html431" |
||
1239 | HREF="node7.html"> |
||
1240 | <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
||
1241 | <A NAME="tex2html427" |
||
1242 | HREF="izpack-doc.html"> |
||
1243 | <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
||
1244 | <A NAME="tex2html421" |
||
1245 | HREF="node5.html"> |
||
1246 | <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
||
1247 | <A NAME="tex2html429" |
||
1248 | HREF="node1.html"> |
||
1249 | <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
||
1250 | <BR>
|
||
1251 | <B> Next:</B> <A NAME="tex2html432" |
||
1252 | HREF="node7.html">Creating Your Own Panels</A> |
||
1253 | <B> Up:</B> <A NAME="tex2html428" |
||
1254 | HREF="izpack-doc.html">izpack-doc</A> |
||
1255 | <B> Previous:</B> <A NAME="tex2html422" |
||
1256 | HREF="node5.html">Advanced Features</A> |
||
1257 | <B> <A NAME="tex2html430" |
||
1258 | HREF="node1.html">Contents</A></B> </DIV> |
||
1259 | <!--End of Navigation Panel-->
|
||
1260 | <ADDRESS>
|
||
1261 | Julien Ponge |
||
1262 | 2005-04-22 |
||
1263 | </ADDRESS>
|
||
1264 | </BODY>
|
||
1265 | </HTML> |