Properties of a Button

In the lower part of the dialog is a text box which contains the VisualPQL commands that are executed when various messages associated with this item are sent from the windows system to the VisualPQL program.

The Message section contains the VisualPQL that is executed when the button is pressed, or a change is made in an edit, choice, check box, list or radio control, or the mouse is clicked in an image.

The Context Help section contains the VisualPQL that is executed when the HELP button is pressed or the question icon on the dialog frame is pressed followed by a click on this control. The code typically pops an information box with some kind of help about the control. E.g:
DISPLAY INFOBOX "Enter your FULL name"

The Focus section applies to edit and multi-line text controls. It contains the VisualPQL that is executed when the control is left (ie looses focus). This VisualPQL might be used to validate a string or perform some other action based on the entire string. The ordinary edit messages are sent each time a character is typed.

Identifier Names

The value -1 need not be unique, many controls in the dialog can have this identifying value but no processing can occur on these controls. They are usually labels or lines.

There is VisualPQL code generated to terminate the dialog when a control with an identifying value of zero (IDCLOSE) is used. You can define code to be executed before the dialog terminates. Closing the dialog using the X (or Alt+F4 in Windows) sends a message with ID zero to the VisualPQL program.

If you use names beginning with "UD" (for user defined) then these are not automatically preset in the generated program. You must assign values to these yourself. This is useful when you want to have a meaningful assignment of numbers to identifiers (eg a set of radio buttons with values and labels "1999","2000","2001","2002").

You can use numbers (integers greater than -1) as control identifiers in the painter.

All other identifying names are assigned a unique arbitrary positive integer value.

Special Variables

m_id contains the value of the dialog item which has just been pressed or changed.
m_arg1 and m_arg1 contain more information on the control.
m_page indicates which pane of a multi-paned dialog is displayed.

List View

The dialog is split into two parts with a horizontal line. The top part controls the layout of the whole dialog. The Dialog title is the text to display in the title bar of the generated dialog. The main box under the title is a list of the controls currently defined for the dialog. A new control can be added by making selections in the bottom section of the designer and pressing Append. There are a number of action buttons down the left and right of the control list as follows:-

• Up Moves the selected control up in the list of controls. The order in the list defines the order that focus is set when the user 'tabs' around the dialogs fields. This does not effect the layout of the dialog.
• Down Moves the selected control down in the list of controls.
• Remove Removes the selected control(s) from the dialog
• Edit Copies the settings for the selected control to the bottom section of the Dialog Designer for editing.
• PQL Displays the selected control's properties.

• Close Exits the List View and returns to the painter after prompting to save any changes.
• Reset Removes all controls from the dialog.
• Save Saves changes made to the dialog layout.
• Test Displays a test dialog. To dismiss the displayed dialog press any button or the close button (usually in the top right corner marked 'X').

• P+ Moves the selected control(s) to the next page in a multi-paged dialog.
• P- Moves the selected control(s) to the previous page in a multi-paged dialog.
• R+ Moves the selected control(s) up one row in the dialog layout.
• R- Moves the selected control(s) down one row in the dialog layout.
• << Moves the selected control(s) left by the number of columns shown in the choice field.
• >> Moves the selected control(s) right by the number of columns shown in the choice field.
• >< Shortens the selected control(s) by the number of columns shown in the choice field.
• <> Lengthens the selected control(s) by the number of columns shown in the choice field.
• |<- Aligns all selected controls to the left most column of the selected controls.
• [=] Makes all selected controls the same width as the widest of the selected controls.
• ^=^ Aligns all selected controls to the top of the topmost control.
• v=v Aligns all selected controls to the bottom of the bottom most control.

• Type selects the type of dialog control. The options are:
  • Label - a static or programmer changeable labels;
  • Edit - a single line text entry box;
  • Button - a button;
  • Check - an on/off button;
  • Radio - one of a set of on/off buttons of which only one may be on;
  • Choice - a pull down list;
  • List - a scrollable list;
  • Text - a multi-line text entry box;
  • Line - a drawn line or box;
  • Image - a picture.
• Id Each item must have an identifier associated with it. This identifier is an integer and if it is to be referenced elsewhere in the VisualPQL code then the number must be unique to this dialog. When using the Dialog Commander, you can use two special names with predefined values viz. IDCLOSE value 0 (zero) and IDSTATIC value -1. This name can be used many times in a dialog but cannot be reference by the VisualPQL code (ie you cannot modify or read its value during execution).

  Any name starting with uppercase ID is automatically be assigned a unique numeric value. If your id does not start with ID then you must define and set it to a unique number in the PROLOGUE section.

