FCMenu and Help Files
FL

A menu or Help file is a text file that can be created or edited as you edit any other text file.  However, the first line of the file must contain a specific 4-character label to tell the LOAD command what kind of file it is:

	;MN; indicates a menu file

	;HL; indicates a Help file

You can include formatting commands on the second line of the file (such as Left Margin, Right Margin, Tabs, or Indents) to control the way text is arranged when displayed on the screen.

After the formatting commands, menu or Help files may have several comment lines.  You can add as many comment lines as you want to describe such things as the contents of the file or any changes you've made to the file.  (Refer to "Including Comments in a Menu or Help File" for a way to enter your notes.)

Following any comment lines, menu or Help files consist of sections or frames that Signature uses to construct and operate each menu or Help screen.


FCMenu and Help File Frames
FL
Each frame in a menu or Help file designates the information Signature displays on a screen at a time.  Menu frames may contain commands or programs the user can initiate from the screen.

In general, menu screens enable the user to perform some task.  There are several different frame types you can use depending on the way you want the menu screen to function.  SIG.MNU contains the following frame types:

	0 displays a menu bar
	L displays a pull-down or side menu
	K displays a dialog box
	5 executes a routine
	M indicates a comment

Types 0, L, and K display information on the screen; Types 5 and M are invisible to the user.  SIG.MNU also contains Types C and 6 frame types, which are specially dedicated to perform specific tasks and are not applicable to general uses.

In general, Help screens provide information to the user.  SIG.HLP contains the following frame types:

	C displays a scrollable Help screen
	9 provides access to detailed error messages

(SIG.HLP also includes some "routine only" Type 5 frames, which initialize some variables before moving to a Help frame.)

Although menu and Help frames have different uses, they have the same basic construction.  Every frame starts with a label enclosed in a pair of double curly braces {{ }}.  A frame begins at the label and ends at the next label (which signals the beginning of the next frame).

Following the label, frames may have one or more displayable lines.  Displayable lines contain text that appears when the user accesses the Help or menu screen.

Following the label or any displayable lines, frames may have one or more executable lines.  Executable lines are not displayed on the screen.  They contain commands or programs and their content depends on the function you want the frame to perform.

The various types of frames are described throughout this section based on their functions (such as displaying a menu bar and displaying a scrollable Help screen).

Although frames are not listed in any particular order within a menu or Help file, Signature can quickly find the topic on which the user requested information.  Refer to "Loading Menu and Help Files" for more information on what happens to a menu or Help file when it is loaded into memory.

