Horizontal Scrolling Wide WinCC PDL Pages via VBScript

Horizontal Scrolling Wide WinCC PDL Pages via VBScript

This engineering reference documents how to expose horizontal panning of a WinCC Graphics Designer process picture (PDL) whose pixel width exceeds the visible monitor viewport, without forcing the operator to drag a Windows scroll bar. The reference applies to SIMATIC WinCC V7.x runtime with the Graphics Designer editor and is built on the documented HMIRuntime automation object model. The two principal approaches covered are direct viewport manipulation through HMIRuntime.ActiveScreen.ScrollPosX and the picture-window alternative for stations where the active screen is locked or where horizontal panning must coexist with layered pop-up graphics.

1. Problem Statement

A process overview picture representing, for example, every bunker in a steelmaking stockhouse, can easily reach 4000–8000 px in width. A typical operator monitor is 1920×1080. When the PDL is opened in runtime, only the leftmost ~1920 px are visible. The default Windows scrollbar can be disabled for cleanliness on a control-room HMI, leaving the operator with no way to inspect the right-hand bunkers without changing screen resolution. The requirement is therefore:

• Provide discrete Left and Right buttons (or hotkeys) that pan the picture.
• Do not display a horizontal scroll bar in the deployed picture window.
• Maintain the last position across screen changes when the operator returns to the overview.
• Clamp the pan so the picture cannot scroll past its left or right edge.

2. Prerequisites

Refer to the How to start the Graphics Designer – WinCC V7.5 entry for opening the editor and creating the host picture that will host the wide PDL.

3. PDL Coordinate and Viewport Model

Every active WinCC picture window defines a viewport rectangle whose origin is the upper-left of the host screen window. The PDL itself is drawn in its own coordinate space starting at (0,0). The runtime maintains a scroll offset (ScrollPosX, ScrollPosY) such that the visible region is [ScrollPosX, ScrollPosX + ViewportWidth] in PDL coordinates. Setting ScrollPosX therefore re-positions the viewport horizontally inside the PDL.

4. Built-in Scrollbar Configuration (Reference)

WinCC exposes the host picture window's scroll behavior through Computer Properties. Configure as a baseline, then disable for the clean operator UI:

1. In the WinCC Explorer, right-click the RT computer → Properties.
2. Select the Graphics Runtime tab.
3. Open Window Attributes.
4. Tick Show slider during commissioning to verify viewport bounds.
5. After validation, untick Show slider and Show title bar for the production picture window so only the buttons drive panning.

This setting only changes appearance; the underlying ScrollPosX / ScrollPosY properties remain writable regardless of slider visibility, which is the basis for the programmatic method below.

5. Programmatic Scrolling via HMIRuntime.ActiveScreen

The HMIRuntime object is the runtime's VBScript root. The ActiveScreen property returns an Screen object representing the currently active picture window of the calling application window. Relevant members:

Because the Screen object is bound to the host window, the maximum allowed ScrollPosX is PictureWidth - Width, where PictureWidth is the configured geometry of the PDL. Setting ScrollPosX to a value outside that range raises runtime error ‘Invalid value’ and the property remains unchanged.

6. Working VBScript Implementation

The snippet below is the canonical implementation. Place it in a Global Script → Action of type “On tag change” triggered by an internal binary tag, or invoke it directly from a button's Mouse click event using the same body.

6.1 Continuous-pan action triggered by an internal tag

' --- PanWidePDL.bas (Global Action, triggered on tag change) ---
Option Explicit

Const PAN_STEP As Long = 40        ' pixels per trigger
Const PICTURE_WIDTH As Long = 6000 ' PDL width in pixels (configure per project)

Dim objView
Set objView = HMIRuntime.ActiveScreen

If objView Is Nothing Then
    HMIRuntime.Trace "PanWidePDL: ActiveScreen is Nothing"
    Exit Sub
End If

objView.Activate

Dim newX As Long
newX = objView.ScrollPosX

' --- Direction comes from two separate internal tags --- 
If HMIRuntime.Tags("Pan_Left").Read  Then newX = newX - PAN_STEP
If HMIRuntime.Tags("Pan_Right").Read Then newX = newX + PAN_STEP

' --- Clamp to picture bounds --- 
If newX < 0 Then newX = 0
If newX > (PICTURE_WIDTH - objView.Width) Then _
    newX = PICTURE_WIDTH - objView.Width

