VisualPQL

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

VisualPQL

Graphical User Interface

VisualPQL provides the tools to build a portable and flexible graphical user interface for your applications.

The top level of the graphical interface is created by a main program that defines the main window and menu system including all sub-menus. This receives control when a menu item is selected and can perform an action directly or can invoke other VisualPQL programs or SIR/XS commands.

Programs can create dialogs that pass control back to the user and receive control back when the user takes an action such as pressing a button.

The member SYSTEM.START in the system procedure file is the main window program. Control is returned to this program until it issues an EXIT message and the system then stops. (N.B. If a different procedure file is specified with the PROC= execution parameter, it must contain the SYSTEM family and START member.)

Any VisualPQL program can output information into the main window (such as title and status) and can put text in the window. Programs can also save, print or clear the main window.

Once the system is running, programs can display and get information through dialogs. The system has to be active for graphical commands to be executed. Any VisualPQL can be compiled when the graphical interface is not active (e.g. in batch), but running a program that uses graphical commands without the main window active returns an error.

Predefined programs can be invoked through menus and any program can create and run with dialogs. A program that creates a dialog remains active until it issues an EXIT command.

WINDOW

Window and menu definition commands and functions can only be used in the initial main program that creates the main window and menus.

WINDOW

Defines the main window and the start of the system.

END WINDOW

Defines the end of the main window and exits the system.

WINDOW TITLE

WINDOW TITLE text_var

Sets title for main window.

This command can be executed from any program running while the main window is active i.e. It is not restricted to running in the program that defines the main window.

WINDOW STATUS

WINDOW STATUS LINE text_var

Puts a message into the status bar in the main window.

This command can be executed from any program running while the main window is active i.e. It is not restricted to running in the program that defines the main window.

WINDOW OUTPUT

WINDOW OUTPUT text_var [AT CURSOR] [HTML]

Writes text to the scrolled main window. Each output line is written to the next line in the window. Specify the keyword AT CURSOR to write to the cursor position (e.g. after selecting some text). This overwrites any text following the cursor.
Specify the keyword HTML to write text formatted using a subset of standard html tags. Supported tags are:

&nbsp;
&quot;
&amp;
&lt;
&gt;

<br>
<li>
<p>
  align
    center
    right
    left
<body>
  bgcolor
    tran[sparent]
    #rrggbb
  readonly
    true
    FALSE
  wrap
    off
    ON
<h1>
<h2>
<h3>
<h4>
<h5>
<h6>
<b>
<u>
<i>
<sub>
<sup>
<big>
<small>
<code>
<pre>
<center>
<ul>
<ol> (same as ul)
<font>
   color
     #rrggbb
   size
     [+|-]n
   face
     fontname

The WINDOW OUTPUT command can be executed from any program running while the main window is active i.e. It is not restricted to running in the program that defines the main window. Note that output from a standard WRITE command that does not specify a filename also goes to the scrolled main window when running without a default output file.

WINDOW CLEAR

WINDOW CLEAR

Clears the scrolled main window.

This command can be executed from any program running while the main window is active i.e. It is not restricted to running in the program that defines the main window.

WINDOW SAVE

WINDOW SAVE filename

Saves the scrolled contents of main window as a file.

This command can be executed from any program running while the main window is active i.e. It is not restricted to running in the program that defines the main window.

Style is an integer variable - 0 for not checkable; 1 for checkable. Checkable means that a menu item can be toggled between two states (checked and unchecked) by the CHECK ITEM,UNCHECK ITEM commands and tested by function GETMCHK. When a menu item is checked it has a visual indication (a tick) next to it.

Note The main window can be closed by the user without using a VisualPQL menu item. When this happens (by using a system facility), the system passes a zero as the id. A message zero must have the same effect as any menu 'Exit' logic and so use zero as the id for the menu item associated with exit.

MENUSEP

MENUSEP

Defines a menu separator. This is only valid in pulldown menus and appears as a horizontal line.

TBARITEM

TBARITEM id,bitmap,tip_text,style

Defines an item on the toolbar.

Bitmap is the name of the bitmap that is the image of the toolbar button.

tip_text is a string variable or constant that is text displayed when the cursor is on the toolbar. Empty tips are not displayed. These can be defined in any sequence at any convenient point and the definition sequence determines the sequence across the toolbar.

Style is an integer variable - 0 for not checkable; 1 for checkable. Checkable means that a menu item can be toggled between two states (checked and unchecked) by the CHECK ITEM, UNCHECK ITEM commands and tested by function GETMCHK. When an item is checked, it has a visual indication (button depressed).

Id is an integer value passed to the message procedure. If the id is the same as a MENUITEM id both must be the same style (checkable, regular) and they are kept synchronised. (i.e. checking is on or off for both). It is strongly recommended that all toolbar items are also menu items.

TBARSEP

TBARSEP

Defines a separator (small space) on the toolbar.

INITIAL

INITIAL

Defines an initial message processing block for the menu.

At this point, the system starts and the commands in the initial block are executed. Processing from this point on is through the message blocks.

MESSAGE

