## 8.10 Menus

### 8.10.1 Description

A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget.

Menu description records are records of the form `menu(E1 E2 .. Ex param1:value1 ... paramY:valueY)` where `Ex` are records of the form `command(...)`, `checkbutton(...)`, `radiobutton(...)`, `cascade(...)` or `separator`. The first three record types (`command`, `checkbutton` and `radiobutton`) are very similar to the widgets of the same name, and have many parameters in common. The `cascade(...)` record form is similar to the `menu(...)` one as that entry pulls out a sub-menu. The `separator` record inserts an horizontal line.

Menu descriptions usage:

- As the `menu` parameter of the `td` or `lr` toplevel widget. This menu's items will be displayed in a menubar accross the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made (see below).

- As the `menu` parameter of a `menubutton` widget. This is the most usual way of using menu declarations.

- As the parameter of the function `QTk.buildMenu`. This function returns an Oz object representing the described menu. This object can be used as the `menu` parameter of a `menubutton` widget, or alternatively be displayed anywhere on the screen using its `post` method (see below). Warning: `QTk.buildMenu` requires that the menu description specifies a `parent` parameter set to a QTk window existing inside the display where the menu is to be posted. Example:

  > `T={QTk.build td(title:"Test")}
  > M={QTk.buildMenu menu(command(text:"Entry 1")
  > command(text:"Entry 2")
  > parent:T)}
  > {M post(100 100)}`

CLONES

When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed.

### 8.10.2 Parameters

The menu description support the following parameters:

- `x:R`: Where `x` starts from 1 and goes up one by one. `R` must be record describing a valid menu entry. This parameter defines the menu's `x`th entry.

- `activebackground:C`: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. `C` must be a valid color (see Section 8.2)

- `activeforeground:C`: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

- `activeborderwidth:P`: Specifies a non-negative value indicating the width of the 3-D border to draw around active elements. `P` must be a valid screen distance (see Section 8.6).

- `background:C`: or `bg:C`: Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 8.2).

- `borderwidth:P`: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the `relief` option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. `P` must be a valid screen distance (see Section 8.6).

- `cursor:A`: Specifies the mouse cursor to be used for the widget. `A` must be a valid cursor (see Section 8.7)

- `disabledforeground:C`: Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. `C` must be a valid color (see Section 8.2)

- `font:F`: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. `F` must be a valid font (see Section 8.8)

- `foreground:C`: or `fg:C`: Specifies the normal foreground color to use when displaying the widget. `C` must be a valid color (see Section 8.2)

- `relief:A`: Specifies the 3-D effect desired for the widget. Must be one of these atoms: `raised`, `sunken`, `flat`, `ridge`, `solid` or `groove`. The value indicates how the interior of the widget should appear relative to its exterior; for example, `raised` means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

- `takefocus:B`: Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the `takeFocus` option. A value of `false` means that the widget should be skipped entirely during keyboard traversal. `true` means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). `B` must be a boolean.

- `tearoff:B`: Specifies whether or not the menu should include a tear-off entry at the top. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. `B` must be a boolean.

- `title:VS`: Specifies title of the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked.

- `type:A`: This option can be one of the following atoms: `menubar`, `tearoff`, or `normal`, and is set when the menu is created.

- `action:C`: Specifies an Oz command to execute just before the menu is posted.

### 8.10.3 Interface

- `insert(I T)`: Inserts the menu entry specified by `T` at the position the position `I` of the menu. `T` must be a record describing a value menu entry, `I` must be a positive integer.

- `index(I V)`: Binds `V` to the object controlling the menu entry referenced by `I`, or binds `V` to the atom `none` if no menu entry is referenced by `I`. `I` can be one of the following:

  - integer: Specifies the entry numerically, where 1 is the first one (topmost).

  - `active`: Indicates the entry that is currently active. If no entry is active then this form is equivalent to `none`.

  - `end`: Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to `none`.

  - `last`: Same as end.

  - `none`: Indicates ``no entry at all''.

  - `"@"#Y`: Where `Y` is an integer. In this form, `Y` is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used.

- `post(X Y)`: Arrange for the menu to be displayed on the screen at the root-window coordinates given by x and y. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen.

### 8.10.4 Menu entries

Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the `label`, `bitmap`, and `image` options for the entry. If the `accelerator` option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an indicator. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string.

In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is invoked. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries.

Entries may be disabled, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again.

Whenever a menu's active entry is changed, a `MenuSelect` virtual event is send to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry.

#### Tear-off

A tear-off entry appears at the top of the menu if enabled with the `tearoff` option of the menu. It is not an entry like others because it is not created the same way. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus.

#### Command

Description

The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, the Oz command specified by the `action` parameter is executed.

