WinCC Scripting: Change Text and Captions via VBS and Dialog

Overview

WinCC exposes two complementary paths for animating an HMI object's text at runtime: a declarative path through the Dynamic Dialog editor (no scripting required) and an imperative path through VBS actions or C actions. Engineers migrating from iFIX expect every property to be reachable from VBA via a single object model. In WinCC, the picture-tree object model exists, but tag bindings and property names are spelled differently, and the runtime contexts (WinCC 7.x RT, WinCC RT Professional, WinCC Unified) each carry their own scripting surface. This reference covers the four practical ways to change a Static Text, Button, or IO field caption inside a group or faceplate, and how to verify the result before handover.

Prerequisites

• SIMATIC WinCC 7.5 SP2 or higher, OR WinCC RT Professional V16/V17, OR WinCC Unified V17/V18/V19/V20 in TIA Portal.
• Configured HMI device with a tag (Boolean, integer, or string) exposed to the HMI.
• Project picture (PDL) with the target text/IO field placed and named.
• For VBS actions: Project documentation window enabled in Graphics Designer (View → Project Documentation).
• For WinCC Unified scripting: read access to SCADAProjects for the UmclService account (see Siemens KB 109805541).

iFIX to WinCC: Property Mapping Cheat Sheet

Before any code is written, build a porting map. The iFIX VBA model and the WinCC object model are not one-to-one. A compact mapping table prevents the most common script errors:

WinCC Object Model: Groups, Faceplates, and Picture Windows

Three containers matter when scripting text changes in WinCC:

The group in WinCC is a flat container. The items inside it (for example Static Text 1, IO Field 1) remain siblings on the picture, not children of the group. To target a Static Text inside Group1 by name, reference it through the picture's ScreenItems collection using its full Object Name as shown in the Graphics Designer properties (Static Text → Object Name). The default name is Static Text 1; rename it to start to match a legacy iFIX tag.

Method 1: Declarative Text Switch with Dynamic Dialog

Use the Dynamic Dialog when the text must change based on one or two tags with discrete states. It compiles into a C action and is faster than VBS for purely tag-driven animations.

1. In Graphics Designer, right-click the Static Text object and select Properties.
2. In the left column, expand Static Text and select Font.
3. In the right column, right-click the light bulb next to Text and choose Dynamic Dialog.
4. Set Data Type to Boolean (or Analog for a multi-state mapping).
5. In the Expression Formula field, browse to your tag, e.g. MyTag.PV or HMI_Tag_1.
6. Type the two result strings - for example "Alarm horn enabled" for True and "Alarm horn disabled" for False.
7. Click Apply and acknowledge the security prompt about replacing the static text.

Method 2: VBS Action in Classic WinCC (WinCC 7.x / RT Professional)

VBS is the closest analogue to iFIX VBA. The runtime exposes a top-level HMIRuntime object plus a per-screen ScreenItems collection. Inside a button click event, you can write:

Sub OnClick(ByVal Item)
    Dim objBtn
    Set objBtn = ScreenItems("bt_Bed4")
    Dim objGroupText
    Set objGroupText = ScreenItems("Group1").ScreenItems("start")

    If HMIRuntime.Tags("AlarmHornActive").Read = 1 Then
        objBtn.Text = "Alarm horn enable"
        objGroupText.Text = "Horn: ON"
    Else
        objBtn.Text = "Alarm horn disable"
        objGroupText.Text = "Horn: OFF"
    End If
End Sub

Key behavioural points:

• ScreenItems(...) takes the Object Name property, not the layer label. Rename the text field from Static Text 1 to start in the properties dialog before scripting.
• The Text property of a button is writable. The Caption property used in iFIX does not exist on WinCC objects; map Caption → Text in your porting checklist.
• Group1.ScreenItems("start") works only if the object is exposed at the picture level. If Graphics Designer placed it as a private sub-object, right-click the group, choose Customize → Properties, and enable Operable + Visible in the Miscellaneous tab.
• For IO Field objects, the displayed string lives in OutputValue and the user-entered string lives in InputValue. Use .Text only to set the label shown next to the field.
• Tag access is asynchronous - always call .Read first and use the returned variant; do not read directly from Tags(...).Value inside tight loops.

