FORM Object

Members

Methods

Note:
SetActive()and SetGadgetsActive()can be used in combination with each other and with the Active property of individual gadgets.

Commands

LAYOUT FORM

The recommended way to define forms is using LAYOUT FORM, but the old 'setup form' command is still supported for upwards compatibility.

A form definition is introduced by the LAYOUT FORM command and terminated by a corresponding EXIT command. Once in form definition mode you can call any commands for defining the form’s properties, creating a menu bar (see BAR object), main and popup menus (see MENU object) and any gadgets which it is to own.

Once-only form attributes are entered as part of the LAYOUT FORM command line; modifiable attributes are entered as contents of the form.

VARCHARS and FIXCHARS

Two layout modes are supported, namely VarChars and FixChars.

VarChars is a new layout mode, based on measuring precise string widths. It is implicit for LAYOUT FORM and cannot be changed. It is better suited to the use of variably spaced fonts, and removes the need for most uses of the TagWidth specifier. The benefits of using VarChars are:

It tends to produce smaller, more pleasing forms, without unwanted space.

No text wrap-around, except possibly in conjunction with TagWidth.

No truncation of explicitly defined text except possibly in conjunction with TagWidth.

The recommended layout mode for all new forms is:

layout form !!<form_name> . . .

FixChars is the old layout mode (prior to PDMS12.1), which is based on the use of notional character width to calculate the (approx.) sizes of textual gadgets and gadget tags. Because the calculated sizes are only approximate, you have to make frequent use of the gadget's Width specifier and TagWidth specifier and considerable trial and error to achieve a desired layout.

The default layout mode for setup form is FixChars, because this will be the least disruptive for existing users, but this can be overridden by the VarChars keyword, or by executing the FMSYS object method !!FMSYS.SetDefaultFormLayout('VarChars'), that allows users to change the default layout mode for Setup form. This can be used to help test any existing appware which is using setup form !!formname . . ., in either mode to determine which forms need layout adjustment. you can return to the original default using !!FMSYS.SetDefaultFormLayout('FixChars').

Note:
This will have no effect on forms defined using Layout Form.

See the FMSYS Object method.

NOALIGN and AUTOALIGN

You should use AutoPlacement, using Path, Dist and Align commands for laying out forms.

However, you can AutoAlign the so-called linear gadgets: BUTTON, TOGGLE, TEXT, OPTION and single line PARGRAPH, which fit within one vertical grid unit and are then drawn with their Y-coordinate adjusted so that they would approximately centre-align with an adjacent BUTTON. This allows very simple forms to be laid out without you having to know about AutoPlacement concepts, but introduces small errors in all other circumstances and prevents accurate controlled layout because you do not know the offsets applied, so this is not recommended.

The default for 'layout form' is NoAlign, but for 'setup form' it is AutoAlign.

NOALIGN allows you to switch off this pseudo-alignment and AUTOALIGN allows you to switch it on.

NOPADDING

Normally there is some padding space inserted around the edges of the layout area for the form and any frame gadgets. This makes sure that any gadgets added do not directly abut to the frame edge for good aesthetics and readability. The NOPADDING keyword removes this padding space so that the content completely fills the frame.

Note:
It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.
The commands to set modifiable attributes are described after the syntax graph.

                         .---------------<---------------------------.

                        /                                            |

>--LAYOUT FORM fname --+-- MAIN -----+-------------------------------|

                       +-- DOCUMENT -+- FLOAT -----------------------|

                       |             ‘-------------------------------|

                       +-- DIALOG ---+- DOCKing -+-------------------|

                       |                         |- Left ---.        |

                       |             |           |- Right ‑-|        |

                       |             |           |- Top ----|        |

                       |             |           ‘- Bottom ‑‘--------|

                       |             |- RESIzeable ------------------|

                       |             ‘-------------------------------|

                       +-- BLOCKingdialog -+- RESIzeable ------------|

                       |                   ‘-------------------------|

                       +-- VARCHARS ---------------------------------|

                       +-- AT <xypos> -------------------------------|

                       +-- SIZE val val -----------------------------|

                       +-- NOQUIT -----------------------------------|

                       +-- NOALIGN ----------------------------------|

                       +-- AUTOALIGN --------------------------------|

                       +-- NOPADDING --------------------------------|

                       +-- CORE -------------------------------------*

                       | .---<------.

                       |/           |

                       +-- <form> --*   form contents

                       ‘—EXIT -->

TITLE

Defines the form title.

CANCELCALL

This command defines the callback string which is executed whenever the form is dismissed from the screen via the CANCEL button or the QUIT/CLOSE control on the window title bar.

