Xfce Foundation Classes
 « Main Page | Index

Menu Items

Table of Contents

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

Gtk::MenuItem and its derived widgets are the only valid children for menus. Their function is to correctly handle highlighting, alignment, events and submenus. As MenuItem 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();

MenuItem(const String& label, bool use_underline = false);

MenuItem(const String& label, Gtk::Menu& submenu, bool use_underline = false

The 'label' argument is a text 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 this method:

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

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

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 'activate' signal. You can connect to the activate signal like this:

menu_item->signal_activate().connect(sigc::mem_fun(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, sigc::mem_fun(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();

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 respectively:

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:

void set_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->signal_toggled().connect(sigc::mem_fun(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();

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);

ImageMenuItem(const StockId& stock_id, AccelGroup *accel_group = 0);

The 'image' argument is the image widget for the menu item. The 'stock_id' argument is the stock item to use to set the menu item image and text. The 'accel_group' argument is the accelerator group to add the stock item's accelerator to. The other arguments are the same as those for the menu items above:

You can set and retrieve the image for an ImageMenuItem with the following methods respectively:

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();

RadioMenuItem(const RadioMenuItem *group);

RadioMenuItem(const RadioMenuItem *group, const String& label, bool use_underline = false);

The first constructor creates an empty radio menu item that starts a new group. The second constructor creates an empty radio menu item that is a member of the specified group. The last constructor creates a radio menu item that is a member of the specified group and displays 'label' as its text. If 'use_underline' is true the label string is parsed for an underscore preceding the mnemonic character.

If the 'group' argument is null a new group will be created for the radio menu item. This should be the case for the first radio menu item created in a group. Then for subsequent radio menu items you pass a pointer to the previous radio menu item created. This allows a chain of radio menu items to be established. The example below should make this clear.

Gtk::Menu *menu; // created elsewhere
Gtk::RadioMenuItem *menu_item = 0;

menu_item = new Gtk::RadioMenuItem(menu_item, "Item1");
menu->append(*menu_item, item1_slot);
menu_item->show();

menu_item = new Gtk::RadioMenuItem(menu_item, "Item2");
menu->append(*menu_item, item2_slot);
menu_item->show();

menu_item = new Gtk::RadioMenuItem(menu_item, "Item3");
menu->append(*menu_item, item3_slot);
menu_item->show();

You can set and get the group a radio menu item belongs to by calling the following methods respectively:

void set_group(Group *group);

Group* get_group() const;

The 'group' argument is a pointer to a Group, which is just a typedef for a GSList.

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

void set_active(bool is_active);

If 'is_active' is true the menu item will be active and the previously active menu tiem will become inactive.

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 menu item 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.


Copyright © 2004-2005 The XFC Development Team Top
XFC 4.4