MESSAGE[S] COMMAND id_var

MESSAGE DROPFILE string_var

NEXT MESSAGE

EXIT MESSAGE

END MESSAGE[S]

If a particular type of message processing block is not defined, then messages of that type are simply ignored.

The MESSAGE COMMAND processing block is the normal message block for menus. This gets control when the user selects a lowest level menu item. The id of the selected menu item is passed to the block in the variable named id_var.

The MESSAGE DROPFILE string_var receives control if the user 'drags and drops' a file into the main window. The name of the file is passed to the block in the string_var variable.

NEXT MESSAGE returns control to the user.

EXIT MESSAGE finishes processing and, in a menu, stops the SIR/XS session.

END MESSAGE finishes the definition of a message processing block. If the command is reached during execution, it returns control to the user.

ENABLE MENUITEM
DISABLE MENUITEM

ENABLE MENUITEM id
DISABLE MENUITEM id

Menu items are enabled by default. These commands enable (make selectable) or disable (grey out) a specified item.

These commands can be executed from any program running while the main window is active i.e. they are not restricted to running in the program that defines the main window.

CHECK MENUITEM
UNCHECK MENUITEM

CHECK MENUITEM id
UNCHECK MENUITEM id

Menu items are unchecked by default. These commands check (tick) or uncheck a specific item.

These commands can be executed from any program running while the main window is active i.e. they are not restricted to running in the program that defines the main window.

The function num = GETMCHK (id) tests the state of a menu or toolbar item. Returns 1 if checked; 0 if unchecked.

DISPLAY POPUP LIST

DISPLAY POPUP LIST [(string_exp,string_exp,..) | array_name,no_of_items]
              ANCHOR id | AT row,col
             [POSTYPE num_exp]
              RESPONSE num_varname
             [SEPARATOR (n,n...)]

Displays a pop up menu that remains on the screen until the user either selects an item or clicks at a point off the menu, thus canceling the menu. This command can be issued in menus, in standard dialogs or in DEDIT dialogs.

(string_exp,...)| array_name,no_of_items The menu consists of a list of entries. These can be defined either as a list of string expressions in parentheses or as a string array name followed by the number of items to be selected from the array. The menu is built with one line per item.
ANCHOR id | AT row,col The menu is either positioned relative to the control identified by the ANCHOR id or at the position specified by the AT clause. If the ANCHOR id is specified, the position of the menu is determined by the appearance of the current screen and the menu is positioned relative to the item referenced by that id in the current menu or dialog.
POSTYPE num_exp If POSTYPE is specified with a numeric expression that evaluates to 1, then values specified in the AT clause are absolute positions; otherwise, the AT clause specifies standard row/col based positions.
RESPONSE num_varname Specifies a numeric variable that is set to the position in the menu list of the item selected. If no item is selected, the response variable is set to -1.
SEPARATOR n,n... If specified, displays a menu separator after the nth item(s).

DIALOG

DIALOG title
END DIALOG

Defines a dialog. All dialog definition commands and message processing blocks must be contained in the DIALOG block. The TITLE must be specified and is a text variable or string in quotes that is displayed in the title bar of the dialog.

Dialogs have two parts:-

1) The dialog definition that specifies the dialog controls, their positions and order on the dialog. Controls are labels, buttons, edit fields, etc. that are the visual items that make up the dialog and allow the user to interact with the system. Each control is identified by a unique numeric id, that is used to reference the control during the execution of the dialog. Controls that are not referenced during execution (e.g. labels, lines) can use -1 as the id.

The following commands can be used to define dialog controls:

2) The dialog message processing routines that can be executed each time a message event takes place. Events include pressing a dialog button, pressing a character key in a text field, selecting an item in a menu etc.

If a message event occurs and there is no message processing routine for that type of event, it is ignored.

The optional INITIAL message processing routine is executed before the dialog appears on the screen.

Message processing routines can perform any appropriate function including creating a new sub-dialog and executing standard SIR/XS commands with the EXECUTE DBMS command.

Control is returned to the user by a NEXT MESSAGE command or by reaching the end of the message processing routine (the END MESSAGE command). This retains the dialog on the screen.

The EXIT MESSAGE command deletes the dialog from the screen and performs any commands that follow the END DIALOG command. When the end of the program is reached, control is returned to any higher level dialog or to the menu system.

If the user exits the dialog using the windowing system (e.g. by clicking on the X button in Windows), a button message is generated with an id of 0 (zero) so ensure that MESSAGE BUTTON 0 exits the dialog.

BORDERS

BORDERS

Specifies that the borders of labels, check boxes or radio buttons are displayed. Is only used when designing a new dialog to establish the positions of controls and to ensure they do not overlap.

Cannot be switched off once turned on for a dialog.

POSTYPE

POSTYPE (0,1)

Positioning of dialog controls uses a vertical and horizontal system of co-ordinates starting at 0,0 in the top left. The horizontal units are 1/4 of the average width for the font being used. The vertical units are by row or by absolute units. The POSTYPE command changes the vertical units from row to absolute during definition (0 is by row and is the default; 1 is by absolute units). Absolute vertical units are 1/8 font height. For precise positioning, dialog metrics can be retrieved with functions.

