• UTF32BE UTF32 big-endian • ISO • LATIN1 ISO8859-1 • LATIN2 ISO8859-2• LATIN5 ISO8859-5 Cyrillic • Windows code page • CP932 Japanese shift-JIS • CP936 Simplified Chinese GBK • CP949 Korean • CP950 Traditional Chinese Big5 • CP1250 Central European • CP1251 Cyrillic • CP1252 LATIN1 + some extras (beware) • For backWards compatibility with legacy PDMS Proje cts • JAPANESE Japanese shift-JIS • CHINESE Simplified Chinese (EUC) • KOREAN Korean (EUC) • TCHINESE Traditional Chinese (used in Taiwan for e example) (EUC) PDMS provides a file transcoding utility transc.exE which users may find useful, particularly For moving files between PDMS12.1 and previous PDMS versions. Transc is a command line Application to transcode files from one encoding to another, and can also be used to add or Remove the BOM from existing UTF8 (or UTF16) files.The basic syntax is:  Transc -encoding> <input-file> -encoding> <output-f ile>  See Transc - text file transcoding utility.doc for more details. The major design decision for the Unicode conversi on of PDMS was to use (32bit) Unicode Scalar (US) iNstead of ASCII codes as it's integer character representation (holding Strings, with up to 4 bytes to represent 1 characte r. The section below describes a few Important properties of Unicode Scalars and the UTF 8 format.  Character. Unicode assumes tHat the 32 bit range wi ll cope uniquely with all the world's Character sets. Codes. To be able to clearly distinguish the number of cha racters held and the number of bytes Needed to represent them - as they cannot be assume d to be the same. Either direction.Search in either direction, and every first byte yi elds the number of bytes in the character. /, &, space, ~ etc.) then subsequent bytes of the c haracter are never ASCII bytes. So when You've found an ASCII byte it is a genuine characte r and not part of another character.


Diagnostic Messages From Within PML Files

PML Tracing If a PML File does not appear to be running in the way you expect the easiest thing to do Is to turn on PML Tracing with the command:  PML TRACE ON  With PML Tracing switched on, each of the PML lines executed is output to the parentWindow together with its line number. Additional tr acing messages tell you when you have Begun to process a new PML File and when it has fin ished. To turn off tracing type:  PML TRACE OFF  These commands can also be put into a PML File on a temporary basis.You can also turn PML tracing on by setting the Environment Variable PMLTRACE to ON before you start the Program. For more precise control of PML tracing yo u can use the $R command. $R100 is The equivalent of PML TRACE ON and $R0 is the same as PML TRACE OFF.Type the Command $HR for online help on how to use the $R command. It is often useful to output a line to the screen from within a running PML File to indicate That the execution of the program has reached a par ticular stage. Use the $P command: $P! Total is: $! Total and! Maximum is: $! Maximum  Note: The use of $ to convert the value of a variable to a STRING. The alpha-log is a file containing a record of all the commands processed together with Any text output and error messages. To startRecord ing use one of the following commands:  Alpha log /filename $* to open a new file Alpha log /filename OVERWRITE $* to replace an exis ting file Alpha log /filename APPEND $* to add to an existing file  To finish recording and close the file use:Alpha log END The alpha-log does not include standard PML tracin g from the command PML TRACE ON. For PML tracing to be included in the alpha-log , PML tracing should be directed to the Alpha-window. For example, to obtain standard PML t racing in the alpha-log use theCommand:  $R102  Refer to the online help given by $HR for other opt ions. If you cannot find out what is going wrong by mean s of PML trace output or writing out the Values of PML Variables, you may suspend a running PML File at a particular point byIncluding the command:


$M You  Can then query the valuesOf any PML Variables of i nterest and even change the values of Some PML Variables. To resume processing of the sus pended PML File type into the Command line:  $M+  Use these facilities only for debugging and do not leave these commands in a finished PMLFile.  Note: These facilities do not apply to PML Functions or m ethods. A variety of queries are available to help diagnos e problems. Typically you might type These queries into the command line while a PML File is suspended. Alternatively you could Include any of these commands temporarily within a PML File. If you are interested in the name of the currently running PML File and the other PML Files from which the current file was invoked use t he command:  $QM The table below gives some usefuL commands for que rying PML Variables.  Command Effect Q var! LocalName Queries the value of a specific local variable, u se the command. Q var LOCAL Queries the values of all local variables. Q var!! GlobalName Queries the value of a specific global variable.Q var GLOBAL Queries the values of all global variables Q var! MyArray[1] Queries the value of a specific element of an arr ay. Q var! MyArray Queries the values of all elements of an array. Q var! MyArray.Size() Queries the number of elements currently in an ar ray.When you are typing commands into a macro or into a command line, you may not Remember exactly what arguments are available or wh at other commands are related. You Will find full details in the appropriate Reference Manuals to the module, but you can also askThe command processor what sort of command or comma nds it is expecting next by typing: $Q  This will produce a list of every valid command wor d or argument type that you may enter Next. The list may be long and could include every valid command for the module that youAre in. The $Q facility is also useful to establish what is allowed as the next component of a Command. Type the beginning of the command sequence followed by $Q.


$M You can then query the values of any PML Variables of i nterest and even change the values of some PML Variables. To resume processing of the sus pended PML File type into the command line: $M+

Use these facilities only for debugging and do not leave these commands in a finished PML File.

Note:
These facilities do not apply to PML Functions or m ethods.
 A variety of queries are available to help diagnos e problems. Typically you might type these queries into the command line whilst a PML Fi le is suspended. Alternatively you could include any of these commands temporarily within a PML File.
 If you are interested in the name of the currently  running PML File and the other PML Files from which the current file was invoked use the command: $QM
 The table below gives some useful commands for que rying PML Variables.

Command   Effect
q var !LocalName   Queries the value of a specific local variable, u se the command.
q var LOCAL   Queries the values of all local variables.
q var !!GlobalName   Queries the value of a specific global variable.
q var GLOBAL   Queries the values of all global variables
q var !MyArray[1]   Queries the value of a specific element of an arr ay.
q var !MyArray   Queries the values of all elements of an array.
q var !MyArray.Size()   Queries the number of elements currently in an ar ray.
 When you are typing commands into a macro or into a command line, you may not remember exactly what arguments are available or wh at other commands are related. You will find full details in the appropriate Reference  Manuals to the module, but you can also ask
the command processor what sort of command or comma nds it is expecting next by typing: $Q

This will produce a list of every valid command wor d or argument type that you may enter next. The list may be long and could include every valid command for the module that you are in. The $Q facility is also useful to establish  what is allowed as the next component of a
command. Type the beginning of the command sequence  followed by $Q.


Upgrading from PML1 to PML2
• PML 1-First version of PML including loops, if sta tements, string handling , labels.
• Is faster with simple single line definition and s ingle execution,
• Returns array of strings of the references,
• The scope can include volumetric limits (within …) ,
• To obtain a value in PML 1 must be preceded with $ , var !value ($!number),
• PML1 must be still used when an expression is used  as an argument to a command and must be enclosed in () brackets,
• PML 1 macros are in PDMSUI folder,
• PML 2-Object oriented language builds on PML 1 and  extends the facilities to be like other object based languages (VB, Smalltalk)
• Is slower and initially more lines of code to set up the collection is necessary,
• Returns array of database references and
• Collection can be used as the scope of a collectio n,
• Can be used with the TABLE object,
• Can’t use volumes to limit the scope,
• To obtain a value in PML 2 is used =, !value = !nu mber,
• PML2 may be of any complexity, may contain PML fun ctions and methods and form gadget values, !value = !!MyFunction(!arg) * !!Form .Gadget.Val / !MyArray.Method(),
• PML2 may consist operators and operands (+,-,*,/,G T,AND,OR,&,EQ…),
• PML 2 macros are in PMLLIB,
• Variable Types - STRING, REAL, BOOLEAN and ARRAY,
• Built in methods for commonly used actions,
• User Defined Object Types,
• PML Search PATH (%PMLLIB%),
• Dynamic Loading of Forms, Functions and Objects,
• New Aid objects for geometric modelling,
• $Wn - Will Break the GUI Software
• Numbered Variables - Are no longer available
• Macros - Avoid Mixing with PML Functions
• Global Variables for results - Use Function “Retur n”
• $M- $M+ $MK - Only for debugging, not LIVE code
• $R+ $R- - Withdrawn, (PML TRACE ON/OFF)
• Synonyms - Not permitted in PML Functions but work s in macros,
• VAR Syntax - Use “=“ Where possible
• VAR Name READ - Use ALERT object or Form
• Expressions in () - Brackets not needed after “=“
• !VALUE = NAME - Use !VALUE = !!CE
• $ - Use variables without $
• Don’t Quote variables - With no $, quotes not need ed
• @ cursor functions - Use Event Driven Graphics
• !ARRAY[-ve] - Not allowed in PML2
• !ARRAY[0] - Not advised to use at PML2
• Dots “.” In Names - New meaning at PML2
• Form EDIT  - syntax Use direct setting


Important difference between PML1 and PML2

Important differences
Only Algebraic expressions are allowed, (No reverse -polish notations after “=“ sign)

Creating numeric variable with “=“ creates a REAL

Some PML1 macros using the “=“ will now create vari ables of the wrong type.

VAR !name value will now create a STRING value.

DO variables are now REAL rather than STRING

If “=“ has been used in existing PML code and probl ems are found, re-write the code using PML2 technology, or revert to PML1 VAR technology.

Conversion utility “eq2var” (Currently runs through  an “awk” script)

DO variables in PML2 are automatically deleted to e nsure that they can be created, This can upset other variables if of the same name.

On exit DO variables remain REAL; previously they w ould have been STRING +1 if loop ran to completion.

Variable in “do values” is deleted on exit.

DO from to are required to be REAL, Existing macros  are unaffected by this ($)

Change variable names to avoid DO variables

Check DO expressions, re-write as necessary

Results of an expression in IF must be TRUE or FALS E.

An error will occur where ZERO=FALSE

e.g.                                     if ($value) then - - (PML1)
will have to be either       if ($value EQ 1) then
                                  or if ( BOOLEAN($value)) then

Most common occurrence
PML1  if ( match ($!String1,$!String2)) then
PML2  if ( match ($!String1,$!String2) GT 0 ) then

Check Form and Global Variable Names

Forms are now GLOBAL variables, and cannot have the  same names as a Global Variable.

Form and Gadget Names Must be Unique and Start with  a Letter

