2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems Inc.
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.
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.
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.
23 #include <Bonobo_Unknown.idl>
25 #ifndef _ACCESSIBILITY_SELECTOR_IDL_
26 #define _ACCESSIBILITY_SELECTOR_IDL_
28 module Accessibility {
30 /** A structure which encapsulates both a string representation of a command and a unique command ID **/
36 /** A list of Command objects **/
37 typedef sequence<Command> CommandList;
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.
46 interface CommandListener {
48 * Notify the CommandListener instance of changes to the currently
49 * available commands, by sending the current ::CommandList.
51 * @param commands The newly-available list of ::Command objects which
52 * may be invoked by the listener.
54 void notifyCommands (in CommandList commands);
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.
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.
68 interface Selector : Bonobo::Unknown {
71 * A code returned by a call to ::activateCommand, indicating
72 * the result of the activation request.
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.
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
88 COMMAND_RESULT_LAST_DEFINED /**< Defines size of enumeration;
89 do not use this value as a parameter.*/
92 /** This attribute is TRUE if this Selector allows its ::CommandList to be specified by the client **/
93 readonly attribute boolean supportsReplace;
96 * Query the ::Selector for the current ::CommandList.
98 * @returns the currently available ::CommandList
100 CommandList getCommands ();
103 * @returns TRUE if the replacement request was successful,
104 * FALSE if the request could not be honored.
106 boolean replaceCommands (in CommandList commands);
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.
117 * @returns TRUE if the ::CommandList changed.
119 boolean refreshCommands ();
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.
128 CommandResult activateCommand (in Command cmd);
131 * Register a :CommandListener instance for notification of
132 * changes to the command set.
133 * @param listener the ::CommandListener to be notified of changes.
135 void registerChangeListener (in CommandListener listener);
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
143 void deregisterChangeListener (in CommandListener listener);
149 * placeholders for future expansion.
151 void unImplemented ();
152 void unImplemented2 ();
153 void unImplemented3 ();
154 void unImplemented4 ();