2009-06-11 Mark Doffman <mark.doffman@codethink.co.uk>

[platform/core/uifw/at-spi2-atk.git] / idl / Accessibility_Action.idl

diff --git a/idl/Accessibility_Action.idl b/idl/Accessibility_Action.idl
index 585438b..d14d90b 100644 (file)
--- a/idl/Accessibility_Action.idl
+++ b/idl/Accessibility_Action.idl
@@ -21,48 +21,87 @@
  */
 
 module Accessibility {
+    /**
+     * An interface through which a user-actionable user interface
+     * component can be manipulated.  Components which react to mouse or
+     * keyboard input from the user, (with the exception of pure text entry
+     * fields with no other function), should implement this interface.
+     * Typical actions include "click", "press", "release" (for instance for
+     * buttons), "menu" (for objects which have context menus invokable from 
+     * mouse or keyboard), "open" for icons representing files folders, and others.
+     */
+  interface Action : Bonobo::Unknown {
 
-  interface Action {
+    /**
+     * nActions: a \c long containing the number of actions this object supports.
+     * 
+     **/
+    readonly attribute long nActions;
 
-        /**
-         * getNActions:
-         * return values: a @long containing the number of actions this object supports.
-         *
-         * Returns the number of actions supported by this object.
-         **/
-        long getNActions ();
+    /**
+     * getDescription:
+     * @param index: the index of the action 
+     *   for which a description is desired.
+     *
+     * Get the description of the specified action.  The description of an action
+     * may provide information about the result of action invocation, unlike the
+     * action name.
+     * @see getName.
+     *
+     * @returns: a \c string containing the description of the specified action.
+     *
+     **/
+    string getDescription (in long index);
 
-        /**
-        * getDescription:
-        * return values: a @wstring containing the description of the specified action.
-        * @index: an %in parameter specifying the index of the action 
-         *   for which a description is desired.
-        *
-        * Gets the description of the specified action.
-        *
-        **/
-        string getDescription (in long index);
+    /**
+     * getName:
+     * @param index: the index of the action 
+     *   whose name is requested.
+     *
+     * Get the name of the specified action.  Action names generally describe
+     * the user action, i.e. "click" or "press", rather then the result of 
+     * invoking the action.
+     *
+     * @returns: a \c string containing the name of the specified action.
+     *
+     **/
+    string getName (in long index);
 
-        /**
-         * doAction:
-         * @index: an %in parameter specifying the 0-based index of the action to perform.
-         *
-         * Causes the object to perform the specified action.
-        *
-         **/
-        void doAction (in long index);
+    /**
+     * doAction:
+     * @param index: the 0-based index of the action to perform.
+     *
+     * Causes the object to perform the specified action.
+     *
+     * @returns: a \c boolean indicating success or failure.
+     *
+     **/
+    boolean doAction (in long index);
 
-        /**
-        * getKeyBinding:
-        * return values: a @wstring containing the key binding for the specified action,
-         *   "" if none exists.
-        * @index: an %in parameter specifying the 0-based index of the action 
-         *   for which a key binding is requested.
-        *
-        * Gets the key binding associated with a specific action.
-        *
-        **/
-        string getKeyBinding (in long index);
-  };
+    /**
+     * getKeyBinding:
+     * @param index: the 0-based index of the action 
+     *   for which a key binding is requested.
+     *
+     * Get the key binding associated with a specific action.
+     *
+     * @returns: a \c string containing the key binding for the specified action,
+     *   or an empty string ("") if none exists.
+     **/
+    string getKeyBinding (in long index);
 
+      
+    /**
+     * \cond
+     * unImplemented:
+     *
+     * placeholders for future expansion.
+     */
+    void unImplemented ();
+    void unImplemented2 ();
+    void unImplemented3 ();
+    void unImplemented4 ();
+      /** \endcond */
+  };
 };
+