Chapter 9

CREATING MENU SYSTEMS

You've come to appreciate WordPerfect's systems of menus, where your command choices are spelled out for you every step of the way. Two of WordPerfect's features, macros and merges, can be used to build a system of custom menus. Your own menus can be used as a guide for yourself or others through the steps of some murky task, or they can serve for you as helpful reminders of how to complete some a complicated word processing chore.

There are four approaches to building your own custom menus systems:

Most menu systems are composed of two parts, an "engine" and the actual menu contents.

When constructed properly, your menu engines can used over and over again to fill in for any application you desire. Once you have the basics down, you'll soon be creating menus for every occasion, from preparing mailing labels to sorting lists to editing and printing documents. In addition, Chapter 19, "For Pros Only: Advanced Topics," includes several menu enhancement macros.

This chapter explains how to create and use custom menus. Several approaches to building menu systems are included, along with basic menu engines you can use for your own applications. This chapter serves mainly to present the technique of constructing menu systems within WordPerfect. Several actual examples of completed menu systems, for a variety of useful applications, appear in Part Two of this book. Chapter 18, "Macro Strategies," provides several unique "menu-making" macros. These auto-generation macros actually create menu macros for you.

 

GENERATING MENUS USING THE MERGE FEATURE

A basic approach to making menus is WordPerfect's merge feature. You may prefer to construct your menus using merges if you are in a hurry and don't have time to write and debug an entire menu macro. Menu merges use a single primary document that includes the menu text as well as codes for branching off to one of any number of macros. Each macro then completes the task, or calls up another menu. A secondary merge document is not required.

Here's one one approach to creating a menu list for easily accessing previously written macros.

In the example, the menu lists the macros MACRO1, MACRO2, MACRO3, and MACRO4. A description beside the name reminds you what the macro does. The {CHAIN MACRO} code starts with a macros\ subdirectory (where the macros are kept), freeing you from typing it in yourself. If your macros are in the same directory as WordPerfect, or are in another directory, edit the {CHAIN MACRO} prefix as necessary.

Write the menu using Tab stops to indent. You can experiment later with the spacing around the text so that the menu better fills the screen. Once the menu is finished, you must remove the Tab stops and replace them with spaces, or the menu items won't be formatted properly. This can easily be done by moving the cursor to the top of the document and using the Replace function to automatically exchange the Tabs with five empty spaces. Use Reveal Codes or Search to check for errant [Tab] codes.

Save the list as MENUTEST.MRG, or some other descriptive name, and clear the screen. Then,

Key Sequence What it Does
1. [Ctrl]-[F9] Opens Merge/Sort menu.
2. MSelects Merge option.
3. menutest.mrg
[Enter]
Enters MENUTEST.MRG as the primary merge file.
4. [Enter] Enters a blank as the secondary merge file.

The menu list will then scroll onto the screen, and the prompt at the bottom will read

Enter a macro to use: macro\

Type one of the macro names (upper or lower case) and press [Enter]. That macro will then be executed. If you want the macro to loop back to the menu, repeat the steps outlined in the key sequence above at the end of each macro.

For your convenience, the same MENUTEST.MRG merge menu is provided on the Applications Disk. It is located in the MISC subdirectory.


Helpful Merge Menu Tips

Examples:

{CHAIN MACRO}A:{KEYBOARD}

Finds the named macro on drive A:, such as A:ENVELOPE or A:BOXDRAW.

{CHAIN MACRO}{KEYBOARD}mrg 

Finds the named macro that ends with "mrg," such as "MACMRG" and "MENUMRG."

{CHAIN MACRO}new{KEYBOARD}mac  

Finds the named macro that starts with "new" and ends with "mac," such as NEW1MAC, NEW2MAC, and so forth.

If you can't display all of the menu choices in one screen, try single spacing or adding an option that calls a second menu.


Converting 5.0 Merge Menu Documents