objView.ScrollPosX = newX

' --- Optional echo for diagnostics --- 
HMIRuntime.Tags("Pan_CurrentX").Write newX

6.2 Direct button-on-click variant

' --- Button event, Mouse click on btn_PanLeft --- 
Dim objView
Set objView = HMIRuntime.ActiveScreen
objView.Activate

If objView.ScrollPosX >= 40 Then
    objView.ScrollPosX = objView.ScrollPosX - 40
Else
    objView.ScrollPosX = 0
End If

6.3 Toggle between extreme positions (leftmost / rightmost)

' --- Toggle picture between far-left and far-right --- 
Dim objView, maxX As Long
Set objView = HMIRuntime.ActiveScreen
objView.Activate

maxX = 6000 - objView.Width        ' PICTURE_WIDTH - viewport

If objView.ScrollPosX >= maxX / 2 Then
    objView.ScrollPosX = 0
Else
    objView.ScrollPosX = maxX
End If

7. Common Failure Modes and Corrections

8. Picture Window Alternative

If the active host screen is shared with overlay graphics (alarm line, status bar, header) and must not scroll itself, place the wide PDL inside a Picture Window smart object that is itself narrower than the picture it contains. The picture window exposes Left and Top properties equivalent to a scroll offset when its contained picture geometry exceeds the window size. Use the same VBScript pattern, but operate on the picture window object:

' --- Pan a Picture Window by adjusting its Left coordinate --- 
Dim objPW
Set objPW = ScreenItems("PW_BunkerOverview")

If objPW Is Nothing Then Exit Sub

Dim stepPx As Long
stepPx = 40

If HMIRuntime.Tags("Pan_Right").Read Then
    objPW.Left = objPW.Left - stepPx      ' moving picture-window left pans content right
End If
If HMIRuntime.Tags("Pan_Left").Read Then
    objPW.Left = objVW.Left + stepPx
End If

' Clamp using picture geometry: PictureWidth - objPW.Width
Dim maxLeft As Long
maxLeft = -(6000 - objPW.Width)         ' picture-window left can be negative
If objPW.Left < maxLeft Then objPW.Left = maxLeft
If objPW.Left > 0       Then objPW.Left = 0

This decouples the scroll surface from the host application window and works even when ActiveScreen is locked by a modal dialog.

9. Button Wiring and Hotkey Configuration

10. Runtime Verification and Diagnostics

1. Open the wide PDL in WinCC RT with the Show slider still enabled (see §4). Verify the picture width attribute matches PICTURE_WIDTH in the script.
2. Click the « Right » button. The horizontal slider thumb should advance by exactly PAN_STEP pixels (40 in the example).
3. Continue clicking. Confirm clamping: at the rightmost valid position the slider parks at PictureWidth - ViewportWidth, and the trace output shows PanWidePDL: clamped at 4080 if you add a trace line before clamping.
4. Switch to another picture, then return. Pan_CurrentX should hold the previous position via the Open picture event action:

   ' Open-picture event of Bunker_Overview.pdl 
   Dim objView
   Set objView = HMIRuntime.ActiveScreen
   objView.Activate
   objView.ScrollPosX = HMIRuntime.Tags("Pan_CurrentX").Read
   

5. Open WinCC Explorer → Tools → Diagnostic → Script Diagnostic and re-run the pan. No runtime errors should appear; warnings about ActiveScreen returning Nothing indicate the action fired before the picture window finished initialising.

11. Performance and Licensing Notes

• Global actions that fire on every tag change add CPU load. For a continuous-pan implementation prefer a 50–100 ms cyclic trigger combined with the tag as a direction selector rather than firing on every edge.
• Reading objView.Width inside a tight loop is cheap but every HMIRuntime.Tags(...).Read crosses the tag-management layer; cache tag values at the top of the action.
• VBS actions are governed by the runtime authorisation system. If operators have scripting disabled, the pan will silently fail with no UI feedback; verify in User Administrator → Authorisation → Runtime scripting.
• Picture windows are subject to the same configuration limits as the host screen; a picture window with <50 px scrollable width produces no visible motion even though ScrollPosX updates internally.
• Refer to the SIMATIC WinCC V7 Graphics Designer manual (SIOS) for the complete Screen and ScreenItem object model, and to the WinCC V7.5 Graphics Designer start guide for editor-side workflow.

FAQ