Improved docs for AtkAction, specifically get_name and get_keybindings.

[platform/upstream/atk.git] / atk / atkaction.c

diff --git a/atk/atkaction.c b/atk/atkaction.c
index ed6d5d2..f47687c 100755 (executable)
--- a/atk/atkaction.c
+++ b/atk/atkaction.c
@@ -20,7 +20,7 @@
 #include "atkaction.h"
 
 GType
-atk_action_get_type ()
+atk_action_get_type (void)
 {
   static GType type = 0;
 
@@ -45,20 +45,24 @@ atk_action_get_type ()
  * @i: the action index corresponding to the action to be performed 
  *
  * Perform the specified action on the object.
+ *
+ * Returns: %TRUE if success, %FALSE otherwise
+ *
  **/
-void
+gboolean
 atk_action_do_action (AtkAction *obj,
                       gint      i)
 {
   AtkActionIface *iface;
 
-  g_return_if_fail (obj != NULL);
-  g_return_if_fail (ATK_IS_ACTION (obj));
+  g_return_val_if_fail (ATK_IS_ACTION (obj), FALSE);
 
   iface = ATK_ACTION_GET_IFACE (obj);
 
   if (iface->do_action)
-    (iface->do_action) (obj, i);
+    return (iface->do_action) (obj, i);
+  else
+    return FALSE;
 }
 
 /**
@@ -77,7 +81,6 @@ atk_action_get_n_actions  (AtkAction *obj)
 {
   AtkActionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, 0);
   g_return_val_if_fail (ATK_IS_ACTION (obj), 0);
 
   iface = ATK_ACTION_GET_IFACE (obj);
@@ -104,7 +107,6 @@ atk_action_get_description (AtkAction *obj,
 {
   AtkActionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, NULL);
   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 
   iface = ATK_ACTION_GET_IFACE (obj);
@@ -120,7 +122,20 @@ atk_action_get_description (AtkAction *obj,
  * @action: a #GObject instance that implements AtkActionIface
  * @i: the action index corresponding to the action to be performed 
  *
- * Returns the name of the specified action of the object.
+ * Returns a non-localized string naming the specified action of the 
+ * object. This name is generally not descriptive of the end result 
+ * of the action, but instead names the 'interaction type' which the 
+ * object supports. By convention, the above strings should be used to 
+ * represent the actions which correspond to the common point-and-click 
+ * interaction techniques of the same name: i.e. 
+ * "click", "press", "release", "drag", "drop", "popup", etc.
+ * The "popup" action should be used to pop up a context menu for the 
+ * object, if one exists.
+ *
+ * For technical reasons, some toolkits cannot guarantee that the 
+ * reported action is actually 'bound' to a nontrivial user event;
+ * i.e. the result of some actions via atk_action_do_action() may be
+ * NIL.
  *
  * Returns a name string, or %NULL
  * if @action does not implement this interface.
@@ -131,7 +146,6 @@ atk_action_get_name (AtkAction *obj,
 {
   AtkActionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, NULL);
   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 
   iface = ATK_ACTION_GET_IFACE (obj);
@@ -143,13 +157,49 @@ atk_action_get_name (AtkAction *obj,
 }
 
 /**
+ * atk_action_get_localized_name:
+ * @action: a #GObject instance that implements AtkActionIface
+ * @i: the action index corresponding to the action to be performed 
+ *
+ * Returns the localized name of the specified action of the object.
+ *
+ * Returns a name string, or %NULL
+ * if @action does not implement this interface.
+ **/
+G_CONST_RETURN gchar*
+atk_action_get_localized_name (AtkAction *obj,
+                               gint      i)
+{
+  AtkActionIface *iface;
+
+  g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
+
+  iface = ATK_ACTION_GET_IFACE (obj);
+
+  if (iface->get_localized_name)
+    return (iface->get_localized_name) (obj, i);
+  else
+    return NULL;
+}
+
+/**
  * atk_action_get_keybinding:
  * @action: a #GObject instance that implements AtkActionIface
  * @i: the action index corresponding to the action to be performed 
  *
  * Returns a keybinding associated with this action, if one exists.
+ * The returned string is in the format "<a>;<b>;<c>"
+ * (i.e. semicolon-delimited), where <a> is the keybinding which
+ * activates the object if it is presently enabled onscreen, 
+ * <b> corresponds to the keybinding or sequence of keys
+ * which invokes the action even if the relevant element is not
+ * currently posted on screen (for instance, for a menu item it
+ * posts the parent menus before invoking).  The last token in the
+ * above string, if non-empty, represents a keyboard shortcut which
+ * invokes the same action without posting the component or its
+ * enclosing menus or dialogs. 
  *
- * Returns a string representing the keybinding, or %NULL
+ * Returns a string representing the available keybindings, or %NULL
  * if there is no keybinding for this action.
  *
  **/
@@ -159,7 +209,6 @@ atk_action_get_keybinding (AtkAction *obj,
 {
   AtkActionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, NULL);
   g_return_val_if_fail (ATK_IS_ACTION (obj), NULL);
 
   iface = ATK_ACTION_GET_IFACE (obj);
@@ -187,7 +236,6 @@ atk_action_set_description (AtkAction   *obj,
 {
   AtkActionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_ACTION (obj), FALSE);
 
   iface = ATK_ACTION_GET_IFACE (obj);