Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gtk::ItemFactory Class Reference

A GtkItemFactory C++ wrapper class. More...

`#include <inti/gtk/itemfactory.h>`

Inheritance diagram for Inti::Gtk::ItemFactory:

List of all members.

## Public Types

- typedef Slot0< void > DestroySlot
    Signature of the callback slot to be called when a popup menu is unposted.

## Public Member Functions

Constructors

- ItemFactory ()
    Construct a new ItemFactory with the container type GTK_TYPE_MENU_BAR, the path "\<main\>" and a default accelerator group.
- ItemFactory (GType container_type, const char *path, AccelGroup *accel_group=0)
    Construct a new ItemFactory with the specified container type, path and accelerator group.
- virtual ~ItemFactory ()
    Destructor.

Accessors

- GtkItemFactory * gtk_item_factory () const
    Get a pointer to the GtkItemFactory structure.
- GtkItemFactoryClass * gtk_item_factory_class () const
    Get a pointer to the GtkItemFactoryClass structure.
- operator GtkItemFactory * () const
    Conversion operator; safely converts an ItemFactory to a GtkItemFactory pointer.
- AccelGroup * accel_group () const
    Gets the accelerator group for the ItemFactory.
- MenuBar * menu_bar () const
    Returns the MenuBar if the container type is GTK_TYPE_MENU_BAR, otherwise it returns null.
- Menu * menu () const
    Returns the Menu if the container type is GTK_TYPE_MENU, otherwise it returns null.
- OptionMenu * option_menu () const
    Returns the OptionMenu if the container type is GTK_TYPE_OPTION_MENU, otherwise it returns null.
- Menu * submenu (const char *path) const
    Obtains the submenu which corresponds to path.
- Menu * submenu_by_action (unsigned int action) const
    Obtains the submenu which was constructed from the ItemFactoryEntry with the given action.
- MenuItem * get_item (const char *path) const
    Obtains the menu item which corresponds to path.
- MenuItem * get_item_by_action (unsigned int action) const
    Obtains the menu item which was constructed from the first ItemFactoryEntry with the given action.

Methods

- void delete_item (const char *path)
    Deletes the menu item which was created for path.
- void popup (unsigned int x, unsigned int y, unsigned int mouse_button, unsigned int time=GDK_CURRENT_TIME)
    Pops up the menu constructed from the item factory at (x, y).
- void popup (unsigned int x, unsigned int y, unsigned int mouse_button, const DestroySlot *destroy, unsigned int time=GDK_CURRENT_TIME)
    Pops up the menu constructed from the item factory at (x, y).

Templates

- template<typename T> void create_item (T &owner, ItemFactoryEntry< T > &entry)
    Creates a menu item for entry.
- template<typename T> void create_items (T &owner, std::vector< ItemFactoryEntry< T > * > &entries)
    Creates the menu items from entries.
- template<typename T> void create_items (T &owner)
    Creates the menu items from the entries in owner's item factory map.
- template<typename T> void delete_entry (ItemFactoryEntry< T > &entry)
    Deletes the menu item which was created from entry.
- template<typename T> void delete_entries (std::vector< ItemFactoryEntry< T > * > &entries)
    Deletes the menu items which were created from entries.
- template<typename T> void delete_entries (T &owner)
    Deletes the menu items which were created from the entries in owner's item factory map.

## Static Public Member Functions

- String path_from_widget (const Widget &widget)
    If widget has been created by an item factory, returns the full path to it.
- String path_from_entry (const char *entry_path)
    Returns entry_path without any underscores.
- ItemFactory * from_widget (const Widget &widget)
    Obtains the item factory from which a widget was created.

## Protected Member Functions

Constructors

- ItemFactory (GtkItemFactory *item_factory, bool reference=true)
    Construct a new ItemFactory from an existing GtkItemFactory.

## Detailed Description

A GtkItemFactory C++ wrapper class.

