### Tutorial

« MessageDialog | OptionMenu »

## Menu Items

1. Check Menu Items
2. Image Menu Items
3. Radio Menu Items
4. Separator Menu Items
5. Tearoff Menu Items

The MenuItem widget and the derived widgets are the only valid children for menus. Their function is to correctly handle highlighting, alignment, events and submenus. As it derives from Gtk::Bin a menu item can hold any valid child widget, although only a few are really useful.
You can create a MenuItem with one of the following constructors:

`MenuItem(); explicit MenuItem(const String& label, bool use_underline = false); MenuItem(const String& label, Gtk::Menu& submenu, bool use_underline = false);`

The label argument is the string to use for the label. The submenu argument is a popup menu to display when the menu item is activated. If use_underline is true the label string is parsed for an underscore preceding the mnemonic character.
The menu item label can be set at any time with:

`void set_label(const String& label, bool use_underline = false);`

The popup submenu can be set, retrieved and removed by calling the following methods:

`void set_submenu(Gtk::Menu& submenu); Gtk::Menu* get_submenu() const;` `void remove_submenu();`

To have a menu item appear justified at the right side of a menu bar call:

`void set_right_justified(bool right_justified);`

This was traditionally done for "Help" menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.)
Menu items emit four signals: activate, activate_item, toggle_size_request and toggle_size_allocate. The main signal applications use is the actviate signal. You can connect to the activate signal like this:

`menu_item->sig_activate().connect(slot(this, &MyClass::activate_handler));`

where the activate_handler has the following prototype:

`void MyClass::activate_handler();`

Most of the time you wont need to connect to the activate signal as this gets done for you when you call one of the Gtk::MenuShell methods: append, prepend or insert and pass it a slot, like this:

`menu->append(*menu_item, slot(this, &MyClass::menu_item_handler));`

### Check Menu Items

A check menu item is a menu item that maintains the state of a bool value in addition to a MenuItem's usual role in activating application code. A small check box indicating the state of the bool value is displayed at the left side of the menu item. Activating the menu item toggles the value off and on.
You can create a CheckMenuItem with one of the following constructors:

`CheckMenuItem(); explicit CheckMenuItem(const String& label, bool use_underline = false);`

You will need to set and get the active state of the menu item. This can be done with the following methods:

`void set_active(bool is_active); bool get_active() const;`

The get_active() method returns true if the check menu item is currently in its active state.
If you want to indicate to the user an intermediate state, neither off nor on, you have to do it manually by calling:

`voidset_inconsistent(bool setting); bool get_inconsistent() const;`

The get_inconsistent() method returns true if the check menu item is currently in an intermediate state.
The toggled signal is emitted when the state of the check box is changed. You can connect to the toggled signal like this:

`check_menu_item->sig_toggled().connect(slot(this, &MyClass::toggled_handler));`

where toggled_handler has the following prototype:

`void MyClass::toggled_handler();`

### Image Menu Items

An image menu item displays an image next to it's label. You can create an ImageMenuItem by calling one of the following constructors:

`ImageMenuItem(); explicit ImageMenuItem(const String& label, bool use_underline = false); ImageMenuItem(Gtk::Widget& image, const String& label, bool use_underline = false); ImageMenuItem(Gtk::Widget& image, const String& label, Gtk::Menu& submenu, bool use_underline = false);`

The image argument is the image widget for the menu item. The other arguments are the same as those for the menu items above:
To create an ImageMenuItem using one of the GTK stock images and it's associated label and accelerator call the following constructor:

`StockMenuItem(const char *stock_id, Gtk::AccelGroup *accel_group = 0);`

StockMenuItem is derived from ImageMenuItem.
You can set and retrieve the image for an ImageMenuItem with the following methods:

`void set_image(Gtk::Widget& image);` `Gtk::Widget* get_image() const;`

### Radio Menu Items

A radio menu item is a check menu item that belongs to a group. At each instant only one radio menu item from a group is selected.
You can create a RadioMenuItem by calling one of the following constructors:

`RadioMenuItem(); explicit RadioMenuItem(Group *group); explicit RadioMenuItem(const Gtk::RadioMenuItem *group); explicit RadioMenuItem(const String& label, bool use_underline = false); RadioMenuItem(Group *group, const String& label, bool use_underline = false); RadioMenuItem(const Gtk::RadioMenuItem *group, const String& label, bool use_underline = false);`

`
`
``You'll notice the extra argument to these constructors. They require a group to perform their duty properly. The group specified can either be a pointer to a Group, which is just a typedef for a GSList or a pointer to a RadioMenuItem already in the group. The first radio menu item can be created by either calling the first or fourth constructors, or by calling the fifth or sixth constructors and passing null for the group argument. Subsequent radio menu items must be constructed by either calling the fifth or sixth constructors and specifying the group. For the fifth constructor, the group can be retrieved by calling:

`Group* get_group() const;`

The important thing to remember is that Gtk::RadioMenuItem::get_group() must be called on the previous menu item and the result passed in as the group argument to the new menu item. Then the result of calling Gtk::RadioMenuItem::get_group() on the new menu item is passed into the constructor call for the next menu item. This allows a chain of menu items to be established. The example below should make this clear.

`Gtk::RadioMenuItem::Group *group = 0;
Gtk::RadioMenuItem *radio_menu_item = new Gtk::RadioMenuItem(group, "item1");
menu->append(*radio_menu_item, slot(this, &MyClass::item1_handler));
radio_menu_item->show();
group = radio_menu_item->get_group();
radio_menu_item = new Gtk::RadioMenuItem(group, "item2");
menu->append(*radio_menu_item, slot(this, &MyClass::item2_handler));
radio_menu_item->show();`

You can shorten this slightly by using either of the following syntax, which removes the need for a variable to hold the Group (list) of menu items:

`Gtk::RadioMenuItem *radio_menu_item2 = new Gtk::RadioMenuItem(radio_menu_item1->get_group(), "item2"); or` `Gtk::RadioMenuItem *radio_menu_item2 = new Gtk::RadioMenuItem(radio_menu_item1, "item2");`

`
` It is also a good idea to explicitly set which menu item should be the active menu item for the group with:

`void set_active(bool is_active);`

### Separator Menu Items

The SeparatorMenuItem widget is a separator used to group items within a menu. It displays a horizontal line with a shadow to make it appear sunken into the interface.
You can create a separator menu item with the following constructor:

`SeparatorMenuItem();`

### Tearoff Menu Items

A tearoff menu item is a special MenuItem which is used to tear off and reattach its menu.
When it's menu is shown normally, the TearoffMenuItem is drawn as a dotted line indicating that the menu can be torn off. Activating it causes it's menu to be torn off and displayed in its own window as a tearoff menu.
When its menu is shown as a tearoff menu, the TearoffMenuItem is drawn as a dotted line which has a left pointing arrow graphic indicating that the tearoff menu can be reattached. Activating it will erase the tearoff menu window and reattach the menu.
You can create a tearoff menu item with the following constructor:

`TearoffMenuItem();`

To determine if a tearoff menu item is in its torn off state call:

`bool is_torn_off() const;`

The return value is true if the menu item has been torn off.

« MessageDialog | Index Miscellaneous Widgets Top | OptionMenu »