Forms & Menus enforces the rule that gadget names m ust start with a letter, and must be
unique, (Gadget names can be re-used in different f orms).

New Forms & Menus Error Messages.

No longer possible to use setup form from within .I NIT macro.


Gadgets that are outside the form are now ERRORS.

More than one OK,CANCEL or HELP will generate an error.

Var list & do list are restricted to LIST gadgets, for TEXTPANES & SELECTOR gadgets use var pane,selector & do selector

DOT in variable, Form and Gadget Names Is now used as separator between a Form or Object name and the name of one of its members or f unctions.

!Array.size()
var !String ‘comment’
!Old.Name = ‘!String’

could now use:
!Size = $!<Old.name>.length()
or
!Size = $!Old.name$N.length()

Negative Array Subscript is now an Error.
Array subscripts MUST now be positive or zero, Zero  is permitted but many of the array methods ignore the zero’th element. Macros which ma ke use of negative array subscripts will need to be revised.

$MKn & $MK-n Withdrawn.

These commands may have had a role when macros were  run directly from a terminal, but are incompatible with form-driven software.

Macros will have to be re-written.

Synonyms are NOT Available in PML Functions but are  still available in Macros.

= in PDMS10 is not compatible with = in PDMS11

Components in Function to the Right of “=“

Existing “var” code is not affected.

Add brackets if PML1 code has none.

To convert to “text” add “$”

!X = 32 , !Y = 52
!Z = !X + !Y Result = REAL  …..84
!Z = ‘$!X’ + ‘$!Y’ Result = STRING  …..3252


PML Form concepts
 The AVEVA software module which provides the abili ty for users to customize the PDMS graphical user interface using the PML is referred to as PML Forms & Menus (or just F&M).
The default ‘system font’ used by Forms and Menus t o display character data is Arial Unicode MS which contains a large number of the wor ld’s alphabets. Internally F&M uses full Unicode, but can only display the characters access ible in its current ‘system font’. You will
be able to copy and paste Unicode characters from a nd to textual fields of F&M gadgets.

 In PML 2, forms are a type of object represented b y a global variable — the form’s name, for example !!EntryForm . This means that a form cannot have the same name as any other object type, global variable, or any other form. Th e form object owns a set of predefined
member variables and built-in methods. In addition,  you can define your own members — form variables and form gadgets — and your own form  methods. All these will determine the content and functionality of the form. Gadget objec ts are user-defined members of the form object. Form members are always accessed using the dot notation, for example !!EntryForm.TextField

Gadgets own a set of predefined member variables an d built-in methods which determine the content and functionality of the gadget. For ex ample, the value of a text field gadget is accessed by: !!EntryForm.TextField.val.

Note that gadgets do not support user-defined membe r variables or user-defined gadget methods.

Callbacks  are user-defined actions assigned to a form and it s gadgets and that are executed when the operator interacts with the form,  for example, by clicking a mouse button on a gadget. The callbacks are supplied as text str ings and may be any valid PML
expression, PML Function or method call, including any form, gadget or user defined object method. Effectively, these callbacks determine the intelligence of the form.
 The following are examples of the format of form a nd member names:

!!EntryForm  The name of a form
!!EntryForm .GadgetName The name of a gadget on a form
!!EntryForm .GadgetName.val The data value held by that gadget

Note:
That total length of the name is limited to 1024 ch aracters even though the length each individual components is limited to 64 characters. Within the form definition, the members of the form should be referred to by using !This to re place the form name part of the gadget
name. For example:

!This.GadgetName
!This.GadgetName.val

Note: The obsolete convention of using an underscore to r eplace the form name has been retained for compatibility with earlier versions.


Simple Form
 You define a form using a command sequence that st arts with:

setup form !!formname

and ending with:

exit

 Between these two commands come a number of option al subcommands which define the gadgets on the form. The following example defi nes a small form, containing the text ‘Hello  World’, and a button labelled ‘ Goodbye’ , which removes the form when pressed:

setup form !!hello
  paragraph .Message text 'Hello world'
  button .bye 'Goodbye' OK
exit

- A simple form
 Some points to note about the above definition and  the form it creates are:

• there are no user-defined methods on this form, an d so the setup form . . . exit sequence is the complete form definition;
• the paragraph command adds a paragraph gadget to t he form (a paragraph gadget is just a piece of text displayed on the form). The na me of the gadget is Message, and the dot before the name indicates that the gadget i s a member of the form. The text itself is specified after the keyword TEXT.
• the button subcommand adds a button gadget named . bye. The text on the button will be ‘Goodbye’. The keyword OK is a form control attr ibute that specifies that the action of this button is to remove the form from th e screen.

To display the form in this example, you can use th e command: show !!Hello
 To perform intelligent actions a form or gadget mu st invoke a callback.We will now add a simple gadget callback to the hello form. We will a dd a second button, change message, which will execute a callback to modify the Message  paragraph gadget.

setup form !!hello
  paragraph .Message text 'Hello world'
  button .change ‘Change message’ callback |!this.m essage.val = ‘Modified’|
  button .bye 'Goodbye' OK
exit


A gadget callback is defined by the callback comma nd followed by a command or PML Function enclosed in text delimiters. As we are giv ing a text string as part of the command which is itself supplied as a text string, we have had to use two kinds of delimiter: the
apostrophe, (‘) and the (|) vertical bar.

Note: The use of this to mean the current form. When the callback is executed,

!this.message.val = ‘Modified’

will set the value member of the gadget Message on this form to read Modified rather than Hello world.

Note: The gadget callback could have been

|!!OtherForm.Para.val = ‘Modified’|

to change the value of a paragraph gadget on anothe r form named !!OtherForm. Typically a callback will involve many commands and could be a complex piece of code in its own right.
In practice, the recommended way of defining a comp licated callback is to use a form method.
 Form definitions must be held one per file. The fi le name must be the form’s name in lowercase with the file extension .pmlfrm.  For example, our form !!Hello would be captured in a file called hello.pmlfrm. This definition file should be stored in a director y pointed to by
the PMLLIB  environment variable. It will then be loaded autom atically on execution of the show !!Hello  command. The form definition file contains:

• The form definition between setup form and exit. T his includes the commands which create the form itself, and set its attributes, suc h as its size and title, the commands which create the gadgets on the form and specify ho w they are arranged, and the definitions of any variables which are to be member s of the form.
• Any method definitions should follow the exit comm and, each method beginning with the define method command and ending with endmethod . Methods on forms are just like methods on any other kind of object.
• In particular, it will contain the form's default constructor method. This is a method with the same name as the form, and no arguments. It is the only method called automatically when the form is loaded, and so it ca n be used, among other things, to set default values for the gadgets on the form.
• The form may be given an initialization method, wh ich is run whenever the form is shown (as opposed to when it is loaded).
• No executable statements should appear in the file  outside of the form definition or form methods. The effect of misplaced executable st atements is indeterminate. You can put comments anywhere in the file.
 A form definition must be loaded before the form c an be displayed. If you have stored the definition in a . pmlfrm  file then loading will be automatic when the form is displayed for the first time. Normally, a form is displayed as a resu lt of the operator making a menu selection
or pressing a button on a form. This is achieved ei ther by using the Form Directive in the
menu or button definition (see next section) or by means of the command show !!formname
used in the gadget’s callback. However, to display forms when you are developing them, you
may find it convenient to type the command:
show !!formname


Sometimes it is useful to force the loading of a f orm’s definition file before the form is actually displayed, so that you can edit the form or gadget attributes from another form’s callbacks before the form is actually displayed. Us ing the command loadform !!formname

from a callback will force load the definition if t he form is unknown to PML, but do nothing if the form has already been loaded. Once a form has b een displayed you can remove it from the screen using the command

hide !!formname

Note that if you show it again it will appear on th e screen, but its definition is already known to PML and so it will not be loaded. It is possible  to remove a form definition from PML using the command kill !!formname

The form is then no longer known to PML until a new  definition is loaded.

Note:  Earlier AppWare used form definitions in macro fil es which had to be loaded explicitly via $M path-name-to-file. This mechanism still oper ates for backwards compatibility, but is strongly discouraged when writing new AppWare.
 PML directives are commands used to control PML it self. For example, you use a PML directive to instruct PML to re-make its index when  you have added a new file. Some of these directives have been described in Storing and  Loading PML Files: the information is
repeated here, with additional directives for loadi ng forms. Note: Unlike the PML commands described in How Forms are Loaded and Displayed, PM L directives should not be included in callbacks, but are generally for command line us e. You will need to use PML directives
when you are developing new form definitions or mod ifying existing ones. PML directives are commands of the form pml . . . The table below give s some useful PML directives.

Command Effect:

pml rehash  When you create a new PML Form while an AVEVA prod uct is running, you must link in the file storing the form by giving th is command. It causes PML to scan all the directories under the PMLLIB path, and to create a file pml.index, which contains a list of all
the .pmlfrm files in the directories. pml index  This command re-reads all the pml.index files in y our search path without rebuilding them. If other users have added PML File s and updated the appropriate pml.index files, you can access the new files by giving this command.
pml reload form !!formname  When you edit an existing form while an AVEVA prod uct is running, you must use this directive to reload the form definition file.
kill !!formname  If you experience problems of an edited form defin ition not being re-loaded, you can use this directive followed by the pml relo ad directive.
pmlscan directory_name  This command runs a utility supplied with AVEVA pr oducts.
When you are not running an AVEVA product, you can use this command to update the pml.index file in a given directory.


Revisiting our Simple Form
Our simple form !!Hello , which we constructed earlier in this chapter, is not very intelligent.
Once we have pressed the Change button the .Message  paragraph will read ‘Modified’ for ever more, even if we hide the form and re-show it.  The extended version of form !!Hello below:

• illustrates the use of the form definition file;
• illustrates form methods as callbacks;
• introduces some important predefined form members.

First save the definition in a file called hello.pm lfrm and ensure that its directory is in your PMLLIB search-path.

setup form !!hello
  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 .hello()
  -- default constructor - set gadget load-time def ault
  values
  !this.message.val = ‘Hello world’
  !this.capture.callback = ‘!this.message.val = !th is.capture.val’
  !this.Okcall = ‘!this.success()’
Endmethod

define method .success()
  -- action when OK button is pressed
  !this.message.val = ‘Hello again’
  !this.capture.val = ‘’
Endmethod

- A Smarter Form

In the form definition:

• title sets the form title member and hence display s a title;
• para adds a PARAGRAPH gadget size 15 chars by 1 li ne with no content;
• text adds a TEXT field gadget with tag ‘Enter mess age’, width 15 chars, to hold data of type STRING.

