
VISUALPQL		Graphical User Interface

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 which 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 SIR2002 commands.

Programs can create dialogs which 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. using WDL, batch or the execution window), but running a program which 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 which 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 which 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 which 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 should have the same effect as any menu 'Exit' logic and so zero should be used 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 which 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 toolitems 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 SIR2002 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 which remains on the screen until the user either selects an item or clicks at a point off the menu, thus cancelling 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 which 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 which is displayed in the title bar of the dialog.

Dialogs have two parts:-

1) The dialog definition which specifies the dialog controls, their positions and order on the dialog. Controls are labels, buttons, edit fields, etc. which are the visual items which make up the dialog and allow the user to interact with the system. Each control is identified by a unique numeric id, which is used to reference the control during the execution of the dialog. Controls which 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 which 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 SIR2002 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 which 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.

BUTTON

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

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

ID is a numeric variable or constant which identifies the control.
ROW and COL are numeric variables or constants which define the starting position of the control.
WIDTH is a numeric variable or constant which 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 which the user can toggle (turn on and off) followed by a label.

ID is a numeric variable or constant which identifies the control. ROW and COL are numeric variables or constants which define the starting position of the control.
WIDTH is a numeric variable or constant which 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 which 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 which identifies the control.
ROW and COL are numeric variables or constants which define the starting position of the control.
WIDTH is a numeric variable or constant which 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 which means that 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.)

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 which is a single row of text.

ID is a numeric variable or constant which identifies the control. The id can be -1 which means that the label text cannot be referenced (retrieved or modified) during the execution of the program.
ROW and COL are numeric variables or constants which define the starting position of the control.
WIDTH is a numeric variable or constant which 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 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.
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.

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.

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 which identifies the control.
ROW and COL are numeric variables or constants which define the starting position of the control.
WIDTH is a numeric variable or constant which 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.

TEXT

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

Defines a multi-line text control. This is a rectangular box which 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 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.
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.

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 these 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 no other message processing blocks should be specified. Otherwise you may specify one of each type. Either ALL or BUTTON should be specified and appropriate logic included to exit the dialog when a button message with an id of zero is received.

Every message processing routine must specify a numeric variable which 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 which 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 which 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 which 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 which is set to 0 or 1 where 0 means unchecked and 1 means checked.

EDIT id, hastext Hastext is a numeric variable which 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 which closes the dialog.

Special Messages

There are three special message types which are not processed by MESSAGE ALL and have to be specified if processing is required. These are:

MESSAGE FOCUS id
MESSAGE HELP id
MESSAGE TIMER

`FOCUS id`	If this message is specified, it receives a message every time focus moves off a dialog item. id is the id of the control which has just been moved away from. Use the `GETFOCUS` function to returns the id of control with had been moved to.
`MESSAGE HELP id`	If this message is specified, then 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 which should 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, it should 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 (which may be a null string).

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.

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
Puts an image from graphical file (windows or OS/2 bitmap) into a defined image 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 OUTPUT WINDOW 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 INFOBOX str
Displays a message. str is a string variable or string constant in quotes which is the message to display.

DISPLAY ERRBOX str
Displays an error message. str is a string variable or string constant in quotes which 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 which is the message to display. var is a numeric variable which 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 which is the message to display. var is a numeric variable which receives 1 (Yes) or 0 (No).

DISPLAY YNCBOX RESPONSE var
Displays a Yes,No,Cancel Box. var is a numeric variable which 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 which is displayed as the title on the box. This would normally indicate to the user what is being asked for. var is a numeric variable which receives -1 (Cancel) or length of string. mess_text is a string variable which is set to the value of the text entered by the user. SECRET is a keyword which 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 which 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. If this is 1 then the file must already exist; if 0 then a new file can be created; if -1 then the command will return a directory name instead of a filename.
var is a numeric variable which receives 0 (Cancel) or length of string. mess_text is a string variable which 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 which 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 which receives 0 (Cancel) or length of string. mess_text is a string variable which is set to the value of the filename selected or entered by the user.

PRINT filename [DEFAULT] [MARGINS=(l,r,t,b)] [FONT=n]
Prints a text file. filename is a string variable or string constant in quotes and is the operating system filename not a SIR2002 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.

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 SIR2002 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 which allows the program and user to interact to place controls of various types and to visually edit 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 actually 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 would typically use 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

NoteThe 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.

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 special 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') which 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 which 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 which contains 0,1 or -1 or a two dimensional array which 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 which 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).