2/10/12

TGML Scripting

Welcome TAC-MAI

User profile
Sea ch

Click to rate and give feedback

Home

Product version

Concept
Functionalit

1.1

Language

Privileged
Products: Graphics Editor

Functionalities: Graphics

Product v ersion: 1.0, 1.1

7/28/2011

English

Products
How to
Tutorials

TGML Scripting
Script Elem ent: Script
Target Area Elem ent: TargetArea

Developers Reference

TGML supports the script language JavaScript 1.5. A JavaScript editor is available in Graphics Editor. You can use the
JavaScript edtor to access the elements and their attributes in View mode. The script engine does not run in Edit mode.

Getting help

The DOM (the elements and their attributes) is accesed using DOM methods such as getCurrentTarget ,
getAttribute , and setAttribute .

Downloads

Apart from accessing the DOM, it is also possible to interact w ith the TGML View er, and thus the underlying system, using
StruxureWare-specific JavaScript functions such as setValue and e ecute .

Troubleshooting

The execution of the scripts is event driven. Event attributes are used to specify the event and a function name. The
function is executed in View mode w hen the specified event is raised.

Script Element: Script

Communit

Script defines a script block that belongs to the immediate parent element.

Target Area Element: TargetArea

TargetArea represents a clickable area in a graphic. Target area is not painted, that is, it is alw ays invisible.

Global Variables
Variables declared outside the Java script functions are global w ithin the script block. The global variables exist w hile the
TGML document is displayed (executed) in Dynamic mode.
The global variables can only be accessed by the functions that are defined in the same script block.

About Data T pes

Java script variables are untyped. If you, for example, use global variables or custom attributes to store numeric values:
Convert the variables to a Number.

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

1/8

2/10/12

TGML Scripting

TGML code w ith an example of how you can convert a varible to a number

Common Event Methods

Method

Description

getCurrentTarget() Returns the element the Script belongs to. That is, the EventTarget w hose EventListeners are
currently being processed.
getTarget()

Returns the element to w hich the event w as originally dispatched. For example, the element you
clicked.

preventDefault()

If the event is cancelable, preventDefault cancels the default action normally taken by the
implementation, for example, the view er.

stopPropagation

Prevents further propagation of an event.

When an element contains Bind or Link, the view er is supposed to respond w hen the user clicks the element. The view er is
supposed to respond by show ing a change value dialog box or opening the linked presentation object. This is the view er
default action that is canceled by the preventDefault function.
preventDefault in an OnMouseClick function cancels the change value dialog box (w hen the element contains a Bind) or the
link function (w hen the element contains a Link).
preventDefault in an OnSignalChange function cancels the error indication indicated by a red cross.

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

2/8

2/10/12

TGML Scripting

TGML code w ith a scipts containing getTarget() and getCurrentTarget() methods

Mouse Event Methods

Method

Description

getButton()

Returns an integer describing w hich button w as pressed or released. Applicable for

MouseDow nEvent and MouseUpEvent.
0 = Left button, 1 = Middle button, and 2 = Right button.

getClientX()

Returns the X coordinate of the cursor, relative the origin of the target coordinate system.
The coordinate is calculated using the transformations of the target element.

getClientY()

Returns the Y coordinate of the cursor, relative the origin of the target coordinate system.
The coordinate is calculated using the transformations of the target element.

getCurrentTargetX()

Returns the X coordinate of the cursor, relative the origin of the current target coordinate
system.
The coordinate is calculated using the transformations of the current target element

getCurrentTargetY()

Returns the Y coordinate of the cursor, relative the origin of the current target coordinate
system.
The coordinate is calculated using the transformations of the current target element.

getCurrentTargetParentX()

Returns the X coordinate of the cursor, relative the origin of the current target's parent
coordinate system.
The coordinate is calculated using the transformations of the current target's parent.

getCurrentTargetParentY() Returns the Y coordinate of the cursor, relative the origin of the current target's parent
coordinate system.
The coordinate is calculated using the transformations of the current target's parent.
getScreenX()

Returns the X coordinate of the cursor, relative to the origin of the document coordinate
system.

getScreenY()

Returns the Y coordinate of the cursor, relative to the origin of the document coordinate
system.

SignalChange Event Methods

Method

Description

getStatus()

Returns the status of the signal:

0: Error (Bad quality)
1: Stored value (Uncertain quality)
2: Real value (Good quality).3: Forced value (Good quality)

getPresentationValue()

Returns the value of the bound signal as a presentation value.

getUnit()

Returns the unit of the bound signal as a string.

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

3/8

2/10/12

TGML Scripting
getValue()

Returns the value of the bound signal.

TGML DOM Methods

Object

Mehtod

Any
getChild
element (" name ")

Description
Returns the immediate child element that has the Name attribute w ith the given value. If no
such child exists, this returns null. If more than one immediate child element has a Name
attribute w ith that value, w hat is returned is undefined.

