diff options
Diffstat (limited to 'accessible/interfaces/nsIAccessiblePivot.idl')
| -rw-r--r-- | accessible/interfaces/nsIAccessiblePivot.idl | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/accessible/interfaces/nsIAccessiblePivot.idl b/accessible/interfaces/nsIAccessiblePivot.idl new file mode 100644 index 000000000..76d2bfd75 --- /dev/null +++ b/accessible/interfaces/nsIAccessiblePivot.idl @@ -0,0 +1,259 @@ +/* -*- 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(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); +}; |