Keyword Labels
------- ------
The keyword label identifies the frame to Signature and allows you to link the various types of menu and Help frames.  Frame labels have the following format:

	{{#,keyword1,keyword2,...}}

# indicates the frame type.  You enter the letter (K, L, M, or C) or the number (0, 5, 6, or 9) that corresponds to the frame type you want to use.  Frame types and their functions are described in sections throughout this document.

MD+ITkeywordMDNM is the name by which the frame can be accessed.  Appendix D lists keywords reserved for use by Signature.

Keywords
--------
One or more keywords in the label indicate the way(s) the frame can be accessed.  In general, there is no limit to the length of a keyword; however, shorter keywords take up less memory.

For example, the following label with the keyword MD+ITFileOpenMDNM designates the beginning of a Type K frame:

	{{K,FileOpen}}

Although shorter keywords are preferable, a keyword can contain two or more words separated by a single space.

If you include several keywords (separated by commas) in a label, the frame can be accessed by different names.  For example, the following Type 5 label provides access to the frame in two ways:

	{{5,Cut,Sh Del}}

Keywords can be either upper or lowercase letters (or any mix); they are not case sensitive.

Keywords also link frames together, which enables the user to move directly from one task or topic to another.  Refer to "Linking Frames" for more information.

Indicating the Entry Point to the Menus !N is a special keyword you use to indicate the frame you want displayed when the user presses F10 to activate the menus.

In SIG.MNU, the entry point is the Type O (zero) frame that produces the menu bar.  The keyword label for the menu bar is:

	{{0,!n}}

In SIG.HLP, the entry point is a Type 5 frame that tests whether the user .  requesting Help for menus or for the command line.  They keyword label for the Type 5 frame is:

	{{5,!n}}


FCLinking Frames
FL
Three things you will find useful to link frames in a file are the JD (Jump to Dialog Box) command, the JM (Jump to Menu) function call, and the JH (Jump to Help) function call.

JD (Jump to Dialog Box) Command
--  ---- -- ------ ---  -------
JD jumps to the frame with the specified keyword and has the following form:

	JDkeyword

MD+ITkeywordMDNM is the keyword of the frame you want execution to jump to.

All execution in the menu takes place by passing from one menu frame to another.  The menu bar is the entry point to the menus.  When the user selects an item from the menu bar, a pull-down menu (Type L frame) appears.  The JD (Jump to Dialog Box) command links the Type L frame to the Type 0 frame.

For example, the following line in a Type 0 menu frame causes execution to move to the menu frame with the keyword MD+ITMBFileMDNM when the user selects "File" from the menu bar:

	&File<<JDMBFile>>,

In the Menu file, you can also use JD to link a Type L to another Type L or a Type 5.  In the Help file, you can use JD to link Type C frames.

For example, the following line in a Type L menu frame causes execution to move to the menu frame with the keyword MD+ITNewMDNM when the user selects "New" from the pull-down menu:

	&New...<<JDNew>>,Create a new file

JM (Jump to Menu) Function Call
--  ---- -- ----  -------- ----
The JM function call jumps to the menu frame with the specified keyword and is used to control the program flow from one dialog box to the next.

JM has the form:

	(keyword)

MD+ITkeywordMDNM is the keyword of the frame where you want execution to continue.  (Parentheses are required around the keyword.)

For example, the following Type 5 frame clears macros 1001 and 1002 and then jumps to another menu frame with the keyword NewA:

	{{5,New}}
	<<SV1001,>><<SV1002,>>(NewA)

JM is also useful in SPL programs to create subroutines.  Refer to the discussion of Executable Lines in "Creating a Dialog Box" for more information.

JH (Jump to Help) Function Call
--  ---- -- ----  -------- ----
You use the JH function call in the Menu file to display the frame that resides in the Help file with the specified keyword.

JH has the form:

	E(keyword)

keyword is the keyword of the Help frame.  (Parentheses are required around the keyword.)

For example, the following Type 5 frame jumps to a Type C Help frame with the keyword GenHlp that resides in the currently loaded Help file:

	{{5,GHelp}}
	E(GenHlp)


FCIncluding Comments in a Menu or Help File
FL
You can use a Type M frame to describe such things as the contents of the file, the contents of a frame, or any changes you've made to the file.  You can enter as many lines as you want, since Type M frames are not loaded into memory.  Type M frames are also useful when you are testing a menu file, because you can disable one or more frames by changing them to Type M frames.

Keyword Label
------- -----
The first line of a Type M frame contains the keyword label (M enclosed in a pair of double curly braces {{ }}).  Unlike other frame types, a Type M frame label does not require a keyword.  However, in SIG.MNU all comment frames have the keyword MD+ITCommentMDNM for legibility.

For example, the following is one of the comment lines in SIG.MNU:

	{{M,comment})
	############### GLOBAL SUBROUTINES ###############

You can find other examples in SIG.MNU, where comment frames are used to annotate the functions of various frames.


FCDisplaying A Menu Bar
FL
You use a Type 0 (zero) frame to display a menu bar that lists the categories of the various available options.  When the user presses F10, Signature constructs the menu from the information in the Type 0 frame and displays the menu horizontally across the top of the screen.

Keyword Label
------- -----
The first line of a Type 0 frame contains the label (0, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}.

Since the Type 0 frame in SIG.MNU is the entry point to the Menu facility, it has the special keyword !N.

Displayable Lines
----------- -----
After the keyword label, each subsequent line of a Type 0 frame contains the number of extra spaces you want between the menu names on the menu bar, the menu name you want displayed in the menu bar, a JD (Jump to Dialog Box) command to link the execution of the menu item to another screen type, and a comma.  You can add a string of text you want Signature to display on the status line when the user highlights the keyword in the menu.

Length of Menu Names
------ -- ---- -----
The menu bar must fit on a single line, across the width of the screen.  Therefore, when choosing your menu names and spacing, make sure the total number of characters and spaces does not exceed 80.

Signature enters menu names in the menu bar in the same order they appear in the Type 0 frame.

For example, the following frame in SIG.MNU creates the menu bar.  The label indicates a Type 0 frame that is the entry point to the menus (!N).

	{{0,!n}}
	&File <<JDMBFile>>,
	&Edit <<JDMBEdit>>,
	&View <<JDMBView>>,
	For&mat <<JDMBFormat>>,
	&Proof <<JDMBProof>>,
	&Options <<JDMBOptions>>,
	&Advanced <<JDMBAdvanced>>,
	&Window <<JDMBWindow>>,
	&Help <<JDMBHelp>>,

When the user chooses an item in the menu bar, execution moves to the menu frame indicated by the JD command.

The ampersands in the keywords indicate the accelerator keys; they do not appear on the menu bar.  Refer to "Using Accelerator Characters in Menu Screens" for more information.


FCCreating a Pull-Down Menu
FL
You use a Type L frame to display a pull-down menu that lists the various options available for a particular menu bar item.  When the user places the cursor on an item in the menu bar, Signature displays the pull-down menu directly below it.  Signature constructs the pull-down menu from the information in the Type L frame.

Keyword Label
------- -----
The first line of a Type L frame contains the keyword label (L, followed by one or more keywords) enclosed in a pair of double curly braces {{}}.  The keyword must correspond to a menu name in the Type 0 frame associated with the pull-down menu.

Displayable Lines
----------- -----
After the keyword label, each subsequent line of a Type L frame contains a display symbol, the text and spacing you want displayed in the menu, a JD (Jump to Dialog Box) command to link the execution of the menu item to another screen type, a comma, and the descriptive text you want displayed on the status line whenever the user highlights the keyword on the menu.

Length of Displayable Lines
------ -- ----------- -----
A displayable line is limited to 32 characters up to the comma in the syntax.  For each keyword this includes any accelerator keys, the MD+BO<<JDkeyword>>MDNM command, and spaces.  Any descriptive text to be displayed on the status line when the user highlights the keyword is not included in the 32-character limitation.

A pull-down menu can be as long as you want to make it; however, Signature displays only the first 22 or 24 lines, depending on the placement of screen elements, such as ruler, menu bar, command line, etc.  The user can scroll down to view any additional items.

Signature enters keywords in the pull-down menu in the same order they appear in the Type L frame.

Display Symbols
------- -------
You can use one or more of the following symbols in a Type L menu frame to control the display of the menu screen:

	&	indicates the accelerator key (refer to "Using Accelerator Characters in Menu Screens" for more information).

		(Signature character 240) dims the menu item if the current window is empty, contains a read-only directory, or a read-only file or a form.  (The item is not dimmed if a read/write file is displayed.)

		(Signature character 238) dims the menu item if the current window is empty (not used for a directory or a file).  To enter character , press Ctrl-Alt 238.

		(Signature character 176) dims the menu item under all conditions.

		(Signature character 251) adds a > to the item in the displayed pull-down menu if the indicated condition is true.  To enter character , press Ctrl-Alt 251.

In Type L menu frames, you can have Signature test existing conditions and adjust the information it displays in the pull-down menu depending on the outcome of the tests.  You precede the displayable text with a series of statements, each separated by a vertical bar ( | ).  For example:

	statement1|statement2|statement3...,description

Signature reads lines in Type L frames from left to right and evaluates any conditions it encounters.  If the condition is true, Signature executes the next statement; if the condition is false, Signature skips to the next statement.

For example, the following Type L frame from SIG.MNU is displayed when the user selects "Spell" from the Proof pull-down menu.

	{{L,CCSpell}}
	&Personal Dict...<<JDLdDict>>,Load or edit personal dictionaries
	|&Main Dict...<<JDMainDictAA>>,Use a main dictionary
	|---------------------
	<<VA$AC>>==1||&Auto-CheckAltF7<<JDAutoCheck>>,Spell-check words as you type...
	&Batch Spell...<<JDBatSpChk>>,Spell-check a series of files

If the user selects "Personal Dict," execution moves to the menu frame with the keyword MD+ITLdDictMDNM.  If the current window is empty, contains a read-only directory, read-only file or a form, Signature dims "Main Dict" in the pull-down menu.

The long horizontal line separates "Personal Dict" and "Main Dict" from "Auto Check" and "Batch Spell" and the | ensures that it cannot be selected.  If Auto-Check is on, Signature displays a > next to "Auto-Check." If the user selects "Batch Spell," execution moves to the menu frame with the keyword MD+ITBatSpChkMDNM.

When the user places the cursor on an item in the pull-down menu, Signature displays on the status line the descriptive text you associated with that item's keyword in the menu file. "Personal Dict," "Main Dict," "Auto-Check," and "Batch Spell" can be accessed by pressing accelerator keys P, M, A, or B, respectively.

Cascading Menus
--------- -----
You can create a pull-down menu that "cascades" from another pulldown menu.  To do this, precede the JD command with a Signature character 16 ().  For example, the following displayable line in a Type L menu frame enables the cascading menu in the previous example to work:

	|&Hyphenation<<JDCCHyphn>>,Control hyphenation

When the user selects "Hyphenation" from the Proof menu, Signature displays another Type L menu screen with the keyword MD+ITCCHyphnMDNM.


FCCreating a Dialog Box
FL
You use a Type K frame in a menu file to create a general-purpose dialog box.  The resulting dialog box emulates a Microsoft Windows dialog box with features such as radio buttons, check boxes, scrollable lists and directories, horizontally scrollable fields, etc.

For example, the following Type K frame appears in SIG.MNU and has many of the features described throughout this document:

{{K,OpenB}}					Keyword Label

   1   1   12  2   56 17    (OpenB-X)			Dialog Box
Specifications
   tx  100 2   0   38 1     <<VA@1010>>
   tb* 101 3   +2  25 1     <<VA@1001>>|<3,4>
   tx  105 2   +2  14 1     F&iles
   lf  5   2   +2  14 8
   tx  106 +17 4   15 1     &Directories
   Id  6   +   +2  14 8
   tx  102 3   +9  18 1     Current Path:
   tc  98  +20 +   20 1     <<VA$P\>>
   tx  107 3   +1  20 1     Format:			Displayable Lines
   tc  108 +20 +   20 1     <<VA@1201>>
   dp  1   <18 1   14 1     OK
   pb  3   +   +2  +  1     &Find...
   pb  4   +   +2  +  1     &Options...
   pb  2   +   +2  +  1     Cancel
   pb  62  +   +2  +  1     Help
   cb  104 -1  +3  12 1     &Read Only			<<VA@1004>=="R"
Executable Lines
---------- -----
<<LB-OK>><<SU1005,OpenB>><<SX1001,@UPR("%101")>><<SV1004,%104>>EXIST <<PV1001>><<IF(<<ER>>)>><<SX40,"""<<VA@1001>>"" not found,">><<SX45,35>>(CenterMess)<<SX1199,<<IS40>>>>(FileNotFound)<<EX>>
<<EI>>(OpenC)<<EX>>
<<LB-Cancel>><<EX>>
<<LB-Find>><<SX1001,@UPR("%101")>><<SV1004,%104>><<SV1805,OpenB>>(OpenFind)<<EX>>
<<LB-Options>><<SX1001,@UPR("%101")>><<SV1805,OpenB>>(OpOpt)<<EX>>
<<SV40,%101>><<SV42,OPEN>><<GT1802>><<EX>>
(dir/pa/na/up)<<EX>>

Type K menu frames consist of four basic parts:  the keyword label, dialog box specifications, displayable lines, and executable lines.

The MD+ITkeyword labelMDNM is similar to those used for other type menu frames.

The line following the keyword label contains MD+ITdialog box specificationsMDNM for the size and placement of the dialog box as well as any text you want displayed as a title.

MD+ITDisplayable linesMDNM indicate the various items you want to appear in the dialog box and their size and placement.  For example, you can include fixed text, a field for entering text, radio buttons, check boxes, pushbuttons, and scrollable lists.  Displayable lines also can:

 indicate the tab order, that is, the order in which the user moves through the items in the dialog box

 indicate how the items appear when the dialog box is displayed

 have Signature dim an item under certain conditions

 have Signature verify that the information entered is valid for the function being performed

 indicate shortcuts, called accelerator characters, so the user can move directly to an item by pressing a key

 assign values and conditions that affect other items in the dialog box

MD+ITExecutable linesMDNM all begin with either a Signature character 2 (0) or a Signature character 1 () to indicate the start of an SPL (Signature Programming Language) program.  They are associated with items in the dialog box and perform the task indicated.  You can pass information the user enters into various dialog box items to executable lines.

The memory requirements for the executable lines of a Type K menu frame are limited to approximately 3K-10K, depending on the amount of memory used by the currently loaded set of macros.

You can test dialog boxes quickly while you are creating or editing them without saving and reloading the menu.  To do this, position the cursor in the frame you want to test and press Ctrl-Alt-Shift Q.  Signature immediately displays the associated screen.

For more information refer to "Testing Dialog Boxes and Help Frames."

The user presses Tab to move through any dialog box from item to item (or Shift-Tab to move backward from item to item).  Cursor keys only move the cursor within fields.  When the last (or first) item is reached, the cursor moves through the list again.  Alternatively, the user can press an accelerator key to move directly to a specific field.

When the user puts the cursor on an item in a dialog box and presses F1, Signature displays the information for the specific item.  Refer to "Providing Context-Sensitive Help Screens" for more information.

Keyword Label
------- -----
The first line of a Type K menu frame contains the keyword label (K, followed by one or more keywords) enclosed in a pair of double curly braces {{}}.  In general, there is no limit to the length of a keyword; however, shorter keywords take up less memory.

Illegal Characters
------- ----------
You cannot use Signature characters 174 (AE) or 175 (AF) in keywords; they cannot be accessed with the JM (Jump to Menu) function call.

If you plan to provide on-line help for a dialog box, the keyword for the dialog box cannot end with a number (for example, OPEN2).

Dialog Box Specifications
------ --- --------------
Dialog box specifications determine the size of the dialog box, its placement on the screen, and the title that you want to appear in its top border.

Dialog box specifications appear on the second line of a Type K frame in the following form:

	scale placement size title

MD+ITscaleMDNM values indicate the factors by which you want Signature to scale the numbers you enter to indicate horizontal and vertical units.  By specifying values of 1 and 1 for the scale argument, you can enter values for x and y coordinates in one character units and one line units, respectively.  Microsoft Windows requires 4 horizontal units and 10 vertical units per character.  Therefore, if you import dialog boxes from Microsoft Windows, specify values of 4 and 10 for the scale argument.

MD+ITplacementMDNM values are x and y coordinates to indicate the location of the upper left corner of the dialog box from the left and top edges of the screen.

MD+ITsizeMDNM values are x and y coordinates to indicate the width and height of the dialog box.

MD+ITtitleMDNM indicates the title you want to appear in the upper left corner of the dialog box border.

For example, in the following dialog box the scale values are 1 and 1, placement values are 12 and 2, size values are 56 and 17, and the title is Open:

	1  1  12  2  56  17  Open

The specifications in the above example produce a dialog box 56 characters wide and 17 lines high.  Its upper left corner is located 12 characters from the left edge of the screen and 2 lines down from the top edge.

Use the Tab Settings Command
--- --- --- -------- -------
Since you must use tabs to separate the various values in the dialog box specifications and in the displayable lines, use the TS (Tab Settings) command to make the columns readable.  You can enter the TS command immediately before the Type K keyword label.

Displayable Lines
----------- -----
The third and subsequent lines of the Type K frame determine the various items you want to appear in the dialog box and their placement and have the form:

	control ID location size text option

MD+ITcontrolMDNM indicates one of the control codes that determines the type of dialog box item.  The available codes are:
	TX Text (fixed)
	TC Text changing (updated by Signature; not editable by user)
	TB Text box (editable)
	RB Radio button
	CB Check box
	PB Pushbutton
	DP Default pushbutton
	LF List files
	LD List directories and drives
	LB List box
	GB Group box
(Each of these controls is described in a separate section below.)

A Type K menu frame can have up to 32 controls, including the dialog box itself.  Signature counts the dialog box specification as one control and a MD+ITgroupMDNM of radio buttons as one control.  Signature does not count TX (Fixed text) or GB (Group box) controls.

To indicate where you want the cursor located when Signature first displays the dialog box, put an asterisk immediately after one control code; for example MD+BOtb*MDNM.

Any line that begins with a semicolon is a comment - it has no effect on dialog box items.

You use a different line for each control you want to include in the dialog box.  The order in which the controls appear in the frame determines the tab order or the order in which the user can move the cursor from item to item, by pressing Tab, when the dialog box is displayed.  If you want to rearrange the tab order, you simply rearrange the lines in the menu frame.

MD+ITIDMDNM indicates the number you assign to each control code.  Each number must be unique within the menu frame; however, the numbers can be in any sequence.  You can correspond these numbers directly to programs Signature runs when the user selects a pushbutton. (See "Executable Lines," below.)  Since you normally would not correspond fixed text to a program, it is not necessary to assign ID numbers to TX controls.

Reserved ID Numbers
-------- -- -------
Signature reserves certain ID numbers for special features.  Refer to Appendix D for more information.

MD+ITlocationMDNM values are x and y coordinates to indicate the location of the item in relation to the upper left corner of the dialog box.  You can use either a plus sign (+) or a minus sign (-) to specify relative locations.  See "Positioning Items in a Dialog Box" for more information.

MD+ITsizeMDNM contains x and y coordinates to indicate the width and height of the item (text, text box, pushbutton, check box, list box, etc.).  To save time, you can reuse the value above it by including a plus sign (+) for the width and/or height.

MD+ITtextMDNM specifies the text or the initial value displayed next to (or within) the item in the dialog box.  You can use the VA (Value of Variable) command when you want to include the current value of a Signature variable in the text.  For example, when the dialog box is displayed, Signature includes the name of the current drive and path in the text after the word, "Current path."

	tx  102  +  +20  100  12  Current path:<<VA$pa>>

You can also use the text argument to have Signature verify that the information entered in a text box (TB) is valid for the function being performed.  Refer to "Validating Text Entry" for more information.

MD+IToptionMDNM has many uses:  you can select a radio button or a check box automatically when the dialog box is displayed; dim an item in the dialog box; and include conditional statements to perform these tasks.  Indicating default check boxes and radio buttons are described in their respective sections.  Refer to "Dimming or Checking Dialog Box Items" for more information.

Positioning Items in a Dialog Box
----------- ----- -- - ------ ---
You position items in a dialog box by specifying their coordinates.  You specify horizontal coordinates in characters (up to 80 across) and vertical coordinates in lines (up to 22 down).

You specify MD+ITlocationMDNM coordinates in relation to the upper left corner of the dialog box.  (Prefacing a location coordinate with a < character indicates that you want to place the item in relation to the MD+ITrightMDNM border of the dialog box.)

Radio Button Positions
----- ------ ---------
Signature positions radio buttons one line apart, regardless of what you specify as a vertical coordinate.  You cannot position radio buttons side by side.

To use absolute locations, type the exact coordinates where you want the items placed.  For example, the following line positions a block of fixed text (ID number 100) 2 characters in from the left border of the dialog box and 1 line down from the top border.  The text, "Example 1," is one line of up to 20 characters long.

	tx  100  2  1  20  1  Example 1

To use relative locations, type the coordinate as you want the item to appear in relation to the preceding coordinate, using either a plus sign (+) or a minus sign (-).

For example, the first control line functions as described above; the second control line positions a text box (ID number 101) 3 characters in from the left border of the dialog box and 3 lines down from the top border.  The text box is one line, 22 characters long and is initially displayed containing the name of the current file.

	tx  100  2  1   20  1  Example 1
	tb  101 +1  +2  22  1  <<VA$fi>>

Use Relative Locations
--- -------- ---------
It is much easier to redesign a dialog box with relative locations, because you need only change one number to move a column of items.

Item's Position May Change
------ -------- --- ------
The position of the item will change if you use relative positions and you rearrange the lines in the menu frame to change the tab order.

In order to have items line up vertically, specify either +O or + as the horizontal coordinate.  For example, the following control lines vertically align two radio buttons under a block of fixed text that is 12 characters in from the left border and 2 lines down from the top:

	tx  102  12  2   20  1  Example2
	rb  103  +   +1  10  1  ODD
	rb  104  +   +1  +   1  EVEN

Notice that the second radio button (ID number 104) is also 10 characters wide as specified by the + in the width MD+ITsizeMDNM coordinate.

As another example, the following control lines vertically align two pushbuttons, starting 12 characters in from the right side of the dialog box:

	dp  1  <12  1   10  +  &OK
	pb  2  +    +2  +   +  &Cancel

Executable Lines
---------- -----
Following the list of control codes and placement information, Signature character 2 () or Signature character 1 () indicate an executable line.  Either character indicates the start of an SPL (Signature Programming Language) program; however, a Signature character 1 () executes the program without removing the dialog box from the screen.

You must have a Signature character 1 or a Signature character 2 for each pushbutton you include in the dialog box.

Signature Character 1 Programs
--------- --------- - --------
Signature character 1 programs are useful only in a few limited situations, because they will not refresh the contents of a dialog box after executing.  For example, the following two lines in a Type K menu frame display a directory of filenames and a directory of paths in list boxes.  The Signature character 1 at the start of both lines enables the directories to be updated without removing the dialog box from the screen:

	(dir/fi/na %101 )<<EX>>
	(dir/pa/na)<<EX>>

Four things you will find useful in executable lines are passing information to SPL programs, the BX (Blind Execute) function call, the JM (Jump to Menu) function call, and checking unchanged fields.

Passing Information to SPL Programs.  You can use information from dialog box items in your SPL programs by prefacing the item's ID number with a %.  If the ID number corresponds to a list box, the text the user highlights with the cursor is accessed by the program.

For example, the following produces a directory based on the path the user enters in the text box that has ID number 101:

	(dir/fi/na %101 )<<EX>>

BX (Blind Execute) Function Call.  The BX function call executes a command from within a program without moving the cursor to or clearing the command line.  If the command and any arguments are enclosed in parentheses (), square brackets [], or curly braces {}, Signature executes the command automatically.  For example:

	(ca test)

Otherwise, if they are not so enclosed, you must use the Q2 (Execute Too) function call with the BX function call to execute the command.  Q2 is useful for executing a command string that may contain parentheses, square brackets, or curly braces.  For example:

	ca test

Illegal Characters
------- ----------
You cannot use angle brackets <> to enclose a command specified by the BX command.

JM (Jump to Menu) Function Call
--  ---- -- ----  -------- ----
The JM function call jumps to the menu frame with the specified keyword and is very useful in SPL programs in three ways:

 To control the program flow from one dialog box to the next

 To jump back to the same dialog box if a condition is not satisfied

 To call a subroutine; for example, to establish initial conditions for the program

JM has the form:

	(keyword)

MD+ITkeywordMDNM is the keyword of the frame or subroutine

The Exit Command
--- ---- -------
An EXIT command <<EX>> in the subroutine causes execution to return to the main program and resume.

For example, the following code jumps to a subroutine named SETNW3, calls a file the user specifies in a text box (ID 101), and jumps to another subroutine named RESTORENW:

	(SETNW3)(call %101)(RESTORENW)

The subroutines are included in the same menu file in Type 5 frames.  For example:

	{{5,SETNW3}}
	<<SX70,<<VA$NW>>>>(d nw=3)<<EX>>

	{{5,RESTORENW}}
	(d nw=<<PV70>>)<<EX>>

Checking Unchanged Fields.  You can use the HF command in the program to direct Signature to execute portions of the program only if a particular field has changed.  For example, if the user does not change the entry displayed in a text box, Signature skips that part of the program from the HF command to the EI (End If) command that follows.

HF has the form:

	<<HFid>>action<<EI>>

MD+ITidMDNM is the number of the control code for the item (usually a text box or a check box) that you want to determine is changed.

MD+ITactionMDNM is one or more commands you want executed if the item is changed.

For example, in the following routine execution moves to the label,
"-Changed" if the user has changed the text box with ID 100; otherwise, execution jumps to the menu frame with the keyword MD+ITPrSettingsMDNM:

	<<HF100>><<GL-Changed>><<EI>>(PrSettings)<<EX>>

Displaying Fixed Text
---------- ----- ----
There are two controls to display fixed text in a dialog box:  TX and TC.

You use the TX (Text) control code to indicate a line of fixed text that is always displayed in the dialog box.  In the text argument, you can specify up to 400 characters per TX control code.  To have Signature automatically calculate the width of the item based on the width of the text, enter the @ character when specifying a width for the MD+ITsizeMDNM argument.

When the text is displayed in the dialog box, the user cannot move the cursor to it.

For example, the following line in a Type K menu frame produces a line of fixed text that contains the words, "PRINT FILE:"

	tx  100  2  1  @  1  PRINT FILE

You use the TC (Text Changing) control code to indicate a line of fixed text that Signature can update to reflect changing conditions.  When the text is displayed in the dialog box, the user cannot select it; however, whenever a change occurs, the information is immediately updated to reflect the change.

For example, the following line in a Type K menu frame displays the current path name.  When the current path changes, the dialog box immediately displays the new path.

	tc  107  +90  +  70  12  <<VA$pa>>

Displaying a Text Entry Field
---------- - ---- ----- -----
You use the TB (Text Box) control code to include a field into which the user can enter text.  The user can select the displayed field either by pressing Tab or by using the mouse.  Signature includes any text you specified in the control line when the dialog box is displayed.  This text is automatically erased when the user starts typing in the first character position.  However, if the user presses a cursor key first, Signature does not erase text when the user starts typing.

You can have Signature validate the text the user enters into the field.  See "Validating Text Entry" for more information.

Specifying Text Box Locations
---------- ---- --- ---------
Signature uses square brackets to display the borders of a text box; for example, MD+BO[This is a text box]MDNM.  However, it does not include the square brackets when calculating the item's location coordinates.  Therefore, when specifying location coordinates for text boxes, add one extra space to compensate for the left square bracket.  (See the example on specifying relative locations in "Positioning Items in a Dialog Box.")

For example, the following line in a Type K menu frame produces a text box that contains the name of the current file:

	tb  101  +1  +2  22  1  <<VA$fi>>

You can assign an accelerator key to a text box by preceding it with a TX (Text) control that has an accelerator key.  Including an accelerator character in a TX control line forces the cursor to move to the next item when the dialog box is displayed and the accelerator key is pressed.  Refer to "Using Accelerator Characters in Menu Screens" for more information.

Using Radio Buttons in a Dialog Box
----- ----- ------- -- - ------ ---
A group of radio buttons covers all possibilities of a task.  Radio buttons are like the buttons on a car radio - when one is pushed in, another pops out - they indicate items that are mutually exclusive.

Radio buttons may be organized into more than one group.  The user must select one MD+ITfor each groupMDNM in order to execute the dialog box.  However, only one button in the set can be selected at a time.

You use the RB (Radio Button) control code to include radio buttons in a dialog box.  Consecutive RB control codes form a set from which only one can be selected at one time.

For example, the following line in a Type K menu frame produces a set of radio buttons that enables the user to choose ALL, EVEN, or ODD:

	rb  103  12  +1  10  1  ALL
	rb  104  +   +1  +   1  EVEN
	rb  105  +   +1  +   1  ODD

Enter Signature character 251 as the MD+IToptionMDNM argument (after the text) to indicate the radio button that is automatically selected when the dialog box is displayed.  To enter the character, type Ctrl-Alt 251.  You can also include a conditional statement to select the radio button depending on the current environment.

For example, the following line in a Type K menu frame selects radio button 3 if the display is draft view:

	rb  3  +5  +12  40  12  Button &1  <<VA$dt>>==1|

When Signature displays the dialog box, it indicates the selected radio button setting with an asterisk.

Using Check Boxes in a Dialog Box
----- ----- ----- -- - ------ ---
You use the CB (Check Box) control code to include a box the user can turn either on or off; it is equivalent to having the user type "Yes" or "No" to indicate a choice.  You can have one or more check boxes in a dialog box; however, usually you would not group them.

For example, the following line in a Type K menu frame produces a check box that enables the user to choose to print only the selected block:

	cb  107  12  +  25  1  &Print selected block

The user presses Spacebar to turn any check box on or off.  Signature displays an "X" to indicate an activated check box.

Enter Signature character 251 as the MD+IToptionMDNM argument (after the text) to indicate that a check box is automatically selected when Signature first displays the dialog box.  To enter the character, press Ctrl-Alt 251.  You can also include a conditional statement to select the check box depending on the current environment.

For example, the following line in a Type K menu frame produces a check box that is preselected if macro 1002 contains an "R:"

	cb  107  -1  +3  11  1  &Read Only  <<VA@1002>>=="R"|

Using Pushbuttons in a Dialog Box
----- ----------- -- - ------ ---
Pushbuttons represent choices associated with procedures or execution; they begin or apply the action.  Every Signature dialog box has at least one pushbutton.

You use the PB (Pushbutton) control code to include a pushbutton in a dialog box; you use the DP (Default Pushbutton) control code to include the default pushbutton.  Signature displays the default pushbutton with a double angle bracket (<< >>).  In Signature, the OK pushbutton is usually the default.

You include one SPL program for each pushbutton.  The pushbutton with ID 1 runs the SPL program designated by the first Signature character 2 () or Signature character 1 (); the pushbutton with ID 2 runs the second, etc.

There are several predefined pushbuttons you can use; for example, "OK" has 1 as an ID number and "CANCEL" has 2 as an ID number.  ID numbers 50 and over are reserved for special functionsthey do not correspond to an SPL program, but perform a function automatically.  For example, "HELP" has 62 as an ID number and displays a Help screen when the user selects it.  Refer to Appendix D for a full list.

For example, the following lines in a Type K menu frame include a default pushbutton (OK) and a CANCEL pushbutton in the dialog box:

	dp  1  40  1  10  1  OK
	pb  2  +   +2 +   +  Cancel

Using Scrollable Lists in a Dialog Box
----- ---------- ----- -- - ------ ---
You can include three types of scrollable lists in a Type K menu frame:

 Files only
 Drives and Directories
 Any words you specify

You use the LF (List Files) control code to list all the files in a directory.

You use the LD (List Drives and Directories) control code to list all the drives available on your computer and directories available from the current directory.  The user can select a drive by moving the cursor to a specific drive in the list and pressing carriage return.  If there is an asterisk (*) in the text box when the user executes the OK pushbutton, Signature displays a directory of the selected drive rather than execute the program associated with the first pushbutton.

For example, in the following Type K frame, the text box (ID 101) contains *.* to produce a list of files.  If the user selects an item from the List Files Box (ID 105), Signature updates the contents of the text box with the selected information.  If the text box contains a wild card and if the user selects the OK pushbutton (ID 1), Signature builds a new directory using that specification.

	{{K,Open}}
	1    1   6   2   66   16
	tx   101 2   1   @    1         Open File:
	tb*  102 2   +1  25   1        <<VA@1001>>
	lf   105 2   +3  20   8                *.*
	ld   106 +22 +0  20   8
	tx   104 2   +9  40   1	Current Directory:<<VA$pa>>
	dp   1   50  1   11   1                &OK
	pb   3   +0  +2  11   1              &Find
	pb   4   +0  +2  11   1           O&ptions
	pb   2   +0  +2  11   1            &Cancel
	pb   5   +0  +2  11   1              &Help
	cb   107 +0  +3  11   1         &Read Only

You use the LB (List Box) control code to list any words you want.  You specify the words in the text argument, separated by Signature character 124 (|).  You can include a list of macros in a List box.  For example:

	lb  102  3  3  22  1  <<VA@111>>|<<VA@121>>|<<VA@122>>|<<VA@98>>|<<VA@101>>

The List Files Box, the List Drive and Directories Box, and the List Box can be linked to the closest text box above it in the list; so that whenever the user selects an item in one of the boxes and presses Spacebar, Signature inserts the selected item into the text box.

Special Lists
------- -----
There are also some special values you can use to produce lists with the LB control:

@x lists the contents of a macro (x).
?x lists one of the following:
	?AS - symbol sets
	?BO - BORDER commands in the current document
	?DZ - all sizes available for the default font and highlights the default size
	?FO - fonts used in the current document
	?IG - graphic files included in the current document
	?MA - all macros
	?PC - printer control codes
	?PP - printers listed in the PP Table of SETTINGS.DFL
	?PR - files currently waiting to be printed (automatically updated)
	?SB - symbol set available for the current font
	?SG - sizes of all macros (not contents), including extended macros and special macros for Signature
	?SP - spelling alternates (used only by the spelling dialog box)
	?SS - styles for the current file
	?ST - commands in the command stack
	?SY - synonyms (used only by the Thesaurus)
	?SZ - sizes available for the current font
	?WI - all open windows

For example, the following produces a list box that when displayed lists all the BORDER commands in the current document:

	lb  240  5  +2  15  2  ?BO

List Services
---- --------
The List Services feature enables you to display a directory, select multiple files in the directory, and execute a command that affects all the selected files, one after another.

To display a directory from which multiple files can be selected, use the /LO switch with the DIR command.  For example:

	(dir/lo %101)<<EX>>

DIR/LO in Executable Lines
------ -- ---------- -----
When using DIR/LO in an executable line, you must always use Signature character 1 (), never Signature character 2 ().

To select a filename from the displayed directory, put the cursor on the filename and press the space bar.  Signature indicates selected filenames with an asterisk.

To process a list of selected filenames with a specific command, use the /LS switch with one of the following commands:

	ATTRIB (Change Attribute)
	COPY (Copy a File)
	COPY/MY (Move a File)
	DEL (Delete a File from Disk)
	REN (Rename a File)

For example, the following removes from disk all the files selected in the list box:

	(del/ls %101)<<EX>>

Grouping Items in a Dialog Box
-------- ----- -- - ------ ---
You use the GB (Group Box) control code to enclose related items, such as radio buttons, in a rectangular box.  Optionally, you can add a title to the box, which Signature displays in the top border of the Group box.  Group boxes organize items visually on the screen; they do not functionally group them.

When the dialog box is displayed, the user cannot move the cursor to the Group box  only to the items in it.

For example, the following groups two lines of fixed text into a box:

	gb  107  1  6   35  4  Shortcut:
	tx       +2 +1  28  1  Alt+PgDn Next page
	tx       +  +1  28  1  Alt+PgUp Previous page

Dimming or Automatically Selecting Dialog Box Items
------- -- ------------- --------- ------ --- -----
To display in a lighter screen display face any item that you do not want the user to access or to automatically select an item, include the following as the MD+IToptionMDNM argument:

	condition1 | action1 | condition2 | action2

MD+ITconditionMDNM is a test that can be evaluated to have a true or false value; it can be any boolean expression, such as normally found in an IF statement.

MD+ITactionMDNM is the action to take if the corresponding condition is true.  To dim an item, enter Signature character 176; to automatically select an item, enter Signature character 251.

A condition usually starts with an embedded command.  If there is no condition, it is assumed to be true.  For example, the following option argument tests the value of the Default BK (Backup of Files) setting.  If the setting is on (BK=1), Signature selects the item:

	<<vabk>>==1|

For another example, the following option argument uses $WS (Window Status) to test if there is a file open.  If the window is empty ($WS=0), Signature dims the item:

	<<va$ws>>==0|

You can test two or more conditions to determine whether or not to select or dim a radio button or a check box.  The test can be true in one case or the other or in both cases (similar to OR and AND conditionals in programming).

To test two or more conditions (OR), one or more of which must be true in order for the test to be true, list each MD+ITconditionMDNM followed by a vertical bar (Signature character 124) and the MD+ITactionMDNM to take if the condition is true.  For example the option argument in the following control line checks to see if line spacing is set to .50 MD+ITorMDNM if automatic leading is off:

	rb  5  2  2  10  1  Half  <<vals>>==.50||<<vaal>>==0|

If line spacing is set to .50, Signature selects radio button 5 as the default and exits.  Otherwise, it tests to see if automatic leading is off; and if so, it selects radio button 5 as the default and exits.

To test two or more conditions (AND), all of which must be true in order for the test to be true, list each MD+ITconditionMDNM followed by a vertical bar (Signature character 124).  At the end of the list include the MD+ITactionMDNM to take if the condition is true.

For example, the option argument in the following control line checks to see if line spacing is set to .50 MD+ITandMDNM automatic leading is off:

	rb  5  2  2  10  1  Half  <<vals>>==.50|<<vaal>>==0|

If both conditions are true, Signature selects radio button 5 as the default.

Validating Text Entry
---------- ---- -----
You can have Signature determine whether the text the user types into a text box is a valid argument for a specific Signature command.  You include the validation in the text argument of the TB (Text Box) control line.

Separate the validation from the text with the string ;**; followed by one of the following validation type indicators.

>	indicates that the field is mandatory.  If the field is left blank, the user cannot execute the dialog box.  > must appear before any other validation.

<	indicates a list of pushbuttons you MD+ITdo notMDNM want validated.  (In Signature, pushbutton 2 is always Cancel and is never validated and pushbutton 62 is always Help and never validated.)  For example, the following avoids validation if the user chooses pushbuttons 2, 3, 9, or 62:  ;**;<3,9.

One Validation Per Control
--- ---------- --- -------
You can only use one validation with each control with the exception of < and >.  < and > are the only validation indicators you can use in conjunction with another type of validation.

@	immediately followed by a two-letter embedded command validates that the value the user enters into the text box is an acceptable argument for that command.  If it is not, Signature displays the same error message it would if the command had been executed from the command line.  For example, the following verifies that the user enters an acceptable value for the Left Margin command:  ;**;@lm.

#	indicates that the user can enter only an integer into the field.

-	indicates that the user must enter two integers separated by a hyphen.

.	indicates that the user can enter either a number with a decimal point or an integer into the field.

+	indicates that the expected user response is a valid math expression, such as 9*3.

%	indicates that the expected user response is a single alphanumeric character (A to Z or 0 to 9).

\	validates that the path and drive the user entered exist.

	Signature character 23 validates that the filename the user enters does not contain any invalid characters (for example, *+=,.?"/\[];:<<>>|), that there are eight characters or fewer in the filename, and that there are three characters or fewer in the extension.

=	validates that the filename the user entered exists, and performs the same validation as .

^	validates that the filename the user entered does not exist.

$	accepts a number with a leading dollar sign if the user enters one; i.e., 11.50 and $11.50 are both valid user entries.

!	indicates that the expected user response is a page-line number; for example, 1-4 (page 1, line 4).

/	indicates that the expected user response is a string of page number ranges; for example, 1-4/9-12 (pages 1 through 4 and 9 through 12).

]	accepts the word "AUTO" used either for the SI (Size) argument in the FA (Frame Area) command or for line spacing in footnote and text formatting commands.  Enter it with the two-letter command; for example, ;**;]RM.

	Signature character 20 validates that the user entered an acceptable vertical position for the FA (Frame Area) command (PC, LP, CP, RP, LC, CC, or RC).  Enter it with a two-letter command that also requires a valid numeric vertical position, such as LS; for example, ;**;LS.

	Signature character 21 validates that the user entered an acceptable horizontal position for the FA (Frame Area) command (PC, TP, CP, BP, TC, CC, or BC).  Enter it with a two-letter command that also requires a valid numeric horizontal position, such as RM; for example, ;**;RM.

[	validates that the style the user entered exists in the current document.

For example, the following indicates that if the user selects any pushbutton other than 2, 3, 9, or 62, Signature validates that the value entered in the mandatory field is a valid argument for the Left Margin command:

	;**;<3,9>@lm

As another example, the following text argument of a TB control line displays the current page width setting and validates that whatever new value the user enters into the field is a valid argument for the Page Width command:

	<<VApw>>;**;@pw

Using One Control to Affect Another
----- --- ------- -- ------ -------
You can set up text boxes, radio buttons, or check boxes to affect other controls in two ways:

 Entering text into a text box can automatically select a radio button.

 Selecting a radio button or a check box can change the contents of text boxes (TB or TC) and check or uncheck check boxes.

You do this by assigning values and conditions to controls.  Selecting a pushbutton executes the SPL program whose ordinal position corresponds to the control's ID numberfor example, the pushbutton with ID 1 runs the SPL program designated by the first Signature character 2 () or Signature character 1 (), the pushbutton with ID 2 runs the second, etc.

By assigning an appropriate ID to a text box, you can automatically select a radio button as soon as the user types into that text box.

By assigning an appropriate ID to a radio button or a check box, you can provide an initial value for a text box or select a check box as soon as the user selects the control.

In either case, you use the following format for the executable line:

	c1 =string1|c2=string2|

MD+ITc1MDNM and MD+ITc2MDNM are control numbers.

MD+ITstring1MDNM and MD+ITstring2MDNM are the values you want included in controls C1 and C2, respectively.  You could use the VA command to insert a current value into the control.

Ending Executable Lines
------ ---------- -----
You must end each executable line with either a Signature character 124 (|) or a Signature character 1 () or a Signature character 2 ().

For example, the following executable line automatically enters values into two fields if the user selects a radio button:

	10=8.5|11=11|

Assume that the example executable line is the fifth in the group of executable lines for a "Page Setup" dialog box.  When the user selects the "Letter" radio button that has an ID of 5, Signature automatically enters a value of 8.5 into the "Width" text box that has an ID of 10 and a value of 11 into the "Length" text box that has an ID of 11.

As another example, the following executable line outputs the contents of macro 1191 into the text box that has an ID of 6 and outputs the location of the startup file in the text box that has an ID of 7 if the user selects a radio button:

	6=<<VA@1191>>|7=<<VA$st>>|

As another example, the following executable line automatically selects the radio button that has an ID of 9 when the user enters text into a text box:

	9=1|


FCExecuting a Routine
FL
You use a Type 5 frame in either the Menu file or the Help file to execute commands and programs.  Although Type 5 frames may contain displayable lines, they are usually used as "routine only" frames, which initialize some variables before moving to a dialog box or a Help frame.

Keyword Label
------- -----
The first line of a Type 5 frame contains the label (5 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}.  Displayable Lines
----------- -----
A Type 5 frame can contain up to twenty displayable lines.  Refer to the next section, "Positioning Menu Screens," for information on determining the placement of Type 5 displayable lines on the screen.

If you do not want to display a screen, simply include the program as the second line of the menu frame.

Executable Lines
---------- -----
The content of the executable lines depends on the function you want the frame to perform.  In order to execute a program, start the line with a Signature character 2 ().

Executable lines can wordwrap.  An executable line begins with the Signature character 2 () and ends at the next Signature character 2 or EX command.

For an example, the following Type 5 frame contains a routine that saves the current status of the NW (New Window) default to macro 70 before setting the default to 0:

	{{5,SetNWO}}
	<<SX7O,<<VA$NW>>>>(d NW=O)

After Signature performs the function that calls the SETNW0 subroutine, it can restore the original settings by calling another subroutine:

	{{5, RestoreNW}}
	(d NW=<<PV70>>)


FCPositioning Menu and Help Screens
FL
You use the DGW (Menu Screen Window Position) command in a menu file to position a Type 5 frame or in a Help file to position a Type C frame on the screen.

DGW has the following format:

	dgw l,t,w,d

MD+ITlMDNM is the number of columns you want the screen displayed from the left of the window

MD+ITtMDNM is the number of lines you want the screen displayed from the top of the window; you must specify a number greater than 3

MD+ITwMDNM is width of the screen specified in columns

MD+ITdMDNM is the depth of the screen specified in lines.

For example, the following line in a frame positions a screen that is 78 columns wide and 20 columns deep, 1 column from the left and 4 lines from the top of the window:

	<<DGW1,4,78,20>>


FCUsing Accelerator Characters in Menu Screens
FL
When a menu screen is displayed, the user can move directly to a specific item by pressing the accelerator key associated with the item.  When a menu screen is displayed, accelerator keys are highlighted.

In the pull-down menus, accelerator keys are the highlighted characters (for example, ~F); for the menu bar and dialog boxes, the accelerator keys are Alt and the highlighted character (for example, Alt A).

You set this up in the menu frame and in the keyboard file.

Menu Bar and Pull-Down Menus
---- --- --- --------- -----
To indicate the accelerator key in the menu frame that displays the menu bar or a pull-down menu, simply precede the keyword character you want as the accelerator with an ampersand (&).

For example, the following two displayable lines in the Type 0 frame in SIG.MNU designate F as the accelerator character for the File item and M as the accelerator character for the Format item:

	{{0,!n}}
	&File <<JDMBFile>>,
	For&mat <<JDMBFormat>>,

When the menu bar is displayed, the user can make a selection by pressing the letter key that corresponds to the highlighted letter in the word (for example, press F to select MD+BOFileMDNM; press M to select MD+BOFormatMDNM).

Dialog Boxes
------ -----
To indicate the accelerator key for a dialog box item, precede the character you want as the accelerator with an ampersand (&) in the text argument of the item's control line.

For example the following entry designates "2" as the accelerator key for the radio button (ID 105):

	rb  105  +  +12  +  +  Button &2

Including an accelerator character in a TX control line forces the cursor to move to the next control the cursor can go to when the dialog box is displayed and the accelerator key is pressed.

For example the following entry designates "N" as the accelerator key for the text box (ID 101):

	tx   100  8  8    100  12  &New Filename:
	tb*  101  +  +14  100  12  123456789:

The cursor moves to the text box when the user presses Alt N.

Using Accelerator Characters with Pushbuttons
----- ----------- ---------- ---- -----------
If you associate an accelerator character with a pushbutton, Signature executes the program associated with the pushbutton when the user presses [a] and the accelerator key.  It is as if the user pressed Tab to move to the item and pressed carriage return.

Keyboard File
-------- ----
Assign the AK (Accelerator Key) function call to the corresponding character in the ALT table of the keyboard file.  The AK function call has the form:

	AK,accel

MD+ITaccelMDNM is the accelerator character you specified in the menu frame.

For example, the following notation in the ALT Table of a keyboard file assigns the accelerator character 2 to Alt 2:

	3=ak,2

When the dialog box is displayed and the user presses Alt 2, the cursor moves directly to the text with "2" as the accelerator character.


FCProviding Context-Sensitive Help Screens
FL
Context-sensitive Help screens are useful to provide information about a specific phase of a task the user is trying to accomplish.  You set up the Help screens differently, depending on the way they will be accessed:  through Help pushbuttons, individual dialog box items, or pull-down menus or other screen types.  You can also provide Help screens for command markers.

Help Pushbuttons
---- -----------
You can provide Help for an entire dialog box by including a frame in the Help file with a label in the following format:

	{{#,keyword}}

# indicates the frame type.

MD+ITkeywordMDNM is the name of the menu frame in the menu file.

For example, the following label designates the beginning of a Type C frame in the Help file that provides information on the menu frame that has the keyword MD+ITPrintToFileMDNM:

	{{C,PrintToFile}}

Result:  When the user activates the Help pushbutton in the dialog box, Signature displays the information contained in the Help frame.

Refer to the next section, "Displaying a Scrollable Help Screen," for more information on Type C frames.

Dialog Box Items
------ --- -----
You can provide Help for the various items in a dialog box.  Help is available by pressing F1 on any item you can tab to:  text boxes, radio buttons, check boxes, list boxes, and pushbuttons.  You set this up by including a frame in the Help file with a label in the following format:

	{{#,keyword id}}

# indicates the frame type.

MD+ITkeywordMDNM is the name of the menu frame in the menu file that includes the field.

MD+ITidMDNM is the number of the dialog box item for which you want to provide Help.  Do not include a space between keyword and id.

For example, the following label designates the beginning of a Type C frame in the Help file that provides information on item 103 in the menu frame with the keyword MD+ITprintMDNM:

{{C,print103}}

Result:  When the user puts the cursor on the item and presses F1, Signature displays the information contained in the Help frame.

Pull-Down Menus and Other Screens
--------- ----- --- ----- -------
To link context-sensitive Help screens for Type 5, Type C, and Type L frames, in the Help file create a Type C frame that has the same keyword as the frame in the menu file you want to chain it to.  Add an @ character to the keyword in the new frame label.

For example, a Help frame with the following keyword label in the Help file provides information on the menu frame with the keyword MD+ITGHelpMDNM:

	{{C,GHelp@}}

To provide Help on an item in a pull-down menu (Type L), use the keyword inside the JD command from the menu file as the keyword for a frame in the Help file followed by @.

For example, in the menu file the following item appears as part of a Type L menu frame:

	&New...<<JDNew>>,Create a new file

To provide information on that item, include a Help frame in the Help file with the keyword MD+ITNew@MDNM.

Command Markers
------- -------
You can use the ST (Show Triangle) function call and a Type C Help frame in the menu file to provide full explanations of command markers.  When the user puts the cursor on a marker in a text file and executes the ST (Show Triangle) function call, Signature displays a frame (if one exists with the proper keyword in the menu file).

The Help frame must reside in the menu file and have as one of its keywords the two-letter embedded command mnemonic preceded by a ^.

For example, the following Type C label has the keyword LM and can be used to provide Help for LM (Left Margin) command markers:

	{{C,^LM}}

To make the function easier to use, assign ST to a key in the keyboard file.  For example, the following entry in the keyboard file assigns the ST function call to key 35 (H):

	35=XH,ST

Result:  When the user puts the cursor on an LM command marker in a text file and presses Alt-Shift H, Signature displays the information contained in the Type C frame with the keyword LM.


FCDisplaying a Scrollable Help Screen
FL
You use a Type C frame in the Help file to display a Help screen that you can scroll vertically.  You can link a Type C frame to other Help frames to replace the currently displayed screen; for example to display a related topic.

To replace the currently displayed screen, the user puts the cursor on a bold keyword and presses carriage return.

When the screen is displayed, the cursor moves to any bold or underlined keyword visible.  When the user presses cursor keys, the cursor moves from visible keyword to visible keyword.

Keyword Label
------- -----
A Type C frame can consist of any number of lines.  The first line contains the label (C, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}.

The second line can contain a DGW (Dialog Window) command to set the size of the window, followed by any formatting commands you want to use.  Refer to "Positioning Menu or Help Screens" for more information.

Displayable Lines
----------- -----
Each subsequent line contains text you want displayed on the screen.  To link the frame to another frame, include a word either in bold or in underline mode somewhere in the text and use the JD (Jump to Dialog Box) command with the other frame's keyword to link the two frames.

JD Command Position
-- ------- --------
The JD command must appear immediately MD+ITafterMDNM the linking word and MD+ITbeforeMDNM the MDNM (Mode Normal) command.

Bold Mode
---- ----
You can use bold mode throughout the frame for emphasis.

For example, the following Type C frame in SIG.HLP has the label, "ghGetstart".

	{{C,ghGetstart}}
	<<DGw05,04,70,19>><<MDBO>>< Exit ><<JDExHelp>><<MDNM>>
	<<MDBO>>< Index ><<JDldxHlp>><<MDNM>>
	<<MDBO>>< Keys ><<JDKeyHlp>><<MDNM>>
	<<MDBO>>< Previous ><<JD>><<MDNM>>
	---------------
	Getting started help topics

	<<MDBO>>System requirements<<JDS49P>><<MDNM>>
	<<MDBO>>Overview<<JDOverview>><<MDNM>>
	<<MDBO>>Using Signature help system<<JDAbouthlp>><<MDNM>>
	<<MDBO>>Starting Signature<<JDEditor>><<MDNM>>
	<<MDBO>>Running programs under Signature<<JDD17P>><<MDNM>>

If the user puts the cursor on "Exit" and presses carriage return, Signature executes the subroutine, ExHelp.  If the user puts the cursor on "System Requirements," Signature displays the frame with the keyword MD+ITS49PMDNM.


FCIncluding Text in Screen Borders
FL
When Signature constructs menu and Help screens from information in a Type 5 frame with displayable lines or a Type C frame, it automatically includes a border for screen display.  You can use the DGT (Menu Screen Top) command to automatically include text in the top of the border and the DGB (Menu Screen Bottom) command to automatically include text in the bottom of the border.

You specify border text for an individual menu or Help screen by using DBT or DGB on the second line of the frame, immediately following the label.

When you type either command on the command line and press carriage return, a command window opens on the screen.  Type the text exactly as you want it to appear in the border, and then press F11 to close the command window and complete the procedure.

For example, the following includes the text "How to Find a File" in the top border of a Type C frame that discusses finding files:

	{{Cfind}}
	<<DGTHow to Find a File>>

You can specify default text that you want included in the border of every Help screen by using the DGT or the DGB command on the second line of the Help file.  For example, the following includes the text "Press the Return key to continue," in the bottom border of all the Help screens generated by the file:

	;HL;
	<<DGBPress the Return key to continue>>


FCDisplaying Detailed Explanations of Error Messages
FL
You use a Type 9 frame in the Help file to activate the Signature feature for displaying a full screen of information about the last error message the user received.  It is another way to access frames by using Signature's error coding system.  A single Type 9 frame in the Help file enables Signature to display the Type C frame that contains in its label the keyword number associated with the last error message displayed.

Keyword Label
------- -----
A Type 9 frame consists of only one line which contains the label (9 followed by one or more keywords) enclosed in a pair of curly braces {{ }}.  For example, in SIG.MNU the Type 9 frame looks something like this:

{{9,last error message,^F1}}

In the example, the MD+IT9MDNM indicates that the frame is a Type 9.  MD+ITlast error messageMDNM and MD+IT^F1MDNM are the keywords associated with the frame.

Displayable Lines
----------- -----
You use a Type C frame to enter the message you want displayed for one or more errors, and use one or more internal Signature error numbers as keywords.  Add leading zeros to error numbers less than three digits (for example, 006 or 032).  You can scroll through the SIG.HLP file for many of the current error numbers.  (All the frames that describe errors are grouped under the Type 9 frame label.)

For example, the Signature error message, "There is no command on the command line," is error message number 11.  If the user presses error when Signature generates that error message, Signature displays a full Help screen describing the problem.  Signature constructs the displayed screen from a Type C frame in SIG.HLP with the following label:

	{{C,011}}

In the label, the C indicates that the frame is a Type C and MD+IT011MDNM is the internal number of the error message.

You can have Signature automatically display your Error Help screens whenever an error occurs.  Use the Default EH=1 to activate the feature; EH=0 to disable it.  (Although this feature is helpful for beginners, it can slow the performance of more experienced users.)


FCTesting Dialog Boxes and Help Frames
FL
Signature has several functions to assist you in debugging menu or Help files.

 ?m and ?h test commands

 Quick Help (QH) function call

 Quick Print (QP) function call

?m and ?h Test Commands
-- --- -- ---- --------
You can quickly display the currently loaded menu or Help frames by using the ?m command for menu frames or the ?h command for Help frames.  These commands have the following format:

	keyword ?m or
	keyword ?h

MD+ITkeywordMDNM is the keyword of the frame you want to display.

For example, to display the Help frame with the keyword MD+ITcreditsMDNM:

	F5 credits ?h F9

The QH (Quick Help) Function Call
--- --  ----------  -------- ----
QH lets you test frames without saving and reloading the menu or the Help file.

The QH function call is assigned to Ctrl-Alt-Shift Q in the Signature keyboard file.

To use QH, position the cursor in the frame you want to test and press Ctrl-Alt-Shift Q.  Signature immediately displays the associated screen.

QH Not Useful with All Frames
-- --- ------ ---- --- ------
QH does not work with Type 0, Type C, or Type L frames.

The QP (Quick Print) Function Call
--- --  ----- -----  -------- ----
QP prints the dialog box associated with the frame in which the cursor is located in a displayed menu or Help file.

To use QP:
1.  Position the cursor in the frame you want to test.

2.  Type:  F5 func qp (carriage return)

Signature prints the dialog box as it will appear on the screen.


FCAccessing a Menu Screen with One Keystroke
FL
You use the JM (Jump to Menu) function call in the keyboard file to access Type K or Type 5 frames directly from the keyboard.

In the keyboard file, JM has the form:

	JM,(,k,e,y,w,o,r,d,)

MD+ITk,e,y,w,o,r,dMDNM is the keyword of the menu frame or subroutine.  The keyword must appear in parentheses and each letter of the keyword must be separated by a comma.

In the Signature keyboard file, all the JM function calls are preceded by XH (Exit Help) commands to remove any currently displayed Help or menu screens before jumping to the frame.

For example, the following notation in the CTRL Table of the Signature keyboard file assigns the Open dialog box to key 24 (O):

	24=XH,JM,(,O,p,e,n,)

When the user presses Ctrl O, Signature first removes any Help or menu screen displayed and then displays the dialog box that has the keyword Open.


FCAccessing a Help Screen with One Keystroke
FL
You use the JH (Jump to Help) function call in the keyboard file to access Type C frames directly from the keyboard.

In the keyboard file, JH has the form:

	JH,(,k,e,y,w,o,r,d,)

MD+ITk,e,y,w,o,r,dMDNM is the keyword of the Help frame you want to access.  The keyword must appear in parentheses and each letter of the keyword must be separated by a comma.

In the Signature keyboard file, all the JH function calls are preceded by XH (Exit Help) commands to remove any currently displayed Help or menu screens before jumping to the frame.

For example, the following notation in the CTRL Table of the Signature keyboard file assigns the Help frame with the keyword ^F1 to key 59 (F1):

	59=XH,JM,(,^,F,1,)

When the user presses Ctrl F1, Signature first removes any Help or menu screen displayed and then displays the Help frame that has the keyword ^F1.


FCLoading Menu and Help Files
FL
Use the Load command to load your menu or Help file as you would any other customization files.  For example, to load a menu file named MY.MNU:

Type:  F5 load my.mnu (carriage return)

If you haven't entered the special file label (;MN; or ;HL;) as the first line of the menu or Help file you are loading, Signature displays the error message, "Customization file requires a file label."

Since menu and Help files can become very large, Signature never keeps the whole file in memory.  The first time you load a menu or Help file, Signature creates an internal index of the file and stores the index at the bottom of the file.  This index, and certain other types of frames, are all that actually load into memory, which allows a very large menu or Help file to consume very little memory.  When you access the Menu or Help facility, Signature checks the index, much as you check the index of a book, to determine where to get the information you want displayed.  It then refers back to the file stored on disk to get the information to display on the screen.

If you load the same unchanged menu or Help file again, Signature does not rebuild the index, so the file loads very quickly.  Whenever you edit a menu or Help file and store it back to the disk, the index is removed.  The next time you load the file, Signature rebuilds the index.  Therefore, loading times vary depending on whether or not the menu or Help file was edited.

Although a menu or Help file can be any size that fits on a disk, the index cannot exceed 64K.