Itemfactories are a quick way to implement a menu heirarchy. You can create simple menus or entire an entire menu bar with its associated menu items and submenus. Item factories are easy to use, especially when creating many menus, and there is no difference in appearence from menus created manually. There are some trade-offs in control:

- Each class can only have one item factory map.
- Each menu item in the item factory map must be connected to its own slot.

What you need to decide is which is more important, control or ease of programming. You will find example code using an ItemFactory in itemfactory.cc in the <examples/menu> directory (see the itemfactory.h file reference).

The 8 basic steps in using an ItemFactory are:

1. Add an ItemFactory pointer to your class declaration. Make this a smart pointer so you don't have to call unref().
2. Add the DECLARE_ITEM_FACTORY_MAP macro to you class declaration. This macro takes the class name as an argument.
3. In the class source file define your item factory map. The map is just a series of macros. It begins with the BEGIN_ITEM_FACTORY_MAP macro which takes the class name as an argument. Then comes a list of one or more menu item macros, one for each submenu and menu item in the menu. Last comes the END_ITEM_FACTORY_MAP macro. Together these macros define an array of Gtk::ItemFactoryEntry that contains all the information needed to implement the menu hierarchy.
4. Construct a new ItemFactory.
5. Call Gtk::Window::add_accel_group() to add the AccelGroup to the owner window. If you don't pass an AccelGroup to the ItemFactory constructor the ItemFactory will create a new AccelGroup for you. In this case you can call accel_group() to get the AccelGroup to pass to Gtk::Window::add_accel_group().
6. Call create_items() to create the menus and menu items in the item factory map. This method takes a reference to the class, which must be a class derived from G::Object.
7. Call one of the Accessor methods menu_bar(), menu() or option_menu() to get a pointer to the new menu. Use this pointer to connect any extra signals and to add or pack the new menu into another widget.
8. Call submenu() or get_item() if you need to access a submenu or menu item. Note, the menu item path string you pass as an argument is without any preceding underscore. This is because the underscores specifed in the item factory map are parsed out of the path string by GTK+.

And that's it! Simple? Well it is once you get used to it.

## Member Typedef Documentation

typedef Slot0<void> Inti::Gtk::ItemFactory::DestroySlot

Signature of the callback slot to be called when a popup menu is unposted.

Example: Method signature for DestroySlot.

                 void method();

## Constructor & Destructor Documentation

Inti::Gtk::ItemFactory::ItemFactory | ( | GtkItemFactory * | item_factory,
|  | bool | reference = true
| ) | `[explicit, protected]`

Construct a new ItemFactory from an existing GtkItemFactory.

Parameters:

  item_factory | A pointer to a GtkItemFactory.
  reference | Set false if the initial reference count is floating, set true if it's not.

The item_factory can be a newly created GtkItemFactory or an existing GtkItemFactory (see G::Object::Object).

Inti::Gtk::ItemFactory::ItemFactory | ( | GType | container_type,
|  | const char * | path,
|  | AccelGroup * | accel_group = 0
| ) |

Construct a new ItemFactory with the specified container type, path and accelerator group.

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 | An AccelGroup to which the accelerators for the menu items will be added, or null to create a new one.

## Member Function Documentation

template<typename T>
void Inti::Gtk::ItemFactory::create_item | ( | T & | owner,
|  | ItemFactoryEntry< T > & | entry
| ) | `[inline]`

Creates a menu item for entry.

Parameters:

  owner | The owner of the item factory.
  entry | The ItemFactoryEntry to create an item for.

template<typename T>
void Inti::Gtk::ItemFactory::create_items | ( | T & | owner | ) | `[inline]`

Creates the menu items from the entries in owner's item factory map.

Parameters:

  owner | The owner of the item factory.

template<typename T>
void Inti::Gtk::ItemFactory::create_items | ( | T & | owner,
|  | std::vector< ItemFactoryEntry< T > * > & | entries
| ) | `[inline]`

Creates the menu items from entries.

