gtk.ItemFactory
Prev | The gtk Class Reference | Next

## gtk.ItemFactory

gtk.ItemFactory — creates menus, menubars and option menus from a data description.

## Synopsis

    class gtk.ItemFactory(gtk.Object):
        gtk.ItemFactory(container_type, path, accel_group=None)
        def construct(container_type, path, accel_group)
        def get_item(path)
        def get_widget(path)
        def get_widget_by_action(action)
        def get_item_by_action(action)
        def create_items(entries, callback_data=None)
        def delete_item(path)
        def popup(x, y, mouse_button, time=GDK_CURRENT_TIME)

    Functions

        def gtk.item_factory_from_widget(widget)
        def gtk.item_factory_path_from_widget(widget)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.ItemFactory

## gtk.ItemFactory Properties

gtk.Object Properties

## gtk.ItemFactory Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

## Description

### Warning

`gtk.ItemFactory` is deprecated in PyGTK 2.4 and above. The `gtk.UIManager` should be used instead.

The `gtk.ItemFactory` provides a convenient way to create and manage menus, menubars and option menus from a data description. The data description is a tuple or list containing a list of entry tuples that each describe an individual menu, menuitem, etc. Each entry tuple may contain the following entry fields though only the path must be specified; the other fields are optional:

- A path that defines the logical position of the menu or menuitem in the menu hierarchy. a path is similar to a file path in that it starts with a slash (/) character and all components are joined by a slash (/) character. The last component may have an underscore that indicates that the following character is to be used as the accelerator mnemonic.

- An accelerator that defines a key sequence that will activate the menuitem. The key sequence is a set of zero or more modifiers followed by a single key. The modifier keys are:

  "<alt>" | Alt-Lor Alt-R
  "<ctl>", "<ctrl>", "<control>", | Ctrl-Lor Ctrl-R
  "<shift>", "<shft>", | Shift-Lor Shift-R

- A callback function or method that will be invoked when the menu item is activated or the accelerator key sequence is pressed. The callback function is defined as either:

          def callback(callback_data, callback_action, widget)
          def callback(callback_action, widget)

  where `callback_action` is the callback action defined below, `callback_data` is the data passed with the `create_items`() method and `widget` is the menuitem widget. The second definition must be used if no `callback_data` argument is specified by the call to `create_items`().

- A callback action that is an arbitrary integer value.

- An item type is a string describing the type of the item:

  "None", "", "Item", | a simple menu item
  "<Title>" | a title item
  "<ImageItem>" | an image item
  "<StockItem>" | an item holding a stock image
  "<CheckItem>" | a check item
  "<ToggleItem>" | a toggle item
  "<RadioItem>" | a radio item
  <path> | the path of a radio item group to add item to
  "<Separator>" | a separator
  "<Tearoff>" | a tearoff separator
  "<Branch>" | an item to hold sub items
  "<LastBranch>" | a right justified item to hold sub items

- extra data that is either a `gtk.gdk.Pixbuf` or a stock ID

## Constructor

        gtk.ItemFactory(container_type, path, accel_group=None)

`container_type` : | the kind of menu to create; one of: `gtk.MenuBar`, `gtk.Menu` or `gtk.OptionMenu`.
`path` : | the path of the new item factory, a string of the form `"<name>"`
`accel_group` : | a `gtk.AccelGroup` to which the accelerators for the menu items will be added, or `None` to create a new one
Returns : | a new `gtk.ItemFactory`

Creates a new `gtk.ItemFactory` object.

## Methods

### gtk.ItemFactory.construct

        def construct(container_type, path, accel_group)

`container_type` : | the kind of menu to create; one of: `gtk.MenuBar`, `gtk.Menu` or `gtk.OptionMenu`.
`path` : | the path of the item factory, a string of the form `"<name>"`
`accel_group` : | a `gtk.AccelGroup` to which the accelerators for the menu items will be added, or `None` to create a new one

The `construct`() method initializes an item factory.

### gtk.ItemFactory.get_item

        def get_item(path)

`path` : | the path to the menu item
Returns : | the menu item with the specified `path`, or `None` if `path` doesn't lead to a menu item

The `get_item`() method returns the menu item that corresponds to `path`. If the widget corresponding to `path` is a menu item that opens a submenu, then the item is returned. If you are interested in the submenu, use the `get_widget`() method instead.

### gtk.ItemFactory.get_widget

        def get_widget(path)

`path` : | the path to the widget
Returns : | the widget associated with the specified `path`, or `None` if `path` doesn't lead to a widget

The `get_widget`() method returns the widget that corresponds to `path`. If the widget corresponding to `path` is a menu item that opens a submenu, then the submenu is returned. If you are interested in the menu item, use `get_item`() instead.

### gtk.ItemFactory.get_widget_by_action

        def get_widget_by_action(action)

`action` : | a callback action value
Returns : | the widget that corresponds to the given action, or `None` if no widget was found

The `get_widget_by_action`() method returns the widget that is associated with the specified `action`. If there are multiple items with the same `action`, the result is undefined.

### gtk.ItemFactory.get_item_by_action

        def get_item_by_action(action)

`action` : | a callback action value
Returns : | the menu item that corresponds to the specified `action`, or `None` if no menu item was found

The `get_item_by_action`() returns the menu item that is associated with the specified `action`.

### gtk.ItemFactory.create_items

        def create_items(entries, callback_data=None)

`entries` : | a tuple or list of item factory entries
`callback_data` : | optional data passed to the callback functions of all entries

The `create_items`() method creates the menu items from the specified item factory `entries`. If no `callback_data` is specified it will not be passed to the callback functions i.e the callback functions will be passed one less argument.

### gtk.ItemFactory.delete_item

        def delete_item(path)

`path` : | a path

The `delete_item`() method deletes the menu item that was created with the specified `path`.

### gtk.ItemFactory.popup

        def popup(x, y, mouse_button, time=0L)

`x` : | the x position
`y` : | the y position
`mouse_button` : | the mouse button that was pressed to initiate this action
`time` : | an optional timestamp for this action; default is 0L which means use the current time

The `popup`() method pops up the menu constructed from the item factory at the specified location (`x`, `y`). This method is generally invoked in response to a "button_press_event" so the arguments are retrieved from the event information.

## Functions

### gtk.item_factory_from_widget

        def gtk.item_factory_from_widget(widget)

`widget` : | a `gtk.Widget` object
Returns : | the `gtk.ItemFactory` that created `widget`

The `gtk.item_factory_from_widget`() function returns the `gtk.ItemFactory` object that created the `gtk.Widget` specified by `widget`.

### gtk.item_factory_path_from_widget

        def gtk.item_factory_path_from_widget(widget)

`widget` : | a `gtk.Widget` object
Returns : | the full path to the `gtk.ItemFactory` that created `widget`

The `gtk.item_factory_path_from_widget`() function returns the full path to the `gtk.ItemFactory` that created the `gtk.Widget` specified by `widget`.

Prev | Up | Next
gtk.Item | Home | gtk.Label