Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gtk::ActionGroup Class Reference

A GtkActionGroup C++ wrapper class. More...

#include <xfc/gtk/actiongroup.hh>

Inheritance diagram for Xfc::Gtk::ActionGroup:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable List of all members.

Signal Prototypes

Public Types

Public Member Functions

Constructors
Accessors
Methods
Action create and add methods.
ToggleAction create and add methods.
Signal Proxies

Protected Member Functions

Constructors

Detailed Description

A GtkActionGroup C++ wrapper class.

Actions are organised into groups. An action group is essentially a map from names to Action objects. All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window's menus would be constructed from a combination of two action groups.

Accelerators are handled by the GTK+ accelerator map. All actions are assigned an accelerator path (which normally has the form <Actions>/group-name/action-name) and a shortcut is associated with this accelerator path. All menuitems and toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item.

GTK+ doesn't let you override action group signals so there is no corresponding ActionGroupSignals class. This means that if you want to respond to an action group signal you must connect to it using the provided proxy signal function.

Adding actions to an action group:

When adding an action to an action group you must remember to call unref(). This is because actions are G::Objects that are created with a reference count of one that the caller owns. An action group increments the reference count of the actions you add. So, if you don't want to hang onto to a reference, which you usually wont, you must call unref() to release the inital reference count.

There are two ways to add actions to an action group. The easiest way is to use one of the overloaded add() methods. These methods create the action, add it to the action group, unreference the action and return a pointer to the action that can then be connected to a callback slot. For example:

    Gtk::ActionGroup *group = new Gtk::ActionGroup("TestActions");
    Gtk::Action *action = group->add("cut", "C_ut", Gtk::StockId::CUT, Gtk::AccelKey("<control>X"), "Cut selected text to clipboard");  
    action->signal_activate().connect(sigc::mem_fun(this, &Window::on_cut_action));
    action = group->add("copy", "_Copy", Gtk::StockId::COPY, Gtk::AccelKey("<control>C"), "Copy selected text to clipboard");
    action->signal_activate().connect(sigc::mem_fun(this, &Window::on_copy_action));
    action = group->add("paste", "_Paste", Gtk::StockId::PASTE, Gtk::AccelKey("<control>V"), "Paste text from the clipboard");
    action->signal_activate().connect(sigc::mem_fun(this, &Window::on_paste_action));
    action = group->add("quit", Gtk::StockId::QUIT, Gtk::AccelKey("<control>Q"), "Quit the application");       
    action->signal_activate().connect(sigc::ptr_fun(&Xfc::Main::quit));

The other way to add actions to an action group is to create each action yourself and call one of the add_action() methods to add it to the action group. This will require a few more lines of code because you also need to set the tooltip, connect up the action's callback slot and unreference the action. For example, the above code would look like this:

    Gtk::ActionGroup *group = new Gtk::ActionGroup("TestActions");
    Gtk::Action *action = new Gtk::Action("cut", "C_ut", StockId::CUT)
    action->set_tooltip("Cut selected text to clipboard");      
    group->add_action(*action, Gtk::AccelKey("<control>X"), sigc::mem_fun(this, &Window::on_cut_action));
    action->unref();    
    action = new Gtk::Action("copy", "_Copy", StockId::COPY)
    action->set_tooltip("Copy selected text to clipboard");     
    group->add_action(*action, Gtk::AccelKey("<control>C"), sigc::mem_fun(this, &Window::on_copy_action));      
    action->unref();    
    action = new Gtk::Action("paste", "_Paste", StockId::PASTE)
    action->set_tooltip("Paste text from the clipboard");       
    group->add_action(*action, Gtk::AccelKey("<control>V"), sigc::mem_fun(this, &Window::on_paste_action));     
    action->unref();    
    action = new Gtk::Action("quit", StockId::QUIT)
    action->set_tooltip("Quit the application");        
    group->add_action(*action, Gtk::AccelKey("<control>Q"), sigc::ptr_fun(&Xfc::Main::quit));

You can add a Gtk::ToggleAction and a Gtk::RadioAction to an action group using any of the above methods. When adding a group radio actions you can either connect a callback slot to the "activate" signal of each action, or alternatively, you can just connect one callback slot to the "changed signal of one action in the group. It doesn't matter which one. Each radio action in a group receives the changed signal (after the activate signal) and passes as an argument a pointer to the newly activated action.

