This appendix describes the Balloon Help compiler, a plug-in compiler that converts text file descriptions of menu and dialog balloon help into the appropriate `hmnu', `hdlg', and a `STR#' resource type for use by the Help Manager in displaying help. Since Balloon Help is compopsed largely of text data, it makes sense to use a text file for easy editing. With the Balloon Help compiler, you can add the text file directly to your project and have it built automatically in the make process.

The topics in this appendix include:

• Balloon Help Setup
• Help File Example
• Formal Specification
• Help Text Commands

NOTE

The Balloon Help compiler has been Carbonized to work with the latest Mac OSes.

Balloon Help Setup

The Balloon Help Compiler should be installed with the rest of CodeWarrior and is located in the CodeWarrior Plugins: Compilers folder. If not, it will need to be placed there and CodeWarrior IDE restarted in order to be recognized and used to generate help files.

The Balloon Help Compiler uses its own file extension (.bh) to identify files that should be compiled. By default, any project created using CodeWarrior stationery already has this file extension included. If you have created your own project without stationery, you may need to add the Balloon Help extension to the list of files recognized by the project. To do this:

To add a new File Mapping extension:

a. Open the project to modify in CodeWarrior.

b. Select Edit > targetName Settings.

c. Click File Mapping in the Target Settings Panels list.

d. Click File Mapping in the Target Settings Panels list.

e. Type TEXT into the File Type text box.

f. Type .bh into the Extension text box.

g. Select Compiler > Balloon Help from the pop-up menu.

h. Click Add.

i. Click Save.

The new file extension is added to the File Mappings list.

You might like to modify your standard stationery files to include this file mapping information.

Help File Example

In a project when you want to add balloon help resources for menus or dialogs, add a .bh file in the correct format (as specified below). When you Make the application, CodeWarrior will compile the balloon help file and add the resources. All you have to do is type in the balloon help messages.

The file format is pretty simple. For each dialog or menu you simply list out the items (dialog items or menu items) with the balloon help text. Listing 13.10 shows an example help file.

The resulting file contains three resources. An hdlg resource describing dialog 100, An hmnu resource for menu 129, and a STR# resource (ID 2000) containing all the text strings.

Balloon Help example:

STR# 2000 Change Strings
DIALOG 100 SaveChanges
1.1 Click this to save your changes.
2.1 Click this cancel and continue editing.
3.1 Click this to discard changes - you may lose some of your work!
END-DIALOG

MENU 129 File
0.1 Use this menu to work with documents.
1.1 Create a new document.
1.2 Unavailable because you can only work with one document.

2.1 Open an existing document.
2.2 Unavailable because you can only work with one document. Close the current document first.

4.1 Close the front window.
4.2 Unavailable because there are no windows open or the front window can't be closed.
10.1 Quit this application.
END-MENU

END

Formal Specification

When creating your balloon help text files, beware of the following limitations:

• Lines are limited to 254 characters.
• White space at the start or end of a line is trimmed.
• Lines starting with the following characters: #;/* { are considered comments and ignored completely.
• Line endings are significant, so lines must not be hard wrapped. You can join lines by placing an Option-L (¬) character at the end of the line. Remember to leave a space character before the ¬ character or on the next line, otherwise the words will join together when the line is concatenated.
• Blank lines are significant (comments are not blank lines).
• The file is case-insensitive (although the balloon help text is obviously case sensitive).
• A single space below means <whitespace>.

Help Text Options

Use the following to specify how the help text items are formatted in the text file.

Help text options:

If parameter type is...	It does this...
<item>	a blank line or <item-spec> <balloon-help-text>.
<items>	one or more <item> lines. The order of <items> lines is irrelevant except where the <index> specifier is omitted.
<item-spec>	is [<index>.]<balloon-kind>.
<index>	the item index value for a dialog or menu item. Menu item zero (0) is the menu title. The <index> value is optional, and if missing, the last index value is used. The index value is incremented once for each blank line since the last use, so you can separate dialog or menu items by a blank line and omit the index specifier.
<balloon-kind>	the balloon type as documented in Inside Macintosh: More Macintosh Toolbox: Help Manager, one of: "1" or "enabled" or "highlighted" "2" or "disabled" or "dimmed" "3" or "checked" "4" or "marked" or "multipart" "*" or "any" matches all four item types.
<balloon-help-text>	the text for this <index>.<balloon-kind> pair. You can include the Option-L (¬) character in the string (but not at the end of a line) and it will be converted to a return character.
<strResID>, <menuResID>, <dlogResID>	the resource ID number.
<strResName>, <menuResName>, <dlogResName>	the resource name.

Duplicate text appears only once in the STR#.

Check out the example project Balloon Help in the Mac OS Examples folder for more information.

Help Text Commands

The following commands are recognized by the Balloon Help compiler:

• Dialog commands
• End command
• Menu commands
• STR# command

Dialog commands

DIALOG <dlogResID> <dlogResName>
<items>
END-DIALOG

Use the DIALOG command to define the start of a dialog item help list. Use dlogResID to specify the DLOG resource ID, and dlogResName to specify the DLOG's resource name.

Use the END-DIALOG command to define the end of a dialog item help list.

A DIALOG example:

DIALOG 200 Save Changes

END-DIALOG

NOTE

The Help Manager won't use your dialog help unless you open the DITL in Resorcerer or ResEdit, select Balloon Help, then tell it to use HMScanhdlg with the same ID as specified in the .bh file.

End command

END

Use the END command to execute a soft termination of the help compilation process. Nothing after END appears in the file is processed.

Menu commands

MENU <menuResID> <menuResName>
<items>
END-MENU

Use the MENU command to define the start of a menu item help list. Use menuResID to specify the MENU resource ID, and menuResName to specify the MENU's resource name.

Use the END-MENU command to define the end of a menu item help list.

A MENU example:

MENU 129 File

END-MENU

STR# command

STR# <strResID> <strResName>

Use STR# to specifies the string list resource ID using strResID and the string list resource name in strResName. Only one STR# command is allowed per file. If no STR# resource ID is specified, the default value of 26724 is used. The STR# command must appear before any other command in the help file.

A STR# example:

STR# 2000 Centauri Help Messages