Tutorial
|
|
|
|
|
Menu Items
- Check Menu Items
- Image Menu Items
- Radio Menu Items
- Separator Menu Items
- 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:
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:
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.