Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Gtk::Menu Class Reference

A GtkMenu C++ wrapper class. More...

`#include <xfc/gtk/menu.hh>`

Inheritance diagram for Xfc::Gtk::Menu:

List of all members.

## Public Types

- typedef sigc::slot< void,
  int *, int *, bool * > MenuPositionSlot
    Signature of the callback slot to be called when a popup menu is displayed by calling popup(); this slot controls the position of the popup menu.

## Public Member Functions

Constructors

- Menu ()
    Construct a new Menu.
- Menu (const AccelGroup &accel_group)
    Construct a new Menu with an accelerator group which holds global accelerators for the menu.
- virtual ~Menu ()
    Destructor.

Accessors

- GtkMenu * gtk_menu () const
    Get a pointer to the GtkMenu structure.
- operator GtkMenu * () const
    Conversion operator; safely converts a Menu to a GtkMenu pointer.
- MenuItem * get_active () const
    Get the selected menu item from the menu.
- AccelGroup * get_accel_group () const
    Gets the AccelGroup which holds global accelerators for the menu (see set_accel_group()).
- Widget * get_attach_widget () const
    Returns the Widget that the menu is attached to.
- bool get_tearoff_state () const
    Returns whether the menu is torn off (see set_tearoff_state()).
- String get_title () const
    Returns the title of the menu (see set_title()).

Methods

- void popup (MenuShell &parent_shell, MenuItem &parent_item, unsigned int button, const MenuPositionSlot &position, unsigned int activate_time=GDK_CURRENT_TIME)
    Displays a menu and makes it available for selection.
- void popup (unsigned int button, const MenuPositionSlot &position, unsigned int activate_time=GDK_CURRENT_TIME)
    Displays a menu and makes it available for selection.
- void popup (unsigned int button, unsigned int activate_time=GDK_CURRENT_TIME)
    Displays a menu and makes it available for selection.
- void reposition ()
    Repositions the menu according to its position slot.
- void popdown ()
    Removes the menu from the screen.
- void set_active (unsigned int index)
    Selects the specified menu item within the menu.
- void set_accel_group (const AccelGroup *accel_group)
    Set the AccelGroup which holds global accelerators for the menu.
- void set_accel_path (const String &accel_path)
    Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu items, can be constructed.
- void attach_to_widget (Widget &attach_widget)
    Attaches the menu to the widget.
- void detach ()
    Detaches the menu from the widget to which it had been attached.
- void set_tearoff_state (bool torn_off)
    Changes the tearoff state of the menu.
- void set_title (const String &title)
    Sets the title string for the menu.
- void reorder_child (const MenuItem &child, int position)
    Moves a MenuItem to a new position within the Menu.
- void set_screen (const Gdk::Screen *screen)
    Sets the Gdk::Screen on which the menu will be displayed.
- void attach (MenuItem &child, unsigned int left_attach, unsigned int right_attach, unsigned int top_attach, unsigned int bottom_attach)
    Adds a new MenuItem to a (table) menu.
- void set_monitor (int monitor_num)
    Informs GTK+ on which monitor a menu should be popped up (see Gdk::Screen::get_monitor_geometry()).

## Static Public Member Functions

Accessors

- std::vector< Menu * > get_for_attach_widget (Widget &widget)
    Obtains a list of the menus which are attached to the widget.

## Protected Member Functions

Constructors

- Menu (GtkMenu *menu, bool owns_reference=false)
    Construct a new Menu from an existing GtkMenu.

Methods

- virtual void on_menu_detach (Widget &attach_widget)
    Called when a menu previously attached to a widget by calling attach_to_widget() is later detached from the widget by calling detach().

## Detailed Description

A GtkMenu C++ wrapper class.

A Menu is a MenuShell that implements a drop down menu consisting of a list of MenuItem objects which can be navigated and activated by the user to perform application functions. A Menu is most commonly dropped down by activating a MenuItem in a MenuBar or popped up by activating a MenuItem in another Menu. A Menu can also be popped up by activating an OptionMenu. Other composite widgets such as the Notebook can pop up a Menu as well. Applications can display a Menu as a popup menu by calling the popup() method. The example below shows how an application can pop up a menu when the 3rd mouse button is pressed.

Example 1: Connecting the popup signal handler.

        // Declare a button_press_event handler in you window class.
        bool on_button_press(GdkEventButton *event);

        // Then connect the window button_press_event to the popup signal handler.
        signal_button_press_event().connect(slot(this, &MyWindow::on_button_press));

