ci-server-engineer/.claude/skills/graphics/tasks/layouts.md

---

task: Configure operator layouts (Layouts.xml): windows, menus, toolbars, frames, popups; open displays in frames and layouts version: R1.03 source: Layouts.readme (installed, %TLS_WAP_PATH%\cfg\operatorInterfaces\DEPLOY\layouts); IM 36K10R30-01EN §1, §4.7; IM 36K10C50-01EN §4.12; practiced with CI-Eng-Sample (layout CIENG_Operator) in the Operator Interface (desktop) and the HTML display 2026-10-01 status: verified

Operator layouts

A layout is a window of the Operator Interface: optional menu and toolbars, a frame set (required) holding displays, and a status line. All layouts of a deployment are in one file, %TLS_WAP_PATH%\cfg\operatorInterfaces\DEPLOY\layouts\Layouts.xml, used by both the Operator Interface (desktop) and the HTML display (web). The complete option and command reference is Layouts.readme in the same folder; Layouts-original.xml is the factory copy.

1. Rules

• Layouts.xml is shared by every operator: back it up and change it only with the user's approval. Keep project layouts in a marked block so they can be removed cleanly (sample: examples/CI-Eng-Sample/layouts/layout.ps1 + CIENG_Operator.xml; the script checks the XML is well-formed, keeps UTF-8 without BOM and CRLF, and -Remove restores the file byte for byte).
• The Operator Interface reads Layouts.xml only when it starts. After a change, close and restart it. A running client does not know a new layout: opening a display in it only reloads the current window ("blink"). The Edit Module also needs a restart to offer the new name in the Open display action.
• Name the main frame default: the factory and AOG displays (alarm lists, faceplates, toolbar commands) open their targets in a frame called default.

2. Structure

<layout name="<Name>" title="<text> $default" icon="poi.png" drawBorder="true"
        sizingAllowed="true" minimizingAllowed="true" closingAllowed="true" alwaysOnTop="false"
        initialPosition="centreScreen" initialSize="pixels" initialSizeWidth="1600"
        initialSizeHeight="900" maximumOpen="1">
  <menu> <menu-item name="m.file" label="File"> <menu-item … command="exit"/> </menu-item> … </menu>
  <toolbar name="t1" floatable="false" position="top"> <toolbar-item icon="ciNavLeft32.png"
           tooltip="Back to $" command="navigate back default"/> … </toolbar>
  <frame-set rows="1*,fitDisplay">            <!-- main area, alarm banner below -->
    <frame-set cols="fitDisplay,1*">          <!-- navigation left, main right -->
      <frame name="nav" initialDisplay="<NavDisplay>" zoomingAllowed="false"/>
      <frame name="default" initialDisplay="<Overview>" stackSize="10" zoom="fitDisplay"/>
    </frame-set>
    <frame name="alarmBannerFrame" initialDisplay="AOG_AlarmBanner" zoom="stretchDisplay"/>
  </frame-set>
  <status-line> <status-line-item type="statusText"/> <status-line-separator/> … </status-line>
</layout>

• title: $<frame> = title of the display in that frame (verified: CI-Eng-Sample - Current Alarm Overview).
• Window: initialPosition (centreScreen, atCursor, pixelsScreen2, centreLayout, …), initialSize (pixels, screenSize, desktopSize, fitFrames), maximumOpen, modal, alwaysOnTop, print options.
• Frame sets: rows / cols with pixels, n* fractions or fitDisplay; nest freely; a <tab> holds several frames as tabs (tabPosition, maximumTabs, closeTabAllowed). Frame options: name, initialDisplay (= home display), stackSize (back/forward history), zoom (fitDisplay, stretchDisplay, <n>%), zoomingAllowed, scrollingAllowed, borderStyle.
• Menu (max. two levels; type normal/check/radio/sub; mnemonic, accelerator like F5, CONTROL P) and toolbar items (icon from the factory set such as ciNavLeft32.png, ciProAlar32.png, ciZoomFull32.png; type combo/editableCombo/dropdownList) run commands:

Command	Effect
navigate to <frame> <display> [<zoom>] [<p>=<v>;…]	Open a display in a frame (with parameters)
navigate back/forward/up/home/history <frame>	Frame history ($ in the tooltip = target name)
reload <frame> / reload all	Reload displays (keeps the session in the HTML display)
zoom <level> <frame>	0 = fit, 1 = 100 %, 10–1000 = relative %
toggleSize fullScreen [n] / toggleSize x,y,WxH	Full screen / given size and back
`print frame	frameWithSetup
login, logout, exit, toolbar, statusline, `playback record	view, shell client

The installed status line also uses item types displayName, playbackIndicator and dateTime, which the readme does not list (ISS-042).

• <translations name="nl"> blocks translate labels per locale (key = item name + .label).

3. Opening displays in frames and layouts

From	How
Button / component (Edit Module, Actions sheet → Open display)	Display, Layout (empty = current window), Frame, parameters; stored as <action type="actionActivateDisplay"> with <type … value="ActivateSpecific"/>, <display>, <layout>, <layoutFrame>
Menu / toolbar	navigate to <frame> <display> (current window only)
Login	User profile Layout and Initial display (Engineering Module, Authorization > Users); empty layout = default (from docs; not changed on the test system)
HTML display	URL ?d=<display>&l=<layout>
Script on a component	Execute command with ACTION <layout command>, e.g. ACTION toggleSize 50,50,710x520

Verified behaviour (desktop): a button with layout CIENG_Operator opened a second window (1600 × 900, own menu/toolbar/frames); buttons without layout opened their display in the main frame of the current window; Back returned. A button with layout popup opened a separate window: always on top, only a close button, sized to the display (fitFrames), and minimised together with the window that opened it — use popups only for small displays (faceplates, setpoint dialogs).

4. Typical project layouts

• Operator main window: navigation frame + main frame default (+ tabs) + alarm banner, project menu/toolbar, assigned to operators via the user profile Layout.
• Kiosk / control-room screen: drawBorder="false", alwaysOnTop="true", initialSize="screenSize", closingAllowed="false", minimizingAllowed="false". toggleSize fullScreen covers the taskbar only when alwaysOnTop="true" (verified: with false the title bar and taskbar stay).
• Popups / faceplates: small layout with one frame default, initialSize="fitFrames", initialPosition="atCursor", alwaysOnTop="true", maximumOpen > 1 for several faceplates (factory: popup, FixedPopup, ResizablePopup, faceplate, tuningpanel, Setpoint, SelectMode).
• Several screens: one layout per screen with initialPosition="pixelsScreen2" / centreScreen2, or the dual-screen pattern of IM 36K10R30 §1.10.

5. HTML display differences

The browser window is the main layout (its size and window options are ignored); other layouts open as windows inside the page; print, look-and-feel and the debug key are not supported; pick the layout with &l=. Verified: ?d=CIENG_Tank&l=CIENG_Operator showed the sample menu, toolbar, navigation frame and banner.

Verified (CI-Eng-Sample, 2026-10-01)

layout.ps1 add / remove / add (removal identical to the original, backup kept); Operator Interface restart required before the layout was found; desktop and web windows as described above; F11 (toggleSize fullScreen) worked within the taskbar limits; after restarting the Operator Interface the main window still used the factory default layout (Admin profile unchanged).