122 lines
7.7 KiB
Markdown
122 lines
7.7 KiB
Markdown
---
|
||
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
|
||
|
||
```xml
|
||
<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|preview|setup|selectFrame` | Printing (desktop only) |
|
||
| `login`, `logout`, `exit`, `toolbar`, `statusline`, `playback record|view`, `shell client|server <cmd>`, `lookfeel <class>`, `help` | |
|
||
|
||
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).
|