Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp

Chapter 30 - Working With Balloon Help

Recipes--Balloon Help

The recipes and sample code in this section demonstrate how to specify Balloon Help for a view, how to change the help resource for a view while your application is running, and how to specify Balloon Help for a menu.

Recipe--Specifying Balloon Help for a View

To specify Balloon Help for a view, you perform these steps:

1. Add an 'hdlg' resource to your resource definition file.
2. Associate the help resource with any view that uses it.

The sample code shown in this recipe is from the DemoDialogs application.

Adding an 'hdlg' Resource to Your Resource Definition File

A help balloon resource can contain text, a picture, or both. The format for your help messages can be text strings within help resources, text strings within 'STR ' resources, lists of text strings within 'STR#' resources, styled text using 'TEXT' and 'styl' resources, or pictures stored in 'PICT' resources.

The 'hdlg' resource specifies the window contents and the placement of the balloon. The Help Manager uses this information to calculate the size of the help balloon, insert text line breaks, and locate the balloon onscreen.

Note

The "Help Manager" chapter in Inside Macintosh: More Macintosh Toolbox refers to the hot rectangle area for a balloon. MacApp does not use the hot rectangle, so unless you call the Help Manager directly, it doesn't matter what value you assign it.

The following 'hdlg' resource is from the DemoDialogs sample application. This help resource is for the dialog box created when the user chooses "Cursors and Balloons" from the Dialogs menu. The resource has been modified slightly for clarity.

// Balloon Help for views with IDs 'ADN1' and 'ADN2'.
resource 'hdlg' (kAdn1Balloon) 
{
   HelpMgrVersion,
   0,
   hmDefaultOptions,
   0,                   // Balloon definition function.
   5,                   // Variation code.
   HMSkipItem {},       // No missing item help.
   {
      // Text help for view with ID 'ADN1'.
      HMStringItem 
      {
         { -1,0 },      // Tip location.
         { 0,0,0,0 },   // MacApp doesn't use the hot rectangle.
         // Next 4 fields define text for enabled, disabled, checked, and other:
         "Enabled, frame and shadow adornment, plus cursor",
         "Disabled,frame and shadow adornment, plus cursor",
         "Checked" ,
         "Other state" 
      },
      // 'PICT' help for view with ID 'ADN2'.
      HMPictItem 
      {
         { -1,0 },      // Tip location.
         { 0,0,0,0 },   // MacApp doesn't use the hot rectangle.
         1000,          // PICT ID for enabled state.
         1000,          // PICT ID for disabled state.
         1000,          // PICT ID for checked state.
         1000,          // PICT ID for any other state.
      },
   }
};

The resource ID for this 'hdlg' resource is defined as

#define  kAdn1Balloon   128

The variation code in the balloon definition specifies the placement of the balloon. If the specified variation code would cause all or part of the help balloon to be offscreen, the Help Manager will try other variation codes to attempt to make the balloon fully visible.

Notice that there are actually four help strings for the view 'ADN1'--one for each possible state of the view or item. MacApp constants are defined for the four states:

kHMEnabledItem	Indicates the item is enabled.
kHMDisabledItem	Indicates the item is disabled.
kHMCheckedItem	Indicates the item is checked.
kHMOtherItem	Indicates the item is in a state other than enabled, disabled, or checked.

The help resource for the view named 'ADN2' specifies a picture with a 'PICT' resource ID. Again, there are four possible states of the view, but in this case the same picture is used for each state.

Associating the Help Resource With a View

MacApp makes it easy to associate a help resource with a view--you can use a view editor to specify the view's help resource by setting two fields of the view:

fHelpID	Set this to the ID of the help resource. A help resource can be used by multiple views.
fHelpIndex	Set this to the index into the help resource for the view. A resource may contain multiple help definitions.

When your application reads the 'View' resource and creates a view object from it, the fHelpID and fHelpIndex instance variables are assigned the values you specified. (Creating views from resources is described in "Specifying Views With View Resource Templates," beginning on page 217.)

Once you have associated a help resource with a view, MacApp takes care of showing and removing the help balloon at the appropriate time.