A command menu entry is described by a record of the form:

> `command(parameter1:value1 ... parameterX:valueX)`

Parameters

- `activebackground:C`: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. `C` must be a valid color (see Section 8.2)

- `activeforeground:C`: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

- `background:C`: or `bg:C`: Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 8.2).

- `bitmap:B`: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. `B` can be one of these atoms: `error`, `gray75`, `gray50`, `gray25`, `gray12`, `hourglass`, `info`, `questhead`, `question`, `warning`, or `B` can be a virtual string beginning by `@` and then containing the name of a bitmap description in the standard X11 or X10 format like `"@x11.xbm"` for example.

- `columnbreak:B`: When this option is `true`, the entry appears below the previous entry. When this option is`false`, the menu appears at the top of a new column in the menu.

- `font:F`: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. `F` must be a valid font (see Section 8.8)

- `foreground:C`: or `fg:C`: Specifies the normal foreground color to use when displaying the widget. `C` must be a valid color (see Section 8.2)

- `hidemargin:B`: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. `true` indicates that the margin for the entry is hidden; `false` means that the margin is used.

- `image:I`: Specifies an image or a bitmap built by `QTk.newImage` to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. `I` must be a valid image or bitmap (see Section 8.4 and see Section 8.3)

- `state:A`: Specifies one of three states for the button: `normal`, `active`, or `disabled`. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the `activeforeground` option for the menu along with the `activebackground` option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the `disabledforeground` option for the menu and the `background` option from the entry.

- `underline:I`: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. `I` must be a positive integer.

- `text:VS`: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as `anchor` or `justify`. `VS` must be a virtual string.

- `action:C`: Specifies an action to execute right after the user clicked the entry. `C` can take several different forms (see Section 4.3.1).

- `accelerator:R`: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:

  `key` option value | accelerator | event binding
  --- | --- | ---
  `a` | a | `a`
  `ctrl(a)` | C-a | `<Control-a>`
  `alt(a)` | A-a | `<Alt-a>`
  `alt(ctrl(a))` | A-C-a | `<Alt-Control-a>`
  `ctrl(alt(a))` | C-A-a | `<Control-Alt-a>`
  virtual string | virtual string | none

- `return:V`: If the execution of the action of the button closes the window, Variable is bound to true. In all other cases where the window is closed, Variable is bound to false. This parameter is valid at creation time only. `V` must be a free variable.

- `handle:V`: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `feature:A`: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

Interface

The object controlling the menu entry implements the following methods:

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.

- `invoke`: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.

- `delete`: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

- `position(Y)`: Binds `Y` to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.

- `type(V)`: Binds `V` to the type of the entry (in this case, to `command`).

#### Checkbutton

Description

A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the `selectcolor` option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If an `action` option is specified for a checkbutton entry, then the Oz command is executed each time the user change the state of the entry; this happens after toggling the entry's selected state.

A checkbutton menu entry is described by a record of the form:

> `checkbutton(parameter1:value1 ... parameterX:valueX)`

Parameters

- `1:B`: Specifies whether or not the menu entry is toggled on or off. This option can be used with the `set()` and `get()` methods only. `B` must be a boolean.

- `init:B`: Specifies whether or not the menu entry is toggled on or off. This option can be used at creation time only. `B` must be a boolean.

- `activebackground:C`: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. `C` must be a valid color (see Section 8.2)

- `activeforeground:C`: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

- `background:C`: or `bg:C`: Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 8.2).

- `bitmap:B`: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. `B` can be one of these atoms: `error`, `gray75`, `gray50`, `gray25`, `gray12`, `hourglass`, `info`, `questhead`, `question`, `warning`, or `B` can be a virtual string beginning by `@` and then containing the name of a bitmap description in the standard X11 or X10 format like `"@x11.xbm"` for example.

- `columnbreak:B`: When this option is `true`, the entry appears below the previous entry. When this option is`false`, the menu appears at the top of a new column in the menu.

- `font:F`: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. `F` must be a valid font (see Section 8.8)

- `foreground:C`: or `fg:C`: Specifies the normal foreground color to use when displaying the widget. `C` must be a valid color (see Section 8.2)

- `hidemargin:B`: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. `true` indicates that the margin for the entry is hidden; `false` means that the margin is used.

- `image:I`: Specifies an image or a bitmap built by `QTk.newImage` to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. `I` must be a valid image or bitmap (see Section 8.4 and see Section 8.3)

- `indicatoron:B`: Specifies whether or not the indicator should be displayed. `B` must be a boolean.

- `selectcolor:C`: Specifies the color to display in the indicator when the entry is selected. If the value is `nil` (default) then the `selectcolor` option for the menu determines the indicator color.

