summaryrefslogtreecommitdiff
path: root/accessible/interfaces/nsIAccessiblePivot.idl
blob: 1db63fc15ed89f8558bbdf66a671f99a06b2e1da (plain)
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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

typedef short TextBoundaryType;
typedef short PivotMoveReason;

interface nsIAccessible;
interface nsIAccessibleText;
interface nsIAccessibleTraversalRule;
interface nsIAccessiblePivotObserver;

/**
 * The pivot interface encapsulates a reference to a single place in an accessible
 * subtree. The pivot is a point or a range in the accessible tree. This interface
 * provides traversal methods to move the pivot to next/prev state that complies 
 * to a given rule.
 */
[scriptable, uuid(81fe5144-059b-42db-bd3a-f6ce3158d5e9)]
interface nsIAccessiblePivot : nsISupports
{
  const TextBoundaryType CHAR_BOUNDARY = 0;
  const TextBoundaryType WORD_BOUNDARY = 1;
  const TextBoundaryType LINE_BOUNDARY = 2;
  const TextBoundaryType ATTRIBUTE_RANGE_BOUNDARY = 3;

  const PivotMoveReason REASON_NONE = 0;
  const PivotMoveReason REASON_NEXT = 1;
  const PivotMoveReason REASON_PREV = 2;
  const PivotMoveReason REASON_FIRST = 3;
  const PivotMoveReason REASON_LAST = 4;
  const PivotMoveReason REASON_TEXT = 5;
  const PivotMoveReason REASON_POINT = 6;

  /**
   * The accessible the pivot is currently pointed at.
   */
  attribute nsIAccessible position;

  /**
   * The root of the subtree in which the pivot traverses.
   */
  readonly attribute nsIAccessible root;

  /**
   * The temporary modal root to which traversal is limited to.
   */
  attribute nsIAccessible modalRoot;

  /**
   * The start offset of the text range the pivot points at, otherwise -1.
   */
  readonly attribute long startOffset;

  /**
   * The end offset of the text range the pivot points at, otherwise -1.
   */
  readonly attribute long endOffset;

