DIGITAL_DECforms______________________________ Guide to Demonstration Forms and Applications April 1997 This document contains descriptions of the demonstration files that are available with the DIGITAL DECforms [TM] kit. This document is available on-line in the directory FORMS$EXAMPLES with the file name FORMS$DEMO_GUIDE and filetypes of PS for the Postscript[R] version and TXT for the plain ASCII version. Software Version: DECforms Version 2.2 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Printing, June 1994 Revised, April 1997 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1989, 1990, 1991, 1992, 1993, 1994, 1997. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: ACMS, DEC, DECforms, DECintact, DECwindows, DIGITAL, OpenVMS, ULTRIX, VAX, VAXcluster, VAX FMS, VAX RMS, VAXstation, VT, and the DIGITAL logo. The following are third-party trademarks: Intel is a trademark of Intel Corporation. Motif is a registered trademark of Open Software Foundation, Incorporated. Postscript is a registered trademark of Adobe Systems, Incorporated. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents Preface.................................................. ix 1 Introduction 1.1 Demonstration Applications...................... 1-1 1.2 Demonstration Forms............................. 1-2 1.3 Using the Demonstrations........................ 1-3 1.3.1 Character-Cell Environment ................... 1-3 1.3.2 DECwindows Motif Environment ................. 1-4 1.4 Finding the Demonstrations...................... 1-4 2 FORMS$DEMO.COM Procedure 2.1 Using The Command Procedure..................... 2-1 2.2 Running Your Own Demonstrations................. 2-2 3 Enable Program 3.1 Using the Enable Program........................ 3-1 3.2 Conventions for Enabling Shareable Images....... 3-2 3.3 Implementation Notes............................ 3-3 3.4 Development Notes............................... 3-3 4 Advanced Sample (Checking) Application 4.1 Overview........................................ 4-1 4.2 Running the Advanced Sample Demo................ 4-1 4.3 Implementation Notes............................ 4-3 4.4 Development Notes............................... 4-3 iii 5 Calls Application 5.1 Overview........................................ 5-1 5.2 Running the Calls Demo.......................... 5-1 5.3 Implementation Notes............................ 5-2 5.4 Development Notes............................... 5-3 6 Mileage Reimbursement Application 6.1 Overview........................................ 6-1 6.2 Running the Mileage Reimbursement Demo.......... 6-2 6.3 Implementation Notes............................ 6-2 6.4 Development Notes............................... 6-3 7 Phone Book Application 7.1 Overview........................................ 7-1 7.2 Running the Phone Book Demo..................... 7-1 7.3 Implementation Notes............................ 7-2 7.4 Development Notes............................... 7-3 8 Show Text Library Application 8.1 Overview........................................ 8-1 8.2 Running the Show Text Library Demo.............. 8-1 8.3 Implementation Notes............................ 8-3 8.4 Development Notes............................... 8-4 9 Timer Application 9.1 Overview........................................ 9-1 9.2 Running the Timer Demo.......................... 9-1 9.3 Implementation Notes............................ 9-1 9.4 Development Notes............................... 9-4 10 TM Application 10.1 Overview........................................ 10-1 10.2 Running the TM Demo............................. 10-1 10.3 Implementation Notes............................ 10-1 10.4 Development Notes............................... 10-2 iv 11 Track and Field Application 11.1 Overview........................................ 11-1 11.2 Running the Track and Field Demo................ 11-1 11.3 Implementation Notes............................ 11-2 11.4 Development Notes............................... 11-3 12 Introductory Sample Application 12.1 Overview........................................ 12-1 12.2 Running the Introductory Sample Demo............ 12-1 12.3 Implementation Notes............................ 12-3 12.4 Development Notes............................... 12-3 13 Calculator Form 13.1 Overview........................................ 13-1 13.2 Running the Calculator Demo..................... 13-1 13.3 Implementation Notes............................ 13-4 13.4 Development Notes............................... 13-4 14 Command Recall Form 14.1 Overview........................................ 14-1 14.2 Running the Command Recall Demo................. 14-1 14.3 Implementation Notes............................ 14-2 14.4 Development Notes............................... 14-2 15 CopyCat Form 15.1 Overview........................................ 15-1 15.2 Running the Copycat Demo........................ 15-1 15.3 Implementation Notes............................ 15-2 15.4 Development Notes............................... 15-3 16 Globe Form 16.1 Overview........................................ 16-1 16.2 Running the Globe Demo.......................... 16-3 16.3 Implementation Notes............................ 16-3 16.4 Development Notes............................... 16-6 v 17 World Form 17.1 Overview........................................ 17-2 17.2 Running the World Demo.......................... 17-2 17.3 Implementation Notes............................ 17-3 17.4 Development Notes............................... 17-3 18 Order Entry Application Form 18.1 Overview........................................ 18-1 18.2 Running the Order Entry Demo.................... 18-2 18.3 Implementation Notes............................ 18-6 18.4 Development Notes............................... 18-12 19 Rule Character Set Form 19.1 Overview........................................ 19-1 19.2 Running the Rule Character Set Demo............. 19-1 19.3 Implementation Notes............................ 19-2 19.4 Development Notes............................... 19-3 20 VT Windows Form 20.1 Overview........................................ 20-1 20.2 Running the VT Windows Demo..................... 20-1 20.3 Implementation Notes............................ 20-2 20.4 Development Notes............................... 20-2 Index Examples 18-1 Listing of Print Panel ....................... 18-12 vi Tables 1 Conventions Used in the Guide ................ xii 2-1 Naming Conventions for Demonstration Files ... 2-3 20-1 Windows Function Keys ........................ 20-2 vii ________________________________________________________________ Preface The DECforms kit contains a set of demonstration forms and applications that demonstrate many DECforms features. By using the demonstrations and examining the IFDL syntax and program code, you can get ideas for creating your own DECforms applications. The techniques used in the examples might not be the best for all circumstances. DIGITAL does not claim that following the techniques will always result in the best DECforms application. You must judge this for yourself. Who Should Use This Guide This guide is for anyone who wants to see what can be done with DECforms or who wants to demonstrate DECforms features to others. Structure of This Guide This guide contains the following chapters: Chapter 1 Introduces the kinds of demonstrations that are supplied in the DECforms kit. Chapter 2 Describes a command procedure used to run the demonstrations. Chapter 3 Describes a BASIC program used to enable any form. Chapter 4 Describes an application used to maintain personal checking account data. Chapter 5 Describes an application that demonstrates the DECforms request calls. ix Chapter 6 Describes an application used to calculate mileage reimbursment for business trips. Chapter 7 Describes an application that implements a phone directory. Chapter 8 Describes an application that accesses text from an OpenVMS library. Chapter 9 Describes an application that asynchronously updates fields on the screen. Chapter 10 Describes an application that shows portable use of the TM data type. Chapter 11 Describes an application that illustrates user interface design concepts discussed in the DECforms Style Guide for Character-Cell Devices. Chapter 12 Describes a rudimentary application for maintaining checking account data. Chapter 13 Describes a form used to simulate a calcula- tor. Chapter 14 Describes a form used to recall field data without program intervention. Chapter 15 Describes a form that uses a simple game to demonstrate the use of color and response step execution order. Chapter 16 Describes a form that displays a map of the world for character-cell display. Chapter 17 Describes a form that displays a map of the world for window display. Chapter 18 Describes a form to illustrate an order entry application. Chapter 19 Describes a form to show the Rule Character Set. Chapter 20 Describes a form that demonstrates the windowing capabilities of DECforms. x For More Information See the online help, the online release notes, and the following documents for more information about DECforms: o DECforms Installation Guide for OpenVMS Systems - Describes how to install DECforms software on processors that are running the OpenVMS[TM] operating system. o DECforms IFDL Reference Manual - Describes the syntax of the DECforms Independent Form Description Language. o DECforms Style Guide for Character-Cell Devices - Describes how to develop Motif[R] style user interfaces for DECforms applications for character-cell terminals. o DECforms Programmer's Reference Manual - Describes how DECforms software operates at run time and how to call the DECforms requests from an application program. o DECforms Guide to Developing an Application - Part I explains to the beginning DECforms programmer how to create a DECforms application, including both the form and the program. Part II contains additional guidelines and examples for more experienced DECforms programmers. o DECforms Guide to Commands and Utilities - Describes the DECforms forms commands and utilities. o DECforms Guide to Converting VAX FMS Applications - Describes how to convert a VAX FMS[TM] application to a DECforms application. For further information on other topics of interest, see the following: o DEC LSE documentation for information on how to use DEC LSE o Oracle/Repository[TM] documentation set for information on Oracle/Repository definitions o The CODASYL Form Interface Management System Journal of Development (see the Acknowledgment section). xi Send Us Your Comments We welcome your comments on this or any other DECforms documentation. If you have suggestions for improving a particular section or find any errors, please indicate the chapter, section, and page number (if available). We also welcome more general comments. Your input is valuable in improving future releases of our documentation. You can send comments to us at the following Internet address: forms_docs@zko.dec.com If you have a customer support contract and have comments or questions about DECforms software, you contact Digital's Customer Support Center (CSC), preferably using electronic means such as DSNlink. In the United States, customers can call the CSC at 1-800-354-9000. Conventions Table 1 lists the conventions used in this guide: Table_1_Conventions_Used_in_the_Guide___________________________ Symbol_or_Term________Meaning___________________________________ (continued on next page) xii Table_1_(Cont.)_Conventions_Used_in_the_Guide___________________ Symbol_or_Term________Meaning___________________________________ layouts When discussing layouts, the following terms are used: character-cell - to refer to layouts that display forms on character-cell devices Motif or DECwindows[TM]-to refer to layouts that display forms on devices running the DECwindows user interface PRINTER-to refer to layouts that output forms for quality printing window-to refer to Motif or DECwindows layouts collectively pixel-to refer to window and PRINTER layouts collectively mouse The term mouse is used to refer to the pointing device that controls the pointer position on the screen. MB1,MB2,MB3 On a three-button mouse, MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. The user can redefine the buttons by using system- specific window management facilities. See your windowing system documentation for more details. click The term click means press and release MB1 (unless another mouse button is specifically mentioned). double click The term double click means press and release MB1 two times in rapid succession without moving the mouse. (continued on next page) xiii Table_1_(Cont.)_Conventions_Used_in_the_Guide___________________ Symbol_or_Term________Meaning___________________________________ drag The term drag means press and hold MB1 (unless another mouse button is specifically meantioned), move the mouse, and then release the button when the pointer is in the desired position. Alt The Alt key. This key is labeled Compose Character on some keyboards. Ctrl/x In procedures, a sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key. KPn Key names that begin with KP indicate keys on the numeric keypad on the right side of the terminal keyboard. For example, KP4 and KP. are keys on the numeric keypad. PF1-x A sequence such as PF1-x indicates that you must first press and release the key labeled PF1, and then press and release another key. . . . In examples, a horizontal ellipsis indi- cates one of the following possibilities: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o Additional parameters, values, or other information can be entered. A vertical ellipsis indicates the omission . of items from a code example or command . format; the items are omitted because . they are not important to the topic being discussed. (continued on next page) xiv Table_1_(Cont.)_Conventions_Used_in_the_Guide___________________ Symbol_or_Term________Meaning___________________________________ () In format descriptions, parentheses indicate that if you choose more than one option, you must enclose the choices in parentheses. $ The dollar sign is used to indicate the ______________________user_prompt_on_OpenVMS_systems.___________ Unless otherwise specified, you terminate commands by pressing the Return key. Acknowledgment DECforms is the DIGITAL implementation of a Form Interface Management System (FIMS) ANSI/ISO standard prepared by the CODASYL Form Interface Management System Committee and ISO/IEC JTC1/SC22 Working Group 18. The FIMS standard is documented in ISO IS 11730:1994 and can be purchased from the International Organization for Standardization or the American National Standards Institute. xv 1 ________________________________________________________________ Introduction Two types of demonstrations are provided in the DECforms kit: demonstration applications and demonstration forms. Each demonstration is described briefly in its own chapter in this book. By using the demonstrations and studying their coding techniques, you can gain ideas of how to design your own panel appearance and form processing for character-cell and window display devices. 1.1 Demonstration Applications Demonstration applications provide a form and a program that works with the form. Applications include the following: Introduction 1-1 __________________________________________________________ Name__________Demonstrates____________Display_Environment_ Advanced Icons and pull-down Character Cell Sample menus (character DECwindows Motif (Checking) cell) and pushbuttons (window) Calls DECforms request calls Character Cell MRF Design techniques for Character Cell data input and display DECwindows Motif PRINTER Phone Multiple-line Character Cell scrolling Show Text Scrolling of text Character Cell Library read from an OpenVMS library Timer Asynchronous field Character Cell update TM Portable use of the TM Character Cell data type Track and User interface Character Cell Field design techniques for emulating DECwindows appearance Introductory Basic panel design for Character Cell Sample data input and display DECwindows Motif ______________________________________PRINTER_____________ 1.2 Demonstration Forms Demonstration forms provide a form that shows IFDL coding techniques that accomplish common forms tasks. Because the demonstration forms do not have a corresponding program, they are designed to be run by the FORMS$DEMO_ENABLE program described in Chapter 3. All interaction is controlled by logic in the form. The forms are built and released as sharable images so that they enable faster. Demonstration forms include the following: 1-2 Introduction __________________________________________________________ Name__________Demonstrates____________Display_Environment_ Calculator Function responses Character Cell and use of OpenVMS DECwindows Motif Run-time Library calls Command Group scrolling to Character Cell Recall recall field data CopyCat Color and order Character Cell of response step execution Globe Use of graphics Character Cell World Use of graphics DECwindows Motif Order Entry Emulation of Character Cell DECwindows appearance Rule Rule characters Character Cell Character Set VT Windows Emulation of window Character Cell Simulation____appearance__________________________________ 1.3 Using the Demonstrations You can run any demonstration by using the command procedure FORMS$DEMO.COM described in Chapter 2. This displays a menu of all the available demonstrations, from which you can make a selection. You can also run the demonstrations from the command line, as described in each demonstration's corresponding chapter. In addition, each chapter contains a brief overview of the demo and major features demonstrated; a list of the files comprising the demo; and the commands used to build the demo. 1.3.1 Character-Cell Environment Before running a demonstration on a character-cell device, you might want to disable broadcast messages to prevent disruption by the arrival of a mail or system message. Introduction 1-3 To disable broadcast messages, enter the following command: $ set terminal/nobroadcast If you choose not to disable messages, you can always use Ctrl/W to refresh the screen after a disruption. If you are using the command procedure (FORMS$DEMO.COM) to run the demos, broadcast messages are disabled by default. 1.3.2 DECwindows Motif Environment Before running a demonstration on a DECwindows device, you must have the logical DECW$DISPLAY defined for a form to be displayed. To define this logical, enter a command in the following format: set display/create/node = your-node-name If you are running DECwindows from a remote node, make sure that you have the Session Manager Security option set up appropriately. 1.4 Finding the Demonstrations All demonstrations are located in the directory pointed to by the logical name FORMS$EXAMPLES. All the files mentioned in this guide, including the guide itself, are in that directory. If you find that the directory is empty or does not exist, ask your system manager for help. Installing the demonstrations is an installation option, and your system manager may need to reinstall the DECforms kit to include them. There are two versions of this guide in the directory: FORMS$DEMO_GUIDE.PS, for printing on PostScript[R] printers; and FORMS$DEMO_GUIDE.TXT, for typing on a terminal or printing on any ASCII printer. The latter is a plain text version with no highlighting. 1-4 Introduction 2 ________________________________________________________________ FORMS$DEMO.COM Procedure The FORMS$DEMO.COM command procedure provides a simple way to run any DECforms demonstration. It displays a menu that lists all the demonstration choices so that you can make a selection, and takes care of setting up any necessary logicals and DCL commands. This chapter describes how to use the command procedure. 2.1 Using The Command Procedure Some of the demos contain both a character-cell layout and a DECwindows Motif layout. Determine the type of device on which you want to display those forms, then enter one of the following commands: For Character-Cell Devices $ define forms$default_device sys$input For Window Devices $ define forms$default_device decw$display If you choose the command for character-cell devices, all demos will display on the character-cell device. If you choose the command for window devices, demos containing only a character-cell layout will display on the character-cell device, while demos containing both a character-cell layout and DECwindows Motif layout will display on the Motif device. To use the FORMS$DEMO command procedure, enter the following command: $ @forms$examples:forms$demo The procedure displays a numbered menu of all the demonstrations available in the FORMS$EXAMPLES directory. FORMS$DEMO.COM Procedure 2-1 To run a demonstration, enter its number and press Return. Control returns to the menu when you leave the demonstration. Enter the number of the next demonstration you want to run, or enter 0 to exit the menu. The command procedure turns off broadcast messages while in use. This prevents mail or other broadcast messages from interfering with your use of the demonstrations. On exit, the command procedure restores your normal setting for broadcast messages. The command procedure also temporarily disables creation of any trace files. If you want to create a trace file while using a demonstration, you must run the demo directly from the command line. See the individual chapters for instructions. 2.2 Running Your Own Demonstrations You can use the FORMS$DEMO command procedure and its resulting menu to run demonstrations that you create. Copy your demonstration programs and forms to the FORMS$EXAMPLES directory, using the naming conventions summarized in Table 2-1. You can also run your demonstrations from any other directory by entering a command in the following format: @forms$examples:forms$demo [your-demo-directory] The command file displays a menu showing the applications and forms available in that directory. When naming demonstrations, use the naming conventions summarized in Table 2-1. (For complete information about the naming conventions used for demonstration files, see the comments in the FORMS$EXAMPLES:FORMS$DEMO.COM file.) 2-2 FORMS$DEMO.COM Procedure Table_2-1_Naming_Conventions_for_Demonstration_Files______ Convention____________Demonstration_Type__________________ FORMS$DEMO_xxx.EXE DIGITAL supplied demo applications. FORMS$xxx.EXE FORMS$DEMO_xxx.FORM DIGITAL supplied demo forms. (The FORMS$xxx.FORM form can be a .FORM file with the same name as the application program .EXE file, or it can be linked into the application program.) FORMS$DEMO_xxx_ DIGITAL supplied demo forms, FORM.EXE in shareable images. (These demonstrations are enabled by the FORMS$DEMO_ENABLE program described in Chapter 3.) DEMO_xxx.EXE Customer-supplied demo applications. DEMO_xxx.FORM Customer-supplied demo forms. Supply the form as a .FORM file with the same name as the application program .EXE file, or link the form into the application program for faster performance. DEMO_xxx_FORM.EXE Customer-supplied demo forms in shareable images, one form per image. (These demonstrations are enabled by the FORMS$DEMO_ENABLE program. See Chapter 3 for the conventions required for enabling ______________________shareable_images.)__________________ FORMS$DEMO.COM Procedure 2-3 3 ________________________________________________________________ Enable Program The Enable program is designed to enable any form. You can use the Enable program to run demonstration forms that do not supply a program. You can also use it to prototype forms that you create[1]. The Enable program enables forms in form files (.FORM) and forms in shareable images (.EXE). Shareable images must be created according to the conventions described in Section 3.2. 3.1 Using the Enable Program To use the Enable program, first define it as a foreign command by entering the following command (you can substitute any symbol name you prefer): $ enable := $forms$examples:forms$demo_enable Then use the command to run the program and enable a form. For example: $ enable myform.form If you omit the form name from the command line, the program uses the logical name FORMS$DEMO_FORM to enable a form. By defining this logical name to point to your form, you can run the Enable program without defining a foreign command. For example: $ define forms$demo_form myform $ run forms$examples:forms$demo_enable ___________________ [1]The Form Development Environment, used for creating character-cell forms, also supplies its own test option for enabling a form and passing control text for testing the form. Enable Program 3-1 You could create a command procedure that defines logicals that identify files and their locations or the display device or node. In this case, to run a demonstration, you might enter a sequence of commands such as the following: $ define/nolog sys$input sys$output $ enable := $forms$examples:forms$demo_enable $ @setup_my_demo ! Your setup procedure $ enable my_demo ! Your demonstration form 3.2 Conventions for Enabling Shareable Images If you are enabling a form in a shareable image, be sure that the name of the form, as specified in the IFDL syntax, is the same as the name of the file. For example, if your form was linked in a shareable image called MYFORM.EXE, the Enable program will work only if the form name is MYFORM, as follows: Form MYFORM . . . End Form If you intend to use the FORMS$DEMO command procedure (described in Chapter 2) to run the demonstration, there are additional naming conventions to follow. For example, to create MYFORM as a shareable image for use with the FORMS$DEMO command procedure, name the image DEMO_MYFORM_FORM.EXE (instead of MYFORM.EXE). In the IFDL syntax, name the form DEMO_MYFORM_FORM, as follows: Form DEMO_MYFORM_FORM . . . End Form To turn the form into a shareable image, enter the following commands: $ forms translate DEMO_MYFORM_FORM /nocomments $ forms extract object DEMO_MYFORM_FORM $ link DEMO_MYFORM_FORM /shareable 3-2 Enable Program 3.3 Implementation Notes The Enable program is written in VAX BASIC. It uses LIB$GET_FOREIGN to get the command line. It then enables the form and, upon return, disables it. Any error status codes cause the program to print a message and terminate. Demonstration forms run from this program can call STR$* and LIB$* routines directly as procedural escapes because the name of the shareable image LIBRTL is included in the enable call. To include another image, add another item list entry and include the name the other image. See the Enable program source code (FORMS$DEMO_ENABLE.BAS) for more information. 3.4 Development Notes The program is compiled and linked as usual. The VAX BASIC compiler might produce some informational messages stating that constructs used within the program do not allow for optimization. Ignore those messages. Files used o FORMS$DEMO_ENABLE.BAS Build commands $ BASIC FORMS$DEMO_ENABLE $ LINK FORMS$DEMO_ENABLE Enable Program 3-3 4 ________________________________________________________________ Advanced Sample (Checking) Application This chapter introduces the advanced sample checking application that is described in detail in Part II of the DECforms Guide to Developing an Application. 4.1 Overview The advanced sample application is an application for maintaining a personal checking account. You can write checks, make deposits, withdraw cash, transfer cash from checking to savings, and review account information. The form includes layouts for character-cell and window display. The application demonstrates the following features: o Use of Portable API request calls (C and FORTRAN versions) o Use of icons and pull-down menus (for character-cell devices) and use of push buttons (for window devices) for initiating application tasks o Support for printing copies of checks and records of transactions o Support for two Motif layouts (one providing extra windowing features) 4.2 Running the Advanced Sample Demo Determine the type of device on which you will display the form, then enter one of the following commands: For Character-Cell Devices $ define forms$default_device sys$input Advanced Sample (Checking) Application 4-1 For Window Devices $ define forms$default_device decw$display To run the advanced sample demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ define forms$checking_form forms$examples:forms$checking_form $ run forms$examples:forms$checking The application displays a welcome panel. Escape routines called from the form supply the version number of the operating system installed on your system and your user name. Press the Help key to display a Help panel. In a windowing environment, you can also click on the Help button. Help panels are associated with all the panels in the form and you can refer to them as you use the application. Choose options at the top of the screen to perform the tasks associated with maintaining a bank account. You can perform tasks in any order. In a character-cell environment, use the arrow keys and the Select key to navigate the choices. In a windowing environment, you can also click on the appropriate button. As you perform tasks, the balance is automatically updated to reflect deposits, withdrawals, and transfers. The balance value is held in the form and updated by the program. It is used directly in the form for validation without reference to the program. Note that changing data in the Review Account option requires that you enter a password. Use help to discover what the password is. To print a copy of a check or a deposit slip, in a character-cell environment press the P4 key with the check or deposit slip displayed on the screen. This creates a text file named forms$checking_form.txt in your SYS$SCRATCH directory (usually your login directory). Each time you press the P4 key, the displayed entry is added to the file. 4-2 Advanced Sample (Checking) Application In a windowing environment, press Ctrl/P with the check or deposit slip displayed; be sure that the check or deposit slip appears to the left side of your screen. Pressing Ctrl/P creates a file named forms$checking_form.ddif in your SYS$SCRATCH directory and prints one entry at a time. To convert the file to a PostScript format, enter the following command: $ convert/document forms$checking_form.ddif forms$checking_form.ps/format=ps To leave the demonstration, choose the Exit option. You are limited to 30 transactions. This restriction is specified in the application; it is not a restriction of DECforms. ________________________Note ________________________ To see an alternate Motif layout that provides some additional windowing capabilities, enter the following command before you start the application: $ define forms$language alternate_pixel _____________________________________________________ 4.3 Implementation Notes For detailed information about the IFDL source code used in this application, see Part II of the DECforms Guide to Developing an Application. The application program source files are supplied in a number of different programming languages. The C and FORTRAN versions support the DECforms portable API. The remaining languages support the OpenVMS Calling Standard and the DECforms OpenVMS API on OpenVMS systems. 4.4 Development Notes Files used o FORMS$CHECKING_FORM.IFDL o FORMS$CHECKING_DATA.DAT o FORMS$CHECKING_ADA.ADA Advanced Sample (Checking) Application 4-3 o FORMS$CHECKING_BASIC.BAS o FORMS$CHECKING_BASIC_COMMON.BAS o FORMS$CHECKING_C.C o FORMS$CHECKING_COBOL.COB o FORMS$CHECKING_DIBOL.DBL o FORMS$CHECKING_FORTRAN.FOR o FORMS_CHECKING_COMMON.F o FORMS_CHECKING_GETSYSINFO.F o FORMS$CHECKING_PASCAL.PAS o FORMS$CHECKING_PLI.PLI Build commands The build commands for the FORTRAN and C applications are shown below. For build instructions for the other languages, see the comments section at the beginning of each language's program source file in the FORMS$EXAMPLES directory. To build the C application, use the following commands: $ CC FORMS$CHECKING_C.C $ FORMS TRANSLATE FORMS$CHECKING_FORM.IFDL $ FORMS EXTRACT OBJECT/PORTABLE_API/NOFORM_LOAD FORMS$CHECKING_FORM.FORM Link the C object, the forms vector, and the shareable image by creating a command file containing the following lines and executing it: $ LINK FORMS$CHECKING_C.OBJ, FORMS$CHECKING_FORM.OBJ, SYS$INPUT:/OPT - SYS$LIBRARY:VAXCRTL.OLB/LIB SYS$LIBRARY:FORMS$PORTABLE_API/SHARE To build the FORTRAN application, use the following commands: $ FORTRAN FORMS$CHECKING_FORTRAN.FOR $ FORMS TRANSLATE FORMS$CHECKING_FORM.IFDL $ FORMS EXTRACT OBJECT/PORTABLE FORMS$CHECKING_FORM.FORM 4-4 Advanced Sample (Checking) Application Link the FORTRAN object, the forms vector, and the shareable image by creating a command file containing the following lines and executing it: $ LINK FORMS$CHECKING_FORTRAN.OBJ, FORMS$CHECKING_FORM.OBJ,SYS$INPUT:/OPT - SYS$LIBRARY:FORMS$PORTABLE_API.EXE/SHARE Advanced Sample (Checking) Application 4-5 5 ________________________________________________________________ Calls Application This chapter describes an application that demonstrates the DECforms program request calls. 5.1 Overview The Calls application provides a very simple demonstration of the basic DECforms programming calls without the distraction of other application-oriented tasks. It is intended to be used with a trace file. The form includes a layout for character-cell display. 5.2 Running the Calls Demo To create a trace file, enter the following command: $ define/user forms$trace true Using the /user qualifier causes tracing to occur for only this single run of the demo. The trace file is called forms$demo_calls.trace and is written to your current default directory. If you want the trace file to go to another directory, define the logical name FORMS$TRACE_ FILE as that directory. For example: $ define forms$trace_file mydisk:[mydir] To run the Calls demo, enter the following commands: $ define forms$demo_calls forms$examples:forms$demo_calls $ run forms$examples:forms$demo_calls You can also run the Calls demo by selecting it from the demonstration menu described in Chapter 2. However, you cannot obtain a trace file because tracing is temporarily turned off when using the FORMS$DEMO command procedure. Calls Application 5-1 The demo displays a welcome panel with help that describes how to use the demo. You can access that same help from the main panel by pressing Help. Hints (help messages) for using the demo are provided in the message area of the main panel. The program receives or transceives a number and a text string. It adds one to the number and reverses the text string before sending or transceiving it back to the screen. You control whether the program uses send/receive or transceive request calls by moving to the appropriate icon and selecting it. To leave the demo, press the F10 key or Ctrl/Z. 5.3 Implementation Notes In the IFDL source file, a highlighted icon identifies the type of call being used. A second icon, controlled by a CONCEALED WHEN clause, points to the highlighted icon. The IFDL syntax for the second icon is: Icon TRANS_CALL_USED Concealed When (CALL_TYPE = "S") Display Bold Literal Text Line 6 Column 14 Value "-->" End Literal Literal Text Line 6 Column 3 Value "Call" End Literal Literal Text Line 7 Column 3 Value "being used" End Literal End Icon 5-2 Calls Application Function responses are used to cause the up arrow key to go to the call type icon. The call type icon is not activated by the call. It is activated by the use of the function key. This provides more information for the trace. The explanation that appears beneath the right hand data box is controlled by a CONCEALED WHEN clause. The controlling value is set in the REQUEST EXIT RESPONSE of the receive or transceive request. This prevents the explanation from appearing with the send part of the initial request. 5.4 Development Notes Files used o FORMS$DEMO_CALLS.IFDL o FORMS$DEMO_CALLS.COB Build commands $ FORMS TRANSLATE FORMS$DEMO_CALLS $ COBOL FORMS$DEMO_CALLS $ LINK FORMS$DEMO_CALLS Calls Application 5-3 6 ________________________________________________________________ Mileage Reimbursement Application This chapter introduces the Mileage Reimbursement application that is described in detail in Part I of the DECforms Guide to Developing an Application. 6.1 Overview The Mileage Reimbursement application is a data input application that computes and displays mileage reim- bursement for business trips. The form contains layouts for character-cell and window display, and for printed output representing the mileage reimbursement form and data entered during the session. The form for the Mileage Reimbursement Application illustrates many aspects of DECforms applications, including the following: o The same viewport for more than one panel o Character, integer, and datetime data o Data groups (structures of data fields) o Multiline text fields o OUTPUT "" WHEN, OUTPUT PICTURE, PROTECTED WHEN, SCALE clauses o Icons and push buttons o Field defaults o Data sent to the program in form records, including the sending of one row of array data o Two sessions from one form, one for the data input and the other for creating the DDIF data output file o Functions, function responses, internal responses, disable response, and receive response Mileage Reimbursement Application 6-1 o Help panels for three different devices (VT-terminals, DECwindows Motif, and Microsoft Windows) 6.2 Running the Mileage Reimbursement Demo Determine the type of device on which you will display the form, then enter one of the following commands: For Character-Cell Devices $ define forms$default_device sys$input For DECwindows Motif Devices $ define forms$default_device decw$display To run the Mileage Reimbursement demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_mrf The application displays a header panel where you can enter employee data. Use the application's help for information on how to navigate among panel items and between panels, and for information on how to print form data. To leave the demonstration, select the Record and Exit icon (or click on the Record and Exit button) on the Trips screen. The demonstration automatically creates a file named prin_mrf.doc. To convert the file to PostScript format, enter the following command: $ convert/document prin_mrf.doc prin_mrf.ps/format=ps 6.3 Implementation Notes There are two source files for the program-one in the C programming language and one in the FORTRAN programming language. Both are written using the DECforms portable API. There is no difference between the C and FORTRAN applications as far as tasks or performance are concerned. The program does not store the data in a permanent location. The data exists only for the duration of the program. 6-2 Mileage Reimbursement Application For a tutorial and detailed description of how to create this application, see Part I of the DECforms Guide to Developing an Application. The source files for the form and programs are contained in an appendix in that guide. 6.4 Development Notes Files used o FORMS$DEMO_MRF_FORM.IFDL o FORMS$DEMO_MRF_C.C o FORMS$DEMO_MRF_FOR.FOR o FORMS$DEMO_MRF_DEF.FOR Build commands To build the FORTRAN application, use the following commands: $ FORTRAN FORMS$DEMO_MRF_FOR.FOR $ FORMS TRANSLATE FORMS$DEMO_MRF_FORM.IFDL $ FORMS EXTRACT OBJECT /PORTABLE_API /FORM_LOAD FORMS$DEMO_MRF_FORM.FORM Link the FORTRAN object, the form object, and the shareable image by creating a command file containing the following lines and executing it: $ LINK FORMS$DEMO_MRF_FOR.OBJ, FORMS$DEMO_MRF_FORM.OBJ, SYS$INPUT:/OPT - SYS$LIBRARY:FORMS$PORTABLE_API.EXE/SHARE To build the C application, use the following commands: $ CC FORMS$DEMO_MRF_C.C $ FORMS TRANSLATE FORMS$DEMO_MRF_FORM.IFDL $ FORMS EXTRACT OBJECT /PORTABLE_API /FORM_LOAD FORMS$DEMO_MRF_FORM.FORM Link the C object, the form object, and the shareable image by creating a command file containing the following lines and executing it: $ DEFINE LNK$LIBRARY SYS$LIBRARY:VAXCRTL $ LINK FORMS$DEMO_MRF_C.OBJ, FORMS$DEMO_MRF_FORM.OBJ, SYS$INPUT:/OPT - SYS$LIBRARY:FORMS$PORTABLE_API.EXE/SHARE Mileage Reimbursement Application 6-3 7 ________________________________________________________________ Phone Book Application This chapter describes an application that implements a simple phone directory. 7.1 Overview The Phone Book application displays a list of phone book entries (names and numbers). You can scroll through the list, print the list, and add, remove, and modify entries in the list. The form includes a layout for character-cell display. The form shows examples of: o Multiple-line scrolling o Pull-down menus o Procedural escapes o OUTPUT WHEN clauses o FIRST and CURRENT form data item usage o Printing support 7.2 Running the Phone Book Demo To run the Phone Book demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_phone To use sample data provided in the kit, first copy the file forms$demo_phone_file.dat from the examples directory to your SYS$SCRATCH directory (usually your login directory). The application displays a list of predefined names and phone numbers. To scroll through Phone Book Application 7-1 the list, use the up and down arrow keys and the Next Screen and Prev Screen keys. To make additions or changes to the list, press the Select key and choose from the resulting options. Press the Help key at any time to get help information about an option. To print the list, press the Select key and choose the Print List option. This causes a file named forms$demo_phonebook.txt to be written to your login directory. To leave the demonstration, press the Select key and select the Exit option. 7.3 Implementation Notes Both the IFDL source file and the Pascal source file are heavily commented. Take a look at them to see how the internals of this demonstration work, and, in particular, the following: o Multiple-line scrolling Each occurrence of the group takes up three lines. Thus, when the group is scrolled one instance, three physical lines are scrolled. o Pull-down menus The form shows how to pull down the same menu at various locations on the display. o Procedural escapes The form shows how simple mathematical and more complex procedural escapes are called from the IFDL source. o OUTPUT WHEN Clauses The form shows how some fields (with insertion literals) can be effectively concealed without using CONCEALED WHEN clauses (which require more processing). o First and Current Form Data Item Usage The form shows some examples of using the FIRST and CURRENT form data items to display pull-down menus. o Printing Support 7-2 Phone Book Application The form shows how to use a printing viewport and panel to generate a large hardcopy list. 7.4 Development Notes Files used o FORMS$DEMO_PHONE.IFDL o FORMS$DEMO_PHONE.PAS o FORMS$DEMO_PHONE_FILE.DAT Build commands $ PASCAL/ENVIRONMENT SYS$LIBRARY:FORMS$PAS_DEFINITIONS.PAS $ PASCAL FORMS$DEMO_PHONE.PAS $ FORMS TRANSLATE FORMS$DEMO_PHONE.IFDL $ FORMS EXTRACT OBJECT/OBJECT=PHONE_EXO.OBJ FORMS$DEMO_ PHONE.FORM $ LINK FORMS$DEMO_PHONE.OBJ, PHONE_EXO.OBJ Because the IFDL source for this form contains many comments, using the /NOCOMMENTS qualifier in the FORMS TRANSLATE command slightly reduces the size of the form file. Phone Book Application 7-3 8 ________________________________________________________________ Show Text Library Application This chapter describes an application that accesses an OpenVMS library. 8.1 Overview The Show Text Library demonstration shows text from an OpenVMS library in a scrolling display. The form contains a layout for character-cell display. Functions are defined only for the LK201 keyboard; there are no corresponding VT100 keys defined. The application demonstrates the following features: o Display of text read from an OpenVMS library o Scrolling a text array using increments of both a single line and the size of the scroll area together with a scroll bar indicator o Hinting help panel o Selection of input data from a predefined list o Built-in debug or test display 8.2 Running the Show Text Library Demo To run the Show Text Library demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_show_textlib The demonstration displays a screen with two fields-the default library used by the demo and a key name. Press the Return key to see the library text for this item. Show Text Library Application 8-1 To scroll through the text, use the arrow keys or the Prev Sreen and Next Screen keys. Press PF1/Prev Screen to return to the top of the text, and PF1/Next Screen to go the bottom of the text. Notice how the scroll bar indicator on the right of the screen changes according to whether you are looking at the top page, a middle page, or the bottom page of the text. To return to the key name field, press the Do key. To see a table of available key names for the default library, press the Help key. Use the arrow keys to move around the table and press the Select key when the cursor is on the key that you want to use. This returns you to the key name field with your new selection filled in. To see how the scrolling is controlled, press the F17 key. A display-only panel appears beneath the text and shows the current values for a number of variables: o Lines read-the number of text lines read from the library for this key o Current line-the number of the line containing the cursor o First line-the number of the line appearing at the top of the text display o Max first-the number that the top line would be when the last line is displayed at the bottom of the area; this is used to control the stopping of downward scrolling o By page-(Max first by page)-the number that the top line would be when the last line is displayed in the area; this is not used, but would be used if scrolling were controlled by means of the SCROLL BY PAGE option o Displays is-the number of lines displayed o Base is-the value used as the base for the group With this display showing, try scrolling the text and watch the values for first line change. 8-2 Show Text Library Application You can change the library name, but be aware that this program only works with single-level library keys. It cannot handle multiple-level keys. Do not ask the program to access an OpenVMS help library that has many levels of help topics defined. Handling nested help is left for a future enhancement. To see an implementation of access to a full OpenVMS help library, look at the help supplied in the DECforms CCPED panel editor. To leave the application, press the F10 key or Ctrl/Z. 8.3 Implementation Notes This application comprises a form, a program, and three escape routines. The programs are written in VAX COBOL. In the IFDL source file, notice the use of a form record to pass a group from the form to the escape routine and back. The help on key name is done by a field group that is declared in the form. An icon group could have been used, since the keys are fixed. However, to be ready for a future enhancement to read the keys from the library itself, a field group is used. Notice also that when the key help panel is displayed, the whole group is activated, then the last element is deactivated because it is empty. When a key name is selected, the function response for the SELECT key causes the help panel to be removed and the chosen value to be placed into the key name field, which now becomes the current field. Two viewports are defined to occupy the same space on the display. This is done to emphasize some points about control of display-only panels. Look at the responses that display the panels on these viewports. Each one will remove the other viewport before displaying a panel. This keeps only one of these viewports active at any one time and makes the display cleaner. Show Text Library Application 8-3 Look at the procedural escape call that obtains the text from the library. DECforms deactivates the group before doing the call. When DECforms activates the group on return from the call, only those lines that contain text are activated. A subscript range ensures that only as much (or as little) as needed is activated or deactivated. Look back at the Form Record. The data in the text group is not transferred into the escape routine, and only as many lines as have been read from the text library are transferred back. This is controlled by the TRANSFER clause. In the text scroll panel, the lines in the text group are defined as NO DATA INPUT so that the cursor can move to them for control of scrolling, but they cannot be changed. All navigation keys are bound to internal responses that do the scrolling up and down. Using internal responses saves space within the form and aids in maintaining it (compared to repeating the steps for each key). A "dummy" field is used to position the cursor. The scrolling is controlled by changing the value of the FIRST data item. Two procedural escape calls are used to add to and subtract from this item. 8.4 Development Notes The form is translated and made into an object file, which is then linked in with the driver program and the procedural escape code to form a single file. Files used o FORMS$DEMO_SHOW_TEXTLIB.IFDL o FORMS$DEMO_SHOW_TEXTLIB.COB Contains the procedural escapes: FORMS$DEMO_ADD_LONGWORD FORMS$DEMO_SUBTRACT_LONGWORD o FORMS$DEMO_TEXTLIB.COB 8-4 Show Text Library Application Build commands $ FORMS TRANSLATE FORMS$DEMO_SHOW_TEXTLIB $ FORMS EXTRACT OBJECT FORMS$DEMO_SHOW_TEXTLIB - _$ /OBJECT=FORMS$DEMO_SHOW_TEXTLIB_FORM $ COBOL FORMS$DEMO_SHOW_TEXTLIB $ COBOL FORMS$DEMO_TEXTLIB $ LINK FORMS$DEMO_SHOW_TEXTLIB, FORMS$DEMO_SHOW_TEXTLIB_ FORM,- _$ FORMS$DEMO_TEXTLIB Show Text Library Application 8-5 9 ________________________________________________________________ Timer Application This chapter describes an application that asynchronously updates a field in the form. 9.1 Overview The Timer application demonstrates a method for updating any set of fields asynchronously. The form includes a layout for character-cell display. 9.2 Running the Timer Demo To run the Timer demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_timer $ run forms$examples:forms$demo_timer_c $ run forms$examples:forms$demo_threaded_timer The application displays the current time and updates it every second, even while you are entering data into the two fields below. To leave the demonstration, delete all data from the fields and press the F10 key or Ctrl/Z. 9.3 Implementation Notes The application enables two sessions to the same form: one for the normal non-AST (or main) form work and the other for the AST (or timer) work. Once the two sessions are enabled, a single SEND is performed at non-AST (or main) level for the AST (or timer) session and a timer is started to invoke an AST-routine after a period of time (or a thread in the threaded example). The normal non-AST (or main) work is then started. In this example a simple RECEIVE loop is used. Timer Application 9-1 Displaying the time every second is probably too wasteful of CPU resources to be usuable in a production application, but suits the purposes of this demonstration. The method for doing asynchronous screen updates is sound; that is, you can use this method to update the screen with any information, not just time. Be aware of a restriction in DECforms concerning asynchronous screen update: When the cursor is on an icon and you do an asynchronous screen update (FORMS$SEND), the cursor remains on the last field updated by FORMS$SEND, instead of returning to the user's current icon. This is a known OpenVMS problem that only affects display; DECforms thinks the cursor is still on the icon. The next action you take to move the cursor (pressing an arrow key, for example) restores the cursor to where it belongs. The demo uses 6 source files for the COBOL version of the example: o FORMS$DEMO_TIMER_AST.COB The main program; it enables both sessions (one for the AST, and one for the regular session) o FORMS$DEMO_TIMER_AST_ROUTINE.COB A subroutine that performs a SEND at AST level; it sends the new time in the form record o FORMS$DEMO_TIMER_COMP_ROUTINE.COB A subroutine that sets up a new timer when the previous AST SEND completes; it is called as the AST completion routine from the asynchronous FORMS$SEND o FORMS$DEMO_TIMER_CHECK_STATUS.COB A subroutine that checks the return status of all DECforms calls and prints an error message if anything goes wrong o FORMS$DEMO_TIMER_SET_TIMER.COB A subroutine that sets up the timer o FORMS$DEMO_TIMER_FORM.IFDL The form, which contains two panels: one displayed by the AST session, the other by the non-AST session 9-2 Timer Application The program's flow of control is as follows: FORMS$DEMO_TIMER_AST.COB-This program sets up the forms session, as well as the initial one-second timer. It then goes into a loop, asking the user for data and waiting to exit. FORMS$DEMO_TIMER_AST_ROUTINE.COB-This routine is executed whenever the one-second AST timer goes off. It sends the current time to the AST-session (which causes the screen to update). It tells the form manager to call FORMS$DEMO_ TIMER_COMP_ROUTINE when it finishes. FORMS$DEMO_TIMER_COMP_ROUTINE.COB-This routine is called when the asynchronous FORMS$SEND is complete. It calls FORMS$DEMO_TIMER_SET_TIMER to set the timer up to go off after one second. The demo uses 2 source files for the C version of the example: o FORMS$DEMO_TIMER_C.C This module contains the full source of the example. o FORMS$DEMO_TIMER_FORM.IFDL The form, which contains two panels: one displayed by the AST session, the other by the non-AST session ________________________Note ________________________ While the form is packaged as a single IFDL file, it is being used as if it were two completely different IFDL form files. In particular, the two sessions do not share data. The non-AST session cannot access the AST_TIME_FIELD form data item that is being updated every second. The non-AST session has its copy of this form data item (which never changes in this demo). _____________________________________________________ The demo uses 2 source files for the Threaded C version of the example: o FORMS$DEMO_THREADED_TIMER_C.C This module contains the full source of the example. Timer Application 9-3 o FORMS$DEMO_THREADED_TIMER_FORM.IFDL The form, which contains two panels: one displayed by the MAIN session, the other by the TIMER session 9.4 Development Notes Files used o FORMS$DEMO_TIMER_FORM.IFDL o FORMS$DEMO_TIMER_AST.COB o FORMS$DEMO_TIMER_AST_ROUTINE.COB o FORMS$DEMO_TIMER_CHECK_STATUS.COB o FORMS$DEMO_TIMER_COMP_ROUTINE.COB o FORMS$DEMO_TIMER_SET_TIMER.COB o FORMS$DEMO_TIMER.C o FORMS$DEMO_THREADED_TIMER.C o FORMS$DEMO_THREADED_TIMER_FORM.IFDL Build commands First, build the form; since the form will be linked in with the application, you need to use FORMS EXTRACT to build an object file: $ FORMS TRANSLATE FORMS$DEMO_TIMER_FORM /NOCOMMENTS $ FORMS EXTRACT OBJECT FORMS$DEMO_TIMER_FORM Second, compile all the COBOL sources: $ COBOL FORMS$DEMO_TIMER_AST.COB $ COBOL FORMS$DEMO_TIMER_AST_ROUTINE.COB $ COBOL FORMS$DEMO_TIMER_CHECK_STATUS.COB $ COBOL FORMS$DEMO_TIMER_COMP_ROUTINE.COB $ COBOL FORMS$DEMO_TIMER_SET_TIMER.COB Finally, link it all together: 9-4 Timer Application $ LINK FORMS$DEMO_TIMER_AST.OBJ, - _$ FORMS$DEMO_TIMER_AST_ROUTINE.OBJ, - _$ FORMS$DEMO_TIMER_CHECK_STATUS.OBJ, - _$ FORMS$DEMO_TIMER_COMP_ROUTINE.OBJ, - _$ FORMS$DEMO_TIMER_SET_TIMER.OBJ, - _$ FORMS$DEMO_TIMER_FORM.OBJ - _$ /EXE=FORMS$DEMO_TIMER.EXE For the C version of the example: $ FORMS TRANSLATE FORMS$DEMO_TIMER_FORM /NOCOMMENTS $ FORMS EXTRACT OBJECT FORMS$DEMO_TIMER_FORM $ CC FORMS$DEMO_TIMER_C.C $ LINK FORMS$DEMO_TIMER_C.OBJ, FORMS$DEMO_TIMER_FORM.OBJ For the Threaded C version of the example: $ FORMS TRANSLATE FORMS$DEMO_THREADED_TIMER_FORM /NOCOMMENTS $ FORMS EXTRACT OBJECT FORMS$DEMO_THREADED_TIMER_FORM $ CC FORMS$DEMO_THREADED_TIMER.C $ LINK FORMS$DEMO_THREADED_TIMER.OBJ, FORMS$DEMO_THREADED_TIMER_FORM.OBJ, SYS$INPUT/OPT {CR} SYS$SHARE:CMA$OPEN_RTL/SHARE {CTRL/Z} Timer Application 9-5 10 ________________________________________________________________ TM Application This chapter describes an application that demonstrates portable use of the TM data type. 10.1 Overview The TM application displays the current date and time and waits for you to press a key to exit. It illustrates the use of the TM data type in a way that conforms to the X /Open Portability Guide. The form contains a layout for character-cell display. 10.2 Running the TM Demo To run the TM demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_tm The application displays the current date and time. To leave the application, press any key except F1 through F5. 10.3 Implementation Notes The demo is made up of two source files: o FORMS$DEMO_TM.C The application program. The program enables the form, sends it a record consisting of the current time formatted as a TM item, disables the form, and exits. o FORMS$DEMO_TM_FORM.IFDL TM Application 10-1 The form. It contains a single panel with three panel fields, and a single record containing a single record field. When the application sends the record field, the forms activates a panel field containing a blank so that the display remains visible and the cursor out of the way until you press a key. 10.4 Development Notes Files used o FORMS$DEMO_TM_FORM.IFDL o FORMS$DEMO_TM.C Build commands First, build the form; since the form will be linked with the portable application, you must use the FORMS EXTRACT OBJECT/PORTABLE_API command to build an object file: $ FORMS TRANSLATE FORMS$DEMO_TM_FORM $ FORMS EXTRACT OBJECT /PORTABLE_API FORMS$DEMO_TM_FORM Second, compile the application: $ CC FORMS$DEMO_TM Finally, link the files together by creating a command file with the following lines and executing it: $ LINK FORMS$DEMO_TM,FORMS$DEMO_TM_FORM,SYS$INPUT:/OPT SYS$SHARE:VAXCRTL.EXE/SHARE SYS$SHARE:FORMS$PORTABLE_API.EXE/SHARE 10-2 TM Application 11 ________________________________________________________________ Track and Field Application This chapter introduces the Track and Field application that is described in detail in Part II of the DECforms Style Guide for Character-Cell Devices. 11.1 Overview The Track and Field application simulates a registration system for a track and field sporting event. The application demonstrates design techniques that emululate a DECwindows Motif user interface on character-cell devices. Each of the functions implemented in the demo illustrates a specific design concept discussed in the DECforms Style Guide for Character-Cell Devices. For example, the main screen demonstrates the use of a bar menu. The form includes a layout for character-cell display. 11.2 Running the Track and Field Demo To run the Track and Field demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$demo_track_and_field The application displays a bar menu with several options. Use the left and right arrow keys to navigate among the options and the Select key to make a selection. Use arrow keys to navigate the resulting pull-down or pop-up menus and the Select key to make a selection. Not all options are implemented, since the purpose of the application is to illustrate user interface design techniques. For example, the Schedule menu is not Track and Field Application 11-1 implemented, nor are all the choices on the Registration menu. To leave any menu that is not fully operational, press the F8 key. To leave the application, select Exit from the File menu, or press the F10 key or Ctrl/Z. 11.3 Implementation Notes The demo is made up of two source files: o FORMS$DEMO_TRACK_AND_FIELD.C The application program. The program enables the form and contains procedural escape routines to perform platform-specific functions. o FORMS$DEMO_TRACK_AND_FIELD.IFDL The form. The form simulates a registration system for a track and field event. It illustrates IFDL coding techniques for implementing DECforms style, including: o Controls - Push buttons - Radio fields - Check fields - Text entry fields - List groups - Option fields o Menus - Bar - Pull-down - Pop-up o Dialog boxes - Work in progress - Informational 11-2 Track and Field Application - File selection The application is written using the DECforms portable API. For a detailed description of the application, see the DECforms Style Guide for Character-Cell Devices. The source files for the form and program are contained in appendixes in that guide. 11.4 Development Notes Files used o FORMS$DEMO_TRACK_AND_FIELD.IFDL o FORMS$DEMO_TRACK_AND_FIELD.C Build commands First, build the form; since the form will be linked in with the portable application, you must use the FORMS EXTRACT OBJECT/PORTABLE_API command to build an object file: $ FORMS TRANSLATE FORMS$DEMO_TRACK_AND_FIELD $ FORMS EXTRACT OBJECT /PORTABLE_API FORMS$DEMO_TRACK_AND_FIELD - _$/OUTPUT=FORMS$DEMO_TRACK_AND_FIELD_FORM.OBJ Second, compile the application: $ CC FORMS$DEMO_TRACK_AND_FIELD Finally, link it together by creating a command file containing the following lines and executing it: $ LINK FORMS$DEMO_TRACK_AND_FIELD, FORMS$DEMO_TRACK_AND_FIELD_FORM, - SYS$INPUT:/OPTIONS SYS$SHARE:VAXCRTL.EXE/SHARE SYS$SHARE:FORMS$PORTABLE_API.EXE/SHARE Track and Field Application 11-3 12 ________________________________________________________________ Introductory Sample Application This chapter introduces the introductory sample checking application that is described in detail in Part II of the DECforms Guide to Developing an Application. 12.1 Overview The introductory sample application is a simple forms application for maintaining a personal checking account. The form includes layouts for character-cell and window display and printed output. The demo shows the following features: o Use of data declarations o Use of OpenVMS API request calls o Simple panel design for accepting operator input o Support for printing the contents of a panel 12.2 Running the Introductory Sample Demo Determine the type of device on which you will display the form, then enter one of the following commands: For Character Cell Devices $ define forms$default_device sys$input For Window Devices $ define forms$default_device decw$display To run the introductory sample demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following command: $ run forms$examples:forms$sample_program Introductory Sample Application 12-1 The panel initially displayed supplies choices for writing a check, making a deposit, or exiting the application. The panel for writing a check shows fields for entering the name of the person to whom the check will be paid, the amount of the check, and memo text. You must enter data in the Pay to and Amount fields before you can move to the next or previous field. Filling the Memo field is optional. For the amount, you cannot enter a number that is greater than the balance shown on the choice panel (the first panel displayed). This restriction is specified in the form, not in the application program. On the panel used for making a deposit, you must enter data in the Deposit field before you can continue. Pressing Ctrl/Z or Ctrl/D when you are done entering data on a panel sends the panel's data to the application program and displays the choice panel (if you are on the deposit or check panel) or the chosen panel (if you are on the choice panel). Use the following keys to enter and edit data: __________________________________________________________ To ________________Press_______________ (Character ______________________Cell)_______(DECwindows)____________ Move to the next Return PF4 field Move to the previous F12 PF3 field Move the cursor Left arrow Left arrow within a field Right Right arrow arrow Delete the character Delete Delete to the left of the cursor____________________________________________________ To print a copy of a check, press Ctrl/P when the check panel is active. This copies the contents of the check panel to a file called ddif_form.doc in the current 12-2 Introductory Sample Application directory. Each time you press Ctrl/P, a copy of the check is saved to this file. When you leave the application, you can convert the file to PostScript format and print it. To convert the file to PostScript format, at the system prompt enter the command: $ convert/document ddif_form.doc ddif_form.ps/format=ps To leave the application, choose option 1 from the choice panel. 12.3 Implementation Notes For detailed information about the IFDL source code used in this application, see Part II of the DECforms Guide to Developing an Application. 12.4 Development Notes Files used o FORMS$SAMPLE_FORM.IFDL o FORMS$SAMPLE_COMMON.F o FORMS$SAMPLE_PROGRAM_FORTRAN.FOR o FORMS$SAMPLE_PROGRAM_C.C Build commands To build the C application, use the following commands: $ CC FORMS$SAMPLE_PROGRAM_C.C $ FORMS TRANSLATE FORMS$SAMPLE_FORM.IFDL $ FORMS EXTRACT OBJECT /NOFORM_LOAD FORMS$SAMPLE_FORM.FORM $ LINK FORMS$SAMPLE_PROGRAM_C.OBJ, FORMS$SAMPLE_FORM.OBJ To build the FORTRAN application, use the following commands: $ FORTRAN FORMS$SAMPLE_PROGRAM_FORTRAN.FOR $ FORMS TRANSLATE FORMS$SAMPLE_FORM.IFDL $ FORMS EXTRACT OBJECT /NOFORM_LOAD FORMS$SAMPLE_FORM.FORM $ LINK FORMS$SAMPLE_PROGRAM_FORTRAN.OBJ, FORMS$SAMPLE_FORM.OBJ Introductory Sample Application 12-3 13 ________________________________________________________________ Calculator Form This chapter describes a form used to simulate a calculator. 13.1 Overview The Calculator demo supplies a version of a "supermarket" calculator that performs simple arithmetic and displays the results in a fixed point format. Its purpose is to show how to use IFDL function responses exclusively to generate data and perform useful work. It also demonstrates the extensive use of OpenVMS STR$ run-time library routines for all calculated results. The demo includes layouts for character-cell and DECwindows Motif display. 13.2 Running the Calculator Demo Determine the type of device on which you will display the form, then enter one of the following commands: For Character-Cell Devices $ define forms$default_device sys$input For DECwindows Motif Devices $ define forms$default_device decw$display To run the Calculator demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_calculator_form A likeness of a four-function calculator keypad is displayed. Use the numeric keypad to enter numbers and perform simple calculations. Calculator Form 13-1 Use the keys on the numeric keypad of your terminal or select the icons or buttons that appear on the screen to perform addition, subtraction, multiplication, or division. In a character-cell environment, use the arrow keys to move between icons, and the Select key to select an icon. In a DECwindows Motif environment, use the mouse to select (trigger) a button. First, enter a number, followed by one of the operation keys ( +, -, *, or / ). Next, enter a second number followed by the equal sign key (=). The results of the calculation are displayed. Note that the operation keys may not be marked the same as their visual representation on the screen. However, their relative positions are correct. The equivalents for an LK201 keyboard are as follows: __________________________________________________________ LK201 Numeric Screen Keypad______Character___Action____________________________ PF1 C Clears the currently displayed entry when pressed once. Clears the display and all internal registers when pressed twice in a row. PF2 OFF Removes the calculator from the screen and exits the form. PF3 / Prepares to divide the current display value by the next entered value. PF4 * Prepares to multiply the current display value by by the next entered value. - - Prepares to subtract the next entered value from the current display value. , + Prepares to add the current display value to the next entered value. 13-2 Calculator Form __________________________________________________________ LK201 Numeric Screen Keypad______Character___Action____________________________ ENTER = Performs the current pending calculation and displays the results. 0-9 0-9 Appends the number of the key to the display. If it is the first digit entered after an operation or equal sign key, it clears the display before appending the digit. . . Prepares for numeric entry to the right of the displayed decimal ________________________point.____________________________ The calculator has two other methods of operation: continuous and chained. Continuous operation is simply one calculation followed by another, using the oper- ation keys but not the equal sign key. For example, Number-A - Number-B * Number-C +... continuously calculates intermediate results and displays them. Chained calculations are similar to continuous cal- culations except that the calculation is continued after the equal sign key is pressed. For example, Number-A + Number-B = * Number-C = would add A to B, display the results, and then use the displayed results as the first number of the multiplication by C. The last press of the equal sign key would calculate that product. The primary difference between the two methods is in where the next entered number is stored internally. Functionally, they are equivalent. In fact, in continuous calculations, there is an implied equals before every operator key press after the first, until the equal sign key is pressed again. To leave the demo, press the PF2 key on the keypad or select the OFF icon or push button. Calculator Form 13-3 13.3 Implementation Notes The IFDL source file is commented in detail. Please refer to it for more information. This form shows examples of: o Implementor-Defined Functions and Keys Shows how to define FUNCTION responses and bind them to specific keys to perform a desired set of actions. The character-cell layout shows how HIGHLIGHT WHEN clauses can be used to give visual feedback (the flashing of the icon) to a user action. This visual feedback happens automatically in the DECwindows Motif layout. o OpenVMS Run-Time Library Calls Shows the use of the CALL response step to invoke OpenVMS RTL routines. In this demo, the STR$ RTL routines are used for virtually all the arithmetic calculations. Additionally, STR$APPEND is used to create the display as a number is entered. Various substring and concatenation routines are used to display the results. o Integer Function Array Shows a method for performing Let x = f(x) class functions for a limited number of integer values of x. This demo implements a decrement function (f(x) = x - 1) and an absolute value function (f(x) = |x|) for integers -20 through +20. Other simple math functions could be implemented in the same way. 13.4 Development Notes Files used o FORMS$DEMO_CALCULATOR_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_CALCULATOR_FORM /NOCOMMENTS $ FORMS EXTRACT OBJECT FORMS$DEMO_CALCULATOR_FORM $ LINK FORMS$DEMO_CALCULATOR_FORM /SHAREABLE 13-4 Calculator Form Because the IFDL source file for this form contains comments, using the /NOCOMMENTS qualifier will result in a smaller form file. Calculator Form 13-5 14 ________________________________________________________________ Command Recall Form This chapter describes a form that illustrates command recall. 14.1 Overview The Command Recall demo shows how entries made in a field can be remembered within the form and recalled by the operator without program intervention. The form includes a layout for character-cell display. The demo shows the following features: o Scrolling a group such that only one element is displayed on the screen. o Scrolling a multi-line group. o Using AUTOSKIP and BOUNDARY CURSOR conditions to move automatically from one field to the next. o Manipulating a circular buffer by directly editing entries. o Manipulating a circular buffer by using an intermediate field. 14.2 Running the Command Recall Demo To run the Command Recall demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable := $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_command_recall_form Command Recall Form 14-1 The introductory screen shows two options: "VMS" style, which uses an intermediate pair of fields and places new entries at the end of the buffer, and Circular buffer style, which directly modifies the buffer. Select the style you want to see and follow the instruc- tions on the screen. To leave the demo at any time, press the F10 key or Ctrl /Z. 14.3 Implementation Notes A form record uses a TRANSFER clause to pass the current entry back to a program. Note the use of fixed pointers in the group. This does away with the need for procedural escape calls to add or subtract to an index (using modular arithmetic due to the circular nature of the buffer). 14.4 Development Notes Files used o FORMS$DEMO_COMMAND_RECALL_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_COMMAND_RECALL_FORM $ FORMS EXTRACT OBJECT FORMS$DEMO_COMMAND_RECALL_FORM $ LINK FORMS$DEMO_COMMAND_RECALL_FORM /SHAREABLE 14-2 Command Recall Form 15 ________________________________________________________________ CopyCat Form This chapter describes a form that supports both color and monochrome display devices. 15.1 Overview The CopyCat demo is a game that shows a method of creating one form, which supports both color terminals and black and white terminals. It is intended to be used with a trace file. The form includes a layout for character-cell display. The demo shows the following features: o Advanced uses of color o The effect of POSITION steps on response steps o Use of special IFDL keypad-related functions o Use of HIGHLIGHT WHEN clauses 15.2 Running the Copycat Demo To create a trace file, enter the following command: $ define/user forms$trace true Using the /user qualifier causes tracing to occur for only this single run of the demo. The trace file is called forms$demo_copycat_form.trace and is written to your current default directory. If you want the trace file to go to another directory, define the logical name FORMS$TRACE_FILE as that directory. For example: $ define forms$trace_file mydisk:[mydir] CopyCat Form 15-1 To run the Copycat demo, enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_copycat_form You can also run the Copycat demo by selecting it from the FORMS$DEMO menu described in Chapter 2. However, you cannot obtain a trace file because tracing is temporarily turned off when using the FORMS$DEMO command procedure. The main screen displays four boxes. When you start the game, individual boxes flash in a series. The object is to duplicate the series by pressing corresponding keypad keys. For more information, press the Help key. To start the demo, press the Return key. To leave the demo, press the F10 key or Ctrl/Z. 15.3 Implementation Notes The IFDL source file is heavily commented. Take a look at it to see how the internals of this demo work. This form shows examples of: o A Color and Monochrome Application The form shows how to create an application that can be run on a black and white screen or on a color screen by using the FOR clause in attributes to get different effects. There are extensive comments in the IFDL file that explain how the demo uses color and how it handles the variations between different terminal types. o Special IFDL Function Definitions The form shows an example of the BUILTIN FUNCTION, USER FUNCTION, and the UNDEFINED FUNCTION responses. o POSITION Response Steps The form shows how a POSITION response step can move the cursor to a panel field or icon and to another field or icon without the operator entering any input. This happens because a POSITION response step in the field or icon ENTRY RESPONSE repositions the cursor before you actually enter input. o HIGHLIGHT WHEN Clauses 15-2 CopyCat Form The form shows how HIGHLIGHT WHEN clauses are applied immediately, as soon as the condition changes. This is how the flashing is done. o Response Step Execution Order By running this form with tracing turned on, you can get a good idea of which response steps are executed immediately (like LET, DISPLAY, REMOVE...), and how other steps (like POSITION...) cause other responses (ENTRY and EXIT RESPONSES) to be executed. 15.4 Development Notes Files used o FORMS$DEMO_COPYCAT_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_COPYCAT_FORM /NOCOMMENTS $ FORMS EXTRACT OBJECT FORMS$DEMO_COPYCAT_FORM $ LINK FORMS$DEMO_COPYCAT_FORM /SHAREABLE Because the IFDL source for this form contains many comments, using the /NOCOMMENTS qualifier in the FORMS TRANSLATE command slightly reduces the size of the form file. CopyCat Form 15-3 16 ________________________________________________________________ Globe Form This chapter describes a form that demonstrates the use of graphics to display a map of the world. It supplies a layout for character-cell display. _____________________Disclaimer _____________________ The political divisions shown on the map are not a statement concerning the rights of nations or their peoples. The selection of entities to include or exclude was made strictly according to convenience and what would fit into the severely limited digitized and distorted screen territory available. The author avers that the only thing he had in mind was fun, and regrets not having the energy to complete the detailed maps in the remainder of the world. Contributions will be cheerfully accepted and possibly included in future versions. For fun, see if you can find the "prize" in one of the detailed maps. Hint: think DIGITAL Software Engineering. _____________________________________________________ 16.1 Overview The demo is intended to push the limits of "graphical" appearance on a character-cell terminal and to show interesting use of the activation list. (For a similar demo designed for window devices, see Chapter 17.) The demo consists entirely of "graphical" entities-it has no fields to fill in. It uses the Rule character set extensively to present the appearance of a globe of earth, mapped to a 24 by 80 screen. Continents, countries, and Globe Form 16-1 sub-country divisions are implemented as icons made up of polylines and text literals. It includes some non-standard use of the HELP activation list (to get either help or confirmation of cursor movement) and it includes some non-standard navigational features. The demo shows the following features: o The first panel shows an equatorial (Mercator) projection of the globe, digitized to a 24 by 80 screen. Interesting parts of the globe are defined as icons. You can navigate across the globe (to different icons) by using the arrow keys. You can "zoom in" to each of the areas you can visit. o There are detailed maps of several land areas and incomplete, sketchy panels for the remainder of the world. o The detailed maps contain icons at the capital cities of the various political subdivisions shown on that map. Some of the maps show several countries; such maps show the country capitals. Other maps show only one or two countries, with state or provincial capitals displayed. o In a detailed map, you can discover the name of the political entity and its capital by pressing the Help key once. Pressing the Help key again brings up a help panel that tells you what various keys do. o From a detailed map, you can "zoom out" to the entire globe. Zooming out takes you to the spot on the globe corresponding to the area you came from in the detailed map. o Since moving from one detailed map to another may take a long time (because many, many characters are written to the screen), whenever a movement of that sort is requested, a pop-up panel appears, asking for confirmation of the movement. This pop-up panel actually uses the help mechanism and shows how the subactivation list feature of help can be used effectively. 16-2 Globe Form The demo can run from VTxxx series terminals; key bindings for the function keys are defined both for the LKxxx keyboards and the VT100 keyboard. 16.2 Running the Globe Demo To run the Globe demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_globe_form The first panel shows a map of the entire globe. The "Arctic" is reversed, showing you where you are now. To move from one area to another, use the arrow keys. To display a detailed map of an area, move to that area and press the Select key, Return key, Enter key, or PF1- down arrow. Diamonds represent capitals. To move between capitals, use the arrow keys. The message panel (line 24) displays the name of the country and its capital. To display a help panel describing the available function keys, press the Help key twice or the PF2 key twice. To return to the map, press PF1-Help or PF1-PF2. The help panel remains displayed; to make it disappear, press an arrow key. If a move would take you off the displayed map, a pop-up panel labelled "Travel Alert" appears, warning you that you will travel to another area and asking you if you want to go there. Select either the "No" or "Yes" icon. To "zoom out" to the whole world, press PF1-up arrow, PF1-Select, PF1-Return, or PF1-Enter. To leave the demo at any time, press the F10 key or Ctrl /Z. 16.3 Implementation Notes The following list contains descriptions of the interest- ing aspects of the demo code: o Globe Panel Globe Form 16-3 You start out on the globe panel, showing the whole world. You can use the arrow keys to navigate, stepping from continental masses to other masses or to various oceans. If you press the Select key, Return key, Enter key or PF1-Down arrow, you zoom into that part of the world. Navigation into and out of oceans is performed in an interesting manner. Where should you go, for example, when you request a movement to the east from the Atlantic Ocean? It could be Northern Europe, Southern Europe, Northern Africa, or Southern Africa, all of which lie to the east of the Atlantic Ocean. If you have never been to any of those land masses, the form will send you to Southern Europe. However, if you moved into the Atlantic Ocean by moving west from any of those land masses, you will be moved back to that same land mass. This effect is achieved by keeping a variable in the form and querying it at the appropriate function response. For details, see the panel EARTH_ PANEL; look at ICON ATLANTIC_OCEAN and the four icons for the four land masses named. o Detailed Map Panels Each detailed map panel contains one or more countries or subdivisions of countries, depending on the size of the area shown. Each country or subdivision has an icon displayed as a diamond; the icon is in the approximate place of the capital of that country or subdivision. Occasionally, some islands are also displayed; some of them are so small that the diamond icon is the only visible part of the island. You can navigate from capital to capital using the arrows. Occasionally, you may move to a different capital than you expect. Usually, the navigation rules are designed for reasonably rectilinear movement. However, sometimes they are designed to recognize the reality of real geography. For example, if you move up (north), the choices for what is "up" must consider whether you are moving up from the capital or from the country as a whole; the two often result in a different choices of destination. No particular algorithm was chosen to determine what was used in each case. 16-4 Globe Form As you arrive at each country, the entry response for the country automatically displays the help message for the country, resulting in that country's name and capital appearing on line 24. If line 24 gets changed for any reason (for example, by an error message), you can press the Help key or the PF2 key to learn the name of the political entity you are in and the name of the capital (if any). Islands belonging to a non-contiguous country have that country identified in parentheses. o Sketchy, Incomplete Panels Some panels consist only of text and a number of text icons that you can visit. Pressing either the Select key or the Return key will move you to the map corresponding to that icon. o Message and Help Panels The message panel and the help panel occasionally cover up parts of maps. The form removes them on the first arrow movement you enter. Alternately, you can press the PF4 key and they will be removed immediately. o Icons Navigation between all icons on the whole globe panel and on the detailed map panel is accomplished by means of function responses for each icon. The UP and DOWN ITEM functions are bound to the up and down arrows; each icon then has a function response for UP ITEM and DOWN ITEM. Since an icon is not allowed to have data entered for it, whenever the left and right arrow keys are pressed while in the icon, the BOUNDARY CURSOR functions are triggered; each icon has a BOUNDARY CURSOR LEFT and a BOUNDARY CURSOR RIGHT function defined for it. Navigation is done this way instead of directly using the default UP/DOWN/RIGHT/LEFT ITEM functions since the default functions are line and column oriented rather than geographically oriented. The sketchy panels use the default steps of POSITION TO LEFT/RIGHT/UP/DOWN ITEM instead of having individual navigational steps defined for them. It is instructive to note the difference in navigation, depending on the arrangement of icons in such panels. Globe Form 16-5 o Subactivation List The ENTER HELP and EXIT HELP response steps are used by the default HELP and TERMINATE HELP function responses. ENTER HELP starts a new activation list immediately and doesn't perform any exit responses for the current item. EXIT HELP returns to the original activation list. In this application, ENTER HELP is also used for confirmation of movement. If the form had merely asked for a new panel to be activated for this confirmation, it would also have had to deal with exiting the current panel. This is avoided by using the ENTER HELP response step and starting a new activation list. Of course, this means that the help form must be prepared to deal with either help or with the confirmation request. It does this by querying a variable, a form data item that is set by the response that executes the ENTER HELP response step. If this variable is non-null, then movement confirmation is requested; if it is null, then help has been requested. 16.4 Development Notes Files used o FORMS$DEMO_GLOBE_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_GLOBE_FORM $ FORMS EXTRACT OBJECT FORMS$DEMO_GLOBE_FORM $ LINK FORMS$DEMO_GLOBE_FORM /SHAREABLE 16-6 Globe Form 17 ________________________________________________________________ World Form This chapter describes a form that demonstrates the use of graphics to display a map of the world. It supplies a layout for window display. _____________________Disclaimer _____________________ The political divisions shown on the map are not a statement concerning the rights of nations or their peoples. The map boundaries, and the selection of entities to include or exclude, were taken from a public domain database distributed jointly by the U.S. Center for Communicable Diseases and the World Health Organization, as listed in the EPIMAP program provided by them for window devices. The database is somewhat out of date, not containing any of the political reorganizations that have taken place since about 1988. For example, the former Soviet Union and Yugoslavia have not yet been broken up. (The author did, however, rejoin East and West Germany.) The database does not have a consistent resolution, so that some entities below the world level are "chunky," not containing enough points to be a good representation of the entity. The author avers that the only thing he had in mind was fun, and regrets not having the energy to complete the detailed maps in the remainder of the world. Contributions will be cheerfully accepted and possibly included in future versions. _____________________________________________________ World Form 17-1 17.1 Overview The demo provides a realistic map of the world and many countries that you may want to include in your applications. The window version of the world shows a significant advantage in graphics over the character-cell version described in Chapter 16: resolution of the display is sufficient to provide a more realistic representation and to show some of the curvature of the earth as mapped to a 2-D representation. This demo has no fields to fill in; it consists entirely of panels containing maps and push buttons. Continents, countries, and sub-country divisions are displayed as closed polylines. Push buttons let you zoom into the identified country for a closer look. The primary mode of interaction is through the mouse. Normal navigation and push button selection can be made through the default bindings of the platform. 17.2 Running the World Demo To run the World demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ define forms$default_device decw$display $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_world_form The first panel shows a map of the world. The Exit push button has focus. Clicking on it terminates the application, as will pressing the Return key, the Enter key, or the space bar while the Exit push button has focus. To move to an area of the world, click on the appropriate push button. A new panel displays the countries of that area. To dismiss the panel, click on the Return to World push button. The returns control to the world panel. Most of the countries have literals or buttons naming them. Clicking on a button pops up a new panel showing the country and any political subdivisions. Those subdivisions are not labelled, but if you look in the IFDL for the 17-2 World Form demo, you can find the names, should you wish to use this map- or any other map. To leave the demo at any time, press Ctrl/D or Ctrl/Z, or click on the "Exit" button on the World panel. 17.3 Implementation Notes As mentioned previously, the selection of points for the maps were obtained from a public domain database. You are free to use these maps in your applications. The author of this IFDL file used the EPIMAP product "export" feature that outputs the points of each map to a DECwindows file. He then wrote a C program that read that file, scaled the the points to the size of a typical window screen, and wrote out an IFDL panel definition containing the points as IFDL polyline literals. Further work involved adding push buttons to identify countries for which there were detailed maps and providing the response steps to navigate to those countries and back again. The author intentionally did no additional special navigational aids since using the mouse and the builtin keyboard bindings (arrow keys) seems to be sufficient. Hence, the IFDL response code is not terribly interesting. The map points are the most interesting features of this demo. Each polyline literal is closed and represents an area. Some countries or political divisions are a single area. Some countries have several areas represented (for example, a country that has several islands). Some countries (mainly islands) are too small to be represented by anything but a point, so they have a line leading to a square representing that country. Each area has an IFDL comment stating what country that area belongs to in case you wish to extract that country for your own uses. 17.4 Development Notes Due to size considerations, only the form file is supplied in the kit. If you want to examine the IFDL source code, back translate the form file. World Form 17-3 Files used o FORMS$DEMO_WORLD_FORM.FORM Build commands $ FORMS EXTRACT OBJECT FORMS$DEMO_WORLD_FORM $ LINK FORMS$DEMO_WORLD_FORM /SHAREABLE 17-4 World Form 18 ________________________________________________________________ Order Entry Application Form This chapter describes a form that emulates a DECwindows user interface style for a data entry application. 18.1 Overview The Order Entry demo shows how a typical commercial application for order entry might look using the DECwindows style of screen appearance as applied to a character-cell terminal (and also as used in the DECforms interactive development utilities FDE and Character-cell Panel Editor). The form includes a layout for character- cell display. The demo is designed to be run from a VT200 or VT300 series terminal; it contains key bindings only for the function keys on the LK201 keyboard. Equivalent VT100 keys are not defined. The demo shows the following features: o Introductory screens and help screen o DECwindows style appearance on a character-cell terminal o Strip menu using icons with pull-down menus from some of the choices o Data entry panel showing left-justified alphanumeric, right-justified alphanumeric and numeric, and decimal input fields o Display-only scroll region where a summary of each order entry line is placed (this region may be browsed by use of function keys; scroll bars are placed on either side of the region to show when there are entries above or below the visible region) Order Entry Application Form 18-1 o Pop-up data display panel, selected by a series of pull-down menus o Border around three sides of the message panel o A printing panel with data formatted differently from the interactive panels o Simple use of color o How to clear the screen and then refresh it in order to start a demo mid-way through the form interaction 18.2 Running the Order Entry Demo To run the Order Entry demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_order_entry_form The demo displays an introductory screen with basic instructions for how to use the demo and how to preload data into the order entry panels. Use the arrow keys to move between icons and the Select key to select an icon. Selecting the More Information icon displays a second screen that lists the major features of the demo. Selecting the See the Demo icon displays the main demo screen. To see help about the demo, press the Help key at any time. To leave the demo, select the Exit icon from the main screen menu icons. Main Screen The main screen contains six sections: 1. Company Name Line-displayed using a double-wide font and physically on line 1 of the terminal 2. Menu Icons-six choices for order entry operations Use the arrow keys to move between the icons and the Select key to select a choice. Note that there is no wrap around implemented here. This contrasts with the sample checking application described in Chapter 4. 18-2 Order Entry Application Form 3. Order Header Line-one line with a field containing the name of the customer (highlighted in bold), an account number, and an order number The demo assumes that order header information has already been entered. 4. Order Summary Region-a scrolled region in which six items from a group of 10 items are visible Use the Prev Screen and Next Screen keys to scroll one entry at a time. The region scrolls only when entries are not visible. 5. Order Entry Panel-a data entry area The data entry area has a border around all sides with header text and a field that shows the index of the current order line item. The index ranges from 1 to 10. The panel allows entry of six fields; only three fields would be used in a real application (stock code, quantity, and comment), but, since this is a demo and there is no database behind the form, you may also enter values into the price, description, and order value fields. This allows you to control what gets placed into the summary region. To save time, you can place values into both the Order Summary Region and the Order Entry Panel by pressing function keys. Press the Help key for more information. To enter your own values, fill in the fields and press the Do key. After you have entered a few order lines, you can use the Prev Screen and Next Screen keys to view all entries. Notice that you are scrolling the order lines without the cursor entering the order summary region. This is "display-only" scrolling. Notice also the use of scroll bars on either side of the scroll region. These are a visual reminder of where you are in the scroll region. When the top of the group is visible at the top of the region, there are corners displayed at the top of each scroll bar. As you move down, these change to double dots to indicate there are more entries above the visible region. Similarly, Order Entry Application Form 18-3 corners and double dots are used at the bottom of the visible region. If you enter your own data in the order entry panel, be aware of the following: o The stock code is a right-justified, alphanumeric field. o The quantity field is right-justified numeric, which, like the other read-only quantity fields in the panel, shows a single zero if the quantity value is zero. o The comment field is left-justified alphanumeric. o The Price and Value fields are both decimal, which means right-justified and insert input mode to the left of the decimal point, and left-justified overstrike input mode to the right of the decimal point. You enter a decimal point to switch from entry of the integer part to entry of the decimal part of the field. You can use the left and right arrow keys to move around in the field, but remember that you are in insert mode when you are to the left of the decimal point and overstrike mode when you are to the right of the decimal point. 6. Message Panel-an area for messages to the operator The message panel has a border around three sides, which means that at run time, DECforms cannot use terminal hardware support for scrolling messages. This is a form designer's trade-off decision. To see a typical message for this type of application, press PF1-F20. Menu Icons To navigate up to the menu icons, use the up arrow key. You are always placed at the leftmost icon, Print. To move between the icons, use the left and right arrow keys. To select one of the menus, position to the one you require and press the Select key. The current icon is highlighted by the bold display attribute. 18-4 Order Entry Application Form A description of each icon follows. o Print The Print icon prints the current display. Each time you select this icon a new file, called order_entry_ system_form.txt, is written in your current default directory. To change this, define the logical name FORMS$PRINT_FILE to a directory and file name of your choice. The print feature does not print just what you see on the screen. It uses the printing viewport feature of DECforms, which lets the print file contain a different organization of data from that which appears on the screen. In this demo, the print file is intended to look like a customer order slip with addresses, summary information, and a full list of all order items. All this data can be seen interactively, but on separate panels. The printing viewport pulls it all together into a single panel. For the sake of this demonstration, extra information such as order total and special messages are placed in the printing panel to make the order slip appear complete. In a real application, this information would be calculated or looked up by a real program. To make the print file look the way it should, you need to fill all the order lines. A special function is provided for that: press PF1-Select while the cursor is on the Print icon. o Customer Inquiry The Customer Inquiry icon leads you into a succession of pull-down menus, which lead into a pop-up data inquiry panel. On all pull-down menus, use the up and down arrow keys to move up and down the choices. Note that the current choice is highlighted in reverse video as you move around. If you move up from the top choice, you are taken off the pull-down menu and back to the Customer Inquiry icon. Not all the choices in the pull-down menus are implemented since this demonstration is only a prototype. Those that are implemented show "..." after the text of the selection. Order Entry Application Form 18-5 Once you select Customer Inquiry, you are presented with two choices. The Current Customer choice takes you to another pull-down menu, while the Another Customer choice is not implemented in this demo. Selecting Current Customer brings up another pull-down menu, the title of which replaces the icon you just selected. This pull-down menu provides four choices. Only the Customer Profile is implemented in this demo. Selecting the Customer Profile icon brings up a pop- up data display panel that overlays the center of the screen. This panel provides further information about the current customer. The dates are formatted by the panel field picture, which could be changed in the form if another format was needed. Pressing the Return key returns to the Customer Inquiry icon. o Stock Inquiry The Stock Inquiry icon is not implemented in this demo. o Order Inquiry The Order Inquiry icon pulls down a menu of three selections. Only the Back Orders selection is implemented. This takes you to a sub-menu where you can choose the type of Back Order Inquiry you require. Selecting By Item and then Current Item displays a data panel. Pressing the Return key moves down the list of items and then back to the Order Inquiry icon. o Exit The Exit icon leaves the demo and clears the screen. o Help The Help icon causes the Help screen to be displayed. 18.3 Implementation Notes This is a large demo. The form contains a number of features that are best discovered by reading through the IFDL source file. This section points out the highlights in the order in which they appear in the IFDL source file. It would help to look at the IFDL as you read this section. See section 18.4 for the name of the source file. 18-6 Order Entry Application Form Walking Through the IFDL Source File 1. The group ORDER_LINES contains more fields than actually appear on the screen. These extra fields are used to control movement between items (scrolling). The fields are initialized at enable time by means of an internal response. This allows scrolling control without the use of procedural escapes to add or subtract from the controlling indexes. Look at the various internal responses to see how this is done. 2. The date form data items show how to give an initial value to a date field. 3. The function declarations show how to bind functions to single or multiple key sequences. Notice the use of %DIGIT_ONE, %DIGIT_TWO, and so on to refer to the digit keys. 4. There are many internal responses that allow the same functions to be easily referenced from different function responses elsewhere in the form. 5. The internal response INIT_LINE_NBRS shows how the pointers are initialized in the group ORDER_LINES. 6. The internal responses START_OVER and BEGIN_DEMO show how form data and the activation list are set up at the start of the demo. The BEGIN_DEMO response is called by the enable response and from the use of the F19 key. The START_OVER response is called from the icon on the introductory screen labeled See the Demo. The START_OVER response uses the ACTIVATE response step to activate individual fields on the panel called ORDER_ENTRY_PANEL. This is so the operator will visit the fields in the required order, rather than in the order in which they actually appear on the screen. The first three fields are those into which an operator would enter data in a real application. The second set of three fields would normally be protected, but they are available for input in this demo so that you can enter data into every field that gets moved into the Order Summary Region. Order Entry Application Form 18-7 7. The function response CLEAR_MESSAGE_AREA clears the message panel by sending two blank lines to it. The message panel is two lines long. 8. Two field defaults are used to ensure that icons have consistent attributes. 9. Each panel has various function responses defined to control the use of function keys on that panel. With one exception (see the next step), these are not further explained here. 10.The function response MENU_SELECT refers to an internal response called SELECTION_NOT_AVAILABLE. This function response is declared at layout level so that it will catch all uses of the Select key, unless a lower-level function response is declared that actually implements a particular selection. 11.Notice how a combination of LITERAL POLYLINE and DISPLAY CHARACTER SET PRIVATE_RULE is used to get the required borders for panels. 12.The main panel that contains the Order Summary Region is called MAIN_PANEL. If you look at the field called ORDER_LINES, you can see how OUTPUT ... WHEN ... is used to control the appearance of the side bars in the scrolling region. WHEN conditions are evaluated as soon as the form data item used in the condition changes. These conditions are defined using corresponding subscripts, the ** notation. 13.The Order Entry area has its own panel, ORDER_ENTRY_ PANEL. This contains the function response that moves the data from the Order Entry Panel to the Order Summary Region. This includes a check on the scroll region becoming full. This panel also contains function responses to control scrolling of the Order Summary Region. 14.Note how decimal values are held in form data as integers, and displayed using the SCALE clause and DECIMAL pictures. For example: 18-8 Order Entry Application Form Field LINE_PRICE Same Line Next Column Output Picture 999WR9.99 Scale -2 Output " " When (ORDER_LINES(**).LINE_PRICE = 0) Protected End Field This example also shows how a field can be set to spaces, with no decimal point visible, when the field value is zero. This particular field comes from the Order Summary Region, not the Order Entry Panel. On the latter, a value of zero in the price field is displayed as 0.00. 15.The Price and Value fields on the Order Entry Panel use different INPUT and OUTPUT PICTURES. This is so that field input can be as efficient as possible, while field display can look as nice as possible. The INPUT PICTURE uses a fixed currency sign and full zero suppression, while the OUTPUT PICTURE uses a floating currency sign and allows a single zero to appear if the integer part of the value is zero. The IFDL code to do this is: Field PRICE Line 4 Column 31 Input Picture W9999R.99 Output Picture 999WR9.99 Scale -2 Justification Decimal End Field 16.The Customer Inquiry Menu and Data Panels show one method of controlling pop-up panels and navigation between them. Examine the function responses to see how this is done. Note that when the operator leaves the data display panel, the viewports are removed explicitly in reverse order of their display. This is so they all disappear together. If they were removed in the order of display, Order Entry Application Form 18-9 then when the first was removed, you would see the other two; when the second was removed, you would see the first. By removing the two "hidden" viewports first, when the top viewport is removed, the two that were underneath are no longer there. 17.The Customer Inquiry Data Panel includes examples of formatted date fields. 18.The Order Inquiry and Back Orders menu panels show how to control pull-down menus using functions and ACTIVATE, DEACTIVATE, and REMOVE response steps. 19.The Message Panel is created by one panel, in its own viewport, that provides the border for the message panel itself, which is in a separate viewport. The relevant viewport declarations are: Viewport MESSAGE_VP Lines 23 Through 24 Columns 2 Through 79 End Viewport Viewport MESSAGE_HDR_VP Lines 22 Through 24 Columns 1 Through 80 End Viewport The message viewport (MESSAGE_VP) then overlays the viewport that contains the panel containing the header line and border (MESSAGE_HDR_VP). 20.The help panel shows how a redefinition of the function response for NEXT ITEM can be used to allow the Return key to leave help and return to the main screen. 21.The Introductory Panel contains code to display the DIGITAL logo. 22.The CLEAR_SCREEN Panel is used to control the clear and refresh of the screen. This panel is empty and its viewport occupies the whole display area of a 24 by 80 terminal. Any function key causes the Form Manager to position to the previous item. The EXIT RESPONSE causes the panel to be deactivated. The panel contains the Remove post-display option which causes this panel 18-10 Order Entry Application Form to be removed and the panels which were hidden to be refreshed. 23.The next two panels, BO_ITEM_SELECTION_PANEL and BO_ ITEM_INQ_DATA_PANEL control the Back Order Inquiry selection and display. Note how the data values are setup as they are needed (remember this is a prototype not a real application) and how the fields on the data panel use PROTECTED WHEN and OUTPUT WHEN. 24.Also see how the EXIT RESPONSE for the panel BO_ITEM_ INQ_DATA_PANEL controls the removal of panels from the first pull-down menu to the top-most data panel in order to provide a clean appearance to the user. If the viewports were removed in a top-down manner, then the intermediate panels would be re-displayed only to be immediately removed. Use of Color This demo is intended to show the simplest use of color. All it does is select four colors and assign them to the four text attributes. This is done in the DISPLAY VIEWPORT clause as shown here: Display Viewport Background Color Black Foreground Color Yellow Bold Foreground Colour Cyan Reverse Foreground Colour Green Note the alternative spellings of COLOR and COLOUR. Both are supported. See the Copycat demo in Chapter 15 for information on how to gain more control over the use of colors. Printing The panel PRINT_PANEL and the viewport PRINT_VP are used to create the print file. The same form data values are used, but they are reformatted to fit on a large, 60- line viewport. Most of the data items that can be seen interactively on various panels are collected together in this one panel for printing. Order Entry Application Form 18-11 In the listing, shown in Example 18-1, notice how items that have value zero are not listed. Also, the Order Quantity is not shown if it is the same as the Quantity Sent. This control is done through declaring CONCEALED WHEN and OUTPUT WHEN conditions for the appropriate panel fields. The printing panel was created using a VAXstation screen, since the terminal emulator can support a window of 60 lines. The DECforms Character-cell Panel Editor was used to copy the elements from their smaller panels into the larger one. The elements were then moved around into an acceptable format. All the display highlighting was removed by editing the IFDL. Finally, a PRINT response step was added to the print icon. If a VAXstation is not available, a printing panel whose size is larger than 24 lines must be created by editing the IFDL source file directly. 18.4 Development Notes Files used o FORMS$DEMO_ORDER_ENTRY_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_ORDER_ENTRY_FORM $ FORMS EXTRACT OBJECT FORMS$DEMO_ORDER_ENTRY_FORM $ LINK FORMS$DEMO_ORDER_ENTRY_FORM /SHAREABLE Example 18-1 Listing of Print Panel *G*D*I* Global Distributors, Inc Orders for Consolidated Computing Services Account No: 3275 Order No: 1205 Customer Address: Delivery Address: 100 Main Street 32 Pilgrim Road Boston Riverville MA 01256-5809 MA 01702-6839 (continued on next page) 18-12 Order Entry Application Form Example 18-1 (Cont.) Listing of Print Panel Last Order Date: 17-Jan-1989 Account Balance: $568,231.00 Last Payment Date: 23-Dec-1988 Order Balance: $112,186.00 Last Statement Date: 16-Dec-1988 -------------------------------------------------------------------------------- Line Stock Code Description Quantity Price Value -------------------------------------------------------------------------------- 1 MS615-CB 9-MB quad module 15 $3548.00 $53220.00 Units/pack: 1 2 BMQ3D-05 Transceiver Cable - 5M 40 $88.50 $3540.00 Units/pack: 8 3 CK492-FF Cabinet Kit 5 $160.00 $800.00 Units/pack: 1 4 RQFXA-Y4 Disk Expansion Kit 18 $188.00 $3384.00 Units/pack: 1 5 DNV16-QD 16-Serial Line Comm 4 $4955.00 $19820.00 Units/pack: 1 6 B7004-BF AC Surge Suppressor, 120V/12A 1 $295.00 $590.00 Units/pack: 1 Order Quantity: 2 and to follow: 1 7 IEM33-AF Dual Bit DMA Controller 1 $2260.00 $2260.00 Units/pack: 1 8 DEMPS-BA Multiport Repeater 2 $3400.00 $6800.00 Units/pack: 2 9 DF128-MA 4800 Sync Modem 10 $2110.00 $21100.00 Units/pack: 1 10 MXU16-BA Bootstrap Proms 8 $84.00 $672.00 Units/pack: 4 ========== Order Value: $112,186.00 Additional Information: Stock Item B7004-BF (AC Surge Suppressor, 120V/12A) out of stock. New shipment due 12 May 1989 (continued on next page) Order Entry Application Form 18-13 Example 18-1 (Cont.) Listing of Print Panel 18-14 Order Entry Application Form 19 ________________________________________________________________ Rule Character Set Form This chapter describes a form that demonstrates the Rule character set. 19.1 Overview This demo shows the characters that comprise the Rule character set. To use these characters in a DECforms form, specify the Rule character set in the display clause for a field or literal. The form also shows how all keys (data and function) can be trapped by the form designer. 19.2 Running the Rule Character Set Demo To run the Rule Character Set demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_rule_form The form displays a single panel showing the alphabetic characters and their equivalent Rule character. To leave the demo, press any key except F1 through F5 (which are reserved by the operating system or the terminal). This disables the form, leaving the panel visible on the screen. Rule Character Set Form 19-1 19.3 Implementation Notes To specify the Rule character set, either edit the IFDL source file directly or use the Character-cell Panel Editor to set the character set. The following IFDL source code displays the literal "l" as the top left corner in a rectangle: Literal Text Same Line Column 23 Value "l" Display Character Set private_rule End Literal Function keys are trapped as follows. The panel defines the following function responses: Function Response BUILTIN FUNCTION Return End Response Function Response USER FUNCTION Return End Response Function Response UNDEFINED FUNCTION Return End Response The result is that using any function key causes the execution of the response step RETURN, which returns control to the enable program. The first response traps the use of any keys that are bound to DECforms built-in functions. The second response traps any keys that are bound by function declarations in the form. (There are none in this form, but the response is shown here for completeness.) The third response traps any keys that are not bound to functions in the form and that are not bound by default. Two fields are defined in the panel. When the panel is activated, the cursor is positioned in the first field. This field has the attribute CONCEALED so that any data entered by the operator is not displayed. The field also 19-2 Rule Character Set Form has the attribute AUTOSKIP. Since this is a single- character field, once a data entry key is pressed, the Form Manager tries to position to the next field. The EXIT RESPONSE causes the Form Manager to return to the enable program. 19.4 Development Notes Files used o FORMS$DEMO_RULE_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_RULE_FORM /OUTPUT=FORMS$DEMO_ RULE_FORM.FORM $ FORMS EXTRACT OBJECT FORMS$DEMO_RULE_FORM $ LINK FORMS$DEMO_RULE_FORM /SHAREABLE Rule Character Set Form 19-3 20 ________________________________________________________________ VT Windows Form This chapter describes a form that demonstrates the windowing capabilities of DECforms. 20.1 Overview The VT Windows Simulation demo simulates a windowing interface on a character-cell device. The form includes a layout for character-cell display. 20.2 Running the VT Windows Demo To run the VT Windows demo, select it from the FORMS$DEMO menu described in Chapter 2, or enter the following commands: $ enable :== $forms$examples:forms$demo_enable $ enable forms$examples:forms$demo_vt_windows_form The form displays a login screen. Enter any username and password and press Return. A screen simulating an icon box and session manager window is displayed. To select options within the session manager, use the left and right arrow keys to move to an option and the Select key to select it. The demo contains extensive help. To see the help, select the Help option in any window. To create up to three pseudo-terminal windows and one puzzle window, use the Create option. To iconize or deiconize windows, including the Session Manager, move the cursor to the upper left corner of the window and press the Select key, or move the cursor to the corresponding icon box entry and press the Select key. VT Windows Form 20-1 The session manager and the terminal windows allow certain customization operations by means of pull-down customization menus. To try them, select the session manager or window Customize option. Table 20-1 summarizes function keys. For more information, see the help that is provided in the demo. Table_20-1_Windows_Function_Keys__________________________ Function_Key_____Definition_______________________________ Arrow Keys General cursor navigation SELECT Invoke a pull down menu, select a menu option, or iconize/deiconize window F10 Exit the demo F8 Quit the demo PF1-UP Position to command line in the Puzzle window PF1-I Position to Icon Box PF1-PF2___________________________________________________ To leave the demo at any time, select Quit from the session manager Session option, or press the F10 key or Ctrl/Z. 20.3 Implementation Notes The complete windowing environment is defined by the IFDL file, which is heavily commented. Please refer to the IFDL for specific implementation details. 20.4 Development Notes Files used o FORMS$DEMO_VT_WINDOWS_FORM.IFDL Build commands $ FORMS TRANSLATE FORMS$DEMO_VT_WINDOWS_FORM $ FORMS EXTRACT OBJECT FORMS$DEMO_VT_WINDOWS_FORM $ LINK FORMS$DEMO_VT_WINDOWS_FORM /SHAREABLE 20-2 VT Windows Form ________________________________________________________________ Index A CONCEALED clause, 19-2 ___________________________ CONCEALED WHEN clause, 5-2 ACTIVATE response step, Controls 18-7, 18-10 emulation of DECwindows, Activation list, 16-1 11-2 Asynchronous Conventions update of fields, 9-1 for enabling shareable AUTOSKIP clause, 14-1, images, 3-2 19-2 for naming demonstrations , 2-2 B__________________________ Creating Bar menus, 11-2 shareable images, 3-2 BOUNDARY CURSOR function, trace files, 5-1, 15-1 14-1, 16-5 Ctrl/W (screen refresh), Broadcast messages 1-4 disabling, 1-3, 2-2 D BUILTIN FUNCTION response, ___________________________ 15-2 Data declarations, 12-1 Data groups, 6-1 C__________________________ Data input CALL response step, 13-4 from a predefined list, Character data type, 6-1 8-1 Character sets panel design, 12-1 Rule, 16-1, 19-1 Data types Check fields, 11-2 character, 6-1 Circular buffer datetime, 6-1 manipulation, 14-1 integer, 6-1 Color usage, 15-2, 18-11 TM, 10-1 Command procedures Datetime data type, 6-1 for defining logicals, DDIF file 3-2 converting to PostScript FORMS$DEMO, 2-1 format, 4-3, 6-2, 12-3 Index-1 DEACTIVATE response step, Enabling 18-10 shareable images, 3-2 Debug display, 8-1 ENTER HELP response step, DECW$DISPLAY logical, 1-4 16-6 DECwindows device EXIT HELP response step, DECW$DISPLAY logical, 1-4 16-6 Demonstrations EXIT response declaration, applications (summary), 19-2 1-1 EXIT RESPONSE declaration, forms (summary), 1-2 18-10 location (FORMS$EXAMPLES logical), 1-4 F__________________________ naming conventions, 2-2 Feedback on documentation running sending comments to customer-supplied, 2-2 on character-cell Digital, xii devices, 1-3 Field defaults, 6-1, 18-8 on DECwindows devices, Field groups, 8-3 1-4 Fields using FORMS$DEMO asynchronous update, 9-1 command procedure, Fixed pointers in groups, 2-1 14-2 Dialog boxes FOR clause, 15-2 emulation of DECwindows, Foreign command 11-2 for Enable program, 3-1 Disabling Form data items, 7-1, 8-4 broadcast messages, 1-3, Form records, 6-1 2-2 FORMS$DEMO command trace files, 2-2 procedure, 2-1 Display-only scrolling, FORMS$DEMO_FORM logical, 18-3 3-1 DISPLAY VIEWPORT clause, FORMS$EXAMPLES logical, 18-11 1-4 Documentation FORMS$PRINT_FILE logical, sending comments to 18-5 Digital, xii FORMS$TRACE_FILE logical, 5-1, 15-1 E Function declarations, ___________________________ 18-7 Enable program Function keys, 19-2 defining as foreign Function responses, 13-4, command, 3-1 18-7, 19-2 FORMS$DEMO_FORM logical, 3-1 Index-2 Functions, 6-1 mathematical, 13-4 M__________________________ Math functions, 13-4 G__________________________ Menus Graphics bar, 11-2 on character-cell devices emulation of DECwindows, , 16-1 18-4 on window devices, 17-1 pop-up, 11-2 Groups pull-down, 4-1, 7-1, field, 8-3 11-2, 18-5 scrolling, 14-1 use of fixed pointers, N__________________________ 14-2 Naming demos conventions, 2-2 H__________________________ NEXT ITEM built-in function HELP function response, , 18-10 16-6 NO DATA INPUT attribute, Help panel design, 6-2, 8-4 8-1 HIGHLIGHT WHEN clause, O__________________________ 13-4, 15-2 OpenVMS API, 4-3, 12-1 I__________________________ displaying library text, Icons, 4-1, 6-1, 16-5 8-1 INPUT and OUTPUT PICTURE Run-Time Library calls, clauses, 18-9 13-4 Integer data type, 6-1 Option fields, 11-2 Internal responses, 8-4 OUTPUT PICTURE clause, 6-1 OUTPUT WHEN clause, 6-1, L__________________________ 7-1 List groups, 11-2 P Location of demos, 1-4 ___________________________ Logicals Pop-up menus, 11-2 DECW$DISPLAY, 1-4 Portable API, 4-1, 6-2, FORMS$DEMO_FORM, 3-1 11-3 FORMS$EXAMPLES, 1-4 POSITION response step, FORMS$PRINT_FILE, 18-5 15-2, 16-5 FORMS$TRACE_FILE, 5-1, PostScript format 15-1 from DDIF file, 4-3, 6-2, 12-3 Index-3 Printing support, 4-1, 7-1, 12-1, 18-11 T__________________________ PRINT response step, 18-12 TERMINATE HELP function Procedural escapes, 7-1, response, 16-6 8-4 Test display, 8-1 PROTECTED WHEN clause, 6-1 Text array Pull-down menus, 4-1, 7-1, scrolling, 8-1 11-2, 18-5 Text entry fields, 11-2 Push buttons, 4-1, 6-1, Text fields 11-2, 17-2 multiline, 6-1 TM data type R__________________________ portable use of, 10-1 Radio fields, 11-2 Trace files Refreshing Calls demo, 5-1 screen (Ctrl/W), 1-4 CopyCat demo, 15-1 REMOVE response step, disabling, 2-2 18-10 TRANSFER clause, 8-4, 14-2 Request calls, 5-1 U OpenVMS API, 12-1 ___________________________ portable API, 4-1 UNDEFINED FUNCTION response REQUEST EXIT response, 5-3 , 15-2 Responses, 6-1 UP and DOWN ITEM functions, Response steps 16-5 execution order, 15-3 USER FUNCTION response, RETURN response step, 19-2 15-2 Rule character set, 16-1, User interface design 19-1 DECwindows emulation, 11-1, 18-1 S__________________________ controls, 11-2 SCALE clause, 6-1, 18-8 dialog boxes, 11-2 Scrolling menus, 11-2 display-only, 18-3 windowing emulation, 20-1 groups, 14-1 multiple-line, 7-1 V__________________________ text array, 8-1 VIEWPORT declaration, Sessions 18-10 multiple, 6-1, 9-1 Viewports, 6-1, 8-3 Shareable images printing, 18-5 conventions for enabling, 3-2 creation of, 3-2 Index-4 W__________________________ WHEN clause, 18-8, 18-11 Windowing emulation, 20-1 Index-5