## GtkItemFactory

GtkItemFactory — A factory for menus

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkItemFactory;
    void        (*GtkPrintFunc)                 (gpointer func_data,
                                                 const gchar *str);
    gchar*      (*GtkTranslateFunc)             (const gchar *path,
                                                 gpointer func_data);
    void        (*GtkItemFactoryCallback)       ();
    void        (*GtkItemFactoryCallback1)      (gpointer callback_data,
                                                 guint callback_action,
                                                 GtkWidget *widget);
    void        (*GtkItemFactoryCallback2)      (GtkWidget *widget,
                                                 gpointer callback_data,
                                                 guint callback_action);
    struct      GtkItemFactoryEntry;
    struct      GtkItemFactoryItem;
    GtkItemFactory* gtk_item_factory_new        (GType container_type,
                                                 const gchar *path,
                                                 GtkAccelGroup *accel_group);
    void        gtk_item_factory_construct      (GtkItemFactory *ifactory,
                                                 GType container_type,
                                                 const gchar *path,
                                                 GtkAccelGroup *accel_group);
    void        gtk_item_factory_add_foreign    (GtkWidget *accel_widget,
                                                 const gchar *full_path,
                                                 GtkAccelGroup *accel_group,
                                                 guint keyval,
                                                 GdkModifierType modifiers);
    GtkItemFactory* gtk_item_factory_from_widget
                                                (GtkWidget *widget);
    G_CONST_RETURN gchar* gtk_item_factory_path_from_widget
                                                (GtkWidget *widget);
    GtkWidget*  gtk_item_factory_get_item       (GtkItemFactory *ifactory,
                                                 const gchar *path);
    GtkWidget*  gtk_item_factory_get_widget     (GtkItemFactory *ifactory,
                                                 const gchar *path);
    GtkWidget*  gtk_item_factory_get_widget_by_action
                                                (GtkItemFactory *ifactory,
                                                 guint action);
    GtkWidget*  gtk_item_factory_get_item_by_action
                                                (GtkItemFactory *ifactory,
                                                 guint action);
    void        gtk_item_factory_create_item    (GtkItemFactory *ifactory,
                                                 GtkItemFactoryEntry *entry,
                                                 gpointer callback_data,
                                                 guint callback_type);
    void        gtk_item_factory_create_items   (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries,
                                                 gpointer callback_data);
    void        gtk_item_factory_create_items_ac
                                                (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries,
                                                 gpointer callback_data,
                                                 guint callback_type);
    void        gtk_item_factory_delete_item    (GtkItemFactory *ifactory,
                                                 const gchar *path);
    void        gtk_item_factory_delete_entry   (GtkItemFactory *ifactory,
                                                 GtkItemFactoryEntry *entry);
    void        gtk_item_factory_delete_entries (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries);
    void        gtk_item_factory_popup          (GtkItemFactory *ifactory,
                                                 guint x,
                                                 guint y,
                                                 guint mouse_button,
                                                 guint32 time_);
    void        gtk_item_factory_popup_with_data
                                                (GtkItemFactory *ifactory,
                                                 gpointer popup_data,
                                                 GtkDestroyNotify destroy,
                                                 guint x,
                                                 guint y,
                                                 guint mouse_button,
                                                 guint32 time_);
    gpointer    gtk_item_factory_popup_data     (GtkItemFactory *ifactory);
    gpointer    gtk_item_factory_popup_data_from_widget
                                                (GtkWidget *widget);
    GtkItemFactory* gtk_item_factory_from_path  (const gchar *path);
    void        gtk_item_factory_create_menu_entries
                                                (guint n_entries,
                                                 GtkMenuEntry *entries);
    void        gtk_item_factories_path_delete  (const gchar *ifactory_path,
                                                 const gchar *path);
    void        gtk_item_factory_set_translate_func
                                                (GtkItemFactory *ifactory,
                                                 GtkTranslateFunc func,
                                                 gpointer data,
                                                 GtkDestroyNotify notify);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkItemFactory

## Description

## Details

### struct GtkItemFactory

    struct GtkItemFactory;

### GtkPrintFunc ()

    void        (*GtkPrintFunc)                 (gpointer func_data,
                                                 const gchar *str);

`func_data` : |
`str` : |

### GtkTranslateFunc ()

    gchar*      (*GtkTranslateFunc)             (const gchar *path,
                                                 gpointer func_data);

`path` : |
`func_data` : |
Returns : |

### GtkItemFactoryCallback ()

    void        (*GtkItemFactoryCallback)       ();

### GtkItemFactoryCallback1 ()

    void        (*GtkItemFactoryCallback1)      (gpointer callback_data,
                                                 guint callback_action,
                                                 GtkWidget *widget);

`callback_data` : |
`callback_action` : |
`widget` : |

