Skill Display Construction

title: "Display Construction — Types, Dashboards, Canvas, Symbols & Dynamics" tags: [display, canvas, dashboard, symbol, navigation, hmi, ui, layout, dynamics, codebehind] description: "Build FrameworX displays: understand display types (content pages, headers, sidebars, dialogs), create Dashboard and Canvas layouts, place and scale symbols properly, add visual dynamics, configure navigation, and write CodeBehind logic" version: "5.1" author: "Tatsoft"

What This Skill Does

Build complete FrameworX displays: choose the right display type for the task, create Dashboard or Canvas content pages, place controls and symbols with proper sizing and tag binding, add visual dynamics, configure navigation, and write CodeBehind for display logic.

When to Use This Skill

Use when:

• Building a new display from scratch
• User asks for a dashboard, HMI screen, or operator interface
• Need to place symbols with tag bindings
• Need visual dynamics (color changes, visibility toggles, rotation)
• Need navigation between displays
• Need CodeBehind for client-side logic

Do NOT use when:

• Just modifying text or properties on an existing display (use get_objects + write_objects)
• Need only a basic starter dashboard (the New Solution skill covers that)

Prerequisites

• Solution open with tags created (Pillar 1 complete)
• For symbol placement: know which tags to bind

MCP Tools and Tables

Critical: Use DisplaysList for creating and editing displays. DisplaysDraw is the Designer visual editor UI — NOT a writable table.

Discovery Entry Points

Before building any display, use these tools to discover what's available:

list_elements()                  -- all element types by category + library folders
list_dynamics()                  -- ALL dynamic types by category
list_elements('Symbol/HMI')     -- browse symbol library
list_elements('Canvas')          -- Canvas display structure schema
list_elements('Dashboard')       -- Dashboard display structure schema
list_elements('Wizard')          -- Wizard symbol schema

Step 1: Understand Display Types

Every display you create falls into one of these categories. Know which one you're building before you start.

Content Pages (Most Common)

Content pages fill the main Content region of the layout. These are what the operator sees and interacts with. Two panel types:

• Dashboard — responsive grid layout (Columns/Rows/Cells). Best for data monitoring: gauges, trends, grids, alarm viewers. Elements auto-fill their cells — no pixel positioning needed.
• Canvas — absolute positioning (Left/Top/Width/Height). Best for process diagrams, P&ID schematics, equipment layouts where spatial arrangement matters. Supports Shapes, Controls, Symbols, and IndustrialIcons.

Default content size: 1366 x 728. Set PanelType explicitly — omitting it silently defaults to Canvas.

Decision guide: If the display is primarily data monitoring (gauges, trends, grids), prefer Dashboard. Use Canvas only when process flow, spatial layout, or custom shapes/lines are needed.

Headers and Sidebars (Navigation)

Headers and sidebars are persistent displays that stay visible while content pages change.

• Header — typically 1366 x 40. Contains the solution title/logo on the left and navigation buttons on the right. Uses Canvas layout with IndustrialIcons and basic labels/buttons.
• Sidebar/Menu — left-side panel, typically with an AssetTree control for plant navigation. Size depends on the layout definition.

These are assigned to layout regions (Header, Menu) in DisplaysLayouts. Read the Startup layout to discover current region assignments and sizes.

CRITICAL: When creating Header by default, use "OnResize": "StretchFill",

Dialogs and Popups

Smaller displays that overlay the main content for confirmations, data entry, or detail views.

• Dialog (DisplayMode: "Dialog") — modal popup with OK/Cancel buttons. Blocks interaction with the page behind it. Use DialogOnOK() CodeBehind method for the OK action. Typical size: 400 x 300 to 600 x 400.
• Popup (DisplayMode: "Popup") — floating non-modal window. Operator can still interact with the page behind it. Typical size: 300 x 200 to 500 x 350.
• PopupWindow (DisplayMode: "PopupWindow") — separate floating window (Not available for Web, do NOT use, unless specifically requested by the user)

Open dialogs/popups via ActionDynamic with navigate to on a button click, with action OpenDisplay

Step 2: General Rules for All Displays

Write Format

The correct format for write_objects on DisplaysList uses top-level properties directly. The identifier field is Name.

{
  "Name": "MyDisplay",
  "PanelType": "Canvas",
  "DisplayMode": "Page",
  "OnResize": "StretchFill",
  "Size": "1366 x 728",
  "Elements": [...]
}

NEVER use JsonFormat wrapper, ObjectName, or nest properties inside sub-objects. Everything goes at the top level.

