WinCC Faceplate VB Script: Referencing Internal Objects

1. Overview

WinCC Comfort, WinCC Advanced, and WinCC Professional (TIA Portal) faceplates are reusable screen objects that encapsulate graphics, I/O fields, buttons, and scripts. A common engineering requirement is to bind the visibility and color of an internal faceplate element (for example, an I/O field or rectangle) to process tags that represent warning and alarm states (H, HH, L, LL). When engineers attempt to do this with the standard runtime object model — HmiRuntime.Screens("Screen1").ScreenItems("IO_field").Visible — the script fails inside a faceplate context with an object reference error or silently no-ops.

This reference documents the correct way to address faceplate-internal objects from VB scripts and from the basic picture, including the "Reference from basic picture" pattern that Siemens officially documents in the TIA Portal help. It also covers the configuration steps for faceplate scripts, the runtime object model for faceplate instances, and working code for warning/alarm-driven color changes.

2. Why HmiRuntime.Screens Fails Inside a Faceplate

The global HmiRuntime object exposes the Screens collection, which enumerates the top-level picture windows of the active screen. Inside a faceplate script, the runtime context is the faceplate instance — not the base picture window. HmiRuntime.Screens(...) returns base-picture screen items, not the children of the faceplate that is currently executing the script. The lookup therefore resolves to Nothing and any property write raises "Object reference not set to an instance of an object" or is silently dropped.

Siemens tech support has explicitly stated that the HMI.Runtime (classic WinCC V7.5) object model is not supported in faceplate VB scripts. The same restriction applies to HmiRuntime.Screens in TIA Portal WinCC. You must reference the object relative to the current faceplate instance or relative to the base picture that hosts the instance.

3. Affected TIA Portal Versions

4. Configuring a Faceplate Script

Open the faceplate type editor in TIA Portal and create a new VB script on the appropriate event:

1. In the project tree, expand HMI tags > Screens > [Faceplate type].
2. In the configuration area, click Scripts > Faceplate scripts.
3. Double-click Add VB script or press the shortcut keys <CTRL+J> to open the object list.
4. Select the trigger event: Loaded, Cleared, or — more commonly — a tag-change event bound to one of the faceplate interface tags.
5. Write the VB script using the patterns in §6 and §7. The script executes in the faceplate instance context whenever the trigger fires.

Reference: Example: Creating a script in the faceplate type (Panels, Comfort Panels, RT Advanced, RT Professional).

5. The Two Valid Reference Paths

There are two correct ways to address an object inside a faceplate from a VB script. Which one you use depends on whether the script lives inside the faceplate type or in the base picture.

5.1 Reference From Inside the Faceplate (Faceplate Script)

When the script runs inside the faceplate type (added under Faceplate scripts), the implicit parent of every child object is the faceplate instance. Use the relative Items collection:

Dim objIO As HMIObject
Set objIO = Items("IO_Hysteresis")
objIO.Visible = False

The Items collection at script execution time is the own collection of the faceplate instance — not the base picture's ScreenItems. This is the correct analogue of ScreenItems for a faceplate script.

5.2 Reference From the Basic Picture (Base Script)

When the script runs in the base picture (a normal screen script) and must reach an object that lives inside a faceplate instance placed on that screen, Siemens calls this "Referencing from the basic picture". The syntax walks down the object hierarchy from the base screen into the faceplate:

Dim objRect As HMIObject
Set objRect = Screen.Items("FaceplateInstance_1").ScreenItems("Rectangle_Alarm")
objRect.BackColor = RGB(255, 0, 0)

The faceplate instance name (here FaceplateInstance_1) is the property name assigned when the faceplate was dropped onto the screen. The inner ScreenItems collection enumerates the faceplate's children. This is the path shown in the TIA Portal help screenshot for the "Referencing from the basic picture" option.

6. Working Code: I/O Field Visibility by Warning/Alarm Tags

Use case: an I/O field for the hysteresis value must be visible only when both warning_H_enabled and alarm_HH_enabled are true. The two tags are exposed on the faceplate's interface as WarningHEnabled and AlarmHHEnabled.

Bind a faceplate script to the event OnChange of the interface tag WarningHEnabled. The script body:

' VB script — faceplate-internal I/O field visibility
Dim intWarning As Integer
Dim intAlarm   As Integer
Dim objIO      As HMIObject

intWarning = SmartTags("WarningHEnabled")
intAlarm   = SmartTags("AlarmHHEnabled")

Set objIO = Items("IO_Hysteresis")

If intWarning = 1 And intAlarm = 1 Then
    objIO.Visible = True
Else
    objIO.Visible = False
End If

Mirror this script on the OnChange event of AlarmHHEnabled so that the I/O field hides immediately when either tag is cleared.