Recipe--Changing the Help Resource Associated With
a View

To change the help resource associated with a view, you modify the values of the two variables described in the previous recipe, fHelpID and fHelpIndex.

Suppose you have defined the following constants for a help resource definition and the index of a resource within that definition:

const short kSpecialBalloonHelpID = 129;
const short kMySpecialPurposeHelpIndex = 1;

The TView class provides accessor methods to get the values of fHelpID and fHelpIndex, but not to set them. However, your view objects can set these instance variables directly, as shown in the code fragment below.

To determine the help state of a view before setting its help resource ID and index, you call the TView method GetHelpState. The GetHelpState method returns one of the four constants described on page 642: kHMEnabledItem, kHMDisabledItem, kHMCheckedItem, or kHMOtherItem.

You can change the help resource for a view with code similar to the following, in a method of your view class:

if (this->GetHelpState() == kHMEnabledItem)
{
   this->fHelpID = kSpecialBalloonHelpID;
   this->fHelpIndex = kMySpecialPurposeHelpIndex;
}

Recipe--Using Balloon Help With a Menu

This recipe depends only on the Help Manager, not on MacApp. Similar code can be used in any application.

To use Balloon Help with a menu, you perform these steps:

1. Add an 'hmnu' (Help menu) resource to your resource definition file. The 'hmnu' resource should specify the resource ID of the 'CMNU' or 'MENU' resource it is associated with.
2. Provide a 'STR#' resource containing the help strings that are specified in the 'hmnu' resource.

The following excerpts, from an 'hmnu' resource and a 'STR#' resource, are from the file DemoDialogs.r in the DemoDialogs sample application. Here is the Help menu resource definition for the Dialogs menu:

resource 'hmnu' (mDialogs) 
{
   HelpMgrVersion,
   hmDefaultOptions,
   0, // Balloon definition function.
   0, // Variation code.
   // Missing items.
   HMStringResItem 
   {
      kDialogsMenuHelp,1,
      kDialogsMenuHelp,1,
      kDialogsMenuHelp,1,
      kDialogsMenuHelp,1,
   },
   // Title and items.
   {  
      // Menu title.
      HMStringResItem 
      {
         kDialogsMenuHelp,2,
         kDialogsMenuHelp,2,
         kDialogsMenuHelp,2,
         kDialogsMenuHelp,2,
      },
      // First item in menu: Views by Procedures.
      HMStringResItem 
      {
         kDialogsMenuHelp,3,
         kDialogsMenuHelp,3,
         kDialogsMenuHelp,3,
         kDialogsMenuHelp,3,
      },
      // Second item in menu: Views by Templates.
      HMStringResItem 
      {
         kDialogsMenuHelp,4,
         kDialogsMenuHelp,4,
         kDialogsMenuHelp,4,
         kDialogsMenuHelp,4,
      },
   // Some items not shown.
}

The following is a string list resource definition for the Help menu items:

resource 'STR#' (kDialogsMenuHelp, purgeable)
{ 
   {
      "No help yet for this item",
      "Choose the items in this menu to open various example windows",
      "A window containing a variety of views, created programmatically without
         a 'View' resource.",
      "A window containing a variety of views, created from a 'View' resource.",
      // Some items not shown.
   }
};

The 'hmnu' resource above specifies a menu ID of mDialogs--the Dialog menu in the DemoDialogs sample program. "Views by Procedures" is the first item in that menu. The following line from the 'hmnu' resource specifies that the help for the "Views by Procedures" item should be retrieved from a string list resource ('STR#'):

HMStringResItem

The next four lines specify the string resource and the indexes of the strings in that resource to use when the menu item is enabled, disabled, checked, and in any other state. In this sample, the same string is used in each case:

kDialogsMenuHelp,3,

For example, if Balloon Help is turned on and a user drags the cursor over the "Views by Procedures" menu choice, the Help Manager will determine that the help to show in the balloon is string number 3 from the 'STR#' resource with ID kDialogsMenuHelp. The user sees a balloon with the string "A window containing a variety of views, created programmatically without a 'View' resource."