VISUALPQL homecontents start chapter top of pagebottom of pagenext page indexExecution Window

Execution Window

There are execution window commands to build interactive user interfaces using a fixed window 30 rows by 80 columns addressed by row and column. Information is displayed using the row and column location to control placement on the screen.

When using the execution window, data can be read either as individual keystrokes or multiple data fields can be entered with control returning to the program under particular circumstances.

The execution window is automatically created when a program that requires it is executed. A flag is set during compilation if any full screen commands are found and this flag is stored with the executable program. The execution window is removed at the end of the command stream, which could include many programs and utility commands, or when an explicit SCREEN OFF command is found. The WRITE command (see Reading and Writing.) sends output to the scrolled output window not the execution window.

The NREAD and SREAD functions and the interactive READ command, pop up a box for data entry which is independent of the execution window.

Templates

It is possible to save the way the execution window or part of the window looks. A stored window or portion of window is called a Template. There are commands create and save templates.

Execution window commands control both the placement of elements in the window and the appearance of the displayed elements. Elements are placed in the window using a screen rows and columns. References to screen locations are by a row and column coordinate system, where the row number is the first reference and the column number is the second reference. Row 1 is the top row of the screen. Column 1 is the leftmost position on the screen. The bottom right coordinate is 30 , 80.

Some commands create two dimensional displays such as a box. These commands require two coordinates, a top left and bottom right coordinate. The second coordinate must be greater than (or equal to) the first coordinate. References to rows and columns may be numeric constants, names of numeric variables and array references. These references are in the form:

row1 , col1 , row2 , col2

Video Attributes

The appearance (colours, inverse, underline, etc.) of display elements are defined in terms of video attributes.

The visual treatment of any display element is specified with the VIDEO option . The syntax of the VIDEO clause on all commands is :

command .... VIDEO video_value
The video value is a numeric value which may be a numeric constant, a variable name or an array reference. If no VIDEO clause is specified, the default video value 0 is used which is black on white.

The video value is a 23 bit number, where each bit represents one attribute (e.g. a colour, underline, inverse, etc.) that can be turned on or off. By turning several bits on, a combination of attributes can be specified. For example, by turning on both the underline bit and the inverse bit, the display would be underlined in inverse.

Some bits are reserved for future use and several have been set aside for user definition. The currently assigned bits and their functions are:

BitValueAttribute
1+2Blue
2+4Inverse
4+16Underline
5+32Dim foreground
6+64Dim background
8+256 Blue foreground
9+512 Green foreground
10+1024 Red foreground
11+2048 Bright foreground
12+4096 blue background
13+8192 Green background
14+16384 Red background
16+65536 Dim background
To turn on a given bit, compute 2 to the power of the bit. To calculate the video value of a combination of bits, add the calculated unique video values together. For example, Blue foreground, Green Background is calculated as follows:
COMPUTE VIDEOVAL = (2 ** 8) + (2 ** 13)

Combinations of "primary" colours produce other colours. Red and blue produce magenta, red and green produce yellow and blue and green produce cyan.

When any foreground/background setting is ON, then the other foreground/background settings come into effect. The default background is white but bits 12,13,14 all off correspond to black. Thus just turning on any of bits 8,9,10 r 11 gives a black background. To have a white background in combination with some foreground settings, turn on bits 12,13 and 14. To have a grey background, turn on bits 12,13,14 and 16.

Keys and Application Programs

An execution window program may need to reacts to the keys that users press. The program must know which key was pressed and then execute the appropriate part of the program. The VisualPQL commands that accept interactive function keys, refer to these by a key value.

SIR Key Values

The values of the standard keys (letters, numbers, etc.) plus the 33 standard ASCII keys plus any defined Logical Function Keys are available.

Internally each key is identified by a numeric value in the range 1-512. This value is returned by VisualPQL commands such as ACCEPT CHARACTER.

The following VisualPQL program displays the key value of a key as it is pressed and may be useful when developing applications. Note that the carriage return key (key value 305) terminates the program:

PROGRAM
INTEGER*2 KEYVAL
ERASE SCREEN
LOOP
. ACCEPT CHARACTER KEYVAL AT 10,10
. DISPLAY TEXT [FORMAT(KEYVAL,3)] AT 10,15
. IF(KEYVAL = 305) EXIT LOOP
END LOOP
END PROGRAM
ASCII standard character values are:

Character Set Decimal Range
Control characters 0 - 31
blank ! " # $ % & ' ( ) * + , - . / 32 - 47
Numbers 0 -9 48 - 57
: ; < = > ? @ 58 - 64
Upper case letters A - Z 65 - 90
[ \ ] ^ _ ` 91 - 96
Lower case letters a - z 97 - 122
{ | } ~ 123 - 126
backspace 127

Terminators

Some commands accept input of characters from the keyboard until a designated terminator key is pressed. For instance, the VERTICAL MENU command allows the user to scroll up and down through the menu and to select or de-select items from the menu. When finished, the user presses one of a set of designated keys called Terminators. Commands which have terminators are specified with a list of terminator keys, so that any one of a number of keys may terminate the execution of the command. These commands can return the value of the terminator key, allowing the program to take different actions depending on which terminator was used.


ACCEPT CHARACTER

ACCEPT CHARACTER varname AT row , col
[ PROMPT string_value]
[ VIDEO video_value]
[ ECHO num_value]
[ TIMEOUT num_value]

Reads a single keystroke returning the key value between 1 and 512 of the pressed key into the specified numeric variable. This variable must be numeric and capable of holding this size number (i.e. not INTEGER*1). It may be an array element.

AT Specifies the screen location where either the prompt, if one is specified, or the input cursor is positioned.

PROMPT Specifies the prompt to display. There is no default prompt.

VIDEO Specifies the video treatment of the prompt.

ECHO Specify either 0 or 1. 0 turns echo off, 1 turns echo on. The default is 0. Echo on means that the input key character is displayed on the screen. The echoed value is the marked value of the key. Non-printing keys such as arrows, control keys or the backspace key are not echoed.

TIMEOUT The numeric value is a positive integer and specifies The number of tenths of seconds to wait for a keypress. If the user does not press a key within the specified time, the program moves on to the next command and sets the specified variable to the value 30002.


BELL

BELL num_value

Makes a sound. The higher the number, the longer the sound.


BOX

BOX  AT | OVER row1 col1 row2 col2
   [ VIDEO video_value ]
   [ CHARACTER 'c' ]

Draws a box on the screen where row1 col1 are the coordinates of the upper left corner of the box and row2 col2 are the coordinates of the lower right corner of the box. If row1 and row2 are equal, a horizontal line is drawn. If col1 and col2 are equal, a vertical line is drawn. If the coordinates are not specified in upper-left, lower-right order, a warning message is issued and nothing is drawn. Either AT or OVER must be specified.

AT | OVER AT draws the box at the specified location, overwriting any previously displayed line characters. OVER draws the box at the specified location, using appropriate line intersection characters wherever two lines intersect.

VIDEO Specifies the video treatment of the box. Use the FILL command to fill the inside of the box.

CHARACTER Specifies an alternate character with which to draw the box. Specify a single character in quotes.

PROGRAM
. BOX AT    5,20,15,60    | draw one box
. BOX OVER 10,30,20,70    | draw overlapping box
. WAIT 30                 | wait 3 seconds
END PROGRAM


CURSOR

CURSOR ON | OFF

Turns the cursor on or off depending on the keyword. One of the keywords must be specified.

The cursor is only displayed during read operations such as ACCEPT CHARACTER and FIELD INPUT commands. Turn the cursor back on before ending any procedure, as it may be left off accidentally.


CURSOR POSITION

CURSOR POSITION row_varname col_varname

The CURSOR POSITION command returns the current position of the cursor in the specified variables. The first variable specified contains the value of the row and the second variable contains the column number. These variables or array references must be numeric.


DISPLAY TEXT

DISPLAY TEXT {'string_val' | varname} AT row col
             [ VIDEO video_value ]

The DISPLAY TEXT command displays either the specified string constant (in quotes) or the contents of the specified variable on the screen. The first character of the text is displayed at the specified row and column. The variable may be string, numeric, date or time.

AT Specifies the coordinates at which the first character of the text is displayed. This is required.

VIDEO Specifies the video treatment of the displayed text.

  • Example: The following example places four fields in various video styles the middle of the screen.

    PROGRAM
    . STRING *8 STR1
    . INTEGER*4  INT1
    . DATE DAT1 ('DD/MM/YY')
    . COMPUTE STR1 = 'String'; INT1 = 1; DAT1 = '01/01/93'
    . DISPLAY TEXT 'No video attribute' AT 10 25
    . DISPLAY TEXT  STR1  AT 11 25 VIDEO 2   | bold
    . DISPLAY TEXT  INT1  AT 12,25 VIDEO 4   | inverse
    . DISPLAY TEXT  DAT1  AT 13,25 VIDEO 22  | Bold/inverse/underline
    . WAIT 30
    END PROGRAM


    ERASE SCREEN

    ERASE SCREEN

    Clears the screen. The cursor position is not affected.


    FIELD INPUT

    FIELD INPUT varname
          AT row, col WIDTH display_width,input_length
        [ ARROWS right_arrow_char_value , left_arrow_char_value ]
        [ AUTOTAB ]
        [ BACKSPACE char_value ]
        [ DEFAULT varname | string_constant ]
        [ DELETE char_value ]
        [ EDITMODE 0 | 1]
        [ EDITSIDE 0 | 1]
        [ HELP 'help page']
        [ INSERT | OVERSTRIKE ]
        [ LEFT | RIGHT ]
        [ POSITION num_varname ]
        [ TABMODE 0 | 1]
        [ TERMINATOR num_varname [ ( list of char_values ) ] ]
        [ TIMEOUT num_value ]
        [ VIDEO video_value ]
    The FIELD INPUT command accepts interactive keyboard data entry into a numeric or string variable. The text entered at the keyboard is put into the specified variable or array element.

    Unless a TERMINATOR clause is specified, input is terminated by pressing any special key aside from the left/right arrow keys, [Delete], [Delete_field] and [End_of_line] keys. The user can use these keys to edit the field.

    The varname is the name of the variable where the input is stored. If a variable is implicitly defined by this command, it is a string variable. Trailing blanks are trimmed from the input.

    If a numeric variable is specified, input text which corresponds to a numeric format is stored as a number. If the input text does not correspond to a numeric format, undefined is stored.

    AT Specifies the screen location of the beginning of the input field.

    WIDTH Specifies the display width of the field and the maximum length of the input string (max_input_length). If the maximum length is greater than the display width, then the field is scrolled horizontally as the cursor attempts to move past either end of the input area.

    ARROWS Specifies the key values that move the cursor one character to the right or to the left. By default, these are 259 and 260. (The Right Arrow and Left Arrow keys.)

    AUTOTAB Specifies that input terminates when the maximum input length is reached. Without AUTOTAB, the user must specifically terminate input.

    BACKSPACE Specifies the key value that deletes the character to the left of the cursor. This default is 304.

    DEFAULT Specifies the variable or string constant that is displayed in the input field area upon entering the FIELD INPUT command. This string may then be edited by the user. If using a variable, it may be the same as the first parameter on the command.

    DELETE Specifies the key value that deletes the character where the cursor is positioned. The default is 276.

    EDITMODE Alternative method of specifying INSERT | OVERSTRIKE option. Specify a numeric integer variable or constant. 0 equates to INSERT, 1 equates to OVERSTRIKE.

    EDITSIDE Alternative method of specifying LEFT | RIGHT option. Specify a numeric integer variable or constant. 0 equates to RIGHT, 1 equates to LEFT.

    HELP Specifies a help page that is displayed if the user presses (Help) while positioned on this field. The page must be in html format in the help directory. The page name can contain directory names using forward slashes to delimit. Enclose the name in quotes. The system will convert this to a file name prefixed with a path pointing to the help directory and suffixed with the file extension .htm.

    INSERT | OVERSTRIKE INSERT (the default) specifies that characters are inserted at the cursor location. OVERSTRIKE specifies that input characters overwrite existing characters.

    LEFT | RIGHT LEFT specifies that characters are entered starting at the leftmost column of the field and moving to the right. RIGHT specifies that characters are entered starting at the rightmost column of the field and moving to the left. If using a language which requires entry of text from right to left, specify, RIGHT, OVERSTRIKE and optionally set ARROWS (304,260). LEFT is the default.

    POSITION Performs two functions. When the command is executed, it specifies the position within the field to place the cursor. If the value is undefined or 0, the cursor is placed at field position 1. After input is terminated, it contains the position within the field where the cursor was located when the terminator key was pressed.

    TABMODE Alternative method of specifying AUTOTAB option. Specify a numeric integer variable or constant.
    0 equates to NOAUTOTAB, 1 equates to AUTOTAB.

    TERMINATOR Specifies a variable that receives the key value that terminated input processing. It optionally specifies a list of key values that terminate input processing. The list of key values may be constants or numeric variables within parentheses. A maximum of 16 terminator values may be specified in the list. If a terminator list is specified, only those referenced in the list terminate input. Other control or function key characters sound a warning. If no list is specified, then any special key not used for editing causes termination of input.

    If the termination is caused by an AUTOTAB, the terminator variable is set to 30001. If termination is caused by a TIMEOUT, the terminator variable is set to 30002.

    TIMEOUT Specifies the amount of time to wait for the user's input, in tenths of a second. Zero (the default) puts no time limit on the user. If the user does not enter a value in the specified amount of time, and a variable is specified on the TERMINATOR, it is set to the "time out" character value which is 30002 and execution continues.

    VIDEO Specifies the video treatment of the input field.

  • Example:

    FIELD INPUT TEXTLINE at 11 , 40 width 20 , 20 video 4


    FILL

    FILL  row1 , col1 , row2 , col2
        [ VIDEO video_value ]
        [ CHARACTER str_var | 'c' ]

    The FILL command fills the rectangular area of the screen defined by the coordinates with the specified character and video treatment.

    VIDEO Specifies the video treatment of the fill character.

    CHARACTER Specifies a single character to fill the area. Specify either a string variable or a single character string constant. The default character is the blank (' ').

  • Example: The following example draws a box in blue on yellow and then fills the box with asterisks with the same video treatment.

    PROGRAM
    . COMPUTE BLUONYEL = 2**2 + 2**8 + 2**13 + 2**14
    . BOX AT  5 20 15 60 VIDEO BLUONYEL
    . FILL 6 21 14 59 CHARACTER '*' VIDEO BLUONYEL
    . WAIT 50
    END PROGRAM


    LINE CHARACTER

    LINE CHARACTER ( list_of_num_values ) AT row , col
       [ VIDEO video_val ]

    LINE CHARACTER draws a set of line characters on the screen. Each value in the parenthesised list draws one character. The values must be between 1 and 15 where each value represents a different line drawing character. The values and the characters that are drawn are:

    1 Top Left Corner
    2 Top Right Corner
    3 Bottom Left Corner
    4 Bottom Right Corner
    5 Top T Intersection
    6 Bottom T Intersection
    7 Left T Intersection
    8 Right T Intersection
    9 Intersection Cross
    10 Vertical Line
    11 Top End of Vertical Line
    12 Bottom End of Vertical Line
    13 Horizontal Line
    14 Left End of Horizontal Line
    15 Right End of Horizontal Line

    AT Specifies the coordinates at which the first line character in the list is placed. This is required.

    VIDEO Specifies the video treatment of the line characters.


    MENU

    HORIZONTAL MENU  row1, col1, row2, col2
          [ SPACING leading_blanks, trailing_blanks ]
          [ WIDTH   width ]

    VERTICAL MENU  row1, col1, row2, col2

    Horizontal menus are displayed across the screen and are scrolled left and right. Vertical menus are displayed down the screen and scroll up and down. The following options can be specified for both menu types:

          [ ARROWS       up_key_value, down_key_value ]
          [ BOX          row1,col1,row2,col2,boxtype_num , video_value ]
          [ ENTER        select_key_value, unselect_key_value ]
          [ EXIT         key_varname, element_varname,top_varname,last_item_varname ]
          [ FILL         char,video_value ]
          [ GROUP        num_value , up_key_value, down_key_value ]
          [ HELP         help_page ]
          [ HOTKEYS ]
          [ KEEPMENU     num_value ]
          [ PASTEONLY    num_value ]
          [ PROMPT       col1, col2, prompt_string, video_value ]
          [ PROMPTVIDEO  video_value ]
          [ SCREENOK     num_value ]
          [ SELECT       col1, col2, select_string, video_value ]
          [ SELECTARRAY  name_of_first_select_variable | array_name ]
          [ SELECTVIDEO  selected_item_video_value ]
          [ START        top_item_to_display, first_item_to_point_to ]
          [ TERMINATORS  ( list of char_values ) ]
          [ TIMEOUT      wait_time_value ]
          [ TITLE        row,col,title_string, video_value ]
          [ VIEW         top, bottom ]

    There are two further options in horizontal menus:

          [ SPACING      before, after]
          [ WIDTH        width]

    Menu Options

    For both menu types, one and only one of the following keywords are specified to define what is to appear within the menu:

    FAMILY first_family, last_family, video_value
    LIST (list of string values), video_value
    LIST array_name, number_of_items, video_value
    LIST str_varname, number_of_items, video_value
    MEMBER family, first_member, last_member, video_value
    RECTYPE first_rectype_num, last_rectype_num, video_value
    VARNAME rectype,first_var,last_var,video_value

    ARROWS Specifies the character values for arrow key movement. By default, arrow key movement for vertical menus is defined as the down Arrow and up Arrow keys (key values 258 and 257), and arrow key movement for horizontal menus is defined as the left Arrow and right Arrow keys (key values 260 and 259).

    BOX Draws a box at the specified coordinates with the specified video attribute. Row1 and col1 specify the upper left corner of the box, and row2 and col2 specify the lower right corner of the box. The boxtype specifies which line drawing characters to use when the current box overlaps another box; a boxtype of 1 causes intersections of one box with another to use intersection characters (equivalent to a BOX OVER); a boxtype of 0 ignores intersections with another box (equivalent to a BOX AT).

    ENTER Specifies the character value of the keys to use for selecting and unselecting menu items, respectively (see the SELECT and EXIT clauses). There are no default ENTER keys.

    EXIT When the user presses a key to exit the menu, the key_varname variable contains the character value of the key pressed to exit the menu. The element_varname contains the position of the menu item being prompted for at the time the menu was exited. The top_varname variable contains the position of the item at the top of the menu when the terminator key was pressed. The last_item_varname contains the string value of the menu item where the prompt was positioned when the menu was exited. The TERMINATORS clause defines which key or keys cause termination of the menu.

    FAMILY Fills the menu with the names of the families specified in the list. The values of the first and last families may be either numeric or string values. The null family occupies a space in the menu but displays no text. By specifying the first family as 'A' and the last family as 'ZZZZZZZZ', all named families in the procedure file are displayed.

    FILL Fills any area of the menu that is not part of a menu item's field, plus leading and trailing blanks in horizontal menus, with the specified character and video attribute.

    GROUP Specifies the size of multiple line scrolling jumps (equivalent to a page-up and page-down function). Specifies which keys (page up, page down) move the prompt the specified number of menu items. The default page up/page down values are 296 for up and 273 for down.

    HELP Specifies a help page that is displayed when the user presses the (Help). The page must be in html format in the help directory. The page name can contain directory names using forward slashes to delimit. Enclose the name in quotes. The system will convert this to a file name prefixed with a path pointing to the help directory and suffixed with the file extension .htm.

    HOTKEYS Specifies that the menu supports hot-keys. If a menu supports hot keys, the first capital letter in each menu item is the hot key. Pressing this from any point in the menu invokes the item. If the menu does not support hot keys, it supports alpha positioning. This means that when the user types in characters, the menu position is set to the item beginning with those characters. The menu should be in alphabetic sequence for alpha positioning.

    KEEPMENU Specifies whether the menu remains on the screen after termination. By default, the menu is cleared from the screen when the user exits from it. A non-zero value keeps the menu on the screen, zero or undefined clears the menu. The value 1 leaves the last prompted for item highlighted. The value 2 'un-highlights' the last prompted for item.

    LIST Specifies a list of items to display as menu choices. The video specifies the video display when the items are not being prompted for. The list is:

    • A list of values in parentheses either string constants or string variables. These are the menu items in the specified sequence.

    • The name of a string array and the number of items to display.

    • A variable and a number of items. The variable is the first menu item and the variables that follow this in the program are the subsequent items. (Typically a TO list.) The number of items is a numeric constant or variable.

    MEMBER Fills the menu with the names of the members implied in the first member and last member specification. The first and last member referenced may be either numeric or string.

    PASTEONLY Specifies that the menu is displayed on the screen, but not executed. A non-zero value displays with no execution; a zero or undefined value displays and executes. This is normally used in conjunction with KEEPMENU which leaves the menu on the screen after it is displayed and when program execution continues past the menu command.

    PROMPT Displays the prompt string at the specified columns of the menu. The prompt string moves from item to item according to the user's directions. (In most applications, either the PROMPT or the PROMPTVIDEO clause is used.)

    In vertical menus, col1 and col2 refer to the columns on the execution window where the prompt string is displayed. These can have the same value resulting in a single character prompt.

    In horizontal menus, col1 and col2 refer to the positions within an item's field that contain the prompt string, where the field width is equal to the width plus any leading or trailing blanks.

    PROMPTVIDEO Specifies the video treatment of the menu item being prompted for.

    RECTYPE Fills the menu with the names of the record types implied by the range of record types specified.

    SCREENOK Specifies that the appearance of the screen is as required and that the menu is not re-displayed. A non-zero value specifies that the screen is OK and is not re-displayed; a zero or undefined value specifies that the menu display is displayed. This is often used with the KEEPMENU option allowing the program to go out of the menu and perform some task and then return to the menu transparently to the user.

    SELECT Specifies the manner in which selected menu items in a multiple select menu are 'marked'. The specified string is displayed at the specified columns next to selected items. The ENTER option and the TERMINATORS option must be used to allow multiple choice menus. The SELECTARRAY option must also be specified so that the program can tell which items were selected after the menu is exited.

    SELECTARRAY Names the array or first variable of a numeric variable list used to indicate which items have been selected. The number of elements in the array must be at least as great as the number of items in the menu. When an item is selected, the array element corresponding to the ordinal position of the menu item is set to 1. When an item is un-selected (see ENTER), the corresponding array element is set to 0. Any select array element containing a non-zero or non-null value at the time the menu is first executed treats the corresponding menu items as having been selected.

    SELECTVIDEO Specifies the video treatment of selected menu items. Either the SELECTVIDEO, SELECT or both are used for multiple choice menus.

    SPACING Specifies the number of spaces before and after each menu item on a HORIZONTAL MENU.

    START Specifies how the menu items are displayed within the menu when the command is executed. The first argument specifies the item to display at the top of the menu. The second argument specifies the item highlighted. Both arguments are numeric and may be variables or constants. If START is not specified, the first menu item is placed at the top and the prompt points to the first item.

    TERMINATORS Specifies a list of legal terminators by their character values. When this clause is specified only the keys defined in the list cause termination of the menu. If the user presses a key not defined as a terminator key or as a special key by one of the other clauses, the bell rings and the menu is not terminated. The maximum number of terminator values that can be specified is 254. If hot-keys are supported these are terminators by definition. The key values may be numeric constants or variables. If this clause is not specified, any key, except those which are defined to take a specific action, causes termination of the menu. The EXIT clause stores which key caused termination of the menu.

    TIMEOUT Specifies the amount of time to wait for a user to press a key after the menu is displayed, in 1/10 of a second increments. If the user does not press a key in that period of time, the "time out" terminator value is set (char_value = 30002) and the menu is terminated.

    VARNAME Fills the menu with a list of variable names for the specified record type, with the specified video attribute. The variable references may be either string or numeric. Strings refer to variable names, numbers refer to DATA LIST order number.

    VIEW Specifies when scrolling occurs as the user moves up and down the menu. Specifies how many rows at the top and bottom of the menu are always displayed away from the prompted item. The default is 0 for both top and bottom, meaning that the menu does not begin scrolling until the user reaches the bottom (or top) of the menu area.

    WIDTH Specifies the maximum width of each item on a horizontal menu. If an item is longer than the width specified, then it is truncated to fit the width; if the item is shorter, it is padded with blanks. A width of 0 uses the minimum width needed for each item.

  • Example:

    c       This program demonstrates two very simple menus, a
    c       VERTICAL MENU and a HORIZONTAL MENU. The user
    c       selects an item from the first menu, the choice is
    c       redisplayed, and the second menu allows the user to
    c       do it all again or exit the program.
    
    PROGRAM
    STRING * 80 MESSAGE
    
    LOOP
    VERTICAL MENU 5 , 30 , 10 , 45
             list     ( 'First Menu Item' 'Second Menu Item'
                        'Third Menu Item' 'Fourth Menu Item') , 0
             promptvideo 4
             exit KEYVAR,ELEMVAR,TOPVAR,LASTSEL
    
    COMPUTE MESSAGE = 'You have selected the ' + LASTSEL + ' '
    DISPLAY TEXT MESSAGE AT 15 , 20
    HORIZONTAL MENU 20,30,20,50
               spacing     2 , 2
               list        ('Do Again' 'Exit') ,0
               promptvideo 4
               box         19,29,21,51,0,0
               exit        KEYVAR,ELEMVAR,TOPVAR,LASTSEL
    IF(ELEMVAR  NE 1) EXIT LOOP
    END LOOP
    END PROGRAM


    SENSE MOUSE

    SENSE MOUSE  START row col
                 END row_var col_var
                 BUTTON button_var
                 CHARACTER char_var

    Displays a mouse cursor on the screen as the mouse is moved. Execution terminates either when a mouse button is pressed or when a keyboard key is pressed. When processing is terminated by a button pressed, the mouse cursor position and the terminating button number is reported. When processing is terminated by a keypress, the character value of the key pressed is reported (the mouse position is also reported). Specify all keywords - START, END, BUTTON, and CHARACTER - in the order shown:

    START The screen coordinates of the mouse cursor when the command is executed. The values of the starting row and column may be either explicit numbers or variable names.

    END The variables which hold the screen coordinates of the mouse when the command is completed.

    BUTTON The variable which contains the numeric value of the button that was pressed. 0 - No button (the command is terminated with a keypress); 1 - primary button; 2 - secondary button.

    CHARACTER The variable which contains the character value of the key that was pressed. 0 - if mouse button pressed.

    Two consecutive SENSE MOUSE commands may not give the user enough time to release the button from the first command. Specify a short delay, with the WAIT command, before executing the second SENSE MOUSE. The following example allows the user to draw a box on the screen by using the mouse to specify the top left and then bottom right coordinates of the box.

    PROGRAM
    SENSE MOUSE START 10 40 END R1 C1 BUTTON BN CHARACTER CHN
    DISPLAY TEXT '*' AT R1 C1   | mark corner until box is drawn
    WAIT 1                      | wait for user
    SENSE MOUSE START R1 C1 END R2 C2 BUTTON BN CHARACTER CHN
    BOX AT R1 C1 R2 C2
    WAIT 10
    END PROGRAM


    WAIT

    WAIT n

    Waits for a specified number of tenths of a second.


    Templates

    The execution window commands control the appearance of the screen. It is possible to save the way the window or part of the window looks. A stored window or portion of window is called a Template. There are commands VisualPQL and options from Tools in the pre version 4 menu system to create and save templates.

    Any stored template may be restored to its original location or to another location on the execution window during execution of a program.

    Templates may be stored in one of three places. First, during execution of a program, a template may be stored temporarily in memory. Second, a template may be stored permanently as a member in the procedure file. Third, a template may be stored permanently on a special file called the Template file.

    Templates Stored in Memory

    Since stored templates must save every character and the video attribute of the characters, a potentially large amount of memory may be needed if many screens are stored. The MEMORY option forces templates to be in memory rather than on the template file. The system parameter, MMRYTMPL , forces all temporary template storage to memory rather than the template file. This parameter can be set on the execution statement, with the SET command and with an environment setting from the pre version 4 menu system.

    Template Members

    There is a procedure file member type for templates, which is designated with a ':P' suffix. The main advantage of storing a template in the procedure file is to guarantee that it is available at execution time.

    The Template File

    When templates are saved, a template file may be created or the existing template file is used. The name of this file is either 'SYSTMPLT' or a file specified on the execution statement. Several commands store templates on this file. It is not automatically deleted upon terminating a session. The size of this file grows as each command that stores a template is executed and it should be deleted on a regular basis.

    Templates and Stored Programs

    When an executable version of a program is saved, many environmental settings are saved with it. The TEMPLATE option on the routine commands specifies that templates are stored with the executable. The default is NOTEMPLATE,.

    If the templates needed in the program are stored either in the procedure file or on the read only template file, there is never a problem. If they were stored on SYSTMPLT and have since been deleted, the executable program does not find the template and execution is terminated with an error message. The solution is to recreate and store the templates once again.


    DEFINE TEMPLATE

    DEFINE TEMPLATE tmplt_name AS member_name

    Copies a template from a template member (with a ':P' suffix) to the template file. Member name is a fully qualified member name including family name, family password, member name, member password and member type. It is a string expression, that is a string variable or a string in quotes.

    DELETE TEMPLATE FILE MEMBER name
    Removes the named template from the template file. The name may be a string constant, a string variable or [string_expression].


    POP TEMPLATE

    POP TEMPLATE [ REDRAW [ AT row, col ]
          [ IOSTAT varname] ]

    Retrieves the top-most template from the push list, removes it from the list and optionally redraws it.

    REDRAW Displays the template on the screen. If the AT clause is not specified, it is re-drawn at its original location.

    AT Specifies the placement of a re-drawn template by specifying the location of the upper left hand corner of the template.

    IOSTAT Specify a numeric variable which receives a return value. A zero indicates success. A non-zero value is the number of the associated error message.


    PUSH TEMPLATE

    PUSH TEMPLATE row1, col1, row2, col2 [ MEMORY ]

    Saves a rectangular area of the screen on a stack for later reloading. The upper left corner of the template is defined by row1 and col1, and the bottom right corner by row2 and col2.

    MEMORY Specifies that the template is stored in memory rather than on the template scratch file. This speeds up execution at the expense of memory.


    RESTORE TEMPLATE

    RESTORE TEMPLATE { LOCAL templt_name_str_value | MEMBER member_name_string_value }
                     [ AT row , col ]
                     [ IOSTAT varname]
                     [ VIDEO video_value]

    Retrieves the named template and displays it on the screen, overwriting the portion of the screen occupied by the template.

    LOCAL Restores a template stored on a template file or in memory, depending on where it was last stored. The name may be specified as a quoted string or as a variable that contains the name of the template.

    MEMBER Restores a template stored as a member in the procedure file. The member name may be fully qualified with procfile name, family name and passwords. The member must be a 'template' type, with the suffix ':P'.

    AT Specifies the placement of the upper left corner of the template. If this is not specified, the template is restored to its original location. A template that exceeds the boundaries of the execution window gives unpredictable results.

    IOSTAT Specify a numeric variable which receives a return value. A zero indicates success. A non-zero value is the number of the associated error message.

    VIDEO Specify a video value to change all video values on the restored template to the specified value.


    SCROLL TEMPLATE

    SCROLL TEMPLATE  row1 , col1 , row2 , col2
         { UP | DOWN } num_value ROWS
         [ FILLCHAR char | FILLSTRING string [ VIDEO video_value ] ]

    Moves an area of the screen, a template, up or down the specified number of rows within the specified template area. If an area is moved up one row, for example, the top line of the area disappears, the other rows move up one row and the bottom row stays the same unless a fill is specified in which case the last row would be filled with the fill character or string.

    The upper left corner of the template area is specified by row1 and col1; the lower right corner of the template area is specified by row2, col2.

    UP | DOWN UP moves the template up the specified number of rows. DOWN moves the template down the specified number of rows.

    ROWS Specifies that the unit of movement is rows and is a required keyword.

    FILLCHAR Specifies a character with which the vacated rows are filled.

    FILLSTRING Specifies a string with which the vacated rows are filled.

    VIDEO Specifies the video treatment of the fill character or string.


    STORE TEMPLATE

    STORE TEMPLATE row1 , col1 , row2 , col2
        { LOCAL name [ MEMORY ] |   MEMBER name }

    Stores a portion of the screen as a template by specifying the upper left corner coordinates ( row1 , col1 ) and the lower right corner ( row2 , col2 ). The stored template can be accessed later with the RESTORE TEMPLATE command.

    LOCAL Stores the template either on the template scratch file or in memory. It is stored in memory if the system setting MMRYTMPL is ON or if the MEMORY keyword is specified. The template name may be a string in quotes or as a string variable.

    MEMORY Specifies that the template is stored in memory rather than on the template file.

    MEMBER Stores the template as a member. The member name may be fully qualified with procfile, family name and passwords. The member is given the suffix ':P'. The name may be specified as a string in quotes or as a string variable.

    homecontents start chapter top of pagebottom of pagenext page index