7. Working Code: Rectangle Color Change for Alarm Limits

Use case: a faceplate displays a measurement (position, value, unit). The status rectangle inside the faceplate must change to yellow for H/L warnings and to red for HH/LL alarms. The user controls this with two process tags that the faceplate polls on every change.

Bind a faceplate script to the OnChange event of the AlarmState interface tag (an integer that the base PLC code sets to 0=OK, 1=HighWarning, 2=HighAlarm, 3=LowWarning, 4=LowAlarm). Body:

' VB script — faceplate-internal rectangle color
Dim intState    As Integer
Dim objRect     As HMIObject

intState = SmartTags("AlarmState")

Set objRect = Items("Rectangle_Status")

Select Case intState
    Case 0          ' OK
        objRect.BackColor = RGB(  0, 176,  80)   ' green
    Case 1, 3       ' H / L warning
        objRect.BackColor = RGB(255, 192,   0)   ' yellow
    Case 2, 4       ' HH / LL alarm
        objRect.BackColor = RGB(255,   0,   0)   ' red
    Case Else
        objRect.BackColor = RGB(128, 128, 128)   ' gray (unknown)
End Select

The same code expressed from the base picture uses the "referencing from the basic picture" path:

' VB script — base picture, modifying a child of a faceplate instance
Dim intState As Integer
Dim objRect  As HMIObject

intState = SmartTags("AlarmState")

Set objRect = Screen.Items("Faceplate_Loop_1").ScreenItems("Rectangle_Status")

Select Case intState
    Case 0
        objRect.BackColor = RGB(  0, 176,  80)
    Case 1, 3
        objRect.BackColor = RGB(255, 192,   0)
    Case 2, 4
        objRect.BackColor = RGB(255,   0,   0)
    Case Else
        objRect.BackColor = RGB(128, 128, 128)
End Select

8. Faceplate Interface Tags for Parameterization

Exposing tags on the faceplate interface is what makes the same faceplate type reusable across multiple process tags. The recommended pattern for a measurement faceplate:

Inside the faceplate, concatenate the prefix with the alarm tag name to read the live PLC bit:

Dim strTag As String
strTag = SmartTags("TagPrefix") & ".H_Alarm"
If SmartTags(strTag) = 1 Then ...

9. Avoiding the HmiRuntime.Screens Trap

Engineers moving from WinCC V7 to TIA Portal often paste the classic HmiRuntime.Screens(...).ScreenItems(...) line into a faceplate script. The line compiles, but at runtime it returns Nothing. Use the rules below to avoid silent failure:

• If the script is a faceplate script: use the implicit Items collection of the faceplate instance — not ScreenItems and not HmiRuntime.Screens.
• If the script is a base-picture script: start the reference at Screen and walk down through Items("FaceplateInstance_X").ScreenItems("ChildName").
• If you need the global screen: call HmiRuntime.BaseScreenName to discover the base picture name, then address Screen.Items(...) from a base-picture script. Never call HmiRuntime.Screens from a faceplate script.
• For tag access: SmartTags("MyTag") works inside faceplate scripts as long as the tag is known to the HMI device.

10. WinCC V7.5 (Classic) Behavior

On classic WinCC V7.5 faceplates, Siemens tech support has confirmed that the HMI.Runtime object model is not supported in faceplate VB scripts. The historical workaround is to use the faceplate's property interface and bind colors via dynamic dialogs (analog/multiplex) rather than scripting. On TIA Portal faceplates, dynamic dialogs remain an alternative — set Appearance > BackColor to a multiplexed variable that selects one of four colors based on an integer tag.

For new projects, prefer the TIA Portal script pattern documented in §5–§7 because it keeps the alarm logic in code (easier to version-control, copy between faceplates, and audit) rather than in the property grid.

11. Verification Checklist

1. Compile the project in TIA Portal. VB syntax errors raise "VB script could not be compiled" in the Inspector.
2. Download to the HMI runtime (WinCC RT Professional, Comfort Panel, or Unified PC).
3. Open the screen that contains the faceplate instance. Force the source tags to 0 from the PLC simulator or the tag table.
4. Toggle WarningHEnabled from 0 to 1. The hysteresis I/O field must appear within one screen refresh cycle (≤500 ms typical).
5. Force AlarmState through 0 → 1 → 2 → 3 → 4. The status rectangle must transition green → yellow (H) → red (HH) → yellow (L) → red (LL).
6. Trigger a tag-change on a different faceplate instance on the same screen. Confirm that only that instance's colors change — the relative Items path must not bleed across instances.
7. Cycle power on the panel or restart the WinCC RT service. Re-verify all state transitions; faceplate scripts do not re-execute automatically on the Loaded event unless you explicitly bind to it.

12. Troubleshooting Matrix

13. Frequently Asked Questions