APPLICATION NOTE #150 CREATING MENUS Rev. 01 RELATED FILES: SAMPLE.HLP, EXTRA.HLP Menus list a variety of tasks or several topics of information on the screen. By simply selecting options from the menu, novice users can execute commands, run programs, or get help using XyWrite. They do this with a minimum of typing and without remembering command syntax, because the menu masks the syntax in an easy-to-use format. Advanced users also find many applications for menus, such as organizing information and performing repetitive or complex tasks easily. This application note tells you how to create menus that are helpful when * displaying information on any topic * executing commands on the command line, from a numbered list, or with a directory on the screen * calling a specific file * displaying information based on words or phrases * displaying keyboard information * accessing ASCII characters * displaying a detailed explanation of the most recent error message Information on accessing a specific Help screen with one keystroke is also provided along with two advanced tech-niques, creating subroutines and temporarily saving values. The ability to create menus is a function of XyWrite's Help feature. You construct menus by creating a Help file that is structured the same way LONG.HLP or SHORT.HLP is structured. (Application Note #143, Modifying LONG.HLP or SHORT.HLP, tells you how to accomplish various functions using the Help feature and provides three useful step-by-step examples.) A Help file consists of many sections or frames. Each frame designates the information XyWrite displays on a screen at a time, and it may contain commands or programs the user can initiate from the screen. SAMPLE.HLP is a Help file that, when loaded, provides on-line examples of the topics discussed in this application note. (SAMPLE.HLP is on the disk you received with this application note.) To load SAMPLE.HLP from the A drive Type: F5load a:sample.hlp Once you have loaded SAMPLE.HLP, access it as you would any Help file Example frames of SAMPLE.HLP are shown throughout this application note in Expanded Mode to illustrate the formatting commands used and the XPL programming. CREATING HELP FILES You create a Help file as you would any other text file. For example, to create a Help file named ADDRESSES Type: F5ne addresses Although you can name the Help file any name you want, the first line of the file must contain the following 4-character label which identifies it as a Help file: ;HL; (You must type the label exactly as shown: semicolon, capitalized HL, semicolon.) On the second line of the Help file, you can include formatting commands (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, you can include 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. Preface all comment lines with a semicolon (;) and end all comment lines with a carriage return. Following the comment lines, Help files consist of sections or Help frames that XyWrite uses to construct and operate each Help screen. HELP FRAMES Each Help frame contains text XyWrite displays on the screen, and it may contain commands or programs the user can initiate from the screen. There are several different Help frame types you can use depending on the way you want the Help screen to function. Some Help frame types display only one line while others are capable of displaying a full screen of information (up to twenty lines). The various types are described throughout this application note based on their functions (such as executing commands and programs or displaying key assignments). The examples provided by SAMPLE.HLP are discussed in detail. Each Help frame starts with a label enclosed in a pair of double curly braces {{ }}. A Help frame begins at the label and ends at the next label (which signals the beginning of the next Help frame). Although Help frames are not listed in any particular order within the Help files, XyWrite has no trouble quickly finding the topic on which the user requested information. Help Frame Labels Help frame labels must have the following format: {{#keyword1,keyword2,. . .}} The # in the label indicates the Help frame type. You enter the number (0 through 9) or the letter (A through G) that corresponds to the frame type you want to use. Help frame types and their functions are described in the sections below. The keyword in the label is the name by which the Help frame can be accessed. KEYWORDS One or more keywords in the label indicate the way(s) the Help frame can be accessed. There is no limit to the length of a keyword; however, shorter keywords are easier to use and take up less memory. For example, the following label with the keyword formats designates the beginning of a Type 5 Help frame that discusses formats: {{5formats}} Although shorter keywords are preferable, a keyword can contain two or more words separated by a single space. For example, the following label with the keyword more addresses designates the beginning of a Type 6 Help frame that contains additional addresses: {{6more addresses}} If you include several keywords (separated by commas) in a label, the Help frame can be accessed by different names. For example, a frame concerning calling a file can be accessed several ways because the following label precedes the text for the frame in the Help file: {{1call,edit}} When the Help file is loaded, one way the user can display the information is by selecting or entering "call," or "edit" from the menu. Keywords can be either upper- or lowercase letters (or any mix). There are three wildcards you can use in keywords: *, ?, and #. The * wildcard means that any character or characters can occupy that position. For example, the following label can be accessed by spelling, speller, spells, or any other characters following the word spell: {{0spell*}} The ? wildcard means that any single character can occupy that position. For example, the following label can be accessed by @a, @b, @$, etc. {{1@?}} The # wildcard means that any single digit can occupy that position. For example, the following label can be accessed by c0, c1, ...c9: {{2c#}} Keywords also link Help frames together, which enables the user to move directly from one task or topic to another. You set this up by including the keyword of one Help frame in bold somewhere in the text of another Help frame. The user places the cursor on one of these words to highlight it and presses the carriage return. XyWrite displays the Help frame labelled with the highlighted word from the previous frame. If you include more than one bold keyword in a Help frame, you must separate them by at least two spaces. To save disk space (and time), you can enter the spaces while still using bold mode. For example, the following Type 6 Help frame lists employee addresses. When the frame is displayed on the screen, the user can place the cursor on the bold Development, Marketing, Shipping, or Tech Support keywords that appear at the bottom of the screen to access these related topics. {{6employees}} EMPLOYEE ADDRESSES Ruth G. Parker, President 44 Manning Park Billerica, MA 01821 Rosemary K. Cross, Vice President 275 Tremont Street Boston, MA 02178 Susan B. Anthony, Finance 27 Main Street Nutting Lake, MA 01730 Other addresses by department: Development Marketing Shipping Tech Support The user can move through as many linked Help screens as needed. The screens are layered on top of each other, the most recent on top in a stack of up to 14 screens. If necessary, the user can move backwards through the stack of screens by pressing Esc. However, if the user accesses more than 14 screens, the first 14 screens are dropped from the stack and XyWrite starts to build another stack of screens. Therefore, when the user accesses the fifteenth linked Help screen and then presses Esc, XyWrite returns to the point at which the user entered Help. Be careful that you do not create two Help screens that use the same keyword, especially when using wildcards. For example, if the following two labels exist in the same Help file in the order shown, the Type 5 Help frame will never be displayed. XyWrite searches the Help files from top to bottom and will select the Type 1 Help frame as a match when the user enters "spelling" because of the wildcard (*). {{1spell*}} {{5spelling}} SPECIAL KEYWORDS There are also six special keywords you can use to designate the conditions under which a specific Help frame can be displayed. Five of the special keywords ($N, $F, $D, $B, and $*) are used when displaying a Help screen menu and are described in this section. The other special keyword is described in "Accessing a Specific Help Screen with One Keystroke." You can use the five special keywords to designate how the user can access Help. The keywords, which must all be prefaced with a dollar sign ($), and the conditions they designate are listed below. Special Keyword User can call the Help frame when $N Nothing is open on the screen $F A file is open on the screen $D A directory is open on the screen $B A block is defined in the current file $* Any of the above situations For example, the Help frame that defines the main menu for SAMPLE.HLP contains the following label, which indicates a Type 0 Help frame that can be displayed whether there is something on the screen such as a directory ($D), or a file ($F) or whether there is nothing on the screen ($N): {{0$D,$F,$N}} LOADING HELP FILES Use the Load command to load your Help files as you would any other customization files. Refer to the XyWrite III Plus Reference Guide for more information on loading customization files. Since Help files can become very large, XyWrite never keeps the whole file in memory. The first time you load a Help file, XyWrite creates an internal index of the file and stores the index at the bottom of the Help file. This index, and certain other types of Help frames, are all that actually load into memory, which allows a very large Help file to consume very little memory. When you access Help, XyWrite 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 Help file stored on disk to get the information to display on the screen. For this reason, it is important to specify the full path and file name when you load the Help file. If you load the same unchanged Help file again, XyWrite does not rebuild the index, so the file loads very quickly. Whenever you edit a Help file and store it back to the disk, the index is removed. The next time you load the Help file, XyWrite rebuilds the index. Therefore, loading times vary depending on whether or not the Help file was edited. Although a Help file can be any size that fits on a disk, the index cannot exceed 64K. (You can monitor the size of the index with the Memory Usage Menu.) One way you can decrease the amount of memory your Help files require is by using the Help frame types that are stored as part of the index, rather than those that are fully stored in memory. The chart on Page 4 indicates which Help frame types are stored in memory and those which are not. TYPES OF HELP FRAMES The chart below summarizes all the types of Help frames available, their functions, their links, and whether or not they are stored in memory. Each function and the associated Help frame is described in detail in separate sections of this application note. Each type of Help frame can be accessed only from certain other types of Help frames as listed in the "Links From Types" column of the chart. Each type of Help frame can be used to access another frame as listed in the "Links To Types" column. Stored Links From Links To Function Type(s) in Memory Types Types Displaying a menu 0 Yes 0 All Displaying a general-purpose full screen 6 No All All Displaying function call 8 No 0, 4, 6 6 information D No 0, 4, 6 8 Executing commands and 1 Yes 0, 6 programs 5 No 0, 5, 6 0, 6 C No 0, 6 from a directory 7 No 0, 6 from a numbered list B No 0, 6 from a list of keywords F No 0, 6 Calling a specific file G Yes All 5, 6, 7, 8, 9, B, C, D, F Displaying information based 3 Yes 0 All on key words or phrases Displaying key assignments 4 Yes 0, 6 8 Using keycodes to access A Yes 0, 6 8 information Accessing ASCII characters 2 Yes 0 Displaying an explanation of 9 No 0, 6 0, 6 the most recent error message DISPLAYING A MENU You use a Type 0 Help frame to display a menu of the various options available. XyWrite constructs the menu from the information in the Type 0 Help frame and displays the menu on the third line of the screen (below the Prompt line). A Type 0 Help frame can consist of any number of lines. (See Note #1.) The first line contains the label (0, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Since Type 0 Help frames are frequently used as entry points to Help, you may want to use one of the special keywords described in a previous section. Each subsequent line of a Type 0 Help frame contains the keyword you want displayed in the menu, a comma, a space, and the descriptive text you want displayed on the Prompt line whenever the user highlights the keyword on the menu. Note #1 Menu Length. A menu must fit on a single line, across the width of the screen. When XyWrite displays the menu, it adds 2 spaces between each of your keywords. Therefore, when choosing your keywords, make sure the total number of characters combined with the spaces XyWrite adds, does not exceed 80. XyWrite enters keywords in the menu line in the same order they appear in the Type 0 Help frame. The keywords are links to other Help frame types. When the user selects a keyword from the menu, XyWrite displays the Help screen associated with that keyword. For example, the following Help frame creates a main menu for an on-line address list. The label indicates a Type 0 Help frame that can be displayed whether there is something on the screen such as a directory ($D), a file ($F), or a defined block ($B) or whether there is nothing on the screen ($N). XyWrite uses the four lines you see following the label line in the Help frame to construct the menu. {{0$d,$f,$b,$n}} BUSINESS, Vendors, consultants, and agents PERSONAL, Family and friends EMPLOYEE, Employees' extensions and addresses CUSTOMER, Alphabetical list of all customers When the user places the cursor on an item in the menu, XyWrite displays on the Prompt line the descriptive text you associated with that item's keyword in the Help file. For example, when you load the Help file and place the cursor on EMPLOYEE in the Help menu, XyWrite displays "Employees' extensions and addresses." You can link an item on any Help menu to display another menu by including the keyword in another Type 0 Help frame. For example, the following Help frame creates another menu for the BUSINESS category of the on-line address list. When the user selects BUSINESS from the main menu, XyWrite displays another menu with VENDORS, CONSULTANTS and AGENTS as options. {{0business}} VENDORS, Names and addresses of sellers CONSULTANTS, Names and addresses of consultants AGENTS, Names and addresses of agents Since Type 0 Help frames are stored entirely in memory, the index may become very large if you use many in your Help file. To conserve memory, you can substitute Type 6 Help frames for some of the Type 0 frames. Refer to the section, "Displaying a General-Purpose Full Screen" for more information on Type 6 Help frames. DISPLAYING A GENERAL-PURPOSE FULL SCREEN You use a Type 6 Help frame to display a general-purpose full Help screen that provides information on any topic, except function calls. (You use a Type 8 Help frame as described in the next section to display a full Help screen specifically for function calls.) A Type 6 frame can consist of any number of lines (up to 20 displayable lines). The first line contains the label (6 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Each subsequent line contains text you want displayed on the screen. To link the Help frame to another Type 6 frame, include the other frame's keyword in bold somewhere in the text. For an example, select Six from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{6Six}} TYPE 6 FRAME <>INFORMATION, PLEASE <> This Help file contains Help frames that demonstrate many features of XyWrite's Help facility. Which Help screen would you like to see? One Two Three Four Five Six Seven Nine Type A B C D F G The label in the example indicates a Type 6 Help frame that is accessed by "Six." The bold One Two Three Four Five Six Seven Nine Type A B C D F G at the bottom of the Help frame correspond to the keywords of other Help frames in SAMPLE.HLP. The user can display these related screens by placing the cursor on any item and pressing . DISPLAYING FUNCTION CALL INFORMATION You use a Type 8 Help frame to display a full Help screen specifically for function calls (as opposed to commands). The distinction between using a Type 6 Help frame for commands and a Type 8 for function calls is important, because many function calls have the same name as two-letter command abbreviations. For example, the abbreviation for the Extra Leading command is EL and the name of the Express Left function call is EL. Therefore, in LONG.HLP the information on the Extra Leading command is included in a Type 6 Help frame; while the information on the Express Left function call is in a Type 8 Help frame. You construct Type 8 Help frames the same as Type 6 Help frames: A Type 8 frame can consist of any number of lines (up to 20 displayable lines). The first line contains the label (8 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Each subsequent line contains text you want displayed on the screen. To link the Help frame to another Type 8 or to a Type 6 frame, include the other frame's keyword in bold in the text. For an example, select Four from the Sample Menu. When you press F9 as directed by the Type 4 Help screen, XyWrite constructs the displayed screen from a Type 8 Help frame in SAMPLE.HLP with the following label: {{8XC}} The label in the example indicates a Type 8 Help frame that is accessed by "XC." You use a Type 8 Help frame in connection with a Type 4 Help frame to display information about function calls that are mapped to keys. However, some function calls are not mapped to keys. In that case, you can use a Type D Help frame in connection with a Type 8 to display the information. A Type D Help frame is similar to a Type 8, except that it can only be linked to a Type 8 Help frame. A Type D frame can consist of any number of lines (up to 20 displayable lines). The first line contains the label (D followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Each subsequent line contains text you want displayed on the screen. To link a Type D Help frame to a Type 8, include the Type 8 frame's keyword in bold in the text of the Type D frame. For an example, select D from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{DD}} TYPE D FRAMES What Function Calls Mean Select the function call you want to know more about: <>XP XM LB <> The label in the example indicates a Type D Help frame that is accessed by "D." When you select either XP, XM, or LB, XyWrite displays a Type 8 Help frame with the two-letter function call mnemonic as its keyword. For example: {{8XP}} The label in the example indicates a Type 8 Help frame that is accessed by "XP." For more information on Type 8 Help frames, see Tip #5 at the end of this application note. EXECUTING COMMANDS AND PROGRAMS You use either a Type 1 or a Type 5 Help frame to perform either of these functions: * executing programs * inserting text in a file Note #2 Creating Programs in Help Files. If you want to include a program in your Help file, create the Help file with the NEP (New Program) command. Always use the CAP (Call Program) command to call the Help file. Use the Scroll Lock key as described in Chapter 5 of the XyWrite III Plus Reference Guide. Refer to the Guide for more information on creating programs. The first line of either a Type 1 or a Type 5 Help frame contains the label (1 or 5 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. The difference between Type 1 and Type 5 Help frames is the number of displayable lines. A Type 1 frame contains one displayable line whereas a Type 5 frame can contain up to twenty. (Another difference between Type 1 and Type 5 Help frames is that Type 5 Help frames are not stored in memory as Type 1 Help frames are.) Note #3 Type C Help Frames. Type C Help frames are identical in function to Type 1 frames, except they do not load into memory. If necessary, you can include underlined areas in the display where the user enters text. You can include a variable (VA) setting or a default setting in an underlined area to include a value in the screen display. For example, the following displays the name of the current file: The current file is: $fi . --------------------------- (in MDUL) Note #4 Automatically Including Text in Underlined Areas. You can place text (other than a variable) in the underlined areas to act as a prompt to the user. Leave a single blank space before the text so that XyWrite does not interpret the first two letters as a variable. If necessary, the user can press F5 to clear the underlined area. Refer to the XyWrite III Plus Reference Guide for more information on VA and default settings. If you do not want to display a screen, simply leave the second line of the Help frame blank; XyWrite will automatically execute the contents of the third line when the user enters the keyword. The content of the executable lines depends on the function you want the Help frame to perform. If you want to insert the text into an open file, start the line with an ASCII 1 character. If you want to execute a program, start the line with an an ASCII 2 character. If you are using a Type 1 or a Type C Help frame, you can indicate that the information is to be entered on the command line; do NOT start the line with either an ASCII 1 or an ASCII 2 character. XyWrite enters the entire third line on the command line if it does not begin with either ASCII character. Note #5 Executable Line Length. Executable lines can wordwrap. An executable line begins with either an ASCII 1 or an ASCII 2 character and ends at the carriage return. You can have the text the user enters (from the underlined areas) automatically made a part of the executable line by using variables %1 indicates the first underlined area, %2 indicates the second underlined area, and so on. The numbering of the underlined areas starts at the upper left corner and continues from left to right on each line in turn. Do not use the character % on an executable line of a Type 1 or a Type 5 Help frame except to indicate that the number that follows relates to a specific underlined area. For an example, select One from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{1One}} New file: <> <> In window <>$wn <> {ASC-2}<>BC window %2XC <><>BC ne %1XC <> The example Help frame enables the user to create a new file. The label in the example indicates a Type 1 Help frame that is accessed by "One." The variable $wn in the second underlined area includes the current window number when the screen is displayed. The ASCII 2 character preceding the executable line indicates that a XyWrite program follows. The HF command in the program directs XyWrite to execute portions of the program only if a particular underlined area has changed. If the user does not change the window number from the current window, XyWrite skips that part of the program from the HF2 command to the EI (end if) which follows. Note #6 The HF Command. If the user blanks a field, the HF command proceeds as if the field were changed, even if the user retypes the same information. For another example, select Five from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{5Five} TYPE 5 FRAME <><>FRICK & FRACK CONSULTING <><><> Name: <> <> Address: <> <> <> <> City: <> <> State: <> <>ZIP: <> <> Phone: <> <> Use the Tab key to move from field to field. Press Enter when you've filled in all the fields. <> {ASC-2}<>>><>==0>>BC p Open file first, pleaseXC XC BC <><>BF<><><> OP <><>%10D!!%20D<>%30D<>!!%4!!%5!! %60D!!%7*0D0DOP <> The example shows how you can use a HELP file to make a mail merge data file. It simplifies the procedure for the user, who does not need to remember when to use the field separator and when to use the record separator. The user just inputs the data. You can construct the program to make certain that all necessary fields are filled in (the example program demands that field 2 be filled in). The label in the example indicates a Type 5 Help frame that is accessed by "Five." The ASCII 2 character preceding the executable lines indicates that a XyWrite program follows. The program takes care of formatting the data file and handles the problem of addresses of different lengths by using different separators (!!) which have been defined in a printer file. EXECUTING COMMANDS FROM A DIRECTORY You use a Type 7 Help frame to execute commands that require a file name by simply pointing at the name in a directory. Type 7 Help frames are similar to Type 0 Help frames in that they provide a list of options for the user but they have two major differences: * When a Type 7 Help frame is displayed, the user has control over the cursor. The , 1A, and Tab keys still move the cursor across the list of options, but the  and the  keys move the cursor up and down in the displayed directory. * The keywords in Type 7 Help frames are not links to other Help frame types. When the user selects a keyword from the list, XyWrite executes the command that operates on the filename the user has chosen. Also, you construct Type 7 Help frames a little differently than Type 0 Help frames: A Type 7 frame can consist of any number of lines. The first line contains the label (7 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Each subsequent line of a Type 7 Help frame contains the keyword you want displayed in the menu, a comma, the command you want to execute, and a space. (See Note #1.) After the space you can include descriptive text you want displayed on the Prompt line whenever the user highlights the keyword on the menu. For an example, display a directory and select Seven from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{7Seven} Call,Call Call a file Erase,Erase Erase a file Change,CD Change directory More,-Additional things to do with Type 7 frames The label in the example indicates a Type 7 Help frame that is accessed by "Seven." When a directory is displayed, the user can move the cursor to the desired filename; select either CALL, ERASE, or CHANGE; and press to execute the command. You can link Type 7 Help frames by including a keyword preceded by a hyphen (-) after the first comma instead of a command. Use the keyword with the hyphen in the label for the linked Help frame. The last option in the Type 7 Help frame example above, More, links to another Type 7 Help frame with the keyword -Additional. For an example, select MORE from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{7-Additional}} Load,Load Load printer, keyboard, help, spell, hyphen file LDPM,LDPM Load an XPL program to memory only EXECUTING COMMANDS FROM A NUMBERED LIST ON A MENU You use a Type B Help frame to display a list of numbered items of the various options available. The user can press a number (1 through 9) to execute the commands associated with the number. A Type B Help frame can contain 19 lines. The first line contains the label (B, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Up to nine items can be part of the Help screen. Number each line and include a description of the commands XyWrite will execute if that number is selected. Follow the numbered list with the same number of executable lines as there are items in the list. (See Note #5.) The displayable lines correspond to the executable lines the first displayable line describes the first executable line; the second displayable line describes the second executable line, and so on. The content of the executable lines depends on the function you want the Help frame to perform. If you want to insert the text into an open file, start the line with an ASCII 1 character. If you want to execute a program, start the line with an ASCII 2 character. For an example, select B from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{BB}} TYPE B FRAME Executing commands from a numbered list 1 Delete all files on this drive with .TMP extension 2 Delete all files on this drive with .BAK extension 3 Delete all files on this drive with either .TMP or .BAK extension {ASC-2}BC find *.tmpXC <>>><><>BC delCC <>XC <>>>BC abXC BC <><><> {ASC-2}BC find *.bakXC <>>><><>BC delCC <>XC <>>>BC abXC BC<><> <> {ASC-2}BC find *.tmpXC <>>><><>BC delCC <>XC <>>>BC<><><> <>BC find *.bakXC <>>><><>BC delCC <>XC <>>>BC abXC BC <><><> The label in the example indicates a Type B Help frame that is accessed by "B." In the example, the ASCII 2 character preceding the executable lines indicates that a XyWrite program follows. When the Help screen is displayed, the user simply presses 1 to execute the first ASCII 2 line and delete all files on the current drive with a .TMP extension; 2 to execute the second ASCII 2 line and delete all files on the current drive with a .BAK extension; or 3 to execute the third ASCII 2 line and delete all files on the current drive with either a .TMP or a .BAK extension. EXECUTING COMMANDS FROM A LIST OF KEYWORDS You use a Type F Help frame to display a list of various options available. The user simply selects the bold keyword to execute the associated command. Type F frames function like Type 6 frames and Type B frames. As with Type 6 frames, you present a list of bold keywords from which users make selections; but each keyword either executes a program or inserts text, as a Type B frame does. A Type F Help frame can consist of any number of lines (up to 20 displayable lines). The first line contains the label (F, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. Up to 20 displayable lines can follow the label. Start each displayable line with a keyword in bold followed by a description of the command XyWrite will execute if that keyword is selected. Follow the list of keywords (displayable lines) with the same number of executable lines as there are keywords in the list. (See Note #5.) The displayable lines correspond to the executable lines the first displayable line describes the first executable line; the second displayable line describes the second executable line, and so on. The content of the executable lines depends on the function you want the Help frame to perform. If you want to insert the text into an open file, start the line with an ASCII 1 character. If you want to execute a program, start the line with an an ASCII 2 character. For an example, select F from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{FF}} TYPE F FRAME Executing commands from a list of keywords <>TMP<> Delete all files on this drive with .TMP extension <>BAK<> Delete all files on this drive with .BAK extension <>BOTH<> Delete all files on this drive with either .TMP or .BAK extension {ASC-2}BC find *.tmpXC <>>><><>BC delCC <>XC <>>>BC abXC BC <><><> {ASC-2}BC find *.bakXC <>>><><>BC delCC <>XC <>>>BC abXC BC<><> <> {ASC-2}BC find *.tmpXC <>>><><>BC delCC <>XC <>>>BC<><><> <>BC find *.bakXC <>>><><>BC delCC <>XC <>>>BC abXC BC<><> <> The label in the example indicates a Type F Help frame that is accessed by "F." In the example, the ASCII 2 character preceding the executable lines indicates that a XyWrite program follows. When the Help screen is displayed, the user simply selects TMP to execute the first ASCII 2 line and delete all files on the current drive with a .TMP extension; BAK to execute the second ASCII 2 line and delete all files on the current drive with a .BAK extension; or BOTH to execute the third ASCII 2 line and delete all files on the current drive with either a .TMP or a .BAK extension. CALLING A SPECIFIC FILE You use a Type G Help frame to call a separate file stored on disk from a menu. When the user selects the option, XyWrite displays the file as an individual Help screen. (Although the Type G Help frame is stored in memory, the separate file it accesses is stored on disk.) A Type G Help frame consists of two lines. The first line contains the label (G, followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. The second line contains the name of the file. For example, SAMPLE.HLP contains the following Type G Help frame: {{GG}} c:\xy\extra.hlp The label in the example indicates a Type G Help frame that is accessed by "G." When you select G from the Sample Menu, XyWrite displays the file C:\XY\EXTRA.HLP (if you have stored EXTRA.HLP in the \XY directory on the C drive). The first character in the named file must be the Help frame type represented by the file. For example, since C:\XY\EXTRA.HLP contains multiple lines and is used to execute a XyWrite program, the first character is a 5 to indicate a Type 5 Help frame. You can follow the Help frame type on the first line with any formatting commands you want to use for the file. For example, the first line of C:\XY\EXTRA.HLP is 5<><> The second and subsequent lines of the file contain the actual text of the file you want to display. The user can enter the AB (Abort) command to clear the file from the screen. DISPLAYING INFORMATION BASED ON WORDS OR PHRASES You use a Type 3 Help frame to display a line of text on the third line of the screen into which the user can enter a word or phrase to access another frame. When the user presses , XyWrite displays the Help screen that matches the key word or phrase. You establish the information you want displayed by linking any other type of Help frame with keywords in its label by which you think the user may try to access the information. A Type 3 Help frame consists of two lines. The first line contains the label (3 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. The second line contains the text you want displayed on the Ruler line including underlined areas where the user enters text. For an example, select Three from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{3Three}} Which type of Help frame do you want to know more about? <> <> The label in the example indicates a Type 3 Help frame that is accessed by "Three." The user can enter any number, one through nine, or Type A through G to gain quick access to other Help screens in Sample Menu. DISPLAYING KEYBOARD INFORMATION You can use a Type 4 Help frame to display key assignments or a Type A Help frame to display information you associated with a key number. Displaying Key Assignments The Type 4 Help frame activates the XyWrite feature for displaying characters or functions assigned to various keys on the keyboard. You use the Type 4 Help frame in the Help file to indicate the message you want displayed on the Ruler line. A Type 4 frame consists of two lines. The first line contains the label (4 followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. The second line contains the message you want displayed on the Ruler line. For an example, select Four from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{4Four}} A Type 4 Help frame explains a function call. Press F9 to see an example. The label in the example indicates a Type 4 Help frame that is accessed by "Four." When the user presses a character key (A through Z or 0 through 9), XyWrite displays the character on the Prompt line. When the user presses a key that has a function call assigned to it, XyWrite displays the function call on the Prompt line. (For example, when F9 is pressed, XC is displayed.) Since there is a corresponding Type 8 Help frame for the function call, XyWrite also displays that Help screen. In this case, the user can press Esc to return to the Type 4 Help screen and press another key. If you want to call a full-screen frame from a Type 4 frame, use a Type 8 (rather than a Type 6) frame, because Type 8 Help frames display information about function calls. Since it is used only to display key definitions, only one Type 4 Help frame is necessary in any Help file. However, you must have a Type 8 Help frame for each function call you want to explain. Using Keycodes to Access Information The Type A Help frame activates the XyWrite feature for displaying information you associated with a key number. (Keyboard files, such as IBM.KBD, list the numbers for each key.) You use the Type A Help frame in the Help file to indicate the message you want displayed on the Ruler line. Also, you include the information in a Type 8 Help frame that you want displayed whenever the user presses the key. A Type A frame consists of two lines. The first line contains the label (A followed by one or more keywords) enclosed in a pair of double curly braces {{ }}. The second line contains the message you want displayed on the Ruler line. If there is a corresponding Type 8 Help frame for the key the user presses, XyWrite briefly displays it. Each Type 8 Help frame you want to associate with a key has as its keyword the keycode (the number of the key preceded by the + character). For example, if you press F1 (which is key +59), XyWrite displays for a few seconds the Help frame that has the label {{8+59}}. Refer to "Displaying Function Call Information" for more information on Type 8 Help frames. Note #7 Freezing Type 8 Help Frames. Type 8 Help frames called from Type A frames are displayed very briefly. You can freeze the display by including bold text in the Type 8 frames. When the screen is displayed, the user can press Esc to return to the A Help screen and press another key. For an example, select Type A from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{AType A}} Type A Help frames are similar to Type 4. Press F5 for an example. The label in the example indicates a Type A Help frame that is accessed by "Type A." In SAMPLE.HLP, there is a Type 8 Help frame with the label {{8+63}}. When you press F5 (which is key +63), XyWrite displays the Type 8 Help frame. Note the bold space at the top of the displayed Type 8 screen that freezes the display. ACCESSING ASCII CHARACTERS You use a Type 2 Help frame to make ASCII characters available for users. The user can select a character with the cursor to * Display on the Prompt line the ASCII value for the character * Insert the character either into the text at the cursor position or in a command line by pressing either F9 or . A Type 2 Help frame consists of two lines. The first line contains the label (2 followed by one or more keywords) enclosed in a pair of curly braces {{ }}. The second line consists of a string of characters with no spaces between them. XyWrite interprets each character as a menu item on the Ruler line. For an example, select Two from the Sample Menu. XyWrite constructs the displayed screen from the following Help frame in SAMPLE.HLP: {{2Two} $ The label in the example indicates a Type 2 Help frame that is accessed by "Two." When the user positions the cursor on one of the characters in the menu, XyWrite displays its ASCII number on the Prompt line. The user can press either F9 or to enter the character in a file or on the command line. (XyWrite places the character wherever the cursor was located before entering Help.) The user can either select other characters or press Esc to move to a previous screen. DISPLAYING A DETAILED EXPLANATION OF THE MOST RECENT ERROR MESSAGE The Type 9 Help frame activates the XyWrite feature for displaying a full screen of information about the last error message the user received. It is another way to access Help frames by using XyWrite's error coding system. When the user accesses a Type 9 frame, XyWrite displays the Type 6 frame that contains in its label the keyword number associated with the last error message displayed. 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: {{9error}} In the example, the 9 indicates that the Help frame is a Type 9. Error is the keyword associated with the frame. You use a Type 6 Help frame to enter the message you want displayed for one or more errors, and use one or more internal XyWrite error numbers as keywords. Add leading zeros to error numbers less than three digits (for example, 006 or 032). You can scroll through the LONG.HLP file for many of the current error numbers. (In recent versions, all the Help frames that describe errors are grouped under the Type 9 Help frame label.) For an example, select Nine from the Sample Menu. XyWrite displays a Type 6 Help screen that instructs you to set the Default EH=1 and then cause an error. Type: F5default eh=1 Press: F5 Press: F9 Result: Instead of a one line error message, "NO COMMAND" displayed on the Prompt line, XyWrite displays a full Help screen describing the problem. XyWrite constructs the displayed screen from a Type 6 Help frame in SAMPLE.HLP with the following label: {{6011}} In the example label, the 6 indicates that the Help frame is a Type 6 and 011 is the internal number of the NO COMMAND error message. You can have XyWrite automatically display your Error Help screens whenever an error occurs. Use the Default EH=1 to activate the feature; EH=0 to disable it. In that way, XyWrite displays the Error Help frames without going through the Menu. (Although this feature is helpful for beginners, it can slow the performance of more experienced users.) You can also access Error Help frames directly from the keyboard. Refer to the section, "Accessing a Specific Help Screen with One Keystroke," for more information. ACCESSING A HELP SCREEN WITH ONE KEYSTROKE You can access Help frames directly from the keyboard by inserting a Help function call ($0 through $9 or $A through $Z) as a special keyword in the Help frame label. You then assign the Help function call to a key by modifying your keyboard file. Using the example of Type 9 Help frames presented earlier, you could include a special keyword in the label, for example $e, and then assign the $e function to a key to allow the user to access the frame directly: {{9error,$e}} When XyWrite reports an error, the user can press the key that has the $e function assigned to it for an explanation of the error message. If you want to use any of the special keywords ($n, $f, $d, or $b) described in a previous section, you should use them only to designate the conditions under which a menu can be displayed and not use them in the same file as the Help function calls $n, $f, $d, or $b. Refer to the XyWrite Reference Manual for more information on function calls and modifying keyboard files. TWO ADVANCED TECHNIQUES Two techniques you might find helpful when you prepare your menus are creating subroutines and temporarily saving values to a Save/get key. Creating Subroutines A subroutine or subprogram is a set of instructions grouped together under one name that will be executed when the main program requires it. You can create subroutines, using either Type 1, Type C, or Type 5 Help frames, which can reduce the size of your Help file and make it easier to debug your programs. You include one or more Help function calls in your program where you want the instructions in the subroutine carried out. You use the same Help function call as the keyword for the Help frame containing the subroutine. For example, the following is a Type 1 Help frame that includes two subroutines as part of its program. {{1margins}} {ASC-2}$5 $6 The label in the example indicates a Type 1 Help frame that is accessed by "Margins." Since the second line is blank, no text is displayed on the screen and the third line will be executed as soon as the user selects "Margins" from the menu. The third line begins with an ASCII 2 character to indicate that a XyWrite program follows, which in this case is a simple program containing two subroutines. The Help frame containing the first subroutine appears as follows: {{1$5}} {ASC-2}BC lm 5XC The label in the example indicates a Type 1 Help frame with the Help function call $5 as a keyword. There are no displayable lines and the third line begins with an ASCII 2 character to indicate that a XyWrite program follows, which in this case sets the left margin to position 5. The Help frame containing the second subroutine, which sets the right margin to position 62, is similar: {{1$6}} {ASC-2}BC rm 62XC When the user selects "Margins" from the menu, XyWrite immediately embeds both an LM and an RM command in the text. Temporarily Saving Values You can temporarily save the information a user enters into the underlined areas of a Type 1 or a Type 5 Help screen. You do this by moving the information to a Save/Get key either the ordinary Save/Get keys (A-Z, 0-9) which users access with the Alt key or the temporary Save/Get keys (000-999) which are saved only while the program is running. You use the SV (Save String) command to save the contents of a specific underlined area. For example, the following saves the contents of the second underlined area (%2) to temporary Save/Get key 07: <> As another example, the following Type 1 Help frame saves the contents of the first underlined area to Save/Get key #1: {{1B}} Save this text in Save/Get 1 <> <> {ASC-2}<>BC The user can retrieve the information by pressing Alt 1 as often as necessary until quitting XyWrite. TIPS 1. You can include formatting commands (such as Flush Center, Tabs, etc) within the text of a Help frame to indicate how you want text to appear on the Help screen. The triangle that represents an embedded command appears in your Help file, but does not display on the screen. 2. When formatting either the entire Help file or an individual Help frame, keep in mind that XyWrite automatically displays a border around many types of Help screens. 3. Although you can use Mode commands to add emphasis to Help screen text, you should avoid using bold mode <> except when you want to link another Help screen. You should also avoid using underline mode <> in Type 1 and Type 5 Help frames except when you want to leave space for user input. 4. You can use the Box Colors (BX) setting in your printer file to define the colors of Help screen borders and the color of the Prompt line. 5. You do not have to list Help frames in any particular order; but if you use the same keyword to label two different Help frames, XyWrite uses the one that appears first in the Help file. Be cautious about any Type 6 Help frames that have abbreviated commands as keywords that XyWrite could interpret as function calls. In this case, the Type 6 Help frame describing the command should appear before the Type 8 Help frame describing the function call. For example, in LONG.HLP the Type 6 Help frame describing the Extra Leading command (where EL is one of the keywords) appears before the Type 8 Help frame describing the Express Left function call (where EL is also one of the keywords). 6. When the user selects a keyword that does not have a corresponding Help frame, you can have XyWrite call a wildcard frame (such as {{8*}}). For example, LONG.HLP contains the following Type 8 Help frame: {{8*,end}} This function is not known to the Help file. For a list of all of the valid 2 letter functions, press Return. FUNCTIONS The label indicates a Type 8 Help frame. Since there is a wildcard instead of a keyword, XyWrite displays the text when it cannot find any other match for the keyword the user selects. Note #8 Wildcard Keywords. Since wildcard keywords match anything, only use them in the last frame in the Help file.