The easiest way the add radio actions to an action group is to use a Gtk::RadioActions object. This object is for convenience only. It has several overloaded add() methods that look similar to the Gtk::ActionGroup::add() methods above. You add all the radio actions in one group to a RadioActions object and then you call add_actions() the add the group of actions to an action group. A RadioActions object can only be created on the stack. You can reuse a RadioActions object to add a second group of radio actions by first calling Gtk::RadioActions::clear(). For example:

    Gtk::ActionGroup *group = new Gtk::ActionGroup("TestActions");
    Gtk::RadioActions ras;
   
    // First group
    ras.add("justify-left", "_Left", Gtk::StockId::JUSTIFY_LEFT, JUSTIFY_LEFT, "Left justify the text"),
    ras.add("justify-right", "_Right", Gtk::StockId::JUSTIFY_RIGHT, JUSTIFY_RIGHT, "Right justify the text");
    ras.add("justify-center", "C_enter", Gtk::StockId::JUSTIFY_CENTER, JUSTIFY_CENTER, "Center justify the text");
    ras.add("justify-fill", "_Fill", Gtk::StockId::JUSTIFY_FILL, JUSTIFY_FILL, "Fill justify the text");
    group->add_actions(ras, JUSTIFY_LEFT, sigc::mem_fun(this, &Window::on_justify_action));     
    
    // Second group
    ras.clear();
    ras.add("toolbar-icons", "Icons", TOOLBAR_ICONS);
    ras.add("toolbar-text", "Text", TOOLBAR_TEXT);
    ras.add("toolbar-both", "Both", TOOLBAR_BOTH);
    ras.add("toolbar-both-horiz", "Both Horizontal", TOOLBAR_BOTH_HORIZ);
    group->add_actions(ras, TOOLBAR_BOTH, sigc::mem_fun(this, &Window::on_toolbar_style_action));

Note: dynamically allocated objects must either be unreferenced or assigned to a smart pointer. Stack objects are automatically unreferenced when they go out of scope.

See also: the User Interface Manager HOWTO and example.

Member Typedef Documentation

typedef sigc::slot<void> Xfc::Gtk::ActionGroup::ActivateSlot
 

Signature of the callback slot to be called when an action is activated.

Example: Method signature for ActivateSlot. 

             void method();

typedef sigc::slot<void, RadioAction&> Xfc::Gtk::ActionGroup::ChangedSlot
 

Signature of the callback slot to be called when a radio action is changed.

Example: Method signature for ChangedSlot. 

             void method(RadioAction& activated);
             // activated: The member of the radio action group which has just been activated.

Constructor & Destructor Documentation

Xfc::Gtk::ActionGroup::ActionGroup (  GtkActionGroup *  action_group,
bool  owns_reference = true
)  [explicit, protected]
 

Construct a new ActionGroup from an existing GtkActionGroup.

Parameters:
action_group A pointer to a GtkActionGroup.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The action_group can be a newly created GtkActionGroup or an existing GtkActionGroup (see G::Object::Object).

Xfc::Gtk::ActionGroup::ActionGroup (  const String &  name  ) 
 

Constructs a new action group with a reference count of 1 that the caller owns.

Parameters:
name The name of the action group.
The name of the action group is used when associating keybindings with the actions.

Member Function Documentation

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const StockId &  stock_id,
const AccelKey &  accel_key,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
stock_id The stock icon to display in widgets representing the action.
accel_key An AccelKey object specifying the accelerator for the action.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const StockId &  stock_id,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
stock_id The stock icon to display in widgets representing the action.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const AccelKey &  accel_key,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
accel_key An AccelKey object specifying the accelerator for the action.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const StockId &  stock_id,
const AccelKey &  accel_key,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
stock_id The stock icon to display in widgets representing the action.
accel_key An AccelKey object specifying the accelerator for the action.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

ToggleAction* Xfc::Gtk::ActionGroup::add (  const char *  name,
const StockId &  stock_id,
bool  is_active,
const char *  tooltip = 0
) 
 

Creates and adds a new toggle action to the action group.

Parameters:
name A unique name for the action.
stock_id The stock icon to display in widgets representing the action.
is_active The initial state of the toggle action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const StockId &  stock_id,
const AccelKey &  accel_key,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
stock_id The stock icon to display in widgets representing the action.
accel_key An AccelKey object specifying the accelerator for the action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const StockId &  stock_id,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
stock_id The stock icon to display in widgets representing the action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const StockId &  stock_id,
const AccelKey &  accel_key,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
stock_id The stock icon to display in widgets representing the action.
accel_key An AccelKey object specifying the accelerator for the action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const StockId &  stock_id,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
stock_id The stock icon to display in widgets representing the action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const AccelKey &  accel_key,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
accel_key An AccelKey object specifying the accelerator for the action.
tooltip The tooltip to display for the action.