- `selectimage:I`: Specifies an image to display in the entry (in place of the `image` option) when it is selected. `I` must be a valid image (see above). This option is ignored unless the `image` option has been specified.

- `state:A`: Specifies one of three states for the button: `normal`, `active`, or `disabled`. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the `activeforeground` option for the menu along with the `activebackground` option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the `disabledforeground` option for the menu and the `background` option from the entry.

- `underline:I`: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. `I` must be a positive integer.

- `text:VS`: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as `anchor` or `justify`. `VS` must be a virtual string.

- `action:C`: Specifies an action to execute right after the user clicked the entry. `C` can take several different forms (see Section 4.3.1).

- `accelerator:R`: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:

  `key` option value | accelerator | event binding
  --- | --- | ---
  `a` | a | `a`
  `ctrl(a)` | C-a | `<Control-a>`
  `alt(a)` | A-a | `<Alt-a>`
  `alt(ctrl(a))` | A-C-a | `<Alt-Control-a>`
  `ctrl(alt(a))` | C-A-a | `<Control-Alt-a>`
  virtual string | virtual string | none

- `return:V`: When the toplevel window is closed, `V` is bound to `true` is the menu entry is selected, otherwise it is bound to `false`.

- `handle:V`: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `feature:A`: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

Interface

The object controlling the menu entry implements the following methods:

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.

- `invoke`: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.

- `delete`: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

- `position(Y)`: Binds `Y` to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.

- `type(V)`: Binds `V` to the type of the entry (in this case, to `checkbutton`).

#### Radiobutton

Description

A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups along with the `radiobutton` and `tbradiobutton` widgets. Widgets are grouped together if their `group` parameters are set to the same atom. Only one entry of a group may be selected at a time. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the `selectcolor` option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If an `action` option is specified for a radiobutton entry, then the specified Oz command is executed just after the user selects the entry.

A radiobutton menu entry is described by a record of the form:

> `radiobutton(parameter1:value1 ... parameterX:valueX)`

Parameters

- `1:B`: Specifies if the button is on or off. If `B` is `true` then the button is selected. All other radiobuttons in the same group are deselected. If `B` is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter can be used with the `set()` and `get()` methods only. `B` must be a boolean.

- `init:B`: Specifies if the button is on or off. If `B` is `true` then the button is selected. All other radiobuttons in the same group are deselected. If `B` is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter is valid at creation time only. `B` must be a boolean.

- `return:V`: When the window is closed, `V` is bound to `true` if the radiobutton, false otherwise. This parameter is valid at creation time only. `V` must be a free variable.

- `action:C`: Specifies an action to execute right after the user clicked the button. `C` can take several different forms (see Section 4.3.1).

- `group:A`: Specifies what group the radiobutton belongs to. All radiobuttons that use the same `A` belong to the same group (only one can be selected at a time in a group). Must be specified at creation time. `A` must be an atom.

- `activebackground:C`: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. `C` must be a valid color (see Section 8.2)

- `activeforeground:C`: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

- `background:C`: or `bg:C`: Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 8.2).

- `bitmap:B`: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. `B` can be one of these atoms: `error`, `gray75`, `gray50`, `gray25`, `gray12`, `hourglass`, `info`, `questhead`, `question`, `warning`, or `B` can be a virtual string beginning by `@` and then containing the name of a bitmap description in the standard X11 or X10 format like `"@x11.xbm"` for example.

- `columnbreak:B`: When this option is `true`, the entry appears below the previous entry. When this option is`false`, the menu appears at the top of a new column in the menu.

- `font:F`: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. `F` must be a valid font (see Section 8.8)

- `foreground:C`: or `fg:C`: Specifies the normal foreground color to use when displaying the widget. `C` must be a valid color (see Section 8.2)

- `hidemargin:B`: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. `true` indicates that the margin for the entry is hidden; `false` means that the margin is used.

- `image:I`: Specifies an image or a bitmap built by `QTk.newImage` to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. `I` must be a valid image or bitmap (see Section 8.4 and see Section 8.3)

- `indicatoron:B`: Specifies whether or not the indicator should be displayed. `B` must be a boolean.

- `selectcolor:C`: Specifies the color to display in the indicator when the entry is selected. If the value is `nil` (default) then the `selectcolor` option for the menu determines the indicator color.

- `selectimage:I`: Specifies an image to display in the entry (in place of the `image` option) when it is selected. `I` must be a valid image (see above). This option is ignored unless the `image` option has been specified.

- `state:A`: Specifies one of three states for the button: `normal`, `active`, or `disabled`. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the `activeforeground` option for the menu along with the `activebackground` option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the `disabledforeground` option for the menu and the `background` option from the entry.