  /**
   * Set the pivot's text range in a text accessible.
   *
   * @param aTextAccessible  [in] the text accessible that contains the desired
   *                           range.
   * @param aStartOffset     [in] the start offset to set.
   * @param aEndOffset       [in] the end offset to set.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @throws NS_ERROR_INVALID_ARG when the offset exceeds the accessible's
   *   character count.
   */
  [optional_argc] void setTextRange(in nsIAccessibleText aTextAccessible,
                                    in long aStartOffset, in long aEndOffset,
                                    [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to next object, from current position or given anchor,
   * complying to given traversal rule.
   *
   * @param aRule            [in] traversal rule to use.
   * @param aAnchor          [in] accessible to start search from, if not provided,
   *                           current position will be used.
   * @param aIncludeStart    [in] include anchor accessible in search.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if there are no new nodes to traverse to.
   */
  [optional_argc] boolean moveNext(in nsIAccessibleTraversalRule aRule,
                                   [optional] in nsIAccessible aAnchor,
                                   [optional] in boolean aIncludeStart,
                                   [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to previous object, from current position or given anchor,
   * complying to given traversal rule.
   *
   * @param aRule            [in] traversal rule to use.
   * @param aAnchor          [in] accessible to start search from, if not provided,
   *                           current position will be used.
   * @param aIncludeStart    [in] include anchor accessible in search.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if there are no new nodes to traverse to.
   */
  [optional_argc] boolean movePrevious(in nsIAccessibleTraversalRule aRule,
                                       [optional] in nsIAccessible aAnchor,
                                       [optional] in boolean aIncludeStart,
                                       [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to first object in subtree complying to given traversal rule.
   *
   * @param aRule            [in] traversal rule to use.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if there are no new nodes to traverse to.
   */
  [optional_argc] boolean moveFirst(in nsIAccessibleTraversalRule aRule,
                                    [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to last object in subtree complying to given traversal rule.
   *
   * @param aRule            [in] traversal rule to use.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   */
  [optional_argc] boolean moveLast(in nsIAccessibleTraversalRule aRule,
                                   [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to next text range.
   *
   * @param aBoundary        [in] type of boundary for next text range,
   *                           character, word, etc.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if there are is no more text.
   */
  [optional_argc] boolean moveNextByText(in TextBoundaryType aBoundary,
                                         [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to previous text range.
   *
   * @param aBoundary        [in] type of boundary for next text range,
   *                           character, word, etc.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if there are is no more text.
   */
  [optional_argc] boolean movePreviousByText(in TextBoundaryType aBoundary,
                                             [optional] in boolean aIsFromUserInput);

  /**
   * Move pivot to given coordinate in screen pixels.
   *
   * @param aRule            [in]  raversal rule to use.
   * @param aX               [in]  screen's x coordinate
   * @param aY               [in]  screen's y coordinate
   * @param aIgnoreNoMatch   [in]  don't unset position if no object was found
   *                           at point.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   * @return true on success, false if the pivot has not been moved.
   */
  [optional_argc] boolean moveToPoint(in nsIAccessibleTraversalRule aRule,
                                      in long aX, in long aY,
                                      in boolean aIgnoreNoMatch,
                                      [optional] in boolean aIsFromUserInput);

  /**
   * Add an observer for pivot changes.
   *
   * @param aObserver [in] the observer object to be notified of pivot changes.
   */
  void addObserver(in nsIAccessiblePivotObserver aObserver);

  /**
   * Remove an observer for pivot changes.
   *
   * @param aObserver [in] the observer object to remove from being notified.
   */
  void removeObserver(in nsIAccessiblePivotObserver aObserver);
};

/**
 * An observer interface for pivot changes.
 */
[scriptable, uuid(6006e502-3861-49bd-aba1-fa6d2e74e237)]
interface nsIAccessiblePivotObserver : nsISupports
{
  /**
   * Called when the pivot changes.
   *
   * @param aPivot           [in] the pivot that has changed.
   * @param aOldAccessible   [in] the old pivot position before the change,
   *                           or null.
   * @param aOldStart        [in] the old start offset, or -1.
   * @param aOldEnd          [in] the old end offset, or -1.
   * @param aReason          [in] the reason for the pivot change.
   * @param aIsFromUserInput [in] the pivot changed because of direct user input
   *                           (default is true).
   */
  void onPivotChanged(in nsIAccessiblePivot aPivot,
                      in nsIAccessible aOldAccessible,
                      in long aOldStart, in long aOldEnd,
                      in PivotMoveReason aReason,
                      in boolean aIsFromUserInput);
};

[scriptable, uuid(e197460d-1eff-4247-b4bb-a43be1840dae)]
interface nsIAccessibleTraversalRule : nsISupports
{
  /* Ignore this accessible object */
  const unsigned short FILTER_IGNORE = 0x0;
  /* Accept this accessible object */
  const unsigned short FILTER_MATCH = 0x1;
  /* Don't traverse accessibles children */
  const unsigned short FILTER_IGNORE_SUBTREE = 0x2;

  /* Pre-filters */
  const unsigned long PREFILTER_INVISIBLE     = 0x00000001;
  const unsigned long PREFILTER_OFFSCREEN     = 0x00000002;
  const unsigned long PREFILTER_NOT_FOCUSABLE = 0x00000004;
  const unsigned long PREFILTER_ARIA_HIDDEN   = 0x00000008;
  const unsigned long PREFILTER_TRANSPARENT   = 0x00000010;

  /**
   * Pre-filter bitfield to filter out obviously ignorable nodes and lighten
   * the load on match().
   */
  readonly attribute unsigned long preFilter;

  /**
   * Retrieve a list of roles that the traversal rule should test for. Any node
   * with a role not in this list will automatically be ignored. An empty list
   * will match all roles. It should be assumed that this method is called once
   * at the start of a traversal, so changing the method's return result after
   * that would have no affect.
   *
   * @param aRoles [out] an array of the roles to match.
   * @param aCount [out] the length of the array.
   */
  void getMatchRoles([array, size_is(aCount)]out unsigned long aRoles,
                     [retval]out unsigned long aCount);

  /**
   * Determines if a given accessible is to be accepted in our traversal rule
   *
   * @param aAccessible [in] accessible to examine.
   * @return a bitfield of FILTER_MATCH and FILTER_IGNORE_SUBTREE.
   */
  unsigned short match(in nsIAccessible aAccessible);
};