BUTTON

BUTTON id,row,col,width,default,text

Defines a dialog button. This is a rectangle one row deep that can be clicked by the user to indicate an action to take. This generates a message event to be handled by a message processing routine.

ID is a numeric variable or constant that identifies the control.
ROW and COL are numeric variables or constants that define the starting position of the control.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
DEFAULT is a numeric variable or constant. A value of 1 makes this the default button.
TEXT is a string variable or string in quotes and is displayed in the button. To define a mnemonic letter precede it by an &. The button label is set to this value at definition time. If you wish to change the label during message processing, use the SET ITEM command.

CHECK

CHECK id,row,col,width,text

Defines a dialog check control. This is a small square box that the user can toggle (turn on and off) followed by a label.

ID is a numeric variable or constant that identifies the control. ROW and COL are numeric variables or constants that define the starting position of the control.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
TEXT is a string variable or string in quotes. The label is set to this value at definition time. If you wish to change the label during message processing, use the SET ITEM command.

Use CHECK ITEM or UNCHECK ITEM to set the control and the GETICHK function to test the setting (0 for unchecked, 1 for checked).

CHOICE

CHOICE id,row,col,width

Defines a dialog choice control. A choice control is a box in a single row with an associated pull down list. This contains values set by the program and the user can choose one of these. A single value from the list is displayed in the box.

Set the values for the choice control in a message processing block (e.g. in the INITIAL routine) with the APPEND ITEM or INSERT ITEM commands or manipulate the values with the REMOVE ITEM, REMOVE ALL and SWAP ITEM commands. Use the GETPOS function to establish the position of a choice the user has selected or the GETTXT function to return the text value. If the values are numeric, the GETFLT or GETINT functions can also be used.

By default, the first item in the list is displayed in the box. Use the SELECT ITEM command to select a different item to display.

EDIT

EDIT id,row,col,width,pass,read

Defines a dialog edit field. This is a box on a single row and can contain text that can be set by the program and possibly entered by the user. The user can scroll horizontally if necessary to enter or view more text than can be displayed in the box.

ID is a numeric variable or constant that identifies the control.
ROW and COL are numeric variables or constants that define the starting position of the control.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
PASS is a numeric variable or constant. If this is 1 then the edit field is password protected and the data is not displayed but replaced by asterisks (this may vary on certain operating systems).
READ is a numeric variable or constant. If this is 1 then the data in the control is read only and the user cannot enter data.

Set the value of an edit control with the SET ITEM command and retrieve data with the GETTXT function (if the control is supposed to return numeric values, the GETFLT or GETINT functions can also be used.)
An EDIT control can be set to the SIR system undefined value. This is so that it can be used to hold the value of database variables which have not been initialised and are not meant to be blank. To set an EDIT control to undefined simply use SET ITEM id,var where the value of var is undefined. GETTXT will return SIR system undefined. Press Ctrl+U to set the EDIT control to undefined interactively. An undefined indicator can be set in the Preferences... dialog so that there is a visual difference between blank and undefined.

COMBO

combo id, row, col, width

A ComboBox control is a combination of an edit and a choice control. It is used when free text can be entered but a set of predefined values also exists.

ID is a numeric variable or constant which identifies the control.
ROW and COL are numeric variables or constants which define the starting position and depth of the control in vertical units.
WIDTH is a numeric variable or constant which defines the length of the control in horizontal units.

You can use the same commands and functions as with an edit control or choice control.

SPIN

SPIN id, row, height, col, width

A Spin or Up/Down control displays a numeric edit box with a pair of arrows. The up arrow increments the value in the edit control and the down arrow decrements it.

ID is a numeric variable or constant which identifies the control.
ROW, HEIGHT and COL are numeric variables or constants which define the starting position and depth of the control in vertical units.
WIDTH is a numeric variable or constant which defines the length of the control in horizontal units.

SELECT ITEM and SET ITEM work on the spin control as do the functions SETPOS GETTXT GETINT and GETPOS

IMAGE

IMAGE id,row,height,col,width,border

Defines a rectangular space for a bitmap image.

Set the actual bitmap into the control in a message processing block (e.g. in the INITIAL routine) with the SET IMAGE command.

LABEL

LABEL id,row,col,width,text

Defines a dialog label that is a single row of text.

ID is a numeric variable or constant that identifies the control. If you specify -1 as the id, the label text cannot be referenced (retrieved or modified) during the execution of the program.
ROW and COL are numeric variables or constants that define the starting position of the control.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
TEXT is a string variable or string in quotes. The label is set to this value at definition time. If you wish to change the label during message processing, use the SET ITEM command.

LINE

LINE id,row,height,col,width

Draws a box or line. The horizontal lines in a box are offset vertically so that they can enclose other controls if necessary. However a line (height of 1) takes a standard row position.

LIST

LIST id,row,height,col,width,type