Example 2: A signal handler which displays a popup menu.

        // Construct the popup menu somewhere first, then pop it up here.
        bool MyWindow::on_button_press(GdkEventButton *event)
        {
            menu->popup(event->button, event->time);
            return true;
        }

There is a complete example of this in the menu example programs in the <examples/menu> subdirectory.

See also: the Menu and MenuItem HOWTOs and example.

## Member Typedef Documentation

typedef sigc::slot<void, int*, int*, bool*> Xfc::Gtk::Menu::MenuPositionSlot

Signature of the callback slot to be called when a popup menu is displayed by calling popup(); this slot controls the position of the popup menu.

Example: Method signature for MenuPositionSlot.

                 void method(int *x, int *y, bool *push_in);
                 // x: The address of the int representing the horizontal position where the menu shall be drawn.
                 // y: The address of the int representing the vertical position where the menu shall be drawn.
                 // push_in: If true, when the popup menu runs off the screen it is moved so it is displayed
                 //          wholely on the screen. The default is false.

## Constructor & Destructor Documentation

Xfc::Gtk::Menu::Menu | ( | GtkMenu * | menu,
|  | bool | owns_reference = `false`
| ) | `[explicit, protected]`

Construct a new Menu from an existing GtkMenu.

Parameters:

  | menu | A pointer to a GtkMenu.
  | owns_reference | Set false if the initial reference count is floating, set true if it's not.

The menu can be a newly created GtkMenu or an existing GtkMenu (see G::Object::Object).

Xfc::Gtk::Menu::Menu | ( | const AccelGroup & | accel_group | ) |

Construct a new Menu with an accelerator group which holds global accelerators for the menu.

Parameters:

  | accel_group | The AccelGroup to be associated with the menu.

This accelerator group also needs to be added to all windows that this menu is being used in with Gtk::Window::add_accel_group(), in order for those windows to support all the accelerators contained in this group.

## Member Function Documentation

void Xfc::Gtk::Menu::attach | ( | MenuItem & | child,
|  | unsigned int | left_attach,
|  | unsigned int | right_attach,
|  | unsigned int | top_attach,
|  | unsigned int | bottom_attach
| ) |

Adds a new MenuItem to a (table) menu.

Parameters:

  | child | A MenuItem.
  | left_attach | The column number to attach the left side of the item to.
  | right_attach | The column number to attach the right side of the item to.
  | top_attach | The row number to attach the top of the item to.
  | bottom_attach | The row number to attach the bottom of the item to.

The number of 'cells' that an item will occupy is specified by left_attach, right_attach, top_attach and bottom_attach. These each represent the leftmost, rightmost, uppermost and lower column and row numbers of the table. (Columns and rows are indexed from zero).

void Xfc::Gtk::Menu::attach_to_widget | ( | Widget & | attach_widget | ) |

Attaches the menu to the widget.

Parameters:

  | attach_widget | The Widget that the menu will be attached to.

When the menu calls detach() during its destruction the virtual on_menu_detach() method is called.

void Xfc::Gtk::Menu::detach | ( |  | ) |

| Detaches the menu from the widget to which it had been attached. Calling this method invokes the virtual on_menu_detach() method.

MenuItem* Xfc::Gtk::Menu::get_active | ( |  | ) | const

Get the selected menu item from the menu.

Returns:
  The MenuItem that was last selected in the menu.

If a selection has not yet been made, the first menu item is selected. This is used by the OptionMenu.

std::vector<Menu*> Xfc::Gtk::Menu::get_for_attach_widget | ( | Widget & | widget | ) | `[static]`

Obtains a list of the menus which are attached to the widget.

Returns:
  A vector of menus attached to this widget.

bool Xfc::Gtk::Menu::get_tearoff_state | ( |  | ) | const

Returns whether the menu is torn off (see set_tearoff_state()).

Returns:
  true if the menu is currently torn off.

String Xfc::Gtk::Menu::get_title | ( |  | ) | const

Returns the title of the menu (see set_title()).

Returns:
  The title of the menu, or null if the menu has no title set on it.

virtual void Xfc::Gtk::Menu::on_menu_detach | ( | Widget & | attach_widget | ) | `[protected, virtual]`

Called when a menu previously attached to a widget by calling attach_to_widget() is later detached from the widget by calling detach().

Parameters:

  | attach_widget | The Widget that the menu is being detached from.

void Xfc::Gtk::Menu::popup | ( | unsigned int | button,
|  | unsigned int | activate_time = `GDK_CURRENT_TIME`
| ) |

Displays a menu and makes it available for selection.

Parameters:

  | button | The button which was pressed to initiate the event.
  | activate_time | The time at which the activation event occurred.

