gecko-dev/accessible/interfaces/nsIAccessiblePivot.idl
2019-05-15 11:54:07 +00:00

260 lines
10 KiB
Plaintext

/* -*- 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 NO_BOUNDARY = -1;
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_POINT = 5;
/**
* 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 nsIAccessible aNewAccessible,
in long aNewStart, in long aNewEnd,
in PivotMoveReason aReason,
in TextBoundaryType aBoundaryType,
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_TRANSPARENT = 0x00000008;
const unsigned long PREFILTER_PLATFORM_PRUNED = 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.
*
* @return an array of the roles to match.
*/
Array<unsigned long> getMatchRoles();
/**
* 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);
};