GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkMenu

## Name

GtkMenu -- a drop down menu widget.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkMenu;
    GtkWidget*  gtk_menu_new                    (void);
    void        gtk_menu_append                 (GtkMenu *menu,
                                                 GtkWidget *child);
    void        gtk_menu_prepend                (GtkMenu *menu,
                                                 GtkWidget *child);
    void        gtk_menu_insert                 (GtkMenu *menu,
                                                 GtkWidget *child,
                                                 gint position);
    void        gtk_menu_reorder_child          (GtkMenu *menu,
                                                 GtkWidget *child,
                                                 gint position);
    void        gtk_menu_popup                  (GtkMenu *menu,
                                                 GtkWidget *parent_menu_shell,
                                                 GtkWidget *parent_menu_item,
                                                 GtkMenuPositionFunc func,
                                                 gpointer data,
                                                 guint button,
                                                 guint32 activate_time);
    void        gtk_menu_set_accel_group        (GtkMenu *menu,
                                                 GtkAccelGroup *accel_group);
    void        gtk_menu_set_title              (GtkMenu *menu,
                                                 const gchar *title);

    void        gtk_menu_popdown                (GtkMenu *menu);
    void        gtk_menu_reposition             (GtkMenu *menu);
    GtkWidget*  gtk_menu_get_active             (GtkMenu *menu);
    void        gtk_menu_set_active             (GtkMenu *menu,
                                                 guint index);
    void        gtk_menu_set_tearoff_state      (GtkMenu *menu,
                                                 gboolean torn_off);
    void        gtk_menu_attach_to_widget       (GtkMenu *menu,
                                                 GtkWidget *attach_widget,
                                                 GtkMenuDetachFunc detacher);
    void        gtk_menu_detach                 (GtkMenu *menu);
    GtkWidget*  gtk_menu_get_attach_widget      (GtkMenu *menu);
    void        (*GtkMenuPositionFunc)          (GtkMenu *menu,
                                                 gint *x,
                                                 gint *y,
                                                 gpointer user_data);
    void        (*GtkMenuDetachFunc)            (GtkWidget *attach_widget,
                                                 GtkMenu *menu);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkMenuShell
                         +----GtkMenu

## Description

A GtkMenu is a GtkMenuShell that implements a drop down menu consisting of a list of GtkMenuItem objects which can be navigated and activated by the user to perform application functions.

A GtkMenu is most commonly dropped down by activating a GtkMenuItem in a GtkMenuBar or popped up by activating a GtkMenuItem in another GtkMenu.

A GtkMenu can also be popped up by activating a GtkOptionMenu. Other composite widgets such as the GtkNotebook can pop up a GtkMenu as well.

Applications can display a GtkMenu as a popup menu by calling the gtk_menu_popup() function. 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.

        /* connect our handler which will popup the menu */
        gtk_signal_connect_object(GTK_OBJECT(window), "button_press_event",
    	GTK_SIGNAL_FUNC (my_popup_handler), GTK_OBJECT(menu));

Example 2. Signal handler which displays a popup menu.

    static gint
    my_popup_handler(GtkWidget *widget, GdkEvent *event)
    {
      GtkMenu *menu;
      GdkEventButton *event_button;

      g_return_val_if_fail (widget != NULL, FALSE);
      g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
      g_return_val_if_fail (event != NULL, FALSE);

      /* The "widget" is the menu that was supplied when
       * gtk_signal_connect_object was called.
       */
      menu = GTK_MENU (widget);

      if (event->type == GDK_BUTTON_PRESS)
        {
          event_button = (GdkEventButton *) event;
          if (event_button->button == 3)
    	{
    	  gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
    			  event_button->button, event_button->time);
    	  return TRUE;
    	}
        }

      return FALSE;
    }

## Details

### struct GtkMenu

    struct GtkMenu;

The GtkMenu struct contains private data only, and should be accessed using the functions below.

### gtk_menu_new ()

    GtkWidget*  gtk_menu_new                    (void);

Creates a new GtkMenu.

Returns : | a new GtkMenu.

### gtk_menu_append ()

    void        gtk_menu_append                 (GtkMenu *menu,
                                                 GtkWidget *child);

Adds a new GtkMenuItem to the end of the menu's item list.

`menu` : | a GtkMenu.
`child` : | The GtkMenuItem to add.

### gtk_menu_prepend ()

    void        gtk_menu_prepend                (GtkMenu *menu,
                                                 GtkWidget *child);

Adds a new GtkMenuItem to the beginning of the menu's item list.

`menu` : | a GtkMenu.
`child` : | The GtkMenuItem to add.

### gtk_menu_insert ()

    void        gtk_menu_insert                 (GtkMenu *menu,
                                                 GtkWidget *child,
                                                 gint position);

Adds a new GtkMenuItem to the menu's item list at the position indicated by `position`.

`menu` : | a GtkMenu.
`child` : | The GtkMenuItem to add.
`position` : | The position in the item list where `child` is added. Positions are numbered from 0 to n-1.

### gtk_menu_reorder_child ()

    void        gtk_menu_reorder_child          (GtkMenu *menu,
                                                 GtkWidget *child,
                                                 gint position);

