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
!!MyForm.GadgetName
!!MyForm.GadgetName.Val

$* name of the form

$* name of a gadget on a form
$* 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
!This.GadgetName.Val

$* just equal to !!Myform.GadgetName

$* 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
setup
setup
setup
setup
setup
setup

form
form
form
form
form
form
form

!!MyForm
!!MyForm
!!MyForm
!!MyForm
!!MyForm
!!MyForm
!!MyForm

dialog dock left

dialog resizeable
dialog
document
block
block resizeable

- creates a resizable docking dialog

- creates a resizable floating dialog
- creates a non-resizable floating dialog
- creates a non-resizable floating dialog
- creates a resizable MDI child document
- creates a non-resizable blocking dialog
- 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

RESIZEABLE command means that the form will be

displayed with re-sizing controls at its corners

The

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 forms 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 forms initialization callback allows the forms gadgets to be

initialized to reflect the current state of the application
You can set the callback by assigning to the forms 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 forms 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 forms 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 forms 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 forms 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
show !!formname free

$* default is a child form

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

gadgets 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

Common properties:
position
tag
tooltip
callback
anchor
docking

width 10 lines 3

All gadgets have this

Most but not all gadgets
have these

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 gadgets 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
!!MyForm.List1.Visible = TRUE

$* Invisible
$* Visible

Activating and de-activating gadgets

!!MyForm.List1.Active = FALSE
!!MyForm.List1.Active = TRUE

$* De-activate
$* 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
add
add
add
exit

.MyRGroup Choices: horizontal callback !this.Select()

tag Red select RED
tag Blue select BLUE
tag Green select GREEN callback !this.RadAction()

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)
Replacement values (RTEXT)
Display

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

events

to left-mouse SLIDER START, MOVE, and STOP

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

choice list gadget returns a STRING
Multiple choice list gadget returns an ARRAY of STRINGS
Single

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]
!col[1][2]
!col[2][1]
!col[2][2]

=
=
=
=

Flange_B1
Elbow_B2
Type is Flange
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]
!row[1][2]
!row[2][1]
!row[2][2]

=
=
=
=

Flange_B1
Type is Flange
Elbow_B2
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
selector
selector
selector
selector

.Sel
.Sel
.Sel
.Sel
.Sel

Selector: single width 12 height 5 DATABASE

multiple width 12 height 5 DATABASE OWNERS
multiple width 12 height 5 DATABASE MEMBERS
single width 12 height 5 DATABASE AUTO
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()

RTEXT

and 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

data type using IS

Supply a FORMAT object
Password type using NOECHO keyword
Specify

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 DRAFTs 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
put /SITE/SHEET

- draws the current element

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

left
0
1
2
3
4
5
6
7
8
9

are positioned on a form from top

0 1 2 3 4 5 6 7 8 9

1 character width per unit

1 line height per unit

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

$* default placement

.But1

HALIGN CENTRE
VDIST 4.0
para .Par2 width 4 height 2
toggle .Tog3

.Par5
$* auto-placed
$* auto-placed

.Par2
PATH RIGHT
HDIST 6.0
VALIGN BOTTOM
list .Lis4 width 5 height 4

$* auto-placed

PATH UP
HALIGN RIGHT
para .Par5 width 6 height 5

$* auto-placed

.Tog3

.Lis4

Relative Gadget Placement

Each gadget has four label points

XMIN

YMIN

XMAX

YMAX

XMAX

YMAX

XMIN

YMIN

gadget

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

0 1 2 3 4 5 6 7 8 9

X
previously created gadget used as
reference

YMAX
.Msg

YMAX + 2

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

0 1 2 3 4 5 6 7 8 9

.Para

existing paragraph gadget

YMAX.Para

.Frm

existing frame gadget

YMAX.Para+5
.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

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
describes gadgets with DOCK and ANCHOR
attributes

These

Complex Form Layout

Defines form with intelligent positioning and

resizing behaviour of gadgets using the DOCK
and ANCHOR attributes
DOCK Attribute:
Allows

you 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:
Allows

you 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:
Main

menu
Popup menu

Defining a Bar Menu Gadget

Defined within a form definition

Created with bar subcommand
Use the bars 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>

<Dtext>

Display text

<Rtext>

CALLBACK, TOGGLE, MENU, FORM

CALLBACK
TOGGLE
MENU
FORM

<Fieldname>

callback string
callback string
menu name string (cannot be blank)
form name string without !! (cannot be blank)

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:

Its 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 templates 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 forms
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

Thats 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
SP3 and SP5.

Author: Romel E. Daguplo

Email: romeldhagz@gmail.com