• Text is the label on Buttons, Radio Buttons, Check Boxes, and plain Labels. This is disabled for other control types.
• Row is the vertical position of the control in the dialog. 0 (zero) is the top row.
• Nrows in the height in rows for Lists, multiline Text, Lines and Images. This is disabled for other control types.
• Pos is the horizontal position of the control in the dialog. 0 (zero) is the leftmost column. There are approximately 4 units to a character.
• Width is the width of the control in horizontal units.
• Password can be checked for Edit controls. Text entered in password edit areas can not be read. This is disabled for other control types.
• ReadOnly can be checked for Edit and multiline Text controls. Text displayed in these areas cannot be modified. This is disabled for other control types.
• DefButton can be checked for one Button control. This button is the Dialog's default button. This is disabled for other control types.
• Border draws a box around Image controls. This is disabled for other control types.
• Single / Extended / Multiple selects the behaviour of List controls. Single means one and only one selection can be made. Extended means one or more selections and multiple means zero or more. Multiple selections are made by clicking on the menu item and unselected by clicking on a selected item.

• Append Appends the control defined in this section to the end of the list of controls.
• Modify Replaces the selected item in the list of controls with the control defined in this section.
• Clear Clears the details in this section.

The Dialog Properties

Below are some settings specific to the painter. The Row and Col step set a grid size for use in the painter. You can also set the dialog page to display if there is more than one page defined.

The left side of the Dialog Commander is a list of the sections in this program. The default program sections are Header, Footer, Prologue, Controls, Initial, Message, Timer, Exit, Footer and specific Control:. the right side of the dialog is the VisualPQL code associated with the current section. You can modify this code.

Header
The text associated with Header typically includes the command to identify the beginning of a VisualPQL routine i.e. PROGRAM or RETRIEVAL or SUBROUTINE. If it does not then the generated code must be included in a program and cannot be run stand-alone.

Footer
The Footer should include the corresponding END command from the Header. e.g. END PROGRAM. The Footer can also be used for user subprocedures.

Prologue
The Prologue contains code to be executed before any other executable commands.

|| Generated by DP - don't edit anything outside |{...|}

|{ Header

|}

integer*4 m_id, m_arg1, m_arg2

integer*4 IDSTATIC; preset IDSTATIC (-1)
integer*4 IDCLOSE ; preset IDCLOSE  ( 0)
integer*4 ....... ; preset .......  ( 1)
integer*4 ....... ; preset .......  ( 2)
...

|{ Prologue

|}

dialog "...title"

|{ Controls

|}

initial
|{ Init

|}
end initial

message ALL m_id, m_arg1, m_arg2

|{ Message

|}

ifthen (m_id eq CONTROL_ID )
|< CONTROL_ID

|>
next message
endif

if (m_id eq 0) exit message

end message

|{ Context Help
message HELP m_id

ifthen (m_id eq CONTROL )
|< CONTROL_ID

|>
next message
endif


end message
|}
message FOCUS m_id
|{ Focus

ifthen (m_id eq CONTROL )
|< CONTROL_ID

|>
next message
endif


|}
end message
message TIMER
|{ Timer

|}
end message

end dialog
|{ Exit

|}
|{ Footer

|}

You can change a control’s page number in the control item properties screen.

Page set to one

To make a dialog with multiple pages using the painter you need some switching method. If this is under user control this might be a choice control or a set of buttons. You can also use paging to show or hide controls under other conditions.

The switch must change the value of the variable m_page and then EXECUTE SUBPROCEDURE PAGE.

Page switced by a radio button

|| Generated by DP - don't edit anything outside |{...|}

|{ Header
PROGRAM
|}

integer*4 m_id, m_arg1, m_arg2

integer*4 IDSTATIC; preset IDSTATIC (-1)
integer*4 IDCLOSE ; preset IDCLOSE  ( 0)
integer*4 IDBUTT1 ; preset IDBUTT1  (1 )
integer*4 IDEDIT2 ; preset IDEDIT2  (2 )
integer*4 IDPAGE1 ; preset IDPAGE1  (3 )
integer*4 IDPAGE2 ; preset IDPAGE2  (4 )
integer*4 m_page; preset m_page (1)

|{ Prologue
|}

dialog ""

|{ Controls
postype 1
button    IDBUTT1 ,  14,        0, 120, 0, "Press ME"
edit    IDEDIT2 ,  14,        0, 117, 0, 0
radio   IDPAGE1 ,   0,        2,  40, "Page 1"
radio   IDPAGE2 ,   0,       52,  40, "Page 2"
|}