The constructor method .hello() does the following:

• initializes the paragraph’s default value to ‘Hell o world’;
• defines the callback on the text input field: to i nsert its value into the paragraph;
• sets the form member Okcall (in the line beginning  !this.Okcall). This is a callback that gets executed when a button with control-type OK is  pressed.


The definition of method .success() does the following:

• Sets the paragraph’s value to ‘Hello again’.
• Resets the text field’s value to empty.

Now load and show the form by typing:

PML rehash
show !!Hello

 This will auto-load the form definition and execut e the default constructor method (which will set the message paragraph to ‘Hello world’ and  define the gadget and form callbacks). It will also display the form. Type your message into the Enter message field and press the
Enter key. This will execute the field’s callback, which will write your typed text into the message paragraph. Type a new message and press Ent er. The paragraph updates to reflect what you typed. Click the Goodbye button. T his executes the form’s Okcall action
which calls the success() method. The success() met hod sets the paragraph to ‘Hello again’ and blanks out the text field. Finally, the OK cont rol action hides the form.

Show the form again and observe that the paragraph reads ‘Hello again’ and not ‘Hello world’. This demonstrates that when you re-show the  form the form’s constructor is not run, because the form is already loaded. If you want to reset the form every time it is shown, you
must define a form initialization callback.


Forms and Gadget callbacks
A callback may be any valid expression, including a ny AVEVA product commands. For example, the following is a PDMS command: ‘new box xlen 10 ylen 20 zlen 50’

It can also include PML general commands like ‘$m %pathname%/MyMacro’

to execute a given command macro, or ‘q var !!form’ ‘q var !!form.gadget’

which will write out details of the form or gadget and its members. You might like to try it on the form !!Hello.Typical expressions for a ca llback are

‘!this.gadget.val = !MyObject.count’
‘!MyObject.count = !this.gadget.val’

which get or set the value of a gadget on the form from or to a user-defined object.
 Most callbacks require more than a single command,  so invoking a method or function (or macro) is an essential requirement. The advantage o f using form methods as callbacks is that this keeps the whole form definition in a sing le file. Forms defined in early versions of
PML 2 used PML Functions as callbacks. This is stil l valid and is sometimes even essential as you may need to manage a group of forms; but mos tly the callbacks on a form are specific to that form.

setup form !!hello
  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 .hello()
  !this.message.val = ‘Hello world’
  !this.capture.callback = ‘!this.message.val = !th is.capture.val’
  !this.Okcall = ‘!this.success()’
Endmethod

define method .success()
  !this.capture.val = ‘’
endmethod

 The .success() method above could only deliver a f ixed string ‘Hello again’ to the message PARAGRAPH gadget. The great advantage of me thods is that you can pass variables as arguments to the method, so it can be used more generally, for example as the callback to several gadgets.

define method .success( !output is GADGET, !message  is STRING, !input is GADGET )
  output.val = !message
  input.val = ‘’
endmethod


We have added three arguments, an output gadget, an  input gadget and a message string variable. This has made the method very general. We  can still use it as the Okcall callback:

!this.Okcall = |!this.success( !this.message, ‘Hell o again’,!this.capture )|

 When the OK button is pressed the Okcall action wi ll invoke the success() method, passing to it the message paragraph gadget as !outp ut, the message text ‘Hello again’ as !message and the text input field gadget capture as  !input. The method will do just what it did
before. However, we could use it differently. We co uld add another button gadget, Restart, to the form:

button .restore 'Restart' callback |!this.success( !this.message,‘Hello world’, !this.capture )|

 When clicked, the Restart button‘s callback will e xecute and set the message paragraph gadget to read ‘Hello world’ and clear the capture text field, thus restoring the form to its state when it was displayed for the very first time . If we invoked the success() method as:

!this.success( !this.capture, ‘Hello world’, !this. message )

it would set the value ‘Hello world’ into the captu re text input field and clear the contents of the message PARAGRAPH gadget. Not what you need her e perhaps, but you can see how versatile methods can be!

Note:  The arguments to methods can be any valid PML obje ct types, built in or user defined.
When the operator interacts with a GUI, an event oc curs. For example, when the operator:

• types something into a field on a form;
• moves the cursor into a window;
• presses down a mouse button;
• moves the mouse with button down;
• let’s the button up.

 The events are queued in a time-ordered queue. The  application software services this queue: it gets the next event, determines the objec t of the event (for example, form, gadget, menu) and the event type (for example, enter, leave , select, unselect, popup etc.), deduces
appropriate actions and carries them out. When one event is completed, the software looks for the next event.
 There are a very large number of possible events, and most of them are very low level and have to be serviced very quickly to produce a u sable GUI. It would be inappropriate to allow the (interpreted) PML AppWare access to them all. However, the application software
defines a set of meta-events for forms and gadgets. When a meta-event occurs, the application software checks for user-defined callba cks and executes them. Hence callbacks are the AppWare’s way of providing actions to be ca rried out at these meta-events.

 Callbacks provide a simple yet versatile mechanism  for the AppWare to create and manage the GUI. Sometimes there is more than one me ta-event associated with a gadget. In this case, the simple assigned callback is insuf ficient to fully exploit the gadget's possible
behaviors. To overcome this shortcoming we can use open callbacks to allow the AppWare


Using a PML Function in an Open Callback

to be informed whenever a meta-event is encountered . Open callbacks can be used wherever callbacks can be used. They always involve  methods or PML Functions with a fixed argument list as follows:

define method .Control( !object is FormsAndMenusObj ect, !action is STRING)

• !object is a Forms and Menus object, for example, a form, gadget or menu.
• !action is the meta-event that occurred on the obj ect and represents the action to be carried out by the method.

The open callback is a string of the form:
'!this.MethodName('

Note:  The open bracket '(', no arguments and no closing b racket. The callback is to an open method or function.

We might assign an open callback to a multi-choice list gadget as follows:

setup form !!Open
  title 'Test Open Callbacks'
  list .choose callback '!this.control(' multi widt h 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() $*get object’s owner
    !type = !object.type() $*get object type
    !name = !object.name() $*get object name
    !field = !object.PickedField $*get picked field  number
    !s = !object.DTEXT[!field] $*get DTEXT
    -- do something with the data
    $p selected $!form$n.$!name $!type field $!fiel d, D text{$!s}
  elseif (!action eq 'UNSELECT' ) then
    !n = !object.PickedField $*get picked field num ber
     $p unselected field $!n $*do something with     data
  endif
endmethod

Note  in the constructor method open() we have initializ ed the list so that field n will display list field n. DTEXT is a shorthand for display-text , that is the text displayed in the list field.
• Control is the method which manages interaction wi th the list. Note the open callback
• defined in list choose.
• Note the use of $* for in-line comments
• Note the use of the printing command $p to print i nformation to the system Request channel. $!form replaces the variable !form with it s current value as a string - this only works for PML simple in-built scalars types RE AL, STRING, BOOLEAN. $n in $!form$n.$!name is a separator needed to separate $ !form from the following ‘.’ which would otherwise be thought of as part of the variable name. When a list field is clicked, the list’s callback will be examined an d if it is an open method or function, then the Forms and Menus software will supply the a rguments required to complete the function.


Thus in this case the actual callback string execut ed will be

|!this.control( !!Open.choose, ‘SELECT’ )|

 Inside the control() method we branch on the value  of !action and access the data of !object (in this case our list). Finally we perform  our application’s resultant action - in this case just printing out all we know about the operat or interaction using the $p command,
which for a selection of an un-highlighted list fie ld will write: Selected OPEN.CHOOSE LIST field 5, Dtext{list field  5}

Notice that the same method could be used to manage  several or even all gadgets on our form since the variable !object is a reference to a  gadget object and is supplied as !!Open.choose, the full name of the gadget includin g its form. This allows us to find
everything about that object from its in-built meth ods, including its gadget type (LIST, TOGGLE, etc) and its owning form:

!type = !object.type()
!form = !object.owner()
All the examples so far have used form methods as o pen callbacks. The code would be essentially the same if we used PML Functions. The PML Function must be in a file of its own called control.pmlfnc. The body of the definiti on would be identical but must be
bracketed by:

define function !!Control( !object is GADGET, !acti on isSTRING)
endfunction

Note that the function has a global name !!control,  that is, it is not a member of any form or object and thus cannot use the !this variable The o pen callback on the choose list gadget would become list .choose callback '!!control(' multi width 15 h eight 8

The rest of the story remains the same.
 Object  Object Callback
LIST multichoice Gadget SELECT,UNSELECT,START,STOP
LIST singlechoice Gadget SELECT, UNSELECT
OPTION Gadget SELECT, UNSELECT
ALPHA VIEW Gadget SELECT
BUTTON Gadget SELECT, UNSELECT
TOGGLE and RTOGGLE Gadget SELECT, UNSELECT
MENU (command fields) Menu SELECT, INIT
MENU (toggle fields) Menu SELECT, UNSELECT, INIT
FORM Form INIT, QUIT, CANCEL, OK,KILLING, FIRSTSHOW N
TEXT Gadget SELECT, MODIFIED, VALIDATE
SLIDER Gadget START, STOP, MOVE
FRAME Gadget SELECT, UNSELECT,SHOWN, HIDDEN
NUMERICINPUT Gadget SELECT, MODIFIED
COMBOBOX Gadget SELECT, UNSELECT, VALIDATE


Forms
 A PDMS GUI module consists of a set of co-operatin g applications running within the Application Window. Each module has:
• A Main form to present the default application and  to control access to the other applications.
• One or more document forms usually displaying the application model.
• Transient floating dialog forms that relate to spe cific tasks.
• A small number of docking dialog forms to provide frequently required services. The Main form has a menu bar that provides access to al l the functionality of the current application of the module, from its pull-down menus  (the main menu system), and a set of toolbars, each containing gadgets (usually i con buttons, icon toggles and pull-down lists) designed to give fast access to frequen tly used functions. The Main form is not displayed directly, but supplies all its men us and toolbars to be displayed in the Application Window.
The form definition is a command sequence starting with:

setup form !!formname

and ending with:

exit

The sequence includes:

• The commands which create the form itself and set its attributes, such as its minimum
size and title.
• The commands which create the gadgets on the form,  and specify how they are
arranged.
• The definitions of any variables which are to be m embers of the form.
All the form attributes are optional and have sensi ble defaults. Those which can only be set once must be specified on the setup form line. Thes e are:

• Form type.
• Layout mode.
• Minimum size.
• Resize.
• Docking.
• Form position.
• NOQUIT
• NOALIGN

