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