Introduction

DIALOG PAINTER

Control Properties

Properties of a Button

List View

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.
• Cut Removes selected controls to the clipboard.
• Paste Inserts previously cut controls into the current selected position.

• 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.
• Check & checks for duplicate alt-letter assignments. It displays a list of the duplicates as well as lists of used and available letters.

• 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;
  • Combo - a combination of edit and choice;
  • Progress - a progress bar;
  • Tree - a tree list;
  • Slider - a dragable slider;
  • Spin - a numeric edit with up/down arrows.
• 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 predefined names with values viz. IDCLOSE value 0 (zero) and IDSTATIC value -1. These names can be used many times in a dialog but cannot be reference by the VisualPQL code (ie you cannot modify or read values during execution).

  Any name starting with uppercase ID is automatically assigned a unique numeric value. If the 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.

Dialog Properties

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, Document, Prologue, 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.

Document
This text will become a comment at the start of the generated program.

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

Initial
The Initial section contains the code to initial the controls in the dialog.

Message
The Message section contains the code executed each time a dialog event message is issued, irrespective of which control is involved.

Timer
The Timer section contains the code executed when a timer message is sent. The timer is set with the ENABLE TIMER n command. This command makes the timer message block execute every ⁿ/₁₀ seconds. The DISABLE TIMER command stops timer messages.

Exit
The Exit section contains the code executed after the dialog is removed from the screen.

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.

Control:
The Control: section contains the VisualPQL message block for the control selected in the choice. This is the same code as the message block in the control properties dialog.

Dialog Painter Format

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

|}

Multipage Dialogs

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 switched 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
|}

PQLFORMS PAINTER

Run the 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 PQLForm

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 Space Evenly Same Width Same Height Properties... Delete Exit

The Align Left, Right, Top & Bottom commands move all selected controls into alignment with the control that was right mouse clicked. That control does not move. The Align Row command move all selected controls into vertical centre alignment with the control that 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 that was right mouse clicked. That control does not change. The Properties... option will display a multiple field properties dialog which will allow changing of attributes across all selected fields. 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 Properties

Properties of a Field

The Position and size of the prompt, data, and labels can be manually altered here or in the painter canvas. You can set various font attributes for prompt, data and label using the corresponding Font... button.

Check the Read Only box to make the field not updatable by the forms user.

Check the No Echo box to make the field secret. When data are entered into these fields they are displayed as asterisks.

The Alias field can be used to enter the variable's name if this field's name is not a record variable. Use this if you have several variables in the database with the same name but different data types. You would give each of these different field names with aliases to the real variable name.

Select a Next Field which the keyboard focus will move to after this field. Optionally enter an If condition for the next field processing.

Button Properties

Properties of a CALL Button

The Position and size of the button can be manually altered here or in the painter canvas. You can set various font attributes for the button text using the Font... button.

Check the AUTO CALL box to make the button hidden and automatically call the screen after processing the previous field (an AUTO CALL button cannot be the first control in the screen). The button will still be visible in the painter but not when the form is run.

Enter an IF condition which must be true to allow the button to be pressed.

Specify a HELP string expression which is displayed when the user requests context sensitive help on the button.

Check ONCALL LAST or ONCALL FIRST to go automatically to the first or last record when the screen is called.

Check USING or VIA to specify the keys to use when calling the record. USING needs a case id and keys whereas VIA just needs the record keys.

After PQL specifies PQL code executed after the button has been presses. This can be multi-lined code and there is no need to end lines with ;.

Properties of an ACTION Button

Field Sequence

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 field sequence does not effect the position of the fields on the screen.

Screen Properties

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.
Title Code is executed when each page is first displayed. Use this to set the dialog title.
Select Code is executed after a data record is read from the database. Set FAILFLD to non-zero to skip this record and read the next.
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.

Form Properties