Xfce Foundation Classes

Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List

Xfc::Gtk::Action Class Reference

A GtkAction C++ wrapper class. More...

#include <xfc/gtk/action.hh>

Inheritance diagram for Xfc::Gtk::Action:

List of all members.

Property Prototypes

• const LabelPropertyType label_property

  Label used for menu items and buttons that activate this action (see property_label()).
  

• const ShortLabelPropertyType short_label_property

  Shorter label that may be used on toolbar buttons (see property_short_label()).
  

• const TooltipPropertyType tooltip_property

  A tooltip for this action (see property_tooltip()).
  

• const StockIdPropertyType stock_id_property

  Stock icon displayed in widgets representing this action (see property_stock_id()).
  

• const IsImportantPropertyType is_important_property

  Whether the action is considered important (see property_is_important()).
  

• const HideIfEmptyPropertyType hide_if_empty_property

  Whether empty menu proxies for this action are hidden (see property_hide_if_empty()).
  

• const SensitivePropertyType sensitive_property

  Whether the action is enabled (see property_sensitive()).
  

• const VisiblePropertyType visible_property

  Whether the action is visible (see property_visible()).
  

• const VisibleHorizontalPropertyType visible_horizontal_property

  Whether the toolbar item is visible in horizontal orientation (see property_visible_horizontal()).
  

• const VisibleVerticalPropertyType visible_vertical_property

  Whether the toolbar item is visible in a vertical orientation (see property_visible_vertical()).
  

• const VisibleOverflownPropertyType visible_overflown_property

  Whether toolitem proxies for this action are represented in the toolbar overflow menu (see property_visible_overflown()).
  

Signal Prototypes

• const ActivateSignalType activate_signal

  Activate signal (see signal_activate()).
  

Public Member Functions

Constructors

• Action (const String &name, const String &label)

  Constructs a new Action object with a reference count of 1 that the caller owns.
  

• Action (const String &name, const StockId &stock_id)

  Constructs a new Action object with a reference count of 1 that the caller owns.
  

• Action (const String &name, const String &label, const StockId &stock_id)

  Constructs a new Action object with a reference count of 1 that the caller owns.
  

• virtual ~Action ()

  Destructor.
  

Accessors

• GtkAction * gtk_action () const

  Get a pointer to the GtkAction structure.
  

• operator GtkAction * () const

  Conversion operator; safely converts an Action to a GtkAction pointer.
  

• String get_name () const

  Gets the name of the action.
  

• bool get_proxies (std::vector< Widget * > &proxies) const

  Gets a list of the proxy widgets for an action.
  

• bool get_sensitive () const

  Determines whether the action itself is sensitive.
  

• bool get_visible () const

  Determines whether the action itself is visible.
  

• bool is_sensitive () const

  Determines whether the action is effectively sensitive.
  

• bool is_visible () const

  Determines whether the action is effectively visible.
  

• String get_accel_path () const

  Obtains the accelerator path for this action.
  

Methods

• void set_sensitive (bool sensitive)

  Sets the "sensitive" property of the action to sensitive.
  

• void set_visible (bool visible)

  Sets the "visible" property of the action to visible.
  

• void activate ()

  Emits the "activate" signal on the specified action, if it isn't insensitive.
  

• Image * create_icon (IconSize icon_size)

  This method is intended for use by action implementations to create stock icons displayed in the proxy widgets.
  

• MenuItem * create_menu_item ()

  Creates a menu item widget that proxies for the given action.
  

• ToolItem * create_tool_item ()

  Creates a toolbar item widget that proxies for the given action.
  

• void connect_proxy (Widget &proxy)

  Connects a widget to an action object as a proxy.
  

• void disconnect_proxy (Widget &proxy)

  Disconnects a proxy widget from an action but does not destroy the widget.
  

• void connect_accelerator ()

  Installs the accelerator for the action, if the action has an accelerator path and group (see set_accel_path() and set_accel_group()).
  

• void disconnect_accelerator ()

  Undoes the effect of one call to connect_accelerator().
  

• void set_accel_path (const String &accel_path)

  Sets the accelerator path for this action (used by action groups).
  

• void set_accel_group (AccelGroup *accel_group)

  Sets the AccelGroup in which the accelerator for this action will be installed (used by action groups).
  

• void set_tooltip (const String &tooltip)

  Sets the tooltip for the action.
  

Property Proxies

