Using the list layout manager with menus

Using the list layout manager with menus
Prev	Chapter 24. Menus	Next

An x::w::listlayoutmanager is a layout manager for x::w::menus in the menu bar, and for any sub-menus. This is the same list layout manager that manages selection lists. A std::vector of x::w::list_item_params specifies the new list items for the append_items(), insert_items(), replace_items(), and replace_all_items() methods.

With selection lists, each x::w::list_item_param is typically a label. It is (derived from) a std::variant; and can take on additional values, such as: the shortcut for a menu item; a callback that gets invoked whenever the menu item gets selected; and several other menu item specific attributes.

This is done by passing all attributes for a menu item as additional x::w::list_item_param values before the new menu item itself:

m->append_items(
      {
            x::w::shortcut{"Alt", 'N'},
            []
            (ONLY IN_THREAD,
             const x::w::list_item_status_info_t &info)
            {
                std::cout << "File->New selected" << std::endl;
            },
            "New",

            x::w::shortcut{"Alt", 'O'},
            []
            (ONLY IN_THREAD,
             const x::w::list_item_status_info_t &info)
            {
                std::cout << "File->Open selected" << std::endl;
            },
            "Open",
      });

append_items() only needs one parameter, a vector of x::w::list_item_param. Each menu item's attributes must appear before the "real" x::w::list_item_param. This example creates two new menu items, "New" and "Open", specifying an optional keyboard shortcut for the new item and a callback that gets invoked whenever the menu item gets selected. This is the most common case. The callback's parameter is the usual x::w::list_item_status_info_t whose item_number member reports which menu item got clicked on, and a selected flag that reports whether this menu option is now drawn with a mark, or not (see below).

Menu item attributes

Multiple attributes may appear in any order, but all attributes precede the x::w::list_item_param that creates the new item. An exception gets thrown if append_items(), insert_items(), replace_items(), and replace_all_items() methods receive a vector that ends with one or more attributes, and no actual menu item.

Other available attributes are:

x::w::inactive_shortcut

This attribute shows a keyboard shortcut for its menu item, but without actually implementing the shortcut itself. Presumably, the keyboard shortcut gets implemented separately.

This option exists mainly for the benefit of the default default Copy/Cut/Paste context menu for text input fields. The text input field directly implements the keyboard commands for copying/cutting/pasting text. The context popup menu lists the keyboard shortcuts only for informational purposes.

x::w::menuoption

This value specifies that selecting the following item toggles a mark, typically a bullet, next to the menu item. This is in addition to invoking the item's callback:

m->append_items(
      {
		x::w::menuoption{},
		[]
		(ONLY IN_THREAD,
                 const x::w::list_item_status_info_t &info)
		{
			std::cout << "View->Tools: " << info.selected
				  << std::endl;
		},
		"Tools"
      });

Mutually exclusive radio-button type groups of menu options get created by passing a radio group identifier:

m->append_items(
      {
		x::w::menuoption{"group1@examples.w.libcxx.com"},
                x::w::selected{},
		[]
		(ONLY IN_THREAD,
                 const x::w::list_item_status_info_t &info)
		{
                            // ...
		},
		"Standard",
		x::w::menuoption{"group1@examples.w.libcxx.com"},
		[]
		(ONLY IN_THREAD,
                 const x::w::list_item_status_info_t &info)
		{
                            // ...
		},
		"Enhanced",
      });

This example adds two selectable menu options, “Standard” and “Enhanced”. The same label, “group1@examples.w.libcxx.com” gets specified for bnoth menu options, placing them in the same radio-button style group. The first one is initially selected (prefixed by a bullet icon). Selecting either one automatically deselects the other one.

x::w::selected

This entry specified that its menu option is initially selected.

x::w::submenu

This is a wrapper for a callback that creates a new sub-menu:

m->append_items(
      {
            x::w::submenu{
                [](const x::w::listlayoutmanager &submenu_layoutmanager)
                {
                      // ...
                }},
            "Recent..."
      });

This creates a "Recent..." menu item that opens a sub-menu. x::w::submenu specifies a creator lambda that receives a x::w::listlayoutmanager for the sub-menu. The creator callback uses it to create the sub-menu.

Note

Sub-menus cannot have keyboard shortcuts.

Separators

menu.C gives an example of passing a x::w::separator values between the "Close" and "Toggle Options" items of its "File" menu.

This draws a horizontal line to visually separate groups of items in a menu. Separators typically appear in menus, but separators can also be added to ordinary selection list elements or combo-boxes. Each separator is considered to be a reserved list item. The list layout manager numbers all items in the list consecutively, starting with item #0, and a separator takes up a list item number; but a separator item cannot actually be selected with a keyboard or mouse pointer, which simply skips over the separators. Separator items cannot have any attributes of their own.