diff -r 000000000000 -r 6474c204b198 accessible/public/nsIAccessiblePivot.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/accessible/public/nsIAccessiblePivot.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,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); +};