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