### GtkItemFactoryCallback2 ()

    void        (*GtkItemFactoryCallback2)      (GtkWidget *widget,
                                                 gpointer callback_data,
                                                 guint callback_action);

### Warning

`GtkItemFactoryCallback2` is deprecated and should not be used in newly-written code.

`widget` : |
`callback_data` : |
`callback_action` : |

### struct GtkItemFactoryEntry

    struct GtkItemFactoryEntry {

      gchar *path;
      gchar *accelerator;

      GtkItemFactoryCallback callback;
      guint			 callback_action;

      /* possible values:
       * NULL		-> "<Item>"
       * ""			-> "<Item>"
       * "<Title>"		-> create a title item
       * "<Item>"		-> create a simple item
       * "<ImageItem>"	-> create an item holding an image
       * "<StockItem>"	-> create an item holding a stock image
       * "<CheckItem>"	-> create a check item
       * "<ToggleItem>"	-> create a toggle item
       * "<RadioItem>"	-> create a radio item
       * <path>		-> path of a radio item to link against
       * "<Separator>"	-> create a separator
       * "<Tearoff>"	-> create a tearoff separator
       * "<Branch>"		-> create an item to hold sub items
       * "<LastBranch>"	-> create a right justified item to hold sub items
       */
      gchar		 *item_type;

      /* Extra data for some item types:
       *  ImageItem  -> pointer to inlined pixbuf stream
       *  StockItem  -> name of stock item
       */
      gconstpointer extra_data;
    };

### struct GtkItemFactoryItem

    struct GtkItemFactoryItem {

      gchar *path;
      GSList *widgets;
    };

### gtk_item_factory_new ()

    GtkItemFactory* gtk_item_factory_new        (GType container_type,
                                                 const gchar *path,
                                                 GtkAccelGroup *accel_group);

Creates a new GtkItemFactory.

`container_type` : | the kind of menu to create; can be GTK_TYPE_MENU_BAR, GTK_TYPE_MENU or GTK_TYPE_OPTION_MENU
`path` : | the factory path of the new item factory, a string of the form `"<name>"`
`accel_group` : | a GtkAccelGroup to which the accelerators for the menu items will be added, or `NULL` to create a new one
Returns : | a new GtkItemFactory

### gtk_item_factory_construct ()

    void        gtk_item_factory_construct      (GtkItemFactory *ifactory,
                                                 GType container_type,
                                                 const gchar *path,
                                                 GtkAccelGroup *accel_group);

Initializes an item factory.

`ifactory` : | a GtkItemFactory
`container_type` : | the kind of menu to create; can be GTK_TYPE_MENU_BAR, GTK_TYPE_MENU or GTK_TYPE_OPTION_MENU
`path` : | the factory path of `ifactory`, a string of the form `"<name>"`
`accel_group` : | a GtkAccelGroup to which the accelerators for the menu items will be added, or `NULL` to create a new one

### gtk_item_factory_add_foreign ()

    void        gtk_item_factory_add_foreign    (GtkWidget *accel_widget,
                                                 const gchar *full_path,
                                                 GtkAccelGroup *accel_group,
                                                 guint keyval,
                                                 GdkModifierType modifiers);

### Warning

`gtk_item_factory_add_foreign` is deprecated and should not be used in newly-written code. The recommended API for this purpose are the functions gtk_menu_item_set_accel_path() and gtk_widget_set_accel_path(); don't use gtk_item_factory_add_foreign() in new code, since it is likely to be removed in the future.

Installs an accelerator for `accel_widget` in `accel_group`, that causes the ::activate signal to be emitted if the accelerator is activated.

This function can be used to make widgets participate in the accel saving/restoring functionality provided by gtk_accel_map_save() and gtk_accel_map_load(), even if they haven't been created by an item factory.

`accel_widget` : | widget to install an accelerator on
`full_path` : | the full path for the `accel_widget`
`accel_group` : | the accelerator group to install the accelerator in
`keyval` : | key value of the accelerator
`modifiers` : | modifier combination of the accelerator

### gtk_item_factory_from_widget ()

    GtkItemFactory* gtk_item_factory_from_widget
                                                (GtkWidget *widget);

Obtains the item factory from which a widget was created.

`widget` : | a widget
Returns : | the item factory from which `widget` was created, or `NULL`

### gtk_item_factory_path_from_widget ()

    G_CONST_RETURN gchar* gtk_item_factory_path_from_widget
                                                (GtkWidget *widget);

If `widget` has been created by an item factory, returns the full path to it. (The full path of a widget is the concatenation of the factory path specified in gtk_item_factory_new() with the path specified in the GtkItemFactoryEntry from which the widget was created.)

`widget` : | a widget
Returns : | the full path to `widget` if it has been created by an item factory, `NULL` otherwise. This value is owned by GTK+ and must not be modified or freed.