WordPerfect 5.1 can run merges (including merges that provides on-screen menus) that were originally created in version 5.0. These merge documents use the older fashion control character merge codes -- ^O for {PROMPT}, ^G for {CHAIN MACRO}, and others. WordPerfect 5.1 also offers a handy built-in conversion feature that exchanges 5.0 merge codes for those used in 5.1. Whenever possible, you'll want to convert your old 5.0 merge documents; WordPerfect 5.1 executes merges faster when they use the updated commands codes.

To convert the merge codes in a 5.0 merge document:

  1. Retrieve the document into WordPerfect 5.1.
  2. Press [Ctrl]-[F9].
  3. Press C (or 3) for Convert Old Merge Codes.
  4. After conversion is complete, resave the document.

If you need to keep the old merge document, be sure to provide a new name for the conversion.

You can also manually convert your old 5.0 merge documents, making alterations and improvements as you go. WordPerfect 5.1 retains all the merge capabilities of 5.0, but adds many more. The following is a list of merge codes used in version 5.0 (and earlier), and their WordPerfect 5.1 counterparts that are regularly used to produce on-screen menus.

5.0 Command 5.1 Command
^C {KEYBOARD}
^G {CHAIN MACRO}
^O {PROMPT}
^Q {QUIT}
^U {REWRITE}


Avoiding Superfluous Characters and Codes

Extra spaces are often used to format merge message prompts (as shown in the examples above). You should avoid spaces and all other printing and non-printing characters and codes within the rest of the primary merge document. WordPerfect passes along any formatting codes, including spaces, tabs, hard returns, and so forth, that it encounters in a non-message portion of the primary merge document.

If extra characters, such as blank spaces or hard returns, appear in your document after running a menu merge, carefully inspect the primary merge document. Look for spaces between codes, such as

{CHAIN MACRO}  {KEYBOARD}

The spaces between the {CHAIN MACRO} and {KEYBOARD} commands will be passed to your document, and may disturb the work you're doing.


Macro and Merge Compatibility

Merge menus have more flexibility in versions 5.0 and 5.1 of WordPerfect than they did in the earlier 4.2 release: the program can now execute macros and merges simultaneously. In the old 4.2 version, starting a merge in the middle of a macro would cancel the macro.

If you tried to used macros and merges together in version 4.2, but were frustrated at the limitations, you owe it to yourself to try again. Note, however, that WordPerfect will still stop the definition of a new macro when you start a merge from the keyboard. The only way to program a merge operation in a macro is to do it in the macro editor.

 

IN REVIEW: WORKING WITH MACROS

Several of the examples in this chapter require you to create a macro from within the macro editor. Chapter 3 detailed the steps of creating and editing a macro, but let's go over the basic procedure here.

To write a macro in the macro editor, you must first create a macro template -- a macro file that contains no codes or commands. Once you've made the template, you can go back and edit it.

Key Sequence What it Does
1. [Ctrl]-[F10] Starts macro definition.
2. {macro name}
[Enter]
Names the macro.
3. {macro description}
[Enter]
Describes the macro (optional).
4. [Ctrl]-[F10] Finishes the macro definition.
5. [Ctrl]-[F10] Starts macro definition again.
6. {macro name} Re-enters macro named you used previously.
7. E Opens editing window showing nearly blank macro editor box, reading for editing.

WordPerfect starts all macros with a {DISPLAY OFF} code. In many cases, you can keep it. Otherwise, position the cursor at the code and press the [Delete] key. To start write the macro after the {DISPLAY OFF} code, use the cursor keys to move past it. Press the [Enter] key to step down a line. Remember: Putting instructions on separate lines makes writing and "debugging" (fixing) the macro easier, and does not actually produce a hard return when the macro is executed.

To enter a macro command (text in all caps and surrounded by braces), press [Ctrl]-[Page Up] and choose the desired command one from the list. DO NOT type macros commands from the keyboard. WordPerfect will not interpret them as commands.

Other tips:

 

GENERATING A ONE-LINE MENU PROMPT WITH MACROS

