Skip to content

Screen API reference

A reference of every object available to scripts on the operator screen. Working with screen elements (Screen, Item) is covered in depth in Elements from scripts; this page gives a summary.

Returns a tag object by name. Matching is case-insensitive and surrounding spaces are ignored, but write the name as in the tag table for readability. If the tag does not exist, the script fails with “Tag … not found”.

const level = Tags("Tank1.Level");

The tag name, a string.

The last value the client received through its subscription.

Tag type What .Value returns
Bool true or false
Byte, Int16, UInt16, Int32, UInt32 A number
Float32, Float64 A number
String A string
No value yet null

A scaled tag’s value is in engineering units, not the PLC’s raw units.

After communication is lost, .Value returns the last known value, not null. When a command depends on the value, check .Quality.

Same as .Value, for when a method call reads better:

if (Tags("Pump1.Fault").Read()) return;

Value quality, a string:

Value Meaning
Good The value is reliable
Uncertain There is a value, but the source does not guarantee it (OPC UA)
Bad Communication works, but the PLC refused the read: missing block, out of range
CommFailure No communication with the device
ConfigError Tag configuration error: address or type
NoData The tag has never been read yet
const t = Tags("Tank1.Level");
if (t.Quality !== "Good") {
HMI.ShowMessage(`Level is not reliable: ${t.Quality}`);
return;
}

Writes a value after the script ends. The value is converted to the tag type:

Passed Bool tag Integer tag Real or scaled tag String tag
true / false As is 1 / 0 1 / 0 "true" / "false"
A number 0 is false, anything else true Rounded to an integer, range-checked As is The number as text
A string 1, true or 0, false (Russian words also accepted) An integer as text A number as text, comma or point As is
null Error Error Error Error

Rounding goes to the nearest integer, with halves going to the even number: 2.5 gives 2 and 3.5 gives 4. If a number does not fit the tag type, such as 70000 for Int16, the script fails with “Allowed from … to …”.

Permissions are checked against the user’s role and the tag’s write protection (operator, engineer, read-only). Without permission, the operator sees a message and the script’s remaining actions are skipped.

An object with client functions.

The signed-in user’s name, a string.

Tags("Shift.Operator").Write(HMI.User);

Opens a project screen after the script ends. If the screen does not exist, the operator sees an error.

Shows a message window immediately. Any value is converted to a string.

HMI.ShowMessage(JSON.stringify({ level: Tags("Tank1.Level").Value }));

Asks the operator a yes/no question and returns true or false.

if (!HMI.Confirm("Stop the line?")) return;
Tags("Line.Stop").Write(true);

In the desktop program, the script waits for the answer. A browser cannot wait like that, so there the script is interrupted at the question and, after the answer, runs again from the start, with HMI.Confirm returning the known answer at once. As a result:

  • writes and messages made before the question are not repeated;
  • ordinary code before the question runs again.

So ask questions at the start of a script and do not change module globals before them.

Returns the text from a project text list for a number. If the list does not exist, the script fails.

Item.Text = HMI.TextList("Modes", Tags("Line.Mode").Value);

Calls a server script function after the client script ends. Requires the Operate permission. The argument is optional and passed as a string. If the function fails on the server, the operator sees a message.

HMI.RunServerScript("startSequence", String(Tags("Recipe.Selected").Value));

Runs any system function after the script ends. Parameters are passed in order, as in the table below. Trailing optional parameters can be omitted, and null skips a parameter in the middle.

HMI.SysFct("IncreaseValue", "Tank1.Setpoint", 0.5, 10);
HMI.SysFct("ShowPopupScreen", "TankDetails", null, null); // centred
HMI.SysFct("ShowGeniePopup", "PumpControl", "Tag=Pump1; Title=Pump 1");
Function Parameters in order
ActivateScreen Screen
ActivatePreviousScreen —
ActivateHomeScreen —
ShowPopupScreen Screen, X?, Y?
ShowGeniePopup Genie, Substitutions?, Title?
ClosePopup —
ShowAlarms —
ShowAlarmJournal —
ShowTrend Tag
ShowTrendGroup Group
ShowTagOverview —
SetBit, ResetBit, InvertBit Tag
SetBitInTag, ResetBitInTag, InvertBitInTag Tag, Bit
SetValue Tag, Value
IncreaseValue, DecreaseValue Tag, Step = 1, Limit?
InputValue Tag
CopyValue Target, Source
LinearScaling, InvertLinearScaling Target, Source, X1, X2, Y1, Y2
ShiftAndMask Target, Source, Shift = 0, Mask = 65535
AcknowledgeAllAlarms —
AcknowledgeAlarm Alarm
ShowLogonDialog, Logoff, ChangePassword —
ShowMessage Text
PrintScreen, ToggleFullScreen, Beep, StopRuntime —
RunScript Function, Argument?
RunServerScript Function, Argument?

Do not call SetBitWhileKeyPressed from a script: it works together with a button release event. See Events and functions for what each function does.

Open screens and element lookup.

Member Description
Screen.Name, Screen.Title Main screen name and title
Screen.Width, Screen.Height, Screen.Background Main screen size and background
Screen.Names() Array of open screen names
Screen.Items(name) An element by name; an error if missing
Screen.Find(name) An element by name or null
Screen.Items() Top-level elements of all open screens
Screen.All() All elements, including nested ones
Screen.Reset() Undo every change scripts made

The element whose event is running, or null. It has the same members as an element from Screen.Items:

Group Members
Information Name, Id, Type, TypeTitle, ScreenName, Events, Parent
Properties Any property as a field (Item.Fill), Get, Set, Has, Actual, Properties()
Position Move(x, y), Resize(w, h)
State Visible, Enabled, IsShown, IsOperable
Tag Tag, Value, Quality
Configuration Config, Apply(fields)
Actions Raise(event), Reload(), Reset(), Children(), Children(name)

See Elements from scripts for details and examples, and the property reference for each element’s properties.