Elements from scripts

A script can find any element on an open screen and read or change any of its properties, animations, events and bindings. All of this works the same in the desktop HMI and the browser.

Finding an element

An element has a Name property in the editor. Scripts find it by that name, ignoring case.

var pump = Screen.Items("Pump1");

Way	Result
Item	The element whose event is running; null on screen events
Screen.Items("Name")	An element by name; a script error if missing
Screen.Find("Name")	An element by name or null
Screen.Items()	Array of top-level elements on all open screens
Screen.All()	Array of all elements, including nested ones
el.Children("Name")	A nested element of a group, genie or screen window
el.Children()	Array of nested elements; empty for a plain element
el.Parent	The parent, or null for a top-level element

Screen.Items and Screen.Find search pop-ups first, newest to oldest, then the main screen, including groups and genie instances. They do not look inside screen windows; use Children for those.

Arrays are ordinary JavaScript arrays:

var lamps = Screen.All().filter(function (e) { return e.Type === "Lamp"; });
lamps.forEach(function (lamp) { lamp.Visible = false; });

Genies

On a screen, a genie instance is a group named after the instance, with Type equal to Group. Names repeat across instances, so go through the parent:

Screen.Items("Pump1").Children("Lamp").Fill = "#3C9A5F";

Element information

Member	Description
.Name	Object name
.Id	Internal identifier
.Type	Type: Button, Lamp, Trend, Group… See the reference for all of them
.TypeTitle	Type title in Russian
.ScreenName	The screen holding the element
.Events	Array of event names with assigned actions

Properties

Every property in the properties panel reads and writes like an ordinary field. Names are English and case-insensitive. See the property reference for all names and allowed values.

Item.Fill = "#D32F2F";
Item.X = Item.X + 10;
Item.Text = "Fault";
Item.FontSize = 18;
Item.Alignment = "Center";

Methods do the same when the property name is in a variable:

var name = "Fill";
Item.Set(name, "#D32F2F");
var color = Item.Get(name);

Method	Description
.Get(name)	The configured value, ignoring animations
.Actual(name)	The value the operator sees now, including animations
.Set(name, value)	Write a property
.Has(name)	Whether the element has this property
.Properties()	An object with all properties: { Fill: "#111111", X: 10, … }
.Move(x, y)	Move
.Resize(width, height)	Resize; a group resizes with its contents

Values are checked:

Property kind	What to pass
Colour	"#RRGGBB" or "#AARRGGBB"
Number, integer	A number or numeric text
Flag	true / false
Choice	The option’s name, case-insensitive: "Center"
Tag, screen, text list	The name of a project object

Writing an unsuitable value or an unknown property is a script error with a clear message. Reading an unknown property returns null; check Has first if needed.

Items on a symbolic field

A symbolic field has its own Items property, which plain el.Items refers to. Nested elements are always reached through Children.

Visibility and control

Member	Read/write	Description
.Visible	Yes	The script’s decision to show the element
.Enabled	Yes	The script’s decision to allow control
.IsShown	Read only	Whether it is visible now, including the Visibility animation
.IsOperable	Read only	Whether it can be operated now, including the Enable animation

An element is visible only if both the script and the animation allow it. Control works the same way, and the Operator right property also applies.

Screen.Items("StartButton").Enabled = Tags("Line.Ready").Value === true;

This only affects operator actions. A script can still call an event through Raise or write a tag, and the server always checks permissions itself, so Enabled does not replace permissions or tag protection.

The element’s tag value

If an element has a Tag property (value, lamp, bar, slider, switch, gauge and others):

Member	Description
.Tag	Tag name; change it and the element reconnects
.Value	The tag’s value; writes go to the tag after the script, with permission checks
.Quality	Value quality

var field = Screen.Items("Setpoint");
field.Value = 2.5;
field.Tag = "Tank2.Setpoint";  // the same element now shows another tag

Using .Value on an element without a tag is an error. On the value change event, .Value may still hold the old value, as the new one arrives from the server by subscription.