Most of the time, you need to display only a single line of menu choices. This is easily accomplished with the merge feature, as you learned in the previous section, or with macros. The macro approach provides more flexibility and capabilities, but is harder to program because it requires the use of many of WordPerfect's advanced macro commands.

One-line prompt menus are the same kind that WordPerfect itself offers, so they are a familiar sight to WordPerfect users. Depending on your requirements, you can write a macro that presents just a single set of choices, or a macro that offers menu levels: pressing an option in one menu drops you down to another menu level, and so forth. Both kinds are detailed here.


Single Level One-Line Menu Prompt

The single level one-line menu prompt displays one line of choices, such as:

 1 Spell Check Document  2 Save Document  3 Quit WordPerfect

This sample menu presents three numbered choices. All three activities are built into one macro or, the menu macro nests or chains to other macros that perform the desired functions.

A menu such as this one is a good example of conditional branching. The macro branches off to a specific portion of the macro depending on the selection you make. Although there are many ways to create conditional branches in macros, perhaps the most straightforward approach is one that uses the {CASE} command.

Here's the basic structure of single level, one-line menu macro:

  1. Display menu line and wait for input.
  2. Use {CASE} to test result of user input.
  3. Branch to indicated label within macro for each of the possible choices of the menu.

The routine within each label can perform the function indicated in the menu, or it can chain to another macro. Using the previous one-line menu example, such a macro could be written as:

1.  {CHAR}1~
    1 Spell Check Document  2 Save Document  3 Quit WordPerfect~
2.  {CASE}{VAR 1}~
    1~spell~
    2~save~
    3~quit~
    ~
    {ELSE}{QUIT}
3.  {LABEL}spell~
    {Spell}d
    {QUIT}
4.  {LABEL}save~
    {Save}
    {QUIT}
5.  {LABEL}quit~
    {Exit}ny
    {QUIT}

Note that the {CASE} command has an extra tilde at the end. This terminates the {CASE} command itself. The {ELSE} and {QUIT} commands after the last tilde of the {CASE} structure indicates what happens if the user types something other than 1, 2, or 3. The {ELSE} command is optional.

A practical application of a single level one-line menu is providing an interactive structure to sort a table. The table is separated into records by hard returns and into fields by tabs. New tab stops were chosen at 1.5 inch increments to accommodate the design of the table. The SORTMAC.WPM macro listed below works in such a way that the list can be any size, but it can be the only thing on the page. The SORTMAC.WPM macro is provided on the Applications Disk.

1.  {DISPLAY OFF}
    {Home}{Home}{Home}{Up}
    {Down}{Down}
2.  {Block}{Home}{Home}{Down}
3.  {Merge/Sort}
4.  {LABEL}startsort~
    {CHAR}1~{^R}Sort by: 1 Last Name; 2 Department; 
    Donation Amount.{^S}~
    {CASE}{VAR 1}~
    1~name~
    2~dept~
    3~amt~
    ~
5. {PROMPT}Press 1, 2, or 3 only; or press F1 twice to quit.~
   {BELL}
   {WAIT}15~
   {GO}startsort~
6. {LABEL}name~  Ka1{Exit}P
   {DISPLAY ON}{QUIT}
7. {LABEL}dept~
   Kn3{Exit}P
   {DISPLAY ON}{QUIT}
8. {LABEL}amt~
   Kn4{Exit}P
   {DISPLAY ON}{QUIT}

Step 4 comprises the "thinking" portion of the macro. You can adapt the macro to just about any application you desire by changing the steps before and after it. For example, let's suppose you store your documents in three different subdirectories on your hard disk. Instead of remembering and typing the subdirectory name, the following macro does it for you. Save this macro as ALTS.WPM (for save), and it will automatically prompt you for the correct subdirectory. You press either 1, 2, or 3, then the name of the document. The macro makes sure that the file is always socked away in the right place.


SAVESUB.WPM (provided on the Applications Disk)