Defines a dialog list control. A list control is a box in multiple rows. This contains values set by the program and the user can choose one (or more) of these. Selected items are highlighted. If there is insufficient room to display all values, the user can scroll vertically.

ID is a numeric variable or constant that identifies the control.
ROW, HEIGHT and COL are numeric variables or constants that define the starting position and depth of the control in vertical units.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
TYPE is a numeric variable or constant with the value 0, 1 or 2. These define the type of selection that the user can make from the list control as follows:-

0 Single - One and only one item can be selected. If the user clicks on a second item, the first is deselected.
1 Extend - Usually one item but more can be selected. If the user simply clicks on a second item, the first is deselected. However the user can select multiple items by using the shift key when selecting.
2 Multiple - Multiple items can be selected. If the user clicks on a second item, it is selected. If the user clicks on a previously selected item, it is deselected.

Set the values for the list control in a message processing block (e.g. in the INITIAL routine) with the APPEND ITEM or INSERT ITEM commands or manipulate the values with the REMOVE ITEM, REMOVE ALL and SWAP ITEM commands. Use the GETPOS function to establish the position of a choice the user has selected and the GETITXT function to return the text value. If the values are numeric, the GETIFLT or GETIINT functions can also be used.

RADIO

RADIO id,row,col,width,text

Defines a dialog radio control. A radio button is very similar to a check box except that it is round and that it may be in a group. A series of radio definitions without any other type of control constitutes a group. In a group of radio buttons, if the user checks one button, then automatically any other checked button is unchecked.

ID is a numeric variable or constant that identifies the control.
ROW and COL are numeric variables or constants that define the starting position of the control.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
TEXT is a string variable or string in quotes. The label is set to this value at definition time. If you wish to change the label during message processing, use the SET ITEM command.

Use CHECK ITEM or UNCHECK ITEM to set the control and the GETICHK function to test the setting (0 for unchecked, 1 for checked). If the program checks a radio control in a group, there is no automatic unchecking of other controls in the group.

SLIDER

SLIDER id,row,height,col,width

Defines a dialog slider control. A slider control is a horizontal representation of a percentage scale (0 to 100) that the user can move left or right to indicate an increase/decrease. It can be set and moved programmatically.

ID is a numeric variable or constant that identifies the control.
ROW and COL are numeric variables or constants that define the starting position of the control.
HEIGHT is a numeric variable or constant that defines the height of the control in vertical units.

WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.

Set the values for the slider control in a message processing block (e.g. in the INITIAL routine) with the SET ITEM using values between 0 and 100. Use the GETPOS function to establish the position of a slider the user has manipulated.

PROGRESS

A Progress control displays a read only progress meter.

PROGRESS id, row, height, col, width

If Height is greater that width then the bar is drawn vertically, otherwise it is horizontal.

Use the SETRANGE function to define the maximum and minimum values for the bar and SETPOS and GETPOS to set and get the position of the progress bar within the control.

The Progress bar is a read only control and does not send any messages to the dialog program.

TEXT

TEXT id,row,height,col,width,read

Defines a multi-line text control. This is a rectangular box that can display text and can allow the user to edit text. The user can scroll horizontally and vertically as necessary.

ID is a numeric variable or constant that identifies the control.
ROW, HEIGHT and COL are numeric variables or constants that define the starting position and depth of the control in vertical units.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
READ is a numeric variable or constant with values 0 or 1. 0 allows the user to edit data; 1 means that the data is read only and cannot be edited.

Set the values for the text control in a message processing block (e.g. in the INITIAL routine) with the APPEND LINE or INSERT TEXT commands. Use the GETLTXT function to return the text values line by line.

TREE

TREE id,row,height,col,width,read

Defines a tree control that is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. This is a rectangular box that can display text and can allow the user to edit text. The user can scroll horizontally and vertically as necessary.

ID is a numeric variable or constant that identifies the control.
ROW, HEIGHT and COL are numeric variables or constants that define the starting position and depth of the control in vertical units.
WIDTH is a numeric variable or constant that defines the length of the control in horizontal units.
READ is a numeric variable or constant with values 0 or 1. 0 allows the user to edit data; 1 means that the data is read only and cannot be edited.

Set the values for the tree control in a message processing block (e.g. in the INITIAL routine) with the BRANCH function. Use the information passed by the standard message processing block to identify nodes selected by the user.

The following commands and functions are used with tree controls:
BRANCH Adds a new node to a tree. The node is added as a child node of the given parent node.

BRANCHD Deletes the node from a tree.

NBRANCH Returns the number of child nodes of the given node.

BRANCHN Returns the node number of the nth child nodes of the given node.

The following list commands also work on tree controls. Note that pos is not the ordinal position of the tree item but the user supplied node number.
SELECT ITEM id,pos
REMOVE ITEM id,pos
REMOVE ALL id
GETTXT(id)
GETITXT(id,pos)
GETPOS(id)

Dialog Message Processing

INITIAL
END INITIAL

If you specify an INITIAL message processing routine, it is executed before the dialog appears on the screen. This can be used to populate lists and set the initial default state of controls.