Parameters:

  owner | The owner of the item factory.
  entries | A vector of ItemFactoryEntry.

template<typename T>
void Inti::Gtk::ItemFactory::delete_entries | ( | T & | owner | ) | `[inline]`

Deletes the menu items which were created from the entries in owner's item factory map.

Parameters:

  owner | The owner of the item factory.

template<typename T>
void Inti::Gtk::ItemFactory::delete_entries | ( | std::vector< ItemFactoryEntry< T > * > & | entries | ) | `[inline]`

Deletes the menu items which were created from entries.

Parameters:

  entries | An vector of ItemFactoryEntry.

template<typename T>
void Inti::Gtk::ItemFactory::delete_entry | ( | ItemFactoryEntry< T > & | entry | ) | `[inline]`

Deletes the menu item which was created from entry.

Parameters:

  entry | A ItemFactoryEntry.

void Inti::Gtk::ItemFactory::delete_item | ( | const char * | path | ) |

Deletes the menu item which was created for path.

Parameters:

  path | A path.

ItemFactory* Inti::Gtk::ItemFactory::from_widget | ( | const Widget & | widget | ) | `[static]`

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.

MenuItem* Inti::Gtk::ItemFactory::get_item | ( | const char * | path | ) | const

Obtains the menu item which corresponds to path.

Parameters:

  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.

MenuItem* Inti::Gtk::ItemFactory::get_item_by_action | ( | unsigned int | action | ) | const

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

Parameters:

  action | An action as specified in the callback_action field of ItemFactoryEntry.

Returns:
  The menu item which corresponds to the given action, or null if no menu item was found.

String Inti::Gtk::ItemFactory::path_from_entry | ( | const char * | entry_path | ) | `[static]`

Returns entry_path without any underscores.

Parameters:

  entry_path | The path for an entry as specified in the item factroy map.

Returns:
  The entry path without any underscores.

This method is used internally by ItemFactory to parse out underscores from the entry paths specified in an item factroy map. It is provided as a separate public method in case you ever need to iterate over each entry in a map. If you do you will need the entry path without any underscores.

String Inti::Gtk::ItemFactory::path_from_widget | ( | const Widget & | widget | ) | `[static]`

If widget has been created by an item factory, returns the full path to it.

Parameters:

  widget | A widget.

Returns:
  The full path to widget if it has been created by an item factory, null otherwise.

The full path of a widget is the concatenation of the factory path specified in the ItemFactory constructor with the path specified in the ItemFactoryEntry from which the widget was created.

void Inti::Gtk::ItemFactory::popup | ( | unsigned int | x,
|  | unsigned int | y,
|  | unsigned int | mouse_button,
|  | const DestroySlot * | destroy,
|  | unsigned int | time = GDK_CURRENT_TIME
| ) |

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

Parameters:

  x | The x position.
  y | The y position.
  mouse_button | The mouse button which was pressed to initiate the popup.
  destroy | A callback slot to be called when the menu is unposted.
  time | The time at which the activation event occurred.

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

void Inti::Gtk::ItemFactory::popup | ( | unsigned int | x,
|  | unsigned int | y,
|  | unsigned int | mouse_button,
|  | unsigned int | time = GDK_CURRENT_TIME
| ) |

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

Parameters:

  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.

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

Menu* Inti::Gtk::ItemFactory::submenu | ( | const char * | path | ) | const

Obtains the submenu which corresponds to path.

Parameters:

  path | The path to the submenu.

Returns:
  The submenu for the given path, or null if path doesn't lead to a submenu.

Menu* Inti::Gtk::ItemFactory::submenu_by_action | ( | unsigned int | action | ) | const

Obtains the submenu which was constructed from the ItemFactoryEntry with the given action.

Parameters:

  action | An action as specified in the callback_action field of ItemFactoryEntry.

Returns:
  The submenu which corresponds to the given action, or null if no submenu was found.

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

The documentation for this class was generated from the following file:

- itemfactory.h

Main Page - Footer