PML Forms and

Menus
The AVEVA Programmable Macro Language

Author: Romel E. Daguplo

Email: romeldhagz@gmail.com
Form Concepts Overview
 A type of object represented by a global variable
 Owns a set of predefined member variables and built-in
methods
 It can also have user-defined members
 Form variables, form gadgets
 It can also have user-defined methods
 Form members are always accessed using the dot
notation
Example:
!!MyForm.Textfield
Form name Form member
Form Concepts Overview
 Gadgets own a set of predefined member variables and
built-in methods and can be accessed using the dot
notation
Example:
!!MyForm.Textfield.Val
Gadget as a member Member variable

 Callbacks are user-defined actions assigned to a form

and its gadgets and that are executed when the
operator interacts with the form

Vantage Plant Design Software Customization Reference Manual contains

a list of all the members and methods of forms and gadget types
Naming Forms and
their Members
 Format:
!!MyForm $* name of the form
!!MyForm.GadgetName $* name of a gadget on a form
!!MyForm.GadgetName.Val $* data value held by that
gadget
 Within the form definition, the members should be referred to by
using !This to replace the form name part of the gadget name.

from the above example:

!This.GadgetName $* just equal to !!Myform.GadgetName
!This.GadgetName.Val $* just equal to !!Myform.GadgetName.Val

PML 1 (obsolete method but still supported):

_GadgetName $* just equal to !!Myform.GadgetName
Forms
 Syntax:
setup form !!formname
…………
exit

Example:
setup form !!hello
paragraph .Message text ‘Hello world’
button .Bye ‘Goodbye’ OK
exit

 paragraph command adds a paragraph gadget

 Message is the name of the gadget and the dot(.) indicates that the gadget is a
member of the form
 button command adds a button gadget named .Bye. The text on the button will
be ‘Goodbye’
 The keyword OK is a form control attribute that specifies that the action of this button is to
remove the form from the screen
Form Attributes
 Form Types:
 MAIN
 DOCUMENT
 DIALOG
 BLOCKINGDIALOG
Examples:
setup form !!MyForm dialog dock left - creates a resizable docking dialog
setup form !!MyForm dialog resizeable - creates a resizable floating dialog
setup form !!MyForm dialog - creates a non-resizable floating dialog
setup form !!MyForm - creates a non-resizable floating dialog
setup form !!MyForm document - creates a resizable MDI child document
setup form !!MyForm block - creates a non-resizable blocking dialog
setup form !!MyForm block resizeable - creates a resizable blocking dialog
Form Attributes
 Minimum Size and Resizability
A form will automatically stretch to fit the gadgets you
add to it
 You can use the SIZE keyword to give minimum size in
multiples of the character width and line height
setup form !!MyForm size 25.5 10

 The RESIZEABLE command means that the form will be

displayed with re-sizing controls at its corners
setup form !!MyForm resizeable
setup form !!MyForm size 25.5 10 resizeable
Form Title and Icon Title
 The TITLE sub-command is used to supply a string that is displayed in
its banner at the top of the form’s window
 The ICONTITLE sub-command is used to supply a string that is used
when a form is iconized
setup form !!MyForm
…………
TITLE ‘My Form Title’
ICONTITLE ‘Short Title’
…………
exit
Or
setup form !!MyForm
…………
!This.FormTitle = ‘My Form Title’
!This.IconTitle = ‘Short Title’
…………
exit
Form Callbacks (Initcall)
 The form’s initialization callback allows the form’s gadgets to be
initialized to reflect the current state of the application
 You can set the callback by assigning to the form’s initcall member:
setup form !!MyForm
…………
INITCALL ‘!this.init()’
…………
exit

Or
setup form !!MyForm
…………
!!Myform.InitCall = ‘!this.init()’
…………
exit
Form Callbacks (OK)
 The OKCALL callback allows the operator to
approve the current gadget settings
 You can assign to the form’s OKCALL member by:
setup form !!MyForm
…………
OKCALL ‘!this.approveData1()’
…………
exit
 You can modify the OK callback at any time using,

!this.OKCall = ‘!this.approveData2()’
Form Callbacks (Cancel)
 The CANCELCALL callback allows the operator
not to proceed with the function of the form
 You can assign to the form’s CANCELCALL
member by:
setup form !!MyForm
…………
CANCELCALL ‘!this.cancelForm1()’
…………
exit
 You can modify the Cancel callback at any time using,
!this.CancelCall = ‘!this.cancelForm2()’
Form Callbacks (Quitcall)
 The QUITCALL callback is executed whenever the user
presses the QUIT/CLOSE icon (X) on the title bar of forms
 You can assign to the form’s QUITCALL member by:
setup form !!MyForm
…………
QUITCALL ‘!this.quitForm1()’
…………
exit
 You can modify the Quit callback at any time using,
!this.QuitCall = ‘!this.quitForm2()’
Form Control Attributes
 A button may optionally have a form control
attribute which takes effect after the callback
command is invoked
 Control Attributes:
 OK
 APPLY
 CANCEL
 RESET
 HELP