Other attributes are specified as sub-commands in t he setup form . . . exit sequence. They can be edited after the form has been created by me ans of the form’s in-built members and methods.


Form Type
 The appearance and behaviour of a form is determin ed by its Type attribute:

MAIN  The form that will be swapped to as a Main form. T hese forms are not usually displayed directly, but serve to provide gadgets fo r the application’s toolbar and menus for the application’s main menus.
DOCUMENT  Resizable form usually with a view gadget, but no menu bar. All document forms can be floated or un-floated using the right- mouse popup menu in the form’s top border. When it is floating, you can drag the form away from the MDI frame and position it
and resize it without constraint. This allows you t o drag the document form away to another screen of a multiscreen configuration.
DIALOG  This is the default type the form will assume if y ou give no type when you set up the form. The default DIALOG form will be non-resiz able, floating, and non-docking. You can specify the DOCKING  attribute to allow the form to be docked within th e application frame. By default, a docking dialog is displayed floating, and you can i nteractively dock it. When a dialog is docked it will be resized to match the application frame edge to which it is docked, and so is resizable by default. The qualifiers LEFT, RIGHT, T OP, and BOTTOM, specify the edge of the application frame to which the dialog form will  be docked when first displayed.
BLOCKING DIALOG  Normal form layout and content, but will block acc ess to all other forms while it is displayed.

Here are some examples of ways you can set up forms  of different types:

setup form !!myform dialog dock left - Creates a re sizable docking dialog;
setup form !!myform dialog resizable - Creates a re sizable floating dialog;
setup form !!myform dialog - Creates a non-resizabl e floating dialog;
setup form !!myform - Creates a non-resizable float ing dialog;
setup form !!myform document - Creates a resizable MDI child document;
setup form !!myform document Float - Creates a floa ting resizable non-MDI document.
 Two layout modes are supported, namely VarChars an d FixChars. VarChars is a new layout mode, based on measuring precise string widt hs. It is better suited to the use of variably spaced fonts, and tends to produce smaller , more pleasing forms, without unwanted
space. The benefits of using VarChars are:

• It tends to produce smaller, more pleasing forms, without unwanted space.
• No text wrap-around, except possibly in conjunctio n with TagWidth.
• No truncation of explicitly defined text except po ssibly in conjunction with TagWidth.

The recommended layout mode for all new forms is:
setup form !!formname . . . VarChars

 FixChars is the old layout mode (prior to PDMS12.1 ), which is based on the use of notional character width to calculate the approxima te sizes of textual gadgets and gadget tags. Because the calculated sizes are only approxi mate, the user has to make frequent use
of the gadget's Width specifier and TagWidth specif ier and considerable trial and error to achieve a desired layout.
 The default layout mode for setup form is FixChars, because this will be th e least disruptive for existing user Appware, so FixChars m ode will currently result from either of

setup form !!formname . . .
setup form !!formname . . . FixChars


Minimum Size and Resizability
 A form will automatically stretch to fit the gadge ts you add to it. You can use the SIZE keyword to give a minimum size in multiples of the character width and line height . For example:

setup form !!New1 size 25.5 10

• Character width is the notional character width for the selected ch aracter font.
• Line height is the height of the tallest single line gadget, th at is a TOGGLE , BUTTON ,

RADIO BUTTON, OPTION  gadget or single-line PARAGRAPH  for the selected character font. The RESIZABLE command means that the form wil l be displayed with re-sizing controls at its corners. This will allow the user to change the size of the form. Docking forms and all
document forms are resizable by default; but for ot her types, if you do not include the RESIZABLE command, the size of the form is fixed.

setup form !!New1 RESIZABLE
setup form !!New2 size 25 10 RESIZABLE
 All gadgets except ALPHA and VIEW gadgets have DOCK and ANCHOR attributes that allow you to define gadgets that have intelligent p ositioning and resizing behaviour when their container gadget resizes.

 This allows you to have more than one resizable ga dget on a form and still have predictable and potentially complex resize behaviou r. However, the DOCK and ANCHOR attributes are mutually exclusive: setting the DOCK  attribute resets the ANCHOR to the
default; setting the ANCHOR attribute resets DOCK t o none.

 ALPHA and VIEW gadgets do not support DOCK or ANCH OR attributes. They do, however, expand to fill their containers, so you ca n put them in a frame and set the frame’s DOCK or ANCHOR attributes to get the behaviour you desire.
Certain gadgets, known as the linear gadgets, have their centres auto-aligned approximately to aid simple layout without the user  having to know about PATH and ALIGN concepts.

 This pseudo-alignment gives sensible layout for si mple forms, but introduces small errors in all other circumstances and prevents accurate co ntrolled layout because the user doesn’t know the offsets applied. The NOALIGN keyword allow s you to switch off this pseudo
alignment.
 The gadgets BUTTON, TOGGLE, TEXT, OPTION, single l ine PARGRAPH fit within 1 vertical grid unit and are by default drawn with th eir Y-coordinate adjusted so that they would approximately centre-align with an adjacent BUTTON.  This pseudo-alignment introduces
small errors in all but a few circumstances and pre vents accurate controlled layout.
NOALIGN prevents this (historical) gadget auto-alig nment. Use NOALIGN in conjunction with PATH RIGHT (the default path) and HALIGN CENTR E, as it gives a better layout, with fewer surprises.
Note:  It is bad practice to place one gadget on top of a nother. This may lead to gadgets being obscured. The commands to set modifiable attr ibutes are described after the syntax graph.


Form Members
 The title sub-command is used to supply a string t hat is displayed in its banner at the top of the form's window. To set the title: title 'Quite a Long Title for a Form'

You can modify the title at any time using the Form Title member: !!MyForm.FormTitle = 'Modified Title'

The icontitle sub-command is used to supply a strin g that is used when a form is iconized.
To set the icon title: icontitle 'Short Title'

You can also modify the icon title at any time usin g the IconTitle member:

!!MyForm.IconTitle = ‘New Icon’
 The form’s initialisation callback allows the form ’s gadgets to be initialised every time it is shown to reflect the current state of the applicati on and possibly to validate whether the form can be displayed in the current context. You can se t the callback by assigning to the form’s initcall member. This can be done with the INITCALL  command:

INITCALL ‘!This.InitCallBack()’

or directly by

!!MyForm.initcall = ‘This.InitCallBack()’

Note:  The form initialisation callback must not attempt to display another form. You may invoke an ALERT object but not otherwise seek any i nput from the user. If the callback discovers an error so serious that the form cannot be displayed it can abort the display of the
form by returning an error. You can supply the text  of an error message that is to be presented in an error alert in place of the form:

define method .initcallback()
  return error 1 'You do not have write access to t his
  database'
endmethod

If the initialisation callback has already caused a n alert to be raised then you can prevent the raising of a new error alert by using the NOALERT k eyword:

define method .initcallback()
  return error 1 NOALERT
endmethod
The form supports the concepts of OK and CANCEL actions:

The OKCALL callback is executed when a form’s OK bu tton is pressed or when the OK button of a form’s ancestor has been pressed It all ows operators to approve the current gadget settings and carry out the function of the f orm. The form is then removed from the
screen. Typically this callback will gather all the  data from the form’s gadgets and perform


the form’s major task. If you do anything of signif icance in callbacks on other gadgets you may have a hard time undoing everything if the user  presses the CANCEL button. You can assign to the form’s OKCALL member using the comman d OKCALL ‘CallbackString’ . You
can modify the Okcallback at any time using !this.Okcall = ‘CallbackString’ .

The CANCELCALL callback is executed when a form’s C ANCEL button is pressed, when the CANCEL button of a form’s ancestor is pressed ( see section on Form Families) or when the window’s CLOSE gadget is used. It allows the op erator not to proceed with the functions
of the form. The form is then removed from the scre en and all gadgets are automatically reset to the values they had when the form was disp layed or when any APPLY button was last pressed. Typically this callback allows you, t he PML programmer, to undo any actions
already carried out on the form that ought to be un done in the light of the CANCEL request You can assign to the form’s CANCELCALL member usin g the command CANCELCALL ‘CallbackString’ .

You can modify the CANCELcallback at any time using

!this.Cancelcall = ‘CallbackString
 All Forms have a QUITCALL member that you can pass  a standard callback string. This is executed whenever the user presses the Quit/Clos e icon (X) on the title bar of forms and the main application window. If an open callback is  used then it is called with the FORM
object as its first parameter and ‘QUIT’ as its act ion string. QUITCALL for MAIN Forms For forms of type MAIN, the QUITCALL callback is execut ed, if present. This permits the user to terminate the application, and so the associated PM L callback should prompt the user for
confirmation. If the user confirms the quit, then t he callback should close down the application, and not return. If the user decides no t to quit, then the callback should return an error to indicate the decision to F&M.

 Use return error…noalert if you want to avoid disp laying an error alert. If the form has no QUIT callback, then the QUIT event will be ignored.  The following example shows a (global) PML function, that you could be use from all forms of type MAIN:

define function !!quitMain( )
  -- Sharable method Quit the application
  !str = !!Alert.Confirm('Are you sure you want to quit the application?')
  if( !str eq 'YES' ) then
    -- execute application termination command, whi ch should not return
    finish
  else
    return error 3 |user chose not to QUIT| noalert
  endif
endfunction

This would be called from the form definition funct ion body or from its constructor method as shown below:

Setup form !!myApplication MAIN
  quitCall ‘!!quitMain( )’
exit
define method .myApplication( )
-- Constructor
  !this.quitCall = ‘!!quitMain( )’
endmethod


Essentially, if no QUIT callback is present, then t he form is cancelled (hidden with reset of gadget values). If a QUIT callback is provided then  you can prevent the default Cancel action by returning a PML error, but you must hide the form from your callback method (It is
more efficient the use ‘!this.hide()’, rather than ‘hide !!myform‘ from your form methods).

Note:  F&M does not display an alert for the returned err or, it is merely for communication.
You don’t need a QUIT callback if you just want to allow the form to be hidden. For DOCUMENT forms (MDI children) only, the callback must not display an alert as this will cause some gadgets to malfunction afterwards.
Typically assigned in the Constructor by

!this.FirstShownCall = '!this.<form_method>'

 The purpose is to allow the user to carry out any form actions which can only be completed when the form is actually displayed. Ther e are a variety of circumstances where this arises and it is often difficult to find a rel iable solution. A couple of examples are given
