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

# GtkMenuShell

## Name

GtkMenuShell -- a base class for menu objects.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkMenuShell;
    void        gtk_menu_shell_append           (GtkMenuShell *menu_shell,
                                                 GtkWidget *child);
    void        gtk_menu_shell_prepend          (GtkMenuShell *menu_shell,
                                                 GtkWidget *child);
    void        gtk_menu_shell_insert           (GtkMenuShell *menu_shell,
                                                 GtkWidget *child,
                                                 gint position);
    void        gtk_menu_shell_deactivate       (GtkMenuShell *menu_shell);
    void        gtk_menu_shell_select_item      (GtkMenuShell *menu_shell,
                                                 GtkWidget *menu_item);
    void        gtk_menu_shell_deselect         (GtkMenuShell *menu_shell);
    void        gtk_menu_shell_activate_item    (GtkMenuShell *menu_shell,
                                                 GtkWidget *menu_item,
                                                 gboolean force_deactivate);
    enum        GtkMenuDirectionType;

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkMenuShell

## Signal Prototypes

    "activate-current"
                void        user_function      (GtkMenuShell *menushell,
                                                gboolean force_hide,
                                                gpointer user_data);
    "cancel"    void        user_function      (GtkMenuShell *menushell,
                                                gpointer user_data);
    "cycle-focus"
                void        user_function      (GtkMenuShell *menushell,
                                                GtkDirectionType arg1,
                                                gpointer user_data);
    "deactivate"
                void        user_function      (GtkMenuShell *menushell,
                                                gpointer user_data);
    "move-current"
                void        user_function      (GtkMenuShell *menushell,
                                                GtkMenuDirectionType direction,
                                                gpointer user_data);
    "selection-done"
                void        user_function      (GtkMenuShell *menushell,
                                                gpointer user_data);

## Description

A GtkMenuShell is the abstract base class used to derive the GtkMenu and GtkMenuBar subclasses.

A GtkMenuShell is a container of GtkMenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A GtkMenuItem can have a submenu associated with it, allowing for nested hierarchical menus.

## Details

### struct GtkMenuShell

    struct GtkMenuShell;

The GtkMenuShell struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

GList *children; | The list of GtkMenuItem objects contained by this GtkMenuShell.

### gtk_menu_shell_append ()

    void        gtk_menu_shell_append           (GtkMenuShell *menu_shell,
                                                 GtkWidget *child);

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

`menu_shell` : | a GtkMenuShell.
`child` : | The GtkMenuItem to add.

### gtk_menu_shell_prepend ()

    void        gtk_menu_shell_prepend          (GtkMenuShell *menu_shell,
                                                 GtkWidget *child);

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

`menu_shell` : | a GtkMenuShell.
`child` : | The GtkMenuItem to add.

### gtk_menu_shell_insert ()

    void        gtk_menu_shell_insert           (GtkMenuShell *menu_shell,
                                                 GtkWidget *child,
                                                 gint position);

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

`menu_shell` : | a GtkMenuShell.
`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_shell_deactivate ()

    void        gtk_menu_shell_deactivate       (GtkMenuShell *menu_shell);

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

`menu_shell` : | a GtkMenuShell.

### gtk_menu_shell_select_item ()

    void        gtk_menu_shell_select_item      (GtkMenuShell *menu_shell,
                                                 GtkWidget *menu_item);

Selects the menu item from the menu shell.

`menu_shell` : | a GtkMenuShell.
`menu_item` : | The GtkMenuItem to select.

### gtk_menu_shell_deselect ()

    void        gtk_menu_shell_deselect         (GtkMenuShell *menu_shell);

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

`menu_shell` : | a GtkMenuShell.

### gtk_menu_shell_activate_item ()

    void        gtk_menu_shell_activate_item    (GtkMenuShell *menu_shell,
                                                 GtkWidget *menu_item,
                                                 gboolean force_deactivate);

Activates the menu item within the menu shell.

`menu_shell` : | a GtkMenuShell.
`menu_item` : | The GtkMenuItem to activate.
`force_deactivate` : | If TRUE, force the deactivation of the menu shell after the menu item is activated.

### enum GtkMenuDirectionType

    typedef enum
    {
      GTK_MENU_DIR_PARENT,
      GTK_MENU_DIR_CHILD,
      GTK_MENU_DIR_NEXT,
      GTK_MENU_DIR_PREV
    } GtkMenuDirectionType;

An enumeration representing directional movements within a menu.

GTK_MENU_DIR_PARENT | To the parent menu shell.
GTK_MENU_DIR_CHILD | To the submenu, if any, associated with the item.
GTK_MENU_DIR_NEXT | To the next menu item.
GTK_MENU_DIR_PREV | To the previous menu item.

## Signals

### The "activate-current" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                gboolean force_hide,
                                                gpointer user_data);

An action signal that activates the current menu item within the menu shell.

`menushell` : | the object which received the signal.
`force_hide` : | if TRUE, hide the menu after activating the menu item.
`user_data` : | user data set when the signal handler was connected.

### The "cancel" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                gpointer user_data);

An action signal which cancels the selection within the menu shell. Causes the GtkMenuShell::selection-done signal to be emitted.

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

### The "cycle-focus" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                GtkDirectionType arg1,
                                                gpointer user_data);

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

### The "deactivate" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                gpointer user_data);

This signal is emitted when a menu shell is deactivated.

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

### The "move-current" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                GtkMenuDirectionType direction,
                                                gpointer user_data);

An action signal which moves the current menu item in the direction specified by `direction`.

`menushell` : | the object which received the signal.
`direction` : | the direction to move.
`user_data` : | user data set when the signal handler was connected.

### The "selection-done" signal

    void        user_function                  (GtkMenuShell *menushell,
                                                gpointer user_data);

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

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

<<< Previous Page | Home | Up | Next Page >>>
GtkMenuItem | GtkOptionMenu