Creating PMENUs for Application Windows Holly Whittle, SAS nstitute nc., Cary, NC ABSTRACT This paper describes the new PMENU procedure, which defines PMENU facilities for windows created with SAS nstitute software products. The paper presents a simple introduction to building action bars, pull-down menus, and dialog boxes. NTRODUCTON Before you can use the PMENU procedure, you need to understand the SAS System's PMENU facility. This facility is provided for SAS windows. The PMENU procedure allows you to create PMENUs for windows that you create using the WNDOW or %WNDQW statement with base SAS software or using SAS AP or SAS/FSP" software. The PMENU Facility The PMENU facility is a menuing system that replaces the command line as a way to execute commands. t is the default at some sites and an option at others. To activate the PMENU fadlity if it is not the default at your site, issue the PMENU command from any command line. When the PMENU facility is active, each active window has an action bar, which lists items you can select. To make a selection, position your cursor on the item and press ENTER (or point and click with a mouse). Depending upon which item you select, the system processes a command, displays information, displays another list of selections (this time in a column format called a pulldown menu), or requests that you complete information in a dialog box. The dialog box is simply a box of questions or choices that require answers before an action can be performed. Display 1 illustrates an action bar, a pull-down menu, and a dialog box. action bar pull-down menu dialog box + LOG----------- ------------ -----/----------- - ---------- ------- ---- ----+ \ File Edit View Globals Help / +----------------------1+ Undo! Unmark +Find.. -------------- + \ Cut marked text 1 Copy to paste buffer \ Enter string to find: Clear marked text 1 Clear text Find... 1 Select searcb order: Change... 0 FRST 0 LAST.. NEXT \ \ Repeat change 0 PREV 0 ALL 1 Check spelling +----1 Options Select context: 1---+ +PROG+-----------------------i 0 PREFX 0 SUFFX 1---+ File Edit View LOcals Global 0 WORD.. NO CONTEXT 00001 1 Select case mode: 1 00002 0 SENSTVE.. NSENSTVE 00003 000011 00005 00006 <OK> <Cancel> +----------------------------+-------------------------------------+---+ Using PROC PMENU to Create PMENU catalog Entries The SAS System supplies the PMENU facility for the windows included in the system. With PROC PMENU, you can create action bars, pull-down menus, and dialog boxes for the windows you define. n most cases, building and using PMENU entries requires the following steps: 1. Use PROC PMENU to define the action bars, pull-down menus, and other features you want. Store the output of PROC PMENU in a SAS catalog. Note: The PMENU procedure produces no immediately visible output; it simply builds a catalog entry that can be displayed later in a userwritten window. 2. Define a window using SAS/AF software, SAS/FSP software, the %WNDOW statement in the macro facility, or the WNDOW statement in base SAS software. 3. Associate the PMENU catalog entry created in step 1 with a window by using one of the following: the MENU= option in the WNDOW statement in base SAS software the MENU= option in the %WNDOW statement in the macro facility the Command Menu field in the GA TR window in the BULD procedure in SASAF software the PMENU function in the Screen Control Language the SET PMENU command in SAS/FSP software. 4. Activate the window you have created in a SAS Display Manager session. Be sure the PMENU facility is on. The action bar appears at the top of the window when the window is displayed. CREATNG SMPLE PMENUS You can create PMENUs with varying degrees of complexity. This paper describes how to create Simple forms of all three levels of PMENUs: action bars, pull-down menus, and dialog boxes. Action Bars The action bar is the portion of the PMENU that is displayed at the top of the window when the PMENU facility is on. You can think of the action bar as a top-level summary of the actions that can be performed with a PMENU. Very simple action bars can consist of a list of display manager commands that you execute by simply selecting the item from the action bar. For example, you could create an action bar with the two items shown in Figure 1. Display 1 Action Bar, Pull-Down Menu, and Dialog in LOG Window 1525
END BYE Figure 1 Action Bar w~h Display Manager Commands Selecting the END item exits the window; selecting the BYE item ex~s the SAS session. Process for Creating Action Bare To create the action bar shown above, use a PROC PMENU step like the following: proe penll eahlog-libnf.catalog; menu simple; item end: item bye; This step creates a PMENU catalog entry named SMPLE that contains the action bar illustrated in Figure 1. To see this action bar, you must associate the PMENU catalog entry with a window. The following code creates a simple window using the DATA step WNDOW and DSPLAY statements. You can use a window like this to test your PMENUs as you develop them. dab...null; 't define window t' window t.. t menu-ljbrsf.cstalog.silllple 14 a10 'Test PKNUS',,9 "0 'YOU must have the PKBNU!ecUity ON.' 120 a10 'Select ND or BY!. ;,. display window t' display test; run: Display 2 illustrates the window created above and shows the simple PMENU. +THST-------------------------------------------------------------+ J DO BY! J Test PXEiUS You mast have the PKNU facility ON. +--- Select ND or BlB. --R---------+ Display 2 Window Created with DATA Step Statements Defining tems that Execute Command Strings n addition to executing standard display manager commands, you might want to execute a series of commands by selecting an item from the action bar. n this case, you can associate a string of commands (or a single, lengthy command) with an action bar nem by using the SELECTON statement. For example, n you want to add an item to this action bar that executes some operating system commands, you could add a SELECTON statement as follows: proc pmenu catalog-libraf.catslo~ menu simple; item DD; item BlB; item 'STATUS' salecuon-status; selection status 'J: time; J: lista'; Note that the TEM statement now includes the SELECTONoption, which points to a subsequent SELECTON statement. The TEM statement defines what term appears on the menu. The SELECTON statement defines the actions that are associated with the menu item. f you want to specify several commands n a SELECTON statement, simply enclose the string n quotes and separate the commands with semicolons. Now the action bar looks Uke the one shown in Figure 2. [ END BYE STATUS Figure 2 Action Bar with Selection tems When you select STATUS from the action bar, the two X commands listed in the SELECTON statement are executed. Summary of Requirements for Action Bars To define an action bar, you create a catalog entry of type PMENU. You must use the PROC PMENU statement, the MENU statement, and one or more TEM statements. n addition, you can use the SELECTON = option on the TEM statement and an associated SELECTON statement to define command strings for a menu item. Dialog es As you build PMENUs to use with application windows, you may find that you need to allow users to enter nformation to complete an action they select from an action bar. For example, instead of defining an action bar tem that submits a specific operating system command, you can define an action bar tem that submits whatever operating system command the user enters. To alkjw users to enter infonnation with a PMENU item, you define a dialog box. Process for Creating Dialog es The following code aeates an action bar that includes an item called SUBMODE. When this item is selected from the action bar, a dialog box s displayed that prompts you to enter an operating system command. proc pmenu catalog-libraf.catalog; menu dialog; item HND; item BlB; item 'SUBKOD' dialog-j:command; dialog J:COlllllland 'l: i1'; tnt " i1 'nter operating syst.. coman4:'; tnt 12 i1 len-40j Note that the TEM statement for SUBMODE includes the DALOG- option, which points to a subsequent DALOG statement. The DALOG statement defines a command string like the one defined on a SELECTON statement, but instead of a complete c0mmand string, the DALOG statement allows room for additlonallnformation. Additional information is inserted into the command string 1526
where the @1 appears. This information comes from a subsequent TEXT statement that defines an input field. n this example, the information to add to the command string comes from the second TEXT statement that follows the DALOG statement. The first TEXT statement n this example simply defines a text string that appears in the dialog box to prompt you for input. (The #1 and @1 arguments in the TEXT statement define where to locate the text or input fields within a dialog box.) The second TEXT statement defines an input field where you enter a character string in response to the prompt. The information you enter is inserted into the command string defined in the DALOG statement SO if you use this dialog box and enter the operating system command TME at the prompt, the following command is processed by the dialog box:,,... When you dlspley the window using the PMENU and select the SUBMODE tem from the action bar, the action bar and dialog box appear n Display 3. Note that the name of a dialog box appears on the action bar and at the top of the dalog box followed by three periods (SUBMODE...) to indicate that more information s required. +T8S!-------------------------------------------------------------+ BHD BY! SUBlODE... +SUBHODB ---------------------------+ 1 nter operating; yatem comanel: _ 'elt PHBUS <OJ:) <Cancel> + -------------------------------------+ Display 3 Partial Window Showing Action Bar and Open Dialog To use this dialog box. you fill in the information, move the cursor to the OK button, and press ENTER (or point and click with a mouse). Note that you do not have to define either the location of the dialog box within the window or the two buttons that appear at the bottom of the box. These are handled automatically by the PMENU procedure. Summary of Requirements for Dialog es To define a dialog box that is displayed when you select an Kern from an action bar, you need a PROC PMENU step that includes the following: a PROC PMENU statement wtth the CATALOG~ option to define where to store the PMENU catalog entry. a MENU statement to define the action bar. one or more TEM statements to define the items on the action bar. One of the TEM statements must use the DALOG~ option to identify the dialog box that should be displayed when the tem is selected from the action bar. a DALOG statement for every TEM statement that includes a DALOG~ option. one or more TEXT statements to define text and input fields for the dialog box. Other statements, such as the CHECKBOX, RADOBOX, and RADOBUTTON statements, can be used with the dialog box, but are beyond the scope of this paper. Pull-Down Menu. Once you have mastered aeating dialog boxes, adding pull-down menus to your PMENU entry is simple. A pull-down menu is very sirmlar to an action bar, but in a pull-down menu items are listed verticalty, not horizontally. A pulklown menu is useful when you want to provide many functions on a PMENU for a window. You can organize the functions nto related groups, define a top level narne for each group, and then build action bars that Dst the groups of functions. For each group of functions, create a pull-down menu that lists the items for that group. Process for Creating Pull-Down Menus For example, suppose you want to define these groups of actions: OS Commands Time Free List Allocates Finish End Bye To create this PMENU, you need to define the following: an action bar with the items OS_Commands and Rnish the OS_Corrunands pull-down menu with the items Time, Free, and List Allocates * the command strings to be associated with the Time and Ust Allocates items the dialog box that prompts for the name of the data set to be freed by the Free Kern the Finish pulkjown menu with the items End and Bye, which are simple display manager commands. The following statements create the PMENU described above. proc penu cltalog-libref.c,tlllog: '* define action bar to bave two pull-down menus e, menu select; item 'OS..commlnds' adu-os; item 'Finish' menu_etone; '* define fiut pull-down menu *' menu 0.; item "lime' selection-time; it_ 'List Allocat8l' selaction-listl; item 'Pree' dialog-free; '* define command strings for two items on menu., aelection till\e 's tia'; selection lista 's Uste';,. deune dialog bas for one item OD menu., dialog free's free fiti11'; test 11 111 'nter name of file to be fread:'; test 12 111 len_'o;,. deune aecond pull-down menu witb DS collllllnd,a., menu done; item end; item bye; Notice that the puh-down menus are defined with the MENU statement, much ike the action bar is defined. To ndicate that an tem on the action bar is associated with a pull-down menu, use the MENU~ option n the TEM statement in the action bar menu. You use SELECTON statements and DALOG statements with pundown menus exactly as you use them with action bars. When you display the PMENU and select OS-Commands from the action bar and Free from the pull-down menu, the window appears as shown in Display 4. 1527
+TEST-------------------- + OLCommands Finish +----------- ------+ Time List Allocates 1 1 Free... +Free... --------------------------- + +-----------------1 Enter name of file to be freed: <OK> <Cancel> 1 j + -------------------------------- - - --- ----+ Display 4 Partial Window Showing Action Bar and Open Dialog '* define action bar *' menu select; item 'PrintJ.eports' menu"'reports; item 'End'; item 'Bye'; '* define pull-down menu *' menu reports; item 'Summary' selection"prt 1; item 'Detail' dialog=detlinfo; '* command string to print summary report *' selection prtl 'end;include rptcode(swll);submit'; /* dialog box to print detail report *' dialog detlinfo 'end;include rptcode{detail);c xx <ill;submit'; text, ~1 'Enter department nulllber (01-99):'; text, 1 ~35 len=2; quit; Summary of Requirements for Pull-Down Menus To define a pull-down menu that is displayed when you select an item from an action bar, you need a PROC PMENU step that includes the following: a PROC PMENU statement with the CATALOG= option to define where to store the PMENU catalog entry. a MENU statement to define the action bar. one or more TEM statements to define the items on the action bar. One of the TEM statements must use the MENU = option to identify the pull-down menu that should be displayed when the item is selected from the action bar. an additional MENU statement for every TEM statement that includes a MENU = option. one or more TEM statements to define the items for a pulldown menu. n addition to these requirements, you can use SELECTON statements and DALOG statements with pull-down menus just as you do with action bars. A SAMPLE APPLCATON The following example shows how to define an action bar, a puhdown menu, and a dialog box for a sample application developed using the WNDOW statement. This example requires that you define the following: the PMENU for the window the window, which specifies the PMENU with the PMENU = option an additional SAS job that is submitted by one of the 11 EM statements. Defining the Window The following statements define the window for the application. Note that the MENU = option in the WNDOW statement associates the RPT.MENU8.SELECT PMENU entry, defined in the previous example, with this window. libnarne rpt 'SAS-data-library'; data ---null; '* define Window *' window describe menu=rpt.menus.select j4 lil0 'This application allows you to' is iil13 '- Print reports (summary or detail)' 18 iil13 '- End the application and return to the PGK window.',10 iil13 '- Exit from the SAS System.',19010 'You must have the PKENU facility ON.' 120 OlO 'Select PRNT...REPORTS, END or BYE.'; /* display window */ display describe; The window produced by these statements appears in Display 5. The window shows the action bar that is associated with the wndow. +DESCRBE-----------~-------------------~------------------- + Print---.Reports End Bye This application allows you to - Print reports (summary or detail) - End the application and return to the PGK window. - Exit from the SAS System. This example defines an application that enables you to select reports to print. Building the PMENU Catalog Entry for the Application The following statements define the PMENU entry that is used in the window: libname rpt 'SAS-data-library'; filename rptcode 'external-file'; proc pmenu cat",rpt.menus; You must have the PMENU facility ON. Select PRNT---.REPORTS, END or BYE. +--------------------------------~----------------------------R---+ Display 5 Sample DATA Step Window Display 6 shows a partial window with the pull-down menu and dialog box that are displayed when you select PrinLReports and then Detail 1528
+DESCRBB---------------------------------------------------------+ PrinLlteports End Bye +------------+ SUll\ary 1 Detail... + +Detall... -----------------------------+ + 1 Enter department number (01-99): J Thl 1 <OK> <Cancel> 1 1 +---------------------------------------+ - t;nd the appliciltioll am return to the PGK window. Display 6 Partial Window Showing Pull-Down Menu and Dialog Defining the Step to Print Reports When you select Detail, enter a number at the prompt, and select OK, the following statements are invoked: llbniud.e rpt 'SAS-data-library'; filename rpteode 'erternal-flle'; '* route output to print file *' proe printto flle='your.list.file' new;,. print report., proe print data=rpt.deptxr;,. restore default output destination *' pro<: printto;,. redisplay DATA step window *' hnc1nde rpteode{windowl; This program is modified by the SELECTON or DALOG statement that invokes it, so the name of the data set is changed from DEPTXX to the correct name. Thus, if you enter 01 to identify the department number, the PROC PRNT statement is modified to'the following: proe print data=rpt.dept01; The last statement in the program redisplays the DATA step window so you can make other selections. CONCLUSON The PMENU procedure allows you to create PMENUs that can be used with user -written windows. n addition to the capabilities described in this paper, the PMENU procedure allows you to create dialog boxes that offer the user radio box and check box choices manipulate the color of the text in dialog boxes for operating systems that support those features of PMENUs, define accelerator keys and mnemonics for items or indicate items that are not active choices (that is, "greyu items). The PMENU procedure is documented in detail in the SAS Procedures Guide, Version 6, Third Edition. FOOTNOTE This paper uses MVS operating system commands, but you can substitute other commands. n this example, the TME command displays the time. The LST A command lists all data sets currently being used by the session. The FREE command (also shown in this paper) frees a data set from use by the current session. SAS, SAS AF, and SAS/FSP are registered trademarks of SAS nstitute nc., Cary, NC, USA. 1529