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 <Accessibility_Accessible.idl>
25 module Accessibility {
28 * An interface which indicates that an object exposes a 'selection' model,
29 * allowing the selection of one or more of its children. Read-only Selection
30 * instances are possible, in which case the interface is used to programmatically
31 * determine the selected-ness of its children. A selected child has ::State::STATE_SELECTED,
32 * and a child which may hypothetically be selected (though possibly not programmatically
33 * selectable) has ::State::STATE_SELECTABLE.
34 * @note Events emitted by implementors of Selection include:
35 * \li \c "object:selection-changed" An instance of Selection has undergone a change in the
36 * 'selected-ness' of its children, i.e. had a selection added,
37 * removed, and/or modified. Usually accompanied by
38 * corresponding \c "object:state-changed:selected" events
39 * from the corresponding children, unless the children are
40 * previously un-queried via AT-SPI and the Selection instance
41 * has ::State::STATE_MANAGES_DESCENDANTS.
43 interface Selection : Bonobo::Unknown {
45 * The number of children of a Selection implementor which are
48 readonly attribute long nSelectedChildren;
50 * Get the i-th selected Accessible child of a Selection.
51 * @note \c selectedChildIndex refers to the index in the list of
52 * 'selected' children as opposed to the more general 'child index'
53 * of an object; as such it generally differs from that used in
54 * Accessible::getChildAtIndex() or returned by
55 * Accessible::getIndexInParent().
56 * \c selectedChildIndex must lie between 0
57 * and Selection::nSelectedChildren-1, inclusive.
58 * @param selectedChildIndex: a long integer indicating which of the
59 * selected children of an object is being requested.
60 * @returns a pointer to a selected Accessible child object,
61 * specified by \c selectedChildIndex.
63 Accessible getSelectedChild (in long selectedChildIndex);
65 * Add a child to the selected children list of a Selection.
66 * @note For Selection implementors that only allow
67 * single selections, this call may result in the
68 * replacement of the (single) current
69 * selection. The call may return \c False if
70 * the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE),
71 * if the user does not have permission to change the selection,
72 * or if the Selection instance does not have ::State::STATE_SENSITIVE.
74 * @param childIndex: a long integer indicating which child of the
75 * Selection is to be selected.
77 * @returns \c True if the child was successfully selected,
80 boolean selectChild (in long childIndex);
82 * Remove a child to the selected children list of a Selection.
83 * @note \c childIndex is the index in the selected-children list,
84 * not the index in the parent container. \c selectedChildIndex in this
85 * method, and \c childIndex in Selection::selectChild
88 * @param selectedChildIndex: a long integer indicating which of the
89 * selected children of the Selection is to be deselected. The index
90 * is a zero-offset index into the 'selected child list', not
91 * a zero-offset index into the list of all children of the Selection.
93 * @returns \c True if the child was successfully deselected,
98 boolean deselectSelectedChild (in long selectedChildIndex);
100 * Determine whether a particular child of an Selection implementor
101 * is currently selected. Note that \c childIndex is the zero-offset
102 * index into the standard Accessible container's list of children.
104 * @param childIndex: an index into the Selection's list of children.
106 * @returns \c True if the specified child is currently selected,
107 * \c False otherwise.
109 boolean isChildSelected (in long childIndex);
111 * Attempt to select all of the children of a Selection implementor.
112 * Not all Selection implementors support this operation (for instance,
113 * implementations which support only "single selection" do not support this operation).
115 * @returns \c True if successful, \c False otherwise.
117 boolean selectAll ();
119 * Attempt to clear all selections (i.e. deselect all children) of a Selection.
120 * Not all Selection implementations allow the removal of all selections.
122 * @note this operation may fail if the object must have at least one selected child,
123 * if the user does not have permission to change the selection, or if the Selection
124 * does not have ::State::STATE_SENSITIVE.
126 * @returns \c True if the selections were successfully cleared, \c False otherwise.
128 boolean clearSelection ();
130 * Remove a child from the selected children list of a Selection,
131 * if the child is currently selected.
133 * @note unlike deselectSelectedChild, \c childIndex is the zero-offset
134 * index into the Accessible instance's list of children,
135 * not the index into the 'selected child list'.
137 * @param childIndex: a long integer (the zero offset index into the Accessible
138 * object's list of children) indicating which child of the
139 * Selection is to be selected.
141 * @returns \c True if the child was successfully selected,
142 * \c False otherwise.
144 * @see deselectSelectedChild
146 * @since AT-SPI 1.8.0
148 boolean deselectChild (in long childIndex);
153 * placeholders for future expansion.
155 void unImplemented ();
156 void unImplemented2 ();
157 void unImplemented3 ();