DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (31ec81b5d7bb)

VCS Links

Line Code
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
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=2 et sw=2 tw=80: */
/* 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(c2938033-e240-4fe5-9cb6-e7ad649ccd10)]
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.
   * @throws NS_ERROR_INVALID_ARG when the offset exceeds the accessible's
   *   character count.
   */
  void setTextRange(in nsIAccessibleText aTextAccessible,
                    in long aStartOffset, in long aEndOffset);

  /**
   * 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.
   * @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);

  /**
   * 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.
   * @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);

  /**
   * Move pivot to first object in subtree complying to given traversal rule.
   *
   * @param aRule [in] traversal rule to use.
   * @return true on success, false if there are no new nodes to traverse to.
   */
  boolean moveFirst(in nsIAccessibleTraversalRule aRule);

  /**
   * Move pivot to last object in subtree complying to given traversal rule.
   *
   * @param aRule [in] traversal rule to use.
   * @return true on success, false if there are no new nodes to traverse to.
   */
  boolean moveLast(in nsIAccessibleTraversalRule aRule);

  /**
   * Move pivot to next text range.
   *
   * @param aBoundary [in] type of boundary for next text range, character, word,
   *                  etc.
   * @return true on success, false if there are is no more text.
   */
  boolean moveNextByText(in TextBoundaryType aBoundary);
  
  /**
   * Move pivot to previous text range.
   *
   * @param aBoundary [in] type of boundary for previous text range, character,
   *                  word, etc.
   * @return true on success, false if there are is no more text.
   */
  boolean movePreviousByText(in TextBoundaryType aBoundary);

  /**
   * 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.
   * @return true on success, false if the pivot has not been moved.
   */
  boolean moveToPoint(in nsIAccessibleTraversalRule aRule,
                      in long aX, in long aY,
                      in boolean aIgnoreNoMatch);

  /**
   * 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(b6508c5e-c081-467d-835c-613eedf9ee9b)]
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.
   */
  void onPivotChanged(in nsIAccessiblePivot aPivot,
                      in nsIAccessible aOldAccessible,
                      in long aOldStart, in long aOldEnd,
                      in PivotMoveReason aReason);
};

[scriptable, uuid(4d9c4352-20f5-4c54-9580-0c77bb6b1115)]
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);
};