{LABEL}startsave~
{CHAR}1~{^R}Save in: 1 Business Letters; 2 Forms; 3
Correspondence{^S}~ 
{CASE}{VAR 1}
  1~buslets~
  2~forms~
  3~corr~
  ~
{PROMPT}Press 1,2, or 3 only; or press F1 twice to quit~
{BELL}{WAIT}15~
{GO}startsave~

{LABEL}buslets~
{TEXT}0~Enter the name of the file to save~
{Save}buslets{VAR 0}{Enter}{QUIT}

{LABEL}forms~
{TEST}0~Enter the name of the file to save~
{Save}forms\{VAR 0}{Enter}{QUIT}

{LABEL}corr~
{TEXT}0~Enter the name of the file to save~
{Save}corres\{VAR 0}{Enter}{QUIT} 

The macro is simple and straightforward. When it starts, it asks which subdirectory you want to save to. Notice that the choices in the menu can be in full English, not the eight-or-less character cryptic words often given to subdirectory names (in this example, the actual names of the subdirectories are "buslets," "forms," and "corres"). The macro checks your entry, then branches off to the corresponding label.


Multiple Level One-Line Menu Prompt

Designing a multiple level menu simply involves adding more choices after the first selection has been made. The macro provided here is a test engine, offering two levels with three choices each. When the macro ends, it prints out the selections you made. In a real application, you'd substitute them for actual WordPerfect commands.

1. {CHAR}0~Main.  Enter 1, 2 or 3.~
   {CASE}{VAR 0}~
    1~sub1~
    2~sub2~
    3~sub3~
    ~
    {QUIT}
2.  {LABEL}sub1~
    {CHAR}0~Sub 1.  Enter 1, 2, or 3.~
    {IF}{VAR 0}=1~Choice 1, sub 1{QUIT}
    {ELSE}
    {IF}{VAR 0}=2~Choice 2, sub 1{QUIT}
    {ELSE}
    {IF}{VAR 0}=3~Choice 3, sub 1{QUIT}
    {ELSE}
    {END IF}{END IF}{END IF}
    {QUIT}
3.  {LABEL}sub2~
    {CHAR}0~Sub 2.  Enter 1, 2, or 3.~
    {IF}{VAR 0}=1~Choice 1, sub 2{QUIT}
    {ELSE}
    {IF}{VAR 0}=2~Choice 2, sub 2{QUIT}
    {ELSE}
    {IF}{VAR 0}=3~Choice 3, sub 2{QUIT}
    {ELSE}
    {END IF}{END IF}{END IF}
    {QUIT}
4.  {LABEL}sub3~
    {CHAR}0~Sub 3.  Enter 1, 2, or 3.~
    {IF}{VAR 0}=1~Choice 1, sub 3{QUIT}
    {ELSE}
    {IF}{VAR 0}=2~Choice 2, sub 3{QUIT}
    {ELSE}
    {IF}{VAR 0}=3~Choice 3, sub 3{QUIT}
    {ELSE}
    {END IF}{END IF}{END IF}
    {QUIT}

To design a macro for a specific application, map out the functions you want to provide and how the options are nested within one another. For example, in a two-tiered menu system that allows you to save, retrieve, or look at documents, you might provide a choice of locating the documents in the current directory of your hard disk, or in two other subdirectories.

Level 1
	Save
	Retrieve
	Look
Level 2
	Main Directory
	Macros Subdirectory
	Text Subdirectory


FILER.WPM (provided on the Applications Disk)

1.  {CHAR}key~Enter Choice: 
    1 Save File; 2 Retrieve File; 3 Look at File  ~
    {CASE}{VARIABLE}key~~
    1~save~
    2~retrieve~
    3~look~
    ~
    {QUIT}