Action* Xfc::Gtk::ActionGroup::add (  const char *  name,
const char *  label,
const char *  tooltip = 0
) 
 

Creates and adds a new action to the action group.

Parameters:
name A unique name for the action.
label The label displayed in menu items and on buttons.
tooltip The tooltip to display for the action.

void Xfc::Gtk::ActionGroup::add_action (  RadioAction &  action,
const AccelKey &  accel_key,
const ChangedSlot &  slot
) 
 

Adds a radio action to the action group, sets up the accelerator and connects slot to the action's "changed" signal.

Parameters:
action The action to add.
accel_key An AccelKey object specifying the accelerator for the action.
slot A callback slot to connect to the radio action's "changed" signal.
You only need to connect one ChangedSlot to a radio action, usually the first in a group. All other members of the same group will also receive the "changed" signal.

Accelerator paths are set to <Actions>/group-name/action-name. The accelerator must be in the format understood by Gtk::accelerator_parse(), or null to use the stock accelerator.

void Xfc::Gtk::ActionGroup::add_action (  RadioAction &  action,
const ChangedSlot &  slot
) 
 

Adds a radio action to the action group and connects slot to its "changed" signal.

Parameters:
action A radio action object.
slot A callback slot to connect to the radio action's changed signal.
You only need to connect one ChangedSlot to a radio action, usually the first in a group. All other members of the same group will also receive the "changed" signal.

Note that if the action set a stock item this method sets up the stock item's accelerator path for the action. Otherwise you must set the accelerator path yourself by calling Gtk::AccelMap::add_entry() and Gtk::Action::set_accel_path().

void Xfc::Gtk::ActionGroup::add_action (  RadioAction &  action,
const AccelKey &  accel_key
) 
 

Adds a radio action to the action group and sets up the accelerator.

Parameters:
action The radio action to add.
accel_key An AccelKey object specifying the accelerator for the action.
Accelerator paths are set to <Actions>/group-name/action-name.

void Xfc::Gtk::ActionGroup::add_action (  Action &  action,
const AccelKey &  accel_key,
const ActivateSlot &  slot
) 
 

Adds an action to the action group, sets up the accelerator and connects slot to the action's "activate" signal.

Parameters:
action The action to add.
accel_key An AccelKey object specifying the accelerator for the action.
slot A callback slot to connect to the action's activate signal.
Accelerator paths are set to <Actions>/group-name/action-name. The accelerator must be in the format understood by Gtk::accelerator_parse(), or null to use the stock accelerator.

void Xfc::Gtk::ActionGroup::add_action (  Action &  action,
const ActivateSlot &  slot
) 
 

Adds an action to the action group and connects slot to its "activate" signal.

Parameters:
action An action object.
slot A callback slot to connect to the action's activate signal.
Note that if the action set a stock item this method sets up the stock item's accelerator path for the action. Otherwise you must set the accelerator path yourself by calling Gtk::AccelMap::add_entry() and Gtk::Action::set_accel_path().

void Xfc::Gtk::ActionGroup::add_action (  Action &  action,
const AccelKey &  accel_key
) 
 

Adds an action to the action group and sets up the accelerator.

Parameters:
action The action to add.
accel_key An AccelKey object specifying the accelerator for the action.
Accelerator paths are set to <Actions>/group-name/action-name.

void Xfc::Gtk::ActionGroup::add_action (  Action &  action  ) 
 

Adds an action object to the action group.

Parameters:
action An action object.
Note that if the action set a stock item this method sets up the stock item's accelerator path for the action. Otherwise you must set the accelerator path yourself by calling Gtk::AccelMap::add_entry() and Gtk::Action::set_accel_path().

void Xfc::Gtk::ActionGroup::add_actions (  const RadioActions &  group,
int  value,
const ChangedSlot &  slot
) 
 

Adds the actions in the RadioActions group to the action group, sets the default value and connects slot to the changed signal of the first radio action.

Parameters:
group A RadioActions group.
value The value of the action to activate initially, or -1 if no action should be activated.
slot The slot to connect to the changed signal.
This is a convenience method that uses a Gtk::RadioActions group to set up a group Gtk::RadioAction and adds them to the action group with one function call. The advantage of using a RadioActions group is that it handles the reference counting issues for you.