### gtk_item_factory_get_item ()

    GtkWidget*  gtk_item_factory_get_item       (GtkItemFactory *ifactory,
                                                 const gchar *path);

Obtains the menu item which corresponds to `path`.

If the widget corresponding to `path` is a menu item which opens a submenu, then the item is returned. If you are interested in the submenu, use gtk_item_factory_get_widget() instead.

`ifactory` : | a GtkItemFactory
`path` : | the path to the menu item
Returns : | the menu item for the given path, or `NULL` if `path` doesn't lead to a menu item

### gtk_item_factory_get_widget ()

    GtkWidget*  gtk_item_factory_get_widget     (GtkItemFactory *ifactory,
                                                 const gchar *path);

Obtains the widget which corresponds to `path`.

If the widget corresponding to `path` is a menu item which opens a submenu, then the submenu is returned. If you are interested in the menu item, use gtk_item_factory_get_item() instead.

`ifactory` : | a GtkItemFactory
`path` : | the path to the widget
Returns : | the widget for the given path, or `NULL` if `path` doesn't lead to a widget

### gtk_item_factory_get_widget_by_action ()

    GtkWidget*  gtk_item_factory_get_widget_by_action
                                                (GtkItemFactory *ifactory,
                                                 guint action);

Obtains the widget which was constructed from the GtkItemFactoryEntry with the given `action`.

If there are multiple items with the same action, the result is undefined.

`ifactory` : | a GtkItemFactory
`action` : | an action as specified in the `callback_action` field of GtkItemFactoryEntry
Returns : | the widget which corresponds to the given action, or `NULL` if no widget was found

### gtk_item_factory_get_item_by_action ()

    GtkWidget*  gtk_item_factory_get_item_by_action
                                                (GtkItemFactory *ifactory,
                                                 guint action);

Obtains the menu item which was constructed from the first GtkItemFactoryEntry with the given `action`.

`ifactory` : | a GtkItemFactory
`action` : | an action as specified in the `callback_action` field of GtkItemFactoryEntry
Returns : | the menu item which corresponds to the given action, or `NULL` if no menu item was found

### gtk_item_factory_create_item ()

    void        gtk_item_factory_create_item    (GtkItemFactory *ifactory,
                                                 GtkItemFactoryEntry *entry,
                                                 gpointer callback_data,
                                                 guint callback_type);

Creates an item for `entry`.

`ifactory` : | a GtkItemFactory
`entry` : | the GtkItemFactoryEntry to create an item for
`callback_data` : | data passed to the callback function of `entry`
`callback_type` : | 1 if the callback function of `entry` is of type GtkItemFactoryCallback1, 2 if it is of type GtkItemFactoryCallback2

### gtk_item_factory_create_items ()

    void        gtk_item_factory_create_items   (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries,
                                                 gpointer callback_data);

Creates the menu items from the `entries`.

`ifactory` : | a GtkItemFactory
`n_entries` : | the length of `entries`
`entries` : | an array of GtkItemFactoryEntrys whose `callback` members must by of type GtkItemFactoryCallback1
`callback_data` : | data passed to the callback functions of all entries

### gtk_item_factory_create_items_ac ()

    void        gtk_item_factory_create_items_ac
                                                (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries,
                                                 gpointer callback_data,
                                                 guint callback_type);

### Warning

`gtk_item_factory_create_items_ac` is deprecated and should not be used in newly-written code.

Creates the menu items from the `entries`.

`ifactory` : | a GtkItemFactory
`n_entries` : | the length of `entries`
`entries` : | an array of GtkItemFactoryEntrys
`callback_data` : | data passed to the callback functions of all entries
`callback_type` : | 1 if the callback functions in `entries` are of type GtkItemFactoryCallback1, 2 if they are of type GtkItemFactoryCallback2

### gtk_item_factory_delete_item ()

    void        gtk_item_factory_delete_item    (GtkItemFactory *ifactory,
                                                 const gchar *path);

Deletes the menu item which was created for `path` by the given item factory.

`ifactory` : | a GtkItemFactory
`path` : | a path

### gtk_item_factory_delete_entry ()

    void        gtk_item_factory_delete_entry   (GtkItemFactory *ifactory,
                                                 GtkItemFactoryEntry *entry);

Deletes the menu item which was created from `entry` by the given item factory.

`ifactory` : | a GtkItemFactory
`entry` : | a GtkItemFactoryEntry

### gtk_item_factory_delete_entries ()

    void        gtk_item_factory_delete_entries (GtkItemFactory *ifactory,
                                                 guint n_entries,
                                                 GtkItemFactoryEntry *entries);

Deletes the menu items which were created from the `entries` by the given item factory.

`ifactory` : | a GtkItemFactory
`n_entries` : | the length of `entries`
`entries` : | an array of GtkItemFactoryEntrys