2.  {LABEL}save~
    {TEXT}name~Enter the name of the document  ~
    {CHAR}saveIn~Save file to: 1 Current Dir; 2 Macros Dir; 
    3 Text Dir  ~
    {IF}{VARIABLE}saveIn~=1~
      {Save}{VARIABLE}name~{Enter}{QUIT}
    {ELSE}
      {IF}{VARIABLE}saveIn~=2~
        {Save}macros\{VARIABLE}name~{Enter}{QUIT}
    {ELSE}
      {IF}{VARIABLE}saveIn~=3~
        {Save}text\{VARIABLE}name~{Enter}{QUIT}
    {END IF}{END IF}{END IF}
3.  {LABEL}retrieve~
    {CHAR}dir~Enter directory: 1 Current; 2 Macros; 3 Text  ~
    {TEXT}name~Enter the name of the file  ~
    {IF}{VARIABLE}dir~=1~
       {Retrieve}{VARIABLE}name~{Enter}{QUIT}
    {ELSE}
    {IF}{VARIABLE}dir~=2~
        {Retrieve}macros\{VARIABLE}name~{Enter}{QUIT}
    {ELSE}
        {IF}{VARIABLE}dir~=3~
            {Retrieve}text\{VARIABLE}name~{Enter}{QUIT}
    {END IF}{END IF}{END IF}

4.  {LABEL}look~
    {CHAR}dir~Enter directory: 1 Current; 2 Macros; 3 Text  ~
    {TEXT}name~Enter the name of the file  ~
    {IF}{VARIABLE}dir~=1~
	{List}{Enter}n
        {VARIABLE}name~
        {Enter}{Enter}
        {QUIT}
    {ELSE}
        {IF}{VARIABLE}dir~=2~
        {List}{Del to EOL}macros{Enter}n
        {VARIABLE}name~
        {Enter}{Enter}
        {QUIT}
    {ELSE}
        {IF}{VARIABLE}dir~=3~
        {List}{Del to EOL}text{Enter}n
        {VARIABLE}name~ 
        {Enter}{Enter}
        {QUIT}
    {END IF}{END IF}{END IF}

 

GENERATING MULTIPLE-LINE MENU PROMPTS WITH MACROS

You can easily expand the one-line menu prompt to fill all 25 lines of the standard IBM PC display. When defining the {TEXT} or {CHAR} message for the menu, end each line (except the last) with an {Enter} character, such as:

{CHAR}1~What do you want to do next?{Enter}
1   Quit WordPerfect{Enter}
2   Start another document{Enter}
3   Spell check this document{Enter}
4   Save this document{Enter}
5   Append another document to the end of this one~

Lingering Menu Lines

One problem with multiple-line menus is that the lines can remain, even after you make a selection and the macro stops. If you subsequently edit or scroll through the document, some or all of the menu lines may "float" into the document. This text is not really a part of the document, and disappears after a while, but it be an annoyance.

You can eliminate this problem by adding a {DISPLAY OFF}{DISPLAY ON} pair immediately after the multiple line menu. If you're going to always use the menu at the main document screen, you can alternatively use two {Screen} codes to clear the message text. Either method causes the display to momentarily blank out, and has the effect of erasing the menu text.

Note that the "phantom" message lines can occur in any type of macro that displays more than one line text of text, as well as a message that is placed on a line other than the status line (line 25).

 

ADDING MNEMONICS

For most all of WordPerfect's menus you can select a number of letter to select an option or command. The letters are mnemonics, and can be helpful in reminding you which keys to press. Many WordPerfect users "think" in terms of command sequences as letters, rather than numbers.

For example, when you choose the Setup menu, you can press 5 or K to select the Keyboard command. It's easier to remember that K, rather than the number 5, stands for Keyboard.

With macros, you can provide menus with mnemonic commands, and make your menus look and act just like WordPerfect. All it takes is highlighting the message text at the right spots (to indicate the mnemonic character to use), and to add the appropriate keys to the {CASE} or {IF} statement that performs the branching operation.

