Shortcut Tips and Troubleshooting 

by Elmar 

Reading this section is not necessary to successfully create shortcuts, but it might help you creating an installation that works more smoothly. In addition, it might give you some knowledge about operating systems that you don't know so well. In fact most of the issues described in this section are focused on differences in operating system specifics.

The Desktop

You should recognize that the desktop is precious real estate for many people. They like to keep it uncluttered and keep only the things there that they use on a regular basis. This is not true for everybody and you might personally think different about this. Still, the fact remains that a lot of people might have different feelings about it, so you should not automatically assume that it is okay to place all of your shortcuts on the desktop proper. While your application is certainly one of the most important things for you, for your customers it is probably one of many applications they use and maybe not even the most important one. Accordingly, placing more shortcut icons there than they feel they will use on a regular basis, and especially doing this without asking for permission, might trigger some bad temper.

It is common practice to create a program group in the application menu system of the OS and place all shortcuts that go with an application in that program group. In addition, only one shortcut to the key access point of the application is placed directly on the desktop. Many installers first ask for permission to do so, as does the ShortcutPanel in IzPack (see DesktopShortcutCheckboxEnabled variable).

I would like to recommend that you always create a shortcut in the menu system, even if your application has only one access point and you are placing this on the desktop. Note that shortcuts can also be placed directly in the menu, they don't need to be in a program group. There are two reasons for doing so.

• If the user elects not to create shortcuts on the desktop, they will end up with no access point to your application
• Even if this works fine, occasionally people 'clean up' their desktop. They might later find that they accidentally deleted the only access point to your application. For the less-savvy users, recreating the shortcut might be a rough experience.

Icons

Icons are supplied in image files, usually in some kind of bitmap format. Unfortunately, there is no format that is universally recognized by all operating systems. If you would like to create shortcuts on a variety of operating systems that use your own icons, you must supply each icon in a number of different formats. This section discusses icon file formats used on various operating systems. Fortunately, there are good programs available that allow you to convert between these formats, so that creating the different files is not much of a problem once the icons themselves are created.

Microsoft Windows

Windows prefers to use its native icon file format. Files of this type usually use the extension .ico. These so called ICO files can hold multiple icons in one file, which can be useful if the same icon is to be provided in a number of sizes and color-depths.

Windows itself selects the icon with the most matching dimensions and displays it. While the Start menu displays the icon with 16x16 pixel if available, the desktop displays the 32x32 pixel resolution of the same ICO if this exists. In other words, a ICO file has embedded one or more dimensions of the same Icon. We recommend to play with microangelo.

DLL and EXE files can also store, amongst other things, a collection of different Icons. You can select your desired icon by its index. The lowest index is 0. Use the iconIndex attribute in the shortcut spec file to specify this index. As a sample look into:

%SystemRoot%\system32\shell32.dll

This contains a lot of Windows own icons. You can use PE Explorer or another Resource Editor to extract or modify icons in DLL or EXE files.

At least Windows also supports the use of bitmap files in the .bmp format as icons. Note that this format does not support multiple icons.

We might have overlooked other file formats that are supported by Windows. However, we suggest to test other formats for compatibility as they might not work all the way back to Windows 95 or on the NT/non-NT strain. Sticking with one of these two formats should keep you out of trouble.

Apple

Apple's Mac systems use the Macintosh PICT format, extension .pct. If you are working with an Apple system you know a whole lot more about this format than I do. If you don't but would like to be able to install your application on a Mac, simply start with any bitmap format that you feel comfortable to work with. Then find an application that is capable of converting this format into a .pct file. i like to use Paint Shop Pro (PC based), because it provides conversion capabilities among several dozen different file formats. 

UNIX flavors

by Marc Eppelmann

To my knowledge, all X-based Unix Window systems supports the (ASCII-) XBM (X-Bitmap ) and the better XPM (X-PixMap) format. The modern GUI systems like KDE and Gnome can display additionally a lot of other ImageIcon formats, such as GIF, JPG, and PNG.

I suggest to use PNG, because this can lossless compress like the GIF format, however this format is absolutely free. And not least, this can store true transparency information (as it has an alpha channel).

Targets for Java Applications

So, you thought you could escape the ugly mess of operating system dependencies at least with the way your Java application is started? Sorry, but I have just another bad message. The one positive thing is that here you have a way of escaping, even if doing so has a few less pretty side effects. At first, I would like to discuss various launching options you have available on different operating systems. At the end of the section, I write about a way to make launching your application OS-independent.

Microsoft Windows

On Microsoft Windows you have a variety of options for launching your application. Probably the most simple case is directly starting the Java VM from the command line and typing out all parameters, such as class path, the class name etc. In principle, this can be placed right in a shortcut and should work. Even though this option is a bit ugly and has some restrictions, it is the most portable of these solution.

A little more elegant solution is to place this in a batch file and have the shortcut point to this batch file. This will also make it more likely that users can repair or recreate shortcuts. Recreating shortcuts with sophisticated command lines is practically impossible.

Another method is less commonly used but just as possible. Implement a native executable that launches the VM with your Java application. The VM comes as DLL and is used by java.exe in just the same way. As a sample, look at the eclipse.exe provided by the Eclipse IDE.

Apple

UNIX

UNIX provides essentially the same options as Windows. You can simply use the command line option, you can write a shell script and you can write a native launcher. Naturally this stuff is in no way compatible with the equivalent Windows implementations. The native option is even more problematic in this environment, since the code can not even be moved from one UNIX platform to another, without recompilation.

OS-Independent Launching

So, after all this rather discouraging news, there is actually a portable way to launch Java applications? You bet! Although I have to admit that it is not necessarily the most pretty way of doing things.