below. Commands which manipulate form, menu or gadg et visual properties, executed from a PML macro, function or callback may not happen un til control is returned to the window manager's event loop. For example, in the applicati on'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 manage r. 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()' w ithin the FIRSTSHOWN callback, because the form will be guaranteed to be actually displaye d (and hence known to the window manager), before it is hidden It is sometimes diffi cult to achieve the correct gadget
background colour setting the first time the form i s displayed. This can be resolved by setting the required colour in the FIRSTSHOWN 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. gl obal 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:
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. killing callbacks.
 It is often convenient to store additional informa tion on a form which will not be displayed to the user. This is achieved by defining form vari ables. These are variables which can be any of the PML data types, including ARRAYS and OBJ ECTS. These variables have the same lifetime as the form and are deleted when the form itself is killed.


Form members are defined in just the same way as ob ject members:

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 j ust the same way as an object
member:

!!MyForm.MyNumber = 42
!Text = !This.MyNumber
!ThirdValue = !This.MyArray[3]

In a callback function you can use !this. to repres ent 'this form':

!ThirdValue = !This.MyArray[3]
You can query the members of a form using the command:

q var !!formname

This will list all the attributes of the form, and all the gadgets defined on it. This is a useful debugging aid. To query all the gadgets of a form ( excludes USERDATA gadget) use:

!!gadgetsarray = !!MyForm.gadgets()

Returns array of GADGET.
 Forms are displayed on the screen either as free-s tanding forms or as a member of a form family. A form can be displayed as a free stan ding form, for example by show !!form free. It then has no parent so it will not disappea r when the form which caused it to be
displayed is hidden.

 When one form causes another form to be displayed,  such as when a button with the FORM keyword is pressed or a gadget callback execut es a show !!form command the result is a child form. A form can have many child forms ( and grand-children…) but a child form
has only one parent - the form which caused the chi ld form to be displayed. The nest of related forms is called a Form Family.

 The Form Family exists just as long as the forms a re displayed. If a form is already on the screen when it is shown, it is brought to the front  of the display. If the child form is already in a Form Family it is transferred to the new parent. If the user presses the OK button of a
parent form, the system in effect presses the OK bu ttons on each of the child forms, 'youngest' first, invoking their OKCALL callbacks. The parent form and all child-forms are hidden and the Form Family then ceases to exist. If  the user presses the CANCEL button or
uses the window's CLOSE controls, the system in effect presses the CANCEL buttons of each of the child forms, 'youngest' first, invoking  their CANCELALL callbacks, and all the forms in the Form Family are hidden. The action of RESET and APPLY buttons does not affect family members.


Loading and Showing Forms
 A form definition must be loaded before the form c an be displayed. If you have saved the definition in a .pmlfrm file then loading will be a utomatic when the form is displayed for the first time. Note: Earlier AppWare used form definit ions in macro files which had to be loaded explicitly via $m path-name.

This mechanism still operates for backwards compati bility, but is strongly discouraged when writing new AppWare. Normally, a form is displayed as a result of the operator making a menu selection or pressing a button on a form. This  is achieved either by using the Form
directive in the menu or button definition or by me ans of the command:

show !!formname

used in the gadget’s callback. In either case the f orm becomes a child of the menu’s or gadget’s owning form. A form may be displayed free- standing, i.e. not as a child, by:

show !!formname free

Sometimes it is useful to force the loading of a fo rm’s definition file before the form is actually displayed, so that you can edit the form or gadget attributes from another form’s callbacks before the form is actually displayed. Using the co mmand:

loadform !!formname

from a callback will force load the definition if t he form is unknown to PML, but do nothing if the form has already been loaded. If you are sure t hat a form’s definition has been loaded hen you can show the form as a child or free-stand ing respectively using the form methods:

!!formname.show( )
!!formname.show( ‘free’ )

but note that this will not dynamically load the fo rm definition.
 Mostly forms are automatically positioned by the s ystem according to their type and the way they are shown. The origin of a form is its top  left hand corner. When a form is displayed as a child form then it is always positioned with r espect to its parent. For a form shown from a MENU, its origin is at the origin of the parent. If the form is displayed from a BUTTON or any other gadget, its origin is at the centre of th e gadget. When a form is shown as a free form for the first time then its default position i s at the top left-hand corner of the screen. We strongly recommend that you allow the system to pos ition forms whenever possible.

You can force the screen position of free-standing forms using the following commands or
methods:

show !!MyForm Free At xr 0.3 yr 0.5
show !!MyForm Free Centred xr 0.5 yr 0.5
!!MyForm.show( 'At', 0.3, 0.5 )
!!MyForm.show( 'Cen', 0.5, 0.5 )


The At option puts the origin of the form at the specified position; alternatively the Cen option puts the centre of the form at the given position. The co-ordinate values are fractions of the screen width or height respectively and are referre d to as screen co-ordinates. For example :

show !!MyForm free At xr 0.25 yr 0.1

positions the origin of !!MyForm one quarter of the way across from the left edge of  the screen, and one tenth of the way down from the top.

!!MyForm.show( 'Cen', 0.5, 0.5 )

centres !!MyForm at the middle of the screen.
 The recommended way for a form to be removed from the screen is for the user to press a button with the OK or CANCEL attribute. Forms may  also be cancelled by using the window’s close controls. Both these mechanisms will  remove the form and any of its children
executing their OK or CANCEL
callbacks appropriately.

 Sometimes it is required to hide a form and other forms which are functionally associated but not part of the form family or as a result of a  button press on a form you may want to hide other associated forms but not the form whose butto n was pressed. The hide command or method allows this:

hide !!MyForm
!!MyForm.hide()

Note: When you explicitly hide a form in this way i ts gadgets will be reset to their values at display or at the last APPLY, just like a CANCEL ac tion, but the CANCELCALL callbacks for the form and its nest will not be applied. This mea ns that before youexecute the hide you
should use any pertinent data  from the forms to be  hidden. You can destroy a loaded form definition using the command kill !!MyForm