initial
|{ Init
|}
. EXECUTE SUBPROCEDURE PAGE
end initial

message ALL m_id, m_arg1, m_arg2


ifthen (m_id eq IDBUTT1 )
|< IDBUTT1
display infobox "Thank you"
|>
next message
endif

ifthen (m_id eq IDPAGE1 )
|< IDPAGE1
SET M_PAGE (1)
EXECUTE SUBPROCEDURE PAGE
|>
next message
endif

ifthen (m_id eq IDPAGE2 )
|< IDPAGE2
SET M_PAGE (2)
EXECUTE SUBPROCEDURE PAGE
|>
next message
endif

if (m_id eq 0) exit message

end message


end dialog
|{ Exit
|}
|{ Pages
SUBPROCEDURE PAGE
.  HIDE ITEM IDBUTT1
.  HIDE ITEM IDEDIT2
.  IFTHEN (m_page EQ 1  )
.    SHOW ITEM IDBUTT1
.  ENDIF
.  IFTHEN (m_page EQ 2  )
.    SHOW ITEM IDEDIT2
.  ENDIF
END SUBPROCEDURE
|}

|{ Footer
END PROGRAM
|}

Run the Forms painter from the menu system by selecting Program, PQLForms Painter... and entering a member or filename that either contains a PQLForms program or does not exist.

The PQLForms painter allows you to control the layout of a form screen; the type, size and position of the individual controls on the form.

Creating a new PQLForms Program

New Database Record Screen

Record Screen Painter

New Field New Local Var New Call New Action Button New Text New Horizontal Line New Vertical Line New Box New Image Screen Properties Field Sequence Test Help Undo Exit

The New Field command inserts a field from the current record or table. The New Local Var command inserts a field based on a derived variable. The New Call command inserts a CALL button to access another PQLForms screen. The New Action Button command inserts an Action Button. A list of Action button types is given. Action buttons can be used to navigate through the data in to form or to execute some user defined VisualPQL. The New Horizontal Line, Vertical Line and Box commands draw lines on the screen. The New Image command defines a bitmap image area for the screen. The Screen Properties (Enter) command controls the properties of the whole PQLForms screen. It also lets you set which page of the VisualPQL screen is visible on the painter canvas. The Field Sequence command lets you change the order in which the fields are processed (using the tab key). This does not change the visual layout. It also lets you define pages of the screen and move fields from one page to another. Test (F5) executes the VisualPQLform layout commands (not the processing commands) so you can see how the final layout looks. Help (F1) displays this help page. Undo (Ctrl+Z)undoes the last painter action or set of moves or resizes. Exit terminates the painter, prompting to save any changes.

Once you have put a field or button on the canvas, right mouse click over it to see a menu of commands related to this control.

Select set Properties... Delete Exit

Select Set selects any Prompt, Data and Label for the field, allowing it to be moved as a group. The Properties (Enter) command controls the properties of this particular field or button. This includes the VisualPQL executed after the field is entered. Delete removes the field or button from the dialog.

When you have more than one field on the canvas, you can select more that one control (by dragging a rectangle around them with the mouse, or CTRL and select), right mouse click on one of the selected items to see a menu of commands related multiple fields.

Align Left Align Right Align Top Align Bottom Align Row Same Width Same Height Delete Exit

The Align Left, Right, Top & Bottom commands move all selected controls into alignment with the control which was right mouse clicked. That control does not move. The Align Row command move all selected controls into vertical centre alignment with the control which was right mouse clicked. That control does not move. The Same Width & Height commands resize all selected controls to be the same as the control which was right mouse clicked. That control does not change. Delete removes the fields from the dialog.

Moving and resizing

PQLforms coordinates are based on text rows and columns. Fine movements and resizing cannot be made.

If more than one control is selected then all are resized or moved.

Field Sequence

The list shows variables in processing order. Select a variable and use the buttons on the left to move the field up or down in the processing order. Press the Page button to insert a page break between fields.

The SCREEN Properties

The Screen name is specific to this PQLForms program and is used to reference the screen in CALLs from other places in the program.

The record name defines which database record or tabfile table the screen accesses.

The Index name defines which database or tabfile index is used to process the data.

You can enter VisualPQL code to execute at various stages of data entry. Initial Code is executed when the screen is first called. Read is executed after a data record is read from the database. Write before the form data is written to the record. Loop is executed every time a field is processed.