Media Share 9

home *** CD-ROM | disk | FTP | other *** search

/ Media Share 9 / MEDIASHARE_09.ISO / graphics / demos304.zip / DEMOSYS.DOC < prev next >

Wrap

Text File | 1993-03-13 | 98KB | 2,147 lines

DEMOSYS.DOC Last revised 03/13/93 Page 1 The DEMO System Wayne Software 113 Sheffield St. Silver Spring, MD 20910 Fax support: (301) 588-8986 General user documentation and tutorial -------------------------------------------------------------------------------- Table of Contents Table of contents ............................................... 1 What is The DEMO System? ........................................ 2 Shareware notice ................................................ 3 Legal stuff ..................................................... 3 Registration form for The DEMO System ........................... 4 The DEMO System documentation ................................... 5 Documentation syntax ............................................ 5 The DEMO System programs: DEMOMAKE.EXE .................................................. 6 The DEMO System viewer ........................................ 6 DEMOSAVE.EXE (registered users only) .......................... 6 DEMOSCRS.EXE .................................................. 6 DEMOSCRX.EXE .................................................. 6 Input files required to create the self-viewer................... 7 Commenting code ................................................. 7 Tutorial: Screen pages .................................................. 8 Program Example 1 ........................................... 9 Settings (SET) statements ..................................... 11 List of SET commands ........................................ 11 The screen display ............................................ 12 Program Example 2 ........................................... 13 ^ codes ..................................................... 14 Program Example 3 ........................................... 14 Variables and functions ..................................... 15 Program Example 4 ........................................... 16 Action commands ............................................... 17 List of action commands ..................................... 17 Primary vs alternate screen ................................. 19 Key definitions ............................................... 20 Program Example 5 ........................................... 22 DEMOSYS.DOC Last revised 03/13/93 Page 2 Full-screen activities ........................................ 24 Program Example 6 ........................................... 25 How input fields are determined and how to do multi-column menus ..................................................... 27 Program Example 7 ........................................... 28 Mouse support ............................................... 30 Program Example 8 ......................................... 31 Keys defined by default ....................................... 32 Self-running demos ............................................ 33 Creating menuing systems ...................................... 34 Program Example 9 ........................................... 36 Data-entry forms .............................................. 39 Program Example 10 .......................................... 40 Using (GLOBAL) ................................................ 43 More labor-saving techniques .................................. 44 (SETn) statements ........................................... 44 Macros ...................................................... 46 Program Example 11 ........................................ 47 Included text ............................................... 48 &P1 to &P9 .................................................. 48 -------------------------------------------------------------------------------- What is The DEMO System? The DEMO System is a multi-purpose utility. It can be used for lots of things: * The DEMO System can can be used to create demonstration programs for text-only products. It allows you to specify branching to different display screens. It allows you to define unique actions based on almost any keyboard entry. This is an ideal vehicle for demonstrating bulletin boards and CD-ROM products without requiring the user to have any hardware. * The DEMO System can be used to create menu systems. You can present a menu with several dozen options, allowing the user to pick an option or view more options. The user can be prompted for information. * The DEMO System can be used to create help and tutorial systems. You can arrange help information in a tree-like structure and have the user branch around as necessary. * The DEMO System can be used as a forms generator, prompting the user for information and writing it to, say, an ASCII-delimited file for later processing. It comes with the rudiments of a programming language, including IF statements and branching tools. You can get a flavor of the possibilities The DEMO System provides you by running the DEMODEMO.EXE program. The control statements for this file are contained in DEMODEMO.CTL. The DEMO System creates an EXE version of your demonstration. This EXE version has imbedded CRC checks that prevent unauthorized tampering. The EXE version can be distributed without restriction. The EXE's are relatively small and can be placed on bulletin boards and floppy diskettes. DEMOSYS.DOC Last revised 03/13/93 Page 3 -------------------------------------------------------------------------------- Shareware notice The DEMO System is a shareware product. This is a "try it before you buy it" concept. If you find The DEMO System useful, you should pay the registration fee (US $50.00) to "Wayne Software" at the following address: Wayne Software 113 Sheffield St. Silver Spring, MD 20910 Upon registration, you will receive: * Fax support for problems. * A program called DEMOSAVE.EXE which takes EXE files created by the The DEMO System and recreates the control card statements. DEMOSAVE.EXE is not for re-distribution and is available only to registered users. * A unique code which can be used during DEMOMAKE operation to turn off the Wayne Software copyright notice when the demo is viewed. * A disk copy of the current release of DEMOMAKE.EXE. You will also receive a current copy of all of Wayne Software's other freebie software products. Please print the following form, fill out a copy of it, and send it back to Wayne Software with payment. -------------------------------------------------------------------------------- Legal stuff No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any other language or computer language in whole or in part, in any form or by any means, whether it be electronic, mechanical, magnetic, optical, manual or otherwise, without prior written consent of Wayne Software. Wayne Software disclaims all warranties as to this software, whether express or implied, including without limitation any implied warranties of merchantability, fitness for a particular purpose, functionality, data integrity or protection. All files in The DEMO System can be freely distributed but they must be distributed as a package. The registration-only file DEMOSAVE.EXE and its companion documentation file DEMOSAVE.DOC can not be distributed. SYSOP's are not given permission to put advertising in the archive. DEMOSYS.DOC Last revised 03/13/93 Page 4 -------------------------------------------------------------------------------- Registration form for The DEMO System Your name: _____________________________________________________________ Your company (optional): ____________________________________________________ Mailing address: ____________________________________________________________ ____________________________________________________________ City, State, ZIP: ___________________________________________________________ Country if not USA: _________________ Voice phone number: _________________________________________________________ Fax phone number: _________________________________________________________ Disk size (check one): 360K 5.25" ____ 1.2MB 5.25" ____ 720K 3.5" ____ 1.44MB 3.5" ____ Please register me as a paid user of The DEMO System. A check or money order for $50.00 (US) is enclosed. (Sorry. No credit card orders at this time.) Mail to: Wayne Software 113 Sheffield St. Silver Spring, MD 20910 Additional comments? DEMOSYS.DOC Last revised 03/13/93 Page 5 -------------------------------------------------------------------------------- The DEMO System documentation The DEMO System documentation consists of two manuals: DEMOSYS.DOC: This manual explains the basics of how to create and compile the files used by The DEMO System. It includes a tutorial with examples. DEMOSYS.REF: This manual is a reference manual that explains each of the commands and how they are used. It also describes the syntax used by the DEMOMAKE.EXE program as well as by the viewer. While programming techies are inclined to skip tutorials, you should at least look through the sample control files (which are stored in the SAMPLES.ZIP file in the distribution file). Unlike other programs, the DEMOMAKE.EXE program itself is not interactive. You are expected to understand the program somewhat before you attempt to use it. In addition, two supplemental quickie documentation files are provided: DEMOSCRS.DOC: Documents the DEMOSCRS.EXE TSR to do screen captures. DEMOSCRX.DOC: Documents the DEMOSCRX.EXE program to process screen captures. -------------------------------------------------------------------------------- Documentation Syntax Throughout this documentation, required items are capitalized. Variables appear in lowercase letters. So "MD directory" indicates that you must type exactly the letters "M" and "D" (in either lowercase or uppercase form) whereas "directory" is to be filled in with some other word. Options are specified in square brackets. They can be left out if desired. "RUN [ string ]" indicates that you can use the RUN command on its own (which will leave you at the DOS prompt) or you can include a command to be executed (at which point you'll be returned to the demonstrator). When several options are available for a given command and, if any are used, you can only pick one, the options appear within one set of brackets and a vertical bar separates each. So "CALL screen [ KEYn | parms ]" says you can either use "CALL screen", "CALL screen KEYn", or "CALL screen parms". DEMOSYS.DOC Last revised 03/13/93 Page 6 -------------------------------------------------------------------------------- The DEMO System programs The DEMO System consists of five distinct programs: - DEMOMAKE.EXE: This program takes a control card file and (typically) stand-alone screen files, verifies and compiles the code, and generates a load file. DEMOMAKE.EXE then appends The DEMO System viewer to this file to make a single demonstration file. DEMOMAKE.EXE need not be distributed with your demonstration program; it is needed for creating demonstration programs, not for viewing them. - The DEMO System viewer: This program presents your demonstration presentation to the end user. The viewer is a self-contained program which will be called anything you want it to be. The DEMOMAKE.EXE program creates this viewer file for you. - DEMOSAVE.EXE: This program is distributed only to registered users and can *not* be distributed with your demonstration program. DEMOSAVE.EXE allows you to uncompile the demonstration file, allowing you to make changes even if you're missing some of the original input screens. It also provides you a complete list of all keys that are valid during any given screen, resolving all GLOBAL statements for you. - DEMOSCRS.EXE: This program is a TSR written using Spectra Publishing's PowerBASIC 3.0 compiler. It saves the current contents of the screen including all color designations upon activating of the TSR with the Alt-Rightshift key. The program is documented in the file DEMOSCRS.DOC. - DEMOSCRX.EXE: This program is used in conjunction with DEMOSCRS.EXE. It can be used to create screen files used by The DEMO System. It can also be used to create ANSI.SYS-compatible files. The program is documented in the file DEMOSCRX.DOC. DEMOSYS.DOC Last revised 03/13/93 Page 7 -------------------------------------------------------------------------------- Input files required to create the self-viewer At a minimum, The DEMO System requires an input file which contains control card statements. Typically, it also requires screen files. At least initially, the screen files are stored as separate files external to the control card file. All input files are ASCII text files. They should not contain any tab, page eject, or other non-printable characters. -------------------------------------------------------------------------------- Commenting code (This has its own little section because in most application language manuals, it's almost impossible to find out how to enter comments.) Comments can be imbedded within control cards in several ways: - You can include blank lines between control cards. - You can begin a line with either ":", ";", or "'". - You can designate a comment within a command line by beginning it with "/*". All comments are ignored by the DEMOMAKE program and do not end up in the compiled code that is actually processed by The DEMO System viewer. The use of comments is heavily recommended. DEMOSYS.DOC Last revised 03/13/93 Page 8 -------------------------------------------------------------------------------- Tutorial Screen pages: There are a great many types of commands available in the demonstration program. There are at least 35 unique commands, 12 settings, and several special operations. Despite the variety, the standard "unit" of the demonstrator is a screen page. Each screen page can have unique key-press logic assigned to it (pressing "G" may take you to another screen on one screen page, or it may take you out of the demonstrator entirely). Each screen page can also have other unique settings: the cursor can change, constant text (if any) can change, the colors can change. All standard screen pages have text screens attached to them; text which is displayed (such as a menu) presenting the user with information so they can select the desired options or else text displayed for informational purposes (as in a help screen). There are several special screen pages. These pages do not have any text screens attached to them. The special pages are: labels (subroutines which are executed at a key press), global definitions (key and other settings which apply to all screens defined after the global definition), set definitions (key and other settings which can be defined once and then invoked later in different screens on an as-desired basis), and "once" definitions (operations which are done once when the program loads and then are not done again; these might including loading unique fonts so you can have you logo appear as graphics characters). Screen pages are identified within your control file as statements that begin with a dash. All of the screen page statements have same basic format: - filename [ description ] /* Screen text is external - *ref [ description ] /* Screen text is imbedded - @label [ description ] /* Action-only pages - (GLOBAL) [ description ] /* Establish defaults for later - (GLOBALNC) [ description ] /* Establish defaults for later - (SETn) [ description ] /* Provide recallable settings - (ONCE) [ description ] /* Done once only The "description" field is totally optional. It can be recalled by your program later if necessary using the function %PageDesc%. Unlike comments, descriptions stay with the data and are retrieved if DEMOSAVE is run on the file. DEMOSYS.DOC Last revised 03/13/93 Page 9 Each regular screen page can consist of four classes of commands. Each of these classes of commands are optional for any given screen. Most screens will only have three of the five classes of commands and some types of screens cannot have one or more of the types. Each class is processed in the following order: (1) settings (cursor shapes, colors, etc; these are processed immediately when the screen is loaded) (2) the screen display (NOT allowed within labels, Global, Set, and Once-only screen pages) (3) any forms generator commands (@ commands) (4) action commands (these commands are processed sequentially after the screen is displayed; typically, action commands are only used within label screen pages; their use within Global screen pages is strongly discouraged and they are ignored within Set screen pages) (5) key definitions (what commands to do when a given key is pressed; these are processed only if the user presses the desired key; typically, key definitions do not appear within label pages) (6) the screen is exited. Although the classes are in fact processed in the above order, they can typically appear within the control card file in any order. A screen page is defined as ending when the first of any of the following conditions are met: - The end of the main control file is reached - Another screen page control statement is reached. - A QUIT, GOTO, SCREEN, KEYPRESS, or POP action command is encountered. These commands have to be used to end label pages. Typically, you would not use any of these commands with non-label pages. Program Example 1: Let's start with a very simple control file. You want the program to pop up, say "Hello world", and then return to DOS. (For some reason, this is the standard "first program" example in most programming language books.) This example doesn't require a text screen at all (we'll add one later); you just need the following control card file: - @HI! A label screen page without much to it ECHO Hello world QUIT The first statement designates that this is a label screen page. The "A label screen page without much to it" is the description for the page. The description, again, was totally optional and you could have put anything you wanted (or nothing) here. DEMOSYS.DOC Last revised 03/13/93 Page 10 The next two statements are action commands. They execute sequentially, without regard to key presses. Each statement is explained in the reference section below but the "ECHO" command displays a character string to the viewer's screen and "QUIT" gets you out of the program. Every demonstration program should have at least one "QUIT" statement in at least one screen page. Save these text lines as an ASCII file called EXAM01.CTL. Then issue the following command: DEMOMAKE EXAM01.CTL When you run the EXAM01 file, you'll see some screen activity and get a final screen that looks something like this: DEMOMAKE (c)Copyright 1993, Wayne Software Last revised xx/xx/xx 23:24:56: Begin 23:24:56: Begin Pass 1 Processing 3 line 3 screen 1 in EXAM01.CTL Maximum number of keys per screen (including globals and actions): 6 23:24:57: Begin Pass 2 Reading screen 1 @HI! A label screen page without much to it Processed Screen lines: 0 Keys (and actions): 6 23:24:57: Creating EXAM01.EXE 23:24:57: Done Not a heck of a lot to it. When you type the command EXAM01.EXE, you'll get something like the following: DEMO (c)Copyright 1993, Wayne Software Last revised xx/xx/xx -Hello world Well, not very exciting, was it? You could have added a CLS command to get rid of the copyright stuff but it basically worked the way you expected it to. Note that all programming examples are contained in the SAMPLES.ZIP file within the distribution file. DEMOSYS.DOC Last revised 03/13/93 Page 11 Settings (SET) statements: Settings (SET) statements are defined once for each screen page. If they are not defined by you, The DEMO System assigns certain default values for you. The setting statements available to you are as follows: SET BASE n /* Sets default color to be used on a given screen SET CASE OFF /* The keypress "g" will be treated as "G" SET CASE ON /* "g" and "G" can each have their own actions SET CLS ON /* Clear the screen before this text page SET CLS OFF /* Do not clear the screen before this text page SET COLOR settings /* Define up to 8 color sets for color monitors SET CURSOR string /* Define a cursor to be used during full-screen SET KEYS CLEAR /* Clear all global key settings SET KEYS SETn /* Bring in key settings from setting "n" SET LOGO string /* Display a logo (text) somewhere on the screen SET MONO settings /* Define up to 8 color sets for monochrome users SET MOUSE OFF /* Turns off the mouse cursor SET MOUSE ON /* Turns on the mouse cursor SET SETTINGS CLEAR /* Clear all global SET settings SET SETTINGS SETn /* Bring in SET settings from setting "n" SET TOP screen /* Define top level that program can POP to Most of these options won't make sense at this point and, frankly, you'll never use some of them. Commands which are needed in the examples will be explained briefly on an as-needed basis. Each command is fully discussed in the reference section. For reference, the default values (where applicable) for each of these are as follows: SET BASE 0 SET CASE OFF SET CLS ON SET COLOR 151 154 152 117 097 153 001 157 SET CURSOR _ SET LOGO (none) SET MONO 150 070 007 157 150 070 007 157 SET MOUSE OFF SET TOP (system picks first non-label screen for you) DEMOSYS.DOC Last revised 03/13/93 Page 12 The screen display: For screen pages that allow a screen display, the screen itself is a block of text consisting of at most 25 lines, each no more than 80 characters in length. Initially, you can create the screen pages using any combination of a text editor, by using a text capture program (such as PC Magazine's PRN2FILE program), or by using the included DEMOSCRS.EXE and DEMOSCRX.EXE programs. These text pages can be stored as either separate external files (each file containing just one screen's worth of information) or else they can be imbedded within the control card file. The DEMOSAVE program (available only for registered users) recreates the control cards with all screens being imbedded. The chief advantage of imbedded screen files is one of control; it's easier to maintain a single combined file than it is to have lots of little screen files. The disadvantages are several; risks increase with only one file (lose the control file and you have to recreate everything from scratch or else use DEMOSAVE), larger files are typically harder to edit and maneuver around, and the DEMOMAKE.EXE program will actually have to process any imbedded text lines twice instead of once so compilation is slower. If the screen files are external, the screen page control card follows this format: - filename [ description ] /* Screen text is external The "filename" can include drive and path information if desired. Otherwise, the program will look for the file in your default directory unless you've provided a DATADIR command telling it to look for the files elsewhere. For imbedded screen files, the control card looks like this: - *ref [ description ] /* Screen text is imbedded The "ref" is a unique and short (one word) clue for what the screen text does (you can always add a fuller "description"). The shorter the better as far as the program is concerned but each reference must be unique. If the screen files are internal, the contents of the screen must be defined before the next screen control card statement is encountered. The screen is defined in a block of text that begins with "/." by itself on one line, followed by the up-to-25 lines of text, followed by "./" on a line by itself. DEMOSYS.DOC Last revised 03/13/93 Page 13 Program Example 2: Let's do the "Hello World" example using an imbedded screen file instead of the ECHO command. To do this, create the following control file as save it as EXAM02.CTL: - *DEMO An imbedded screen file /. Hello world ./ QUIT Remember the rules for what defines the end of a screen page. Among other things, a screen page ends when it hits a QUIT (or POP, GOTO, SCREEN, or KEYPRESS) action command. If you had placed the QUIT command before the imbedded text, the program would have misplaced the imbedded text and would have given you an error message. Compile this text file ("DEMOMAKE EXAM02.CTL") and then run it ("EXAM02"). The screen will clear, the words "Hello there!" will appear, and you'll be left at the DOS prompt. DEMOSYS.DOC Last revised 03/13/93 Page 14 ^ codes: The screens themselves can include codes which establish colors, input locations, and other things. There are seven types of control codes that The DEMO System accepts in text strings (including logos and cursor indicators) but one of them (the "^Prow,col" indicator) should not be used within a screen. These codes are as follows: ^Cn /* Set the color to color (or monochrome) set "n" ^K /* Establish this as a keyboard-input field ^Evar^ /* Print a DOS environmental variable here ^Uvar^ /* Print a user-defined variable here ^Tn /* Print "n" non-destructive spaces here ^Sn /* Print "n" destructive spaces here (used only /* to reduce the size of your input file; The DEMO /* System automatically uses space compression when it /* encounters five or more spaces together) ^Pr,c /* Locate the cursor at row "r" and column "c": /* this setting is not allowed within text screens /* themselves and should only be used in SET CURSOR, /* SET LOGO, ECHO, PROMPT, etc commands ^_ /* Ignored. Typically used only if you want to /* print out one of the other control key sequences Any text that is not part of these control codes (including spaces) are treated as text and is printed as is. Program Example 3: Okay, back to the "Hello world" example. In this case, we're going to print a text screen which contains the words "Hello world", then print a "Goodbye world" string on top of that screen, and then quit. Create the following control cards and save them as EXAM03.CTL: - *Overprinting Doing a screen, overprinting it, and then quitting /. ^S20^C1Hello ^C0world ./ ECHO ^P20,20^C2Goodbye ^C3world QUIT After compiling the program ("DEMOMAKE EXAM03.CTL"), then running it ("EXAM03"), you'll see the screen clear, print a blank line, skip to column 20, print "Hello world" in two different colors, then skip 18 lines and print "Goodbye world" in two different colors underneath it. While these examples work as expected, they don't sound like anything you'd like to demonstrate, do they? We're getting there! DEMOSYS.DOC Last revised 03/13/93 Page 15 Variables and functions: Most text strings (including input pages) can contain DOS-defined environmental variables (like your system prompt), user-defined variables, and system-defined functions. User-defined variables can be displayed or modified; the others cannot be changed. All DOS-defined environmental variables appear as "^Evar^" (without the quotes). The DOS prompt, for example, is represented as "^EPROMPT^". If this character string appears as part of an output block (either a screen, or a logo, prompt, or ECHO result), the variable will be expanded into the proper string. (Some times, this will present problems. Avoid putting any variable or function in a row that, upon expansion, will not fit on the screen. Results are uncertain in these cases.) All user-defined variables are represented as "^Uvar^" (again, without the quotes). If you want to create a variable called UserName, that would be "^UUserName^" in The DEMO System. Functions are indicated as "%func%" (again, forget the quotes) followed, optionally, by one or more parameters. The current system date, for example, is %Date%. All of these variables and functions are resolved when The DEMO System viewer is executed; not when the demo itself is created. (%Date% will be the date the user runs the program, not the date you created it.) In addition, functions %1% to %9% are parameters that you pass into a screen when using a CALL or GOTO statement. There are over 50 functions; check the DEMOSYS.REF manual for complete details about each of them. Variables are resolved when the demonstration itself is run, not when it is compiled. For example, the path (if requested) will be the user's path. You can usually concatenate variables with other variables and character strings. For example, the following usually works: KEY (PGDN) GOTO *006 KEY%Field% DEMOSYS.DOC Last revised 03/13/93 Page 16 Program Example 4: In this example, we'll generate a output screen that shows you the current definition of several functions. Note that some of the functions don't really have applicable values unless they're used in specific cases. Create the following control cards and save them as EXAM04.CTL: - @MAIN This is the main screen CALL @FILE Apples are good for you! QUIT - @FILE This is the screen that displays everything ECHO Date = %Date% ECHO Time = %Time% ECHO TimeElapsed = %TimeElapsed% ECHO ECHO PageName = %PageName% ECHO PageDesc = %PageDesc% ECHO PageNum = %PageNum% ECHO ECHO Dir = %Dir% ECHO DriveDirOrig = %DriveDirOrig% ECHO ECHO FieldNum = %FieldNum% ECHO Col = %Col% ECHO Row = %Row% ECHO ECHO Passed parms: (1)=%1% (2)=%2% (3)=%3% ECHO Passed parms: (4)=%4% (5)=%5% (6)=%6% ECHO Passed parms: (7)=%7% (8)=%8% (9)=%9% POP Other than the function variables, there is a new action command included in this example. The CALL statement brings in another screen page. The word after the "CALL" must correspond to a page defined in a screen page statement. In this case, the screen page is a label page with no text screen at all. All information is displayed using ECHO commands. At the bottom of the page is the command "POP" which returns control to the statement after the call. CALL and GOTO are the primary way used to move from one display screen to another. CALL (and the related GOTO) command allow you to pass in up to 9 words (separated by one or more spaces) which become functions %1% to %9%. You could pass in file names, control ("^") text codes, or anything else you want. In this example, "Apples are good for you!" is passed in. "Apples" is assigned to %1%, "are" is assigned to %2%, etc. Variables %6% to %9% are left as blank. Compile this code ("DEMOMAKE EXAM04.CTL") and then test it out ("EXAM04"). It will display some information on the screen and then quit. DEMOSYS.DOC Last revised 03/13/93 Page 17 Action commands: We've already used four action commands: CALL, ECHO, POP, and QUIT. There are more than 40 action commands available within The DEMO System. These are listed below. Some of them will be used in later examples and all are explained in the reference section at the end. Note that most action commands actually appear within label pages, not screen pages. Most of these action commands can be used in KEY statements (discussed next) but some (like RUN) will typically require a REDRAW command after executing; since you cannot assign two functions to a single keystroke, you will want to move these to label pages anyway. Action commands are ignored within SET pages and are not recommended within Global pages. Also note that most of the parameters can be replaced by variables or functions where desired. ASSIGN ^Uvar^ [ = string ] /* Assign a value to a user-defined /* variable BEEP /* Beep BUFFER [ keys ] /* Put input characters into a buffer /* so self-running demoes can be done CALL screen [ KEYn | parms ] /* Call a label or screen, with the /* intention of returning to the /* current location CD directory /* Change to a given subdirectory CDD drive:directory /* Change to a given drive and subdir CLS /* Clear the primary screen CLSA /* Clear the alternate screen COPY file1 file2 /* Copy file1 as file2 DELETE filename /* Delete a specified file DISPLAY COLOR /* Use SET COLOR color settings DISPLAY MONO /* Use SET MONO color settings DISPLAY TOGGLE /* Toggles between COLOR and MONO DRIVE letter /* Set the default drive DROP location /* Sets a location for a later HOP ECHO [ string[@] ] /* Display a given string ECHOA [ string[@] ] /* Display a given string to the /* alternate screen FIELD [ TOP | FIRST | -999 to 999 | BOTTOM | LAST | @1 to @99 ] /* Move to a particular input field GOTO screen [ KEYn | CLEAR | parms ] /* Branch to a label or screen, /* intending to not return to the /* current screen HOP location /* Unconditionally branches to a DROP IF cond1 rel cond2 THEN HOP location /* Conditionally branches to a DROP site KEYPRESS /* Wait for a keypress (automatically /* done in any screen text screen) DEMOSYS.DOC Last revised 03/13/93 Page 18 LOADLOGO ^Uvar^ char_count /* Loads bit-mapped characters to /* replace a VGA text character LOADLOGO CLEAR /* Clears bit-mapped text characters LOCATE row col /* Move to a given row and column on /* the screen, can also be done with /* ^Pr,c in display string itself MD directory /* Make a subdirectory MSGBOX type message /* Displays message at primary screen MSGBOXA type message /* Displays message at alternate screen NONE /* Don't do anything; only used in /* KEY assignments PAUSE [ seconds ] /* Wait for seconds to pass or until /* key is pressed PAUSEA [ seconds ] /* Wait on the alternate screen PAUSE BREAK ON /* Allow people to escape out of /* buffered sequences PAUSE BREAK OFF /* Don't allow people to escape PAUSE DEMO seconds /* Wait specified number of seconds /* before processing next key in the /* buffer PLAY string /* Play a given musical string PLAY ON /* Activate all PLAY commands PLAY OFF /* Turn off all PLAY commands POP [ TOP | 1 to 20 ] [ KEYn ] /* Return to some CALL statement PROMPT ^Uvar^ pattern [ other parms ] /* Prompt user for some input PROMPTA ^Uvar^ pattern [ other parms ] /* Prompt user, secondary screen QUIT [ return_code ] /* Return to DOS RD directory /* Remove a subdirectory REDRAW /* Redraw the current screen RUN [ string ] /* Run a DOS command RUNA [ string ] /* Run a DOS command to the /* alternative screen SAVE filename /* Save the current screen SCREEN [ TOP | FIRST | -999 to 999 | BOTTOM | LAST | @1 to @999 ] /* Switch to another screen SELECT /* Allow the mouse to select options; /* only used in KEY assignments WRITE filename string /* Write a line to a text file Action commands are executed sequentially after the screen text (if any) is displayed and before any user keypresses are processed (unless KEYPRESS appears). While several of the normal computer programming branching constructs, like GOTO and CALL statements, are implemented in The DEMO System, you will typically find they are implemented unusually in The DEMO System and you will need to develop work-arounds for some of them. DEMOSYS.DOC Last revised 03/13/93 Page 19 Primary vs alternate screen: There are actually two screens that The DEMO System uses. The first screen, the "primary screen", is used automatically for all text screens and by most of the commands. The second screen, called the "alternate screen", is typically used when you want to run a DOS command and not have the output from this command affect the text screen the user is viewing. Sometimes, you will want the output of the command to disappear completely. There are are number of commands that provide the capability of writing to either of these two screens: Primary Alternate CLS vs CLSA ECHO vs ECHOA MSGBOX vs MSGBOXA PAUSE vs PAUSEA PROMPT vs PROMPTA RUN vs RUNA In most cases, stick to the command without the "A" suffix. DEMOSYS.DOC Last revised 03/13/93 Page 20 Key definitions: Okay. Time for the meat and potatos command within The DEMO System. Key definitions tell the program what it should do if the user presses a given character. Each key definition statement follows this basic format: KEY key[,key]... action_command [ options ] where, at least for some of the action commands, the options are, in fact, not optional. The "key" portion of the statement can be any regular character, like "R" (without the quotes). If you want to assign an action to them, there are four characters that have to be coded specially: = code as (EQUAL) space code as (SPACE) ( code as (LPAREN) , code as (COMMA) You can also define just about any other character on the keyboard to do something. All of these keys are coded as a word in parentheses. These include all of the following keys which should be self-evident: (DEL) (ENTER) (INS) (PGUP) (UP) (DOWN) (ESC) (LEFT) (RIGHT) (F1) to (F12) (END) (HOME) (PGDN) (TAB) as well as some keys that may not be readily apparent or be standard: (BS) backspace key (A-key) Any letter key or F1 to F12 with Alt key pressed (A-n) Any key sequence generated by pressing the Alt key down, and, while keeping it down, pressing one to three digits on the numeric keypad (C-key) Any letter key, ENTER, BS, or F1 to F12 with Ctrl key pressed (S-key) TAB, DEL, INS, END, DOWN, PGDN, F1 to F12, etc with shift key pressed Note that all one-letter control keys are in fact defined as something else too. (C-M) internally is the same key as (ENTER), (C-I) is the same as (TAB), etc. You should watch out for this when you define your key sequences; only the first key assignment will win. You should also watch for this when you use the (A-n) convention. Most keys in the (A-32) to (A-126) range can be entered directly. Most of the keys before (A-32) are in fact keys like (ENTER) and (BS). If you have one key assigned with something like (A-62) and another key defined as ">" (decimal value 62), the first key defined will always win. DEMOSYS.DOC Last revised 03/13/93 Page 21 You can assign multiple keys to the same action if desired, either on separate KEY statements or else by separating each key with a comma *only* (don't put any spaces around the comma). Three mouse-related "keys": (MOUSER) right mouse button pressed (MOUSEL) left mouse button pressed (MOUSEB) both left and right mouse buttons pressed Full-screen field related keys: @1 to @90 field-selections 1 to 90 And three special "keys": (ELSE) any non-defined key was pressed (ANY) any key was pressed (LASTKEY) the last user key pressed; only allowed in BUFFER cmd The "action_command" and "[ options ]" part of the KEY statement are the same as were mentioned above. Typically, you will have key presses either call another screen or go to another screen. The difference between a CALL and a GOTO is whether you want to be able to return easily to where you were when you issued the command. You might use a CALL statement from a main menu, which offers the user several choices and then ultimately returns the user to the menu. You might use a GOTO statement when you have several pages of information to present to a user and you want PgDn to simply go to the next screen of information. DEMOSYS.DOC Last revised 03/13/93 Page 22 Program Example 5: It's time for a more useful example. In this case, you're going to have a menu with two branching options as well as a "quit" option. The program will contain three screens: a main menu and the two subsequent screens (one of which is a label screen). We won't use any full-screen options at this point. Create your control card file EXAM05.CTL: - *001 Main menu KEY A,(MOUSEL) CALL *002 KEY B,(MOUSER) CALL @003 KEY Q,(MOUSEB) QUIT /. Select an option: A. Display the current date and time (left mouse button) B. Display the files in the default subdirectory (right mouse button) Q. Quit (both buttons) ./ - *002 Display the current date and time KEY (ANY) POP /. Current date: %Date% Current time: %Time% Elapsed time: %TimeElapsed% Press any key to return to the main menu ./ - @003 Display a directory RUN DIR /W ECHO Press a key to return to the main menu PAUSE POP POP DEMOSYS.DOC Last revised 03/13/93 Page 23 This example has three KEY statements appearing in the first screen alone: KEY A,(MOUSEL) CALL *002 KEY B,(MOUSER) CALL @003 KEY Q,(MOUSEB) QUIT When an "A" character or the left mouse button is pressed, the first KEY statement calls screen "*002", which has some imbedded text. When a "B" character or the right mouse button is pressed, the second KEY statement calls the label "@003", which has some RUN and ECHO commands in it. "SET CASE OFF" is the default setting so "a" and "A" are treated the same as are "b" and "B". The third statement quits the program when a "Q" (or "q") or both mouse buttons are pressed. Screen *002 contains another KEY statement: "KEY (ANY) POP". This says that if the user presses any key (including either mouse key), the program will return to the previous CALL statement. In this case, it will return to *001, from which the CALL statement was made. Several new action commands are used here. The "RUN DIR /W" command shells out to the DOS command processor, and runs a directory command with the "/W" (wide) option. "PAUSE" waits for the user to enter any keystroke and then goes on. The %func% items (like %Time%) in *002 are functions which were discussed above. Compile this code ("DEMOMAKE EXAM05.CTL") and then test it out ("EXAM05"). The screen will clear, you'll get a small menu, you can pick any of the options by using the first character. When you're done, press Q and you'll be returned to DOS. This is a typical example for a demo set up for a bulletin board. In BBS's, you typically select an item by pressing a mnemonic key. There is usually no ability to do any selections using cursor keys. Non-BBS applications, on the other hand, allow users to select options based on moving the cursor and pressing Enter. For this, you need to know some full-screen functions. DEMOSYS.DOC Last revised 03/13/93 Page 24 Full-screen activities: Full-screen systems typically allow the user to move around the menu using the cursor keys. For example, a list of 10 items might be presented vertically on the screen and you're able to use the up and down cursor keys to position the cursor to the item you want. Then you press Enter. The DEMO System allows this as well. There are a number of things that have to be decided: * What user-selectable fields are there? What format will they have on the screen? Are they arranged in columns or vertically? Or are they some combination of both? * What keys can be used to maneuver around the screen and what do they do? A vertical list might support just the up and down arrow keys. But typically, you will also want to support the Home and End keys to move to the first and last item on the list. If you have a menu with vertical lists in several columns, you may want to add support for the right and left arrow keys. * What should the cursor look like? Should it be something like a greater-than symbol (">"). Or should it be a different-colored text block? Or should it be parentheses around the current item, perhaps also in a different-colored text block? * Where do you want the cursor to start in each field? One space before the item? Two spaces? Three? Maybe the cursor is "==>"; four would be appropriate for that. Maybe the cursor appears *after* the item? In The DEMO System, all input screens are in fact text screens. If you want to designate fields within the screen, you use the "^K" character combination where you want the field location to begin. You can designate up to 90 input areas per screen. For single-column presentations, you can skip lines all you want. For multi-column presentations, there are some other things to consider. We'll cover the simpler single-column presentation first. DEMOSYS.DOC Last revised 03/13/93 Page 25 Program Example 6: In this example, we're going to do a short menu based on the screens in example 5. This menu will allow the user to use the arrow keys to get around. The input selections are arranged in a single column (you can guess what example 7 will cover!). Create your control card file EXAM06.CTL: - *001 Main menu SET CURSOR ^C2=> KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 KEY A,@1 CALL *002 KEY B,@2 CALL @003 KEY Q,@3 QUIT /. Select an option: ^K A. Display the current date and time ^K B. Display the files in the default subdirectory ^K Q. Quit ./ - *002 Display the current date and time KEY (ANY) POP /. Current date: %Date% Current time: %Time% Elapsed time: %TimeElapsed% Press any key to return to the main menu ./ - @003 Display a directory RUN DIR /W ECHO Press a key to return to the main menu PAUSE POP The *002 and @003 screens are identical to what they were originally. What's been added are the full-screen commands in the first screen. Checking the changes line by line, the first new statement is: SET CURSOR ^C2=> This establishes a cursor as "=>" which will be printed using color set 2 (which defaults to white on green). The next lines establish what happens when the up and down arrow keys are used: KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 DEMOSYS.DOC Last revised 03/13/93 Page 26 If (UP) is pressed, the cursor will move from the current field to the previous field. If it's at the top item, it will be moved to the bottom item. If (DOWN) is pressed, the cursor will move from the current field to the next field. If it's at the bottom item, it will be moved to the top item. These two keys don't actually select any of the items on the list. They simply determined where the cursor would be placed. If Enter is pressed, the key statement designated with that input field's number will take affect: KEY A,@1 CALL *002 KEY B,@2 CALL @003 KEY Q,@3 QUIT If the cursor is at the first field when Enter is pressed, page *002 will be executed. If it's at the second field, then label page @003 will be executed. If it's at the third field, the user will drop to DOS. The actual designation of what fields are defined in done in the screen portion: /. Select an option: ^K A. Display the current date and time ^K B. Display the files of the default subdirectory ^K Q. Quit ./ The "^K" combination is used three times so there are three user-selectable fields. Note that there are three spaces between the "^K" and the item letter. This means that there will be one space between the cursor (which is two characters long) and the item letter. Note that the cursor will skip all lines that don't contain a ^K designator. Compile this code ("DEMOMAKE EXAM06.CTL") and then test it out ("EXAM06"). The screen will clear, you'll get a small menu, and you can pick any of the options by using either the first character or by using the cursor keys and then pressing Enter. When you're done, press Q or move the cursor to the Q option and press Enter. You'll then be returned to DOS. DEMOSYS.DOC Last revised 03/13/93 Page 27 How input fields are determined and how to do multi-column menus: The DEMO System detects input fields in the order they are found in the screen file. The fields are numbered from the first column to the last column, first line to last line. The "KEY (DOWN) FIELD 1" statement tells The DEMO System to move the cursor from the current field location to the next field location. If that field location is on the next line, the cursor will physically move down. If, on the other hand, that field is on the current line, the cursor will instead move physically right instead of down. The DEMO System does not try to make the (DOWN) key move to the next line. As far as The DEMO System is concerned, the key sequence for (DOWN) is defined as an action command; that action command, not the key itself, are processed during a demonstration. If you have a multicolumn input screen, you will have to select your key locations more carefully. Typically, you will want to insure that all columns have the same number of input fields. You will want to do this even if there are cells that are missing in a given column. (The reason for this will make sense in the example that follows.) Keep in mind that any keys that aren't defined for The DEMO System are in fact ignored. If someone positions the cursor at a field for which you don't have any KEY statements and presses Enter, nothing happens. Let's design a screen with multi-column user inputs. DEMOSYS.DOC Last revised 03/13/93 Page 28 Program Example 7: In this example, we're going to do a multi-column menu. The menu selections don't actually do much (we need to keep the example short). This menu will allow the user to use the arrow keys to get around. Create your control card file EXAM07.CTL: - *SCR Basic input screen SET CURSOR ^C2(^T8) KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -3 KEY (DOWN) FIELD 3 KEY (HOME) FIELD TOP KEY (END) FIELD BOTTOM KEY @1 CALL @DISPLAY Field 1 KEY @2 CALL @DISPLAY Field 2 KEY @3 CALL @DISPLAY Field 3 KEY @4 CALL @DISPLAY Field 4 KEY @5 CALL @DISPLAY Field 5 KEY @6 CALL @DISPLAY Field 6 KEY @7 CALL @DISPLAY Field 7 KEY @8 CALL @DISPLAY Field 8 KEY @10 CALL @DISPLAY Field 10 KEY @11 CALL @DISPLAY Field 11 KEY @13 CALL @DISPLAY Field 13 KEY @14 CALL @DISPLAY Field 14 KEY @15 QUIT /. Use the cursor keys to select a cell below: ^K Field 1 ^K Field 2 ^K Field 3 ^K Field 4 ^K Field 5 ^K Field 6 ^K Field 7 ^K Field 8 ^K ^K Field 10 ^K Field 11 ^K ^K Field 13 ^K Field 14 ^K Quit ./ - @DISPLAY ECHO ^P10,10^C2You selected %1% %2% PAUSE 2 /* Waits for two seconds or a user keystroke POP For instructional purposes only, the text screen labels the fields sequentially in the order that the program sees them (left to right, top line down). There's no reason you'd have the user see something like "Field 4" when they selected something. The (RIGHT) and (LEFT) KEY statements do about what you'd expect them to do. They move the cursor one field to the left or right ("KEY (RIGHT) FIELD 1" moves it one field to the right). When the cursor is on the last field of a row, pressing (RIGHT) will move it to the first field of the next row. Pressing (LEFT) will do the reverse. DEMOSYS.DOC Last revised 03/13/93 Page 29 The (UP) and (DOWN) key statements had to trick the program. If you want the cursor to move down to the cell immediately below the current one, the program has to be told to move the cursor over three fields. If, for example, the cursor is on field 1, "SET (DOWN) FIELD 3" tells the program to move to field 1 --> 2 --> 3 --> 4 and stop there. If you want to, test out this example eliminating those "unused" ^K designators. When the (ENTER) key is pressed, if there is a key field defined on the screen, the program checks to see where the cursor is currently positioned. It then executes any KEY statement found for that particular field position. These KEY statements provide the field position as "KEY @n action_command", where "n" is the field number. (Any "KEY (ENTER) action_command" statements are ignored if there are fields defined on the screen. You have to use cursor movements if you've defined fields.) There are two fields, fields 9 and 12, which don't have an text next to them. If you look through the key assignments, you'll notice there are no corresponding "KEY @9 action_command" or "KEY @12 action_command" statements. These are dummy fields. The cursor will be allowed to rest on these fields but if the user presses (ENTER), nothing happens. Notice the SET CURSOR assignment too. This one: SET CURSOR ^C2(^T8) sets the cursor to a different color, prints a left parenthesis, skips 8 characters (not printing over what's already there on the screen), and then prints the right parenthesis, still in the different color. This is fairly common in full-screen systems. Compile this code ("DEMOMAKE EXAM07.CTL") and then test it out ("EXAM07"). The screen will clear, you'll get a small menu, and you can pick any of the options by using the cursor keys and then pressing Enter. When you're done, press Q or move the cursor to the Q option and press Enter. You'll then be returned to DOS. DEMOSYS.DOC Last revised 03/13/93 Page 30 Mouse support: So far, the mouse hasn't been all that useful in any of these examples. We've used the (MOUSER), (MOUSEL), and (MOUSEB) KEY assignment to do the same thing that single keystrokes do. We haven't actually allowed you to move the mouse cursor somewhere and pick something. The DEMO System provides full support for the mouse. There are only two commands required to provide mouse support. The first is: SET MOUSE ON This turns the mouse cursor on. The mouse will only be activated in screens where there are least two defined keyboard input fields ("^K" fields). With the mouse on, the user can move the mouse cursor anywhere on the screen. Once the mouse is turned on, if a designated mouse button is pressed, The DEMO System looks for the last keyboard input field to the left of the mouse cursor and selects that one as if the cursor had manually been moved to that field. The button designation is done using the SELECT command. You can designate any or all mouse buttons to do the selecting. You can have the left button (say) select the item while the right button asks as escape: KEY (MOUSEL) SELECT KEY (MOUSER) POP DEMOSYS.DOC Last revised 03/13/93 Page 31 Program Example 8: Adding two statements to example 7 provides mouse support for the mouse. Here's the contents for EXAM08.CTL: - *SCR Basic input screen SET CURSOR ^C2(^T8) SET MOUSE ON /* Turns mouse support on KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -3 KEY (DOWN) FIELD 3 KEY (HOME) FIELD TOP KEY (END) FIELD BOTTOM KEY (MOUSER),(MOUSEL) SELECT /* Says what mouse does KEY @1 CALL @DISPLAY Field 1 KEY @2 CALL @DISPLAY Field 2 KEY @3 CALL @DISPLAY Field 3 KEY @4 CALL @DISPLAY Field 4 KEY @5 CALL @DISPLAY Field 5 KEY @6 CALL @DISPLAY Field 6 KEY @7 CALL @DISPLAY Field 7 KEY @8 CALL @DISPLAY Field 8 KEY @10 CALL @DISPLAY Field 10 KEY @11 CALL @DISPLAY Field 11 KEY @13 CALL @DISPLAY Field 13 KEY @14 CALL @DISPLAY Field 14 KEY @15 QUIT /. Use the cursor keys to select a cell below: ^K Field 1 ^K Field 2 ^K Field 3 ^K Field 4 ^K Field 5 ^K Field 6 ^K Field 7 ^K Field 8 ^K ^K Field 10 ^K Field 11 ^K ^K Field 13 ^K Field 14 ^K Quit ./ - @DISPLAY ECHO ^P10,10^C2You selected %1% %2% PAUSE 2 /* Waits for two seconds or a user keystroke POP Compile the program and try it out. DEMOSYS.DOC Last revised 03/13/93 Page 32 Keys defined by default: The DEMO System pre-defines four key combinations for you. They are defined for debugging and "whoops!" purposes. These assignments are: SET (C-C) QUIT SET (C-F1) ECHO ^P25,65%PageName%@ SET (C-J) RUN SET (C-R) REDRAW The first assignment provides a QUIT definition, allowing you to get out of the program. This is often necessary because it frequently turns out that even when you remember to code one of more QUIT statements in your program, you code a screen that leaves you in any infinite loop. (The most common way to do this is to have a page which calls itself.) The second assignment tells you the current screen name. This is useful when you're viewing a demo and you notice that you need to make a change to a particular screen. Maybe you forgot to code a key assignment or the characters don't align properly. The third assignment allows you to jump to DOS. You need to say "EXIT" at the command line in order to be returned to The DEMO System. This is useful for checking directories, making sure required files are present, etc. The fourth assignment redraws the current screen for you. This is frequently useful when you've done something like run a DOS command which has messed up your display screen and you need to get the menu back on. (You can also do this with a "SCREEN 0" command although that command behaves somewhat differently. See the reference manual.) You can reassign these keys if desired by doing specific reassignments (e.g. "KEY (C-C) GOTO @HOME" or "KEY (C-F1) (NONE)"). They provide some useful functionality though and defining other keys to do the same thing is recommended if you need these key sequences for something else. DEMOSYS.DOC Last revised 03/13/93 Page 33 Self-running demos: You may find yourself wanting to create some self-running demos, where the user's keys are in fact pressed for them. The user will see the results of each key press (e.g. the cursor will move). This may be desirable for an entire presentation or just for parts of a presentation. Several action commands relate to this capability: BUFFER [ keys ] KEYPRESS PAUSE BREAK ON PAUSE BREAK OFF PAUSE DEMO seconds The BUFFER command pushes keystrokes into a keystroke buffer. Each keystroke is retrieved sequentially on a first-in, first-out basis whenever a KEYPRESS command is encountered or whenever the program awaits a keypress in a normal text screen. You can clear the buffer by skipping the "keys" parameter. The KEYPRESS command is typically used in a label screen to get a keypress from the buffer. Since label screens never wait for a keypress otherwise (except when executing PAUSE or PROMPT commands), this is the only way to have them register any user-defined inputs. PAUSE BREAK ON says that a user can escape out of buffered keystrokes by pressing the Escape key. Doing so clears the keystroke buffer. This is useful if you want them to be able to do something on their own instead of getting stuck with your keystrokes only. PAUSE BREAK ON is the default in The DEMO System. PAUSE BREAK OFF is the opposite of PAUSE BREAK ON. PAUSE BREAK ON is the default for The DEMO System. Note that it's possible to crash The DEMO System (as well as your reputation) through poor placement of a BUFFER command. Placing a BUFFER command in a screen that is frequently executed may result in the BUFFER being filled up and provide no convenient way for the user to get out. If you have PAUSE BREAK OFF in effect, you may provide yourself will no way out of an overflowing buffer. Having said this, PAUSE BREAK OFF is clearly necessary in some cases. PAUSE DEMO seconds tells The DEMO System to wait a specified number of seconds before processing each keystroke. The user can press a key before the number of seconds is up, in which case the next keystroke will be activated (or, if PAUSE BREAK ON is in effect and they press Escape, they'll clear the buffer). The default value for this is PAUSE DEMO 1. Other than PAUSE DEMO 0 (which operates too quickly to be seen on some systems), PAUSE DEMO 1 is as fast as you can go. Note that the contents of the buffer is not applied to PROMPT or PAUSE/PAUSEA action commands. The system will not take the buffered input to answer a prompt or get out of a wait condition. DEMOSYS.DOC Last revised 03/13/93 Page 34 Creating menuing systems: The DEMO System provides enough functionality to create your own menuing system, providing menu access to basic DOS commands as well as a program launcher for other application products. You can set up a series of screens which let the user select applications to run or execute various DOS functions for them. Several action commands provide DOS functionality and closely correspond to the standard DOS commands. These are listed below without explanation. See the reference manual if any of them don't make sense to you. CD directory CDD drive:directory COPY file1 file2 DELETE filename DRIVE letter MD directory RD directory RUN [ string ] Several action commands are a bit more obscure. These are listed below and described afterward: PROMPT ^Uvar^ "pattern" [ other parms ] PROMPTA ^Uvar^ "pattern" [ other parms ] QUIT [ return_code ] RUNA [ string ] WRITE filename string The PROMPT command prompts the user for a response and sets a user variable to their response. The command consists of several parts (which are described completely in the reference manual): * "^Uvar^" is the user-defined variable that stores the results of the user's input. * "pattern" defines the type of input that is expected. The "pattern" can be replaced by any combination of the following characters: A alpha input (A-Z) (either upper or lower case) B Boolean input (T/F/Y/N; translated to Y/N on output) N numeric input (digits 0 to 9 only) U uppercase alpha (A-Z) only (translated to uppercase if provided in lowercase) X any character (decimal 32 to 125) (no translation) ! uppercase any character (decimal 32 to 125) (translated to uppercase if provided in lowercase) else any other characters in the pattern are left in the result verbatim; spaces are not allowed numchar a number followed by a one-character pattern is treated as a repetition factor. "5X" is the same as "XXXXX" DEMOSYS.DOC Last revised 03/13/93 Page 35 * "LEN=n" specifies the minimum length that the user has to fill in. Optional. * "RANGE=n-n" specifies the range (typically numeric) that the values must fall within. Optional. * "DEF=s" specifies the default value. Optional. * "TEST=cond1 rel cond2" imposes a test that the user entry must meet before the response will be accepted. For example, you can verify that they entered an existing file name if you wanted to. * "QUIT=key" is used for forms entry and specifies which key will exit you from the form. Defaults to QUIT=(NONE). * "VQUIT=key" is used for forms entry and specifies which key will exit you from the form. Unlike QUIT=key, VQUIT=key checks to make sure that all fields in fact met any imposed conditions. Defaults to VQUIT=(NONE). * "HELP=key" specifies what key will show the required input pattern and other characteristics. Defaults to HELP=(A-F1). * "COLOR=n" specifies the color to use for the input. Defaults to COLOR=1. * "REQ" specifies the the field must be filled in. Optional. * "NOESCAPE" prevents the person from leaving the form. * "QUIET" keeps to "Insr"/"Over" insert/overwrite indicator off the screen. * "-QUIET" keeps the "Insr"/"Over" indicator on. The QUIT command has already been used in a few examples to get out of the program. It also provides the ability to pass a return code to DOS. Quitting and looking for a return code is one way that a menu batch command can run another application without running out of memory. An easier method is to create a batch file in the menuing system and test for this batch file on exit. The easier method is demonstrated below. The RUNA command switches to the alternate screen before running a DOS command. You will see the command run but it probably won't permanently affect your menu display. Many applications will take charge of your screens anyway and they'll affect the menu. Note that using RUN or RUNA means The DEMO System remains in memory while your command is run. The DEMO System requires about 130K of RAM. If your program needs more than about 475K, you will have to exit the system (using QUIT), run a batch file, and then return to The DEMO System. This is demonstrated below. The WRITE command writes a line to a text file. This is typically used for creating a batch file from scratch. It can also be used to create accounting records saying that a particular command was run at a particular date and time. It can also be used to general ASCII-delimited files. DEMOSYS.DOC Last revised 03/13/93 Page 36 Program Example 9: This is going to be a fairly complicated example. For most real menuing systems, you need to set up a batch file that calls The DEMO System and then optionally calls another batch file which has commands to execute. This is done for any command that is too big to fit into memory. In this example, most of the options in the menu are directly available from The MENU System but one, running WordPerfect, is not. We presume for the sake of this example that you have a batch file called WP.BAT that invokes WordPerfect, changing the subdirectory and drive if necessary, and running it will all of the proper options. You could have many batch files if you wanted to. The DEMO System also allows you to create files (such as batch files) on the fly using the WRITE action command. You also have a batch file that you're running The DEMO System from. We'll call it EXAMMENU.BAT and it looks like this: ECHO OFF :Restart EXAM09 IF NOT EXIST EXAM09X.BAT GOTO :Done CALL EXAM09X.BAT GOTO :Restart :Done This batch file loads The DEMO System's program (EXAM09.EXE in this case). Once the program runs, the batch file checks to see if it has created a file called EXAM09X.BAT. If yes, that batch file is run and then The DEMO System is entered again. If not, then the user is returned to DOS. DEMOSYS.DOC Last revised 03/13/93 Page 37 EXAM09.EXE is the file you're creating with The DEMO System this time. Its source control cards look like this: /* Creating a sample user menu - (ONCE) DELETE EXAM09X.BAT /* Killing off the temporary batch file - *000 Main menu KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 KEY @1,A CALL @SHELLRUN WP.BAT KEY @2,B CALL @RUN CHKDSK KEY @3,C CALL @RUN DIR /W KEY @4,D CALL @RUN FORMAT A: KEY @5,E CALL @SHELL KEY @6,Q,(ESC) GOTO @QUIT /* EXAM09X.BAT is gone so batch program st SET CURSOR ^C1==> /. Sample menuing system: Pick an option: ^K A Run WordPerfect ^K B Run CHKDSK ^K C Display a directory ^K D Run FORMAT A: ^K E Drop into DOS ^K Q Quit ./ - @RUN Running a command while staying in The MENU System CLS /* Unnecessary, but it looks better RUN %1% %2% %3% %4% ECHO Press a key to continue PAUSE POP - @SHELLRUN Running a batch command. /* Copying the file as EXAM09X.BAT which is tested for in the /* main batch file. COPY %1% EXAM09X.BAT QUIT - @SHELL Leaving the user in DOS itself ECHO ^P20,1Enter EXIT and then (ENTER) to go back into The MENU System RUN POP - @QUIT Quitting ECHO ^P20,1Thanks for your interest! QUIT The entire menuing system consists of just five screens in this example, three of which are labels and one of which is a (ONCE) declaration. This leaves just one visual screen for the user to see. You could easily create a multiple-page menuing system which allowed the user to branch through a long series of commands and such. DEMOSYS.DOC Last revised 03/13/93 Page 38 The very first screen is a (ONCE) statement that deletes the file EXAM09X.BAT. A (ONCE) statement contains statements that you only want run when The DEMO System first starts up. EXAM09X.BAT is the file that is tested for in the EXAMMENU.BAT file and whose non-existence means that there's nothing more for the program to do ("IF NOT EXIST EXAM09X.BAT GOTO :Done"). The only way that file is recreated is in label @SHELLRUN; any other way out of the program will result in the file not being there so the user will be left in DOS. The first KEY assignment gives control to this @SHELLRUN label. It passes the name of the batch file that should be copied over EXAM09X.BAT. (You could create the batch file on the fly with WRITE commands but it's easier to take an existing one if you can.) The passed parameter becomes function %1% (subsequent ones would have become %2% to %9%). The @SHELLRUN label expands %1% into "WP.BAT" and then copies this file over EXAM09X.BAT. It then quits to DOS, at which point the EXAMMENU.BAT file kicks in, runs the program, and then puts you back into The MENU System. There are several RUN commands in the program but all of the programs they're running can be done within about 475K of memory so they do not cause problems. Compile the program ("DEMOMAKE EXAM09.CTL"). Then try the command out (the EXAMMENU.BAT file is also in the SAMPLES.ZIP file) and see if it works the way you expect it to. DEMOSYS.DOC Last revised 03/13/93 Page 39 Data-entry forms: The DEMO System provides the ability to create data-entry forms. Unlike using a series of PROMPT or PROMPTA commands, this allows you to have the user tab between input fields, modifying any that they want. Data-entry forms are somewhat unique in that they are typically incorporated with text screens but the normal KEY statements aren't used at all. For a data-entry form, a page is processed in this order: (1) Any SET statements are executed (2) The screen page is displayed (3) The data-entry is done (4) Any commands are executed (5) KEY statements are *not* executed (6) The screen is exited Data-entry forms use the "@" command to prompt the user. The text screen has to have several keyboard input fields (^K) defined. It has to have one "@" command associated with each of these fields. Each "@" command has the same format as the PROMPT and PROMPTA commands: @ ^Uvar^ "pattern" [ LEN=n ] [ RANGE=n-n ] [ DEF=s ] [ TEST=cond [rel cond] ] [ QUIT=key ] [ VQUIT=key ] [ HELP=key ] [ COLOR=n ] [ REQ ] [ NOESCAPE ] [ QUIET | -QUIET ] Each of these parameters were touched upon in the PROMPT discussion above and they are fully explained in the DEMOSYS.REF document. Several of the parameters have special applicability in a data-entry form: * "QUIT=key" specifies the key that will get the user out of the form without forcing every field to be verified. * "VQUIT=key" (verify quit) specifies the key that will get the user out of the form but force every field to be verified. * "REQ" specifies that the field has to have some value before the user leaves it. * "QUIET" specifies that the "Over"/"Insr" indicators are not to be specified on the bottom of the screen. DEMOSYS.DOC Last revised 03/13/93 Page 40 Program Example 10: This example demonstrates how the data-entry forms work. It prompts the user to enter some name and address information. At the end, they can opt to save the record, re-edit the record, or abort the record. - *001 Data-entry form @ ^UName^ "!25X" LEN=5 @ ^UCompany^ "!25X" @ ^UStreet1^ "!25X" LEN=5 @ ^UStreet2^ "!25X" @ ^UCity^ "!19X" @ ^UState^ "!!" LEN=2 @ ^UZip^ "NNNNN-NNNN" @ ^UPhone^ "(NNN) NNN-NNNN" LEN=14 @ ^USubmit^ "!" VQUIT=S QUIT=Q DEF=E TEST=%Instr%(SQE,^USubmit^) > 0 IF %Upper%(^USubmit^) = Q THEN HOP Skip ASSIGN ^UName^ = %Proper%(^UName^) ASSIGN ^UCompany^ = %Proper%(^UCompany^) ASSIGN ^UStreet1^ = %Proper%(^UStreet1^) ASSIGN ^UStreet2^ = %Proper%(^UStreet2^) ASSIGN ^UCity^ = %Proper%(^UCity^) WRITE TEST.PRN "^UName^","^UCompany^","^UStreet1^","^UStreet2^", (continued) "^UCity^, ^UState^ ^UZip^","^UPhone^" ECHO ECHO Entry saved. DROP Skip /. Address entry form User name: ^K Company: ^K Street: ^K ^K City, State ZIP: ^K , ^K ^K Phone: ^K Submit?: ^K (S=submit & save, Q=quit & nosave, E= ./ POP The form itself consists of nine keyboard entry (^K) fields. There are also nine "@" commands. The first ^K field corresponds to the first "@" command, the second to the second, etc. In the "City, State ZIP" line, you'll notice the ^K fields are spaced on the form. User input is not inserted into the screen; it's typed over whatever's there. As a result, you have to leave enough space for whatever length fields you're going to handle. Also notice there is a comma before the middle parameter. That's the comma that will appear after City. DEMOSYS.DOC Last revised 03/13/93 Page 41 Each @ command has to specify the variable name that will be assigned to any data entered as well the input pattern that that data must adhere to. Optionally, you can specify a number of other parameters. For the first field--user name--the variable is defined as "^UName^". The variable name itself is in mixed-case ("Name" vs "NAME"). If the user incorrectly answers this question, the error message will identify the field by variable name. Logically assigned names in mixed case will be more intuitive to your user. (The DEMO System limits the number of uniquely-named user-defined variables. See the discussion of "System Maximums" in the DEMOSYS.REF document.) The @ command specifies that the pattern for this field is "!25X". The "!" indicates that the first character will be automatically converted to uppercase. The "25X" indicates that the remaining 25 characters can be any character and will not be converted to uppercase. Finally, the "LEN=5" parameter specifies that the user must enter at least five characters for the name or the program will beep, identify an error, and reprompt them to enter the name again. The last field in the form is identified as "^USubmit^": @ ^USubmit^ "!" VQUIT=S QUIT=Q DEF=E TEST=%Instr%(SQE,^USubmit^) > 0 The user can only enter one character for this field and it will be automatically converted to uppercase by the program. "VQUIT=S" (verify quit) specifies that if the user enters an "S" (or "s"), the program will check each field to make sure it matches all LEN=, RANGE=, TEST=, and REQ conditions and then exit out of the form. This is typically used when the user indicates they want to submit the data from the form. "QUIT=Q" specifies that if the user enters an "Q" (or "q"), the program will exit out of the form. If the user avoided fields by tabbing or back-tabbing around them, these fields will not be verified. This is typically used when the user wants to quit the form without actually saving anything. "DEF=E" specifies that the default value for this field is "E". "TEST=%Instr%(SQE,^USubmit^) > 0" indicates that the user has to enter either an S, Q, or E or their input will not be accepted. If they enter the S, the VQUIT= clause will take control. Q will cause QUIT= to take affect. And E will cause the system to skip to the next field (in our case, the first field again) so they can edit the data. (In fact, the QUIT= and VQUIT= options take affect before the TEST= clause can be applied; the only thing this TEST= clause will actually test for is the "E" key.) None of the fields are tagged with "NOESCAPE" so the user can get out at any time by pressing (C-C) (exit to DOS) or (C-J) (jump to DOS). DEMOSYS.DOC Last revised 03/13/93 Page 42 Once the user leaves the form--with Q or S--the system will then execute the action commands within the page. The first of these is: IF %Upper%(^USubmit^) = Q THEN HOP Skip This tests to see if they entered Q or S. If Q, the program branches to the DROP location Skip. This avoids writing out the data. If S was pressed, the program executes a series of ASSIGN commands which convert several text fields to "proper name case". ^UCity^, which might have been entered as "SILVER SPRING", gets converted to "Silver Spring". Next, the program writes out the various variables to a file TEST.PRN. The WRITE command had to be split onto multiple lines for documentation purposes; it's really all on one line: WRITE TEST.PRN "^UName^","^UCompany^","^UStreet1^","^UStreet2^", (continued) "^UCity^, ^UState^ ^UZip^","^UPhone^" The data are written out to TEST.PRN in exactly the format shown. The quotation marks and commas are written as given and the resulting record becomes a standard ASCII-delimited record. Each field is automatically trimmed of trailing spaces so the only gaps in the record will be between words or where you asked them to be placed. So the record might be written as such: "Bruce Guthrie","Wayne Software","113 Sheffield St.","", (continued) "Silver Spring, MD 20910","(301) 588-8986" DEMOSYS.DOC Last revised 03/13/93 Page 43 Using (GLOBAL): It's time to backtrack a bit. Six screen page statements were introduced back at the beginning of this tutorial: - filename [ description ] /* Screen text is external - *ref [ description ] /* Screen text is imbedded - @label [ description ] /* Action-only pages - (GLOBAL) [ description ] /* Establish defaults for later - (SETn) [ description ] /* Provide recallable settings - (ONCE) [ description ] /* Done once only So far, we've covered the first three of these without saying much about the remaining ones. The (GLOBAL) statement is used when you have a lot of similar screens and you want to avoid coding the same basic KEY statements or SET statements for each of them. For example, say you have a series of screens, all of which should have the same cursor shape and all of which should uniformly treat (RIGHT), (LEFT), (UP), and (DOWN). You could of course code the same KEY and SET statements in for each of these screens. Alternatively, you could establish a default for KEY and SET statements and all screens defined after that default is set will share those defaults. In our case, you could say: - (GLOBAL) Establishing certain defaults SET MOUSE ON KEY (MOUSER),(MOUSEL) SELECT KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -3 KEY (DOWN) FIELD 3 KEY (ESC) POP SET CURSOR ^C2(^T8) - TEST01.SCR First screen - TEST02.SCR Second screen - TEST03.SCR Third screen Presuming that the files TEST01.SCR, TEST02.SCR, and TEST03.SCR all share the same types of field assignments, this would work fine. (GLOBAL) is presumed for any statements that appear in the control file before the first real screen is encountered. You only *need* to use the (GLOBAL) if you want to redefine the defaults part-way through a control file. Whenever (GLOBAL) is encountered, all previously-defined (GLOBAL) KEY assignments are cleared but SET statements are not. You cannot put regular action command (like RUN) in a (GLOBAL) section although they can be assigned to a keystroke in that section. Otherwise, you'd end up with an action command being performed at the start of every screen. DEMOSYS.DOC Last revised 03/13/93 Page 44 More labor-saving techniques: The (GLOBAL) statement (discussed above) is one way to save yourself from adding a lot of repeating lines to your control file. Other labor-saving tools exist and this section discusses them. These include (SETn) statements, Macros, and included text. (SETn) statements: There can only be one set of (GLOBAL) statements defined at a time. Frequently, you will want to have alternative defaults that you bring in. For example, let's say you have a presentation which has some screens with single input columns, some with double input columns, and some with only horizontal selections (e.g. "Pick a drive: A B C D E F G"). You could spend your time trying to make sure that all screens with similar characteristics follow each other in sequence but that might destroy the "natural order" of your control file. The first easy way to get around this is to use (SETn) statements. These are of the format: - (SETn) [ description ] /* Provide recallable settings You can define up to ten (SETn) definitions, where "n" is a digit from "0" to "9". In our example, we could define three (SETn) statements: - (SET0) Single-column input KEY (DOWN) FIELD 1 KEY (UP) FIELD -1 KEY (HOME) TOP /* Takes you to first field on screen KEY (END) BOTTOM /* Takes you to last field on screen KEY (ESC) POP - (SET1) Dual-column input KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -2 KEY (DOWN) FIELD 2 KEY (HOME) TOP KEY (END) BOTTOM KEY (ESC) POP - (SET2) Horizontal input KEY (LEFT) FIELD -1 KEY (RIGHT) FIELD 1 KEY (HOME) TOP KEY (END) BOTTOM KEY (ESC) POP DEMOSYS.DOC Last revised 03/13/93 Page 45 Then, in the screens that need these key definitions, you can refer to the appropriate (SETn) definition by using the SET KEYS statement: - TEST01.001 First file with single-column input SET KEYS SET0 - TEST01.002 Double-column input SET KEYS SET1 - TEST01.003 Another single-column input SET KEYS SET0 The (SETn) section can also include regular SET statements like SET CURSOR, SET COLOR, etc. These definitions will be brought in if you use the "SET SETTINGS SETn" statement in your program. Action commands are ignored within a (SETn) definition. When you use the SET KEYS or SET SETTINGS statements, the (SETn) definitions are added to whatever you already have in your current screen's configuration. The configuration is not cleared first. If the (SETn) definition includes a KEY assignment that you try to redefine later for this same screen in your control card file, the (SETn) definition will win. You must define the (SETn) section before you invoke it. You can re-use the (SETn) declaration if you want. The SET KEYS and SET SETTINGS statements count as action commands so they cannot be used in (GLOBAL) sections. Macros, on the other hand, can appear anywhere. DEMOSYS.DOC Last revised 03/13/93 Page 46 Macros: Macros are groups of code that are brought in whenever needed. Macros can include SET statements, KEY definitions, action commands, (GLOBAL) statements, etc. In fact, a Macro can include any statement except another block of macro statements. In most cases, you will only find Macros useful for setting up KEY definitions that you want to include in (GLOBAL) statements. You may also find Macros useful in labels when several labels include the same block of action commands. Macros begin with a MACRO declaration and include every control line from the statement after the MACRO declaration to a corresponding MEND statement: MACRO name [ REUSE | SKIP ] ... MEND There has to be one and only one MEND statement for every MACRO declaration. The Macro name is truncated at eight characters and has to be unique against all other Macro names up to those eight characters. If "REUSE" is specified and the macro name is already in use, the new definition will replace it. If "SKIP" is specified and the macro name is already in use, the new definition will be ignored. The Macro has to be defined before it is invoked. In order to invoke a Macro, you must use the following command: DO name [ parms ] The "name" corresponds with the Macro name (again, being truncated at eight characters). The optional parameters allow you to pass in up to 9 words. These words will replace special variables &1 to &9 if any of these variables are found within the macro or within any code encountered before the next DO statement. This means that the &1 to &9 variables can appear just about anywhere but they will only have a value once a DO statement passes them a value. You can assign multiple words by enclosing the words in quotes. This is shown in the example below. If desired, you can issue a DO statement against a system-defined fake Macro named (DUMMY). Depending on whether you pass parameters in or not, you can either change the definition of &1 to &9 or clear them entirely. Just like the MACRO statement itself, the DO statement can appear anywhere in your control card file. DEMOSYS.DOC Last revised 03/13/93 Page 47 Program Example 11: In this example, we'll define a Macro and use it and the &1 to &9 variables a little bit. Create the following control cards and save them as EXAM11.CTL: MACRO @TESTING /* A sample macro ECHO &1 is coming to &2 ECHO Get your &3 ready! ECHO PAUSE 2 MEND - @001 Invoking the macro DO @TESTING "Santa Claus" town stockings DO @TESTING "Bill Clinton" "Washington DC" hopes DO @TESTING "George Bush" Texas "tax exemptions" ECHO The value of &^_1 is &1 DO (DUMMY) ECHO The value of &^_1 is now &1 LOCATE 20 1 QUIT The Macro is invoked three times within one screen, each time passing in three different parameters. Then one of the parameters is tested outside of the Macro. Then DO (DUMMY) is invoked with no parameters, clearing &1 to &9 and one of the variables is tested again. One trick that you'll notice here is the use of ^_. This control combination is ignored by the system but only after the other parameters have been resolved. As a result, "&1" will actually show up when the ECHO command is printed instead of "George Bush" (a definite improvement too). As always, compile this text file ("DEMOMAKE EXAM11.CTL") and then run the program ("EXAM11"). See if it works the way you'd expect. DEMOSYS.DOC Last revised 03/13/93 Page 48 Included text: Periodically, you will develop a subset of a demo file that you will want to use in several demos. For example, you might have a group of screens that talk about modem problems and you decide to include this in both a technical help program as well as in a demonstration of your BBS. While you could manually copy the lines to include into your file, it's easier to tell your main control file to include at some point the other text. This is done using the + control statement: + filename When The DEMO System encounters one of these statements, it will stop processing the current file and start processing the new file. When done with that file, it will return to the originating file. Included files can have any type of control cards in them (including Macros). They can also have included files, nesting being limited roughly by the number of remaining file handles your DOS environment has allowed for. &P1 to &P9: You can pass up to nine additional parameters when using DEMOMAKE to create your demonstration. These parameters are stored as &P1 to &P9 and can be used in your control file. They will be resolved during compilation. For example, say you write a demonstration program and are distributing it to two different groups. You decide it would be nice to have the name of the group show up. You don't want to require them to have an environmental variable set (which you could trap with something like ^ECOMPANY^). You also don't want to have to modify the source files twice. Instead, you can add &P1 to &P9 in your screens or your control file. You might have a line in a text screen which says: Demonstration prepared for &P1 &P2 &P3 &P4 Say the control file is TEMP.CTL. When you want to create the demonstration for the company "Batwings and Others", you compile the demonstration using "DEMOMAKE TEMP.CTL DEMO1.EXE Batwings and Others". For "Apples and IBMs Unlimited", you compile it with "DEMOMAKE TEMP.CTL DEMO2.EXE Apples and IBMS Unlimited". (Note you have to specify the output file and, in this case, you have to name them different things.)