Applications can use this function to display context-sensitive menus. The default menu positioning function will position the menu at the current pointer position.

void Xfc::Gtk::Menu::popup | ( | unsigned int | button,
|  | const MenuPositionSlot & | position,
|  | unsigned int | activate_time = `GDK_CURRENT_TIME`
| ) |

Displays a menu and makes it available for selection.

Parameters:

  | button | The button which was pressed to initiate the event.
  | position | A MenuPositionSlot that is called to control the positon of the menu.
  | activate_time | The time at which the activation event occurred.

Applications can use this function to display context-sensitive menus.

void Xfc::Gtk::Menu::popup | ( | MenuShell & | parent_shell,
|  | MenuItem & | parent_item,
|  | unsigned int | button,
|  | const MenuPositionSlot & | position,
|  | unsigned int | activate_time = `GDK_CURRENT_TIME`
| ) |

Displays a menu and makes it available for selection.

Parameters:

  | parent_shell | The menu shell containing the triggering menu item.
  | parent_item | The menu item whose activation triggered the popup.
  | button | The button which was pressed to initiate the event.
  | position | A MenuPositionSlot that is called to control the positon of the menu.
  | activate_time | The time at which the activation event occurred.

Applications can use this function to display context-sensitive menus.

void Xfc::Gtk::Menu::reorder_child | ( | const MenuItem & | child,
|  | int | position
| ) |

Moves a MenuItem to a new position within the Menu.

Parameters:

  | child | The MenuItem to move.
  | position | The new position to place child. Positions are numbered from 0 to n-1.

void Xfc::Gtk::Menu::set_accel_group | ( | const AccelGroup * | accel_group | ) |

Set the AccelGroup which holds global accelerators for the menu.

Parameters:

  | accel_group | The AccelGroup to be associated with the menu.

This accelerator group also needs to be added to all windows that this menu is being used in with Gtk::Window::add_accel_group(), in order for those windows to support all the accelerators contained in this group.

void Xfc::Gtk::Menu::set_accel_path | ( | const String & | accel_path | ) |

Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu items, can be constructed.

Parameters:

  | accel_path | A valid accelerator path.

The main purpose of this method is to spare the programmer the inconvenience of having to call set_accel_path() on each menu item that should support runtime user changable accelerators. Instead, by just calling set_accel_path() on their parent, each menu item of this menu, that contains a label describing its purpose, automatically gets an accel path assigned. For example, a menu containing menu items "New" and "Exit", will, after set_accel_path("<Gnumeric-Sheet>/File") has been called, assign its items the accel paths: "<Gnumeric-Sheet>/File/New" and "<Gnumeric-Sheet>/File/Exit". Assigning accel paths to menu items then enables the user to change their accelerators at runtime. More details about accelerator paths and their default setups can be found at Gtk::AccelMap::add_entry().

Parameters:

  | accel_path | A valid accelerator path.

void Xfc::Gtk::Menu::set_active | ( | unsigned int | index | ) |

Selects the specified menu item within the menu.

Parameters:

  | index | The index of the menu item to select. Index values are from 0 to n-1.

This is used by the OptionMenu and should not be used by anyone else.

void Xfc::Gtk::Menu::set_monitor | ( | int | monitor_num | ) |

Informs GTK+ on which monitor a menu should be popped up (see Gdk::Screen::get_monitor_geometry()).

Parameters:

  | monitor_num | The number of the monitor on which the menu should be popped up.

This function should be called from a MenuPositionSlot if the menu should not appear on the same monitor as the pointer. This information can't be reliably inferred from the coordinates returned by a MenuPositionSlot, since, for very long menus, these coordinates may extend beyond the monitor boundaries or even the screen boundaries.

void Xfc::Gtk::Menu::set_screen | ( | const Gdk::Screen * | screen | ) |

Sets the Gdk::Screen on which the menu will be displayed.

Parameters:

  | screen | A Gdk::Screen, or null if the screen should be determined by the widget the menu is attached to.

void Xfc::Gtk::Menu::set_tearoff_state | ( | bool | torn_off | ) |

Changes the tearoff state of the menu.

Parameters:

  | torn_off | If true, the menu is displayed as a tearoff menu.

A menu is normally displayed as drop down menu which persists as long as the menu is active. It can also be displayed as a tearoff menu which persists until it is closed or reattached.

void Xfc::Gtk::Menu::set_title | ( | const String & | title | ) |

Sets the title string for the menu.

Parameters:

  | title | A string containing the title for the menu.

The title is displayed when the menu is shown as a tearoff menu.

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

- menu.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3