1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/accessible/public/nsIAccessiblePivot.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,232 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim: set ts=2 et sw=2 tw=80: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +typedef short TextBoundaryType;
1.13 +typedef short PivotMoveReason;
1.14 +
1.15 +interface nsIAccessible;
1.16 +interface nsIAccessibleText;
1.17 +interface nsIAccessibleTraversalRule;
1.18 +interface nsIAccessiblePivotObserver;
1.19 +
1.20 +/**
1.21 + * The pivot interface encapsulates a reference to a single place in an accessible
1.22 + * subtree. The pivot is a point or a range in the accessible tree. This interface
1.23 + * provides traversal methods to move the pivot to next/prev state that complies
1.24 + * to a given rule.
1.25 + */
1.26 +[scriptable, uuid(c2938033-e240-4fe5-9cb6-e7ad649ccd10)]
1.27 +interface nsIAccessiblePivot : nsISupports
1.28 +{
1.29 + const TextBoundaryType CHAR_BOUNDARY = 0;
1.30 + const TextBoundaryType WORD_BOUNDARY = 1;
1.31 + const TextBoundaryType LINE_BOUNDARY = 2;
1.32 + const TextBoundaryType ATTRIBUTE_RANGE_BOUNDARY = 3;
1.33 +
1.34 + const PivotMoveReason REASON_NONE = 0;
1.35 + const PivotMoveReason REASON_NEXT = 1;
1.36 + const PivotMoveReason REASON_PREV = 2;
1.37 + const PivotMoveReason REASON_FIRST = 3;
1.38 + const PivotMoveReason REASON_LAST = 4;
1.39 + const PivotMoveReason REASON_TEXT = 5;
1.40 + const PivotMoveReason REASON_POINT = 6;
1.41 +
1.42 + /**
1.43 + * The accessible the pivot is currently pointed at.
1.44 + */
1.45 + attribute nsIAccessible position;
1.46 +
1.47 + /**
1.48 + * The root of the subtree in which the pivot traverses.
1.49 + */
1.50 + readonly attribute nsIAccessible root;
1.51 +
1.52 + /**
1.53 + * The temporary modal root to which traversal is limited to.
1.54 + */
1.55 + attribute nsIAccessible modalRoot;
1.56 +
1.57 + /**
1.58 + * The start offset of the text range the pivot points at, otherwise -1.
1.59 + */
1.60 + readonly attribute long startOffset;
1.61 +
1.62 + /**
1.63 + * The end offset of the text range the pivot points at, otherwise -1.
1.64 + */
1.65 + readonly attribute long endOffset;
1.66 +
1.67 + /**
1.68 + * Set the pivot's text range in a text accessible.
1.69 + *
1.70 + * @param aTextAccessible [in] the text accessible that contains the desired
1.71 + * range.
1.72 + * @param aStartOffset [in] the start offset to set.
1.73 + * @param aEndOffset [in] the end offset to set.
1.74 + * @throws NS_ERROR_INVALID_ARG when the offset exceeds the accessible's
1.75 + * character count.
1.76 + */
1.77 + void setTextRange(in nsIAccessibleText aTextAccessible,
1.78 + in long aStartOffset, in long aEndOffset);
1.79 +
1.80 + /**
1.81 + * Move pivot to next object, from current position or given anchor,
1.82 + * complying to given traversal rule.
1.83 + *
1.84 + * @param aRule [in] traversal rule to use.
1.85 + * @param aAnchor [in] accessible to start search from, if not provided,
1.86 + * current position will be used.
1.87 + * @param aIncludeStart [in] include anchor accessible in search.
1.88 + * @return true on success, false if there are no new nodes to traverse to.
1.89 + */
1.90 + [optional_argc] boolean moveNext(in nsIAccessibleTraversalRule aRule,
1.91 + [optional] in nsIAccessible aAnchor,
1.92 + [optional] in boolean aIncludeStart);
1.93 +
1.94 + /**
1.95 + * Move pivot to previous object, from current position or given anchor,
1.96 + * complying to given traversal rule.
1.97 + *
1.98 + * @param aRule [in] traversal rule to use.
1.99 + * @param aAnchor [in] accessible to start search from, if not provided,
1.100 + * current position will be used.
1.101 + * @param aIncludeStart [in] include anchor accessible in search.
1.102 + * @return true on success, false if there are no new nodes to traverse to.
1.103 + */
1.104 + [optional_argc] boolean movePrevious(in nsIAccessibleTraversalRule aRule,
1.105 + [optional] in nsIAccessible aAnchor,
1.106 + [optional] in boolean aIncludeStart);
1.107 +
1.108 + /**
1.109 + * Move pivot to first object in subtree complying to given traversal rule.
1.110 + *
1.111 + * @param aRule [in] traversal rule to use.
1.112 + * @return true on success, false if there are no new nodes to traverse to.
1.113 + */
1.114 + boolean moveFirst(in nsIAccessibleTraversalRule aRule);
1.115 +
1.116 + /**
1.117 + * Move pivot to last object in subtree complying to given traversal rule.
1.118 + *
1.119 + * @param aRule [in] traversal rule to use.
1.120 + * @return true on success, false if there are no new nodes to traverse to.
1.121 + */
1.122 + boolean moveLast(in nsIAccessibleTraversalRule aRule);
1.123 +
1.124 + /**
1.125 + * Move pivot to next text range.
1.126 + *
1.127 + * @param aBoundary [in] type of boundary for next text range, character, word,
1.128 + * etc.
1.129 + * @return true on success, false if there are is no more text.
1.130 + */
1.131 + boolean moveNextByText(in TextBoundaryType aBoundary);
1.132 +
1.133 + /**
1.134 + * Move pivot to previous text range.
1.135 + *
1.136 + * @param aBoundary [in] type of boundary for previous text range, character,
1.137 + * word, etc.
1.138 + * @return true on success, false if there are is no more text.
1.139 + */
1.140 + boolean movePreviousByText(in TextBoundaryType aBoundary);
1.141 +
1.142 + /**
1.143 + * Move pivot to given coordinate in screen pixels.
1.144 + *
1.145 + * @param aRule [in] raversal rule to use.
1.146 + * @param aX [in] screen's x coordinate
1.147 + * @param aY [in] screen's y coordinate
1.148 + * @param aIgnoreNoMatch [in] don't unset position if no object was found at
1.149 + * point.
1.150 + * @return true on success, false if the pivot has not been moved.
1.151 + */
1.152 + boolean moveToPoint(in nsIAccessibleTraversalRule aRule,
1.153 + in long aX, in long aY,
1.154 + in boolean aIgnoreNoMatch);
1.155 +
1.156 + /**
1.157 + * Add an observer for pivot changes.
1.158 + *
1.159 + * @param aObserver [in] the observer object to be notified of pivot changes.
1.160 + */
1.161 + void addObserver(in nsIAccessiblePivotObserver aObserver);
1.162 +
1.163 + /**
1.164 + * Remove an observer for pivot changes.
1.165 + *
1.166 + * @param aObserver [in] the observer object to remove from being notified.
1.167 + */
1.168 + void removeObserver(in nsIAccessiblePivotObserver aObserver);
1.169 +};
1.170 +
1.171 +/**
1.172 + * An observer interface for pivot changes.
1.173 + */
1.174 +[scriptable, uuid(b6508c5e-c081-467d-835c-613eedf9ee9b)]
1.175 +interface nsIAccessiblePivotObserver : nsISupports
1.176 +{
1.177 + /**
1.178 + * Called when the pivot changes.
1.179 + *
1.180 + * @param aPivot [in] the pivot that has changed.
1.181 + * @param aOldAccessible [in] the old pivot position before the change, or null.
1.182 + * @param aOldStart [in] the old start offset, or -1.
1.183 + * @param aOldEnd [in] the old end offset, or -1.
1.184 + * @param aReason [in] the reason for the pivot change.
1.185 + */
1.186 + void onPivotChanged(in nsIAccessiblePivot aPivot,
1.187 + in nsIAccessible aOldAccessible,
1.188 + in long aOldStart, in long aOldEnd,
1.189 + in PivotMoveReason aReason);
1.190 +};
1.191 +
1.192 +[scriptable, uuid(4d9c4352-20f5-4c54-9580-0c77bb6b1115)]
1.193 +interface nsIAccessibleTraversalRule : nsISupports
1.194 +{
1.195 + /* Ignore this accessible object */
1.196 + const unsigned short FILTER_IGNORE = 0x0;
1.197 + /* Accept this accessible object */
1.198 + const unsigned short FILTER_MATCH = 0x1;
1.199 + /* Don't traverse accessibles children */
1.200 + const unsigned short FILTER_IGNORE_SUBTREE = 0x2;
1.201 +
1.202 + /* Pre-filters */
1.203 + const unsigned long PREFILTER_INVISIBLE = 0x00000001;
1.204 + const unsigned long PREFILTER_OFFSCREEN = 0x00000002;
1.205 + const unsigned long PREFILTER_NOT_FOCUSABLE = 0x00000004;
1.206 + const unsigned long PREFILTER_ARIA_HIDDEN = 0x00000008;
1.207 + const unsigned long PREFILTER_TRANSPARENT = 0x00000010;
1.208 +
1.209 + /**
1.210 + * Pre-filter bitfield to filter out obviously ignorable nodes and lighten
1.211 + * the load on match().
1.212 + */
1.213 + readonly attribute unsigned long preFilter;
1.214 +
1.215 + /**
1.216 + * Retrieve a list of roles that the traversal rule should test for. Any node
1.217 + * with a role not in this list will automatically be ignored. An empty list
1.218 + * will match all roles. It should be assumed that this method is called once
1.219 + * at the start of a traversal, so changing the method's return result after
1.220 + * that would have no affect.
1.221 + *
1.222 + * @param aRoles [out] an array of the roles to match.
1.223 + * @param aCount [out] the length of the array.
1.224 + */
1.225 + void getMatchRoles([array, size_is(aCount)]out unsigned long aRoles,
1.226 + [retval]out unsigned long aCount);
1.227 +
1.228 + /**
1.229 + * Determines if a given accessible is to be accepted in our traversal rule
1.230 + *
1.231 + * @param aAccessible [in] accessible to examine.
1.232 + * @return a bitfield of FILTER_MATCH and FILTER_IGNORE_SUBTREE.
1.233 + */
1.234 + unsigned short match(in nsIAccessible aAccessible);
1.235 +};