### gtk_item_factory_popup ()

    void        gtk_item_factory_popup          (GtkItemFactory *ifactory,
                                                 guint x,
                                                 guint y,
                                                 guint mouse_button,
                                                 guint32 time_);

Pops up the menu constructed from the item factory at (`x`, `y`).

The `mouse_button` parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, `mouse_button` should be 0.

The `time_` parameter should be the time stamp of the event that initiated the popup. If such an event is not available, use gtk_get_current_event_time() instead.

The operation of the `mouse_button` and the `time_` parameter is the same as the `button` and `activation_time` parameters for gtk_menu_popup().

`ifactory` : | a GtkItemFactory of type GTK_TYPE_MENU (see gtk_item_factory_new())
`x` : | the x position
`y` : | the y position
`mouse_button` : | the mouse button which was pressed to initiate the popup
`time_` : | the time at which the activation event occurred

### gtk_item_factory_popup_with_data ()

    void        gtk_item_factory_popup_with_data
                                                (GtkItemFactory *ifactory,
                                                 gpointer popup_data,
                                                 GtkDestroyNotify destroy,
                                                 guint x,
                                                 guint y,
                                                 guint mouse_button,
                                                 guint32 time_);

Pops up the menu constructed from the item factory at (`x`, `y`). Callbacks can access the `popup_data` while the menu is posted via gtk_item_factory_popup_data() and gtk_item_factory_popup_data_from_widget().

The `mouse_button` parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, `mouse_button` should be 0.

The `time_` parameter should be the time stamp of the event that initiated the popup. If such an event is not available, use gtk_get_current_event_time() instead.

The operation of the `mouse_button` and the `time_` parameters is the same as the `button` and `activation_time` parameters for gtk_menu_popup().

`ifactory` : | a GtkItemFactory of type GTK_TYPE_MENU (see gtk_item_factory_new())
`popup_data` : | data available for callbacks while the menu is posted
`destroy` : | a GtkDestroyNotify function to be called on `popup_data` when the menu is unposted
`x` : | the x position
`y` : | the y position
`mouse_button` : | the mouse button which was pressed to initiate the popup
`time_` : | the time at which the activation event occurred

### gtk_item_factory_popup_data ()

    gpointer    gtk_item_factory_popup_data     (GtkItemFactory *ifactory);

Obtains the `popup_data` which was passed to gtk_item_factory_popup_with_data(). This data is available until the menu is popped down again.

`ifactory` : | a GtkItemFactory
Returns : | `popup_data` associated with `ifactory`

### gtk_item_factory_popup_data_from_widget ()

    gpointer    gtk_item_factory_popup_data_from_widget
                                                (GtkWidget *widget);

Obtains the `popup_data` which was passed to gtk_item_factory_popup_with_data(). This data is available until the menu is popped down again.

`widget` : | a widget
Returns : | `popup_data` associated with the item factory from which `widget` was created, or `NULL` if `widget` wasn't created by an item factory

### gtk_item_factory_from_path ()

    GtkItemFactory* gtk_item_factory_from_path  (const gchar *path);

### Warning

`gtk_item_factory_from_path` is deprecated and should not be used in newly-written code.

Finds an item factory which has been constructed using the `"<name>"` prefix of `path` as the `path` argument for gtk_item_factory_new().

`path` : | a string starting with a factory path of the form `"<name>"`
Returns : | the GtkItemFactory created for the given factory path, or `NULL`

### gtk_item_factory_create_menu_entries ()

    void        gtk_item_factory_create_menu_entries
                                                (guint n_entries,
                                                 GtkMenuEntry *entries);

### Warning

`gtk_item_factory_create_menu_entries` is deprecated and should not be used in newly-written code.

Creates the menu items from the `entries`.

`n_entries` : | the length of `entries`
`entries` : | an array of GtkMenuEntrys

### gtk_item_factories_path_delete ()

    void        gtk_item_factories_path_delete  (const gchar *ifactory_path,
                                                 const gchar *path);

### Warning

`gtk_item_factories_path_delete` is deprecated and should not be used in newly-written code.

Deletes all widgets constructed from the specified path.

`ifactory_path` : | a factory path to prepend to `path`. May be `NULL` if `path` starts with a factory path
`path` : | a path

### gtk_item_factory_set_translate_func ()

    void        gtk_item_factory_set_translate_func
                                                (GtkItemFactory *ifactory,
                                                 GtkTranslateFunc func,
                                                 gpointer data,
                                                 GtkDestroyNotify notify);

Sets a function to be used for translating the path elements before they are displayed.

`ifactory` : | a GtkItemFactory
`func` : | the GtkTranslateFunc function to be used to translate path elements
`data` : | data to pass to `func` and `notify`
`notify` : | a GtkDestroyNotify function to be called when `ifactory` is destroyed and when the translation function is changed again