IPC Message Support

A program can control the !Help! NDA by the use of IPC calls. 

Send IPC calls to ÒSeven Hills~!Help!Ó stopAfterOne.

$8000 =  PerformAnAction
  DataIn:
    dc i2'4'         number of parameters in this block
    dc i2'Action'
    dc i4'Subject'
    dc i4'Topic'
    dc i4'TargetString'
  DataOut:
    dc i2'recvCount'


Action = 1 ÒAre you there?Ó

If the !Help! NDA is present then this call is accepted. No other parameters are
needed.


Action = 2 ÒOpen !Help! NDA with Subject/Topic/TargetStringÓ

This action opens the !Help! NDA, sets the Subject menu to a particular subject,
sets the Topic menu to a particular topic, then scrolls the help text to a
particular location.

Typically this action would be used to provide context-sensitive help in an
application (where the application has provided its own help files and knows the
Subjects, Topics, and text contents of the help.

Action 2 accepts the following parameters:

Subject = Pointer to pString, max 15, for a program/folder name within the
Subject Menu. The string is not case sensitive.

Topic = Pointer to pString, 34 max, for a Topic name within the Topic Menu. The
string is case sensitive. (Note that if the pString parses out to a valid decimal
number, and the number is of a valid item in the Topic menu [range 1 to numitems]
that item will be selected. Normally this feature should not be used.)

TargetString = Pointer to a target string, 128 characters maximum. That string
will be searched for and the text will be scrolled to the first occurrence of
that string. The string is case sensitive. (Note that if the pString parses out
to a valid decimal number, the display will be scrolled to that point in the
text, or to the end, if that is less than the decimal number. Normally this
feature should not be used.)

NOTE: If any of the passed pointers are zero, or are not valid, then the default
settings are used. That is, if you supply a valid Subject it will be selected; a
valid Topic and it will be selected; a valid TargetString and it will be scrolled
to. If you do not provide a valid Subject then !Help! will open as if the user
manually selected !Help! from the Apple menu.


Action = 3 ÒClose !Help! NDAÓ

This action closes the !Help! NDA. No other parameters are needed. Normally you
should not close the !Help! NDA; just let the user close the window when he is
finished working with it.


Action = 4 ÒOpen !Help! NDA with Subject/MenuID/MenuItemÓ

This action opens the !Help! NDA and references a cross-reference data file to
determine which Subject, Topic, and TargetString to display.

Typically this action would be used to provide menu-selection help in an
application. An application can provide a menu item such as ÒMenu Item HelpÓ
that, when chosen, would allow selection of any menu item (including dimmed
items). The selected Menu ID and Item ID can then be used in this action, and
!Help! will open to the appropriate Subject and Topic, and will scroll to the
appropriate point in the help file.

Action 4 accepts the following parameters:

Subject = Pointer to a pString representing the name of the current application.
The string is not case sensitive.  !Help! picks up the name of the current
application and uses it to select the appropriate item on the Subject menu; this
Subject pString should just be a name suitable for display in possible future
versions of the !Help! NDA.

Topic = The ID number of the selected Menu (2 bytes).

TargetString = The ID number of the selected Menu Item (2 bytes).

!Help! looks up the given Menu ID and Item ID in a cross-reference file named
ÒDataÓ in the same folder as the subject application. For example, the Spectrum
application would have a ÒSpectrumÓ folder, and inside that folder would be a
ÒDataÓ cross-reference file.

The ÒDataÓ cross-reference file is constructed as follows:

$menu
$item
Subject
Topic
TargetString
                             <=- AT LEAST ONE EMPTY LINE
...repeat until complete...

NOTES:

- $menu is the Menu ID in hex (the $ is required).
   For example: $0110
- $item is the Menu Item ID in hex (the $ is required).
   For example: $001F
- The Subject/Topic/TargetString items are specified
   as described in Action = 2 above.
- The entries do not use quotes, and must be an exact match,
   with no leading or trailing spaces.