home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_Selector.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  5.8 KB  |  161 lines

  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 command 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 command);
  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
  161.