atk/atkaction.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright 2001 Sun Microsystems Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "atkaction.h"
  21
  22 /**
  23  * SECTION:atkaction
  24  * @Short_description: The ATK interface provided by UI components
  25  * which the user can activate/interact with.
  26  * @Title:AtkAction
  27  *
  28  * #AtkAction should be implemented by instances of #AtkObject classes
  29  * with which the user can interact directly, i.e. buttons,
  30  * checkboxes, scrollbars, e.g. components which are not "passive"
  31  * providers of UI information.
  32  *
  33  * Exceptions: when the user interaction is already covered by another
  34  * appropriate interface such as #AtkEditableText (insert/delete text,
  35  * etc.) or #AtkValue (set value) then these actions should not be
  36  * exposed by #AtkAction as well.
  37  *
  38  * Though most UI interactions on components should be invocable via
  39  * keyboard as well as mouse, there will generally be a close mapping
  40  * between "mouse actions" that are possible on a component and the
  41  * AtkActions.  Where mouse and keyboard actions are redundant in
  42  * effect, #AtkAction should expose only one action rather than
  43  * exposing redundant actions if possible.  By convention we have been
  44  * using "mouse centric" terminology for #AtkAction names.
  45  *
  46  */
  47
  48 GType
  49 atk_action_get_type (void)
  50 {
  51   static GType type = 0;
  52
  53   if (!type) {
  54     GTypeInfo tinfo =
  55     {
  56       sizeof (AtkActionIface),
  57       (GBaseInitFunc) NULL,
  58       (GBaseFinalizeFunc) NULL,
  59
  60     };
  61
  62     type = g_type_register_static (G_TYPE_INTERFACE, "AtkAction", &tinfo, 0);
  63   }
  64
  65   return type;
  66 }
  67
  68 /**
  69  * atk_action_do_action:
  70  * @action: a #GObject instance that implements AtkActionIface
  71  * @i: the action index corresponding to the action to be performed
  72  *
  73  * Perform the specified action on the object.
  74  *
  75  * Returns: %TRUE if success, %FALSE otherwise
  76  *
  77  **/
  78 gboolean
  79 atk_action_do_action (AtkAction *obj,
  80                       gint      i)
  81 {
  82   AtkActionIface *iface;
  83
  84   g_return_val_if_fail (ATK_IS_ACTION (obj), FALSE);
  85
  86   iface = ATK_ACTION_GET_IFACE (obj);
  87
  88   if (iface->do_action)
  89     return (iface->do_action) (obj, i);
  90   else
  91     return FALSE;
  92 }
  93
  94 /**
  95  * atk_action_get_n_actions:
  96  * @action: a #GObject instance that implements AtkActionIface
  97  *
  98  * Gets the number of accessible actions available on the object.
  99  * If there are more than one, the first one is considered the
 100  * "default" action of the object.
 101  *
 102  * Returns: a the number of actions, or 0 if @action does not
 103  * implement this interface.
 104  **/
 105 gint
 106 atk_action_get_n_actions  (AtkAction *obj)
 107 {
 108   AtkActionIface *iface;
 109
 110   g_return_val_if_fail (ATK_IS_ACTION (obj), 0);
 111
 112   iface = ATK_ACTION_GET_IFACE (obj);
 113
 114   if (iface->get_n_actions)
 115     return (iface->get_n_actions) (obj);
 116   else
 117     return 0;
 118 }
 119
 120 /**
 121  * atk_action_get_description:
 122  * @action: a #GObject instance that implements AtkActionIface
 123  * @i: the action index corresponding to the action to be performed
 124  *
 125  * Returns a description of the specified action of the object.
 126  *
 127  * Returns: a description string, or %NULL if @action does not
 128  * implement this interface.
 129  **/
 130 const gchar*
 131 atk_action_get_description (AtkAction *obj,
 132                             gint      i)
 133 {
 134   AtkActionIface *iface;
 135
 136   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 137
 138   iface = ATK_ACTION_GET_IFACE (obj);
 139
 140   if (iface->get_description)
 141     return (iface->get_description) (obj, i);
 142   else
 143     return NULL;
 144 }
 145
 146 /**
 147  * atk_action_get_name:
 148  * @action: a #GObject instance that implements AtkActionIface
 149  * @i: the action index corresponding to the action to be performed
 150  *
 151  * Returns a non-localized string naming the specified action of the
 152  * object. This name is generally not descriptive of the end result
 153  * of the action, but instead names the 'interaction type' which the
 154  * object supports. By convention, the above strings should be used to
 155  * represent the actions which correspond to the common point-and-click
 156  * interaction techniques of the same name: i.e.
 157  * "click", "press", "release", "drag", "drop", "popup", etc.
 158  * The "popup" action should be used to pop up a context menu for the
 159  * object, if one exists.
 160  *
 161  * For technical reasons, some toolkits cannot guarantee that the
 162  * reported action is actually 'bound' to a nontrivial user event;
 163  * i.e. the result of some actions via atk_action_do_action() may be
 164  * NIL.
 165  *
 166  * Returns: a name string, or %NULL if @action does not implement this
 167  * interface.
 168  **/
 169 const gchar*
 170 atk_action_get_name (AtkAction *obj,
 171                      gint      i)
 172 {
 173   AtkActionIface *iface;
 174
 175   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 176
 177   iface = ATK_ACTION_GET_IFACE (obj);
 178
 179   if (iface->get_name)
 180     return (iface->get_name) (obj, i);
 181   else
 182     return NULL;
 183 }
 184
 185 /**
 186  * atk_action_get_localized_name:
 187  * @action: a #GObject instance that implements AtkActionIface
 188  * @i: the action index corresponding to the action to be performed
 189  *
 190  * Returns the localized name of the specified action of the object.
 191  *
 192  * Returns: a name string, or %NULL if @action does not implement this
 193  * interface.
 194  **/
 195 const gchar*
 196 atk_action_get_localized_name (AtkAction *obj,
 197                                gint      i)
 198 {
 199   AtkActionIface *iface;
 200
 201   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 202
 203   iface = ATK_ACTION_GET_IFACE (obj);
 204
 205   if (iface->get_localized_name)
 206     return (iface->get_localized_name) (obj, i);
 207   else
 208     return NULL;
 209 }
 210
 211 /**
 212  * atk_action_get_keybinding:
 213  * @action: a #GObject instance that implements AtkActionIface
 214  * @i: the action index corresponding to the action to be performed
 215  *
 216  * Gets the keybinding which can be used to activate this action, if one
 217  * exists. The string returned should contain localized, human-readable,
 218  * key sequences as they would appear when displayed on screen. It must
 219  * be in the format "mnemonic;sequence;shortcut".
 220  *
 221  * - The mnemonic key activates the object if it is presently enabled onscreen.
 222  *   This typically corresponds to the underlined letter within the widget.
 223  *   Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for
 224  *   a button.
 225  * - The sequence is the full list of keys which invoke the action even if the
 226  *   relevant element is not currently shown on screen. For instance, for a menu
 227  *   item the sequence is the keybindings used to open the parent menus before
 228  *   invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a
 229  *   traditional "New..." menu item.
 230  * - The shortcut, if it exists, will invoke the same action without showing
 231  *   the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a
 232  *   traditional "New..." menu item.
 233  *
 234  * Example: For a traditional "New..." menu item, the expected return value
 235  * would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N"
 236  * for the German locale. If, hypothetically, this menu item lacked a mnemonic,
 237  * it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively.
 238  *
 239  * Returns: the keybinding which can be used to activate this action,
 240  * or %NULL if there is no keybinding for this action.
 241  *
 242  **/
 243 const gchar*
 244 atk_action_get_keybinding (AtkAction *obj,
 245                            gint      i)
 246 {
 247   AtkActionIface *iface;
 248
 249   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 250
 251   iface = ATK_ACTION_GET_IFACE (obj);
 252
 253   if (iface->get_keybinding)
 254     return (iface->get_keybinding) (obj, i);
 255   else
 256     return NULL;
 257 }
 258
 259 /**
 260  * atk_action_set_description:
 261  * @action: a #GObject instance that implements AtkActionIface
 262  * @i: the action index corresponding to the action to be performed
 263  * @desc: the description to be assigned to this action
 264  *
 265  * Sets a description of the specified action of the object.
 266  *
 267  * Returns: a gboolean representing if the description was successfully set;
 268  **/
 269 gboolean
 270 atk_action_set_description (AtkAction   *obj,
 271                             gint        i,
 272                             const gchar *desc)
 273 {
 274   AtkActionIface *iface;
 275
 276   g_return_val_if_fail (ATK_IS_ACTION (obj), FALSE);
 277
 278   iface = ATK_ACTION_GET_IFACE (obj);
 279
 280   if (iface->set_description)
 281     return (iface->set_description) (obj, i, desc);
 282   else
 283     return FALSE;
 284 }