Because mnemonics requires that you test for both upper and lower case letters, it's far easier to use a {CASE} construction for branching. Otherwise, your macros will become littered with dozens of {IF} statements, with each one testing for a different number or letter. WordPerfect normally uses bold to indicate the keys (number and letter) you press at any menu (you can change this with the Setup key). In a macro, use the {^]} and {^\} attribute codes to turn bold on and off.

For example, to create a menu line that looks like this when the macro is played back:

 1 Spell Check Document  2 Save Document  3 Quit WordPerfect

Enter these bold on/off codes (for the sake of clarity, each menu item is shown on a different line, with spaces (shown as a mid-line dot) between the items; when the macro is run, all three items will appear on the same line):

 {^]}1{^\} Spell {^]}C{^\}heck Document  
 {^]}2 S{^\}ave Document  
 {^]}3 Q{^\}uit WordPerfect

You can use these bold on/off attributes with {TEXT}, {CHAR}, {PROMPT}, {INPUT}, and {SYSTEM PROMPT} messages. Attribute codes can be used only in macros. They have no affect (or cause an error) when used in merge prompts and messages.

The {CASE} structure for this three-item menu includes the numbers and letters for each choice.

{CASE}{VAR X}~
  1~spell~
  C~spell~
  c~spell~
  2~save~
  S~save~
  s~save~
  3~quit~
  Q~quit~
  q~quit~
  ~

Note that:

{CASE}{VAR X}~
  1~spell~  C~spell~  c~spell~
  2~save~   S~save~   s~save~
  3~quit~   Q~quit~   q~quit~
  ~

Use the tab key to separate the items in the {CASE} structure. Don't format the macro using the spacebar.

 

PLACING MENU PROMPTS

Recall from Chapter 5, "Making More of Macros," you can precisely control the location of messages on the screen using cursor positioning codes. For example, the {Up} code placed before the message text, as in

{CHAR}1~{Up}Your message here~

Writes the messages one line above the status line. Add more {Up} codes and you move the message up more lines. You can use a series of {Up} codes to prevent multiple-line menus from scrolling the document text when you call the menu macro.

For example,

{CHAR}1~
{Up}{Up}{Up}{Up}{Up}What do you want to do next?{Enter}
1   Quit WordPerfect{Enter}
2   Start another document{Enter}
3   Spell check this document{Enter}
4   Save this document{Enter}
5   Append another document to the end of this one~

starts the first line of the up five spaces from the bottom of the screen. Each subsequent line of the menu is placed one line below. Line 5, "Append another document..." appears on the status line. When this menu is run, any text that is in the document screen remains where it is. This makes the menu less obstrusive, and helps prevent panic when used by those new to WordPerfect.

One of the handiest cursor positioning codes is {Del to EOP}, which is entered into a macro by pressing [Ctrl]-[Page Down]. Used in a multiple-line menu, the code temporarily clears the screen (but does not delete any text in the document), and starts the menu at the top of the screen.

{CHAR}1~{Del to EOP}What do you want to do next?{Enter}
1   Quit WordPerfect{Enter}  
2   Start another document{Enter}
3   Spell check this document{Enter}
4   Save this document{Enter}
5   Append another document to the end of this one~

For exact placement of menus and other message text, use the {^P} cursor position code, as described in Chapter 5. Several macros throughout Part Two of this book use the {^P} code to produce "pop-up" windows and menus. As this is an advanced topic, Chapter 18, "Macro Strategies," provides additional information on getting the most from the {^P} code.

 

GENERATING A FULL-PAGE MENU WITH MACROS AND TEMPLATE

If you have a complex menu system, or just don't care to create the menu in a macro, you can use a template document that displays the actual menu. A macro is still used to detect which menu option is selected, and to perform the required functions associated with that option.

WordPerfect's two document screens make it fairly easy to provide full-page menus. You write and edit in Doc 1, and the menus are displayed in Doc 2. A macro automatically switches between the two and monitors your choices. The basic full-page menu macro consists of only a few lines, and you can easily modify it to work with any application. I'll show you how to construct a basic "trainer" macro for testing the operation of full-page menus, then show you how to convert it to a useful "what-do-you-want-to-do-next" menu that's ideally suited for helping newcomers to WordPerfect master the program.