• const LabelPropertyProxy property_label ()

  The label used for menu items and buttons that activate this action (String : Read / Write).
  

• const ShortLabelPropertyProxy property_short_label ()

  A shorter label that may be used on toolbar buttons (String : Read / Write).
  

• const TooltipPropertyProxy property_tooltip ()

  A tooltip for this action (String : Read / Write).
  

• const StockIdPropertyProxy property_stock_id ()

  The stock icon displayed in widgets representing this action (String : Read / Write).
  

• const IsImportantPropertyProxy property_is_important ()

  Whether the action is considered important.
  

• const HideIfEmptyPropertyProxy property_hide_if_empty ()

  When true, empty menu proxies for this action are hidden (bool : Read / Write).
  

• const SensitivePropertyProxy property_sensitive ()

  Whether the action is enabled (bool : Read / Write).
  

• const VisiblePropertyProxy property_visible ()

  Whether the action is visible (bool : Read / Write).
  

• const VisibleHorizontalPropertyProxy property_visible_horizontal ()

  Whether the toolbar item is visible when the toolbar is in a horizontal orientation (bool : Read / Write).
  

• const VisibleVerticalPropertyProxy property_visible_vertical ()

  Whether the toolbar item is visible when the toolbar is in a vertical orientation (bool : Read / Write).
  

• const VisibleOverflownPropertyProxy property_visible_overflown ()

  When true, toolitem proxies for this action are represented in the toolbar overflow menu (bool : Read / Write).
  

Signal Proxies

• const ActivateSignalProxy signal_activate ()

  Connect to the activate_signal; emitted when the action is activated.
  

Protected Member Functions

Constructors

• Action (GtkAction *action, bool owns_reference=true)

  Construct a new Action from an existing GtkAction.
  

Methods

• void block_activate_from (Widget &proxy)

  Disables calls to the activate() method by signals on the given proxy widget.
  

• void unblock_activate_from (Widget &proxy)

  Re-enables calls to the activate() method by signals on the given proxy widget.
  

---

Detailed Description

A GtkAction C++ wrapper class.

The Action object represents an action that can be triggered by a menu or toolbar item. Actions are operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself.

As well as the callback that is called when the action gets activated, the following also gets associated with the action:

• a name (not translated, for path lookup)
• a label (translated, for display)
• an accelerator
• whether label indicates a stock id
• a tooltip (optional, translated)
• a toolbar label (optional, shorter than label)

The action will also have some state information:

• visible (shown/hidden)
• sensitive (enabled/disabled)

Apart from regular actions, there are toggle actions, which can be toggled between two states and radio actions, of which only one in a group can be in the "active" state. Other actions can be implemented as GtkAction subclasses.

Each action can have one or more proxy menu item, toolbar button or other proxy widgets. Proxies mirror the state of the action (text label, tooltip, icon, visible, sensitive, etc), and should change when the action's state changes. When the proxy is activated, it should activate its 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.

---

Constructor & Destructor Documentation

Xfc::Gtk::Action::Action (  GtkAction *  action, bool  owns_reference = true )  [explicit, protected]

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

Xfc::Gtk::Action::Action (  const String &  name, const String &  label )

Constructs a new Action object with a reference count of 1 that the caller owns. Parameters: name  A unique name for the action. label  The label displayed in menu items and on buttons. To add the action to a ActionGroup and set the accelerator for the action, call Gtk::ActionGroup::add_action().

Xfc::Gtk::Action::Action (  const String &  name, const StockId &  stock_id )

Constructs a new Action object with a reference count of 1 that the caller owns. Parameters: name  A unique name for the action. stock_id  The stock icon and label to display in widgets representing the action. To add the action to a ActionGroup and set the accelerator for the action, call Gtk::ActionGroup::add_action().

Xfc::Gtk::Action::Action (  const String &  name, const String &  label, const StockId &  stock_id )

Constructs a new Action object with a reference count of 1 that the caller owns. 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. To add the action to a ActionGroup and set the accelerator for the action, call Gtk::ActionGroup::add_action(). Note that label is displayed instead of the stock_id label.

---

Member Function Documentation

void Xfc::Gtk::Action::activate (   )

Emits the "activate" signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated. It can also be used to manually activate an action.

void Xfc::Gtk::Action::block_activate_from (  Widget &  proxy  )  [protected]

Disables calls to the activate() method by signals on the given proxy widget. Parameters: proxy  The action widget. This is used to break notification loops for things like check or radio actions. This method is intended for use by action implementations.

