GtkItemFactory: GTK+ 2 Reference Manual

## GtkItemFactory GtkItemFactory — A factory for menus |

## Functions

void | (*GtkPrintFunc) ()
gchar * | (*GtkTranslateFunc) ()
void | (*GtkItemFactoryCallback) ()
void | (*GtkItemFactoryCallback1) ()
void | (*GtkItemFactoryCallback2) ()
GtkItemFactory * | gtk_item_factory_new ()
void | gtk_item_factory_construct ()
void | gtk_item_factory_add_foreign ()
GtkItemFactory * | gtk_item_factory_from_widget ()
const gchar * | gtk_item_factory_path_from_widget ()
GtkWidget * | gtk_item_factory_get_item ()
GtkWidget * | gtk_item_factory_get_widget ()
GtkWidget * | gtk_item_factory_get_widget_by_action ()
GtkWidget * | gtk_item_factory_get_item_by_action ()
void | gtk_item_factory_create_item ()
void | gtk_item_factory_create_items ()
void | gtk_item_factory_create_items_ac ()
void | gtk_item_factory_delete_item ()
void | gtk_item_factory_delete_entry ()
void | gtk_item_factory_delete_entries ()
void | gtk_item_factory_popup ()
void | gtk_item_factory_popup_with_data ()
gpointer | gtk_item_factory_popup_data ()
gpointer | gtk_item_factory_popup_data_from_widget ()
GtkItemFactory * | gtk_item_factory_from_path ()
void | gtk_item_factory_create_menu_entries ()
void | gtk_item_factories_path_delete ()
void | gtk_item_factory_set_translate_func ()

## Types and Values

struct | GtkItemFactory
struct | GtkItemFactoryEntry
struct | GtkItemFactoryItem

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkItemFactory

## Includes

    #include <gtk/gtk.h>

## Description

As of GTK+ 2.4, GtkItemFactory has been deprecated in favour of GtkUIManager.

## Functions

### GtkPrintFunc ()

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

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

### GtkTranslateFunc ()

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

The function used to translate messages in e.g. GtkIconFactory and GtkActionGroup.

#### Parameters

path | The id of the message. In GtkItemFactory this will be a path from a GtkItemFactoryEntry, in GtkActionGroup, it will be a label or tooltip from a GtkActionEntry. |
func_data | user data passed in when registering the function |

#### Returns

the translated message

### GtkItemFactoryCallback ()

    void
    (*GtkItemFactoryCallback) ();

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

### GtkItemFactoryCallback1 ()

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

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

### GtkItemFactoryCallback2 ()

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

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

### gtk_item_factory_new ()

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

`gtk_item_factory_new` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Creates a new GtkItemFactory.

Beware that the returned object does not have a floating reference.

#### Parameters

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. | [allow-none]

#### Returns

a new GtkItemFactory

### gtk_item_factory_construct ()

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

`gtk_item_factory_construct` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Initializes an item factory.

#### Parameters

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);

`gtk_item_factory_add_foreign` has been deprecated since version 2.4 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.

#### Parameters

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);

`gtk_item_factory_from_widget` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Obtains the item factory from which a widget was created.

#### Parameters

widget | a widget |

#### Returns

the item factory from which `widget` was created, or `NULL`.

[allow-none]

### gtk_item_factory_path_from_widget ()

    const gchar *
    gtk_item_factory_path_from_widget (GtkWidget *widget);

`gtk_item_factory_path_from_widget` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.)

#### Parameters

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);

`gtk_item_factory_get_item` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.

#### Parameters

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.

[allow-none]

### gtk_item_factory_get_widget ()

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

`gtk_item_factory_get_widget` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.

#### Parameters

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.

[allow-none]

### gtk_item_factory_get_widget_by_action ()

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

`gtk_item_factory_get_widget_by_action` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.

#### Parameters

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.

[allow-none]

### gtk_item_factory_get_item_by_action ()

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

`gtk_item_factory_get_item_by_action` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

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.

[allow-none]

### gtk_item_factory_create_item ()

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

`gtk_item_factory_create_item` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Creates an item for `entry` .

#### Parameters

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);

`gtk_item_factory_create_items` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Creates the menu items from the `entries` .

#### Parameters

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);

`gtk_item_factory_create_items_ac` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Creates the menu items from the `entries` .

#### Parameters

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);

`gtk_item_factory_delete_item` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

ifactory | a GtkItemFactory |
path | a path |

### gtk_item_factory_delete_entry ()

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

`gtk_item_factory_delete_entry` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

ifactory | a GtkItemFactory |
entry | a GtkItemFactoryEntry |

### gtk_item_factory_delete_entries ()

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

`gtk_item_factory_delete_entries` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

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_);

`gtk_item_factory_popup` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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()`.

#### Parameters

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,
                                      GDestroyNotify destroy,
                                      guint x,
                                      guint y,
                                      guint mouse_button,
                                      guint32 time_);

`gtk_item_factory_popup_with_data` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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()`.

#### Parameters

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 GDestroyNotify 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);

`gtk_item_factory_popup_data` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.

#### Parameters

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);

`gtk_item_factory_popup_data_from_widget` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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.

#### Parameters

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);

`gtk_item_factory_from_path` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

path | a string starting with a factory path of the form `"<name>"` |

#### Returns

the GtkItemFactory created for the given factory path, or `NULL`.

[allow-none]

### gtk_item_factory_create_menu_entries ()

    void
    gtk_item_factory_create_menu_entries (guint n_entries,
                                          GtkMenuEntry *entries);

`gtk_item_factory_create_menu_entries` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Creates the menu items from the `entries` .

#### Parameters

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);

`gtk_item_factories_path_delete` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

Deletes all widgets constructed from the specified path.

#### Parameters

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,
                                         GDestroyNotify notify);

`gtk_item_factory_set_translate_func` has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkUIManager instead.

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

#### Parameters

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

## Types and Values

### struct GtkItemFactory

    struct GtkItemFactory;

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

### 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;
    };

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

### struct GtkItemFactoryItem

    struct GtkItemFactoryItem {
      gchar *path;
      GSList *widgets;
    };

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