The form is hidden and then its definition is destr oyed so that it is then no longer known to PML. You cannot then access the form or its gadgets , members or methods (including its .show() method. Normally you will not need to inclu de the kill command within your
AppWare. If you re-show the form using the show com mand then the system will attempt to demand load the definition again. This is slow and expensive if you haven’t modified the definition so avoid it: use loadform !!MyForm and ! !MyForm.show() instead. If you execute a
setup form !!MyForm... while the form !!MyForm alre ady exists then it is killed and a new definition is started. This mechanism may be useful  because it makes it possible to generate a form definition interactively from within your Ap pWare. This can be very powerful but
should be used with great care.
 You can stop forms from being hidden from the bord er close/quit pull-down menu by setting the NOQUIT attribute:

Setup form !!MyForm . . . NOQUIT

By default, you can quit from any user-defined form , except for the current system Main
form.


Menus
 Menus are always members of forms but can be emplo yed in various ways by the form and its gadgets. Menus come in two types: main menu s and popup menus. You determine what type a menu is when you create it. If you do n ot specify the type, then the system will
try to infer its type from the context of its first  use.

For example, if the first action in a form definiti on is to define the menubar, then the system will infer any menus referenced in the bar…e xit sequence to be of type MAIN. Or, as a second example, if a menu is assigned as the popu p for the form or a gadget of the form,
then the system will infer the menu to be of type P OPUP.
 Forms may have a bar menu gadget or main menu, whi ch appears as a row of options across the top of the form. When you select one of the menu options, a pull-down menu is temporarily displayed. Fields on a menu may have pu ll-right arrows (>) that open a pulldown
sub-menu when selected. Forms and gadgets can have popup menus assigned to them.
When you move the cursor onto them and press the mo use popup button, the menu pops-up at the cursor and you can then select from the disp layed options. The following rules determine how you can use menus:

• Each menu belongs either to the Main menu system or to the Popup menu system, but cannot belong to both .
• A menu in the Main system can appear only once. i. e. it cannot be a sub-menu of several menus.
• A menu in the Popup system may appear only once in a given popup tree, but may be used in any number of popup trees.
• A menu cannot reference itself , either directly as a pullright of one of its own fields or be a pullright of another menu in its own menu tree .
• Any pullright field of a menu references a sub-men u that will be inferred to be of the same type as the referencing menu.
 A bar menu is defined within a form definition. Th e menu bar is created with the bar subcommand. Note that its name is ‘bar’: there can be only one bar menu on a form. Then you can use the bar’s Add() method to add the optio ns. For example:

setup form !!MyForm Dialog size 30 5
bar
!this.bar.add ( 'Choose', 'Menu1')
!this.bar.add ( 'Window', ' ' )
!this.bar.add ( 'Help', ' ' )
exit

This code specifies the text of three options label led Choose, Window, and Help.


• The Choose option when picked will open Menu1 as a  pull-down
• The Window and Help options will open the Window a nd Help system menus

Note:  That Menu1 need not exist when the bar is defined,  it can be defined later in the form definition, but it must exist before the Choose opt ion is selected or an error alert will be raised.
 A menu is a set of menu fields, each representing an action that is invoked when the field is selected. The fields’ display text indicates to the user what the actions are, and the fields’ replacement text defines what the actions are. With in the form definition a menu object can
be created using the form’s NewMenu method or the m enu sub-command. You can then use the menu’s Add(), InsertAfter(), and InsertBefore()  methods to add or insert named menu fields. A menu field can do one of three things:

• Execute a callback.
• Display a form.
• Display a sub-menu.

You can also add a visual separator between fields.  Below is an example of a complete menu definition:

!menu = !this.newmenu( 'file', ‘main’ )
!menu.add( 'MENU', 'Send to', 'SendList', 'SendTo' )
!menu.add( 'SEPARATOR', 'saveGroup' )
!menu.add( 'CALLBACK', 'Save', '!this.SaveFile()', 'Save' )
!menu.add( 'FORM', 'Save as...', 'SaveFile', 'SaveA s' )
!menu.add( 'SEPARATOR' )
--core-code managed field for Explorer Addin, ticke d.
--Note no Rtext needed
!menu.add( 'CORETOGGLE', 'Explorer', '', 'Expl' )
!menu.add( 'MENU', 'Pull-right1', 'Pull1')
--initialise toggle field as ticked (typically in t he
constructor)
!menu.SetField( 'Expl', 'Selected', true )

This creates a new main menu called Menu with six f ields and two separators between them. For example:

• The SAVE field when picked will execute the callba ck command this.SaveFile().
• The Save as... field when picked will load and dis play the form !!SaveFile. By convention, the text on a menu field leading to a f orm ends with three dots, which you must include with the text displayed for the fi eld.
• The SEPARATOR, usually a line, will appear after t he previous field.
• The Pull-right1 field when picked will display the  sub-menu !this.Pull1 to its right. A
• menu field leading to a sub-menu ends with a > sym bol: this is added automatically.
• Named Menu Fields

You can add menu fields with an optional fieldname that you can later refer to when editing the menufield or modifying its attributes’. If you do not specify a field name then you will not be able to refer to the field again. You can also a ssign a name to separator fields, which
allows separator group editing. The general syntax is:

!menu.Add( ‘<FieldType>’,’ <Dtext>’, ‘<Rtext>’, { ‘ <FieldName>’ } )
!menu.Add( ‘SEPARATOR’, { ‘<FieldName>’ })


Where the fields have the following meanings:

<FieldType>  has allowable values: ‘CALLBACK’, ‘TOGGLE’, ‘MENU’ , and ‘FORM’.
<Dtext>  is the display-text for the field (cannot be null or blank). May contain multi-byte characters.
<Rtext>  is the replacement-text for the field. A null stri ng indicates no replacement-text. The allowable values for RTEXT for the different field types are:

• CALLBACK’ - callback string
• TOGGLE’ - callback string
• MENU’ - menu name string (without preceding ‘.’).
• It cannot be blank.
• FORM’ - form name string (without preceding ‘!!’).  It
• cannot be blank.

<FieldName>  is an optional argument, which, if present, is the  unique field name within the menu.
You can add the system Window menu to a bar menu using:

!this.bar.add (‘<Dtext>’, ‘window’)

This menu is dynamically created on use with a list  of the titles of the windows currently displayed as its fields. Selecting a field will pop  that window to the front. This can be very useful on a cluttered screen.
You can add the system Help menu with the specified  display text to a bar menu using

!this.bar.add (‘Dtext’, ‘Help')
!this.bar.InsertAfter(‘window’, ‘<Dtext>’, ‘Help’)

When selected, this Help option displays a system-h elp pull-down menu that gives Access to the application help system. The fields are:

Contents  This displays the Help window so that you can find  the required topic from the hierarchical contents list.
Index  This displays the Help window with the Index tab s elected, so that you can browse for the topic you want to read about from the alphabeti cally-arranged list. You can locate topics quickly by typing in the first few letters of their  title.
Search  This displays the Help window with the Search tab at the front so that you can find all topics containing the keywords you specify.
About  To see the product version information.

You can access On Window help by pressing the F1 ke y while the form has keyboard focus, or by including a Help button in the form’s definition.

Note:  By convention, the help menu should be the last on e defined for the menu bar, which will ensure that it appears at the right-hand end o f the menu bar.
 You can use any of your defined menus as popup men us for most interactive gadgets and for the form background as long as you have spe cified them as belonging to the popup menu system. When the cursor is moved over it with the popup mouse button pressed down,


and then released, the menu will be displayed, and you can select from it in the normal way.
A popup is added to a gadget or form using its Setp opup() method, with the popup menu as the argument to the method. Note that the menu pop1  must exist when the Setpopup() method is executed. For example:

setup form !!MyForm resizable
  menu .pop1 popup
  !this.pop1.add( 'MENU', 'Options', 'optionmenu' )
  !this.pop1.add( 'MENU', 'More', 'moremenu' )
  !this.pop1.add( 'MENU', 'Last', 'Lastmenu'
  button .b1 ...
  !this.b1.setpopup( !this.pop1 )
exit
 You can find out whether a menu was popped up from  a gadget, and if so, the gadget’s name. The method is:

!menu.popupGadget() is GADGET

If the menu was a popup on a gadget then the return ed GADGET variable is a reference to the gadget. If the menu was popped up from a pulldo wn-menu or from a popup on the form itself, the value is UNSET. Example:

!g = !menu.popupGadget()
if !g.set() then
  !n = !g.name()
  $p menu popped up by gadget $!n
else
  !n = menu.owner().name()
  $p menu popped up by form $!n
endif
 A menu TOGGLE field is a menu field with a callbac k action and a tick-box to show that the field has been selected or unselected. By defau lt the field will be unselected so the box will not be ticked. When picked the fields callback  action will be executed and the tick-box
ticked. If you pick the field again the callback ac tion will again be executed and the tick removed. Note that the open callback is an obvious candidate for toggle menus as the SELECT or UNSELECT action is returned as the second  argument to the callback method.
For example, in your form definition you can add a toggle field as follows:

setup form !!Myform Dialog size 30 5
  !menu = !this.newmenu(‘Test’, ‘popup’)
  !menu.add( 'Toggle' ,’Active/Inactive’, '!this.to ggle(‘,'OnOff' )
Exit

define method .toggle( !menu IS MENU, !action IS ST RING )
  !name = !menu.fullname()
  !field = !menu.PickedFieldName
  $P menu $!name $!action field: $!field
Endmethod

Note: How we use the PickedFieldName member of the menu object to obtain the last picked field. If you pick this menu field the callb ack method will print:

menu !!MyForm.Menu1 SELECT field: OnOff


Editing Bars and Menus
 The contents of menu bars and menus can be modifie d at any time using the members and methods of the bar menu gadget object and the menu object.
 You can insert new fields into a menu bar using th e InsertBefore() and InsertAfter() methods, which insert the new fields relative to ex isting named menus. The methods use named menus to determine the point where they shoul d insert the new menu. The general syntax is:

InsertBefore(<TargetMenuName>, <Dtext>, <MenuName>)
InsertAfter(<TargetMenuName>, <Dtext>, <MenuName>)

Where the fields have the following meanings:

<TargetMenuName>  is the name of the menu immediately before or afte r where you want the new menu to go.
<Dtext>  is the display-text for the menu.
<FieldName>  is the unique name for the menu within the bar.

For example:

setup form !!MyForm Dialog size 30 5
  bar
  -- adds a pulldown for menu1 labelled with <dtext >
  !this.bar.Add( ‘<dtext>’, ‘menu1’ )
  -- adds a window pulldown labelled with <dtext>
  !this.bar.Add( ‘<dtext>’, ‘Window’ )
  -- adds a help pulldown labelled with <dtext>
  !bar.InsertAfter( ‘Window’, ‘<dtext>’, ‘Help’ )
Exit

 If you use the identifier ‘Window’ or ‘Help’ as th e name of the menu, the system will interpret them as system Window and Help menus, alt hough they will still be displayed with the string given in <dtext>. Named menus and the me thods that create them are discussed in more detail in the rest of this section.
You can insert new fields into a menu using the Ins ertBefore() and InsertAfter() methods, which insert the new fields relative to existing na med menu fields. The methods use named menu fields to determine the point where they shoul d insert the new field. The general
syntax is:

InsertBefore(<TargetFieldName>,<FieldType>,<Dtext>, <Rtext >,{<FieldName>})
InsertBefore(‘SEPARATOR’,{<FieldName>})
InsertAfter(<TargetFieldName>,<FieldType>,<Dtext>,< Rtext> ,{<FieldName>})
InsertAfter(‘SEPARATOR’,{<FieldName>})

Where the fields have the following meanings:

<TargetFieldName>  is the name of the field immediately before or aft er where you want the
new field to go.
<FieldType>  has allowable values: ‘CALLBACK’, ‘TOGGLE’, ‘MENU’ , and ‘FORM’.
<Dtext>  is the display-text for the field (cannot be null or blank). May contain multi-byte characters.


<Rtext>  is the replacement-text for the field. A null stri ng indicates no replacement-text. The allowable values for RTEXT for the different field types are:

• CALLBACK’ - callback string
• TOGGLE’ - callback string
• MENU’ - menu name string (without preceding ‘.’). It cann ot be blank.
• FORM’ - form name string (without preceding ‘!!’). It can not be blank.

<FieldName>  is an optional argument, which, if present, is the  unique field name within the menu.
 There are two methods you can use to set and read the status of menu- and menu-field properties. Setting Menu-Options’ Status You can de -activate a menufield on a menu bar and a field in a menu with the SetFieldProperty() s o that it cannot be selected. Similarly, you
can make them invisible so the user cannot see them . You can also use SetFieldProperty() to hide a menu field and to select or unselect togg le-type fields. The general syntax is:

!menu.SetFieldProperty (<FieldName>, <PropertyName> , Boolean)

Where the fields have the following meanings:

<FieldName>  The name of the field you want to change.
<PropertyName>  The name of the property you want to change in the  named field. The allowed values are:

• ACTIVE’ - greyed in or out
• VISIBLE’ - visible or invisible
• SELECTED’ - selected or unselected (toggle type fi elds, only. Specifically, this value cannot be used with bars).

Boolean  The value, TRUE or FALSE, for the property.

Note:  The property names may optionally be truncated to the first three characters ‘ACT’, ‘VIS’, and ‘SEL’. For example:

!bar = !!MyForm.bar
!menu = !!MyForm.Menu1

sets local variables !bar and !menu to be reference s to the bar gadget and Menu1 of form
!!MyForm.

Then

!bar.SetFieldProperty( 'Foo', ‘ACTive’, false)

will grey-out the menufield on bar that has the fie ld-name “Foo”. And

!menu.SetFieldProperty ( 'Bar', ‘ACTive’, true)

will activate the menufield on Menu1 that has the f ield-name “Bar”.

You can use the same method to change the selected status of a toggle menu field.


Reading the Status of Menus and Menus’ Fields
To read the status of a menu or of a menu-field pro perty, you can use the FieldProperty() method. The general syntax is:

Boolean = !menu.FieldProperty (<FieldName>, <Proper tyName>)

Where the fields have the following meanings:

<FieldName>  is the name of the field you want to change.
<PropertyName>  is the name of the property you want to change in the named field. The
allowed values are:

• ‘ACTIVE’ - greyed in or out
• VISIBLE’ - visible or invisible
• ‘SELECTED’ - selected or unselected (toggle type f ields, only. Specifically, this value
cannot be used with bars)

Note:  The property names may optionally be truncated to the first three characters ‘ACT’, ‘VIS’, and ‘SEL’. For example:

!bar = !!MyForm.bar

sets local variable !bar to be a reference to the b ar gadget of form !!MyForm.

Then

!isSet = !bar.FieldProperty( 'Foo', ‘ACT’)

will get the greyed-out status of the menufield on bar that has the field-name “Foo”. You can
use the same method to change the selected status o f a toggle menu field.
 A separator field and all following fields up to b ut not including the next separator field
implies a menu-field group. You can modify the ACTI VE and VISIBLE properties of all fields
in the group, by reference to its separator name. F or example, for the menu:

!menu = !this.newmenu( 'file', 'Main' )
!menu.add( 'MENU', 'Send to', 'SendList', 'SendTo' )
!menu.add( 'SEPARATOR', 'SaveGroup' )
!menu.add( 'CALLBACK', 'Save', '!this.SaveFile()',' Save' )
menu.add( 'FORM', 'Save as...', 'SaveFile', 'SaveAs ' )
!menu.add( 'SEPARATOR', 'explGroup' )
!menu.add( 'FORM', 'Explorer...', 'ExplFile', 'Expl ' )

<FieldName>  is the name of the field you want to change.
<PropertyName>  is the name of the property you want to change in the named field. The
allowed values are:

• ACTIVE’ - greyed in or out
• VISIBLE’ - visible or invisible
• SELECTED’ - selected or unselected (toggle type fi elds, only. Specifically, this value cannot be used with bars)


Executing the method

!menu.SetField( 'saveGroup', 'visible', false )

will make the all the fields invisible for the grou p currently implied by the separator field ‘SaveGroup’, i.e. the fields SaveGroup, Save and SaveAs.

The combination of named SEPARATOR fields, insertio n and field group visibility will be useful for managing the sharing of menus between co -operating sub-applications. This facility should be used with great care.
 You can create new menus from within your appware dynamically using the form method NewMenu(). For example, you could equip your form w ith the methods popupCreate() and popupAction() which would allow you create and serv ice a popup menu from an array of
strings. Executing !this.popupCreate(‘NewPopup’, !f ieldArray) will create a new popup menu and assign it to the form.

define method .popupCreate( !name is STRING, !field s is ARRAY )
  --!fields is an array of field name strings
  !menu = !this.newmenu( !name, ‘popup’ )
  --add all the fields with same open callback
  do !n from 1 to !fields.size()
    !menu.add( 'Callback', !fields[!n], '!this.menu Action(' )
  enddo
  -- assign the new menu as the form’s popup menu
  !this.setpopup( !menu )
endmethod

define method .popupAction( !menu is MENU, !action is STRING )
  -- General popup menu action routine
  if ( !action eq ‘SELECT’ ) then
    !name = !menu.fullname()
    !field = !menu.pickedField
    -- execute application actions according to the  field selected
    $P selected field $!field of menu $!name
  else
    -- execute applications for unselected field (t oggle)
  endif
endmethod


Form layout
The Form Layout section explains how to lay gadgets  out on a form.
 F&M supports a system font which provides the character representations used w ithin any forms, gadgets and menus which you define. This  system font has variable width characters (referred to as VarChars ), so different characters may have different widths.
A notional character width for the font is also supported. This is a sort of a verage width (usually the width of upper-case X), and provides a  rough guide to the width of a text string as (number of characters X notional width). The rec ommended system font also supports
many of the World's character sets, so forms can be  designed to use non-English characters, and even to mix different languages on the same form. In order to achieve this PML and F&M now use the Unicode standard as their internal character format.
 Two layout modes are supported, namely VarChars an d FixChars. VarChars is a new layout mode, based on measuring precise string widt hs. It is better suited to the use of variably spaced fonts, and removes the need for mos t 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 conjunctio n with TagWidth.
• No truncation of explicitly defined text except po ssibly in conjunction with TagWidth.

The recommended layout mode for all new forms is:

setup form !!formname . . . VarChars

 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 t he user has 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 f orm is FixChars, because this will be the least disruptive for existing user Appware, so FixC hars mode will currently result from either of

setup form !!formname . . .
setup form !!formname . . . FixChars

See the FMSYS object method

!!FMSYS.SetDefaultFormLayout(layout is STRING)

that allows users to change the default layout mode  for Setup form. This can be used to help est any existing appware which is using setup form  !!formname . . ., in either mode to determine which forms need layout adjustment.

Future Change to VarChars as Default Layout Mode
The intention is to change the recommended layout m ode to be VarChars at a subsequent
PDMS release. It is probable that this will be achi eved by introducing the alternative,
optional, form definition Syntax
Layout form !!<form_name> . . . exit
This will ensure VarChars mode (and NoAlign) by def ault.


Containers, Grid Co-ordinates and Gadget Boxes
 The Form and its Frame gadgets act as containers for holding gadgets. Typically gadgets are laid out in their containers from left to right and from top to bottom. Each container has a rectangular co-ordinate grid with origin (0, 0) at the top at the top left-hand corner. Each gadget has an origin at its top left-hand corner and a width and height , which together define a notional gadget box , which contains the gadget including its tag-text if defined. Layout involves positioning each gadget, b y its origin, at a specified position within the grid of its container and indicating its width and height.

• The grid horizontal pitch is the notional characte r width for the system font. Because this font is variably spaced, n horizontal grid units do not equate to n characters.
Generally, it is more than n unless the string has a high proportion of wide characters e.g. capitals, numerals, w's, m's etc. I t is important that you understand this concept when you specify gadget sizes.
• The grid vertical pitch is the line-height , which is the height of the tallest of the textual gadgets: TOGGLE, BUTTON, OPTION, TEXT or single-lin e PARAGRAPH.

For the Form container its extremities are referred to as XMIN form , YMIN form , XMAX form and YMAX form .

The extremities of a gadget box are referred to as XMIN.gadget , YMIN.gadget , XMAX.gadget an YMAX.gadget .

When new gadgets are added to a container, the XMAX and YMAX extremities grow to include the gadget boxes.


Positioning, Alignment and Size of Gadgets
 We strongly recommend that you lay out your form u sing auto-placement in combination with relative placement and use the NoAlign keyword.

Note: This is vital because it allows gadgets to be added , removed, and repositioned,
without having to adjust the geometry of all the ot her gadgets on the form.

Auto-placement chooses a gadget's position coordinate automaticall y relative to the last placed gadget.
Relative placement uses the AT syntax to specify a gadget's position c oordinate relative to a previously placed gadget.
NoAlign switches off the default approximate centre-alignme nt of the gadgets TEXT, OPTION, COMBO, TOGGLE and single line PARAGRAPH for  path right and path left, which interferes with Auto-placement.

A gadget's size component , width or height, is either a literal value, or a previous gadget's size component, or an extension to a previous gadge t's co-ordinate limit, i.e. min or max.
The last option, referred to as sizing to Positional Extent , uses the width to… and height to… syntax. This makes it much simpler to lay out compl ex and resizable forms.

The following example form demonstrates layout of a  simple, fixed size dialog form using the VarChars layout mode. Each gadget's position is set within t he gadget definition either, implicitly using auto-placement , or using the AT syntax. Gadget sizes are set implicitly, or
relative to the size of other gadgets or to the pos itional extents of other gadgets.

Note:  No actual co-ordinate positions are required to sp ecify this form. It is mostly undesirable and unnecessary to specify a gadget's p osition as absolute grid coordinates, e.g. at x 12, y 5; we recommend defining the layout  of each gadget relative to a predecessor.
This allows simple editing of the layout, without h aving to calculate new positions. There are exceptions, for example, for the first gadget in a form or frame, where you may want to establish an initial x or y co-ordinate that is not  at the default position.

Here is the corresponding PML code for the form: us ingVarChars.pmlfrm. The 'layout' keywords are emboldened and explained later in the chapter.


setup form !!usingVarChars dialog Varchars NoAlign
  $*-- layout form !!usingVarChars dialog
  title |Form !!usingVarChars|
  path down
  paragraph .para1 text 'Simple form layout using V arChars'
  frame .frame1 |frame1: See my gadgets|
    paragraph .para2 text 'text positioned implicit ly in frame1'
    frame .frame2 |frame2: path right|
      toggle .tog1 |BBC news 24|
      path right
      toggle .tog2 |BBC 1|
      toggle .tog3 |BBC 2|
      path down
      vdist 0
      frame .frame3 |frame3: path down, vdist 0| at  xmin.frame2 width to max.frame2
        -- path down, vdist 0 gives minimum vertica l spacing
        rtoggle .rad1 |ClassicFM| at xcen.frame3 - 0.5 * size
        rtoggle .rad2 |Caroline|
        rtoggle .rad3 |BBC Radio 2|
      exit
    exit
  exit
  button .cancel |CANCEL| at xmin form CANCEL
  path right
  button .ok |OK| at xmax form-size OK
exit
 Auto-placement uses the PATH , DISTANCE and ALIGNMENT commands, which have the following meanings:

• PATH The direction in which the next gadget origin will be placed relative to the previous gadget.
• DISTANCE The distance increment between gadgets along the cu rrent path.
• ALIGNMENT Specifies how the next gadget aligns to the previou s one for the current path.
Relative placement means specifying the new gadget position by reference to the extremities of a previously defined gadget. It is a lso possible to position gadgets using explicit form coordinates, but this is rarely neces sary.
 The path along which gadgets are to be added, is s et using a PATH attribute: Usually PATH right or PATH up, occasionally PATH left or PA TH down. The default direction is PATH right. The current path direction is set until  you give a different PATH command.
 To specify the horizontal and vertical displacemen t between adjacent gadgets, use the
HDISTANCE and VDISTANCE keywords, respectively. The  default displacements are
HDIST 0.2 grid units, VDIST 1.0 grid units. Note th at these specify clearance distances
between gadgets (for example, the distance between the XMAX of one gadget and the XMIN
of the next), not the distance between gadget origins, thus:


CABLE TRAY APPLICATION Configuration of tools

The Choose Options dialog box allows the configuration of component choices, as well as connection rules when they are created. It is possible to define a default component specification.The selected specification will then be recommended automatically when creating Cable Tray, Branch and Components.


CABLE TRAY APPLICATION Creation of cable path

CrCable Tray eation: Name of the cable path Specification Attributes Branch creation: Branch name Specification Attributes Attribute information window: Name Design Code Inspection Schedule Paint Schedule Tray Duty Material Reference FlUid Reference Case Reference Temperature Pressure etc...


CABLE TRAY APPLICATION Connections of the ends of branches

When creating a branch, it is possible to configureRer the Head and Tail connection points of this one These connections are managed manually, because unlike Piping, cable trays cannot be connected to nozzles Once one of the connections is configured, the branch appears dotted between the Head and the TailIt is also possible to connect the Head and Tail of a branch to cable tray components


CABLE TRAY APPLICATION Creation of components

Cable Tray Specicfication ChOix of Specifications Allows you to choose the specifications of the components to be created Creation/Re-selection mode of a component Choosing the type of elements to be created, Configuration of the direction of creation forward backward Position Modifications/position of a componentCreate Creating a component In the same way as in the Piping module it is possible to change the orientation and position of the components with the Model Editor Change Exit and Route Component allow the modification of inputs and outputs for multi-channel componentsThe Swap Branch function allows you to reverse multi-channel components The straight lengths of cable trays are automatically managed by AVEVA E3D In the majority of cases, the straight lengths are represented by a simple cylindrical volume representedFeeling the axis of the cable path The Fill With Straights and Remove Straights functions allow the automatic generation and deletion of straight sections whose maximum lengths are specified in the catalog Unlike cylindrical volumesBy default, whose length automatically adapts between 2 components, the sections are considered components in their own right and must be modified manually or regenerated


CABLE TRAY APPLICATION Nomenclatures and Isometrics

Piping pipe Isometrics The nomenclature of a cable path can be generated by a deferral From the bar ribbon, in the Piping discipline it is possible to edit an isometry and the nomenclature of a cable tray


This module allows the creation of HVAC parts AVEVA E3D allows you to create ventilation elements according to the following hierarchy model: HVAC BRANCH HVAC Components BEND STRAIGHT TRANSFORMATION... NOTE: The HVAC module is close to the Piping module. An HVAC element must contain a branch, it then has at least 2 ends, which are the Head and Tail of the branch. However, if he hasOf several branches, it can have more than 2 ends.


HVAC DESIGNER APPLICATION  Tool configurations

Create HVAC Create an HVAC System Element HVAC Main Branch Create a Main BRanch Element Choice of Specifications and name. Selection of the direction and dimensions of the Head Choice of the specification and thickness of heat insulation. Head Start: defined where the head will be positioned. NOTE: To define the dimensions of the HeAd, use the Picture icon...


HVAC DESIGNER APPLICATION  Creation of components

Categories Choose the category of components you want See chapter 2 4 for more informationAvailable Types Choose the type of components available in this category See chapter 2 4 for more information Once the category and type of elements have been selected A dialog box appears Fill in the dimensions (Attention this boIte differs depending on the category and type of element chosen)


HVAC DESIGNER APPLICATION  Library of available items

Here is the library of items available in the HVAC moduleHVAC rectangular HVAC Circular HVAC Shape Transformation HVAC Extra Equipment HVAC Nozzle Items HVAC Inline Plant Equipment HVAC Branch Connectors


AVEVA E3D is a software that uses databases Indeed, work on AVEVA E3D does not use a so-called "drawing" file such as AutoCAD Microstation or SolidWorks To better understand, AVEVA E3D organizes the elements created in baIts of data that are prioritized in the following way PROJECT (ex: FTN) MDB Multiple Data Base (ex: FTN ALL) DB(Database) MODEL in writing DB(Database) CATALOGUE in read-only DB(Database) DRAW in writing NOTE: There is pOther types of DB (Database), the same database can be attached to several MDBs (Multiple Database), and can be read-only or write-only for the user.


PRESENTATION OF AVEVA E3D   Starting the software

List and choice of project User name Password Choice of the MDB Stamp: Project backup choice Choice of E3D Model Draw Isodraft Spool Paragon module


PRESENTATION OF AVEVA E3D  User Interface

Quick Access Toolbar Ribbon Model Explorer 3D graphic view view Properties


AVEVA E3D THE HIERARCHY   Common hierarchy

Elements common to allAll the hierarchies (PIPES, STRUCTURES, EQUIPMENT,...) WORL Site Zone


AVEVA E3D THE HIERARCHY  Specific hierarchy (examples)

Zone EQUI SUBE Primitives ( BOX, CYLI, NOZZ ) PIPE BRAN Piping Components(VALV,ELBO,...) STRU FRMW SBFR STRUCTURAL Elements


This dialog box allows you to view the elements of the database, and to position yourselfR also in this one The blue highlighted current element, corresponds to the active element It is called by the initials CE Current Element Drag and drop Drag and drop allows you to take an object from the Model Explorer and display it in the 3D view Right click menuAtttibutes display the attributes Rename rename the current element Delete delete the current item Add CE To Current Collection add to Active collection Add CE Members to Current Collection add members of the current item to the active collectionNew Explorer display a new explorer for this item Copy copy eg Ctrl C Paste paste eg Ctrl +V  Add display in the graphic view Add Only display the item without its group Add Connected show the connected elements Add Supports show mediaAdd Supported Element display supported elements Add Within Volume display the elements in the volume Add Laser Within Volume display the laser in the volume Remove undisplay Remove Only Remove the item without its group Remove linked media Remove linked mediaHightlight highlight Unhightlight remove the highlight  Command Window Add this: adds the object in the 3D view Rem ce: remove the object in the 3D view Rem all: remove all objects in the 3D view  NOTE: It is essential to know how toEpérer in the database thanks to this browser. It allows you to position yourself well to create the elements.


LEFT CLICK Selection of an itemMIDDLE BUTTON Mollette Front/Rear: Zoom IN / OUT Button: Refocus view RIGHT CLICK Power Wheel NOTE: The right-click menu is only accessible in the background of the view.


Automatic representation: Enable by default this option allows the automatic management of the representation of the elements (transparency, edges) at their display Temporary representation: Allows you to manage the representation of future elementsDisplayed, these colors are only temporary, the undisplay of an element resets its representation


View Setting: CuRrent View Allows the configuration of 3D window options. Projection adjustment of the view perspective Rotate adjustment of the rotation mode Effects Choice of visual effects (Disable Shadows to optimize performance) Tools Display of graphic orientation aidsBackground Choice of the background color of the view Capping Choice of the color of the cutting sections Lighting Brightness adjustment Anti-alias Enable or disable anti aliasing The level allows you to determine the fineness of the trace of a diagonal line PRead the level is higher, the more powerful the computer's processor must be Point cloud Enable or disable the display of a point cloud NOTE: The Background color allows you to change the background color of the 3D view, it is important to put it inWhite when printing screens. "Graphics Drawlists" Allows the configuration of the graphical representation of the elements in the 3D window. Tube representation of pipes Centreline representation of piping axes Holes Drawn representation of holes (negative)Flange Bolts representation of flange holes Tracing representation of tracing (pipes) Insulation representation of heat retardants (pipes) Hvac Tube Translucendy HVAC 3D Display Management Obstruction representation of the volumes of obstructionsArc Tolerance precision of the representation of the arcs Level :(see the Equipment Application manual)


AVEVA E3D THE INTERFACE  Management of views

By default, only one graphic windowUe is active when the software is opened The items displayed in this window are listed in a drawlist collection It is possible to open several graphical windows, with drawlists that may be different Separate View CreatedEr an independent view with a drawlist different from that of the main view Cloned View Create a view identical to the main view but allowing a different orientation Local View Create a view whose drawlist content is the selection on the main viewNew Create an empty view with an independent drawlist Grid plane Create a grid


AVEVA E3D THE INTERFACE Selection of elements in the graphic view

Navigate to The Navig functionAte To Element allows the choice of primitives in the General Discipline, it does not work with the Model Editor. This function allows the selection of only one element (CE). Multiple selection: A multiple selection can be made with theA Ctrl key or by a selection rectangle with a left click The CE is not necessarily included in the selected elements Selection with left click It allows you to choose two selection options depending on the direction in which you create your selection rectangleSelection of the elements included entirely in the rectangle. Selection of all objects passing through the rectangle.


F1 Help F2 Left windowF3 Object snaping F4 Project Snap onto LCS F5 Walk mode F6 Fly mode F7 Show grid F8 Orthogonal lock F9 Grid snap F10 Polar tracking F11 Wired mode F12 Dynamic hints


Savework backup Getwork: recovery of the latest bases Undo / Redo: Cancel / Redo eq Ctrl + Z / Ctrl + Y) Discipline: Choice of discipline and associated tools NOTE: To add launch iconsNt quick function in the Quick Access Toolbar, just right-click on the tool to add and select Add to Quick Access Toolbar.


When hovering the mouse over the elements of the graphic view, it is possible to display a table of information relating to the element by pressing "shift"


When moving a window on the edges of the screen a location appears on the edges of the screen, to lock this position just let go of the left click


AVEVA E3D is a CAD software, based on a database The user acts on this database and E 3 D makes it a graphic interpretationThis implies a few simple rules 1 Each element is identified in the database thanks to a n called the Refno reference number 2 Each Name name given to an element must be unique 3 In the same hierarchy, the name of the parent owner is transmitted toThe child member Ex Equipment /EQUI 01 Under equipment /EQUI 01 /CHASSIS 4 All names begin with " / " (not visible in the Model Explorer) 5 " / " is used as the default separator (of a parent/child hierarchy) 6 The current element CE isUnique, there can only be one element chosen in the explorer 7 AVEVA E3D uses a graphical interface that allows the selection of several elements These elements then become a graphic selection neg À CE 8 A graphic group is a setWhich can be displayed or undisplayed independently The most common are the following EQUI Equipment Under Equipment SUBE Branch BRAN 9 The creation of SITES and generally ZONES are managed by the administrator


Home Attributes Each element of the database is determined by different attributes These attributes can be filled in directly by the user from the windowBe attribute, or through the creation and modification tools For example, a cylinder is determined by a Diameter attribute and a Height attribute Track CE Allows an automatic update of attributes on the CE It is possible to activateFilters on the attributes to facilitate reading in the Attributes window NOTE: The Q ATT command allows the display of the attributes of the current element in the command window Right-click menu in the dialog box Navigate To Navigate toThe target of the link that becomes CE Set Attribute Value to CE Fills the attribute by the name of the CE WRT Element Choice of repository Display P-Points Display of P-Points attributes (Primitive) Track CE Automatic window update Categorised/Alphabetical Sort attributes by category and alphabetical order Expand / Collapse Nodes Display of node attributes Modify / Category Filters Modify the display filters Manage Category Filters Management of filters by item Display standardD Attributes Displaying the main attributes Display UDAs Display of UDA (User Defined Attribtuts) attributes Display Pseudo attributes Display of pseudo attributes Columns Display of Columns Description and Data Type Settings Display of undefined attribute valuesExport to Excel Export attributes to Excel Print Preview Visualization before printing NOTE: UDAs are attributes created by the administrator. Some features are not usable with the Track CE function.


MANAGE So that an element of the database is not modified by 2 users at the same time, each user has his own Claimlist The Claimlist regrUpe all the elements whose write access is reserved for the user It updates automatically according to the elements created or modified by the user In the event that an item cannot be added to the user's claimlistEur, this one will appear highlighted in red during its selection