MESSAGE[S] type id,arg1,arg2
END MESSAGE[S]
Messages are generated by a user action and are passed to the appropriate message processing block. If there is no appropriate message processing block, the message is ignored.

TYPE determines which messages are processed by the block and is one of the following keywords:
ALL, BUTTON, CHECK, CHOICE, EDIT, LIST, RADIO and TEXT.

If ALL is specified then do not specify any other message processing blocks. Otherwise you may specify one of each type. Specify either ALL or BUTTON and include appropriate logic to exit the dialog when a button message with an id of zero is received.

Every message processing routine specifies a numeric variable that is set to the id of the control that generated the message.

arg1 and arg2 are variables on some types of messages. Ensure that the correct number of variables (none, one or two) are specified for the appropriate message type. The values in the specified variables are set depending on the type of message processing block and contain frequently needed data for the type of control. However, this data can also be retrieved by functions if necessary (e.g. when using an ALL message processing routine). The following describes the arguments passed for each message type:-

ALL id,position,dbl_click Position is a numeric variable and is set to the position in a list or choice if appropriate. Dbl_click is a numeric variable that is set to 0 or 1 where 0 means a single mouse click and 1 means a double mouse click.

BUTTON id Has no further arguments.

CHECK id, check Check is a numeric variable that is set to 0 or 1 where 0 means unchecked and 1 means checked.

CHOICE id, position Position is a numeric variable and is set to the position in the choice list.

LIST id, position, dbl_click - Position is a numeric variable and is set to the position in the list. Dbl_click is a numeric variable that is set to 0 or 1 where 0 means a single mouse click and 1 means a double mouse click.

RADIO id, check Check is a numeric variable that is set to 0 or 1 where 0 means unchecked and 1 means checked.

EDIT id, hastext Hastext is a numeric variable that is set to zero if there is no text in the control and to a positive value if there is text.

TEXT id, line,position Line and position are set to the line and position of the cursor when text is entered. Line is set to zero if there is no text in the control.

Once the appropriate actions have been taken, control is returned to the dialog either by issuing a NEXT [MESSAGE] command or by reaching the end of the block. This dialog remains active until a message processing block issues a EXIT [MESSAGE] command that closes the dialog.

Other Message Types

There are three message types that are not processed by MESSAGE ALL and you must specify the message processing block explicitly if you need to process these messages. The messages are:

MESSAGE FOCUS id
MESSAGE HELP id
MESSAGE TIMER

`MESSAGE FOCUS id`	This message is generated every time focus moves off a dialog item. id is the id of the control moved away from. Use the `GETFOCUS` function to return the id of control moved to.
`MESSAGE HELP id`	When this message is specified, a small ? is displayed in the top right corner of the dialog. If the user clicks on this, it becomes a floating ? and the user can position this to a control to request help. When the user clicks again, a message is passed to the `MESSAGE HELP` block to display appropriate help for the identified control.
`MESSAGE TIMER`	This message processing block receives messages that are automatically generated. This could be used to refresh the display of some image or animation. Use the `ENABLE TIMER n` command to start automatic generation of timer messages every n tenths of a second. Use the `DISABLE TIMER` command to stop generation of timer messages.

Dialog Control Commands

The following commands can be used within a message processing block while a dialog is active. id is a numeric variable or constant. pos is a numeric variable or constant.

ENABLE ITEM id
DISABLE ITEM id
Enables and disables (greys out) a control.

FOCUS ITEM id
Sets the focus on to the control.

SHOW ITEM id
HIDE ITEM id
These two commands alter the appearance of the dialog while it is active. Items can be hidden and other items shown. Items can thus appear to be on different pages within a dialog or emulate tabbed dialogs.

SET DIALOG TITLE string
Sets the dialog title, enabling different pages within a dialog to have appropriate titles.

CHECK ITEM id
UNCHECK ITEM id
Checks a radio button or check box. If the user checks a radio button, all others in that group are unchecked by the system. If a radio button is checked by a program, the program must uncheck all others in the group.

SET ITEM id,var
The var may be text, integer or floating point and the command sets this value as the label for label, button, check and radio and as data for edit. Sets a multi-line edit control to one line containing the value specified in the variable (that may be a null string).

If the id is an EDIT control and the value of var is system undefined then the field will have this attribute set. When the undefined attribute is set then GETTXT will return undefined. The undefined indicator can be set in Preferences... to display a specific string value in a different colour.

