libs/gtkmm2/atk/atkmm/action.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _ATKMM_ACTION_H
   4 #define _ATKMM_ACTION_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright (C) 2002 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27
  28 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  29 extern "C" { typedef struct _AtkActionIface AtkActionIface; }
  30 #endif
  31
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 typedef struct _AtkAction AtkAction;
  35 typedef struct _AtkActionClass AtkActionClass;
  36 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  37
  38
  39 namespace Atk
  40 { class Action_Class; } // namespace Atk
  41 namespace Atk
  42 {
  43
  44 /** The ATK interface provided by UI components which the user can activate/interact with,
  45  * This should be implemented by instances of Atk::Object classes with which the user can interact directly, i.e. buttons,
  46  * checkboxes, scrollbars, e.g. components which are not "passive" providers of UI information.
  47  *
  48  * Exceptions: when the user interaction is already covered by another appropriate interface such as Atk::EditableText
  49  * (insert/delete test, etc.) or Atk::Value (set value) then these actions should not be exposed by Atk::Action as well.
  50  *
  51  * Also note that the Atk::Action API is limited in that parameters may not be passed to the object being activated;
  52  * thus the action must be self-contained and specifiable via only a single "verb". Concrete examples include "press",
  53  * "release", "click" for buttons, "drag" (meaning initiate drag) and "drop" for drag sources and drop targets, etc.
  54  *
  55  * Though most UI interactions on components should be invocable via keyboard as well as mouse, there will generally be
  56  * a close mapping between "mouse actions" that are possible on a component and the Atk::Actions. Where mouse and keyboard
  57  * actions are redundant in effect, Atk::Action should expose only one action rather than exposing redundant actions if
  58  * possible. By convention we have been using "mouse centric" terminology for Atk::Action names.
  59  */
  60
  61 class Action : public Glib::Interface
  62 {
  63
  64 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  65
  66 public:
  67   typedef Action CppObjectType;
  68   typedef Action_Class CppClassType;
  69   typedef AtkAction BaseObjectType;
  70   typedef AtkActionIface BaseClassType;
  71
  72 private:
  73   friend class Action_Class;
  74   static CppClassType action_class_;
  75
  76   // noncopyable
  77   Action(const Action&);
  78   Action& operator=(const Action&);
  79
  80 protected:
  81   Action(); // you must derive from this class
  82   explicit Action(AtkAction* castitem);
  83
  84 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  85
  86 public:
  87   virtual ~Action();
  88
  89   static void add_interface(GType gtype_implementer);
  90
  91 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  92   static GType get_type()      G_GNUC_CONST;
  93   static GType get_base_type() G_GNUC_CONST;
  94 #endif
  95
  96   ///Provides access to the underlying C GObject.
  97   AtkAction*       gobj()       { return reinterpret_cast<AtkAction*>(gobject_); }
  98
  99   ///Provides access to the underlying C GObject.
 100   const AtkAction* gobj() const { return reinterpret_cast<AtkAction*>(gobject_); }
 101
 102 private:
 103
 104
 105 public:
 106
 107
 108   /** Perform the specified action on the object.
 109    * @param i The action index corresponding to the action to be performed.
 110    * @return <tt>true</tt> if success, <tt>false</tt> otherwise.
 111    */
 112   bool do_action(int i);
 113
 114   /** Gets the number of accessible actions available on the object.
 115    * If there are more than one, the first one is considered the
 116    * "default" action of the object.
 117    * @return A the number of actions, or 0 if @a action  does not
 118    * implement this interface.
 119    */
 120   int get_n_actions() const;
 121
 122   /** Returns a description of the specified action of the object.
 123    * @param i The action index corresponding to the action to be performed.
 124    * @return A description string, or <tt>0</tt>
 125    * if @a action  does not implement this interface.
 126    */
 127   Glib::ustring get_description(int i) const;
 128
 129   /** Returns the name of the specified action of the object.
 130    * @param i The action index corresponding to the action to be performed.
 131    * @return A name string, or an empty string if @a action  does not implement this interface.
 132    */
 133   Glib::ustring get_name(int i) const;
 134
 135   /** Returns a keybinding associated with this action, if one exists.
 136    * @param i The action index corresponding to the action to be performed.
 137    * @return A string representing the keybinding, or an empty string
 138    * if there is no keybinding for this action.
 139    */
 140   Glib::ustring get_keybinding(int i);
 141
 142   /** Sets a description of the specified action of the object.
 143    * @param i The action index corresponding to the action to be performed.
 144    * @param desc The description to be assigned to this action.
 145    * @return A <tt>bool</tt> representing if the description was successfully set;.
 146    */
 147   bool set_description(int i, const Glib::ustring& desc);
 148
 149   /** Returns the localized name of the specified action of the object.
 150    * @param i The action index corresponding to the action to be performed.
 151    * @return A name string, or an empty string
 152    * if @a action  does not implement this interface.
 153    */
 154   Glib::ustring get_localized_name(int i);
 155
 156 protected:
 157     virtual bool do_action_vfunc(int i);
 158     virtual int get_n_actions_vfunc() const;
 159     virtual const char* get_description_vfunc(int i) const;
 160     virtual const char* get_name_vfunc(int i) const;
 161     virtual const char* get_keybinding_vfunc(int i) const;
 162     virtual bool set_description_vfunc(int i, const Glib::ustring& desc);
 163
 164
 165 public:
 166
 167 public:
 168   //C++ methods used to invoke GTK+ virtual functions:
 169
 170 protected:
 171   //GTK+ Virtual Functions (override these to change behaviour):
 172
 173   //Default Signal Handlers::
 174
 175
 176 };
 177
 178 } // namespace Atk
 179
 180
 181 namespace Glib
 182 {
 183   /** @relates Atk::Action
 184    * @param object The C instance
 185    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 186    * @result A C++ instance that wraps this C instance.
 187    */
 188   Glib::RefPtr<Atk::Action> wrap(AtkAction* object, bool take_copy = false);
 189
 190 } // namespace Glib
 191
 192 #endif /* _ATKMM_ACTION_H */
 193