gtkmm: Gtk::MenuShell Class Reference

gtkmm 3.4.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions | Related Functions
Gtk::MenuShell Class Reference
Widgets | Container Widgets | Menu classes

The abstract base class for Gtk::Menu and Gtk::MenuBar. More...

Inheritance diagram for Gtk::MenuShell:
[legend]

List of all members.

## Public Member Functions
virtual | ~MenuShell ()
GtkMenuShell* | gobj ()
| Provides access to the underlying C GtkObject.
const GtkMenuShell* | gobj () const
| Provides access to the underlying C GtkObject.
void | append (MenuItem& menu_item)
| Adds a new Gtk::MenuItem to the end of the menu shell's item list.
void | prepend (MenuItem& menu_item)
| Adds a new Gtk::MenuItem to the beginning of the menu shell's item list.
void | insert (MenuItem& menu_item, int position)
| Adds a new Gtk::MenuItem to the menu shell's item list at the position indicated by position.
void | select_item (MenuItem& menu_item)
| Selects the menu item from the menu shell.
void | deselect ()
| Deselects the currently selected item from the menu shell, if any.
void | activate_item (MenuItem& menu_item, bool force_deactivate=false)
| Activates the menu item within the menu shell.
void | select_first (bool search_sensitive=true)
| Select the first visible or selectable child of the menu shell; don't select tearoff items unless the only item is a tearoff item.
void | deactivate ()
| Deactivates the menu shell.
void | cancel ()
| Cancels the selection within the menu shell.
Glib::SignalProxy0< void > | signal_deactivate ()
Glib::SignalProxy0< void > | signal_selection_done ()
Glib::SignalProxy1< gboolean, int > | signal_move_selected ()
Glib::SignalProxy2< void, Widget*, int > | signal_insert ()
void | accelerate (Window& window)
| Initializes menu accelerators.
void | accelerate (Widget& parent)
| Initializes menu accelerators.
bool | get_take_focus () const
| Returns `true` if the menu shell will take the keyboard focus on popup.
void | set_take_focus (bool take_focus=true)
| If take_focus is `true` (the default) the menu shell will take the keyboard focus so that it will receive all keyboard events which is needed to enable keyboard navigation in menus.
Widget* | get_selected_item ()
| Gets the currently selected item.
const Widget* | get_selected_item () const
| Gets the currently selected item.
Widget* | get_parent_shell ()
| Gets the parent menu shell.
const Widget* | get_parent_shell () const
| Gets the parent menu shell.
Glib::PropertyProxy< bool > | property_take_focus ()
| A boolean that determines whether the menu grabs the keyboard focus.
Glib::PropertyProxy_ReadOnly < bool > | property_take_focus () const
| A boolean that determines whether the menu grabs the keyboard focus.
## Protected Member Functions
virtual void | on_deactivate ()
| This is a default handler for the signal signal_deactivate().
virtual void | on_selection_done ()
| This is a default handler for the signal signal_selection_done().
virtual gboolean | on_move_selected (int distance)
| This is a default handler for the signal signal_move_selected().
| MenuShell ()
## Related Functions
(Note that these are not member functions.)
Gtk::MenuShell* | wrap (GtkMenuShell* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

The abstract base class for Gtk::Menu and Gtk::MenuBar.

It is a container of Gtk::MenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. It can have a submenu associated with it, allowing for nested hierarchical menus. Use append(), prepend() and insert() to add Gtk::MenuItem widgets.

## Constructor & Destructor Documentation

virtual Gtk::MenuShell::~MenuShell | ( |  | ) | `[virtual]`

Gtk::MenuShell::MenuShell | ( |  | ) | `[protected]`

## Member Function Documentation

void Gtk::MenuShell::accelerate | ( | Window& | window | ) |

Initializes menu accelerators.

This method initializes the menu accelerators. Therefore an AccelGroup object is needed which is stored in each Window object in the Gtkmm library implementation.

When using MenuBar and OptionMenu objects this method is called automatically when the menus are realized. Because most likely the MenuBar and OptionMenu is attached to a window at this time and the window object can be found automatically.

Important note when using popup menus: If you are using accelerated menu entries inside a popup menu you have to call the accelerate() method manually. This is because the popup menu is not connected to any window and the accelerators should be initialized even before the popup menu is shown. The right place to call the accelerate() method is right after the popup menu has been build.

Parameters:

  window | Window where the menu is shown. Inside this window the AccelGroup object is stored that will be used to initialize the accelerators.

void Gtk::MenuShell::accelerate | ( | Widget& | parent | ) |

Initializes menu accelerators.

Does the same as the accelerate(Window& window) method. But you can use any parent widget where the menu is used. This method then gets the toplevel window using Widget::get_toplevel() and uses this window for registering the menu accelerators.

Parameters:

  parent | Parent widget used as starting point for searching the toplevel window.

void Gtk::MenuShell::activate_item | ( | MenuItem& | menu_item,
|  | bool | force_deactivate = `false`
| ) |  |

Activates the menu item within the menu shell.

Parameters:

  menu_item | The Gtk::MenuItem to activate.
  force_deactivate | If `true`, force the deactivation of the menu shell after the menu item is activated.

void Gtk::MenuShell::append | ( | MenuItem& | menu_item | ) |

Adds a new Gtk::MenuItem to the end of the menu shell's item list.

Parameters:

  child | The Gtk::MenuItem to add.

void Gtk::MenuShell::cancel | ( |  | ) |

Cancels the selection within the menu shell.

Since gtkmm 2.4:

void Gtk::MenuShell::deactivate | ( |  | ) |

Deactivates the menu shell.

Typically this results in the menu shell being erased from the screen.

void Gtk::MenuShell::deselect | ( |  | ) |

Deselects the currently selected item from the menu shell, if any.

Widget* Gtk::MenuShell::get_parent_shell | ( |  | ) |

Gets the parent menu shell.

The parent menu shell of a submenu is the Gtk::Menu or Gtk::MenuBar from which it was opened up.

Since gtkmm 3.0:

Returns:
  The parent Gtk::MenuShell.

const Widget* Gtk::MenuShell::get_parent_shell | ( |  | ) | const

Gets the parent menu shell.

The parent menu shell of a submenu is the Gtk::Menu or Gtk::MenuBar from which it was opened up.

Since gtkmm 3.0:

Returns:
  The parent Gtk::MenuShell.

Widget* Gtk::MenuShell::get_selected_item | ( |  | ) |

Gets the currently selected item.

Since gtkmm 3.0:

Returns:
  The currently selected item.

const Widget* Gtk::MenuShell::get_selected_item | ( |  | ) | const

Gets the currently selected item.

Since gtkmm 3.0:

Returns:
  The currently selected item.

bool Gtk::MenuShell::get_take_focus | ( |  | ) | const

Returns `true` if the menu shell will take the keyboard focus on popup.

Since gtkmm 2.8:

Returns:
  `true` if the menu shell will take the keyboard focus on popup.

GtkMenuShell* Gtk::MenuShell::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Container.

Reimplemented in Gtk::MenuBar, Gtk::RecentChooserMenu, and Gtk::Menu.

const GtkMenuShell* Gtk::MenuShell::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Container.

Reimplemented in Gtk::MenuBar, Gtk::RecentChooserMenu, and Gtk::Menu.

void Gtk::MenuShell::insert | ( | MenuItem& | menu_item,
|  | int | position
| ) |  |

Adds a new Gtk::MenuItem to the menu shell's item list at the position indicated by position.

Parameters:

  child | The Gtk::MenuItem to add.
  position | The position in the item list where child is added. Positions are numbered from 0 to n-1.

virtual void Gtk::MenuShell::on_deactivate | ( |  | ) | `[protected, virtual]`

This is a default handler for the signal signal_deactivate().

virtual gboolean Gtk::MenuShell::on_move_selected | ( | int | distance | ) | `[protected, virtual]`

This is a default handler for the signal signal_move_selected().

virtual void Gtk::MenuShell::on_selection_done | ( |  | ) | `[protected, virtual]`

This is a default handler for the signal signal_selection_done().

void Gtk::MenuShell::prepend | ( | MenuItem& | menu_item | ) |

Adds a new Gtk::MenuItem to the beginning of the menu shell's item list.

Parameters:

  child | The Gtk::MenuItem to add.

Glib::PropertyProxy< bool > Gtk::MenuShell::property_take_focus | ( |  | ) |

A boolean that determines whether the menu grabs the keyboard focus.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< bool > Gtk::MenuShell::property_take_focus | ( |  | ) | const

A boolean that determines whether the menu grabs the keyboard focus.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

void Gtk::MenuShell::select_first | ( | bool | search_sensitive = `true` | ) |

Select the first visible or selectable child of the menu shell; don't select tearoff items unless the only item is a tearoff item.

Since gtkmm 2.2:

Parameters:

  search_sensitive | If `true`, search for the first selectable menu item, otherwise select nothing if the first item isn't sensitive. This should be `false` if the menu is being popped up initially.

void Gtk::MenuShell::select_item | ( | MenuItem& | menu_item | ) |

Selects the menu item from the menu shell.

Parameters:

  menu_item | The Gtk::MenuItem to select.

void Gtk::MenuShell::set_take_focus | ( | bool | take_focus = `true` | ) |

If take_focus is `true` (the default) the menu shell will take the keyboard focus so that it will receive all keyboard events which is needed to enable keyboard navigation in menus.

Setting take_focus to `false` is useful only for special applications like virtual keyboard implementations which should not take keyboard focus.

The take_focus state of a menu or menu bar is automatically propagated to submenus whenever a submenu is popped up, so you don't have to worry about recursively setting it for your entire menu hierarchy. Only when programmatically picking a submenu and popping it up manually, the take_focus property of the submenu needs to be set explicitely.

Note that setting it to `false` has side-effects:

If the focus is in some other app, it keeps the focus and keynav in the menu doesn't work. Consequently, keynav on the menu will only work if the focus is on some toplevel owned by the onscreen keyboard.

To avoid confusing the user, menus with take_focus set to `false` should not display mnemonics or accelerators, since it cannot be guaranteed that they will work.

See also gdk_keyboard_grab()

Since gtkmm 2.8:

Parameters:

  take_focus | `true` if the menu shell should take the keyboard focus on popup.

Glib::SignalProxy0< void > Gtk::MenuShell::signal_deactivate | ( |  | ) |

Slot Prototype:
  `void on_my_deactivate()`

This signal is emitted when a menu shell is deactivated.

Glib::SignalProxy2< void,Widget*,int > Gtk::MenuShell::signal_insert | ( |  | ) |

Slot Prototype:
  `void on_my_insert(Widget* child, int position)`

The signal_insert() signal is emitted when a new Gtk::MenuItem is added to a Gtk::MenuShell. A separate signal is used instead of GtkContainer::add because of the need for an additional position parameter.

The inverse of this signal is the GtkContainer::removed signal.

Since gtkmm 3.2:

Parameters:

  child | The Gtk::MenuItem that is being inserted.
  position | The position at which the insert occurs.

Glib::SignalProxy1< gboolean,int > Gtk::MenuShell::signal_move_selected | ( |  | ) |

Slot Prototype:
  `gboolean on_my_move_selected(int distance)`

The signal_move_selected() signal is emitted to move the selection to another item.

Since gtkmm 2.12:

Parameters:

  distance | +1 to move to the next item, -1 to move to the previous.

Returns:
  `true` to stop the signal emission, `false` to continue.

Glib::SignalProxy0< void > Gtk::MenuShell::signal_selection_done | ( |  | ) |

Slot Prototype:
  `void on_my_selection_done()`

This signal is emitted when a selection has been completed within a menu shell.

## Friends And Related Function Documentation

Gtk::MenuShell* wrap | ( | GtkMenuShell * | object,
|  | bool | take_copy = `false`
| ) |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- gtkmm/menushell.h