Moves a GtkMenuItem to a new position within the GtkMenu.

`menu` : | a GtkMenu.
`child` : | the GtkMenuItem to move.
`position` : | the new position to place `child`. Positions are numbered from 0 to n-1.

### gtk_menu_popup ()

    void        gtk_menu_popup                  (GtkMenu *menu,
                                                 GtkWidget *parent_menu_shell,
                                                 GtkWidget *parent_menu_item,
                                                 GtkMenuPositionFunc func,
                                                 gpointer data,
                                                 guint button,
                                                 guint32 activate_time);

Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply NULL for the `parent_menu_shell`, `parent_menu_item`, `func` and `data` parameters. The default menu positioning function will position the menu at the current pointer position.

`menu` : | a GtkMenu.
`parent_menu_shell` : | the menu shell containing the triggering menu item.
`parent_menu_item` : | the menu item whose activation triggered the popup.
`func` : | a user supplied function used to position the menu.
`data` : | user supplied data to be passed to `func`.
`button` : | the button which was pressed to initiate the event.
`activate_time` : | the time at which the activation event occurred.

### gtk_menu_set_accel_group ()

    void        gtk_menu_set_accel_group        (GtkMenu *menu,
                                                 GtkAccelGroup *accel_group);

Set the GtkAccelGroup which holds global accelerators for the menu.

`menu` : | a GtkMenu.
`accel_group` : | the GtkAccelGroup to be associated with the menu.

### gtk_menu_set_title ()

    void        gtk_menu_set_title              (GtkMenu *menu,
                                                 const gchar *title);

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

`menu` : | a GtkMenu.
`title` : | a string containing the title for the menu.

### gtk_menu_popdown ()

    void        gtk_menu_popdown                (GtkMenu *menu);

Removes the menu from the screen.

`menu` : | a GtkMenu.

### gtk_menu_reposition ()

    void        gtk_menu_reposition             (GtkMenu *menu);

Repositions the menu according to its position function.

`menu` : | a GtkMenu.

### gtk_menu_get_active ()

    GtkWidget*  gtk_menu_get_active             (GtkMenu *menu);

Returns the selected menu item from the menu. This is used by the GtkOptionMenu.

`menu` : | a GtkMenu.
Returns : | the GtkMenuItem that was last selected in the menu. If a selection has not yet been made, the first menu item is selected.

### gtk_menu_set_active ()

    void        gtk_menu_set_active             (GtkMenu *menu,
                                                 guint index);

Selects the specified menu item within the menu. This is used by the GtkOptionMenu.

`menu` : | a GtkMenu.
`index` : | the index of the menu item to select. Index values are from 0 to n-1.

### gtk_menu_set_tearoff_state ()

    void        gtk_menu_set_tearoff_state      (GtkMenu *menu,
                                                 gboolean torn_off);

Changes the tearoff state of the 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.

`menu` : | a GtkMenu.
`torn_off` : | If TRUE, menu is displayed as a tearoff menu.

### gtk_menu_attach_to_widget ()

    void        gtk_menu_attach_to_widget       (GtkMenu *menu,
                                                 GtkWidget *attach_widget,
                                                 GtkMenuDetachFunc detacher);

Attaches the menu to the widget and provides a callback function that will be invoked when the menu calls gtk_menu_detach() during its destruction.

`menu` : | a GtkMenu.
`attach_widget` : | the GtkWidget that the menu will be attached to.
`detacher` : | the user supplied callback function that will be called when the menu calls gtk_menu_detach().

### gtk_menu_detach ()

    void        gtk_menu_detach                 (GtkMenu *menu);

Detaches the menu from the widget to which it had been attached. This function will call the callback function, `detacher`, provided when the gtk_menu_attach_to_widget() function was called.

`menu` : | a GtkMenu.

### gtk_menu_get_attach_widget ()

    GtkWidget*  gtk_menu_get_attach_widget      (GtkMenu *menu);

Returns the GtkWidget that the menu is attached to.

`menu` : | a GtkMenu.
Returns : | the GtkWidget that the menu is attached to.

### GtkMenuPositionFunc ()

    void        (*GtkMenuPositionFunc)          (GtkMenu *menu,
                                                 gint *x,
                                                 gint *y,
                                                 gpointer user_data);

A user function supplied when calling gtk_menu_popup() which controls the positioning of the menu when it is displayed. The function sets the `x` and `y` parameters to the coordinates where the menu is to be drawn.

`menu` : | a GtkMenu.
`x` : | address of the gint representing the horizontal position where the menu shall be drawn. This is an output parameter.
`y` : | address of the gint representing the vertical position where the menu shall be drawn. This is an output parameter.
`user_data` : | the data supplied by the user in the gtk_menu_popup() `data` parameter.

### GtkMenuDetachFunc ()

    void        (*GtkMenuDetachFunc)            (GtkWidget *attach_widget,
                                                 GtkMenu *menu);

A user function supplied when calling gtk_menu_attach_to_widget() which will be called when the menu is later detached from the widget.

`attach_widget` : | the GtkWidget that the menu is being detached from.
`menu` : | the GtkMenu being detached.

<<< Previous Page | Home | Up | Next Page >>>
GtkListItem | GtkMenuBar