Software Customisation Reference Manual
Summary of Objects, Members and Methods : Object Type Details : FORM Object
FORM Object
Members
 
Name
Type
Purpose
FormRevision
STRING Get/Set
Form Revision text.
FormTitle
STRING Get/Set
Form title.
IconTitle
STRING Get/Set
Icon title.
Initcall
STRING Get/Set
Callback executed when form is initialised.
Autocall
STRING Get/Set
Callback executed when any of the specified application attributes have changed.
Okcall
STRING Get/Set
Callback executed when OK button is pressed.
Cancelcall
STRING Get/Set
Callback executed when CANCEL button is pressed.
KeyboardFocus
GADGET Get/Set
Gadget to have initial keyboard focus on display of the form. One of TEXTFIELD, TEXTPANE, BUTTON, TOGGLE or ALPHA VIEW.
AutoScroll
BOOLEAN
Get/Set
If AutoScroll is selected the form will automatically gain horizontal or vertical scrollbars if the forms size becomes too small to display its defined contents. This member does not apply to form types Main Window and Document.
Quitcall
STRING Get/Set
Callback executed whenever you press the Quit/Close icon (X) on the title bar of forms and the main application window.
For forms of type MAIN, the QUITCALL callback is executed, if present. This permits you to terminate the application, and so the associated PML callback should prompt you for confirmation.
For all other form types, the QUITCALL callback is executed, if present, and then the form and its children are hidden unless the PML callback returns an error. When the form nest is hidden the CANCELCALL callback for each form of the nest is executed (in reverse display order).
Maximised
BOOLEAN Get/Set
Get/set form’s maximised status (on screen).
Active
BOOLEAN Get Only
Gives form's active/inactive status.
Popup
MENU
Get/Set
Get/set form’s current popup menu.
HelpContextID
STRING
Read/Write STRING
Property:!!myform.HelpContextID = STRING - sets the context Id within the help file for this form.
STRING=!!myform.HelpContextID - gets the current context Id for this form.
Killingcall
STRING
Get/Set
Notify the form that it is being destroyed and allow the assigned callback method to destroy any associated resources, e.g. global PML objects which would otherwise not be destroyed (see Killing callback).
FirstShowncall
STRING
Get/Set
Allow you to carry out any form actions which can only be completed when the form is actually displayed for the first time (see FirstShown callback).
Opacity
REAL
Get/Set
Purpose Set the percentage opaqueness of the form as an integer in the range 10% (nearly transparent) to 100% (opaque - default). This is only valid for non-docking Dialog and BlockingDialog form types.
Methods
 
Name
Result
Purpose
Name()
STRING
Get name.
FullName()
STRING
Get the full form name (Including !!).
NewMenu(STRING menuname)
MENU
Adds a new named menu to the form.
NewMenu(STRING menuname, STRING type)
MENU
Adds a new named and typed menu to the form. The first argument is the name of the new menu; the second argument is the type of the menu, and must be either ‘POPUP’ or ‘MAIN’.
SetActive(BOOLEAN)
NO RESULT
SetActive(FALSE) greys-out all gadgets on the form, but doesn’t set their Active status, so that SetActive(TRUE) restores the form to the precise state it was in before greying out, i.e. any inactive gadgets will still be inactive.
SetGadgetsActive(BOOLEAN)
NO RESULT
SetGadgetsActive(FALSE) greys out all gadgets on the form and sets their Active status to ‘inactive’, i.e. their previous active state is lost. Similarly SetGadgetsActive(TRUE) greys-in all gadgets and sets their Active status to ‘active’.
SetPopup(MENU)
NO RESULT
Specifies the pop-up to be displayed when the right-hand mouse button is released over the form background.
RemovePopup(MENU)
NO RESULT
Removes a pop-up
associated with a form.
GetPickedPopup()
MENU
Returns the last picked popup menu for the form.
Show('FREE')
NO RESULT
Show the form on the screen as a FREE form.
Show('AT', REAL X, REAL Y)
NO RESULT
Show the form as a FREE form with the origin at the X,Y relative screen position.
Show('CEN', REAL X, REAL Y)
NO RESULT
Show the form as a FREE form with its centre at the X,Y relative screen position.
Shown()
BOOLEAN
Get 'shown' status
Hide()
NO RESULT
Hides the form (removes it from the screen)
Owner()
FORM
Returns the form's parent form, or unset variable if the form is free-standing
SetOpacity( REAL PERCENT )
NONE
Set the percentage opaqueness of the form as an integer in the range 10 (nearly transparent) to 100 (opaque - default). This is only valid for non-docking Dialog and BlockingDialog form types.
Subtype( )
STRING
Gets the form's subtype, one of 'DIALOG',
'BLOCKINGDIALOG', 'MAIN', 'DOCUMENT'
SetUndoable( )
STRING, ANY
 
Undoable( )
STRING
 
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 -->
 
Default:
Dialog, non-resizeable; size adjusted automatically to fit contents.
TITLE
Defines the form title.
>-- TITLe text -->
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.
>-- CANCELcall text -->
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 minimised.
>-- 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 initialise 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 centre, VALIGN bottom
For PATH up, down: HALIGN left, HALIGN centre, 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:
Define
the form, its gadgets, methods and layout are specified (usually in a '.pmlfrm' file)
Load
the form definition is read by PML and the form's constructor method is run
Show
the form's INITialisation event is raised, and the display process is begun
Activate
the form and its contents is created by the window management system and is activated (actually displayed) and the FIRSTSHOWN event is raised
Hide
the form is hidden and its OK or CANCEL event is raised
Kill
the form's KILLING event is raised and then the form is destroyed. It is no longer known to PML
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 colour setting the first time the form is displayed. This can be resolved by setting the required colour 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, e.g. 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:
1.
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.
2.
Form callbacks designed for other Form events (e.g. CANCEL, INIT) are rarely suitable as killing callbacks.
3.
Restrict form and gadget operations to querying.
1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved.
AVEVA Logo