Help Object Library: 5 HelpControlClass Reference

| Up: GEOS SDK TechDocs | Up | Prev: 4 Creating Help Files

This section will only be useful if you plan on customizing help for your application. Nearly all of what you need for creating normal help files and adding help to your application is described in the previous sections. The following is detailed reference information for HelpControlClass (shown in HelpControlClass ).

Code Display 13-3 HelpControlClass

	@instance HelpType			 HCI_helpType;			/* See HelpType, below */
	@instance MemHandle			HCI_curFile;			/* Internal */
	@instance MemHandle			HCI_historyBuf;			/* Internal */
	@instance word			HCI_nameArrayVM;			/* Internal */
	@instance GeodeHandle			HCI_compressLib;			/* Internal */
	    @default GII_attrs = (@default | GIA_NOT_USER_INITIATABLE);
	    @default GII_visibility = GIV_DIALOG;
	@vardata void				 ATTR_HELP_SUPPRESS_INITIATE;
	@vardata char[]				 ATTR_HELP_INITIAL_HELP;
	@vardata optr				 ATTR_HELP_CUSTOM_POINTER_IMAGE;
	@vardata CompSizeHintArgs 				 HINT_HELP_TEXT_FIXED_SIZE;
	@vardata void				 HINT_HELP_NOT_RESIZABLE;
	@vardata char[]				 ATTR_HELP_INITIAL_HELP_FILE;
typedef ByteEnum  HelpType;
    #define HT_NORMAL_HELP				0
    #define HT_FIRST_AID				1
    #define HT_STATUS_HELP				2
    #define HT_SIMPLE_HELP				3
    #define HT_SYSTEM_HELP				4	/* Reserved for system use */
/* Internal Vardata fields--do not use these. */
	@vardata char[]			TEMP_HELP_ERROR_FILENAME;
	@vardata char[]			TEMP_HELP_TOC_FILENAME;
	@vardata void			TEMP_HELP_DETACH_RECEIVED;

HelpControlClass is a subclass of GenControlClass and, as such, inherits the feature management attributes and messages thereof. For complete information on feature and tool sets, see the Controllers chapter. The HelpControl object has features but no tools. The feature set of HelpControlClass is shown in HelpControl Features .

Code Display 13-4 HelpControl Features

/* These features can be turned on or off with ATTR_GEN_CONTROL_REQUIRE_UI and
 * ATTR_GEN_CONTROL_PROHIBIT_UI. They can be turned on or off dynamically with
 * MSG_GEN_CONTROL_ADD_FEATURE and MSG_GEN_CONTROL_REMOVE_FEATURE. */
typedef WordFlags  HPCFeatures;
    #define HPCF_HELP					0x0100	/* has a "help on help" trigger */
    #define HPCF_TEXT					0x0080	/* has text */
    #define HPCF_CONTENTS					0x0040	/* has "Contents" button */
    #define HPCF_HISTORY					0x0020	/* has "History" button */
    #define HPCF_GO_BACK					0x0010	/* has "Go Back" button */
    #define HPCF_CLOSE					0x0008	/* has "Close" button */
    #define HPCF_INSTRUCTIONS					0x0004	/* has "Instructions" button */
    #define HPCF_FIRST_AID_GO_BACK					0x0002	/* has "Go Back" button for
						 * First Aid */
    #define HPCF_FIRST_AID					0x0001	/* has First Aid configuration */

HelpControlClass , as a GenControl subclass, receives notification when the controlled item changes. For example, a change in help context will cause the HelpControl object to display the new context page. The HelpControl object must be put on the GAGCNLT_NOTIFY_HELP_CONTEXT_CHANGE notification list. When a context change occurs, the help controller will receive MSG_META_NOTIFY_WITH_DATA_BLOCK , with the notification type GWNT_HELP_CONTEXT_CHANGE . This notification type passes a data block containing a NotifyHelpContextChange structure, which is shown below.

Code Display 13-5 Help Notification Structure

/* This data structure is passed in MSG_META_NOTIFY_WITH_DATA_BLOCK to the help
 * controller when a change in the help context occurs. This structure can be
 * generated by calling HelpSendHelpNotification(). This structure uses the
 * following constant and type. */
#define MAX_CONTEXT_NAME_SIZE				22
typedef char		ContextName[MAX_CONTEXT_NAME_SIZE];
typedef struct {
    HelpType			NHCC_type;			/* HelpType involved in change */
    ContextName			NHCC_context;			/* New context to link to */
    FileLongName			NHCC_filename;			/* New file name to link to */
    FileLongName			NHCC_filenameTOC;			/* File name to get TOC from */
}  NotifyHelpContextChange;

HelpControlClass has two exported messages that subclasses may intercept. These are not often intercepted by subclasses. Their reference information is presented below.

MSG_HELP_CONTROL_FOLLOW_LINK

Cause the HelpControl object to follow the specified link in the help file.

Source: Unrestricted; typically internal to the controller.

Destination: The HelpControl object to follow the link.

Parameters: link name 16-bit token of the link name.

link file
16-bit token of the link file.

Return: Nothing.

Interception: Not generally intercepted.

MSG_HELP_CONTROL_GET_POINTER_IMAGE

Return the pointer image to be used when the pointer is over a link in the help text. It looks for ATTR_HELP_CUSTOM_POINTER_IMAGE and returns the pointer stored there; if no custom pointer exists, the default is returned.

Source: Unrestricted; typically internal to the controller.

Destination: The HelpControl object using the custom pointer.

Parameters: not over link Pass FALSE if the pointer is not over a link, TRUE if it is. (Must pass TRUE, not just non-zero).

Return: A word of MouseReturnFlags . If MRF_SET_POINTER_IMAGE is set in this record, the optr of the pointer image will also be returned. Otherwise, the optr will be NullOptr.

Interception: A "viewer" application may subclass this and return its own pointer images if they are dynamic. If static pointer images are used, the application should use ATTR_HELP_CUSTOM_POINTER_IMAGE instead. There is no need to call the superclass with this message .

| Up: GEOS SDK TechDocs | Up | Prev: 4 Creating Help Files