Provides a button (with icon and/or label) with an OS-native popup menu to select from a list of options.

Example

-- Create a new option menu (and add it to some existing box) that shows a
-- list of colors.  The idea is that the optionmenu button will take the
-- color based on the custom color field, unless that's absent in which
-- case it will fall back to id (which is *not* a custom field, that's part
-- of the menu spec defined by rtk.NativeMenu).
local colors = box:add(rtk.OptionMenu{
    menu={
        {'Blue', id='blue', color='cornflowerblue'},
        {'Red', id='red'},
        {'Green', id='green', color='seagreen'},
        {'Purple', id='purple'},
    },
})
-- Add a custom handler when the selected item changes and set the button to
-- the selected color.
colors.onchange = function(self, item)
    self:attr('color', item.color or item.id)
end
-- Initialize to blue.  Note here we can use either the id field or the item's
-- index (in this case 1). And because we've added the onchange handler above,
-- that will fire now as a result of calling this, setting the button to this
-- color.
colors:select('blue')
-- Incidentally, this is equivalent, although a bit less visually streamlined
colors:attr('selected', 'blue')

Which looks like this when open:

Remember, optionmenus are buttons (styled with the tagged attribute set to true), so all the attributes from rtk.Button apply here as well. In particular, the icon attribute can be used to override the default triangle icon.

Attributes

rtk.OptionMenu.menu table read/write ¶

A table that describes the menu layout per rtk.NativeMenu (default nil). The table format is the same as that described for rtk.NativeMenu:set().

In addition to all the fields defined by rtk.NativeMenu:set(), menu items can also receive an altlabel field, which, if defined, is the label used in the OptionMenu button when the item is selected (provided icononly is false). This allows different display strings for the item in the popup menu and the button's label when selected.

rtk.OptionMenu.icononly boolean read/write ¶

If true, only shows the icon in the button, and not the label of the selected item (default false). Useful when using as a button-based popup menu, for example as part of a toolbar.

rtk.OptionMenu.selected string or number read/write ¶

The id or index of the selected item (default nil). You can set this attribute to change the option menu selection, which is equivalent to calling select().

You may set this attribute to either the menu item id or its index, however when it's set implicitly after a user changes the selection by selecting an item from the menu, it will always favor the menuitem's id if it exists, and will fall back to the item's index if not. For this reason, you may find it more convenient to use selected_index, selected_id, or even selected_item as these are unambiguous.

rtk.OptionMenu.selected_index number or nil read-only ¶

The index of the selected menu item, or nil if nothing is selected (default nil). This attribute cannot be set; use the selected attribute to change the selection.

rtk.OptionMenu.selected_id string or nil read-only ¶

The user-supplied id of the selected menu item, or nil if nothing is selected or if the item doesn't have an user-defined id (default nil). This attribute cannot be set; use the selected attribute to change the selection.

rtk.OptionMenu.selected_item table or nil read-only ¶

The table of the selected menu item, as it was defined in the menu, or nil if nothing is selected (default nil). This attribute cannot be set; use the selected attribute to change the selection.

Methods

rtk.OptionMenu(attrs, ...) ¶

Create a new option menu widget with the given attributes.

rtk.OptionMenu:select(value, trigger) ¶

Selects the current item based on id or index. This is exactly equivalent to setting the selected attribute directly, and is only offered as a slightly more readable shorthand.

Parameters

value	(number, string or nil)	the user-defined id of the menu item to be selected, or its index. It can also be nil to programmatically remove the selection.
trigger	(boolean)	same as rtk.Widget:attr().

Return Values

(rtk.OptionMenu)

returns self for method chaining

rtk.OptionMenu:open() ¶

Opens the popup menu programmatically.

Normally the menu would be opened by the user clicking the button, but it can also be opened programmatically using this method.

onchange() will be fired if the selected item changes.

See also handlers for rtk.Widget.

rtk.OptionMenu:onchange(item, lastitem) ¶

Called when the selection changes.

This differs from onselect() in that this is only called when the current selection has changed from the previous value, and the trigger argument to select() is ignored.

Parameters

item	(table or nil)	the table of the menu item as passed to the menu attribute, or nil if selection was removed or invalid. This can only happen if an invalid (or nil) value was programmatically assigned to the selected attribute, and cannot happen through user interaction.
lastitem	(table or nil)	the item table for the previously selected item that has just been replaced.

Return Values

(nil)

Return value has no significance. This is a notification event only.

rtk.OptionMenu:onselect(item, lastitem) ¶

Called when select() is called, or when the user makes a selection from the popup menu.

Note

This differs from onchange() in that this handler is called even when the user's selection is the same as the last selected value. This is useful when using an rtk.OptionMenu as a popup menu to activate commands in which the last selected item may be invoked multiple times.

Parameters

item	(table or nil)	the table of the menu item as passed to the menu attribute, or nil if selection was removed or invalid. This can only happen if an invalid (or nil) value was programmatically assigned to the selected attribute, and cannot happen through user interaction.
lastitem	(table or nil)	the item table for the previously selected item, which may be the same as the new item if the current item was re-selected.

Return Values

(nil)

Return value has no significance. This is a notification event only.