WinCC Close Multiple Picture Windows with C Script: Complete Guide

When designing multi-level HMI screens in Siemens WinCC and WinCC Professional in the TIA Portal, engineers frequently embed secondary .pdl pictures inside a root screen using the Picture Window smart object. A common requirement is the ability to dismiss every nested picture with a single reset or close button. This reference covers the C script, the VBS alternative, and the tag-based animation method to close all picture windows from one operator action.

1. Overview of the Close-All Problem

A Picture Window in WinCC is a container object that loads a referenced .pdl file at runtime. A single root screen may host several Picture Windows (typically named PictureWindow1, PictureWindow2, PictureWindow3), each pointing at a different child picture such as 1.pdl, 2.pdl, 3.pdl. When an operator presses a global Reset or Close All button, the engineer needs a one-shot script that hides every nested window.

Two recommended approaches exist:

1. Direct property method – C script using the SetPropBool API to set Visible = 0 on each Picture Window object.
2. Animation / tag-driven method – A bit-pattern HMI tag is wired to the Visibility dynamic dialog of each Picture Window. The reset button writes 0 to the tag and all windows hide simultaneously.

For two or three windows the script approach is faster. For dynamic numbers of windows (especially when pictures are opened or closed by faceplates), use the tag-based method so the logic scales without code edits.

2. Prerequisites

Before adding scripts, confirm the following project environment:

• WinCC V7.4 SP1 or later, OR TIA Portal V16 + WinCC Professional V16 or later
• Graphics Designer / TIA HMI editor licensed and open with the project loaded
• Global Script Runtime activated (C scripts require the C-Script option in WinCC V7; in TIA Portal it is part of the Professional runtime)
• Authoring rights for the HMI station; write access to the project folder
• Reference manuals on hand: WinCC V7.5 SP2 Scripting Manual and the SIMATIC WinCC Professional V19 System Manual

3. Configuring the Picture Windows in the Root Screen

1. Open the root .pdl in the Graphics Designer (WinCC V7) or in the HMI screen editor (TIA Portal).
2. From Smart Objects, drag three Picture Window objects onto the canvas.
3. Rename them to PictureWindow1, PictureWindow2, PictureWindow3 using the Object Properties > Properties > Miscellaneous > Object Name field. Object names are case-sensitive in the script.
4. In Object Properties > Properties > Picture > Picture Name, enter the relative paths 1.pdl, 2.pdl, 3.pdl (or qualified paths such as NewPdl1.PDL in V7).
5. Stack them at the same X/Y position (typical: 0,160 for a 1152 × 768 root) so only the topmost is visible at any time, or arrange them side-by-side for split layouts.

The properties most often read or written by the close script are:

4. C Script Implementation (SetPropBool)

The classic C-Script function for toggling a single object property is SetPropBool declared in apdefap.h:

Place the following code on the Mouse > Release Left event of the reset/close button. The release left event fires after the operator releases the mouse, preventing accidental double-clicks from re-firing the close sequence.

// Close all picture windows on the active screen
#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszItemName)
{
    // Replace "principal.pdl" with the actual root picture name
    SetPropBool("principal.pdl", "PictureWindow1", "Visible", 0);
    SetPropBool("principal.pdl", "PictureWindow2", "Visible", 0);
    SetPropBool("principal.pdl", "PictureWindow3", "Visible", 0);

    // Optional: log the action for audit
    // printf("All picture windows closed by operator\r\n");
}

Key arguments:

• lpszPictureName – The screen containing the Picture Window. Use the exact file name including extension. In TIA Portal, this can be empty ("") to address the calling screen; in WinCC V7 it must match the active .pdl name.
• lpszObjectName – The Picture Window's Object Name, not its caption. Names are case-sensitive.
• lpszPropertyName – The property to modify. "Visible" is the documented close flag for Picture Window, IO Field, Button, Graphic View, and most smart objects.

5. C Script Using the Active Screen Helper

To make the script portable across screens (so the same button code works on any picture that contains the three Picture Windows), use the current screen placeholder:

// Portable close-all - works on any host screen
#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszItemName)
{
    SetPropBool(lpszPictureName, "PictureWindow1", "Visible", 0);
    SetPropBool(lpszPictureName, "PictureWindow2", "Visible", 0);
    SetPropBool(lpszPictureName, "PictureWindow3", "Visible", 0);
}

The runtime passes the host picture name in lpszPictureName automatically. This pattern is recommended when the close button is reused on multiple screens.

6. C Script to Close AND Reset a Tag

Often the same button must reset the underlying HMI tags that drive the picture visibility. Combine SetPropBool with SetTagBit:

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszItemName)
{
    // Hide all picture windows
    SetPropBool(lpszPictureName, "PictureWindow1", "Visible", 0);
    SetPropBool(lpszPictureName, "PictureWindow2", "Visible", 0);
    SetPropBool(lpszPictureName, "PictureWindow3", "Visible", 0);

    // Reset the visibility tag (Word) to 0 - drives dynamic dialogs
    SetTagWord(lpszPictureName, "HMI_VisibleMask", (WORD)0);

    // Also reset each operator flag if used
    SetTagBit(lpszPictureName, "Flag_Open1", 0);
    SetTagBit(lpszPictureName, "Flag_Open2", 0);
    SetTagBit(lpszPictureName, "Flag_Open3", 0);
}

7. VBScript Alternative (HMIRuntime Object Model)

WinCC V7 SP3+ and WinCC Professional fully support VBScript as a more maintainable alternative. Use the HMIRuntime global object and the ScreenItems collection:

' CloseAllPictureWindows.vbs
Sub OnClick(ByVal Item)
    Dim objPW1, objPW2, objPW3
    Set objPW1 = HMIRuntime.ActiveScreen.ScreenItems("PictureWindow1")
    Set objPW2 = HMIRuntime.ActiveScreen.ScreenItems("PictureWindow2")
    Set objPW3 = HMIRuntime.ActiveScreen.ScreenItems("PictureWindow3")

    objPW1.Visible = False
    objPW2.Visible = False
    objPW3.Visible = False
End Sub

For a configurable count, loop a numeric tag:

Sub OnClick(ByVal Item)
    Dim i, objPW
    Dim nCount : nCount = CLng(HMIRuntime.Tags("HMI_PictureCount").Read)
    For i = 1 To nCount
        Set objPW = HMIRuntime.ActiveScreen.ScreenItems("PictureWindow" & i)
        objPW.Visible = False
    Next
End Sub

8. Tag-Driven Animation (No Code Path)

When the same close behavior must scale to N picture windows without code edits, drive the Visibility property of every Picture Window with one Word tag such as HMI_VisibleMask (data type Word / UInt).

1. Create an internal HMI tag HMI_VisibleMask of type Word in the HMI tag table.
2. Select PictureWindow1 > Object Properties > Properties > Miscellaneous > Visible and click the small lightening-bolt to open the Dynamic dialog.
3. Configure: Tag/Expression = HMI_VisibleMask, Bit = 0, Value = 0 → Visible = 0, Value = 1 → Visible = 1.
4. Repeat for PictureWindow2 with Bit = 1, and PictureWindow3 with Bit = 2.
5. On the open button, set the corresponding bit (e.g., SetTagBit("Flag_Open1", 1) and write HMI_VisibleMask = 1).
6. On the reset/close button, set HMI_VisibleMask = 0. All windows hide at once.

Tag mapping table for clarity:

Wire the open buttons to write the corresponding decimal constant:

// On Click of "Open 1" button
SetTagWord(lpszPictureName, "HMI_VisibleMask", (WORD)1);  // 0b001
// On Click of "Open 2" button
SetTagWord(lpszPictureName, "HMI_VisibleMask", (WORD)2);  // 0b010
// On Click of "Open 3" button
SetTagWord(lpszPictureName, "HMI_VisibleMask", (WORD)4);  // 0b100
// On Click of "Reset/Close All" button
SetTagWord(lpszPictureName, "HMI_VisibleMask", (WORD)0);  // 0b000

9. Verification Procedure

1. Static compile – In WinCC V7 Graphics Designer, select File > Compile > All Pictures. Any unresolved object names in the C script will produce warnings such as "Object not found: PictureWindow1".
2. Tag simulator – Use the WinCC Tag Simulator (Start > Programs > Siemens Automation > WinCC > Tools) to force HMI_VisibleMask to 7, then 0, and watch the Picture Windows toggle.
3. Runtime test – Start the WinCC Runtime, press the open button for each window, then press the reset button. All three Picture Windows must hide in a single animation cycle (typically 100–250 ms on a 1152 × 768 panel).
4. Cross-screen test – Duplicate the reset button on a second screen and confirm the portable lpszPictureName version still closes the windows.
5. PLCSIM hook – For tag-driven variants, in PLCSIM toggle the linked PLC bit and verify the change of state is reflected within one acquisition cycle (default 500 ms for WinCC V7, 100 ms for TIA V18+).

10. Common Errors and Fixes

11. Performance and Best Practices

• Prefer the tag-driven mask method for systems with more than three Picture Windows; the script variant requires one line per window and is harder to maintain.
• Group all Picture Windows under a parent Group object, then call SetPropBool on the group's Visible property – this closes every child in one call.
• For faceplate-driven UIs in TIA Portal, use the faceplate's container interface and call Container.Close() rather than setting Visible.
• Place the close script on the Click event, not the Press event, to debounce.
• Use internal HMI tags with the Synchronous update attribute on the tag connection so writes from PLC and operator stay consistent.
• For auditability, write a GetTagXXX snapshot to a buffer tag before closing, so the operator can restore the last state on a separate button.

12. Adapting the Pattern to TIA Portal WinCC Professional

In TIA Portal, the SetPropBool C function is replaced by the VBScript / C-script equivalents under the HMIRuntime and Screen objects. The equivalent close-all script in TIA Portal V18 is:

' TIA Portal WinCC Professional - VBScript
Sub OnClick(ByVal Item)
    Dim oScreen, i, oItem
    Set oScreen = HMIRuntime.Screens(HMIRuntime.ActiveScreen.Name)
    For i = 1 To 3
        On Error Resume Next
        Set oItem = oScreen.ScreenItems("PictureWindow" & i)
        If Not oItem Is Nothing Then oItem.Visible = False
        Set oItem = Nothing
        On Error Goto 0
    Next
End Sub

In TIA Portal C-Script (IEC 61131-like syntax), the equivalent block on the Click event of the button is:

// TIA Portal WinCC Professional - C
void OnClick(char* screenName, char* objectName)
{
    char prop[32];
    char item[32];
    int i;
    for (i = 1; i <= 3; i++)
    {
        sprintf(item, "PictureWindow%d", i);
        SetPropBool(screenName, item, "Visible", 0);
    }
}

Documentation references for these APIs:

• SIMATIC WinCC Professional V19 System Manual (SIOS)
• WinCC V7.5 SP2 - Scripting: VBScript and C-Script (SIOS)
• WinCC V7.5 SP2 - Working with WinCC (SIOS)

13. Frequently Asked Questions