void Xfc::Gtk::Action::connect_accelerator (   )

Installs the accelerator for the action, if the action has an accelerator path and group (see set_accel_path() and set_accel_group()). Since multiple proxies may independently trigger the installation of the accelerator, the action counts the number of times this method is called and doesn't remove the accelerator until disconnect_accelerator() has been called as many times.

void Xfc::Gtk::Action::connect_proxy (  Widget &  proxy  )

Connects a widget to an action object as a proxy. Parameters: proxy  The proxy widget Synchronises various properties of the action with the widget (such as label text, icon, tooltip, etc), and attaches a callback so that the action gets activated when the proxy widget does. If the widget is already connected to an action, it is disconnected first.

Image* Xfc::Gtk::Action::create_icon (  IconSize  icon_size  )

This method is intended for use by action implementations to create stock icons displayed in the proxy widgets. Parameters: icon_size  The size of the icon that should be created. Returns: A widget that displays the icon for this action.

MenuItem* Xfc::Gtk::Action::create_menu_item (   )

Creates a menu item widget that proxies for the given action. Returns: A menu item connected to the action.

ToolItem* Xfc::Gtk::Action::create_tool_item (   )

Creates a toolbar item widget that proxies for the given action. Returns: A toolbar item connected to the action.

void Xfc::Gtk::Action::disconnect_proxy (  Widget &  proxy  )

Disconnects a proxy widget from an action but does not destroy the widget. Parameters: proxy  The proxy widget

String Xfc::Gtk::Action::get_accel_path (   )  const

Obtains the accelerator path for this action. Returns: The accelerator path for this action, or null if none is set.

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

Gets the name of the action. Returns: The name of the action.

bool Xfc::Gtk::Action::get_proxies (  std::vector< Widget * > &  proxies  )  const

Gets a list of the proxy widgets for an action. Parameters: proxies  A reference to a vector of Widget pointers to hold the proxy list. Returns: true if the proxies vector is not empty, false otherwise.

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

Determines whether the action itself is sensitive. Returns: true if the action itself is sensitive. Note that this doesn't necessarily mean effective sensitivity (see is_sensitive() for that).

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

Determines whether the action itself is visible. Returns: true if the action itself is visible. Note that this doesn't necessarily mean effective visibility (see is_visible() for that).

bool Xfc::Gtk::Action::is_sensitive (   )  const

Determines whether the action is effectively sensitive. Returns: true if the action and its associated action group are both sensitive.

bool Xfc::Gtk::Action::is_visible (   )  const

Determines whether the action is effectively visible. Returns: true if the action and its associated action group are both visible.

const IsImportantPropertyProxy Xfc::Gtk::Action::property_is_important (   )

Whether the action is considered important. When TRUE, toolitem proxiesfor this action show text in Gtk::TOOLBAR_BOTH_HORIZ mode (bool : Read / Write).

void Xfc::Gtk::Action::set_accel_group (  AccelGroup *  accel_group  )

Sets the AccelGroup in which the accelerator for this action will be installed (used by action groups). Parameters: accel_group  An AccelGroup, or null.

void Xfc::Gtk::Action::set_accel_path (  const String &  accel_path  )

Sets the accelerator path for this action (used by action groups). Parameters: accel_path  The accelerator path. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent (use by action groups).

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

Sets the "sensitive" property of the action to sensitive. Parameters: sensitive  Set to true to make the action sensitive. Note that this doesn't necessarily mean effective sensitivity (see is_sensitive()).

void Xfc::Gtk::Action::set_tooltip (  const String &  tooltip  )

Sets the tooltip for the action. Parameters: tooltip  The tooltip to display for the action.

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

Sets the "visible" property of the action to visible. Parameters: visible  Set to true to make the action visible. Note that this doesn't necessarily mean effective visibility (see is_visible()).

void Xfc::Gtk::Action::unblock_activate_from (  Widget &  proxy  )  [protected]

Re-enables calls to the activate() method by signals on the given proxy widget. Parameters: proxy  The action widget. This undoes the blocking done by block_activate_from(). This method is intended for use by action implementations.

---

Member Data Documentation

const ActivateSignalType Xfc::Gtk::Action::activate_signal [static, protected]

Activate signal (see signal_activate()). Calls a slot with the signature: void function();

---

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

• gtk/action.hh

---

Copyright © 2004-2005 The XFC Development Team

XFC 4.3