Document Objects — Read Before Write

Displays are document objects — full replacement on write. When modifying an existing display, ALWAYS read first, merge your changes, then write back the complete document. Omitted content is deleted.

get_objects('DisplaysList', names=['MainPage'], detail='full')

MainPage is predefined in new solutions. Write main content directly into it — no need to create a new display for the landing screen.

Theming

• OMIT color properties (Fill, Stroke, Foreground) to use themed defaults that respect Light/Dark theme switching
• Only specify colors when intentionally overriding for process-specific meaning (alarm red, water blue)
• When overriding: set the color AND clear the theme — {"Fill": "#FF3498DB", "FillTheme": ""} — otherwise the theme engine silently overrides your color
• Use list_elements('ThemeColors') for available named theme brushes

Symbol Placement Rules (ALL Display Types)

When placing symbols on any display:

• Use @Tag. bindings in SymbolLabels. NEVER use @Label. when placing symbols — @Label. is only for symbol internal definitions (in DisplaysSymbols).
• Wizard Symbols (TANK, VALVE, PUMP, MOTOR, BLOWER) are always available: SymbolName: "Wizard/PUMP".
• Library symbols (~1,600) auto-import when referenced by SymbolName. No manual import needed.
• Sizing: Symbols are vector-based. Width/Height do NOT need to match library defaults. Scale to ANY proportional size that fits your layout. Maintain the aspect ratio to avoid distortion. If a library symbol's default is 120×80, you can use 60×40 or 180×120 — just keep the same ratio.

Step 3: Building Dashboard Displays

Dashboards use a grid defined by DashboardDisplay (Columns/Rows) and a Cells array. Elements auto-fill their cells — no pixel positioning.

Dashboard Rules

• Start simple: Default to a 3 × 2 grid unless the user specifically requests more cells or gives you enough elements to justify a larger grid.
• Don't over-engineer: only add rows/columns when the content demands it.
• If controls/symbols aren't specified, use: Gauges on the first row; TrendChart, AlarmViewer, and DataGrid on the second row.
• TrendChart Duration: Use "1m" (1 minute) for demos and first prototypes so charts populate with data immediately. Use longer durations ("5m", "30m", "1h") only when the user specifies a monitoring window.
• ColSpan/RowSpan for elements that need multiple cells.
• Cell.HeaderLink adds a header label above the cell content.
• Set Width/Height on content elements inside cells, not on the Dashboard itself.
• For Symbols in cells, set Width/Height proportional to the symbol's original aspect ratio so it scales nicely.

Dashboard Example

list_elements('Dashboard')

{
  "table_type": "DisplaysList",
  "data": [{
    "Name": "MainPage",
    "PanelType": "Dashboard",
    "DashboardDisplay": {
      "Columns": ["*", "*", "*"],
      "Rows": ["*", "*"]
    },
    "Cells": [
      {
        "Row": 0, "Col": 0,
        "Cell": { "HeaderLink": "Tank Level" },
        "Content": {
          "Type": "CircularGauge",
          "LinkedValue": "@Tag.Plant/Tank1/Level.Value",
          "Minimum": 0, "Maximum": 100
        }
      },
      {
        "Row": 0, "Col": 1,
        "Cell": { "HeaderLink": "Temperature" },
        "Content": {
          "Type": "CircularGauge",
          "LinkedValue": "@Tag.Plant/Tank1/Temperature.Value",
          "Minimum": 0, "Maximum": 100
        }
      },
      {
        "Row": 0, "Col": 2,
        "Cell": { "HeaderLink": "Trend" },
        "Content": {
          "Type": "TrendChart",
          "Duration": "1m",
          "Pens": {
            "Type": "TrendPenList",
            "Children": [
              { "Type": "TrendPen", "LinkedValue": "@Tag.Plant/Tank1/Level", "PenLabel": "Level", "Stroke": "#FF2196F3", "Auto": true }
            ]
          }
        }
      },
      {
        "Row": 1, "Col": 0, "ColSpan": 3,
        "Cell": { "HeaderLink": "Alarms" },
        "Content": {
          "Type": "AlarmViewer"
        }
      }
    ]
  }]
}

Step 4: Building Canvas Displays

Canvas displays use absolute positioning. Think of it like building a React UI — you're arranging elements on a coordinate plane.

Canvas Build Order: Layout First, Symbols Later

CRITICAL: Do not spend time searching for library symbols at the start. Build the display in two passes:

Pass 1 — Layout and structure:

1. Divide the canvas into logical areas for each process section or information panel
2. Place background Rectangles for visual grouping (use FillTheme: "PanelBackground")
3. Add titles, labels, and value TextBlocks
4. Place controls (gauges, trends, alarm viewers)
5. Use only Wizard symbols (TANK, VALVE, PUMP, MOTOR, BLOWER) for equipment — they're always available, no lookup needed

Pass 2 — Optional library symbols (if needed):

• If you want more specific symbols, THEN browse the library with list_elements('Symbol/HMI/...')
• When placing library symbols, set Width and Height to scale down proportionally so the symbol fits the area you allocated in Pass 1
• Example: if a library symbol's default is 200×150 and your allocated area is 100 wide, use Width: 100, Height: 75

Non-Overlapping Rule

Unless you are intentionally layering elements (e.g., a status indicator on top of a tank), do NOT overlap elements. Tanks, motors, valves — each gets its own space. Overlapping equipment symbols creates a confusing, unreadable display.

Minimum Element Sizes (Non-Negotiable)

Value + Unit Text Pattern

NEVER put value and unit in separate TextBlocks side by side. Use ONE TextBlock with composite LinkedValue:

{
  "Type": "TextBlock",
  "LinkedValue": "Flow: {@Tag.Plant/Intake/FIT_1001} GPM",
  "Left": 30, "Top": 150, "Width": 170, "Height": 24,
  "FontSize": 14
}

Patterns: "Flow: {@Tag.X} GPM" (label + value + unit), "{@Tag.X} NTU" (value + unit), "pH: {@Tag.X}" (label + value).

Symbol Centering in an Area

Symbol.Left = Area.Left + (Area.Width - Symbol.Width) / 2
Symbol.Top  = Area.Top  + offset

Step 5: Canvas Zone-Based Layout (Process Overview Displays)

When building process overview displays with multiple stages (intake → treatment → distribution), use this zone-based approach to ensure the entire canvas is utilized and content is well-organized.

Core Principle: Think in Zones, Not Elements

NEVER start by placing individual elements. Instead:

1. Divide the canvas into zones (rectangular regions for each process section)
2. Size each zone based on content complexity
3. Place elements within zones using coordinates relative to zone origin
4. Connect zones with flow indicators

Zone Calculation for N Process Stages (1366×728 canvas)

Title bar: full width, 50px tall
Available width  = 1366 - 20 (margins)  = 1346
Zone width  = (1346 - (N-1) × 15) / N
Zone height = 320
Zone startY = 60
Zone[i].Left  = 20 + i × (zoneWidth + 15)
Zone[i].Top   = 60
Zone[i].Width = zoneWidth
Zone[i].Height = 320
Bottom panel: Left=20, Top=400, Width=1326, Height=remaining

Zone Background Rectangles (REQUIRED)

Every zone MUST have a background Rectangle for visual grouping, placed FIRST in the Elements array:

{
  "Type": "Rectangle",
  "Left": 20, "Top": 60, "Width": 208, "Height": 320,
  "FillTheme": "PanelBackground",
  "Stroke": "#FF909090", "StrokeThickness": 1
}

Zone Internal Layout

Each process zone follows this vertical pattern from its origin:

• Zone title (FontSize 15–16) at y+10
• Symbol (80×80 to 100×100, centered horizontally) at y+40
• Value labels (FontSize 14, one per line) starting at y+150, spaced 26px apart
• Status indicator (optional) at y+240

Flow Arrows Between Zones

{
  "Type": "TextBlock",
  "Text": "→",
  "Left": 228, "Top": 190, "Width": 15, "Height": 30,
  "FontSize": 20
}

Bottom Panel

Below the process zones, fill remaining space with ONE of:

• Trend + KPI sidebar — TrendChart (w:700) + KPI column
• Trend + Alarm split — TrendChart (w:660) + AlarmViewer (w:640)
• Full-width trend with a status bar above

Bottom panel sections should also use PanelBackground theme background rectangles.

Elements Array Order

1. Zone background Rectangles (render behind everything)
2. Title TextBlock
3. In-page action buttons (start/stop — NOT navigation)
4. Zone titles
5. Symbols (centered in each zone)
6. Value TextBlocks
7. Flow arrows between zones
8. Bottom panel background Rectangle(s)
9. Bottom panel content (TrendChart, AlarmViewer, etc.)
10. Dynamic indicators and status elements

Step 6: Add Visual Dynamics (Canvas Displays Only)

