accessible/public/nsIAccessiblePivot.idl@141e0f1194b1
accessible/public/nsIAccessiblePivot.idl
Wed, 31 Dec 2014 07:16:47 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:16:47 +0100
- branch
- TOR_BUG_9701
- changeset 3
- 141e0f1194b1
- permissions
- -rw-r--r--
Revert simplistic fix pending revisit of Mozilla integration attempt.
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include "nsISupports.idl"
9 typedef short TextBoundaryType;
10 typedef short PivotMoveReason;
12 interface nsIAccessible;
13 interface nsIAccessibleText;
14 interface nsIAccessibleTraversalRule;
15 interface nsIAccessiblePivotObserver;
17 /**
18 * The pivot interface encapsulates a reference to a single place in an accessible
19 * subtree. The pivot is a point or a range in the accessible tree. This interface
20 * provides traversal methods to move the pivot to next/prev state that complies
21 * to a given rule.
22 */
23 [scriptable, uuid(c2938033-e240-4fe5-9cb6-e7ad649ccd10)]
24 interface nsIAccessiblePivot : nsISupports
25 {
26 const TextBoundaryType CHAR_BOUNDARY = 0;
27 const TextBoundaryType WORD_BOUNDARY = 1;
28 const TextBoundaryType LINE_BOUNDARY = 2;
29 const TextBoundaryType ATTRIBUTE_RANGE_BOUNDARY = 3;
31 const PivotMoveReason REASON_NONE = 0;
32 const PivotMoveReason REASON_NEXT = 1;
33 const PivotMoveReason REASON_PREV = 2;
34 const PivotMoveReason REASON_FIRST = 3;
35 const PivotMoveReason REASON_LAST = 4;
36 const PivotMoveReason REASON_TEXT = 5;
37 const PivotMoveReason REASON_POINT = 6;
39 /**
40 * The accessible the pivot is currently pointed at.
41 */
42 attribute nsIAccessible position;
44 /**
45 * The root of the subtree in which the pivot traverses.
46 */
47 readonly attribute nsIAccessible root;
49 /**
50 * The temporary modal root to which traversal is limited to.
51 */
52 attribute nsIAccessible modalRoot;
54 /**
55 * The start offset of the text range the pivot points at, otherwise -1.
56 */
57 readonly attribute long startOffset;
59 /**
60 * The end offset of the text range the pivot points at, otherwise -1.
61 */
62 readonly attribute long endOffset;
64 /**
65 * Set the pivot's text range in a text accessible.
66 *
67 * @param aTextAccessible [in] the text accessible that contains the desired
68 * range.
69 * @param aStartOffset [in] the start offset to set.
70 * @param aEndOffset [in] the end offset to set.
71 * @throws NS_ERROR_INVALID_ARG when the offset exceeds the accessible's
72 * character count.
73 */
74 void setTextRange(in nsIAccessibleText aTextAccessible,
75 in long aStartOffset, in long aEndOffset);
77 /**
78 * Move pivot to next object, from current position or given anchor,
79 * complying to given traversal rule.
80 *
81 * @param aRule [in] traversal rule to use.
82 * @param aAnchor [in] accessible to start search from, if not provided,
83 * current position will be used.
84 * @param aIncludeStart [in] include anchor accessible in search.
85 * @return true on success, false if there are no new nodes to traverse to.
86 */
87 [optional_argc] boolean moveNext(in nsIAccessibleTraversalRule aRule,
88 [optional] in nsIAccessible aAnchor,
89 [optional] in boolean aIncludeStart);
91 /**
92 * Move pivot to previous object, from current position or given anchor,
93 * complying to given traversal rule.
94 *
95 * @param aRule [in] traversal rule to use.
96 * @param aAnchor [in] accessible to start search from, if not provided,
97 * current position will be used.
98 * @param aIncludeStart [in] include anchor accessible in search.
99 * @return true on success, false if there are no new nodes to traverse to.
100 */
101 [optional_argc] boolean movePrevious(in nsIAccessibleTraversalRule aRule,
102 [optional] in nsIAccessible aAnchor,
103 [optional] in boolean aIncludeStart);
105 /**
106 * Move pivot to first object in subtree complying to given traversal rule.
107 *
108 * @param aRule [in] traversal rule to use.
109 * @return true on success, false if there are no new nodes to traverse to.
110 */
111 boolean moveFirst(in nsIAccessibleTraversalRule aRule);
113 /**
114 * Move pivot to last object in subtree complying to given traversal rule.
115 *
116 * @param aRule [in] traversal rule to use.
117 * @return true on success, false if there are no new nodes to traverse to.
118 */
119 boolean moveLast(in nsIAccessibleTraversalRule aRule);
121 /**
122 * Move pivot to next text range.
123 *
124 * @param aBoundary [in] type of boundary for next text range, character, word,
125 * etc.
126 * @return true on success, false if there are is no more text.
127 */
128 boolean moveNextByText(in TextBoundaryType aBoundary);
130 /**
131 * Move pivot to previous text range.
132 *
133 * @param aBoundary [in] type of boundary for previous text range, character,
134 * word, etc.
135 * @return true on success, false if there are is no more text.
136 */
137 boolean movePreviousByText(in TextBoundaryType aBoundary);
139 /**
140 * Move pivot to given coordinate in screen pixels.
141 *
142 * @param aRule [in] raversal rule to use.
143 * @param aX [in] screen's x coordinate
144 * @param aY [in] screen's y coordinate
145 * @param aIgnoreNoMatch [in] don't unset position if no object was found at
146 * point.
147 * @return true on success, false if the pivot has not been moved.
148 */
149 boolean moveToPoint(in nsIAccessibleTraversalRule aRule,
150 in long aX, in long aY,
151 in boolean aIgnoreNoMatch);
153 /**
154 * Add an observer for pivot changes.
155 *
156 * @param aObserver [in] the observer object to be notified of pivot changes.
157 */
158 void addObserver(in nsIAccessiblePivotObserver aObserver);
160 /**
161 * Remove an observer for pivot changes.
162 *
163 * @param aObserver [in] the observer object to remove from being notified.
164 */
165 void removeObserver(in nsIAccessiblePivotObserver aObserver);
166 };
168 /**
169 * An observer interface for pivot changes.
170 */
171 [scriptable, uuid(b6508c5e-c081-467d-835c-613eedf9ee9b)]
172 interface nsIAccessiblePivotObserver : nsISupports
173 {
174 /**
175 * Called when the pivot changes.
176 *
177 * @param aPivot [in] the pivot that has changed.
178 * @param aOldAccessible [in] the old pivot position before the change, or null.
179 * @param aOldStart [in] the old start offset, or -1.
180 * @param aOldEnd [in] the old end offset, or -1.
181 * @param aReason [in] the reason for the pivot change.
182 */
183 void onPivotChanged(in nsIAccessiblePivot aPivot,
184 in nsIAccessible aOldAccessible,
185 in long aOldStart, in long aOldEnd,
186 in PivotMoveReason aReason);
187 };
189 [scriptable, uuid(4d9c4352-20f5-4c54-9580-0c77bb6b1115)]
190 interface nsIAccessibleTraversalRule : nsISupports
191 {
192 /* Ignore this accessible object */
193 const unsigned short FILTER_IGNORE = 0x0;
194 /* Accept this accessible object */
195 const unsigned short FILTER_MATCH = 0x1;
196 /* Don't traverse accessibles children */
197 const unsigned short FILTER_IGNORE_SUBTREE = 0x2;
199 /* Pre-filters */
200 const unsigned long PREFILTER_INVISIBLE = 0x00000001;
201 const unsigned long PREFILTER_OFFSCREEN = 0x00000002;
202 const unsigned long PREFILTER_NOT_FOCUSABLE = 0x00000004;
203 const unsigned long PREFILTER_ARIA_HIDDEN = 0x00000008;
204 const unsigned long PREFILTER_TRANSPARENT = 0x00000010;
206 /**
207 * Pre-filter bitfield to filter out obviously ignorable nodes and lighten
208 * the load on match().
209 */
210 readonly attribute unsigned long preFilter;
212 /**
213 * Retrieve a list of roles that the traversal rule should test for. Any node
214 * with a role not in this list will automatically be ignored. An empty list
215 * will match all roles. It should be assumed that this method is called once
216 * at the start of a traversal, so changing the method's return result after
217 * that would have no affect.
218 *
219 * @param aRoles [out] an array of the roles to match.
220 * @param aCount [out] the length of the array.
221 */
222 void getMatchRoles([array, size_is(aCount)]out unsigned long aRoles,
223 [retval]out unsigned long aCount);
225 /**
226 * Determines if a given accessible is to be accepted in our traversal rule
227 *
228 * @param aAccessible [in] accessible to examine.
229 * @return a bitfield of FILTER_MATCH and FILTER_IGNORE_SUBTREE.
230 */
231 unsigned short match(in nsIAccessible aAccessible);
232 };