Animations, events and everything else

Some settings are not in the properties panel: animations, dynamics, events, trend pens and table rows. For those, use the element’s full configuration.

Member	Description
.Config	A copy of the full configuration as a JavaScript object, as in the screen file
.Apply(fields)	Overlay fields on the configuration

Apply changes only the top-level fields you pass. A null value removes a field. type cannot be changed, id is ignored, and a group’s contents change through elements from Children. An unknown field is an error.

To see how a particular element is configured:

HMI.ShowMessage(JSON.stringify(Item.Config, null, 2));

Field names start with a lowercase letter (fill, penList), while event and property names inside events and dynamics stay as they are (Click, Fill).

Events

Item.Apply({
  events: {
    Click: { script: "HMI.ShowMessage('Clicked: ' + Item.Name);" },
    DoubleClick: { functions: [{ function: "ShowTrend", args: { Tag: "Tank1.Level" } }] }
  }
});

The events field is replaced as a whole. To add one event to the existing ones:

var events = Item.Config.events || {};
events.RightClick = { script: "HMI.SysFct('ShowAlarms');" };
Item.Apply({ events: events });

Event names: Click, DoubleClick, LeftDown, LeftUp, RightClick, RightDown, RightUp, MouseEnter, MouseLeave, Change, Activate, Deactivate, KeyDown, KeyUp.

To fire an element’s event from code:

Screen.Items("StartButton").Raise("Click");

Its actions run after the current script.

Animations

Item.Apply({
  animations: {
    appearance: {
      tag: "Pump1.State",
      type: "Range",
      rows: [
        { range: "0", background: "#F2F3F4" },
        { range: "1", background: "#3C9A5F" },
        { range: ">=2", background: "#D32F2F", flashing: true }
      ]
    },
    visibility: { tag: "Line.ShowPump", type: "SingleBit" }
  }
});

Item.Apply({ animations: null });   // remove all animations

Property bindings

var dynamics = Item.Config.dynamics || {};
dynamics.Rotation = { kind: "Linear", tag: "Valve1.Pos", inMin: 0, inMax: 100, outMin: 0, outMax: 90 };
delete dynamics.Fill;
Item.Apply({ dynamics: dynamics });

Trend pens

Screen.Items("Trend1").Apply({
  penList: [
    { tag: "Tank1.Level", color: "#2F6FB0" },
    { tag: "Tank1.Pressure", color: "#D32F2F" }
  ]
});

Which wins: script or animation

A script changes the element’s configuration. Animations and tag bindings apply on top of it at every tag update.

Item.Fill = "#D32F2F";
Item.Get("Fill");     // "#D32F2F"
Item.Actual("Fill");  // the animation's colour, if it controls the fill

If a colour does not change, an animation controls it. Remove it with Apply.

How long changes last

• Changes last while the client is open and apply only to that client. The project and other operators do not see them.
• They survive moving to another screen and back.
• A genie pop-up is created each time it opens, so changes inside it disappear when it closes.
• After signing out and back in, the screen is as defined in the project.

To restore the project configuration without restarting:

Method	What it does
.Reset()	Undoes changes to the element and its nested elements, including Visible and Enabled
Screen.Reset()	The same for all open screens

Recreating an element

Reload() recreates an element: a data table re-runs its query and a trend reloads history.

Screen.Items("OrdersTable").Reload();

Changing a tag or screen and calling Apply recreate the element automatically. Ordinary properties (colour, text, position) do not, so they are safe to change right on a button press.

The Screen object

Member	Description
Screen.Name	Main screen name
Screen.Title	Main screen title
Screen.Width, Screen.Height	Size in design coordinates
Screen.Background	Background colour
Screen.Names()	Array of open screen names: the main screen and pop-ups
Screen.Items(), Screen.Items(name), Screen.Find(name), Screen.All()	Finding elements
Screen.Reset()	Restore the project configuration

Open and close screens with HMI.ActivateScreen and HMI.SysFct.