- `underline:I`: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. `I` must be a positive integer.

- `text:VS`: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as `anchor` or `justify`. `VS` must be a virtual string.

- `accelerator:R`: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:

  `key` option value | accelerator | event binding
  --- | --- | ---
  `a` | a | `a`
  `ctrl(a)` | C-a | `<Control-a>`
  `alt(a)` | A-a | `<Alt-a>`
  `alt(ctrl(a))` | A-C-a | `<Alt-Control-a>`
  `ctrl(alt(a))` | C-A-a | `<Control-Alt-a>`
  virtual string | virtual string | none

- `handle:V`: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `feature:A`: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

Interface

The object controlling the menu entry implements the following methods:

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.

- `invoke`: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.

- `delete`: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

- `position(Y)`: Binds `Y` to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.

- `type(V)`: Binds `V` to the type of the entry (in this case, to `radiobutton`).

#### Cascade

Description

A cascade entry is one with an associated menu (determined by the `menu` option). Cascade entries allow the construction of cascading menus.

A cascade menu entry is described by a record of the form:

> `cascade(parameter1:value1 ... parameterX:valueX)`

Parameters

- `activebackground:C`: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. `C` must be a valid color (see Section 8.2)

- `activeforeground:C`: Specifies the foreground color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

- `background:C`: or `bg:C`: Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 8.2).

- `bitmap:B`: Specifies a Tk pre-defined bitmap to display in the widget, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. `B` can be one of these atoms: `error`, `gray75`, `gray50`, `gray25`, `gray12`, `hourglass`, `info`, `questhead`, `question`, `warning`, or `B` can be a virtual string beginning by `@` and then containing the name of a bitmap description in the standard X11 or X10 format like `"@x11.xbm"` for example.

- `columnbreak:B`: When this option is `true`, the entry appears below the previous entry. When this option is`false`, the menu appears at the top of a new column in the menu.

- `font:F`: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. `F` must be a valid font (see Section 8.8)

- `foreground:C`: or `fg:C`: Specifies the normal foreground color to use when displaying the widget. `C` must be a valid color (see Section 8.2)

- `hidemargin:B`: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. `true` indicates that the margin for the entry is hidden; `false` means that the margin is used.

- `image:I`: Specifies an image or a bitmap built by `QTk.newImage` to display in the widget. Typically, if the image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the image option may be reset to an empty string to re-enable a bitmap or text display. This parameter can't be get at runtime, however it can be set. `I` must be a valid image or bitmap (see Section 8.4 and see Section 8.3)

- `state:A`: Specifies one of three states for the button: `normal`, `active`, or `disabled`. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the `activeforeground` option for the menu along with the `activebackground` option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the `disabledforeground` option for the menu and the `background` option from the entry.

- `underline:I`: Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. `I` must be a positive integer.

- `text:VS`: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as `anchor` or `justify`. `VS` must be a virtual string.

- `action:C`: Specifies an action to execute right after the user clicked the entry. `C` can take several different forms (see Section 4.3.1).

- `accelerator:R`: Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows:

  `key` option value | accelerator | event binding
  --- | --- | ---
  `a` | a | `a`
  `ctrl(a)` | C-a | `<Control-a>`
  `alt(a)` | A-a | `<Alt-a>`
  `alt(ctrl(a))` | A-C-a | `<Alt-Control-a>`
  `ctrl(alt(a))` | C-A-a | `<Control-Alt-a>`
  virtual string | virtual string | none

- `menu:O`: Specifies the menu that is posted when the user selects the cascade entry. `O` must be a record describing a proper menu. See Section 8.10 for menu details.

- `handle:V`: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `feature:A`: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

Interface

The object controlling the menu entry implements the following methods:

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.

- `invoke`: Invoke the action of the menu entry. If the menu entry is disabled then nothing happens.

- `delete`: Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

- `position(Y)`: Binds `Y` to a positive integer giving the y-coordinate within the menu window of the topmost pixel of the entry.

- `type(V)`: Binds `V` to the type of the entry (in this case, to `cascade`).

#### Separator

Description

A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance.

A separator menu entry is described by a record of the form:

> `separator(parameter1:value1 ... parameterX:valueX)`

Parameters

- `columnbreak:B`: When this option is `true`, the entry appears below the previous entry. When this option is`false`, the menu appears at the top of a new column in the menu.

- `hidemargin:B`: Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. `true` indicates that the margin for the entry is hidden; `false` means that the margin is used.

- `handle:V`: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `feature:A`: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

Interface

The object controlling the menu entry implements the following methods:

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.

- `type(V)`: Binds `V` to the type of the entry (in this case, to `separator`).