Action* Xfc::Gtk::ActionGroup::get_action (  const String &  action_name  ) 
 

Looks up an action in the action group by name.

Parameters:
action_name The name of the action.
Returns:
The action, or null if no action by that name exists.

String Xfc::Gtk::ActionGroup::get_name (   )  const
 

Gets the name of the action group.

Returns:
The name of the action group.

bool Xfc::Gtk::ActionGroup::get_sensitive (   )  const
 

Determines whether the action group is sensitive.

Returns:
true if the group is sensitive.
The constituent actions can only be logically sensitive (see Gtk::Action::is_sensitive()) if they are sensitive (see Gtk::Action::get_sensitive()) and their group is sensitive.

bool Xfc::Gtk::ActionGroup::get_visible (   )  const
 

Determines whether the group is visible.

Returns :

Returns:
true if the group is visible.
The constituent actions can only be logically visible (see Gtk::Action::is_visible()) if they are visible (see Gtk::Action::get_visible()) and their group is visible.

bool Xfc::Gtk::ActionGroup::list_actions (  std::vector< Action * > &  actions  )  const
 

Lists the action objects in the action group.

Parameters:
actions A reference to a vector of Action pointers to hold the list of actions.
Returns:
true if the vector of actions is not empty, false otherwise.

void Xfc::Gtk::ActionGroup::remove_action (  Action &  action  ) 
 

Removes an action object from the action group.

Parameters:
action An action object.

void Xfc::Gtk::ActionGroup::set_sensitive (  bool  sensitive  ) 
 

Changes the sensitivity of the action group.

Parameters:
sensitive The new sensitivity.

void Xfc::Gtk::ActionGroup::set_visible (  bool  visible  ) 
 

Changes the visibility of the action group.

Parameters:
visible The new visibility.

const ConnectProxySignalProxy Xfc::Gtk::ActionGroup::signal_connect_proxy (   ) 
 

Connect to the connect_proxy_signal; emitted after connecting a proxy widget to an action in the group.

Note that the proxy may have been connected to a different action before. This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar. Gtk::UIManager proxies the signal and provides global notification just before any action is connected to a proxy, which is probably more convenient to use.

const DisconnectProxySignalProxy Xfc::Gtk::ActionGroup::signal_disconnect_proxy (   ) 
 

Connect to the disconnect_proxy_signal; emitted after disconnecting a proxy widget from an action in the group.

Gtk::UIManager proxies the signal and provides global notification just before any action is connected to a proxy widget, which is probably more convenient to use.

const PostActivateSignalProxy Xfc::Gtk::ActionGroup::signal_post_activate (   ) 
 

Connect to the post_activate_signal; emitted just after the action in the action_group is activated.

This is intended for Gtk::UIManager to proxy the signal and provide global notification just after any action is activated.

const PreActivateSignalProxy Xfc::Gtk::ActionGroup::signal_pre_activate (   ) 
 

Connect to the pre_activate_signal; emitted just before the action in the action_group is activated.

This is intended for Gtk::UIManager to proxy the signal and provide global notification just before any action is activated.

Member Data Documentation

const ConnectProxySignalType Xfc::Gtk::ActionGroup::connect_proxy_signal [static, protected]
 

Connect proxy signal (see signal_connect_proxy()).

Calls a slot with the signature: 

             void function(Action& action, Widget& proxy);
             // action: The action proxy is being connected to.
             // proxy: The proxy widget being connected to action.

const DisconnectProxySignalType Xfc::Gtk::ActionGroup::disconnect_proxy_signal [static, protected]
 

Disconnect proxy signal (see signal_disconnect_proxy()).

Calls a slot with the signature: 

             void function(Action& action, Widget& proxy);
             // action: The action proxy is being disconnected from.
             // proxy: The proxy widget being disconnected from action.

const PostActivateSignalType Xfc::Gtk::ActionGroup::post_activate_signal [static, protected]
 

Post-activate signal (see signal_post_activate()).

Calls a slot with the signature: 

             void function(Action& action);
             // action: The action being activated.

const PreActivateSignalType Xfc::Gtk::ActionGroup::pre_activate_signal [static, protected]
 

Pre-activate signal (see signal_pre_activate()).

Calls a slot with the signature: 

             void function(Action& action);
             // action: The action being activated.

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3