Form Control Attributes
 Examples:
button .Ok ‘OK’ callback ‘!!MyOKFunction’ OK
button .Apply ‘Apply’ callback $
‘!!MyApplyFunction’ APPLY
button .Cancel ‘Cancel’ callback $
‘!!MyCancelFunction’ CANCEL
button .Reset ‘Reset’ RESET
button .Help ‘Help’ HELP

 You can only have one of each type of control

attribute on any form except for APPLY which may
be used on several buttons
A Simple Form
 Example (simpleForm.pmlfrm):

setup form !!simpleForm

title 'My Form'
icontitle 'Myform'
paragraph .message text 'Hello world!'
button .bye 'Goodbye' ok
exit
The Form Definition File
 Should be held one per file
 The file should be stored in a directory pointed to by the PMLLIB
environment variable
 Filename must have suffix .pmlfrm
 !!MYFORM or !!MyForm or !!myform all corresponds to myform.pmlfrm
 Begins with setup form and ends with exit
 Any method definitions should follow the exit command
 Each method begins with define method and ends with endmethod
 In particular, it will contain the form’s default constructor method
 This method has the same name with the form and no arguments
 The only method called automatically when the form is loaded
 Used to set default values for the gadgets of the form
 The form may be given an initialisation method
 Which is run whenever the form is shown
 No executable statements should appear in the file outside the form
definition or form methods
 But comments can be put anywhere in the file
Loading and Displaying
Forms
 PML will automatically load an object or form from file
when first used
 To display a form (can either be free-standing or as a member of
a form family):
show !!formname $* default is a child form
show !!formname free

 Removing or hiding from the screen:

hide !!formname

 Redefining a form once loaded:

pml reload form !!formname

 Loading a form:
loadform !!formname
Loading and Displaying
Forms
Note: If you show the form again, it will appear on
the screen but its definition is already known so it
will not be loaded again

 Removing a form definition:

kill !!formname
Some Built-in Methods
for Forms
 A variety of useful method calls have been
provided:
 To show a form:
!!MyForm.Show()
!!MyForm.Show(‘FREE’)
!!MyForm.Show(‘At’,0.3,0.5) $* automatically FREE

 To hide a form:
!!MyForm.Hide()

 To query whether a form is currently shown:

if (!!MyForm.Shown()) then
………
endif
Form Member Variables
 Used to store additional information on a form which will
not be displayed to the user
 These are variables which can be any of the PML data types,
including ARRAYS and OBJECTS
setup form !!MyForm
…………
member .MyNumber is REAL
member .MyString is STRING
member .MyArray is ARRAY
…………
exit

 The value of a form member can be set and used in just the
same way as an object member
!this.MyNumber = 42
!this.MyString = ‘Gadz’
!Num = !this.MyNumber
Form Gadgets
 There are many kinds of form gadgets
 Two common aims in defining gadgets on the
form
 Define the area to be taken up on the form
 Define the action to be taken if the gadget is
selected
 Each gadget size and position determines the
area taken up
 The action is defined by the gadget’s CALLBACK
Callbacks
 Any selectable gadget has a callback which
is defined at the time the gadget is created
 The callback can do one of the three things:
 Show a form
 Execute a command directly
 Run a function or method
Callbacks
Example:
setup form !!MyForm
paragraph .Message text ‘Hello world’
button .Change ‘Change Message’ callback $
|!this.Message.Val = ‘Modified’|
button .Bye ‘Goodbye’ OK
exit

 a gadget callback is defined by the callback command followed by a

command or PML functions enclosed in text delimiters
 for defining complicated callback, it is recommended to use a form
method
Callback Example
 For a callback to call a function
setup form !!MyForm
…………
button .Query ‘Query’ callback ‘!!queryCatalogueDetails()’
…………
exit

 For a callback to call a method

setup form !!MyForm

…………
button .Query ‘Query’ callback ‘!this.queryDetails()’
…………
exit
Callback Example
 Showing another form from a form gadget
setup form !!MyForm
…………
button .Gadz ‘Show Gadz Form’ callback ‘show !!gdzMainForm’
…………
exit
or
setup form !!MyForm
…………
button .Gadz ‘Show Gadz Form’ form !!gdzMainForm
…………
exit
Callbacks: Form Methods
 Most callbacks require more than a single command, so invoking a method
or function or macro is an essential requirement
 Example:
setup form !!MyForm
title ‘Display Your Message’
paragraph .Message width 15 height 1
text .Capture ‘Enter message: ’ width 15 is STRING
button .Bye ‘Goodbye’ OK
exit
define method .MyForm()
$* default constructor – set gadget default values
!this.Message.Val = ‘Hello world!’
!this.Capture.Callback = ‘!this.Message.Val = !this.Capture.Val’
!this.OKcall = ‘!this.Success()’
endmethod
define method .Success()
!this.Message.Val = ‘Hello again!’
!this.Capture.Val = ‘’
endmethod
Callbacks: Form Methods
 The great advantage of methods is that you can pass
variables as arguments to the method and it can also
return a result just like a PML function
 Example:

define method .Success(!output is GADGET, !input is GADGET)

!output.Val = ‘Hello again!’
!input.SetFocus()
endmethod

define method .setGadget(!output is GADGET) is BOOLEAN

!output.Val = ‘Gadget initialized!’
handle any
return FALSE
endhandle
return TRUE
endmethod
PML Open Callbacks
 When the operator interacts with a GUI, an event occurs
 Example:
 Types something into a field on a form
 Moves the cursor into a window
 Presses down a mouse button
 Etc.
 Application software defines a set of meta-events for
forms and gadgets
 When a meta-event occurs, the application software
checks for user-defined callbacks and execute them
PML Open Callbacks
 Simple assigned callback is insufficient to fully exploit the
gadget’s possible behaviors
 To overcome this shortcoming, we can use OPEN CALLBACKS to
allow the AppWare to be informed whenever a meta event is
encountered
 Open Callback:
define method .Control(!object is GADGET, !action is STRING)

 !object is a Forms and Menus object (i.e. a form, gadget, or

menu)
 !action is the meta-event that occurred on the object and
represents the action to be carried out by the method
PML Open Callbacks
 The open callback is a string of the form:

‘!this.MethodName(‘

 Note the open bracket ‘(‘ (no arguments and

no closing bracket).
 The callback is to an open method or function
PML Open Callbacks Example
 An open callback to a multi-choice list gadget:
setup form !!Open
title ‘Test Open Callbacks’
list .Choose callback ‘!this.Control(’ multi width 15 height 8
exit
define method .Open()
do !i from 1 to 10
!fields[!i] = ‘list field $!i’
enddo
!this.Choose.Dtext = !fields
endmethod
define method .Control(!object is GADGET, !action is STRING)
if (!action eq ‘SELECT’) then
-- find out all about our gadget object
!form = !object.Owner()
!type = !object.Type()
!name = !object.Name()
!field = !object.PickedField
!fieldtext = !object.Dtext[!field]
$P Selected $!form$n.$!name $!type Field $!field Dtext{$!fieldtext}
elseif (!action eq ‘UNSELECT’) then
!field = !object.PickedField
$P Unselect field $!field
endif
endmethod
PML Open Callbacks
 It is also be essential if we use PML functions as
open callbacks
define function !!Control(!object is GADGET, !action is
STRING)
……………
endfunction

 List of objects that can have open callbacks is

found Vantage Plant Design Software Customisation Guide
Section 14.3.4
Gadgets and their Attributes
 Types of Gadgets:
 FRAME
 PARAGRAPH
 BUTTON
 TOGGLE
 RGROUP
 OPTION
 LIST
 DATABASE SELECTOR
 TEXT
 TEXTPANE
 VIEW
 SLIDER
 RTOGGLE
Gadget Definition Commands
 Can only be defined within the form definition sequence
setup form
…………
exit
 Format:
type name {common prop.} {specific prop.}
Example:
list .List1 at X…… Y…… width 10 lines 3

 Common properties:

}
 position - All gadgets have this
 tag
 tooltip
 callback
Most but not all gadgets
 anchor
have these
 docking

 Specific properties: The order of commands generally matters

 See syntax graph in VANTAGE Plant Design Software Customisation
Reference Manual
Gadget Size Management
 User Specifiable Tagwidth for TEXT, TOGGLE, OPTION
and RGROUP Gadgets
 TEXT, TOGGLE, OPTION and RGROUP gadgets support the
Tagwidth syntax
 Tagwidth specifies the size of the gadget’s tag field in grid
width units

option .ELLIST tagwid 7 |Element Id| width 4

 The actual tag may have more characters than the

declared Tagwidth and still fit in the tag field
Gadget Size Management
 Specifying Gadget Size Relative to Other Gadgets

 Example:

frame .fr1 ‘Frame 1’ at x0 y0 width 10 height 10

……………
exit
frame .fr2 ‘Frame 2’ at xmin ymin width.fr1 height 15
……………
exit
Gadget that Support Pixmaps
 Some gadgets support pixmaps as content as an alternative to text
e.g. Buttons, Toggles, and Paragraphs
 Pixmaps are pixelated pictures held in files of type .png
 Default size for pixmaps is assumed to be 32x32 pixels
 When pixmaps are required, you will need to specify
 pathnames to the pixmap file
 Maximum required size of the image

button .But1 pixmap /C:\pic.png width 26 height 26

 Using AddPixmap() Method:

button .But1 pixmap width 26 height 26

 In the constructor method:

!this.but1.AddPixmap(‘C:\pic.png’)
Gadget Members
 Members Contained by All Gadgets
 Visible
 Active
 Callback
 Tag

 Making gadgets visible and invisible

!!MyForm.List1.Visible = FALSE $* Invisible
!!MyForm.List1.Visible = TRUE $* Visible

 Activating and de-activating gadgets

!!MyForm.List1.Active = FALSE $* De-activate
!!MyForm.List1.Active = TRUE $* Activate
Gadget Members
 Setting Keyboard Focus
 The keyboard focus defines which gadget will receive keystrokes

!!MyForm.KeyboardFocus = !!MyForm.Gadget

 This can be moved at any time to another gadget using the

SetFocus() method

!!MyForm.Textfield.SetFocus()
Frame Gadgets
 Frame gadgets provide visual grouping of gadgets on a
form
 Frame Definition:
frame .MyFrame at x0 y3 ‘My Frame’
…………………
exit
 Frame Size:
 Automatically expands downwards and to the right when gadget is
added but you can specify default size

frame .MyFrame at x0 y3 ‘My Frame’ width 25 height 5

…………………
exit
Tabset Frames
 A frame with tab pages
 Tabset Frame Definition:

frame .MyFrame tabset width 25 height 5

frame .Tab1 ‘Tab 1’
……………
exit
frame .Tab2 ‘Tab 2’
……………
exit
exit
Paragraph Gadgets
 Paragraph gadgets are simple named gadgets which
allow piece of text or a pixmap to be displayed on the
form
 Textual Paragraph Gadgets:
paragraph .Message text ‘Text String’
paragraph .Message at …… text ‘Text String’ width 16 lines 7
paragraph .Message at …… background 2 width 20 lines 2

 Pixmap Paragraph Gadgets:

paragraph .Picture at …… pixmap /C:\pic.png
paragraph .Picture at …… pixmap /C:\pic.png width 30 height 30

 Pixmap may be changed any time by assigning a new value to the

.Val member:
!!MyForm.Picture.Val = /C:\newpic.png
Button Gadgets

 Also called control button , usually displays a child form or invoke a

callback (typically a PML Form method)
 Tag, pixmap, callback, and child form are all optional
button .SubForm ‘More…’ form !!ChildForm
button .SubForm pixmap /C:\pic.png form !!ChildForm
button .Calculate ‘Calculate’ callback ‘!this.Calculate()’
button .But1 ‘More…’ at …… width 10 height 1

 Toggle Mode Buttons:

button .But1 toggle pixmap /C:\unselectpic.png
/C:\selectpic.png /C:\inactivepic.png width 16 height 16
tooltip ‘This is a toggle button’
Toggle Gadgets
 Are used for independent on/off settings
opposed to a radio group
 Example:
toggle .Bold ‘Bold’
toggle .Italic ‘Italic’
toggle .Underline ‘Underline’

 Using Pixmap:
toggle .GridOn pixmap /C:\gridon.png callback
‘!this.enableGrid()’
RGroup Gadgets
 Used to allow selection of one of a small fixed number of choices
 Example:
rgroup .MyRGroup ‘Choices:’ horizontal callback ‘!this.Select()’
add tag ‘Red’ select ‘RED’
add tag ‘Blue’ select ‘BLUE’
add tag ‘Green’ select ‘GREEN’ callback ‘!this.RadAction()’
exit

 The SELECT keyword in the add command defines its replacement

text string (RTEXT)
 When querying current selection using Selection() method, it will
return the RTEXT string of the selected button
if (!!MyForm.MyRGroup.Selection() eq ‘RED’) then
………
endif
RToggle Gadgets
 Very similar to TOGGLE gadget, but is allowed only in
FRAMES, where they operate together to form a set of
radio buttons similar to RGROUP gadget

 Example:
frame .MyFrame ‘Frame’ at xmin ymin
rtoggle .Rad1 ‘Radio Button 1’ callback ‘!this.Control(’
rtoggle .Rad2 ‘Radio Button 2’ callback ‘!this.Control(’
rtoggle .Rad3 ‘Radio Button 3’ callback ‘!this.Control(’
exit
Option Gadgets
 Offers a single choice from a list of items
 The items on the list can be either pixmaps or
text strings but not a mixture
 Contains two parallel lists of the same length in
ARRAY format
values (DTEXT)
 Display
 Replacement values (RTEXT)
Textual Option Gadgets
 Width of a textual option gadget must be
specified
Example:
option .Colour ‘Colours’ at …… callback ‘!!MyFunc()’ width 10
!ColourDtext[1] = ‘Color Black’
!ColourDtext[2] = ‘Color White’
!ColourDtext[3] = ‘Color Red’
!ColourRtext[1] = ‘Black’
!ColourRtext[2] = ‘White’
!ColourRtext[3] = ‘Red’
!this.Colour.Dtext = !ColourDtext
!this.Colour.Rtext = !ColourRtext
Pixmap Option Gadgets
 Gadget shape must be specified using WIDTH
keyword and either HEIGHT or ASPECT
 DTEXT member will be the pixmap’s filename
Example:
option .Circle ‘Circles’ at …… callback ‘!!MyFunc()’ pixmap
width 256 height 128
!CircleDtext[1] = ‘C:\circle1.png’
!CircleDtext[2] = ‘C:\circle2.png’
!CircleRtext[1] = ‘Circle 1’
!CircleRtext[2] = ‘Circle 2’
!this.Circle.Dtext = !CircleDtext
!this.Circle.Rtext = !CircleRtext
Option Gadgets
 Setting and Getting the Current Selection
 Setting selection using Select() Method:
!!MyForm.Colour.Select(‘Dtext’,’Color Black’)
!!MyForm.Colour.Select(‘Rtext’,’Black’)
!!MyForm.Circle.Select(‘Dtext’,’C:\circle1.png’)

 Reading the selection using Selection() Method:

!Selected = !this.Colour.Selection()
!Selected = !this.Colour.Selection(‘Dtext’)
!Selected = !this.Colour.Selection(‘Rtext’)
Slider Gadgets
 Allows you to interactively to
generate values in a specified
range, at specified steps
 Supports vertical and horizontal
frame .fr1 ‘Slider’ at xmin ymax width 10
text .txt width 3 is REAL
slider .sld horizontal callback ‘!this.ControlSlide(’
range -50 +50 step 5 val 0 width 5
exit

 Responds to left-mouse SLIDER START, MOVE, and STOP

events
List Gadgets
 Allows the user to make
single or multiple selections
from many alternatives
 Appropriate for long list choices
 Single Choice List Gadgets
list .Components ‘List’ single zeroselection width 25 lines 15
!ComponentDtext[1] = ‘ELBO1’
!ComponentDtext[2] = ‘FLAN1’
!ComponentRtext[1] = ‘=1565/1543’
!ComponentRtext[2] = ‘=1565/1544’
!this.Components.Dtext = !ComponentDtext
!this.Components.Rtext = !ComponentRtext

 ZEROSELECTION means no default field selection

 only applicable to single choice list gadget
List Gadgets
 Multiple Choice List Gadgets
list .Components ‘List’ multiple width 25 lines 15
!ComponentDtext[1] = ‘ELBO1’
!ComponentDtext[2] = ‘FLAN1’
!ComponentRtext[1] = ‘=1565/1543’
!ComponentRtext[2] = ‘=1565/1544’
!this.Components.Dtext = !ComponentDtext
!this.Components.Rtext = !ComponentRtext

 Querying selected values

 Single choice list gadget returns a STRING
 Multiple choice list gadget returns an ARRAY of STRINGS
Form Exercise 1
 Create the following form.
Upon the form is initialized;
Default value in textbox: 0
Default frame tag: ‘Sequence Frame’

Upon choosing ‘Fibonacci’

button;
Frame tag: ‘Fibonacci Sequence’
The sequence is shown inside the
frame.

Upon choosing ‘Hailstone’

button;
Frame tag: ‘Hailstone Sequence’
The sequence is shown inside the
frame.
Form Exercise 1
Use the functions you created in the previous exercises 3 & 4
found in Part 1.

Handle invalid input (0 and string). Input should be a REAL

object.

Define a constructor method.

Multi-Column List Gadgets
 A list gadget with a COLUMNS keyword
 Column Oriented - SETCOLUMNS()
list .Components columns single zeroselection width 25 lines 15
!head[1] = ‘Name’
!head[2] = ‘Type’

!col[1][1] = ‘Flange_B1’
!col[1][2] = ‘Elbow_B2’
!col[2][1] = ‘Type is Flange’
!col[2][2] = ‘Type is Elbow’

!rtext[1] = ‘=156/256’
!rtext[2] = ‘=157/257’

!this.Components.SetHeadings(!head)
!this.Components.SetColumns(!col)
!this.Components.Rtext = !rtext

 Can be apply to Multiple Choice List gadget also

Multi-Column List Gadgets
 Row Oriented - SETROWS()
list .Components columns single zeroselection width 25 lines 15
!head[1] = ‘Name’
!head[2] = ‘Type’
!row[1][1] = ‘Flange_B1’
!row[1][2] = ‘Type is Flange’
!row[2][1] = ‘Elbow_B2’
!row[2][2] = ‘Type is Elbow’
!rtext[1] = ‘=156/256’
!rtext[2] = ‘=157/257’
!this.Components.SetHeadings(!head)
!this.Components.SetRows(!row)
!this.Components.Rtext = !rtext

 DTEXT string is held as a ‘horizontal tab’ character separated

string of column data
Database Selector Gadgets
 A special kind of list gadget
 Provides a mechanism for
displaying the current database
element along with its owner
and members
 User can interact with a selector
to change the current element
selector .Sel ‘Selector:’ single width 12 height 5 DATABASE
selector .Sel multiple width 12 height 5 DATABASE OWNERS
selector .Sel multiple width 12 height 5 DATABASE MEMBERS
selector .Sel single width 12 height 5 DATABASE AUTO
selector .Sel callback ‘!this.Mylist(‘ single width 12
height 5 DATABASE
Database Selector Gadgets
 DATABASE keyword is mandatory
 OWNERS and MEMBERS are optional
 AUTO and MULTIPLE cannot be used together
 To get and set values for a selector:
 Selection() – get value
 Select() – set value

!element = !this.Sel.Selection()

 RTEXTand DTEXT are always the same as one

another
 AUTO means the selector gadget is updated when
you do action to the design explorer form
Text Gadgets
 A box that can display a
value and into which the
user may type a value,
or edit an existing value
text .Number at ……… width 10 is REAL
text .Str ‘Username:’ callback ‘!!MyFunction’ width 10
scroll 100 is STRING
text .Bore ‘Bore:’ width 10 is BORE format !!FormatBore
text .Passwd ‘Password:’ at …… width 10 NOECHO is STRING

 Specifydata type using IS

 Supply a FORMAT object
 Password type using NOECHO keyword
Text Gadgets
 Validating Input to Text Fields
 Has an optional validation callback member which
the user can specify
!textField.ValidateCall = <callback string>

Example:
!!MyForm.Txt1.ValidateCall = ‘!this.Validate()’

 VALIDATECALL is used to apply any checks

 if an error is encountered then the callback raises the error
and returns
Textpane Gadgets
 Provides a box on a form into which a user may type
and edit multiple lines of text
textpane .Txt ‘Text:’ at …… width 10 height 20
textpane .Txt ‘Text:’ at …… height 20 aspect 0.5

 Its contents is an array of strings

 Each element of the array corresponds to a line of text in the
gadget

 Setting contents:
!Lines[1] = ‘Hello World’
!Lines[2] = ‘’
!Lines[3] = ‘’
!Lines[4] = ‘Goodbye World’
!this.Txt.Val = !Lines
Fast Access to Lists, Selectors and
Textpanes using Do Loops
 To a LIST gadget:
do !field list !!FormA.ListA
…………
enddo

 To a SELECTOR gadget:
do !field selector !!FormA.SelectorA
…………
enddo

 To a TEXTPANE gadget:
do !line pane !!FormA.TextpaneA
…………
enddo
View Gadgets
 Used to display and interact with alphanumeric or graphical views
 Types of View Gadgets:
 ALPHA
 PLOT
 2D Graphical Views
 3D Graphical Views
 Example (using multiple lines):
view .MyView at …… PLOT
height 10 width 20
cursortype pick
border on
setcolour 15
exit
 Example (using one line):
view .MyView at …… PLOT height 10 width 20 bord on setc 15 exit
View Gadgets
 Defining ALPHA Views
 Views for displaying text output and/or allowing command input
view .Input at …… ALPHA
height 10 width 20
channel COMMANDS
exit
view .InputOutput at …… ALPHA
height 10 width 20
channel REQUESTS
channel COMMANDS
exit

 channel COMMANDS – causes alpha view to have a command input

field and displays command lines and error messages in the messages
in the scrollable output region
 channel REQUESTS – displays the output resulting from commands, in
particular, queries in the scrollable output region
View Gadgets
 Defining PLOT Views
 Views for displaying non-interactive
2D plotfiles

setup !!MyForm ……
……
view .Diagram at …… PLOT height 10 width 20 …… exit
!this.Diagram.Borders = false
!this.Diagram.Add(‘C:\plot1.plt’)
……
exit

 To define the content of the plot view, specify the PLOTFILE path with
the Add() method
View Gadgets
 Defining DRAFT’s Area (2D) Views
 Contents of the view may be any valid 2D graphical element, such as
DRAFT SHEET, VIEW, LIBRARY, etc.
 To define the content of the view, use the PUT command
 put CE - draws the current element
 put /SITE/SHEET - draws the named Sheet element

Example:

view .Drawing at …… AREA

height 10 width 20
put /MDS-ABA-3-VIEWS(METRIC)-PS00001-AREA
limits 200 100 to 600 500
exit
!this.Drawing.Background = ‘beige’

 For DRAFT Module only

View Gadgets
 Defining DESIGN’s Comparator (2D) Views
 Contents of the view may be any valid Process and Instrument
Diagram sheet reference

Example:

view .Pid at …… COMPARE

height 20 width 40
put /SHEET
cursortype pointer
exit
!this.Pid.Background = ‘darkslate’
View Gadgets
 Defining DESIGN’s Volume (3D) Views
Example:
setup form !!MyForm
……
view .Model at …… VOLUME
height 10 width 30
limits auto
iso 3
exit
……
exit
define method .MyForm()
……
!this.Model.Borders = false
!this.Model.Shaded = true
……
endmethod

 Full list of members and methods is found in VANTAGE Plant Design Software
Customisation Reference Manual
Form Layout
 Typically, gadgets are laid out onto the form
from top left to right and from top to bottom

 Two types of form Layout:

 Static
Form Layout
 Complex Form Layout
Gadget Positioning
 Form Coordinate System
 Gadgets are positioned on a form from top
left
0 1 2 3 4 5 6 7 8 9 X
0 1 character width per unit
1
2
3
4
5 1 line height per unit
6
7
8
9

Y
Gadget Auto-Placement
 The PATH command can be used to define the logical
position of subsequent gadgets
 PATH DOWN means that the next gadget will be below
the current one, PATH RIGHT means that the next gadget
will be to the right of the current one
 The spacing between gadgets is controlled by VDIST
and HDIST for vertical and horizontal spacing
 If desperation calls!!! There are settings of HALIGN and
VALIGN which can set the alignment LEFT, RIGHT, TOP,
CENTRE, and BOTTOM
Gadget Auto-Placement
 Example:
button .But1 $* default placement
PATH DOWN
.But1
HALIGN CENTRE
VDIST 4.0
.Par5
para .Par2 width 4 height 2 $* auto-placed
toggle .Tog3 $* auto-placed
.Par2
PATH RIGHT
HDIST 6.0
VALIGN BOTTOM

list .Lis4 width 5 height 4 $* auto-placed .Lis4

.Tog3
PATH UP
HALIGN RIGHT

para .Par5 width 6 height 5 $* auto-placed

Relative Gadget Placement
 Each gadget has four label points
 XMIN YMIN

 XMAX gadget
YMAX
 YMIN

XMIN

XMAX
 YMAX

 These can be used for positioning using

the AT keyword
paragraph .message at xmin ymax text ‘Hello world!’
Relative Gadget Placement
 Relative to the last gadget
0 1 2 3 4 5 6 7 8 9 X
0
1 previously created gadget used as
2 reference
3
4
5 YMAX
6
7
8
.Msg YMAX + 2
9

Y new paragraph gadget

XMIN

paragraph .Msg ‘Hello!’ at xmin ymax+2

Relative Gadget Placement
 Relative to the last gadget
0 1 2 3 4 5 6 7 8 9 X
0 existing paragraph gadget
1
2
.Para
3 YMAX.Para
4
5
6 .Frm existing frame gadget
7
8 YMAX.Para+5
9
.Msg

Y
new paragraph gadget

XMIN.Para-5

paragraph .Msg ‘Hello!’ at xmin.Para-5 ymax.Para+5

Mixing Auto and Relative
Placement
 Example:
toggle .t1 at xmin ymin
toggle .t2 at xmax ymax.t1+0.25

PATH DOWN
VDIST 2.0

toggle .t3 at xmin.t1

 places .t3 with respect to XMIN of gadget .t2, whilst Y coordinate

for .t3 is auto-placed at current VDIST value (which is 2.0) below the
last placed gadget (which is .t2)
Absolute Gadget Positioning
 Example:
toggle .OnOff at 4 3.5
toggle .OnOff at x 4 y 3.5

0 1 2 3 4 5 6 7 8 9 X
0
1
2
3
4
5
6
7
8
9

Note: Absolute positioning is not recommended way to define your gadget positions,
use relative positioning
Intelligent Positioning and Resizing
 So far, we have considered the static layout of
the form
 Defining intelligent positioning and resizing
behavior of gadgets is considered as Complex
Form Layout
 These describes gadgets with DOCK and ANCHOR
attributes
Complex Form Layout
 Defines form with intelligent positioning and
resizing behaviour of gadgets using the DOCK
and ANCHOR attributes
 DOCK Attribute:
 Allowsyou to dock a gadget to the left, right, top, or
bottom edge of its container, typically a form or a
frame: or you can cause the gadget to dock to all
edges, or to no edges
 ANCHOR Attribute:
 Allowsyou to control the position of an edge of the
gadget relative to the corresponding edge of its
container
Complex Form Layout
 DOCK Attribute Examples:
 For forms:
setup form !!MyForm dialog dock bottom

 For gadgets:
frame .MyFrame at …… width 50 heigth 10
button .But1 ‘This is a button’ dock fill
path down
frame .Fr1 ‘A Frame’ width 5 height 10 dock right
exit
exit
Complex Form Layout
 ANCHOR Attribute Examples:
 Only applicable to gadgets

frame .MyFrame ‘My Frame’ at …… anchor all

textpane .Txt anchor all width 5 height 5
button .Apply ‘Apply’ anchor bottom + right at
xmax-size ymax+0.5
path left
button .Cancel ‘Cancel’ anchor bottom + right
exit
Menus
 Menus are always members of forms but can
be employed in various ways by the form and
its gadgets
 Two types of menus:
 Mainmenu
 Popup menu
Defining a Bar Menu Gadget
 Defined within a form definition
 Created with bar subcommand
 Use the bar’s Add() method to
add options
Example:
setup form !!MyForm dialog size 25 1
bar
!this.bar.Add(‘Choose’,’Menu1’)
!this.bar.Add(‘Window’,’Window’)
!this.bar.Add(‘Help’,’Help’)

exit
Defining a Menu Object
 A Menu is a set of menu fields, each
representing an action that is invoked
when the field is selected
 A menu field can do one of three things:
 Execute a callback
 Display a form
 Display a sub-menu
Defining a Menu Object
 Example of a complete
menu definition:
-- Menu1 definition
!menu1 = !this.newMenu('MENU1‘,’Main’)
!menu1.Add('CALLBACK',‘Query Elbows',‘!!queryElbows()’)
!menu1.Add('SEPARATOR')
!menu1.Add('MENU','Pull-right','PULLR')

-- PULLR menu definition

!pullr = !this.newMenu('PULLR‘,’Main’)
!pullr.Add(‘CALLBACK’,’Menu 1’,’show !!MyForm’)
!pullr.Add(‘FORM',‘Gadz Menu','gdzMainForm')
Defining a Menu Object
 General Syntax:
!menu.Add(‘<Fieldtype>’,’<Dtext>’,’<Rtext>’, {‘<Fieldname>’})

 <Fieldtype>
 CALLBACK, TOGGLE, MENU, FORM
 <Dtext>
 Display text
 <Rtext>
 CALLBACK – callback string
 TOGGLE – callback string
 MENU – menu name string (cannot be blank)
 FORM – form name string without ‘!!’ (cannot be blank)
 <Fieldname>
 Optional argument (unique field name)
 Popup Menus
 You can use any of your defined menus as popup menus
for most interactive gadgets and for the form background
as long as you have specified them as belonging to the
popup menu system
 Triggered using Right-click
 A popup is added to a gadget or form using its SetPopup()
method
Example (Using MENU keyword):

button .But1 'A Button' at ……

menu .pop1 popup
!this.pop1.Add(‘TOGGLE’,‘Active/Inactive’,’’)
!this.pop1.Add('CALLBACK',‘Clear','ALPHA REQUEST Clear')
!this.But1.SetPopup(!this.pop1)
Popup Menus
 Another Way:

button .But1 'A Button' at ……

!popit = !this.newMenu(‘POPIT’,’Popup’)
!popit.Add(‘TOGGLE’,‘Active/Inactive’,’!this.Control(’)

!this.But1.SetPopup(!popit)
Toggle Menus
 A menu field with a callback action and a tick-box to show that the
field has been selected or unselected
 By default, the field is unselected

Example:

setup form !!Myform Dialog size 30 5

……
!menu = !this.newMenu(‘Test’,‘popup’)
!menu.add(‘TOGGLE',’Active/Inactive’,'!this.toggle(‘,'OnOff')
……
exit

define method .toggle(!menu is MENU, !action is STRING )

!name = !menu.Fullname()
!field = !menu.PickedFieldName
$P menu $!name $!action field: $!field
endmethod
ALERT Objects
 The ALERT object provides a simple way of giving a warning or
getting a response from the user, avoiding the necessity of
creating a separate form
 Alerts are always blocking: they prevent interaction with any other form until
they have been actioned
Examples:

!!Alert.Error(‘You cannot do this!’)

!!Alert.Message(‘Saving your data now’)
!!Alert.Warning(‘Do not press this button again!’)
!answer = !!Alert.Confirm(‘Are you sure?’)
!answer = !!Alert.Question(‘OK to delete component?’)

 Confirm Alert returns:

‘YES’ or ‘NO’ Strings
 Question Alert returns:
‘YES’ or ‘NO’ or ‘CANCEL’ Strings
ALERT Objects
 INPUT Alerts
 allows the user to obtain textual input from the operator via a
blocking alert which overrides all other interactive activities.
 The alert can be summoned by the alert methods:

!!Alert.Input( !prompt is STRING, !default is STRING) is STRING

Examples:

!!Alert.Error(‘You cannot do this!’)

!!Alert.Message(‘Saving your data now’)
!!Alert.Warning(‘Do not press this button again!’)
!answer = !!Alert.Confirm(‘Are you sure?’)
!answer = !!Alert.Question(‘OK to delete component?’)

 Confirm Alert returns:

‘YES’ or ‘NO’ Strings
 Question Alert returns:
‘YES’ or ‘NO’ or ‘CANCEL’ Strings
Form Exercise 2
 Create the following form. When stretched;
Form Exercise 2
The ‘Choose Template’ list gadget:
 It’s contents is based in an option file;

 First row means the Name of the template

 Next row is for the description
 Third row is the plot files
 Forth row is the macro file of the template
 Last row means how many arguments are needed of the template
 The list only shows the name and the description of the template
 Upon choosing each item on the list;
 The plot file will change based on the plot file defined in the option file
 The tag of the frame in the parameters frame will also change base on the name

 Disabling and enabling of the parameter fields are also handled

 Example (If the selected template’s required arguments are only 2, then parameter field 3 will be
disabled and parameter 1 and 2 will be enabled. Same concepts apply to all.)
Form Exercise 2
The ‘Create’ button:
 Upon clicking this button;
 Check validity of the name supplied (If already exists, etc.)
 Check validity of the hierarchy
 Check if all required fields of the chosen template are supplied by the user
 If successful to all checking, create the equipment and revert the form’s
mode to initialization mode.

Form as initialized:
 The first item is the default selection of the form
 This means, the plot file, parameter frame tag and enabled/disabled
parameter fields are also based on the default item selected

Supplied files:
 The option file, plot files, and macro files will be supplied.
 It is delivered together with this manual under Form Exercise 2 folder
 That’s All Folks!

DISCLAIMER:

This guide is for information purpose only. It is

recommended that users following this guide have
undergone training first.

You may use this manual at your own risk. In no

event shall the writer be liable for any direct,
indirect, incidental, exemplary or consequential
damages.

All examples in this guide are tested in PDMS 11.6 Author: Romel E. Daguplo
SP3 and SP5.
Email: romeldhagz@gmail.com