Skip to content

Menu Button

The Menu Button is a button with a fixed label that opens a menu of options. By default the operator can check several options, for example to choose what a list or a chart shows. It is found in the Input - OpenBridge section of the Perspective Component Palette as Menu Button.

The Menu Button is one of the input components. Values, events, disabling and the behavior in the Designer are shared by all of them and are described in Input Components — Common Features. This page covers what is specific to the Menu Button.

Note: The menu does not open in the Designer, not even in Preview Mode. Try the component in a session.

label is the text on the button. It does not change with the selection. Set hasIcon to true to show icon before the label.

Name Description Property Type
label Text on the button. Default Menu button. value
hasIcon Show an icon before the label. Default false. value
icon The icon, chosen with the icon picker. Only shown when hasIcon is true. object

options is the list in the menu. Each option has a value, a label and an optional icon:

[
{"value": "alarms", "label": "Alarms"},
{"value": "warnings", "label": "Warnings"},
{"value": "cautions", "label": "Cautions"}
]

Give every option a different value. A value can be a text, a number or true/false.

Name Description Property Type
options The options in the menu. A Menu Button dropped from the palette starts with three examples. array
options[].value Value written to selectedValues when the option is checked. value
options[].label Text shown for the option. value
options[].icon Icon before the text, chosen with the icon picker. Optional. Not shown on a checkbox. object

menuType sets how the menu is laid out:

menuType Menu
regular (default) A plain list. With multiSelect on, every option gets a checkbox.
checkboxes A list with a checkbox on every option.
nested-checkboxes A tree of checkboxes. options[].level sets how far each option is indented.
flyout Options with children open a submenu.
multi options split into columns of itemsPerColumn options.
multi-with-subtitles Columns in groups with a subtitle each, from columnGroups instead of options.

Give each option a level, starting at 1. Each level is indented 16 px more than the one before. The level only indents the option: checking an option does not check the options under it.

[
{"value": "engines", "label": "Engines", "level": 1},
{"value": "me-port", "label": "Main engine port", "level": 2},
{"value": "me-stbd", "label": "Main engine starboard", "level": 2},
{"value": "thrusters", "label": "Thrusters", "level": 1}
]

An option with children opens a submenu with those options. One level of submenus is supported:

[
{
"value": "theme",
"label": "Theme",
"children": [
{"value": "day", "label": "Day"},
{"value": "night", "label": "Night"}
]
},
{"value": "help", "label": "Help"}
]

With multiSelect on, the options in a submenu get checkboxes, but an option without children stays a plain item: choosing it replaces the whole selection with that one option.

multi splits options into columns of itemsPerColumn options. multi-with-subtitles reads columnGroups instead. Each group has a title, the number of columns it spans and its own options. While columnGroups is empty, it shows options in columns titled Group 1, Group 2 and so on:

[
{
"title": "Port",
"columns": 1,
"options": [
{"value": "p1", "label": "Pump 1"},
{"value": "p2", "label": "Pump 2"}
]
},
{
"title": "Starboard",
"columns": 1,
"options": [
{"value": "s1", "label": "Pump 1"},
{"value": "s2", "label": "Pump 2"}
]
}
]
Name Description Property Type
menuType Layout of the menu, see the table above. Default regular. value
options[].level Indent level in the nested-checkboxes menu, starting at 1. value
options[].children Options of the submenu in the flyout menu. array
itemsPerColumn Options per column in the multi and multi-with-subtitles menus. Default 5, at least 1. value
columnGroups Groups of columns for the multi-with-subtitles menu. Only shown for that menu type. array

selectedValues is the list of values of the checked options. When the operator checks or unchecks an option, the component writes the new list to selectedValues and then fires onChange. Bind it bidirectionally to keep the selection, for example in a session property.

The values are written with the type they look like: 2 is written as the number 2, true and false as booleans, anything else as text.

With multiSelect at true (the default) the options get checkboxes and the menu stays open while the operator checks options. With multiSelect at false only one option can be selected and the menu closes when the operator chooses one. The checkboxes and nested-checkboxes menus are the exception: they keep their checkboxes, so the menu closes after each choice but the checked options add up. Set multiSelect to null to let menuType decide: checkboxes, nested-checkboxes, multi and multi-with-subtitles are then multi-select, regular and flyout are not.

With multiSelect off, selectPerGroup allows one selected option in each flyout submenu or column instead of one in the whole menu — for example one theme and one language.

Name Description Property Type
selectedValues Values of the checked options. Written when the operator changes them. Empty by default. array
multiSelect Let the operator check several options. null follows menuType. Default true. value
selectPerGroup One selected option per submenu or column. Only used with multiSelect off. Default false. value

The menu opens to the right of the button, level with its top edge. It does not move to stay on screen and a long menu does not scroll, so leave room to the right of and below the button.

Name Description Property Type
hasTitleBar Show a title bar with a close button at the top of the menu. Default false. value
menuTitle Text of the title bar. Only shown when hasTitleBar is true. value
fullWidth Make the button fill the width of the component. Default false. value

A disabled Menu Button does not open its menu. See Disabled.

Unlike most input components, the Menu Button does not have onActionPerformed. It has four events of its own:

Event Description Event Object
onChange Fired when the operator changes the selection, after selectedValues has been written. See below
onItemClick Fired when the operator clicks an option without a checkbox. See below
onOpen Fired when the menu opens. —
onClose Fired when the menu closes. —

The event object of onChange:

Name Description Property Type
selectedValues Values of the checked options: the new list, the same as selectedValues. array

The event object of onItemClick:

Name Description Property Type
value value of the clicked option. value

The values have the type they look like, as in selectedValues: 2 is the number 2, true and false are booleans, anything else is text.

Clicking an option with a checkbox fires only onChange. In a flyout menu, onItemClick also fires for a submenu’s header: when the operator opens the submenu, and again when they click an option inside it. onClose fires however the menu closes, also when it closes by itself after a choice in a single-select menu.

def runAction(self, event):
system.perspective.print(event.selectedValues)

See Events.

  1. Drop a Menu Button into the view and set label to Filter.
  2. Set options to the categories, for example Alarms, Warnings and Cautions.
  3. Bind selectedValues bidirectionally to view.custom.filter.
  4. Use {view.custom.filter} in the binding of the list to show only the checked categories.

Built on the OpenBridge Design System