Reference Manual
Inti Logo
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:

Inti::Gtk::Object Inti::G::Object Inti::G::TypeInstance Inti::MemoryHandler Inti::ReferencedBase List of all members.

Public Types

Public Member Functions

Constructors
Accessors
Methods
Templates

Static Public Member Functions

Protected Member Functions

Constructors

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:

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: Main Page - Footer


Generated on Sun Sep 14 20:08:16 2003 for Inti by doxygen 1.3.2 written by Dimitri van Heesch, © 1997-2002