svn-gvsig-desktop / tags / v1_2_Build_1200 / install / IzPack / src / doc / chapter4.tex @ 38629
History | View | Annotate | Download (42.2 KB)
1 | 5819 | cesar | % IzPack - Documentation |
---|---|---|---|
2 | |||
3 | % Shortcut definition |
||
4 | |||
5 | \chapter{Desktop Shortcuts} (by Elmar \textsc{Grom} and Marc \textsc{Eppelmann})\\ |
||
6 | |||
7 | \section{Defining Shortcuts} |
||
8 | |||
9 | \subsection{Introduction} |
||
10 | |||
11 | On todays GUI oriented operating systems, users are used to launching |
||
12 | applications, view web sites, look at documentation and perform a |
||
13 | variety of other tasks, by simply clicking on an icon on the desktop or |
||
14 | in a menu system located on the desktop. Depending on the operating |
||
15 | system these icons have different names. In this context we will refer to |
||
16 | them collectively as shortcuts.\\ |
||
17 | |||
18 | Apart from actually placing an application on the target system, users |
||
19 | routinely expect an installer to create the necessary shortcuts for the |
||
20 | application as well. For you as application developer, this means that |
||
21 | for a professional appearance of your product you should also |
||
22 | consider creating shortcuts.\\ |
||
23 | |||
24 | In contrast to the general specification of an IzPack installer, the |
||
25 | specification of shortcuts in IzPack requires a little more effort. In |
||
26 | addition, some of the concepts are a bit more complex and there are some |
||
27 | operating system specific issues to observe. Fortunately, you only need |
||
28 | to worry about operating system specifics if you want to deploy your |
||
29 | application to multiple different operating systems. In any case, it |
||
30 | will pay off to spend some time to study this documentation and the |
||
31 | example spec files before you start to implement your own shortcuts.\\ |
||
32 | |||
33 | At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is only |
||
34 | capable to creating shortcuts on |
||
35 | \begin{enumerate} |
||
36 | \item Microsoft Windows\\ |
||
37 | and |
||
38 | \item Unix and Unix-based operating systems (like Linux), which use the \href{http://www.x11.org/}{X11} GUI-System and \href{http://www.freedesktop.org/}{FreeDesktop.org} |
||
39 | based shortcut handling (such as \href{http://www.kde.org/}{KDE} and \href{http://www.gnome.org/}{Gnome}). |
||
40 | |||
41 | \end{enumerate} |
||
42 | |||
43 | Other operating or GUI systems, such as MacOS \texttt{<} MacOS-X are |
||
44 | not supported. However, there is a special UI-variant that automatically pops up |
||
45 | on unsupported systems. It informs the user about the intended targets of your shortcuts and allows |
||
46 | the user to save this information to a text file. While this is not an |
||
47 | elegant solution, at least it aids the user in the manual creation of |
||
48 | the shortcuts.\\ |
||
49 | |||
50 | If you would like to review what an end user would see if the target |
||
51 | operating system is not supported, you can do the following. Simply |
||
52 | place the tag \texttt{<notSupported/>} in the spec file. This tag requires no |
||
53 | attributes or other data. It must be placed under \texttt{<shortcuts>}, just like |
||
54 | the individual shortcut specifications. Be sure to remove this tag |
||
55 | before getting your application ready for shipment.\\ |
||
56 | |||
57 | We expect other operating systems to be supported in the near future and |
||
58 | as always, contributions are very welcome. At present someone is |
||
59 | actively working on Mac support. |
||
60 | |||
61 | \subsection{What to Add to the Installer} |
||
62 | |||
63 | There are some things that you have to add to your installer to enable |
||
64 | shortcut creation. Obviously you need to add the panel |
||
65 | responsible for creating shortcuts. This panel is aptly enough called |
||
66 | ShortcutPanel. However, in order for the ShortcutPanel to work |
||
67 | properly a number of additional items are required. These must be added |
||
68 | manually to the installer, as all other resourcs, since the front-end will be rewritten. |
||
69 | In this chapter we will explain which of these items are |
||
70 | required and for what reason.\\ |
||
71 | |||
72 | First, we would like to discuss items that are supplied with IzPack and |
||
73 | only need to be added to the installer. After that, we move on to the |
||
74 | things you have to prepare yourself before you can add them. The way in |
||
75 | which shortcuts are created varies widely among operating systems. In |
||
76 | some cases it is possible to do this with pure Java code, while |
||
77 | other systems -such as MS-Windows- require native code to accomplish |
||
78 | this task. On the other side, the current implementation, which creates shortcuts on |
||
79 | Unix based systems needs no native library at all, since it works with 'these' pure Java code. |
||
80 | The native library required for the Windows operating |
||
81 | systems are supplied with IzPack is called \texttt{ShellLink.dll}. |
||
82 | Note: They will not be automatically added to your installer file. |
||
83 | You need to list them yourself in the XML file for |
||
84 | the installer. A describtion how to do this follows in the next section.\\ |
||
85 | |||
86 | Native libraries can be added to the installer by using the |
||
87 | \texttt{<native>} tag. To add the \texttt{ShellLink.dll}, you just |
||
88 | have to add the following line to the installer XML file:\\ |
||
89 | \texttt{<native type="izpack" name="ShellLink.dll"/>}\\ |
||
90 | For more details about the use of the \texttt{<native>} tag see the |
||
91 | chapter about the format of the XML file.\\ |
||
92 | |||
93 | You have also to add an extra specification file for each platform family to enable shortcut creation on these platforms. |
||
94 | At least one (the default file) is required by the shortcut panel. The format of all spec files is XML and they must be |
||
95 | added to the installer as a resource. The source name of this |
||
96 | specification does not matter, however its resource name (also called id or alias) when added to the |
||
97 | installer must be \texttt{(prefix)+shortcutSpec.xml}.\\ |
||
98 | At this release, there are only two prefixes supported: "Win\_" for the Windows family and "Unix\_" for all Unixes. |
||
99 | If the prefix is ommited the shortcut panel searches for a named resource: \texttt{shortcutSpec.xml}. This is the default resource name. |
||
100 | As the default resource name will be used on Windows platforms, the \texttt{"Win\_shortcutSpec.xml"} can be ommited.\\ |
||
101 | Hint: If the shortcut panel does not find one of these named resources, it will never appears. |
||
102 | So, do not use different resource names and do not add a path to these.\\ |
||
103 | |||
104 | \textbf{Example}\\ |
||
105 | |||
106 | \footnotesize |
||
107 | \begin{verbatim} |
||
108 | <res src="C:\MyDocuments\Installer\default_shortcut_specification.xml" |
||
109 | id="shortcutSpec.xml"/> |
||
110 | <res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml" |
||
111 | id="Unix_shortcutSpec.xml"/> |
||
112 | \end{verbatim} |
||
113 | \normalsize |
||
114 | |||
115 | Why use different shortcut spec files?\\ |
||
116 | |||
117 | \begin{enumerate} |
||
118 | \item The Target filenames are most different.(batch files on Windows vs. shell scripts on Unix.) |
||
119 | \item The Icon file formats are different. ICOs on Windows-, PNGs on Unix-platforms. |
||
120 | \item The Target locations can be different. |
||
121 | \end{enumerate} |
||
122 | |||
123 | This is the simple reason.\\ |
||
124 | |||
125 | |||
126 | |||
127 | \subsection{Why Native Code to do the Job on Windows?} |
||
128 | |||
129 | by Elmar\\ |
||
130 | |||
131 | This little chapter is not strictly part of the documentation but I have |
||
132 | been asked this question sufficiently often that I think it's worth |
||
133 | explaining right here. It is certainly a natural question to ask. After |
||
134 | all IzPack is an application completely written in Java and primarily |
||
135 | targeted for the installation of Java based programs. So why wouldn't we |
||
136 | try to keep everything pure Java and avoid the use of native code |
||
137 | altogether? There must be some personal preference of the developer |
||
138 | hidden behind this approach you might think. Well, not really, but I |
||
139 | admit at first it seems quite feasible to write it all in Java. On |
||
140 | virtually any operating system or GUI surface around, Shortcuts are |
||
141 | simply files on the local file system. Files can be created and accessed |
||
142 | directly from within Java, so why should there be a need for using |
||
143 | native code?\\ |
||
144 | |||
145 | Well, it turns out that just creating a file is not good enough, it also |
||
146 | needs to have the right content. Shell Links as they are called in |
||
147 | Windows land are binary files. I actually managed to find documentation |
||
148 | on the format. Naturally this was hacker data, you won't get this sort |
||
149 | of thing from Microsoft (by the way: thanks a lot to Jesse Hager for a |
||
150 | smash job!). Armed with this information I tried to create these files |
||
151 | myself in Java. The problem was that the documentation was not entirely |
||
152 | accurate and had some gaps as well. I tried for over a month to get this |
||
153 | to work but finally I had to give up. Even if I would have succeeded, it |
||
154 | would have been a hack, since a shell link requires some information that |
||
155 | is impossible to obtain from within Java. Usually you can successfully |
||
156 | create a shell link by only filling in the bare minimum information and |
||
157 | then ask Windows to resolve the link. Windows then repairs the shell |
||
158 | link. Unfortunately this was only the beginning, soon I encountered a |
||
159 | host of other problems. For one thing, the installer needs to know the |
||
160 | correct directories for placing the links and it turns out they are |
||
161 | named differently in different countries. In addition, there are ways of |
||
162 | manually modifying them, which some people might actually have done. The |
||
163 | only way to place the shortcut files reliably is through accessing the |
||
164 | Windows Registry. Naturally, this operation also required native code. |
||
165 | Same thing with asking Windows to resolve the link... On the bottom |
||
166 | line, at every step and turn you run into an issue where you just need |
||
167 | to use native code to do the trick. So I decided that I would do it the |
||
168 | proper way all the way through. That is in a nutshell the reason why I |
||
169 | used native code to create shortcuts on MS-Windows.\\ |
||
170 | |||
171 | As I am writing this I am at work with a friend to replicate this work |
||
172 | for the Mac and it looks very much like we need to take the same |
||
173 | approach there as well. On the various Unix GUIs on the other hand, we are lucky that we |
||
174 | can do the job without native libraries.\\ |
||
175 | |||
176 | \subsection{The Shortcut Specification} |
||
177 | |||
178 | As we say above, the specification for shortcuts is provided to the ShortcutPanel in the |
||
179 | XML fileformat. At the time of this writing (for IzPack version 3.7.0-M3) |
||
180 | the front-end will be rewritten. Until these work is in progress |
||
181 | you have to write the specification files manually. For your convenience, there are two annotated sample |
||
182 | specification files in the sample subdirectory of your IzPack installation. At the beginning you might want to experiment with these files.\\ |
||
183 | |||
184 | Both specification files have one root element called \texttt{<shortcuts>}. |
||
185 | This root elements recognizes 3 different child elements:\\ |
||
186 | \texttt{<programGroup>}, \texttt{<skipIfNotSupported/>} and \texttt{<shortcut>}.\\ |
||
187 | |||
188 | \texttt{<skipIfNotSupported/>} can be used to avoid the panel to show the alternative UI which shows the shortcut information |
||
189 | that would have been created on a system that supports it. In other words, |
||
190 | using this tag will make the panel be silent on non-supported systems. The |
||
191 | default is to show the alternative UI.\\ |
||
192 | |||
193 | The \texttt{<programGroup>} tag allows you to specify the name of the |
||
194 | menu, or more precise, the folder in which the shortcuts will be grouped. The exact location and |
||
195 | appearance of the program group depends on the specific target system on |
||
196 | which the application will be installed, however you can partially control it. |
||
197 | Please note that \texttt{<programGroup>} may only appear once |
||
198 | in the specification. If more than one instance occurs, only the first |
||
199 | one will be used. This tag requires two attributes: \texttt{defaultName} |
||
200 | and \texttt{location}. \texttt{defaultName} specifies the name that the |
||
201 | group menu should have on the target system. You should be aware that |
||
202 | the ShortcutPanel will present this name to the user as a choice. The |
||
203 | user can then edit this name or select a group that already exists. As a |
||
204 | result, there is no guarantee that the actual name of the program group |
||
205 | on the target system is identical with your specification. |
||
206 | \texttt{location} specifies where the group menu should show up. There |
||
207 | are two choices: \texttt{applications} and \texttt{startMenu}. If you |
||
208 | use \texttt{applications}, then the menu will be placed in the menu that |
||
209 | is ordinarily used for application shortcuts. \texttt{applications} is recommended for Unix shortcuts. |
||
210 | If you use \texttt{startMenu}, the group menu will be placed at the top most menu |
||
211 | level available on the target system. Depending on the target system, it |
||
212 | might not be possible to honor this specification exactly. In such |
||
213 | cases, the ShortcutPanel will map the choice to the location that most |
||
214 | closely resembles your choice. Unix shortcuts do not need to support the \texttt{startMenu}, because the \texttt{applications} menu is already on the highest level. This means this has no affect on thess platform.\\ |
||
215 | |||
216 | For each shortcut you want to create, you have to add one \texttt{<shortcut>} tag. |
||
217 | Most details about the shortcut are listed as attributes with this tag. |
||
218 | The following sections describe what each attribute does, which |
||
219 | attributes are optional and which ones are required and what the values |
||
220 | are that are accepted for each of the attributes. Note that all |
||
221 | attributes that have a yes/no choice can also be omitted. Doing so has |
||
222 | the same effect as using a value of no. The shortcut attributes can be |
||
223 | divided into two groups\\ |
||
224 | |||
225 | \begin{itemize} |
||
226 | \item attributes that describe properties of the shortcut |
||
227 | \item attributes that define the location(s) at which a copy of the |
||
228 | shortcut should be placed. |
||
229 | \end{itemize}\ |
||
230 | |||
231 | The following attributes are used to define location: |
||
232 | \begin{itemize} |
||
233 | \item \texttt{programGroup} |
||
234 | \item \texttt{desktop} |
||
235 | \item \texttt{applications} |
||
236 | \item \texttt{startMenu} |
||
237 | \item \texttt{startup} |
||
238 | \end{itemize}\ |
||
239 | |||
240 | \subsection{Shortcut Attributes} |
||
241 | |||
242 | There are three classes of attributes. Some are required, most are |
||
243 | completely optional and some are semi-optional. The set of semi-optional |
||
244 | attributes are all the attributes used to define the location of a |
||
245 | shortcut. These are semi-optional because for any individual one it is |
||
246 | your choice if you want to include it or not. However they are not |
||
247 | completely optional. You must specify at least one location. If all were |
||
248 | omitted, the instruction would essentially tell the panel that a copy of |
||
249 | this shortcut is to be placed at no location. In other words no copy is |
||
250 | to be placed anywhere. |
||
251 | |||
252 | \textbf{name} \texttt{- required}\\ |
||
253 | |||
254 | The value of this attribute defines the name that the shortcut will |
||
255 | have. This is the text that makes up the menu name if the shortcut is |
||
256 | placed in a menu or the caption that is displayed with the shortcut if |
||
257 | it is placed on the desktop.\\ |
||
258 | |||
259 | \textbf{target} \texttt{- required}\\ |
||
260 | |||
261 | The value of this attribute points to the application that should be |
||
262 | launched when the shortcut is clicked. The value is translated through |
||
263 | the variable substitutor. Therefore variables such as |
||
264 | \texttt{\$INSTALL\_PATH} can be used to describe the location. |
||
265 | \textbf{You should be aware that the use of this tag is likely to change |
||
266 | once other operating systems are supported}.\\ |
||
267 | |||
268 | \textbf{commandLine} \texttt{- optional}\\ |
||
269 | |||
270 | The value of this attribute will be passed to the application as command |
||
271 | line. I recommend to work without command line arguments, since these are |
||
272 | not supported by all operating systems. As a result, your applications |
||
273 | will not be portable if they depend on command line arguments. Instead, |
||
274 | consider using system properties or configuration files.\\ |
||
275 | |||
276 | \textbf{workingDirectory} \texttt{- optional}\\ |
||
277 | |||
278 | This attribute defines the working directory for the application at the |
||
279 | time it is launched. I would recommend some caution in relying on this |
||
280 | too heavily if your application should be portable, since this might not |
||
281 | be supported by all operating systems. At this time I don't have enough |
||
282 | information to make a definite statement one way or the other. The value |
||
283 | is translated through the variable substitutor. Therefore variables such |
||
284 | as \texttt{\$INSTALL\_PATH} can be used to describe the directory.\\ |
||
285 | |||
286 | \textbf{description} \texttt{- optional}\\ |
||
287 | |||
288 | The value of this attribute will be visible to the user when a brief |
||
289 | description about associated application is requested. The form of the |
||
290 | request and the way in which this description is displayed varies |
||
291 | between operating systems. On MS-Windows the description is shown as a |
||
292 | tool tip when the mouse cursor hovers over the icon for a few seconds. |
||
293 | On some operating systems this feature might not be supported but I |
||
294 | think it is always a good idea to include a brief description.\\ |
||
295 | |||
296 | \textbf{iconFile} \texttt{- optional}\\ |
||
297 | |||
298 | The value of this attribute points to the file that holds the icon that |
||
299 | should be displayed as a symbol for this shortcut. This value is also |
||
300 | translated through the variable substitutor and consequently can contain |
||
301 | variables such as \$INSTALL\_PATH. If this attribute is omitted, no icon |
||
302 | will be specified for the shortcut. Usually this causes the OS to |
||
303 | display an OS supplied default icon. \textbf{The use of this attribute |
||
304 | is also likely to change once other operating systems are supported. |
||
305 | Read the Section about Icons below, for more information.}\\ |
||
306 | |||
307 | \textbf{iconIndex} \texttt{- optional}\\ |
||
308 | |||
309 | If the file type for the icon supports multiple icons in one file, then |
||
310 | this attribute may be used to specify the correct index for the icon. I |
||
311 | would also advise against using this feature, because of operating |
||
312 | system incompatibilities in this area. In file formats that do not |
||
313 | support multiple icons, this values is ignored.\\ |
||
314 | |||
315 | \textbf{initialState} \texttt{- optional}\\ |
||
316 | |||
317 | There are four values accepted for this attribute: \texttt{noShow}, |
||
318 | \texttt{normal}, \texttt{maximized} and \texttt{minimized}. If the |
||
319 | target operating system supports this feature, then this value will have |
||
320 | the appropriate influence on the initial window state of the |
||
321 | application. \texttt{noShow} is particularly useful when launch scripts |
||
322 | are used that cause a command window to open, because the command window |
||
323 | will not be visible with this option. For instance on MS-Windows |
||
324 | starting a batch file that launches a Java application has the less than |
||
325 | pretty side effect that two windows show: the DOS command prompt and the |
||
326 | Java application window. Even if the shortcut is configured to show |
||
327 | minimized, there are buttons for both windows in the task bar. Using |
||
328 | \texttt{noShow} will completely eliminate this effect, only the Java |
||
329 | application window will be visible. \textit{On Unix use } \texttt{normal} |
||
330 | \textit{, because this is not supported}.\\ |
||
331 | |||
332 | \textbf{programGroup} \texttt{- semi-optional}\\ |
||
333 | |||
334 | The value for this attribute can be either yes or no. Any other value |
||
335 | will be interpreted as no. If the value is yes, then a copy of this |
||
336 | shortcut will be placed in the group menu. |
||
337 | \textit{On Unix (KDE) this will always be placed on the top level.}\\ |
||
338 | |||
339 | \textbf{desktop} \texttt{- semi-optional}\\ |
||
340 | |||
341 | For this attribute the value should also be yes or no. If the value is |
||
342 | yes, then a copy of the shortcut is placed on the desktop. |
||
343 | \textit{On Unix the shortcuts will only be placed on the (KDE-) desktop |
||
344 | of the user, who currently runs the installer. For Gnome the user can |
||
345 | simply copy the *.desktop files from } \texttt{\~/Desktop} \textit{ to } |
||
346 | \texttt{\~/gnome-desktop}. |
||
347 | (This is already a TODO for the Unix-shortcut implementation.)\\ |
||
348 | |||
349 | \textbf{applications} \texttt{- semi-optional}\\ |
||
350 | |||
351 | This is also a yes/no attribute. If the value is yes, then a copy of the |
||
352 | shortcut is placed in the applications menu (if the target operating |
||
353 | system supports this). This is the same location as the applications |
||
354 | choice for the program group. |
||
355 | \textit{This makes no sense on Unix.}\\ |
||
356 | |||
357 | \textbf{startMenu} \texttt{- semi-optional}\\ |
||
358 | |||
359 | This is a yes/no attribute as well. If the value is yes, then a copy of |
||
360 | the shortcut is placed directly in the top most menu that is available |
||
361 | for placing application shortcuts. |
||
362 | \textit{This is not supported on Unix. see above.}\\ |
||
363 | |||
364 | \textbf{startup} \texttt{- semi-optional}\\ |
||
365 | |||
366 | This is also a yes/no attribute. If the value is yes, then a copy of the |
||
367 | shortcut is placed in a location where all applications get automatically |
||
368 | started at OS launch time, if this is available on the target OS. |
||
369 | \textit{This is also not supported on Unix.}\\ |
||
370 | |||
371 | \subsubsection{Unix specific shortcut attributes } |
||
372 | |||
373 | This extension was programmed by \textsc{Marc Eppelmann}. |
||
374 | This is still in development and may be changed in |
||
375 | one of the next releases of IzPack.\\ |
||
376 | |||
377 | \textbf{type} \texttt{- required}\\ |
||
378 | |||
379 | This must be one of \texttt{Application} or \texttt{Link}\\ |
||
380 | |||
381 | \begin{itemize} |
||
382 | |||
383 | \item Application: To start any application, native, Java or shell-script based, |
||
384 | the \textbf{type} has to be \texttt{Application}. The GUI-System will launch |
||
385 | this Application, so as is, thru their native shell or application launcher. |
||
386 | In this case, note that the right \texttt{workingDirectory} |
||
387 | is always important on Unix platforms. If the users PATH environment |
||
388 | variable does not contain the path, where the application is located, |
||
389 | this can never be run, until the \texttt{workingDirectory} does not contain |
||
390 | these path. The needed current path: ".", this is the case on most |
||
391 | systems, should be in the users PATH environment variable. |
||
392 | Consult the Unix manuals for more details. |
||
393 | |||
394 | \item Link: If you want to open a URL in the users default Webbrowser, |
||
395 | you have to set the \textbf{type} to \texttt{Link}. Note: The \texttt{url} attribute |
||
396 | must be set to work properly. |
||
397 | |||
398 | \item Other: There are more supported types on KDE, like FSDevice, |
||
399 | but these types makes no sense for IzPack, in my opinion. |
||
400 | \end{itemize} |
||
401 | |||
402 | Without the type the Unix shortcut does not work.\\ |
||
403 | |||
404 | \textbf{url} \texttt{- semi-optional}\\ |
||
405 | |||
406 | If you want to create a shortcut as type \textit{Link}, then you have |
||
407 | to set the \texttt{url} attribute. The value can be a locally installed |
||
408 | html or another document, with a known MIME type, like plain text, |
||
409 | or a WWW Url i.e. 'http://www.izforge.com/izpack'.\\ |
||
410 | |||
411 | A local document can be referenced by i.e. "\$INSTALL\_PATH/doc/index.html".\\ |
||
412 | |||
413 | The IzPack variable substitution system is supported by the \textbf{url}.\\ |
||
414 | |||
415 | \textbf{encoding} \texttt{- required}\\ |
||
416 | |||
417 | This should always set to \textbf{UTF-8}.\\ |
||
418 | |||
419 | \textbf{terminal} \texttt{- optional}\\ |
||
420 | |||
421 | If you want, the user can see the console output of a program |
||
422 | (in Java applications "System.outs"), set the \texttt{terminal} attribute to \textbf{true}.\\ |
||
423 | |||
424 | \textbf{KdeSubstUID} \texttt{- unused}\\ |
||
425 | |||
426 | This is not fully implemented by IzPack. |
||
427 | I the future this is the sudo option for a shortcut.\\ |
||
428 | |||
429 | \subsection{Selective Creation of Shortcuts} |
||
430 | |||
431 | Usually all shortcuts that are listed will be created when the user |
||
432 | clicks the 'Next' button. However it is possible to |
||
433 | control to some degree if specific shortcuts should be created or |
||
434 | not. This is based on install conditions. By including one or more |
||
435 | \texttt{<createForPack name=''a pack name'' />} tags in the |
||
436 | specification for a shortcut, you can direct the ShortcutPanel to |
||
437 | create the shortcut only if any of the listed packs are actually |
||
438 | installed. The 'name' attribute is used to define the name of one of |
||
439 | the packs for which the shortcut should be created. You do not need to |
||
440 | list all packs if a shortcut should always be created. In this case |
||
441 | simply omit this tag altogether.\\ |
||
442 | |||
443 | \textbf{A word of caution}\\ |
||
444 | |||
445 | For any shortcut that is always created, I would recommend to omit this |
||
446 | tag, since I have seen a number of problems related to changing pack |
||
447 | names. You can save yourself some troubleshooting and some Aspirin by |
||
448 | not using this feature if it's not required. On the other hand if you |
||
449 | need it I would advise to be very careful about changing pack names.\\ |
||
450 | |||
451 | \subsection{Summary} |
||
452 | |||
453 | \textbf{Native Libraries} |
||
454 | \begin{itemize} |
||
455 | \item ShellLink.dll \texttt{- required by Microsoft Windows} |
||
456 | \item 'Nothing' \texttt{- for KDE/Gnome shortcuts} |
||
457 | \end{itemize}\ |
||
458 | |||
459 | \textbf{Names of the Specification Files}\\ |
||
460 | \texttt{shortcutSpec.xml} for Windows and as default.\\ |
||
461 | \texttt{Unix\_shortcutSpec.xml} for Unix.\\ |
||
462 | |||
463 | \textbf{Specification File Layout - Windows} |
||
464 | \footnotesize |
||
465 | |||
466 | \begin{verbatim} |
||
467 | <shortcuts> |
||
468 | <skipIfNotSupported/> |
||
469 | <programGroup defaultName="MyOrganization\MyApplication" |
||
470 | location="applications||startMenu"/> |
||
471 | <shortcut |
||
472 | name="Start MyApplication" |
||
473 | target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat" |
||
474 | commandLine="" |
||
475 | workingDirectory="$INSTALL_PATH\Path\to\MyApplication" |
||
476 | description="This starts MyApplication" |
||
477 | iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico" |
||
478 | iconIndex="0" |
||
479 | initialState="noShow||normal||maximized||minimized" |
||
480 | programGroup="yes||no" |
||
481 | desktop="yes||no" |
||
482 | applications="yes||no" |
||
483 | startMenu="yes||no" |
||
484 | startup="yes||no"> |
||
485 | |||
486 | <createForPack name="MyApplication Binaries"/> |
||
487 | <createForPack name="MyApplication Batchfiles"/> |
||
488 | </shortcut> |
||
489 | </shortcuts> |
||
490 | \end{verbatim} |
||
491 | \normalsize |
||
492 | |||
493 | \textbf{A sample Specification File for Unix is at the end of this chapter} |
||
494 | |||
495 | \section{Shortcut Tips} |
||
496 | |||
497 | I wrote this section to provide additional information about issues |
||
498 | surrounding the creation of shortcuts. Reading this section is not |
||
499 | necessary to successfully create shortcuts, but it might help you |
||
500 | creating an installation that works more smoothly. In addition, it might |
||
501 | give you some knowledge about operating systems that you don't know so |
||
502 | well. In fact most of the issues described in this section are focused |
||
503 | on differences in operating system specifics.\\ |
||
504 | |||
505 | \subsection{The Desktop} |
||
506 | |||
507 | You should recognize that the desktop is precious real estate for many |
||
508 | people. They like to keep it uncluttered and keep only the things there |
||
509 | that they use on a regular basis. This is not true for everybody and you |
||
510 | might personally think different about this. Still, the fact remains |
||
511 | that a lot of people might have different feelings about it, so you |
||
512 | should not automatically assume that it is ok to place all of your |
||
513 | shortcuts on the desktop proper. While your application is certainly one |
||
514 | of the most important things for you, for your customers it is probably |
||
515 | one of many applications they use and maybe not even the most important |
||
516 | one. Accordingly, placing more shortcut icons there than they feel they |
||
517 | will use on a regular basis and especially doing this without asking for |
||
518 | permission might trigger some bad temper.\\ |
||
519 | |||
520 | Annotation: But even the experienced user should be able to organize their Desktop. |
||
521 | On Linux the users desktop is the only place, which supports any kind of shortcuts.\\ |
||
522 | |||
523 | It is common practice to create a program group in the application menu |
||
524 | system of the OS and place all shortcuts that go with an application in |
||
525 | that program group. In addition, only one shortcut to the key access |
||
526 | point of the application is placed directly on the desktop. Many |
||
527 | installers first ask for permission to do so, as does the ShortcutPanel |
||
528 | in IzPack.\\ |
||
529 | |||
530 | I would like to recommend that you always create a shortcut in the menu |
||
531 | system, even if your application has only one access point and you are |
||
532 | placing this on the desktop. Note that shortcuts can also be placed directly |
||
533 | in the menu, they don't need to be in a program group. There are two |
||
534 | reasons for doing so.\\ |
||
535 | |||
536 | \begin{itemize} |
||
537 | \item If the user elects not to create shortcuts on the desktop, they |
||
538 | will end up with no access point to your application |
||
539 | \item Even if this works fine, occasionally people 'clean up' their |
||
540 | desktop. They might later find that they accidentally deleted the |
||
541 | only access point to your application. For the less technology |
||
542 | savvy users, recreating the shortcut might be a rough experience. |
||
543 | \end{itemize} |
||
544 | |||
545 | \subsection{Icons} |
||
546 | |||
547 | Icons are supplied in image files, usually in some kind of bitmap |
||
548 | format. Unfortunately there is no format that is universally recognized |
||
549 | by all operating systems. If you would like to create shortcuts on a |
||
550 | variety of operating systems that use your own icons, you must supply |
||
551 | each icon in a number of different formats. This chapter discusses icon |
||
552 | file formats used on various operating systems. Fortunately there are |
||
553 | good programs available that allow you to convert between these formats, |
||
554 | so that creating the different files is not much of a problem once the |
||
555 | icons themselves are created.\\ |
||
556 | |||
557 | \textbf{Microsoft Windows}\\ |
||
558 | |||
559 | Windows prefers to use its native icon file format. Files of this type |
||
560 | usually use the extension *.ico. These so called ICO files can hold |
||
561 | multiple icons in one file, which can be useful if the same icon is |
||
562 | to be provided in a number of sizes and color-depths. |
||
563 | |||
564 | Windows itself selects the icon with the most matching dimensions and displays it. |
||
565 | While the Start menu displays the icon with 16x16 pixel if available, the desktop displays |
||
566 | the 32x32 pixel resolution of the same ICO if this is in. |
||
567 | |||
568 | In other words, a ICO file has embedded one or more dimensions of the same Icon. |
||
569 | We recommend to play with \href{http://www.microangelo.us}{microangelo}. |
||
570 | |||
571 | Dlls and Exe files on the other side, can store, amongst other things, a collection of different Icons. |
||
572 | You can select your desired Icon by its index. The lowest index is 0. |
||
573 | Use the iconIndex attribute in the spec file to specify this index.\\ |
||
574 | |||
575 | As a sample look into |
||
576 | \begin{verbatim} |
||
577 | %SystemRoot%\system32\shell32.dll |
||
578 | \end{verbatim} |
||
579 | These contains a lot of Windows own icons. |
||
580 | You can use the \href{http://www.heaventools.com}{PE Explorer} |
||
581 | or another Resource Editor to extract or modify |
||
582 | Icons in dlls or exe files. But be warned. You can also destroy a working |
||
583 | application with these kind of tools. |
||
584 | |||
585 | At least Windows also supports the use of bitmap files in the *.bmp format as |
||
586 | icons. Note that this format does not support multiple icons.\\ |
||
587 | |||
588 | We might have overlooked other file formats that are supported by Windows. |
||
589 | However, we suggest to test other formats for compatibility as they |
||
590 | might not work all the way back to Windows 95 or on the NT/non-NT strain. |
||
591 | Sticking with one of these two formats should keep you out of trouble.\\ |
||
592 | |||
593 | \textbf{Apple}\\ |
||
594 | |||
595 | Apple Macintosh systems use the Macintosh PICT format, extension *.pct. |
||
596 | If you are working with an apple system you know a whole lot more about |
||
597 | this format than I do. If you don't but would like to be able to install |
||
598 | your application on a Mac, simply start with any bitmap format that you |
||
599 | feel comfortable to work with. Then find an application that is capable |
||
600 | of converting this format into a *.pct file. I like to use Paint Shop |
||
601 | Pro (PC based), because it provides conversion capabilities among |
||
602 | several dozen different file formats.\\ |
||
603 | |||
604 | \textbf{UNIX flavors}\\ |
||
605 | |||
606 | by Marc Eppelmann\\ |
||
607 | |||
608 | As my knowledge, all X based Unix Window systems supports |
||
609 | the (ASCII-) XBM (X-Bitmap ) and the better XPM (X-PixMap) format. |
||
610 | The modern GUI systems like KDE and Gnome can display additionally |
||
611 | a lot of other ImageIcon formats, such as GIF, JPG, and PNG.\\ |
||
612 | |||
613 | I suggest to use PNG, because this can lossless compress like the GIF format, |
||
614 | however this format is absolutely free. And not least, this can store true |
||
615 | transparency informations (It has an alpha channel). |
||
616 | |||
617 | \subsection{Targets} |
||
618 | |||
619 | So, you thought you could escape the ugly mess of operating system |
||
620 | dependencies at least with the way how your Java application is started? |
||
621 | Sorry but I have just another bad message. The one positive thing is |
||
622 | that here you have a way of escaping, even if doing so has a few less |
||
623 | pretty side effects. At first, I would like to discuss various launching |
||
624 | options you have available on different operating systems. At the end of |
||
625 | the chapter I write about a way to make launching your application OS |
||
626 | independent.\\ |
||
627 | |||
628 | \textbf{Microsoft Windows}\\ |
||
629 | |||
630 | On Microsoft Windows you have a variety of options for launching your |
||
631 | application. Probably the most simple case is directly starting the Java |
||
632 | VM from the command line and typing out all parameters, such as class |
||
633 | path, the class name etc. In principle, this can be placed right in a |
||
634 | shortcut and should work.\\ |
||
635 | |||
636 | A little more elegant solution is to place this in a batch file and have |
||
637 | the shortcut point to this batch file. This will also make it more |
||
638 | likely that users can repair or recreate shortcuts. Recreating shortcuts |
||
639 | with sophisticated command lines is practically impossible.\\ |
||
640 | |||
641 | Another method is less commonly used but just as possible. Implement a |
||
642 | native executable that launches the VM with your Java application. The |
||
643 | VM comes as DLL and is used by java.exe in just the same way. |
||
644 | As a sample look at the exlipse.exe provided by the \href{http://www.eclipse.org}{Eclipse-IDE}\\ |
||
645 | |||
646 | Clearly, even though the first option is a bit ugly and has some |
||
647 | restrictionss, it is the most portable solution among the three.\\ |
||
648 | |||
649 | \textbf{Apple}\\ |
||
650 | |||
651 | We hope, there is a IzPack developer currently researching |
||
652 | for the details for the Mac environment. We expect |
||
653 | an updated chapter in one of the next releases.\\ |
||
654 | |||
655 | \textbf{UNIX}\\ |
||
656 | |||
657 | UNIX provides essentially the same options as Windows. You can simply |
||
658 | use the command line option, you can write a shell script and you can |
||
659 | write a native launcher. Naturally this stuff is in no way compatible |
||
660 | with the equivalent Windows implementations. The native option is even |
||
661 | more problematic in this environment, since the code can not even be |
||
662 | moved from one UNIX platform to another, without recompilation.\\ |
||
663 | |||
664 | \textbf{OS Independent Launching}\\ |
||
665 | |||
666 | So, after all this rather discouraging news, there is actually a |
||
667 | portable way to launch Java applications? You bet! although I have to |
||
668 | admit that it is not necessarily the most pretty way of doing things.\\ |
||
669 | |||
670 | This approach is currently used by IzPack. Package your application in a |
||
671 | *.jar file if you don't already do so and make it executable by including the |
||
672 | necessary METAINF/MANIFEST.MF information file. I am not |
||
673 | going into all the details on how exactly to do this, the Java |
||
674 | documentation will have to do. You might have noticed that even though |
||
675 | the instructions to install IzPack say to type : |
||
676 | \begin{verbatim} |
||
677 | java -jar IzPack-install.jar |
||
678 | \end{verbatim} |
||
679 | |||
680 | You can just as well double click on IzPack-install.jar and it will |
||
681 | start up. This procedure will work on all GUI based Java supported operating |
||
682 | systems -though you might have to replace double clicking with dropping |
||
683 | the file on the VM. In just the same way, you can make the *.jar file |
||
684 | itself the target of a shortcut. Note: This works only, if jars are registered |
||
685 | as files, which have to launch by the installed JRE (with: javaw.exe -jar *)\\ |
||
686 | |||
687 | The one restriction with this approach is that a *.jar file can only have |
||
688 | one main file. So, if you have multiple targets, they need to be |
||
689 | packaged each into a different *.jar file. They can be in one *.jar file |
||
690 | but then you have to start them explicitly, which gets you back to the |
||
691 | problems that I mentioned before. This brings me to the ugly part. If |
||
692 | you have just one target, then you are all set. If you have multiple |
||
693 | targets, you need to create a *.jar file for each of them. In addition, |
||
694 | you have a much harder time setting the classpath, because each of the |
||
695 | *.jar files that contain supporting code must be listed. In fact, at |
||
696 | present there is no way of setting this during the installation, because |
||
697 | IzPack does not yet (version 3.0) support the setting and modification |
||
698 | of environment variables.\\ |
||
699 | |||
700 | \subsection{Command Line} |
||
701 | |||
702 | Before I start to write a lot about the use of command line arguments |
||
703 | let me state this: If you can avoid using them, do it! Not that there |
||
704 | is anything wrong with command line arguments as such. The issue is |
||
705 | simply that if you want your application to be usable cross platform |
||
706 | (the big Java promise) you should shy away from using command line |
||
707 | arguments. The problem here is that not all operating systems actually |
||
708 | support command line arguments. To be more precise, to my knowledge only |
||
709 | Apple operating systems do not support command line parameters. If you |
||
710 | don't care for running your application on a Mac, then you might not |
||
711 | worry about his at all. If you are interested to support the Mac as |
||
712 | well, read on.\\ |
||
713 | |||
714 | In fact the Mac lower than MacOSX supports command line parameters in a way. |
||
715 | More to the point, it supports a single parameter that your application should |
||
716 | interpret as the name of a data file to open. You have no way of |
||
717 | supplying this to your application through the command line attribute. |
||
718 | The operating system generates this when the user drops the file on your |
||
719 | application and then passes it as command line argument. That's it. This |
||
720 | same behavior will probably fly well on pretty much any system and |
||
721 | should therefore be an ok implementation.\\ |
||
722 | |||
723 | So what to do if you want to modify program behavior based on runtime |
||
724 | switches? For one thing, you could set system properties accordingly. |
||
725 | The disadvantage here is the same as with the command line parameters: the |
||
726 | way of setting these might vary between operating systems. The best way |
||
727 | seems to be using a property file that contains the configuration |
||
728 | data.\\ |
||
729 | |||
730 | \section{Trouble Shooting} |
||
731 | |||
732 | by Elmar |
||
733 | |||
734 | It has been some time since I wrote this chapter during which a good |
||
735 | number of users had a chance to gather experience. Unfortunately I |
||
736 | never know how many have used it successfully without much difficulty. I |
||
737 | only hear from those that have encountered one problem or another. The |
||
738 | type of problems that I have seen prompted me to write this section, |
||
739 | because I think it will help you in locating most problems that you might |
||
740 | encounter or at least give you some idea where the problem might be |
||
741 | located.\\ |
||
742 | |||
743 | \subsection{Problems You Can Solve} |
||
744 | |||
745 | If you see an exception that essentially says that a library can not be |
||
746 | loaded (ShellLink.dll) you have an easy problem to deal with. Your |
||
747 | installer file is probably missing the native tag that adds the Windows |
||
748 | dll to the installer or something with this tag is no quite right. Read |
||
749 | 'What to Add to the Installer' for all details on this topic.\\ |
||
750 | |||
751 | Most other problems cause the ShortcutPanel not to show at all during |
||
752 | the installation process. The reason is simply that the ShortcutPanel |
||
753 | skips if it does not know what to do or if it has nothing to do (no |
||
754 | point showing then and confusing the user). The problem is that this is |
||
755 | not always what you intended. The most simple but not so uncommon |
||
756 | case is, that the ShortcutPanel cannot find their spec file. This can be caused by |
||
757 | a number of reasons. The associated resource tag might be missing in the |
||
758 | installer specification file, the target file name might be misspelled (the |
||
759 | name you specify for the \texttt{id} attribute) or the target file name |
||
760 | has a path or package name pre-pended. You have only to use |
||
761 | \texttt{shortcutSpec.xml} or \texttt{Unix\_shortcutSpec.xml} and nothing else, |
||
762 | just as described in 'What to Add to the Installer'. |
||
763 | You can always verify if this part is ok by |
||
764 | inspecting the content of the installer *.jar file. The file |
||
765 | shortcutSpec.xml should be located in the directory \texttt{res}. This |
||
766 | inspection can be performed with any zip tool. If the file is not there, |
||
767 | first correct this before proceeding.\\ |
||
768 | |||
769 | If the file is there and the panel does not appear, you have a problem |
||
770 | within the specification file. In most cases that I have seen, it comes |
||
771 | down to a spelling mistake of an attribute or tag name. You just have to |
||
772 | carefully make sure that everything is spelled correctly. Don't forget |
||
773 | that all names are case sensitive! In a few cases it is also happend, |
||
774 | that required or semi-optional attributes are omitted, so you might want |
||
775 | to verify if all attributes that you need are actually supplied.\\ |
||
776 | |||
777 | If everything is correct up to this point the problem becomes more |
||
778 | elusive. Most likely the panel will not be displayed, because it is instructed |
||
779 | not to show. There are be several reasons for this. The simple |
||
780 | case is that no location has been specified for the shortcuts in your |
||
781 | installation. This can happen if all five location attributes are |
||
782 | omitted or if all the ones that are listed are set to \texttt{no}. |
||
783 | Remember, you have to specify at least one location for every shortcut. If |
||
784 | this is also correct, you might have used the \texttt{<createForPack>} tag. Review |
||
785 | the details in 'Selective Creation of Shortcuts'. One possibility for |
||
786 | the panel not to show is that based on the packs that are currently |
||
787 | selected for installation no shortcut qualifies for creation. In this |
||
788 | case the panel will not show, this is perfectly normal behavior. More |
||
789 | likely this condition is true because of some accident and not because |
||
790 | it's intended. Make sure the packs that you list for the shortcut are |
||
791 | actually defined in your installation and verify that they are all |
||
792 | spelled correctly. Remember: case matters! Did the ShortcutPanel use to |
||
793 | work in your installation and all of a sudden stopped working? Very |
||
794 | likely you are dealing with the last problem. A package name might have |
||
795 | been modified and the shortcut spec was not adjusted to stay in sync.\\ |
||
796 | |||
797 | \subsection{Problems That Have No Solution (yet)} |
||
798 | |||
799 | Unfortunately one problem has been very persistent and only recently one |
||
800 | user found the reason. The problem occurs when installing on some target |
||
801 | systems where non-English characters are used in the storage path for |
||
802 | the shortcuts. The problem is that these characters don't seem to be |
||
803 | properly translated across the Java Native Interface. This leads to a |
||
804 | situation where the proper path can not be located and the shortcut |
||
805 | creation fails. I write 'some target systems' because it does not fail |
||
806 | everywhere. After much agonizing over this problem, one user found the |
||
807 | solution: The shortcut creation works fine if a Sun virtual machine is |
||
808 | installed, but fails if a version from IBM happens to be installed. So |
||
809 | far I have no solution for this problem but I am trying to find a |
||
810 | workaround the problem.\\ |
||
811 | |||
812 | \subsection{A sample shortcut specification file for Unix} |
||
813 | |||
814 | \footnotesize |
||
815 | \begin{verbatim} |
||
816 | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> |
||
817 | |||
818 | <shortcuts> |
||
819 | |||
820 | <programGroup defaultName="IzForge/IzPack" location="applications"/> |
||
821 | |||
822 | <!-- Disabled since there is no Frontend |
||
823 | shortcut |
||
824 | name="IzPack" |
||
825 | programGroup="yes" |
||
826 | desktop="yes" |
||
827 | applications="no" |
||
828 | startMenu="yes" |
||
829 | startup="no" |
||
830 | target="$INSTALL_PATH/bin/izpack-fe.sh" |
||
831 | commandLine="" |
||
832 | workingDirectory="$INSTALL_PATH/bin" |
||
833 | description="Front-End for IzPack installation tool" |
||
834 | iconFile="$INSTALL_PATH/bin/icons/izpack.png" |
||
835 | iconIndex="0" |
||
836 | type="Application" |
||
837 | encoding="UTF-8" |
||
838 | terminal="true" |
||
839 | KdeSubstUID="false" |
||
840 | initialState="normal"> |
||
841 | <createForPack name="Core"/> |
||
842 | </shortcut --> |
||
843 | |||
844 | <shortcut |
||
845 | name="IzPack Documentation" |
||
846 | programGroup="yes" |
||
847 | desktop="yes" |
||
848 | applications="no" |
||
849 | startMenu="yes" |
||
850 | startup="no" |
||
851 | target="konqueror" |
||
852 | workingDirectory="" |
||
853 | commandLine="" |
||
854 | initialState="noShow" |
||
855 | iconFile="help" |
||
856 | iconIndex="0" |
||
857 | url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html" |
||
858 | type="Link" |
||
859 | encoding="UTF-8" |
||
860 | description="IzPack user documentation (HTML format)"> |
||
861 | |||
862 | <createForPack name="Documentation-HTML"/> |
||
863 | </shortcut> |
||
864 | |||
865 | <shortcut |
||
866 | name="Documentation" |
||
867 | programGroup="yes" |
||
868 | desktop="yes" |
||
869 | applications="no" |
||
870 | startMenu="yes" |
||
871 | startup="no" |
||
872 | target="acroread" |
||
873 | workingDirectory="" |
||
874 | commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
||
875 | initialState="noShow" |
||
876 | iconFile="acroread" |
||
877 | iconIndex="0" |
||
878 | url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
||
879 | type="Application" |
||
880 | encoding="UTF-8" |
||
881 | description="IzPack user documentation (PDF format)"> |
||
882 | |||
883 | <createForPack name="Documentation-PDF"/> |
||
884 | </shortcut> |
||
885 | |||
886 | <shortcut |
||
887 | name="Uninstaller" |
||
888 | programGroup="yes" |
||
889 | desktop="yes" |
||
890 | applications="no" |
||
891 | startMenu="no" |
||
892 | startup="no" |
||
893 | target="/usr/lib/java/bin/java" |
||
894 | commandLine="-jar "$INSTALL_PATH/Uninstaller/uninstaller.jar"" |
||
895 | initialState="noShow" |
||
896 | iconFile="trashcan_full" |
||
897 | iconIndex="0" |
||
898 | workingDirectory="" |
||
899 | type="Application" |
||
900 | encoding="UTF-8" |
||
901 | description="IzPack uninstaller"> |
||
902 | <createForPack name="Core" /> |
||
903 | </shortcut> |
||
904 | |||
905 | </shortcuts> |
||
906 | |||
907 | \end{verbatim} |
||
908 | \normalsize |