Writing the Basic Engine

Create the menu engine entirely in the macro editing window.


FULLPG1.WPM (provided on the Applications Disk)

1.  {DISPLAY OFF}
2.  {LABEL}loop~
    {Switch}
    {Home}{Home}{Up}
    {Retrieve}MENU1.TXT{Enter}
3.  {LABEL}start~
    {DISPLAY ON}
    {CHAR}3~Type a number for your choice  ~
4.  {CASE}{VAR 3}~
      1~one~
      2~two~
      3~three~
      4~four~
      5~five~
      6~six~
      7~seven~
      ~ 5.  
    {PROMPT}{^R}  Press a number from 1 to 7.  {^S}~
    {BELL}
    {WAIT}15~
    {GO}start~
6.  {LABEL}one~
    {Switch}
    You pressed 1  {Enter}
    {GO}repeat~

    {LABEL}two~
    {Switch}
    You pressed 2  {Enter}
    {GO}repeat~

    {LABEL}three~
    {Switch}
    You pressed 3  {Enter}
    GO}repeat~

    {LABEL}four~
    {Switch}
    You pressed 4  {Enter}
    {GO}repeat~

    {LABEL}five~
    {Switch}
    You pressed 5  {Enter}
    {GO}repeat~

    {LABEL}six~
    {Switch}   
    You pressed 6  {Enter}
    {GO}repeat~

    {LABEL}seven~
    {Switch}
    You pressed 7  {Enter}
    {GO}repeat~ 

7.  {LABEL}repeat~
    {WAIT}15~
    {Switch}
    {GO}start~

IMPORTANT NOTES: The macro expects the test document (MENU1.TXT, included on the Applications Disk) to be in your current directory. If you start the macro and WordPerfect reports a file not found message, you must do ONE of the following:

TO STOP THE MACRO, PRESS THE CANCEL KEY ([F1]). After running the macro, be sure to clear both documents (Doc 1 and Doc 2).

The macro assumes that Doc 2 is empty. If it's not, then WordPerfect will attempt to append the MENU1.TXT file to the current document. The macro is not built to test when Doc 2 is is not empty, nor handle the prompt WordPerfect provides when you are about to add a document to existing next. Running this macro with text in Doc 2 will cause it to fail.

When you run the FULLPG1.WPM macro, the screen temporarily blanks out, then shows you the menu list. Pressing a number key from 1 through 7 precipitates the proper response from the macro. You can be sure that the macro works properly when it echos the correct number you pressed. Because this macro loops back onto itself, it will go on forever until you cancel out of it. When you are tired playing with the macro, press the [Cancel] key. Clear both document screens when you're done.


Creating a Mini Menu Application

Let's take the basic engine and turn it into something useful. This macro offers four options (you can provide more, if you wish):


FULLPG2.WPM (provided on the Applications Disk)

1.  {DISPLAY OFF}
2.  {Switch}
    {Home}{Home}{Up}
    {Retrieve}MENU2.TXT{Enter}
    {DISPLAY ON}
3.  {LABEL}start~
    {CHAR}3~Type a number for your choice  ~
4.  {CASE}{VAR 3}~
      1~one~
      2~two~
      3~three~
      4~four~
      ~
5.  {PROMPT}{^R}  Press a number from 1 to 4  {^S}~
    {BELL}
    {WAIT}15~
    {GO}start~
6.  {LABEL}one~
    {Exit}nn
    {Switch}{Exit}ny{Exit}ny
    {QUIT}

    {LABEL}two~
    {Exit}nn
    {Switch}{List}{Enter}
    {QUIT}

    {LABEL}three~
    {Exit}nn
    {Switch}{Exit}nn
    {QUIT}

    {LABEL}four~
    {Exit}nn
    {Switch}{Home}{Home}{Up}
    {Spell}D
    {QUIT}

