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

# GtkOptionMenu

## Name

GtkOptionMenu -- a widget used to choose from a list of valid choices.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkOptionMenu;
    GtkWidget*  gtk_option_menu_new             (void);
    GtkWidget*  gtk_option_menu_get_menu        (GtkOptionMenu *option_menu);
    void        gtk_option_menu_set_menu        (GtkOptionMenu *option_menu,
                                                 GtkWidget *menu);
    void        gtk_option_menu_remove_menu     (GtkOptionMenu *option_menu);
    void        gtk_option_menu_set_history     (GtkOptionMenu *option_menu,
                                                 guint index);
    gint        gtk_option_menu_get_history     (GtkOptionMenu *option_menu);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkButton
                                     +----GtkOptionMenu

## Properties

      "menu"                 GtkMenu              : Read / Write

## Style Properties

      "indicator-spacing"    GtkTypeBorder        : Read
      "indicator-size"       GtkTypeRequisition   : Read

## Signal Prototypes

    "changed"   void        user_function      (GtkOptionMenu *optionmenu,
                                                gpointer user_data);

## Description

A GtkOptionMenu is a widget that allows the user to choose from a list of valid choices. The GtkOptionMenu displays the selected choice. When activated the GtkOptionMenu displays a popup GtkMenu which allows the user to make a new choice.

Using a GtkOptionMenu is simple; build a GtkMenu, by calling gtk_menu_new(), then appending menu items to it with gtk_menu_shell_append(). Set that menu on the option menu with gtk_option_menu_set_menu(). Set the selected menu item with gtk_option_menu_set_history(); connect to the "changed" signal on the option menu; in the "changed" signal, check the new selected menu item with gtk_option_menu_get_history().

## Details

### struct GtkOptionMenu

    struct GtkOptionMenu;

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

### gtk_option_menu_new ()

    GtkWidget*  gtk_option_menu_new             (void);

Creates a new GtkOptionMenu.

Returns : | a new GtkOptionMenu.

### gtk_option_menu_get_menu ()

    GtkWidget*  gtk_option_menu_get_menu        (GtkOptionMenu *option_menu);

Returns the GtkMenu associated with the GtkOptionMenu.

`option_menu` : | a GtkOptionMenu.
Returns : | the GtkMenu associated with the GtkOptionMenu.

### gtk_option_menu_set_menu ()

    void        gtk_option_menu_set_menu        (GtkOptionMenu *option_menu,
                                                 GtkWidget *menu);

Provides the GtkMenu that is popped up to allow the user to choose a new value. You should provide a simple menu avoiding the use of tearoff menu items, submenus, and accelerators.

`option_menu` : | a GtkOptionMenu.
`menu` : | the GtkMenu to associate with the GtkOptionMenu.

### gtk_option_menu_remove_menu ()

    void        gtk_option_menu_remove_menu     (GtkOptionMenu *option_menu);

Removes the menu from the option menu.

`option_menu` : | a GtkOptionMenu.

### gtk_option_menu_set_history ()

    void        gtk_option_menu_set_history     (GtkOptionMenu *option_menu,
                                                 guint index);

Selects the menu item specified by `index` making it the newly selected value for the option menu.

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

### gtk_option_menu_get_history ()

    gint        gtk_option_menu_get_history     (GtkOptionMenu *option_menu);

Retrieves the index of the currently selected menu item. The menu items are numbered from top to bottom, starting with 0.

`option_menu` : | a GtkOptionMenu
Returns : | index of the selected menu item, or -1 if there are no menu items

## Properties

"`menu`" (GtkMenu : Read / Write)

  The menu of options

## Style Properties

"`indicator-spacing`" (GtkTypeBorder : Read)

  Spacing around indicator

"`indicator-size`" (GtkTypeRequisition : Read)

  Size of dropdown indicator

## Signals

### The "changed" signal

    void        user_function                  (GtkOptionMenu *optionmenu,
                                                gpointer user_data);

`optionmenu` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

<<< Previous Page | Home | Up | Next Page >>>
GtkMenuShell | GtkImageMenuItem