Configuring Menus

Menus are interactive DDOs that present a list of commands or actions organized in a hierarchical tree. SAMMI Web supports three distinct menu modes, each determined by the DDO’s name.

Menu Modes

Important: Every Menu DDO requires a DDO name. The editor will block saving if a Menu has no name or still uses the default auto-generated name (e.g. “Menu 1”).

Creating a Menu

Step 1: Add the DDO

1. Open the DDO Palette (toolbar or keyboard shortcut)
2. Select Menu from the Dynamic Objects section
3. Click or drag on the canvas to place it

Step 2: Set the DDO Name

1. With the Menu selected, open the AFD Panel (Property Inspector)
2. In the header, find the DDO Name field (marked with a red asterisk)
3. Enter one of:
   • $MAINPANEL — for a menu bar across the top
   • $MAINMENU — for a page-level right-click context menu
   • A custom name (e.g. pump_options) — for a DDO-specific popup menu

Step 3: Add Menu Items

1. Switch to the DFD Panel → Items tab
2. Click ＋ Add Item to add a top-level menu item
3. Set the item’s Label (display text) and Command (action to execute)
4. To create submenus (cascade levels), click the → indent button to nest an item under its parent
5. Use the ← outdent button to promote an item back up a level
6. Use ↑ / ↓ buttons to reorder items
7. Add separators with the separator button to group related items visually

Step 4: Configure Commands

For each menu item that should trigger an action:

Menu Bar ($MAINPANEL)

The $MAINPANEL menu renders as a full-width horizontal menu bar pinned to the top of the page — the standard application menu bar pattern.

Editor Appearance

In StudioWeb, the $MAINPANEL menu is rendered WYSIWYG: it appears as a full-width bar across the top of the canvas, showing all top-level items horizontally. This is a significant improvement over legacy SAMMI, where the menu bar was an invisible placeholder during design.

• The bar spans the full canvas width at y=0
• Top-level items display horizontally as clickable buttons
• Clicking a top-level item opens its dropdown submenu
• Submenus with children show a ▶ arrow and cascade on hover
• Orientation is forced to Horizontal regardless of the DFD setting

Runtime Behavior

At runtime, the menu bar appears at the top of the page window. Users click a top-level item to open its dropdown, then select a command.

Example Structure

File
├── Open Page...        (cmd: aw)
├── Close Page          (cmd: dw)
├── ────────            (separator)
└── Exit                (cmd: logoff)
Edit
├── Preferences...      (cmd: preferences)
└── Reset Layout        (cmd: recall-window)
View
├── Zoom In             (cmd: zoom -i)
├── Zoom Out            (cmd: zoom -o)
├── ────────            (separator)
├── Layer Control       (cmd: layer-control)
└── Show Active Formats (cmd: show-active-formats)

Page Context Menu ($MAINMENU)

The $MAINMENU menu is a popup that appears when the user right-clicks on the page background (not on a DDO).

Editor Appearance

Since context menus are invisible at runtime until triggered, the editor renders $MAINMENU as a ghosted overlay:

• 40% opacity — clearly communicates “hidden at runtime”
• Dashed border — visual cue that this is an overlay element
• Label badge: $MAINMENU · right-click context menu
• Moveable — drag it anywhere on the canvas to keep it out of the way of other objects

To edit: left-click the ghosted menu to select it, then use the DFD Items tab.

Runtime Behavior

At runtime, right-clicking on empty page background opens this menu at the cursor position.

Example Structure

Refresh Display         (cmd: refresh)
────────                (separator)
Add Window...           (cmd: aw)
Delete Window...        (cmd: dw)
────────                (separator)
Zoom
├── 50%                 (cmd: zoom 50)
├── 100%                (cmd: zoom 100)
└── 200%                (cmd: zoom 200)
────────                (separator)
About                   (cmd: about)

Popup Option Menu (Custom Name)

A Menu DDO with any name other than $MAINPANEL or $MAINMENU becomes a popup option menu — a context menu associated with a specific DDO on the page. The user right-clicks on that DDO at runtime to see the menu.

Linking a Popup Menu to a DDO

1. Create a Menu DDO and name it (e.g. pump_options)
2. Select the target DDO (e.g. a Gauge or Real field)
3. In the target DDO’s AFD Panel → Input section, set Popup DDO Name to pump_options
4. The menu is now linked — it will appear when the user right-clicks that DDO at runtime

Editor Appearance

Popup option menus are rendered as ghosted overlays, similar to $MAINMENU:

• 40% opacity with dashed border
• Label badge shows the association:
  • pump_options · popup for "Gauge 1" (when linked to a DDO)
  • pump_options · popup option menu (unattached) (when no DDO references it yet)
• Auto-anchoring: When a DDO references this menu, the ghost automatically positions itself at the lower-left corner of that DDO, visually showing the association
• Moveable when unattached: If no DDO references it yet, the menu stays at its placed position and can be dragged around

Runtime Behavior

At runtime, right-clicking on the target DDO opens this menu at the cursor position.

Example: Pump Control Menu

Menu DDO name: pump_options
Linked to: Gauge DDO "pump_speed" (via popupDDOName)

Start Pump              (cmd: start_pump, server: peer_slow)
Stop Pump               (cmd: stop_pump, server: peer_slow)
────────                (separator)
View Details            (cmd: aw pump_detail, server: $local-cmd)
View Trend              (cmd: aw pump_trend, server: $local-cmd)

Using $local-cmd

When a menu item should execute a local SAMMI command (like opening a page or deleting a window), set the Logical Server to $local-cmd. The command string is then processed by the RuntimeWeb command executor directly.

Common local commands:

Without $local-cmd, the command is sent to the specified logical server (peer) via the Gateway for remote execution.

DFD Properties Reference

General Tab

Appearance Tab

Items Tab

The Items tab provides a tree editor for building the menu hierarchy:

Each item has:

Tips

• $MAINPANEL is WYSIWYG — you can see exactly how the menu bar will look while designing
• Start with $local-cmd for navigation menus — add-window and delete-window cover most use cases
• Use accelerator text to hint at keyboard shortcuts (display only in current implementation)
• Cascade depth — menus support unlimited nesting levels via the indent button
• Separators improve readability — group related commands with separator lines between them
• One $MAINPANEL per page — only one menu bar can be active; additional ones will overlap
• One $MAINMENU per page — only one page-level context menu is supported
• Multiple popup menus — different DDOs can each have their own popup option menu
• Ghost menus are moveable — drag them out of the way if they overlap other objects during design
• Layer trick — put ghost menus on a separate layer and hide it when you don’t need to see them

See Also

• Adding DDOs to a Page
• Editing DDO Properties
• Configuring Push Buttons — buttons also use commands and logical servers
• Configuring Data Bindings — readKey/writeKey for data-driven menus