Any
getChildRecursive Returns the child element at any level that has the Name attribute w ith the given value. If no
element (" name ")
such element exists, this returns null. If more than one element has a Name attribute w ith that
value, w hat is returned is undefined.
Any
getFullBindName() Returns the exposed name of the Bind or Link element, including names of parent
element
components.

TGML code w ith a script containing a getFullBindName() method

Standard DOM Methods

These standard methods are commonly used. For more information, see he W3C Doc men Objec Model (DOM), Le el 3
Co e Specifica ion . .
Object

Method

Description

Any
element

getAttribute(" attribute ")

Returns the value of attribute

Any
element

getChildNodes()

Returns a NodeList that contains all children of this node

Any
element

getOw nerDocument()

Returns the document

Any
element

getParentNode()

Returns the parent element

Any
element

getTagName()

Returns the element tag name, e.g. Rectangle or Bind

Any
element

setAttribute(" attribute ",

" value ")

Sets the value of attribute to value . If the element does not have the attribute, it
is created as a TGML custom attribute.

Document getDocumentElement()

Returns the TGML (root) element

Document getElementById(" Id ")

Returns the child element that has the Id attribute w ith the given value

Document getElementsByTagName
(" tagName ")

Returns a NodeList of all the elements in document order w ith a given tag name

NodeList

getLength()

Returns the number of elements in the NodeList

NodeList

item(" index ")

Returns the element at index in the NodeList

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

4/8

2/10/12

TGML Scripting

TGML code w ith a script containing getAttribute() and setAttribute() methods

TGML JavaScript Functions

Method

Description

alert("<messages>")

Displays a message box

clearInterval(intervalID)

Cancels the previously started interval using the setInterval function.

intervalID is an identifier returned by a previous call to the setInterval function.

clearTimeout(timeoutID)

Cancels a time-out that w as set w ith the setTimeout function.

timeoutID is an identifier returned by a previous call to the setTimeout function.

confirm("<message>")

Displays a confirm box w ith "Yes" and "No" buttons.

Returns true if the user clicks "Yes" or false if the user clicks "No".

execute("<commande>"),
execute("<command>", "
<options>")

Requests an execute operation to be performed by the TGML view er (start a Window s

program).
command is the name of the program (full path) and options is the command line options.
Returns true if succeeded or false if failed.
Note: The implementation of this function is system dependent. May not be implemented in
some systems.

invoke("<bindingName>", "
<operation>")

Requests an operation to be performed on a bound object by the TGML view er. The
bindingName is the full name (as it is exposed to the binding tools) of a Bind or Link
element.
Returns true if succeeded or false if failed.
Note: The implementation of this function is system dependent. May not be implemented in
some systems.

openFile("<path>", "
<operation>")

Request the TGML view er to open a file. The operation is typical Window s object verbs.
Returns true if succeeded or false if failed.
Note: The implementation of this function is system dependent. May not be implemented in
some systems.

prompt("<message>", "
<defaultValue>")

Prompts the user to enter a value.

setForce("<bindingName>", "
<true|false>")|

Sets the force state of a bound signal object. The bindingName is the full name (as it is
exposed to the binding tools) of a Bind element.

Returns the entered value or null if canceled.

Returns true if succeeded or false if failed.

Note: The implementation of this function is system dependent. May not be implemented in

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

5/8

2/10/12

TGML Scripting
some systems.
setInterval("<expression>", "
<milliseconds>")

Evaluates (executes) the expression each time the specified number of milliseconds has
elapsed.
Returns an identifier that cancels the timer w ith the clearTimeout method.

setTimeout("<expression>", "
<milliseconds>")

Evaluates (executes) the expression after the specified number of milliseconds has
elapsed.
Returns an identifier that cancels the timer w ith the clearInterval method.

setValue("<bindingName>", "
<value>")

Sets the value of a bound signal object. The bindingName is the full name (as it is exposed
to the binding tools) of a Bind element.
Returns true if succeeded or false if failed.
Note: The implementation of this function is system dependent. May not be implemented in
some systems.

TGML code containing a rectangle that toggles a value

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

6/8

2/10/12

TGML Scripting

Rectangle that toggles a value on screen

TGML code that starts an interval timer and animates (toggles) the fill color w hen the pointer is placed over the rectangle.
The timer is stopped and the color is restored w hen the pointer is moved from the rectangle.

TGML code w here an alert box is displayed w hen the pointer is held over the rectangle for one second. The timer is stopped
w ehn the pointer is moved from the rectangle.

JavaScript 1.5
For more information, see ECMASc ip Lang age Specifica ion, Re . 3. .

See Also
TGML Script Element: Script
TGML Target Area Element:
TGML Signal Binding:

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

7/8

2/10/12

TGML Scripting

Communit Content
Add new content

2011 Schneider Electric Buildings AB |

help.struxureware.schneider-electric.com/Topics/show.castle?id=5716&locale=en-US&productversio

Terms of Serv ice

8/8