If you have problems or suggestions, email <support@stairways.com.au>. Please note that I will probably be quite brutal about suggestions for extending this program - in all likelihood, if you want more than this program can provide, you should be using Rez or Resorcerer.
Purpose
The Balloon Help compiler compiles text file descriptions of menu and dialog balloon help in to appropriate resources (namely 'hmnu', 'hdlg', and a 'STR#' resource) for use by the Help Manager in displaying balloons. Since Balloons Help is largely text, it makes sense to have a text file for editing them. And with Metrowerks plugin compiler technology and this compiler, you can add the text file directly to your project and have it built automatically in the make process.
Installation
Drop the ﾒBalloon Helpﾓ file in to the ﾒCompilersﾓ folder in the ﾒCodeWarrior Pluginsﾓ folder. Quit the CodeWarrior IDE if it is running, and then launch it.
In each project, choose Preferences from the Edit menu and select Target. Type ﾒTEXTﾓ in to the File Type field, type ﾒ.bhﾓ (or whatever you like) in to the Extension field, and select Balloon Help from the Compiler popup menu. Click the Add button.
You might like to modify your standard stationery files to include this file mapping information.
Using the Compiler
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.
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. For example:
DIALOG 200 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 Create a new document. Not available because you can only work with one document.
2.1 Open an existing document.
2.2 Open an existing document. Not available because you can only work with one document. Close the current document first.
4.1 Close the front window.
4.2 Close the front window. Not available because there are no windows open or the front window canﾕt be closed.
10.1 Quit this application.
END-MENU
END
That would create three resources. An hdlg resource describing dialog 200, An hmnu resource for menu 129, and a STR# resource (id 26724) containing all the text.
Note: The Help Manager wonﾕt use your dialog help unless you open the DITL in ResEdit and select Balloon Help and tell it to use HMScanhdlg with the same ID as specified in the .bh file.
Formal Specification
･ Lines are limited to 254 characters.
･ White space at the start or end of a line is trimmed
･ Lines starting with one of #;/*{ are comments and are 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. Donﾕt forget to leave a space before the ﾂ character or on the next line, otherwise the words will join together.
･ 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>.
The STR# command
STR# <id> <name>
Specifies the STR# id of the generate STR# resource. At most one per file is allowed. Default is 26724, you are encouraged to use the default unless there is good reason not to. It must come before any other commands.
Dialog Help Text
DIALOG <id> <name>
<items>
END-DIALOG
Menu Help Text
MENU <id> <name>
<items>
END-MENU
Soft End-Of-File
END
Terminates the file, nothing after this point is processed.
Specifying Help Text
<items> is one or more <item> lines.
<item> is either a blank line or <item-spec> <balloon-help-text>
<item-spec> is [<index>.]<balloon-kind>
<index> is the item index (dialog item or menu item - menu item 0 is the menu title). It is optional, and if it is missing, the last index is used (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> is the balloon type as documented in IM6, one of:
･ ﾒ1ﾓ or ﾒenabledﾓ or ﾒhighlightedﾓ
･ ﾒ2ﾓ or ﾒdisabledﾓ or ﾒdimmedﾓ
･ ﾒ3ﾓ or ﾒcheckedﾓ
･ ﾒ4ﾓ or ﾒmarkedﾓ or ﾒmultipartﾓ
<balloon-help-text> is 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.
<id> is a resource ID.
<name> is the resource name.
<whitespace> means any sequence of one or more spaces or tabs.
The order of <items> lines is irrelevant except where the index specifier is omitted.
Duplicate text appears only once in the STR#.
Check out the example project for more information.
Limitations
Requires CodeWarrior 7 or later.
Small Print
This program is Shareware, which means if you use it, you must pay me US$20 using the Register program.
Site Licensing:
World-wide license: US$2000
Universities or companies site license: US$500
Single-user license: US$20.
Use the Register provided to fill out the registration form and send (Email, Snail-Mail or FAX) it to my US distributor, Kagi Shareware.
You may distribute this program any way you wish as long as you don't charge for it (except for reasonable download costs). I donﾕt guarantee any support, but I always answer my Email. If I donﾕt answer Email its because your message didnﾕt get to me, or my reply bounced, so try again and include a valid Internet address if you can.
You MAY NOT DISTRIBUTE this program on any disk costing more than $5 without my explicit permission. You MAY NOT DISTRIBUTE this program on any CD without my explicit permission.
Warranty
This program should do what Iﾕve described in this document. If it doesnﾕt, you can simply stop using it. If you pay me, and within a year find that it doesnﾕt do what I describe here, then you can notify me and I will refund your money and cancel your license.
Fine Print
Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
US Government:
Government End Users: If you are acquiring the Software and fonts on behalf of any unit or agency of the United States Government, the following provisions apply. The Government agrees:
(i) if the Software and fonts are supplied to the Department of Defense (DoD), the Software and fonts are classified as "Commercial Computer Software" and the Government is acquiring only "restricted rights" in the Software, its documentation and fonts as that term is defined in Clause 252.227-7013(c)(1) of the DFARS; and
(ii) if the Software and fonts are supplied to any unit or agency of the United States Government other than DoD, the Government's rights in the Software, its documentation and fonts will be as defined in Clause 52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause 18-52.227-86(d) of the NASA Supplement to the FAR.
Acknowledgements
Thanks go to Metrowerks for making such a fine compiler, for saving Pascal (which I use for most of my programs including this one), for having great tech support, and for opening their environment to plugin compiler writers.
