System Resources

This section contains information on resources used by the iTool system.

Icon Bitmaps

Some iTool components have associated icons. Icons for iTool components are displayed in the tree view of a browser window.

Bitmaps used as icons in the iTool system must be either .bmp or .png files. The images contained in icon bitmap files can be either True Color (24-bit color) images or paletted (8-bit color) images.

Note
There are different requirements for bitmap images that will be displayed on button widgets. See About Button Widgets (User Interface Programming) for details.

By default, bitmap files for icons used by the iTool system are stored in the bitmaps subdirectory of the resource subdirectory of the IDL distribution. If an icon's bitmap file is located in this directory, specify the base name of the file — without the filename extension — as the value of the ICON property of the component. For example, to use the file arrow.bmp, located in the resource/bitmaps subdirectory of the IDL distribution, specify the value of the ICON property as follows:

ICON = 'arrow'

If you include the filename extension when setting the ICON property, the iTool system assumes that the specified value is the full path to the bitmap file. For example, to use the file my_icon.png, stored in the directory /home/mydir as an icon, specify the value of the ICON property as follows:

ICON = '/home/mydir/my_icon.png'

If you are distributing your iTool code to others, you may want to specify a path relative to the location of your code for the icon bitmap files. To retrieve the path to the file containing code for a given routine, you could use code similar to the following:

; Use my own Icon bitmap 
iconName = 'my_icon.png' 
routineName = 'myVisualizationType__define' 
routineInfo = ROUTINE_INFO(routineName, /SOURCE) 
path = FILE_DIRNAME(routineInfo.path, /MARK_DIRECTORY) 
iconPath = path + iconName

This code uses the ROUTINE_INFO function to retrieve the path to the file specified by the string routineName. It then extracts the directory that contains the file using the FILE_DIRNAME function, and concatenates the directory name with the name of the bitmap file contained in the string iconName.

Note
The routine specified by routineName must have been compiled for the ROUTINE_INFO function to return the correct value.

Including this code in a routine and setting the ICON property equal to the variable iconPath provides a platform-independent method for locating bitmap files in a directory relative to the directory from which your iTool code was compiled.

If the value of the ICON property is not set and the iTool system needs to display a bitmap to represent a component, the file resource/bitmaps/new.bmp is used.

Help System

The iTool system allows the user to select "Help on Selected Item" from the Help menu (or, in the case of the Operations browser, from the context menu) to display online help for the selected item.

Note
Help for iTool items is provided via a call to the ONLINE_HELP procedure. It is beyond the scope of this chapter to discuss the creation of help files suitable for display by ONLINE_HELP; please see Providing Online Help For Your Application (Application Programming) for additional information.

Creating a Help Directory

Help content designed for use by the iTools help system should be located in a separate directory that is included in IDL's help path (as defined by the !HELP_PATH system variable).

Information about the topic to be displayed by ONLINE_HELP is contained in an XML format file with a name of the form *help.xml. To create the *help.xml file, copy the file <IDL_DIR>/help/template_help.xml into your help directory, rename it to suit your application, and edit it as described in Format of Help Entries.

Note
You must also copy the file <IDL_DIR>/help/itools.xsd into your help directory.

See Example: Help Topic for MyVisType for an example outlining the process of creating a help topic for a user-created iTool component.

Format of Help Entries

The format for a help entry in the *help.xml file is:

<Topic> 
   <Keyword>helpKeyword</Keyword> 
   <Link type="IDLHELP" book="adpFile">fileName</Link> 
   <Link type="MSHTMLHELP" book="chmFile">contextNumber</Link> 
   <Link type="PDF" book="pdfFile"></Link> 
   <Link type="HTML" book="htmlFile">htmlAnchor</Link> 
   <Link type="TEXT">path_to_textFile</Link> 
</Topic>

Where:

The value of the <Keyword> element is the iTool object class name of the selected object. There can be multiple <Keyword> elements for a given <Topic>, but they must all precede any <Link> element. There must be at least one <Link> element for a given <Topic>.

Note
All strings are case sensitive. "Book" is not the same as "book".

The type attribute of the <Link> element defines the type of help viewer to be invoked. The allowed values for the type attribute are:

Table 2-2: Help Topic Link Types
Link type	Meaning
IDLHELP	Use the default IDL online help viewer application.
MSHTMLHELP	Use the Microsoft Windows HTML Help viewer application.
PDF	Use the system default PDF file viewer application.
HTML	Use the system default web browser.
TEXT	Use the IDL XDISPLAYFILE procedure.

