WinCC Professional: Move Screen Window Position with VBScript

WinCC Professional: Move Screen Window Position with VBScript

WinCC Runtime Professional routinely renders process screens whose pixel canvas exceeds the physical resolution of the HMI panel or PC monitor. The standard operator response is to scroll vertically or horizontally, but in many plants the visible scrollbars are intentionally hidden for cosmetic reasons, locked by access protection, or mapped to events that the engineer wants to drive programmatically. This reference consolidates the supported VBScript properties for repositioning screen windows, panning oversized base screens, binding the offset to PLC tags, and verifying the result in TIA Portal V13 and later (forward-compatible through V20).

1. Problem Statement: Oversized Screens on Fixed-Resolution HMIs

A WinCC Professional engineering team is asked to deliver a 1020 x 3380 px process overview onto a Comfort-style IPC whose display is fixed at 1020 x 1920 px. The operator must be able to:

• Open the screen and immediately land on the top section (process overview).
• Click a navigation button to jump to the lower alarm / detail section without using a mouse wheel.
• Maintain the visual identity of the layout — i.e., no scrollbar should appear at runtime.

Two independent techniques solve the requirement, and they are commonly combined:

1. Picture Window panning — A base screen sized to the monitor hosts a Picture Window object whose content is a second screen larger than the picture window. The VBScript repositions the picture window within the base screen.
2. Base-screen scroll offset — The full oversized base screen is itself panned using the screen-level HorizontalScrollbarPosition / VerticalScrollbarPosition properties.

Figure 1 — Left: oversized base screen panned vertically. Right: picture window repositioned inside a fixed-size base screen.

2. WinCC Runtime Editions — Choosing the Right Engine

Engineers working with TIA V13 should confirm the exact runtime installed on the target IPC by opening the SIMATIC Runtime Manager and checking the installed WinCC Runtime Professional build number (e.g., V13.0 + SP1 → 13.0.1.x). Object-model behavior is stable from V13 through V20, but property names remain case-sensitive across all releases.

3. Prerequisites

• SIMATIC TIA Portal V13 (or later through V20) installed with WinCC Professional option.
• WinCC Runtime Professional V13 (or matching version) installed on the target IPC.
• Project with at least one HMI device configured for WinCC Runtime Professional.
• Engineering access (read/write) to the Scripts container of the HMI device.
• For multi-monitor setups: Windows 10 / Windows 10 IoT Enterprise LTSC on the runtime PC.

4. Architecture — Screen, Screen Window, and Picture Window

WinCC Professional distinguishes three runtime containers that engineers often conflate:

The two techniques presented in this article rely on these containers:

• Technique A — Picture window panning: A picture window sized to the monitor is placed inside a fixed-resolution base screen. The picture window itself displays the oversized canvas; the engineer repositions the picture window to expose different sections.
• Technique B — Base-screen scroll offset: The base screen itself is oversized; the engineer moves the runtime's scroll offset.

5. ScreenItems Object Model Reference

The ScreenItems collection is the runtime handle to every addressable object on the currently active screen. The collection is reached only from inside a local screen script (button click, scheduled task on a screen, or screen-cycle event) or from a global script that has been passed an HMI screen reference. The collection is not available at project compile time.

5.1 PictureWindow properties (read/write)

5.2 Base-screen scrollbar properties (read/write)

6. Step-by-Step — Repositioning a Picture Window on a Button Click

1. In the project tree, expand Screens > [YourBaseScreen] and confirm a Picture Window object named PictureWindow_1 is placed at Top = 0, Left = 0, Width = 1020, Height = 1920.
2. Place a button (Basic objects > Button) on the base screen. Rename it btnGoDown.
3. Select the button, switch to the Events tab in the inspector, and open the Click event.
4. From the dropdown, choose Add script > VBScript. The integrated VBScript editor opens.
5. Paste the following code. Replace PictureWindow_1 and 1020/3380 with your project values.

