[Chapter 18] 18.14 The Menubutton Widget
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:59:03Z

#

| Chapter 18 Perl/Tk |

## 18.14 The Menubutton Widget

Create a menubutton with the `Menubutton` method. For example:

>     $mainwindow->Menubutton(-text => "File",
>     	-menuitems => [ [ 'command' => "New",
>     			  "-command" => \&newfile,
>     			  "-underline" => 0 ],
>     			[ 'command' => "Open",
>     			  "-command" => \&openfile,
>     			  "-underline" => 0 ],
>     			"-",
>     			[ 'command' => "Save",
>     			  "-command" => \&savefile,
>     			  "-underline" => 0 ],
>     			[ 'command' => "SaveAs",
>     			  "-command" => \&saveasfile,
>     			  "-underline" => 4 ] ] );

The `-menuitems` option takes a list of lists describing the menu items. For each menu item, an embedded anonymous list describes the type of menu item, the label to use, and the action to take when it is selected along with any other options desired to configure the menu item. In this example, each of the menu items is the `'command'` type, and we use the `-command` option for each item to point to the callback to execute when the menu item is selected. We also use the `-underline` option to enable the user to select a menu item using keystrokes. (The `\[`quotedbl`]-"` represents a separator between menu items.)

In addition to `'command'`, other types of menus are:

`'cascade'`

  Embeds a cascade menu.

`'checkbutton'`

  Treats the menu item as a checkbutton.

`'command'`

  Executes a callback.

`'radiobutton'`

  Treats the menu item as a radiobutton.

You can configure both the menu itself and the individual menu items. The configuration options that apply to `Menubutton` are: `-activebackground`, `-activeforeground`, `-anchor`, `-background`, `-bg`, `-bitmap`, `-borderwidth`, `-bw`, `-cursor`, `-disabledforeground`, `-font`, `-foreground`, `-fg`, `-height`, `-highlightbackground`, `-highlightcolor`, `-highlightthickness`, `-image`, `-justify`, `-padx`, `-pady`, `-relief`, `-state`, `-takefocus`, `-underline`, `-width`, and `-wraplength`.

Other `Menubutton` options are:

`-indicatoron =>` `boolean`

  Determines whether or not to display an indicator.

`-menu =>` `$menu`

  Display the menu associated with `$menu`.

`-menuitems =>` `list`

  Specifies items to create in the menu as a list of lists. See the description at the beginning of this section.

`-tearoff =>` `boolean`

  Whether or not to allow the menu to be "torn off." Default is 1.

`-text =>` `string`

  Specifies the text to display as a label for the button.

`-textvariable =>` `\$variable`

  Points to the variable containing text to be displayed in the menubutton. Button text will change as `$variable` does.

### 18.14.1 Menu Item Options

In addition to the menu itself, each individual menu item can be configured. The widget configuration options that apply to menu items are: `-activebackground`, `-background`, `-bg`, `-bitmap`, `-font`, `-foreground`, `-fg`, `-image`, `-state`, and `-underline`. Other options are:

`-accelerator`

  Displays an accelerator key sequence for the menu item. The key sequence must be independently defined with a `bind`.

`-command =>` `callback`

  Pointer to a function that will be called when the menu item is selected.

`-indicatoron =>` `boolean`

  Determines whether or not to display an indicator.

`-label =>` `string`

  The string to use as a label for the menu item.

`-menu =>` `$submenu`

  For a cascade menu, points to the menu to embed.

`-offvalue =>` `newvalue`

  For a checkbutton, specifies the value used when the checkbutton is "off."

`-onvalue =>` `newvalue`

  For a checkbutton, specifies the value used when the checkbutton is "on."

`-selectcolor =>` `color`

  For a checkbutton or radiobutton, color of the indicator when "on."

`-selectimage =>` `imgptr`

  For a checkbutton or radiobutton, defines the image to be displayed instead of text when the radiobutton is "on". Ignored if `-image` is not used.

`-value =>` `value`

  For a radiobutton, sets `$variable` to the specified value when the radiobutton is selected (default is 1).

`-variable =>` `\$variable`

  Associates the value of the menu item to the specified variable.

### 18.14.2 Menubutton Methods

In addition to `configure` and `cget`, the following methods are defined for Menubutton widgets:

`AddItems`

  Adds menu items to the end of the menu. The arguments to `AddItems` are lists configuring each menu item, similar to the lists defined with the `-menuitem` option.

  >     $menubutton->AddItems(["command" => "Print",
  >     		       "-command" => \&printscreen ],
  >     		      ["command" => "Exit",
  >     		       "-command" => \&exitclean ]);

`command`

  Adds a command item to the end of the menu. The above example could have read:

  >     $menubutton->command(-label => "Print", -command => \&printscreen);
  >     $menubutton->command(-label => "Exit", -command => \&exitclean);

`checkbutton`

  Adds a checkbutton item to the end of the menu.

  >     $menubutton->checkbutton(-label => "Show Toolbar",
  >                [-variable => \$toolbar");

`radiobutton`

  Adds a radiobutton item to the end of the menu.

  >     $menubutton->radiobutton(-label => "Red", -variable => \$color");
  >     $menubutton->radiobutton(-label => "Blue", -variable => \$color");

`separator`

  Adds a separator line to the end of a menu.

`cascade`

  Adds a cascade item to the end of the menu.

`menu`

  Returns a reference to the menu.

`entrycget`

  Gets information on a menu entry given an index and option to query.

`entryconfigure`

  Changes information on a specific menu item given an index.

18.13 The Scale Widget |  | 18.15 The Menu Widget