Help System for SWT

SWT Patterns provide Windows-like help system which is very easy to develop and deploy. The following shows an example implementation;

Preparing Patterns Help System

Patterns help system consists of the following files. The files are bundled with your main program binary files. This will make your program deployment simple and easy;

1) The Help Resources Directory

To prepare help system, the first step is to determine a directory in your deploy JAR archive files. For example, the following example assumes "/texts/en/help/" as the directory of deployed help pages. Notice that there are three text files: "helpcontents.html", "helpindex.txt", and "helpsearches.txt". They are the files you are to prepare and bundled into your JAR archive files. Write the files as described in the subsequent sections.

2) Help Pages

Help pages are written in html. It may include most image type files: GIF, PNG, JPEG, etc. CSS files may be used to format your help files. Help files are normally stored at the root of the help resources directory. Image files may be stored in sub directories, as shown in the above figure. Note that the "version.html" file in the figure in fact is a help page!

3) Content Trees

Help pages can be organized into tree-like structure as shown in the following figure. The tree allows you organize your help pages into chapters and sections;

Content tree information is stored in the "helpcontents.txt" file. The following shows an example specification of a content tree;

Content1 :: content1.html
	Content2 :: content2html
	Content3 :: content3.html
		Content4 :: content4.html
Content5 :: content5.html
	Content6 :: content6.html

The followings are coding conventions for the file;

Each line represents a node in the content tree.
Each line contains three information: node level, node label, and help page file path name (in the help resources directory).
Node level is specified with TAB characters. If no TAB characters are specified, it represents a top level node. If one TAB is specified, it means a dependent of the most recent top-level node. Like-wise, if two TAB characters are typed, it means the a dependent of the most recent second-level node, and so on. For example, in the example, "Content1" and "Content5" are top-level nodes. "Content2" and "Content3" are dependents of "Content1". "Content4" is a dependent of "Content3".
Content labels and page path names are separated with "::". When no help pages are available for nodes, page path names may be omitted.

It is important to note that all configuration files are to be prepared using ASCII or UTF-8 encoding!

4) Keyword Indexes

Keyword indexes are a useful resource in locating help pages. The following figure shows an example;

Keyword index information is stored in the "helpindexes.txt" file. The following shows an example specification of a keyword index list;

keyword1 :: content1.html
	subkey1 :: content2html
	subkey2 :: content3.html
keyword2 :: content5.html
	subkey3 :: content6.html

Keyword indexes also use similar coding convention as content trees. The following are conventions;

Each line represents a keyword.
Sub-keywords may be coded with SPACE or TAB prefix characters. Note that TAB characters are equivalent to three SPACE characters
Sub-keyword are specified next to main keywords.
Keywords and page path names are separated with "::".
keyword entries are specified following alphabetical order!

4) Searchable Page Lists

Finally, help provides robust search capabilities. Search keyword expressions can include AND, OR and enclosed expressions.

To make help pages available for searches, include them in the "helpsearches.txt" file. Coding convention is very simple: write a path name in a line! The following shows an example;

content1.html
content2.html
content3.html
content5.html
content6.html

Internationalization and Multi-language Support

Internationalization is essential for applications used globally. Just providing different directories for different languages to help system will change help contents correspond to user's environment.

The labels used the help system per se can be changed with simple API calls. There are three files you can change and provide with your language specific help files;

"helplabels.txt" : This file contains help window label strings. Translate into your local language. Translation guide is available in the original file.
"helpsearch.html" : The help page for the search. Translate into your local language.
"styles.css" : The style file for the "helpsearch.html" file. (You may not need to translate this!)

Place them into your help resources directory. Note that simply placing them into the directory does not warrant to use the files! You need to do one more in your program. Call the following API with the argument substituted with your help directory containing the above files. Note that the path is relative JAR archive path names. It starts with "/" and ends with "/". In addition, the files must be stored in the same directory!

    Help.setHelpLabelFolder("/texts/en/help/");

Bundling Help Pages

All resources related to help system are bundled into your application jar files. From your applications, path information to help files is passed to Help System by simple API calls. The rest is taken care by Patterns Help System. At the start of your application programs, the following two APIs are called. The first is to supply window icons and your JAR files. Note the class argument is used to located your JAR files containing the help resources files. It must be class definition contained in the same JAR file with the help resources. The second argument is the name of your application which may show up in operating systems. The third is the path name of the window icon stored in the same JAR file as the class definition. The second API is to provide the root of your help resources.

   Device.setup(YourApp.class, //  a class of your application
                   "Surf Pattern Analyzer", // your application title
                   "/yourapp/icon.../path/youricon.gif"); // icon path name
   Help.setHelpContentFolder("/texts/en/help/");

Finally, to open a help page, call the following API with appropriate arguments;

   Help.createHelpPage("helppage.html",  // initial page to display;
                          .NONE, // additional button styles;
                          true,  // true to hide the help toolbox;
                          true); // true to allow toolbox hide/show toggle;

Putting it together

To put things together, your programs will contain the following codes;

// import class definitions;
import rosella.swtpatterns.Device;
import rosella.swtpatterns.Help;

   ...

   // to setup help windows icons and pathe information;
   Device.setup(YourApp.class, //  a class of your application
                   "Surf Pattern Analyzer", // your application title
                   "/yourapp/icon.../path/youricon.gif"); // icon path name

   // setup help page folder information;
   Help.setHelpContentFolder("/texts/en/help/");

   // for non-enlish help pages, provide translation;
   Help.setHelpLabelFolder("/texts/en/help/"); // omit for english!

   ...

   // create help page with an initial page;
   Help help = Help.createHelpPage("helppage.html",  // initial page to display;
                          .NONE, // additional button styles;
                          true,  // true to hide the help toolbox;
                          true); // true to allow toolbox hide/show toggle;

   ...

Attaching Icons to Jar Files

Although your self-contained JAR files can be executed directly, they still show coffee cups, not you application icons. You can use JSmooth (or similar programs) to associate an icon for your programs and convert them into executable ".exe" files.

Creating Program Installer

Once your programs are associated with programs icons and transformed into executable ".exe" files, they can be used to create install programs. Install programs can not only install your programs and user manuals but also add to menu systems and desktops. Inno setup or similar programs may be used to prepare install programs.

Congratulation!

Now you have genuine native-look Java desktop programs with own Windows help systems.

License?

If you are interested in licensing help system packages, please Contact Us.