SET ITEM FONT id,bold,italic,underline,size,face
This command changes the appearance of text in a label, edit, button, list or text box.
The bold, italic and underline can be zero or one to turn these font attributes off or on. The size is zero or +/-1. 1 makes the size of the font larger than current, -1 makes the size of the font smaller than current and 0 does not change the size (executing the command several times with a +/-1 changes the size progressively).
The face is a string and can be either a font name or a colour code. The colour codes are in the form [#RRGGBB][/#RRGGBB] where the first code sets the foreground colour and the second code sets the background colour. Specify the colour using exactly six characters; valid characters are 0 to 9 and A to F. These are three sets of hexadecimal specifications of the strength of the red, green and blue components of the colour. Each setting has a value from 00 to FF. Either component can be omitted completely. Execute the command twice to specify both a font name and colour. Note that you cannot specify the colour of a button.

Example: SET ITEM FONT IDTEXT,1,0,0,0,"#FF0000/#FFFFFF" sets the font of IDTEXT to be bold with foreground red and background white.

SELECT ITEM id,pos
Selects an item in a list. (Unselects other item in choice or list if single selection)

CLEAR SELECT ITEM id,pos
Clears selection.

SELECT ALL id
Selects all items in multiple selection.

CLEAR ALL id
Clears selection for all items in multiple selection.

APPEND ITEM id,var
Adds an item to choice or list. The var can be text, integer or floating point.

INSERT ITEM id,pos,var
Inserts an item at position in choice or list. The var can be text, integer or floating point.

SWAP ITEM UP|DOWN id
Swaps current item in list with one above or below.

REMOVE ITEM id,pos
Removes an item from choice or list.

REMOVE ALL id
Removes all items from choice or list.

SET IMAGE id,filename [type]
Puts an image from graphical file (windows or OS/2 bitmap) into a defined image or button control. If the type number is specified for an image control it can either be 1 or 2 to centre or resize the image to fit the control.

APPEND LINE id,var [HTML]
Adds a text line to a multi-line text control. Specify the keyword HTML to write text formatted using a subset of standard html tags. Supported tags are listed on the WINDOW OUTPUT command.

INSERT TEXT id,var
Inserts text into multi-line control at cursor position. The var can be text, integer or floating point.

Other GUI Commands

BEEP
Issues a short beep (displaying an error box beeps automatically).

DISPLAY TIPBOX str
Pops up a message. str is a string variable or string constant in quotes that is the message to display.

DISPLAY INFOBOX str
Displays a message in a dialog with an OK button. str is a string variable or string constant in quotes that is the message to display.

DISPLAY ERRBOX str
Displays an error message. str is a string variable or string constant in quotes that is the message to display.

DISPLAY OKCANBOX str RESPONSE var
Displays a message and asks for an OK or Cancel response. str is a string variable or string constant in quotes that is the message to display. var is a numeric variable that receives 1 (OK) or 0 (Cancel).

DISPLAY YESNOBOX str RESPONSE var
Displays a message and asks for a Yes or No response. str is a string variable or string constant in quotes that is the message to display. var is a numeric variable that receives 1 (Yes) or 0 (No).

DISPLAY YNCBOX RESPONSE var
Displays a Yes, No, Cancel Box. var is a numeric variable that receives 1 (Yes) or 0 (No) or -1 (Cancel)

DISPLAY TEXTBOX label [SECRET] RESPONSE var, mess_text
Displays a text input box. label is a string variable or string constant in quotes that is displayed as the title on the box. This normally indicates to the user what is being asked for. var is a numeric variable that receives -1 (Cancel) or length of string. mess_text is a string variable that is set to the value of the text entered by the user. SECRET is a keyword that means that the text is echoed back as ***.

DISPLAY OPENBOX title,filter,ext,exists RESPONSE var,mess_txt
Displays a file browse box. title is a string variable or string constant in quotes that is displayed as the title of the box.
filter is a string variable or string constant in quotes in format Type|mask e.g. List files|*.lis|All files|*.*|
ext is a string variable or string constant in quotes and is the file extension in lower case without a leading period.
exists is a numeric variable or constant. 1 means the file must already exist; 0 allows a new file to be created; -1 means that the command returns a directory name instead of a filename.
var is a numeric variable that receives 0 (Cancel) or length of string. mess_text is a string variable that is set to the value of the filename selected or entered by the user.

DISPLAY SAVEBOX title,filter,ext,overwrite RESPONSE var,filename
Displays a Save As file box. title is a string variable or string constant in quotes that is displayed as the title of the box.
filter is a string variable or string constant in quotes in format Type|mask e.g. List files|*.lis|All files|*.*|
ext is a string variable or string constant in quotes and is the file extension in lower case without a leading period.
overwrite is a numeric variable or constant. If this is 1 then, if the file already exists the user is prompted for permission to overwrite; if 0, then an existing file is simply overwritten.
var is a numeric variable that receives 0 (Cancel) or length of string. mess_text is a string variable that is set to the value of the filename selected or entered by the user.

PRINT filename [DEFAULT] [MARGINS l,r,t,b] [FONT n] [WRAP|PAGE|TRUNCATE]
Prints a text file. filename is a string variable or string constant in quotes and is the operating system filename not a SIR/XS internal file attribute.
If the DEFAULT keyword is specified printing commences immediately, otherwise a Print box to alter print specifications is displayed.
MARGINS are in mm and defaults are 25 left, right 20 top, bottom.
FONT is in points with a default of 10.
WRAP, PAGE and TRUNCATE specify the way long lines are handled. Wrap splits the long line over several print lines; Page will print long lines on separate pages and Truncate will only print that part of the line that will fit on the page.

INVOKE DDESIGN filename
Invokes the Dialog Designer. filename is a string variable or string constant in quotes and is the operating system filename not a SIR/XS internal file attribute. The file should be a file saved by the dialog designer.

DEDIT

DEDIT type,id,arg1,arg2
END DEDIT

The DEDIT dialog editor is a full screen dialog that allows the program and user to interact to place controls of various types and to edit visually these controls. The dialog visually resizes to accommodate controls. This is the basis for the dialog painter and PQLForms painter and can also be used to develop custom painting style applications.

Controls are placed on the dialog through commands and functions rather than through any definitions. There is no separate message definition command. Control is returned to this block each time a message is generated.

The command requires the specification of four numeric variables. These variables return the message type, the id of any control and two arguments, either x (across the screen) and y (down the screen) co-ordinates or width and height of the control on a size message.

Message types are as follows:

Value   Message     id     arg1   arg2
 0      Initial      0        0      0
 1      Exit         0        0      0
 2      Key        key        0      0
 3      Rclick      id        x      y
 4      Ctrl-D       0        0      0
 5      Move        id        x      y
 6      Resize      id        w      h
 7      Del         id        0      0
 8      Dblclick    id        0      0
 9      F9           0        0      0
10      F5           0        0      0
11      F1(Help)     0        0      0
12      Ctrl-Z(Undo) 0        0      0

Initial is sent after the dialog editor window has been created, but before it is made visible. The program can put the initial set of controls into the editor.

Exit is sent when the user tries to close the dialog editor. The program needs to exit the dialog to stop the editor.

Rclick is sent when the user right clicks the mouse. If the mouse is positioned on a control, the control is selected (if not already selected) and the id is passed, otherwise any selected control is deselected and id is set to zero. X and Y position is passed.

Move and Resize are sent as the user moves/resizes a control. The program should just accept the new position or size and do nothing else. If a group of controls is moved/resized as a single operation, the program receives separate messages for each control. The program must not interact with the user nor change the editor's control set while processing this message.

Dblclick is sent when the user quickly left clicks the mouse twice. If the mouse is positioned on a control, the control is selected and id is passed, otherwise any selected control is deselected and id is set to zero.

Help is sent when the user presses F1. The application should display appropriate help.

Other messages are passed when the user presses various keys. It is up to the individual application to assign meanings to these. An application typically uses the DISPLAY POPUP LIST command to offer the user a set of appropriate actions to take e.g. to insert a control, to copy a control, etc. on given messages. The Rclick passes co-ordinates so is appropriate for inserting a new control at a given position.

The following keys are enabled during a DEDIT dialog:

Key
ESC                      No Message - Unselects if one or more controls are selected
TAB                      No Message - Selects next

                         Message     id arg1 arg2
Shift+Esc                Exit         0    0    0
Esc (None Selected)      Exit         0    0    0
Arrow (Selected Item(s)) Move        id    x    y
Shift+Arrow      "       Resize      id    w    h
Ctrl+Arrow       "       Fine Move   id    x    y
Ctrl+Shift+Arrow "       Fine Resize id    w    h
Delete                   Delete      id    0    0
Return or Space          Dblclick    id    0    0 (id is zero if none selected)
Ctrl+Z                   Undo         0    0    0
D                        Ctrl-D       0    0    0
F1                       Help         0    0    0
F2                       Rclick       0    0    0
F5                       F5           0    0    0
F9                       F9           0    0    0
Insert                   Key          0    0    0

L:[Label]                Key          1    0    0
E:[Edit]                 Key          2    0    0
B:[Button]               Key          3    0    0
K:[Check]                Key          4    0    0
R:[Radio Button]         Key          5    0    0
C:[Choice]               Key          6    0    0
M:[List]                 Key          7    0    0
T:[Text]                 Key          8    0    0
H:[Horizontal Line]      Key          9    0    0
V:[Vertical Line]        Key         10    0    0
S:[Box]                  Key         11    0    0
I:[Image]                Key         12    0    0

Note The dialog editor is not reenterable. You cannot start a second instance while the first one is active.

INSERT DCONTROL

INSERT DCONTROL id,type,x,y,w,h,text

Inserts a control on a DEDIT dialog. Control types are as follows:

LABEL   1
EDIT    2
BUTTON  3
CHECK   4
RADIO   5
CHOICE  6
LIST    7
TEXT    8
HLINE   9
VLINE  10
LBOX   11
IMAGE  12

Positioning of dialog edit controls uses a horizontal (x) and vertical(y) system of co-ordinates starting at 0,0 in the top left. The horizontal units are 1/4 of the average width for the font being used. The vertical units are 1/8 font height. See POSTYPE to use these same units in standard dialogs.

Height and width use the same units. Height is irrelevant to control types 1 to 6. Various controls have minimum height and/or width limits. A height of 12 and a width of 32 is sufficient for all control types.

The text is displayed in an appropriate place for the control and should be helpful to the user to identify the control in some way.

MODIFY DCONTROL

MODIFY DCONTROL id,x,y,w,h,text

Modifies the position, size and text of a control on a DEDIT dialog. The control type cannot be modified.

MODIFY DCONTROL FONT

MODIFY DCONTROL id,bold,italic,underline,size,font/colour

Modifies the font of a control on a DEDIT dialog. The specifications for the font are the same as SET ITEM FONT.

REMOVE DCONTROL

REMOVE DCONTROL id

Removes a control from a DEDIT dialog.

SELECT DCONTROL

SELECT DCONTROL id

Selects a control on a DEDIT dialog. The user can do this interactively without program intervention.

CLEAR DCONTROL

CLEAR DCONTROL id

De-selects a control on a DEDIT dialog. The user can do this interactively without program intervention.

DEDIT MESSAGE

DEDIT MESSAGE text_exp

Displays a text message in the message area at the bottom of a DEDIT dialog. The current position, size and id of any selected control are automatically displayed alongside the message area.

GRID

GRID title_string_exp
     list_of_arrays (1 or 2 dimension)
     [HEADERS=(list_of_col_headers)]
     [RESPONSE = integer_varname|
                 array_varname]
     [SIZE=rows]
     [DISPLAY=row,width]
     [UPDATE | NOUPDATE]

The GRID command displays data in a spreadsheet format and can be used to display arrays of data and to accept back changes. The grid is a dialog with predefined buttons and a grid of data. The columns are array variables; the rows are occurrences in the array. The grid displays very quickly and essentially has no size limitations beyond those imposed by processing very large arrays.

title_string_exp A string expression (e.g. 'My Data') that is displayed as the title of the dialog.

array_name, array_name, ... A list of array variables of one or two dimensions. The first dimension represents the number of rows of data. If the variable has a second dimension, this is taken as multiple columns. The following example displays 20 rows and 5 columns:
INTEGER*4 ARRAY MYARRAY (20) INTEGER*4 ARRAY MYARRAY1 (20,4) GRID 'Example' myarray, myarray1
Variables can be any type. Maximum total number of columns is 256.

HEADERS= (heading, heading, ...) A list of string expressions that are used as column headings. The position in the list corresponds to the column. The default heading is the variable name. The default headings for columns defined by a two dimensional array is the variable name for the first occurrence, then the variable name and subscript value for subsequent occurrences.

RESPONSE = integer_varname| array_varname Either a single integer variable that contains 0,1 or -1 or a two dimensional array that contains 0,1 or -1 in each element. 0 means not updated; 1 means updated; -1 means an error occurred. If rows are deleted, then the array is shorter and response values after the end of the new array size are set to missing.

SIZE=rows Number of rows available to the user. The default is the first dimension of the smallest array being used (including any response array). If the user chooses to insert rows, the dimension of all arrays must be large enough to allow the insertion.

DISPLAY = row, width Number of rows and width of visible grid. Rows must be between 10 and 50; width between 50 and 150 characters. The default is 10 rows, 80 characters.

UPDATE | NOUPDATE Whether the user is allowed to update the data. The default is UPDATE.

`(string_exp,...)\| array_name,no_of_items`	The menu consists of a list of entries. These can be defined either as a list of string expressions in parentheses or as a string array name followed by the number of items to be selected from the array. The menu is built with one line per item.
`ANCHOR id \| AT row,col`	The menu is either positioned relative to the control identified by the `ANCHOR` id or at the position specified by the `AT` clause. If the `ANCHOR` id is specified, the position of the menu is determined by the appearance of the current screen and the menu is positioned relative to the item referenced by that id in the current menu or dialog.
`POSTYPE num_exp`	If `POSTYPE` is specified with a numeric expression that evaluates to 1, then values specified in the `AT` clause are absolute positions; otherwise, the `AT` clause specifies standard row/col based positions.
`RESPONSE num_varname`	Specifies a numeric variable that is set to the position in the menu list of the item selected. If no item is selected, the response variable is set to -1.
`SEPARATOR n,n...`	If specified, displays a menu separator after the nth item(s).

Graphical User Interface

WINDOW

WINDOW TITLE

WINDOW STATUS

WINDOW OUTPUT

WINDOW CLEAR

WINDOW SAVE

MENU

MENUITEM

MENUSEP

TBARITEM

TBARSEP

INITIAL

MESSAGE

ENABLE MENUITEMDISABLE MENUITEM

CHECK MENUITEMUNCHECK MENUITEM

DISPLAY POPUP LIST

DIALOG

BORDERS

POSTYPE

BUTTON

CHECK

CHOICE

EDIT

COMBO

SPIN

IMAGE

LABEL

LINE

LIST

RADIO

SLIDER

PROGRESS

TEXT

TREE

Dialog Message Processing

Other Message Types

Dialog Control Commands

Other GUI Commands

DEDIT

INSERT DCONTROL

MODIFY DCONTROL

MODIFY DCONTROL FONT

REMOVE DCONTROL

SELECT DCONTROL

CLEAR DCONTROL

DEDIT MESSAGE

GRID

ENABLE MENUITEM
DISABLE MENUITEM

CHECK MENUITEM
UNCHECK MENUITEM