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.
Button
Section titled “Button”label is the text on the button. It does not change with the selection. Set
hasIcon to true to show icon before the label.
Properties
Section titled “Properties”| 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
Section titled “Options”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.
Properties
Section titled “Properties”| 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 |
Menu Types
Section titled “Menu Types”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. |
Nested Checkboxes
Section titled “Nested Checkboxes”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}]Flyout
Section titled “Flyout”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.
Columns
Section titled “Columns”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"} ] }]Properties
Section titled “Properties”| 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 |
Selection
Section titled “Selection”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.
Properties
Section titled “Properties”| 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.
Properties
Section titled “Properties”| 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 |
Disabled
Section titled “Disabled”A disabled Menu Button does not open its menu. See Disabled.
Common Properties
Section titled “Common Properties”- Appearance —
style.
Component Events
Section titled “Component Events”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.
Examples
Section titled “Examples”Example 1 — Filter a List
Section titled “Example 1 — Filter a List”- Drop a Menu Button into the view and set
labeltoFilter. - Set
optionsto the categories, for exampleAlarms,WarningsandCautions. - Bind
selectedValuesbidirectionally toview.custom.filter. - Use
{view.custom.filter}in the binding of the list to show only the checked categories.
Found an error or something unclear?
Tell us what is wrong, confusing or missing on this page.
Built on the OpenBridge Design System