Providing Help Balloons for Items in Dialog and Alert Boxes
For dialog boxes and alert boxes created with a dialog item list
('DITL'), you can provide help balloons for individual items in the
dialog box or alert box by supplying a resource of type 'hdlg' ( dialog
item help). When the user moves the cursor over an item that has a
help balloon associated with it, the Help Manager automatically displays and removes the help balloon as the cursor moves into and out
of the item's rectangle. The Help Manager can display different help balloons for various states of a dialog item-by control value if the
dialog item is a control, and by enabled and disabled states for dialog
items that are not controls.
You can also provide help balloons for other areas of a dialog box or
alert box using the 'hwin' (window help) resource as described in
To create help balloons for items in dialog boxes or alert boxes,
create an 'hdlg' resource that corresponds to a 'DITL' resource. You
associate the help information defined in the 'hdlg' resource in one of
three ways:
• by adding an item of type helpItem to the 'DITL' resource
• by supplying a resource of type 'hwin'
application
The 'hdlg' resource describes the tip, the alternate rectangle, and help
information for dialog items in a dialog box or alert box. The 'DITL'
resource describes the dialog items, and if it includes an item of type
helpItem, it can contain the resource ID of a corresponding 'hdlg'
resource. The Help Manager uses the item rectangles defined in the 'DITL' resource as the hot rectangles for the items. The
Help Manager uses the alternate rectangles specified in the 'hdlg' resource for transposing help balloons' tips when trying to fit the
balloons on screen.
If the dialog or alert box has an item of type helpItem in its 'DITL',
help is enabled, and your application calls the ModalDialog procedure
tracks the cursor and displays help balloons as the user moves the
cursor over items designated in the 'hdlg' resource.
If the cursor passes over any active windows, including dialog or
alert boxes, the Help Manager searches the current resource file for resources of type 'hwin' (see
attempts to match either the title of the window or the windowKind
value in its window record with the title or windowKind value specified
in an 'hwin' resource. The matched 'hwin' resource, in turn, specifies
the resource ID of an 'hdlg' or 'hrct' (rectangle help) resource that
contains the relevant help balloon content.
The 'hrct' resource is also described in
the 'hwin' resource can provide help for various elements across the
entire window as well as for items in a dialog box or an alert box.
If you prefer, you can track and display help balloons for modal dialog
boxes and alert boxes yourself by using a filter function and calling the
to a 'DITL' or adding an 'hwin' requires only that you add resources,
As shown here, the 'hdlg' resource contains header information,
missing items information, and the help information for individual
dialog items.
Dialog item help
Component resource element
Index number of starting dialog item
(first item is number 0)
Options
Balloon definition function
Variation code
Missing items Tip location
Alternate rectangle
Identifier for help balloon content
Balloon content for missing highlighted
controls, or for missing enabled items
that are not controls
Balloon content for missing dimmed
controls, or for missing disabled items
that are not controls
Balloon content for missing active
controls that are checked
Balloon content for missing multipart
controls
First dialog item Tip location
Alternate rectangle
Identifier for help balloon content
Balloon content for a highlighted
control, or for an enabled item that is
not a control
Balloon content for a dimmed control,
or for a disabled item that is not a
control
Balloon content for an active control
item that is checked
Balloon content for a multipart control
Next dialog item (Same as for first dialog item)
.
.
.
The state of a dialog item depends on whether the dialog item is a
control, such as a check box or radio button, or something else, such as
a static text field or an icon.
starting index, options, the balloon definition function, and the
variation code. As in the other help resources, specify the
HelpMgrVersion constant in the first field of the header component of
the 'hdlg' resource.
You can use the starting index field to start the help information with
any dialog item and then continue sequentially. To derive a dialog item
number to start from, the Help Manager adds the index number you specify in this field to the number of the first item in the dialog item
list ('DITL') resource. So index number 0 starts with the item
number 1 in the 'DITL' resource (because 0 plus 1 equals 1). For
example, to describe help information for only the fifth through
s eventh dialog items, specify 4 as the starting index in the header and,
because 4 plus 1 equals 5, provide help content starting with the fifth
and proceeding through the sixth and s eventh dialog items.
In the options field, specify a constant (normally, hmDefaultOptions)
or the sum of several constants' values from this list.
options.)
Specify the balloon definition function and variation code (both
typically 0) in the fourth and fifth fields of the header (see
Following the header, you can specify the help content for dialog items
that are missing from the 'hdlg' resource or that are present but have
no help content defined for a particular state. (The missing items
component is explained in
component, you specify a single tip location and a single alternate
rectangle for all help balloons described in this component.
The tip location is always relative to the item's position in the dialog
window. If you specify the point (0,0) as a default tip, then it is placed
10 pixels from the right and 10 pixels from the bottom of the item's
rectangle (as specified in the 'DITL' resource) for all missing items.
To move the missing item's tip relative to this default location, you can
specify positive or negative integers in place of the coordinates (0,0).
For the missing item's alternate rectangle, you specify offsets from
the dialog items' rectangles if you want alternate rectangles that are