Name
MENU -- create a menu strip (V6.0)
Synopsis
@MENU id, table
Function
This preprocessor command can be used to create a menu strip that can later be attached to one or more displays by calling SetDisplayAttributes() on an existing display or by specifying the Menu tag in the @DISPLAY preprocessor command or in the CreateDisplay() call.

You need to pass an identifier for the menu strip to this preprocessor command as well as the actual menu definition. Menus are defined as a tree structure that is composed of a master table that contains various subtables. There are two different types of subtables:

  1. Menu tables: These tables contain a heading for the menu in the table element at index 0 and a list of single menu items in the table element at index 1. The list of single menu items, of course, is another subtable that is composed of another number of tables that describe a menu item each (see below). The table you pass to @MENU must start with a number of menu tables because every menu item needs a parent menu that it belongs it. These parent menus are described in the menu tables. You can also nest menus, i.e. it is possible to insert a submenu among a number of menu items.

  2. Menu item tables: A menu item subtable is a table that describes a single menu item. The name of the menu item that is to be shown in the menu has to be passed at table index 0. If you pass an empty string ("") at table index 0, Hollywood will insert a horizontal divider bar instead of a selectable menu item. These divider bars can be used to group related menu items together. There must not be any element at table index 1 for menu item tables. Instead, you can use a number of other tags to configure things like menu item type, hotkey, and identifier. See below for a list of possible tags.

Menu item tables recognize the following tags:

ID:
Here you can specify a string that identifies this menu item. This string will be passed to your event handler callback so that you know which menu item has been selected by the user. The identifier specified here is also necessary if you want to use functions like DisableMenuItem() or SelectMenuItem() to manually modify the state of menu items.

Flags:
This tag allows you to set some flags for this menu item. This can be set to a bitmask containing one or more of the following flags:

#MENUITEM_TOGGLE:
If this flag is set, this menu item will be created as a toggle menu item. Toggle menu items have two different states (selected and deselected) and the window manager usually renders them with a checkmark indicating their current state. You can manually modify the toggle state of a menu item by calling the functions SelectMenuItem() and DeselectMenuItem() or by setting the #MENUITEM_SELECTED flag (see below). The toggle state can be checked by calling the IsMenuItemSelected() function.

#MENUITEM_RADIO:
Set this flag to make the menu item part of a radio group. All neighbouring menu items which have #MENUITEM_RADIO set, will be included in the same radio group. All menu items inside a radio group will be mutually exclusive, i.e. only one menu item of a radio group can be active at a time. You can manually modify the state of a radio menu item by calling the functions SelectMenuItem() or by setting the #MENUITEM_SELECTED flag (see below). The radio state can be checked by calling the IsMenuItemSelected() function. Since radio groups always need an active item, it is not possible to call DeselectMenuItem() on a radio menu item. If you want to deselect a radio menu item, you need to select a different radio menu item using SelectMenuItem() and then the previously selected radio menu item will automatically be deselected. (V7.1)

#MENUITEM_SELECTED:
If you have set the #MENUITEM_TOGGLE or #MENUITEM_RADIO flag to create a toggle or a radio menu item, you can set this flag to put the menu item into selected state. See above for more information on toggle and radio menu items.

#MENUITEM_DISABLED:
If you set this flag, the menu item will be grayed out so that the user won't be able to select it. You can also manually disable a menu item by calling the function DisableMenuItem(). To enable a disabled menu item, use EnableMenuItem(). The disabled state of a menu item can be checked by calling the IsMenuItemDisabled() function.

Hotkey:
This tag can be set to a character that acts as a key shortcut for this menu item. For the best cross-platform compatibility, this tag should be set to a string that contains one character only, e.g. "q" for a quit shortcut. Some platforms also support custom hotkeys like "CTRL+F1" but in that case you often have to implement the key handling on your own because the window manager does not support listening to these special shortcuts. If you pass a one character string, however, automatic hotkey listening will work on all platforms.

Menu strips can also be created at runtime by using the CreateMenu() command. See CreateMenu for details.

You can attach menu strips to displays by using the SetDisplayAttributes() function or by specifying the Menu tag in the @DISPLAY preprocessor command or in the CreateDisplay() call. To detach a menu strip from a display, call SetDisplayAttributes() passing the special value -1 in the Menu tag.

To get notified when the user selects items from the menu, you have to listen to the OnMenuSelect event handler. This can be done by installing a listener callback for this event using InstallEventHandler(). See InstallEventHandler for details.

Please note that menu strips are not supported for displays in fullscreen mode. They will only work if your display is in windowed mode.

Note that on Android, it's normally not possible to place menu items in the root level of the action bar's options menu because on desktop systems menu items always have to be members of certain root groups (e.g. "File", "Edit", "View", etc.) There can't be any menu items outside such root groups. When using menu strips on Android, Hollywood will of course replicate the desktop menu behaviour by creating individual submenus for those root groups. This means, however, that the user has to tap at least twice to select a menu item because there won't be any menu items in the root level, they will always be in submenus instead. So if you don't want Hollywood to create those submenus but just place all items in the root level, set the SingleMenu tag in the @DISPLAY preprocessor command to True. This is especially useful if there are only a few menu items and it doesn't make sense to place them in submenus.

Also note that menu strips are currently unsupported on Linux and iOS.

Inputs
id
a value that is used to identify this menu strip
table
menu tree definition (see above)
Example
@MENU 1, {
    {"File", {
        {"New", ID = "new"},
        {"Open...", ID = "open"},
        {""},
        {"Close", ID = "close", Flags = #MENUITEM_DISABLED},
        {""},
        {"Save", Flags = #MENUITEM_DISABLED, Hotkey = "S"},
        {"Compress", ID = "cmp", Flags = #MENUITEM_TOGGLE},
        {""},
        {"Export image...", {
            {"JPEG...", ID = "jpeg"},
            {"PNG...", ID = "png"},
            {"BMP...", ID = "bmp"}}},
        {""},
        {"Dump state", ID = "dump"},
        {""},
        {"Quit", ID = "quit", Hotkey = "Q"}}},

    {"Edit", {
        {"Cut", ID = "cut"},
        {"Copy", ID = "copy"},
        {"Paste", ID = "paste"}}},

    {"?", {
        {"About...", ID = "about"}}}
    }

@DISPLAY {Menu = 1}
The code above creates a menu strip that is attached then attached to the default display.

Show TOC