The book attribute of the <Link> element defines the location of your iTool's help system. The type of file specified as the value for the book attribute depends on the value of the type attribute:

Table 2-3: Help Topic book Attribute Values
Link type	Value of book attribute
IDLHELP	The `book` attribute should contain the name of your help system's `.adp` file.
MSHTMLHELP	The `book` attribute should contain the name of your help system's `.chm` file.
PDF	The `book` attribute should contain the name of the PDF file to be displayed.
HTML	The `book` attribute should contain the name of an HTML file to be displayed.
TEXT	The `book` attribute can contain the full path to the text file to be displayed. This value will be ignored, however, if the `<Link>` element has a value.

Note
You must either specify the full path to the file as the value of the book attribute, or the file must be located in a directory that is included in IDL's help path.

The value of the <Link> element specifies the specific content to be displayed from the help system specified by the book attribute. The value depends on the value of the type attribute:

Table 2-4: Help Topic Link Values
Link type	Value of the Link Element
IDLHELP	The base name of an HTML file (do not include the file extension) to be displayed in the main window of the IDL Assistant help viewer. The file must be located in the same directory as the help system's `.adp` file. If no value is provided, IDL displays home page specified in the help system's `.adp` file.
MSHTMLHELP	The context number. A context number is an integer used by the Microsoft Windows HTMLHelp viewer to select a topic from the help system's `.chm` file. If no value is provided, IDL displays the help system's home page.
PDF	Ignored. IDL will always display the first page of the file specified by the `book` attribute.
HTML	An HTML anchor tag within the specified HTML file. If no value is provided, IDL displays the top of the HTML page specified by the `book` attribute.
TEXT	The full path to the text file to be displayed. If the value is present, it takes precedence over the value of the `book` attribute (if any).

If more than one <Link> element is present, IDL will first attempt to use the element with the type attribute set to IDLHELP. If no <Link> element with the type attribute set to IDLHELP is present, IDL will choose which to display based on the platform; on Windows platforms, the <Link> element with the type attribute set to MSHTMLHELP will be used, on Unix platforms, the <Link> entity with the type attribute set to PDF will be used. If the appropriate platform-specific <Link> is not present, the first <Link> entity of a type that can be displayed on the current platform will be used.

Example: Help Topic for MyVisType

Suppose you have created a new iTool visualization type named MyVisType and registered it with the iTool, and you have created a single-topic HTML file named MyVisType.html to describe it. In order to display your HTML file when the user selects a MyVisType visualization and selects Help → Help on Selected Item, you would do something like the following:

Install the MyVisType.html file somewhere. Installing the file in the same directory as the MyVisType__define.pro and other associated iTool files would be a reasonable choice, and for the purposes of this example we assume this is the location of the file. In addition, suppose that you create this directory as myvistype at the same level as the itt directory that contains the IDL hierarchy.

Copy the <IDL_DIR>/help/template_help.xml file to the same directory as the MyVisType.html file and rename it. The exact name does not matter, as long as the filename matches the pattern *help.xml. We'll assume the file is named MyVisType_help.xml.

Copy the <IDL_DIR>/help/itools.xsd file to the same directory as the MyVisType.html file.

Edit the MyVisType_help.xml file to contain topic information for your help file. The <Topic> element would look like:

<Topic> 
   <Keyword>MyVisType</Keyword> 
   <Link type="HTML" book="MyVisType.html"></Link> 
</Topic>

Ensure that the directory that includes the MyVisType files is included in IDL's help path. (You may already be adding this directory to IDL's search path.) Since you have created your myvistype directory at the same level as the itt directory, you could use IDL code that looks like this:

idldir=EXPAND_PATH('<IDL_DIR>') 
myVisDir=idldir + PATH_SEP() + '..' + PATH_SEP() + '..' + $ 
   PATH_SEP() + 'myvistype' 
!HELP_PATH = !HELP_PATH + PATH_SEP(/SEARCH) + myVisDir 
 You might include this code block in the myvistype__define.pro file, to ensure that the help path is set correctly when your visualization type is in use.

With this preparation, a user who displayed a visualization of type MyVisType could select the visualization and then select Help → Help on Selected Item to display your MyVisType.html file in the default web browser.

Providing help content using the IDL Assistant help viewer, a PDF file, or any other supported help content format would follow the same procedure, with adjustments for the help file type in the MyVisType_help.xml file.