idl/Accessibility_Selector.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <Bonobo_Unknown.idl>
  24
  25 #ifndef _ACCESSIBILITY_SELECTOR_IDL_
  26 #define _ACCESSIBILITY_SELECTOR_IDL_
  27
  28 module Accessibility {
  29
  30     /** A structure which encapsulates both a string representation of a command and a unique command ID **/
  31     struct Command {
  32           string name;
  33           long   id;
  34      };
  35
  36     /** A list of Command objects **/
  37     typedef sequence<Command> CommandList;
  38
  39     /**
  40     * An interface which should be implemented by assistive technologies or other
  41     * clients of the ::Selector interface, over which notifications to the list of
  42     * available commands is made.  The notifyCommands() method of the client is then called by
  43     * the ::Selector instance.
  44     * @since AT-SPI 1.7.0
  45     **/
  46     interface CommandListener {
  47         /**
  48          * Notify the CommandListener instance of changes to the currently
  49          * available commands, by sending the current ::CommandList.
  50          *
  51          * @param commands The newly-available list of ::Command objects which
  52          * may be invoked by the listener.
  53          **/
  54         void notifyCommands (in CommandList commands);
  55     };
  56
  57     /**
  58      * This interface is intended for use by assistive technologies
  59      * and related user-agents.  Via this interface, an assistive technology or
  60      * user agent may expose a series of choices or selections in textual form,
  61      * which can be activated on demand by a client of the Selector interface.
  62      *
  63      * Examples of the use of this interface include voice-command and remote-control
  64      * applications, in which the user interaction is wholly or partly delegated by the
  65      * implementor to an external agent.
  66      * @since AT-SPI 1.7.0
  67      **/
  68   interface Selector : Bonobo::Unknown {
  69
  70       /**
  71        * A code returned by a call to ::activateCommand, indicating
  72        * the result of the activation request.
  73        **/
  74       enum CommandResult {
  75           COMMAND_RESULT_INVALID, /**< The command was invalid or ill-formed; usually indicates
  76                                    * an error condition. */
  77           COMMAND_RESULT_SUCCESS, /**< The command was successfully activated. */
  78           COMMAND_RESULT_FAILED, /**< The command was valid, but could not be activated.
  79                                   * This may be due to problems with permissions or error conditions.
  80                                   */
  81           COMMAND_RESULT_OBSOLETE, /**< The command is no longer valid in the current program context.
  82                                     * This may mean that the application has changed state in such a
  83                                     * way that the specified command it no longer applicable, or
  84                                     * because changes to the application state have rendered it
  85                                     * ambiguous.  Commands should be re-fetched and a new selection
  86                                     * made.
  87                                     */
  88           COMMAND_RESULT_LAST_DEFINED /**< Defines size of enumeration;
  89                                          do not use this value as a parameter.*/
  90       };
  91
  92       /** This attribute is TRUE if this Selector allows its ::CommandList to be specified by the client **/
  93       readonly attribute boolean supportsReplace;
  94
  95       /**
  96        * Query the ::Selector for the current ::CommandList.
  97        *
  98        * @returns the currently available ::CommandList
  99        **/
 100       CommandList getCommands ();
 101
 102       /**
 103        * @returns TRUE if the replacement request was successful,
 104        * FALSE if the request could not be honored.
 105        **/
 106       boolean replaceCommands (in CommandList commands);
 107
 108       /**
 109        * Ask the ::Selector to re-calculate its ::CommandList.
 110        * @note in most cases the ::Selector will continuously
 111        * update its ::CommandList without recourse to this call.
 112        * This call is equivalent to ::getCommands, except that
 113        * after ::refreshCommands the new ::CommandList will be returned
 114        * via any registered ::CommandListener instances rather than
 115        * synchronously via this call.
 116        *
 117        * @returns TRUE if the ::CommandList changed.
 118        **/
 119       boolean refreshCommands ();
 120
 121       /**
 122        * Request that the ::Selector invoke the specified ::Command.
 123        * @param cmd the ::Command to activate/invoke.
 124        * @returns a ::CommandResult indicating whether the
 125        * request was honored, and the reason for failure if the
 126        * ::Command could not be activated or invoked.
 127        **/
 128       CommandResult activateCommand (in Command cmd);
 129
 130       /**
 131        * Register a :CommandListener instance for notification of
 132        * changes to the command set.
 133        * @param listener the ::CommandListener to be notified of changes.
 134        **/
 135       void registerChangeListener (in CommandListener listener);
 136
 137       /**
 138        * Tell the ::Selector instance to cease notifying the
 139        * specified ::CommandListener of changes to the command list.
 140        * @param listener the ::CommandListener to remove from the
 141        * notification list.
 142        **/
 143       void deregisterChangeListener (in CommandListener listener);
 144
 145         /**
 146          *\cond
 147          * unImplemented:
 148          *
 149          * placeholders for future expansion.
 150          */
 151         void unImplemented ();
 152         void unImplemented2 ();
 153         void unImplemented3 ();
 154         void unImplemented4 ();
 155         /**\endcond */
 156     };
 157
 158 };
 159
 160 #endif