Note:
This command overrides the callback string on the CANCEL button.

CURSORTYPE

When a screen cursor enters a view, the view gadget determines what cursor type should be displayed initially, and what type will be displayed during different types of graphical interaction. You can specify the initial setting for the cursor type using this command.

Note:
You cannot specify an initial cursor type for VOLUME views.

>-- CURSortype  --+-- POINTER ----.

                  +-- NOCURSOR ---|

                  +-- PICK -------|

                  +-- PICKPLUS ---|

                  ‘-- CROSSHAIR ‑-‘-->

Note:
There are other cursor types that are for AVEVA’s use only.

ICONTITLE

Defines the title for the icon when the form is minimized.

>-- ICONTItle text -->

INITCALL

Defines the callback string that is executed each time the form is displayed. This callback is usually run to check the validity of showing the form and to initialize gadget values.

>-- INITcall text -->

OKCALL

Defines the OK callback string for a form. It is executed whenever the form is dismissed from the screen via its OK button or that of an ancestor.

>-- OKcall text -->

Note:
This command overrides the callback string on the OK button.

AUTO-PLACEMENT Commands

Auto-placement is the recommended way of laying out forms.

Auto-placement uses the PATH, DISTANCE and ALIGNMENT commands, which have the following meanings:

PATH: The direction in which a gadget is placed relative to the previous one.

Values RIGHT, DOWN (occasionally LEFT, UP).

Default is: PATH right.

>-- PATH --+-- Up ------.

           +-- Down ----|

           +-- Left ----|

           ‘-- Right ---‘-->

VALIGN, HALIGN: How a gadget aligns to the previous one. Values are:

For PATH right, left: VALIGN top, VALIGN center, VALIGN bottom.

For PATH up, down: HALIGN left, HALIGN center, HALIGN right.

>-- VAlign --+-- Top -----.

+-- Centre --|

‘-- Bottom --‘-->

>-- HAlign --+-- Left ----.

             +-- Centre --|

             ‘-- Right ‑--‘-->

HDIST, VDIST: The grid distance between adjacent gadget boxes for horizontal and vertical paths. Default values: HDIST 0.5, VDIST 0.2.

>-- HDistance value -->

>-- VDistance value -->

The position of a new gadget relative to the previously placed one depends on the combination of the current path, distance increment and alignment.

For horizontal paths RIGHT and LEFT: HDIST and VALIGN apply.

For vertical paths DOWN and UP: VDIST and HALIGN apply.

FirstShown and Killing Events

The following actions determine the life of a form:

Notes:

1. Load, Activate and Kill only happen once in the life of a form.

2. Show and Hide may happen repeatedly.

3. The form's Constructor is run once only.

4. The FirstShown event only happens once.

5. INIT is raised for every Show.

The PML User can define callbacks to service any or all of the above events. These will typically be open callbacks supported by form methods. They can be assigned within the form's Constructor method (recommended), or within the form's Layout Form . . . Exit block.

FIRSTSHOWN callback

Typically assigned in the Constructor by !this.FirstShownCall = '!this.<form_method>'.

The purpose is to allow you to carry out any form actions which can only be completed when the form is actually displayed. There are a variety of circumstances where this arises and it is often difficult to find a reliable solution. A couple of examples are given below.

Commands which manipulate form, menu or gadget visual properties, executed from a PML macro, function or callback may not happen until control is returned to the window manager's event loop. For example, in the application's start-up macro the command sequence 'show !!myForm … hide !!myform' will result in the form not being displayed, but also not becoming known at all to the window manager. Attempts to communicate with this form via the External callback mechanism (possibly from another process) will not work. This can be rectified by doing the '!this.hide()' within the FIRSTSHOWN callback, because the form will be guaranteed to be actually displayed (and hence known to the window manager), before it is hidden.

It is sometimes difficult to achieve the correct gadget background color setting the first time the form is displayed. This can be resolved by setting the required color in the FIRSTSHOWN callback.

KILLING callback

Typically assigned in the Constructor by !this.KillingCall = '!this.<form_method>'.

The purpose is to notify the form that it is being destroyed and allow the assigned callback method to destroy any associated resources, for example, Global PML objects which would otherwise not be destroyed. This may be necessary because PML global objects will survive an application module switch, but may not be valid in the new module.

Notes:

6. The callback method MUST NOT carry out any modifications to the Gadgets belonging to the form or to the Form itself (e.g. don't show or hide the form). Attempts to edit the form or its gadgets may cause unwanted side effects or possible system errors.

7. Form callbacks designed for other Form events (e.g. CANCEL, INIT) are rarely suitable as killing callbacks.

8. Restrict form and gadget operations to querying.