Note that options 1 and 3 can result in disaster if they are inadvertently chosen. It's good practice, when providing an automatic menu system that deletes a file, exits the program, or otherwise might cause great disruption of work, to offer a last-ditch check to be sure that the correct option has been chosen. It's fairly easy to provide a fail-save net within macros.

Change Step 6 to:

6.  {LABEL}one~
    {Exit}nn
    {Switch}
    {CALL}fail safe~
    {Exit}ny{Exit}ny
    {QUIT}  

Change Step 8 to:

8.  {LABEL}three~
    {Exit}nn
    {Switch}
    {CALL}fail safe~
    {Exit}nn
    {QUIT}

Add the "fail-safe" subroutine with this additional step:

{LABEL}fail safe~
{BELL}
{CHAR}2~{^R}Are you sure you want to exit WordPerfect or clear
  the screen?(Y or N){^S}~ 
{IF}"{VAR 2}"="Y"~
  {RETURN}
{ELSE}
{IF}"{VAR 2}"="y"~
  {RETURN}
{ELSE}
  {QUIT}
{END IF}{END IF}

The IF...ELSE statement checks to see if you press Y or y any other character reprompts for another choice. Note that there are two {IF} statements; one for capital Y, and one for lower-case y. This is required because {IF} {as well as all other macro commands that use text as an argument) is case sensitive.


Canceling Out

What if you don't want to choose any of the options? You need a way to cancel out of the macro gracefully. Add an {ON CANCEL} exception command at the beginning of the macro, as well as a cancel routine at the end. With this extra bit of code, you can press the Cancel key ([F1]), and the macro will take care of cleaning up after itself.

Add this at the very beginning of the macro:

 {ON CANCEL}{GO}cancel~~

Add this at the end of the macro:

{LABEL}cancel~
{Exit}nn
{Switch}

Don't forget the double tildes after the {ON CANCEL} command. One tilde is for the {ON CANCEL} command itself, and the other is for the {GO} command.


The Completed Macro

Here is the complete menu macro, with the fail safe and on cancel subroutines. This macro is supplied on the Applications Disk as FULLPG3.WPM.


FULLPG3.WPM (provided on the Applications Disk)

{ON CANCEL}{GO}cancel~~
{DISPLAY OFF}
{Switch}
{Home}{Home}{Up}
{Retrieve}MENU2.TXT{Enter}
{DISPLAY ON}

{LABEL}start~
{CHAR}3~Type a number for your choice  ~

{CASE}{VAR 3}~
   1~one~
   2~two~
   3~three~
   4~four~
   ~
{PROMPT}{^R}  Press a number from 1 to 4  {^S}~
{BELL}
{WAIT}15~
{GO}start~

{LABEL}one~
{Exit}nn
{Switch}
{CALL}fail safe~
{Exit}ny{Exit}ny
{QUIT}

{LABEL}two~
{Exit}nn
{Switch}{List}{Enter}
{QUIT}

{LABEL}three~
{Exit}nn
{Switch}
{CALL}fail safe~
{Exit}nn
{QUIT}

{LABEL}four~
{Exit}nn
{Switch}{Home}{Home}{Up}
{Spell}D
{QUIT}

{LABEL}fail safe~ {BELL}
{CHAR}2~{^R}Are you sure you want to exit WordPerfect or clear the 
screen?  (Y or N){^R}  ~
{IF}"{VAR 2}"="Y"~
   {RETURN}
   {ELSE}
{IF}"{VAR 2}"="y"~
   {RETURN}
   {ELSE}
   {QUIT}
{END IF}{END IF}

{LABEL}cancel~
{Exit}nn
{Switch}

 

IMPORTANT TOPICS

In this chapter, you learned:

---

 Top Contents

WordPerfect 5.1 Macros and Templates
Electronic Edition
Copyright 1990, 1997, Gordon McComb.  All Rights Reserved.
First published by Bantam Electronic Publishing, 1990.
http://www.gmccomb.com/.