1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
/*
* AT-SPI - Assistive Technology Service Provider Interface
* (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
*
* Copyright 2001 Sun Microsystems, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#include <Accessibility_Accessible.idl>
module Accessibility {
/**
* An interface which indicates that an object exposes a 'selection' model,
* allowing the selection of one or more of its children. Read-only Selection
* instances are possible, in which case the interface is used to programmatically
* determine the selected-ness of its children. A selected child has ::State::STATE_SELECTED,
* and a child which may hypothetically be selected (though possibly not programmatically
* selectable) has ::State::STATE_SELECTABLE.
* @note Events emitted by implementors of Selection include:
* \li \c "object:selection-changed" An instance of Selection has undergone a change in the
* 'selected-ness' of its children, i.e. had a selection added,
* removed, and/or modified. Usually accompanied by
* corresponding \c "object:state-changed:selected" events
* from the corresponding children, unless the children are
* previously un-queried via AT-SPI and the Selection instance
* has ::State::STATE_MANAGES_DESCENDANTS.
**/
interface Selection : Bonobo::Unknown {
/**
* The number of children of a Selection implementor which are
* currently selected.
*/
readonly attribute long nSelectedChildren;
/**
* Get the i-th selected Accessible child of a Selection.
* @note \c selectedChildIndex refers to the index in the list of
* 'selected' children as opposed to the more general 'child index'
* of an object; as such it generally differs from that used in
* Accessible::getChildAtIndex() or returned by
* Accessible::getIndexInParent().
* \c selectedChildIndex must lie between 0
* and Selection::nSelectedChildren-1, inclusive.
* @param selectedChildIndex: a long integer indicating which of the
* selected children of an object is being requested.
* @returns a pointer to a selected Accessible child object,
* specified by \c selectedChildIndex.
*/
Accessible getSelectedChild (in long selectedChildIndex);
/**
* Add a child to the selected children list of a Selection.
* @note For Selection implementors that only allow
* single selections, this call may result in the
* replacement of the (single) current
* selection. The call may return \c False if
* the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE),
* if the user does not have permission to change the selection,
* or if the Selection instance does not have ::State::STATE_SENSITIVE.
*
* @param childIndex: a long integer indicating which child of the
* Selection is to be selected.
*
* @returns \c True if the child was successfully selected,
* \c False otherwise.
*/
boolean selectChild (in long childIndex);
/**
* Remove a child to the selected children list of a Selection.
* @note \c childIndex is the index in the selected-children list,
* not the index in the parent container. \c selectedChildIndex in this
* method, and \c childIndex in Selection::selectChild
* are asymmettric.
*
* @param selectedChildIndex: a long integer indicating which of the
* selected children of the Selection is to be deselected. The index
* is a zero-offset index into the 'selected child list', not
* a zero-offset index into the list of all children of the Selection.
*
* @returns \c True if the child was successfully deselected,
* \c False otherwise.
*
* @see deselectChild
**/
boolean deselectSelectedChild (in long selectedChildIndex);
/**
* Determine whether a particular child of an Selection implementor
* is currently selected. Note that \c childIndex is the zero-offset
* index into the standard Accessible container's list of children.
*
* @param childIndex: an index into the Selection's list of children.
*
* @returns \c True if the specified child is currently selected,
* \c False otherwise.
**/
boolean isChildSelected (in long childIndex);
/**
* Attempt to select all of the children of a Selection implementor.
* Not all Selection implementors support this operation (for instance,
* implementations which support only "single selection" do not support this operation).
*
* @returns \c True if successful, \c False otherwise.
*/
boolean selectAll ();
/**
* Attempt to clear all selections (i.e. deselect all children) of a Selection.
* Not all Selection implementations allow the removal of all selections.
*
* @note this operation may fail if the object must have at least one selected child,
* if the user does not have permission to change the selection, or if the Selection
* does not have ::State::STATE_SENSITIVE.
*
* @returns \c True if the selections were successfully cleared, \c False otherwise.
*/
boolean clearSelection ();
/**
* Remove a child from the selected children list of a Selection,
* if the child is currently selected.
*
* @note unlike deselectSelectedChild, \c childIndex is the zero-offset
* index into the Accessible instance's list of children,
* not the index into the 'selected child list'.
*
* @param childIndex: a long integer (the zero offset index into the Accessible
* object's list of children) indicating which child of the
* Selection is to be selected.
*
* @returns \c True if the child was successfully selected,
* \c False otherwise.
*
* @see deselectSelectedChild
*
* @since AT-SPI 1.8.0
*/
boolean deselectChild (in long childIndex);
/**
* unImplemented:
*
* placeholders for future expansion.
*/
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
};
};
|
