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.
Tags(name)
Section titled “Tags(name)”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.
.Value
Section titled “.Value”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.
.Read()
Section titled “.Read()”Same as .Value, for when a method call reads better:
if (Tags("Pump1.Fault").Read()) return;.Quality
Section titled “.Quality”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;}.Write(value)
Section titled “.Write(value)”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.
HMI.User
Section titled “HMI.User”The signed-in user’s name, a string.
Tags("Shift.Operator").Write(HMI.User);HMI.ActivateScreen(name)
Section titled “HMI.ActivateScreen(name)”Opens a project screen after the script ends. If the screen does not exist, the operator sees an error.
HMI.ShowMessage(text)
Section titled “HMI.ShowMessage(text)”Shows a message window immediately. Any value is converted to a string.
HMI.ShowMessage(JSON.stringify({ level: Tags("Tank1.Level").Value }));HMI.Confirm(question)
Section titled “HMI.Confirm(question)”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.
HMI.TextList(list, value)
Section titled “HMI.TextList(list, value)”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);HMI.RunServerScript(function, argument)
Section titled “HMI.RunServerScript(function, argument)”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));HMI.SysFct(name, …args)
Section titled “HMI.SysFct(name, …args)”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); // centredHMI.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.
Screen
Section titled “Screen”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.