Dynamics attach runtime behaviors to ANY element. They are placed inside the element's Dynamics array. Each dynamic is a separate JSON object within that array. Call list_dynamics() to see all types.

list_dynamics()                      -- all dynamics by category
list_dynamics('FillColorDynamic')    -- full schema for a specific dynamic

FillColorDynamic — Color Changes

{
  "Type": "Rectangle",
  "Left": 100, "Top": 200, "Width": 60, "Height": 60,
  "Dynamics": [
    {
      "Type": "FillColorDynamic",
      "LinkedValue": "@Tag.Plant/Pump1/Running",
      "ChangeColorItems": [
        { "Type": "ChangeColorItem", "ChangeLimit": 0, "LimitColor": "#FF808080" },
        { "Type": "ChangeColorItem", "ChangeLimit": 1, "LimitColor": "#FF00FF00" }
      ]
    }
  ]
}

For analog values, use graduated thresholds (e.g., 0→blue, 60→yellow, 80→orange, 95→red).

VisibilityDynamic — Show/Hide

{
  "Type": "Rectangle",
  "Left": 50, "Top": 100, "Width": 30, "Height": 30,
  "Dynamics": [
    {
      "Type": "VisibilityDynamic",
      "LinkedValue": "@Tag.Plant/Tank1/AlarmActive"
    }
  ]
}

Element visible when non-zero/true, hidden when zero/false.

RotationDynamic — Rotate

{
  "Type": "Ellipse",
  "Left": 200, "Top": 150, "Width": 80, "Height": 80,
  "Dynamics": [
    {
      "Type": "RotationDynamic",
      "LinkedValue": "@Tag.Plant/Fan1/Speed",
      "MinAngle": 0, "MaxAngle": 360,
      "MinValue": 0, "MaxValue": 100
    }
  ]
}

Elements can have multiple dynamics simultaneously in the Dynamics array. Always verify schemas: list_dynamics('DynamicTypeName').

Dynamics Format Rules

• Every dynamic goes inside the element's Dynamics array — NEVER as a direct property on the element.
• ChangeColorItems uses a flat array of ChangeColorItem objects — do NOT wrap in {"Type": "ColorChangeList", "Children": [...]}.
• An element can have multiple dynamics of different types in the same Dynamics array.

Step 7: Click Actions (ActionDynamic)

ActionDynamic defines actions triggered by user interactions. Like all dynamics, it goes inside the element's Dynamicsarray. Navigation is typically in Header displays only.

Standard format — ActionDynamic inside the Dynamics array with explicit mouse event:

{
  "Type": "Button",
  "Text": "Go to Details",
  "Left": 50, "Top": 400, "Width": 150, "Height": 40,
  "Dynamics": [
    {
      "Type": "ActionDynamic",
      "MouseLeftButtonDown": {
        "Type": "DynamicActionInfo",
        "ActionType": "OpenDisplay",
        "ObjectLink": "DetailPage"
      }
    }
  ]
}

Common Action Examples:

// Toggle a digital tag
"Dynamics": [
  {
    "Type": "ActionDynamic",
    "MouseLeftButtonDown": {
      "Type": "DynamicActionInfo",
      "ActionType": "ToggleValue",
      "ObjectLink": "@Tag.Placeholder.DigitalTag"
    }
  }
]

// Navigate to a display
"Dynamics": [
  {
    "Type": "ActionDynamic",
    "MouseLeftButtonDown": {
      "Type": "DynamicActionInfo",
      "ActionType": "OpenDisplay",
      "ObjectLink": "MainPage"
    }
  }
]

// Set a specific value
"Dynamics": [
  {
    "Type": "ActionDynamic",
    "MouseLeftButtonDown": {
      "Type": "DynamicActionInfo",
      "ActionType": "SetValue",
      "ObjectLink": "@Tag.Plant/Flow/FIT_1001",
      "ObjectValueLink": 10
    }
  }
]

// Run a CodeBehind script
"Dynamics": [
  {
    "Type": "ActionDynamic",
    "MouseLeftButtonDown": {
      "Type": "DynamicActionInfo",
      "ActionType": "RunScript",
      "ActionScript": "MouseLeftButtonDown1"
    }
  }
]

Multi-event — same element, different actions for different mouse events:

{
  "Type": "Button",
  "Left": 31.6, "Top": 133.84,
  "LabelLink": "Button",
  "Width": 100, "Height": 32,
  "Dynamics": [
    {
      "Type": "ActionDynamic",
      "MouseLeftButtonDown": {
        "Type": "DynamicActionInfo",
        "ActionType": "RunScript",
        "ActionScript": "MouseLeftButtonDown1"
      }
    }
  ]
}

Step 8: Header Navigation (Multi-Page Solutions)

When a solution has multiple content pages, navigation buttons belong in the Header display — not on content pages.

IMPORTANT: First create all the Content Pages you need, the Header on the end. So you know the pages you need to put in the navigation.

Workflow

1. Read the Startup layout: get_objects('DisplaysLayouts', names=['Startup'], detail='full')
2. Read the Header display: get_objects('DisplaysList', names=['Header'], detail='full')
3. Add navigation buttons right-aligned in the header bar (standard: 100–120px wide × 30–35px tall, 10px gap)
4. Write back the modified Header display

CRITICAL: Do NOT put page navigation buttons on content pages. Content pages only get in-page action buttons (start/stop, acknowledge, open popup). Page-to-page navigation is always in the Header.

Step 9: CodeBehind (Client-Side Display Logic)

CodeBehind is CLIENT-SIDE C# or VB.NET code embedded in each display.

Lifecycle methods: DisplayOpening(), DisplayIsOpen(), DisplayClosing(), DialogOnOK()

Contents field format: {Language}\r\n{Code} — first line is CSharp or VBdotNet.

{
  "Name": "Page1",
  "Engine": "Portable",
  "PanelType": "Canvas",
  "DisplayMode": "Page",
  "OnResize": "StretchFill",
  "Width": 1366,
  "Height": 728,
  "Elements": [
    {
      "Type": "Button",
      "Left": 31.6,
      "Top": 133.84,
      "LabelLink": "Button",
      "Width": 100,
      "Height": 32,
      "Dynamics": [
        {
          "Type": "ActionDynamic",
          "MouseLeftButtonDown": {
            "Type": "DynamicActionInfo",
            "ActionType": "RunScript",
            "ActionScript": "MouseLeftButtonDown1"
          }
        }
      ]
    }
  ],
  "IsOpenInterval": "100",
  "Contents": "CSharp\r\npublic async Task DisplayOpening()\r\n{\r\n\t// Add your code here\r\n\t\r\n}\r\npublic async Task DisplayIsOpen()\r\n{\r\n\t// Add your code here\r\n\t\r\n}\r\npublic async Task DisplayClosing()\r\n{\r\n\t// Add your code here\r\n\t\r\n}\r\npublic async Task<bool> DialogOnOK()\r\n{\r\n\t// Add your code here\r\n\t\r\n\treturn true;\r\n}\r\n\r\npublic async Task MouseLeftButtonDown1(object sender, System.Windows.Input.InputEventArgs e)\r\n{\r\n\t// Add your code here\r\n\t\r\n}"
}

See the Scripts and Expressions skill for full CodeBehind guidance.

Step 10: Layouts and Asset Navigation

Layouts

Layout regions: Header, Footer, Menu, Submenu, Content. The Startup layout defines which display loads into each region.

get_table_schema('DisplaysLayouts')
get_objects('DisplaysLayouts', names=['Startup'], detail='full')

Asset Navigation (Advanced)

For plant-wide navigation with dynamic content:

• Layout with Header + AssetTree (left menu) + Content region
• User selects an asset → Client.Context updates → content displays react
• Static binding: @Tag.Area1/Line1/State
• Dynamic binding: Asset(Client.Context.AssetPath + "State1")

This allows a single display template to show data for whichever asset the operator selects.

Canvas Layout Checklist

Before writing any Canvas display, verify:

• [ ] Areas calculated to fill the FULL canvas width and height
• [ ] Every grouped area has a background Rectangle with FillTheme: "PanelBackground"
• [ ] Background Rectangles are FIRST in the Elements array
• [ ] Symbols are ≥ 80×80 pixels, centered in their areas
• [ ] Library symbol Width/Height scaled proportionally to fit allocated area
• [ ] No equipment symbols overlapping unless intentionally layered
• [ ] Zone titles FontSize ≥ 14, value text FontSize ≥ 12
• [ ] Value and Unit in the SAME TextBlock
• [ ] No element extends beyond the display size
• [ ] Page navigation is in the Header display, NOT on content pages
• [ ] Display identifier field is Name (not ObjectName)
• [ ] PanelType is set at top level
• [ ] All dynamics are inside the element's Dynamics array (never as direct properties)

Common Pitfalls

Quick Reference