' ----------------------------------------------------------------
'  VBScript - Click event of btnGoDown
'  Pans the picture window so the lower section of the oversized
'  canvas is visible on a fixed-resolution monitor.
'  Tested on WinCC Runtime Professional V13 SP1 / V15 / V20.
' ----------------------------------------------------------------
Const PW_NAME      = "PictureWindow_1"
Const CANVAS_H     = 3380        ' height of the loaded screen
Const MONITOR_H    = 1920        ' visible height of picture window
Const STEP_PX      = 720         ' vertical pan step in pixels

Dim objPW, maxTop, currentTop
Set objPW = ScreenItems(PW_NAME)

If Not IsNull(objPW) Then
    currentTop = objPW.Top
    maxTop     = CANVAS_H - MONITOR_H   ' = 1460

    ' Negative Top moves the picture window upward, exposing
    ' content that previously sat below the visible area.
    If (currentTop - STEP_PX) < -maxTop Then
        objPW.Top = -maxTop
    Else
        objPW.Top = currentTop - STEP_PX
    End If
End If

The base principle is that PictureWindow.Top accepts negative values. The picture window is positioned relative to the top-left corner of the base screen; assigning -1460 shifts the picture window up by 1460 px, exposing pixels 1460…3380 of the loaded screen.

6.1 Reset to top

Add a second button named btnGoTop and reuse the same handler with the following body:

Dim objPW
Set objPW = ScreenItems("PictureWindow_1")
If Not IsNull(objPW) Then
    objPW.Top  = 0
    objPW.Left = 0
End If

6.2 Centring on a known X / Y target