This approach is currently used by IzPack.  You might have noticed that even though the instructions to install IzPack say to type: 

java -jar IzPack-install.jar

You can just as well double click on IzPack-install.jar and it will start up. This procedure will work on all GUI-based Java-supported operating systems - though you might have to replace double clicking with dropping the file on the VM. In just the same way, you can make the .jar file itself the target of a shortcut. Note: this works only if jars are registered as files, which have to launch by the installed JRE (i.e., with javaw.exe -jar).

 To achieve this functionality, package your application in a .jar file (if you don't already do so) and make it executable by including the necessary META-INF/MANIFEST.MF information file. See the Java documentation for Setting an Application's Entry Point. 

The one restriction with this approach is that a .jar file can only have one main class. So, if you have multiple targets, they need to be packaged each into a different .jar file. They can be in one .jar file but then you have to start them explicitly, which gets you back to the problems that can only be solved by specifying a class name or creating a batch/shell script. This brings me to the ugly part. If you have just one target, then you are all set. If you have multiple targets, you need to create a .jar file for each of them. In addition, you have a much harder time setting the classpath, because each of the .jar files that contain supporting code must be listed. In fact, at present there is no way of setting this during the installation, because IzPack does not yet (version 3.0) support the setting and modification of environment variables.

Command Line

Before I start to write a lot about the use of command line arguments let me state this: if you can avoid using them, do it! Not that there is anything wrong with command line arguments as such. The issue is simply that if you want your application to be usable cross platform (the big Java promise) you should shy away from using command line arguments. The problem here is that not all operating systems actually support command line arguments. To be more precise, to my knowledge only Apple operating systems do not support command line parameters. If you don't care for running your application on a Mac, then you might not worry about his at all. If you are interested to support the Mac as well, read on.

In fact the Mac lower than Mac OS X supports command line parameters in a way. More to the point, it supports a single parameter that your application should interpret as the name of a data file to open. You have no way of supplying this to your application through the command line attribute. The operating system generates this when the user drops the file on your application and then passes it as command line argument. That's it. This same behavior will probably fly well on pretty much any system and should therefore be an okay implementation.

So what to do if you want to modify program behavior based on runtime switches? For one thing, you could set system properties accordingly. The disadvantage here is the same as with the command line parameters: the way of setting these might vary between operating systems. The best way seems to be using a property file that contains the configuration data.

Trouble Shooting

It has been some time since I wrote this page, during which a good number of users had a chance to gather experience. Unfortunately I never know how many have used it successfully without much difficulty. I only hear from those that have encountered one problem or another. The type of problems that I have seen prompted me to write this section, because I think it will help you in locating most problems that you might encounter, or at least give you some idea where the problem might be located.

Problems You Can Solve

If you see an exception that essentially says that a library can not be loaded (e.g. ShellLink.dll) you have an easy problem to deal with. Your installer file is probably missing the native tag that adds the Windows DLL to the installer or something with this tag is not quite right. See the section on ShellLink.dll for details.

Most other problems cause the ShortcutPanel not to show at all during the installation process. The reason is simply that the ShortcutPanel skips if it does not know what to do, or if it has nothing to do (no point showing then and confusing the user). The problem is that this is not always what you intended. The most simple but not so uncommon case is that the ShortcutPanel cannot find its spec file. This can be down to a number of reasons.

• The associated resource tag might be missing in the installer specification file.
• The target file name might be misspelled (the name you specify for the id attribute).
• The target file name has a path or package name pre-pended.

Check the section on shortcutSpec.xml, including details on OS variants and localization. You can always verify if this part is okay in your installer by inspecting the content of the installer .jar file. The file shortcutSpec.xml should be located in the directory res. This inspection can be performed with any zip tool. If the file is not there, first correct this problem in your install.xml before proceeding.

If the file is there and the panel does not appear, you have a problem within the specification file itself. In most cases that I have seen, it comes down to a spelling mistake of an attribute or tag name. You just have to carefully make sure that everything is spelled correctly. Don't forget that all names are case sensitive! In a few cases it has also happened, that required or attributes are omitted, so you might want to verify if all attributes that you need are actually supplied. See the Shortcut Specification guide for details.

If everything is correct up to this point, the problem becomes more elusive. Most likely the panel will not be displayed, because it is instructed not to show. There are be several reasons for this. The simple case is that no location has been specified for the shortcuts in your installation. This can happen if all five location attributes are omitted, or if all the ones that are listed are set to no. Remember, you have to specify at least one location for every shortcut.

If this is also correct, you might have used the <createForPack> tag. One possibility for the panel not to show is that, based on the packs that are currently selected for installation, no shortcut qualifies for creation. In this case the panel will not show - this is perfectly normal behavior. More likely this condition is true because of some accident and not because it's intended. Make sure the packs that you list for the shortcut are actually defined in your installation and verify that they are all spelled correctly. Remember: case matters! Did the ShortcutPanel work previously in your installation and all of a sudden stopped working? Very likely you are dealing with this problem. A pack name might have been modified and the shortcut spec was not adjusted to stay in sync.

Problems That Have No Solution (yet)

Unfortunately, one problem has been very persistent and only recently one user found the reason. The problem occurs when installing on some target systems where non-English characters are used in the storage path for the shortcuts. The problem is that these characters don't seem to be properly translated across the Java Native Interface. This leads to a situation where the proper path can not be located and the shortcut creation fails. i write 'some target systems' because it does not fail everywhere. After much agonizing over this problem, one user found the solution: the shortcut creation works fine if a Sun virtual machine is installed, but fails if a version from IBM happens to be installed. So far there is no solution for this difference in VM implementation.