GTK+ Reference Manual
<<< Previous PageHomeUpNext 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 PageHomeUpNext Page >>>
GtkListItemGtkMenuBar