When a button must centre a particular tag coordinate on screen (for example, a clicked motor's status block), compute the offset from the tag's stored pixel coordinates:

' Tag values populated by PLC: iFaceplateCenterX, iFaceplateCenterY
Dim objPW
Set objPW = ScreenItems("PictureWindow_1")
If Not IsNull(objPW) Then
    objPW.Left = SmartTags("iFaceplateCenterX") - (objPW.Width  / 2)
    objPW.Top  = SmartTags("iFaceplateCenterY") - (objPW.Height / 2)
End If

7. Step-by-Step — Scrolling an Oversized Base Screen

When you do not want a picture window container (for example, because the entire 1020 x 3380 canvas is one screen), use the base-screen scrollbar properties. Configure the screen in the engineering view with Adapt screen > Hide scrollbars off, then expose the offsets at runtime.

1. Open the oversized base screen (e.g., ProcessOverview_1020x3380).
2. In HMI tags, create two Int tags: iScrollX, iScrollY.
3. Place two buttons on the screen: btnScrollDown and btnScrollUp.
4. Wire the click events to the script below.

' Click event of btnScrollDown
Dim objScr, maxY, step
step = 480
Set objScr = HmiRuntime.Screens("ProcessOverview_1020x3380")

If Not IsNull(objScr) Then
    maxY = objScr.Height - objScr.Width   ' use Height / Width of the screen object
    objScr.VerticalScrollbarVisible = False
    If (objScr.VerticalScrollbarPosition + step) > maxY Then
        objScr.VerticalScrollbarPosition = maxY
    Else
        objScr.VerticalScrollbarPosition = objScr.VerticalScrollbarPosition + step
    End If
End If

Notice that the screen object exposes .Height and .Width directly, so the legal maximum can be computed dynamically if you later resize the canvas. The runtime recalculates the visible area based on the active monitor's resolution.

8. Multi-Monitor Operation and OS-Level Targeting

Plant floor IPCs frequently host two monitors: one for the operator mimic, one for engineering or video. If the WinCC Runtime window opens on the wrong monitor, the runtime pixel coordinates are still correct, but the visible region of the picture window changes. Three remediation layers exist.

8.1 Runtime-side: WinCC start position

Configure the HMI device's Runtime settings > Window > Position to the monitor index reported by Windows. WinCC Professional V13+ supports a multi-monitor-aware start position; verify the documentation for your specific build.

8.2 OS-side: Microsoft Windows shortcut switch

For Windows 10 / IoT, append the /screen:<N> switch to the WinCC Runtime startup shortcut, where N is the 1-based monitor index. This is the same approach documented by Microsoft for any Windows application:

"C:\Program Files\Siemens\Automation\WinCC RT Professional\WinCCExplorer.exe" /screen:2 "<ProjectName>"

Microsoft documents this behaviour in the Q&A How do I make a program open on a specific monitor. Be aware that when Windows positions the runtime window on monitor 2, the VBScript offsets Top/Left/ScrollbarPosition remain relative to the runtime window itself, so no further script changes are needed.

8.3 Script-side: detect monitor changes

Subscribe to the HmiRuntime event that fires when the runtime window is moved or resized, and re-clamp your offsets to the new visible area:

' Global script > HmiRuntime.Events > OnWindowChanged
Sub OnWindowChanged(ByVal leftPx, ByVal topPx, ByVal widthPx, ByVal heightPx)
    Dim objPW, maxTop, maxLeft
    Set objPW = ScreenItems("PictureWindow_1")

    If IsNull(objPW) Then Exit Sub

    maxTop  = ScreenItems("PictureWindow_1").ScreenHeight - heightPx
    maxLeft = ScreenItems("PictureWindow_1").ScreenWidth  - widthPx

    If objPW.Top  < -maxTop  Then objPW.Top  = -maxTop
    If objPW.Left < -maxLeft Then objPW.Left = -maxLeft
End Sub

9. Binding the Offset to PLC Tags

Many plants want the runtime to remember the last position per operator, or to be driven by the PLC (for example, auto-jump to the alarm section when a critical alarm arrives). Wire the offset to an HMI tag with a one-cycle update:

' Click event of btnGoDown  (tag-bound variant)
Dim objPW, requestedTop

Set objPW = ScreenItems("PictureWindow_1")
If IsNull(objPW) Then Exit Sub

requestedTop = SmartTags("iRequestedTop")     ' written by PLC

' Clamp
If requestedTop < -(objPW.ScreenHeight - objPW.Height) Then
    requestedTop = -(objPW.ScreenHeight - objPW.Height)
ElseIf requestedTop > 0 Then
    requestedTop = 0
End If

objPW.Top       = requestedTop
SmartTags("iAppliedTop") = requestedTop       ' echo back to PLC

Persist the last position with an HMI recipe or a file in C:\ProgramData\Siemens\Automation\<Project>\ using FileSystemObject in a global script.

10. Verification and Acceptance Test

After deployment, run the following checks before sign-off:

11. Troubleshooting Matrix

12. Performance, Safety, and Best-Practice Notes

• Authorization. Repositioning the picture window should be reserved for roles with at least Operator authorization. A non-authenticated user must not be able to drive the view to a different screen region.
• Acknowledge interrupts. When an alarm forces a programmatic jump, do not override the operator's current view without an alarm acknowledgement — return control to the operator automatically once the alarm is acknowledged.
• Avoid race conditions. Two concurrent scripts writing objPW.Top can produce flicker. Use a module-level boolean guard (bPanningInProgress) or move the logic into a single dispatcher function.
• Save state. Persist the last applied offset to an HMI recipe if the panel reboots unexpectedly. Without persistence, the operator lands at Top = 0 after every cold start.
• Test at native resolution. Always validate the script on the production monitor at native resolution. Stretching a 1020 x 1920 design onto a 1920 x 1080 panel changes the pixel-per-inch mapping and the offsets feel different.
• Use the F1 help. The TIA Portal inline help (F1 on any property in the VBScript editor) is the canonical reference for the current build. The documentation referenced above for screen-object positioning applies equally to RT Advanced and RT Professional; for RT-Professional-only scripting, fall back to the WinCC Professional help index.