VBS Inside a Picture Window (Faceplate)

When the target object lives inside a Picture Window, address the embedded picture through the parent:

Dim pw
Set pw = ScreenItems("PicWin1")
pw.PictureName = "PID_FacePlate.pdl"
pw.Visible = True
pw.Screen.ScreenItems("start").Text = "Loop 1 running"

Method 3: VBS in WinCC Unified (TIA Portal V16-V20)

WinCC Unified replaces the HMIRuntime and ScreenItems model with a typed item model accessed through the screen object. The closest port of the iFIX snippet is:

export function btn_Bed4_OnClick(item) {
    let tagValue = Tags("AlarmHornActive").Read();
    let btn = Screen.FindItem("bt_Bed4");
    let txt = Screen.FindItem("Group1.start");
    if (tagValue === 1) {
        btn.Text = "Alarm horn enable";
        txt.Text = "Horn: ON";
    } else {
        btn.Text = "Alarm horn disable";
        txt.Text = "Horn: OFF";
    }
}

Differences from classic WinCC:

• Functions are export-ed and use camelCase, e.g. OnClick, OnPropertyChanged, OnMouseUp.
• Screen.FindItem("Group1.start") uses dot-notation to reach items inside a group; Screen.Items() returns a flat collection including groups, but you still need the relative path for sub-items.
• Tag access is synchronous in the runtime API: Tags("MyTag").Read() returns a value and accepts an optional quality argument.
• For faceplate internals, only the configured interface properties are addressable from outside; use Screen.FindItem("FaceplateInstance.MyProperty") to read/write them.

Method 4: C Action for High-Performance Tag-Driven Text

When a text change must happen on every cycle (e.g. a position readout updated every 100 ms) and the source is purely a tag value, a C action is the most efficient option. It compiles to native code and avoids the VBS interpreter overhead.

{
    char szText[64];
    DWORD dwPos = GetTagDWord("Axis1.ActPos");
    sprintf(szText, "Position: %lu mm", dwPos);
    SetPropChar(lpszPictureName, "txtPosition", "Text", szText);
}

The function SetPropChar takes PictureName, ObjectName, PropertyName, Value and is the only supported way to push a string into a property from a C action. Use it for read-only displays; for two-way bindings, use tag connections instead.

Building a Reusable Faceplate with Picture Window

For multi-instance faceplates in classic WinCC, the Picture Window remains the lowest-friction container.

1. Create a new PDL (e.g. PID_FacePlate.pdl) containing the labels, IO fields, and bar graphs that make up the regulator view.
2. On the base picture, drop a Picture Window from the Smart Objects library.
3. In the Miscellaneous properties, set Picture Name to PID_FacePlate.pdl. Enable Sizable, Movable, Can be Maximized, and Can be Closed as required.
4. Add a button on the base picture whose click event toggles ScreenItems("PicWin1").Visible.
5. To display the same faceplate for many loops, copy the Picture Window, give each instance a unique Object Name, and parameterize the tag prefix through a structure tag passed at the instance level (WinCC 7.4+ supports multi-instance tag prefixes via the Picture Window's Tag Prefix property).
6. Compile, download, and run RT. Verify that each instance reacts to its own tag set.

Common Errors and Troubleshooting

Verification

1. In Graphics Designer, hold Ctrl and double-click the object to open the action in the debugger; step through the VBS.
2. Activate the project locally and trigger the event. Confirm the text updates within one polling cycle.
3. On Unified targets, open the runtime's diagnostic page (System → Diagnostics) and verify that no ScriptError entries are logged for the affected screen.
4. Force a tag toggle from the PLC and watch the text change without a manual refresh.
5. Stop and restart the runtime. The text should restore to its initial value as defined in the Static Text properties.
6. For Picture Windows, instantiate at least two faceplates with different tag prefixes and confirm each shows its own state independently.

FAQ