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 201243c..f47687c 100755 (executable)
--- a/atk/atkaction.c
+++ b/atk/atkaction.c
@@ -122,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.
@@ -144,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.
- *
- * Returns a string representing the keybinding, or %NULL
+ * 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 available keybindings, or %NULL
  * if there is no keybinding for this action.
  *
  **/