bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/accessibility/AccessibleTextExtendedAdapter.java

   1 /*******************************************************************************
   2  * Copyright (c) 2009, 2016 IBM Corporation and others.
   3  *
   4  * This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License 2.0
   6  * which accompanies this distribution, and is available at
   7  * https://www.eclipse.org/legal/epl-2.0/
   8  *
   9  * SPDX-License-Identifier: EPL-2.0
  10  *
  11  * Contributors:
  12  *     IBM Corporation - initial API and implementation
  13  *******************************************************************************/
  14 package org.eclipse.swt.accessibility;
  15
  16 /**
  17  * This adapter class provides default implementations for the
  18  * methods in the <code>AccessibleTextExtendedListener</code> interface.
  19  * <p>
  20  * Classes that wish to deal with <code>AccessibleTextExtended</code> events can
  21  * extend this class and override only the methods that they are
  22  * interested in.
  23  * </p>
  24  *
  25  * @see AccessibleTextExtendedListener
  26  * @see AccessibleTextEvent
  27  *
  28  * @since 3.6
  29  */
  30 public class AccessibleTextExtendedAdapter extends AccessibleTextAdapter implements AccessibleTextExtendedListener {
  31         /**
  32          * Adds a text selection.
  33          *
  34          * @param e an event object containing the following fields:<ul>
  35          * <li>[in] start - the 0 based offset of the first character of the new selection</li>
  36          * <li>[in] end - the 0 based offset after the last character of the new selection</li>
  37          * <li>[out] result - set to {@link ACC#OK} if the text selection was added</li>
  38          * </ul>
  39          */
  40         @Override
  41         public void addSelection(AccessibleTextEvent e) {}
  42
  43         /**
  44          * Returns the total number of characters in the text.
  45          *
  46          * @param e an event object containing the following fields:<ul>
  47          * <li>[out] count - the total number of characters</li>
  48          * </ul>
  49          */
  50         @Override
  51         public void getCharacterCount(AccessibleTextEvent e) {}
  52
  53         /**
  54          * Returns the number of links and link groups contained within this hypertext
  55          * paragraph.
  56          *
  57          * @param e an event object containing the following fields:<ul>
  58          * <li>[out] count - the number of links and link groups within this hypertext paragraph,
  59          *              or 0 if there are none</li>
  60          * </ul>
  61          */
  62         @Override
  63         public void getHyperlinkCount(AccessibleTextEvent e) {}
  64
  65         /**
  66          * Returns the specified hyperlink.
  67          *
  68          * @param e an event object containing the following fields:<ul>
  69          * <li>[in] index - the 0 based index of the hyperlink to return</li>
  70          * <li>[out] accessible - the specified hyperlink object, or null if the index is invalid</li>
  71          * </ul>
  72          */
  73         @Override
  74         public void getHyperlink(AccessibleTextEvent e) {}
  75
  76         /**
  77          * Returns the index of the hyperlink that is associated with this character offset.
  78          * <p>
  79          * This is the case when a link spans the given character index.
  80          * </p>
  81          * @param e an event object containing the following fields:<ul>
  82          * <li>[in] offset - the 0 based offset of the character for which to return the link index</li>
  83          * <li>[out] index - the 0 based index of the hyperlink that is associated with this
  84          *              character offset, or -1 if the offset is not in a link</li>
  85          * </ul>
  86          */
  87         @Override
  88         public void getHyperlinkIndex(AccessibleTextEvent e) {}
  89
  90         /**
  91          * Returns the offset of the character under the specified point.
  92          *
  93          * @param e an event object containing the following fields:<ul>
  94          * <li>[in] x - the X value in display coordinates for which to look up the offset of the character
  95          *              that is rendered on the display at that point</li>
  96          * <li>[in] y - the position's Y value for which to look up the offset of the character
  97          *              that is rendered on the display at that point</li>
  98          * <li>[out] offset - the 0 based offset of the character under the given point,
  99          *              or -1 if the point is invalid or there is no character under the point</li>
 100          * </ul>
 101          */
 102         @Override
 103         public void getOffsetAtPoint(AccessibleTextEvent e) {}
 104
 105         /**
 106          * Returns the text range(s) contained within the given bounding box.
 107          * <p>
 108          * Partially visible characters are included in the returned ranges.
 109          * </p>
 110          *
 111          * @param e an event object containing the following fields:<ul>
 112          * <li>[in] x - the X coordinate of the top left corner of the bounding box, in display relative coordinates</li>
 113          * <li>[in] y - the Y coordinate of the top left corner of the bounding box, in display relative coordinates</li>
 114          * <li>[in] width - the width of the bounding box</li>
 115          * <li>[in] height - the height of the bounding box</li>
 116          * <li>[typical out] start - the 0 based offset of the first character of the substring in the bounding box</li>
 117          * <li>[typical out] end - the 0 based offset after the last character of the substring in the bounding box</li>
 118          * <li>[optional out] ranges - an array of pairs specifying the start and end offsets of each range,
 119          *              if the text range is clipped by the bounding box</li>
 120          * </ul>
 121          */
 122         @Override
 123         public void getRanges(AccessibleTextEvent e) {}
 124
 125         /**
 126          * Returns the character offsets of the specified text selection.
 127          *
 128          * @param e an event object containing the following fields:<ul>
 129          * <li>[in] index - the 0 based index of the selection</li>
 130          * <li>[out] start - the 0 based offset of first selected character</li>
 131          * <li>[out] end - the 0 based offset after the last selected character</li>
 132          * </ul>
 133          */
 134         @Override
 135         public void getSelection(AccessibleTextEvent e) {}
 136
 137         /**
 138          * Returns the number of active non-contiguous selections.
 139          *
 140          * @param e an event object containing the following fields:<ul>
 141          * <li>[out] count - the number of active non-contiguous selections</li>
 142          * </ul>
 143          */
 144         @Override
 145         public void getSelectionCount(AccessibleTextEvent e) {}
 146
 147         /**
 148          * Returns a substring and its range for the given range, count and boundary type.
 149          * <p>
 150          * Returns the substring of the specified boundary type that is located count
 151          * positions from the given character range. Also returns the start and end
 152          * offsets of the returned substring.
 153          * </p><p>
 154          * For example, if the boundary type is TEXT_BOUNDARY_WORD, then the complete
 155          * word that is located count words from the specified range is returned.
 156          * If count is negative, then return the word that is count words before start.
 157          * If count is positive, then return the word that is count words after end.
 158          * If count is zero, start and end are the same, so return the word at start.
 159          * </p><p>
 160          * The whole text can be requested by passing start == 0 and end == getCharacterCount,
 161          * TEXT_BOUNDARY_ALL, and 0 for count. Alternatively the whole text can be requested
 162          * by calling AccessibleControlListener.getValue().
 163          * </p><p>
 164          * If start and end are valid, but no suitable word (or other boundary type) is found,
 165          * the returned string is null and the returned range is degenerate (start == end).
 166          * </p>
 167          *
 168          * @param e an event object containing the following fields:<ul>
 169          * <li>[in] type - the boundary type of the substring to return. One of:<ul>
 170          *              <li> {@link ACC#TEXT_BOUNDARY_CHAR}</li>
 171          *              <li> {@link ACC#TEXT_BOUNDARY_WORD}</li>
 172          *              <li> {@link ACC#TEXT_BOUNDARY_SENTENCE}</li>
 173          *              <li> {@link ACC#TEXT_BOUNDARY_PARAGRAPH}</li>
 174          *              <li> {@link ACC#TEXT_BOUNDARY_LINE}</li>
 175          *              <li> {@link ACC#TEXT_BOUNDARY_ALL}</li>
 176          *              </ul></li>
 177          * <li>[in,out] start - the 0 based offset of first character of the substring</li>
 178          * <li>[in,out] end - the 0 based offset after the last character of the substring</li>
 179          * <li>[in,out] count - the number of boundary type units to move to find the substring:<ul>
 180          *              <li>in - look count units before start if count &lt; 0, or after end if count &gt; 0. Look at start if count == 0</li>
 181          *              <li>out - the actual number of boundary type units that were moved. This may be fewer than the input count</li>
 182          *              </ul></li>
 183          * <li>[out] result - the requested substring.  This may be empty or null
 184          *              when no appropriate substring is found, or if the type is invalid.</li>
 185          * </ul>
 186          */
 187         @Override
 188         public void getText(AccessibleTextEvent e) {}
 189
 190         /**
 191          * Returns the bounding box(es) of the specified text range in display coordinates.
 192          * <p>
 193          * Typically, the text range will represent a single character, i.e. end - start = 1,
 194          * therefore providers should optimize for this case.
 195          * </p><p>
 196          * Note: The virtual character after the last character of the represented text,
 197          * i.e. the one at offset getCharacterCount, is a special case. It represents the
 198          * current input position and will therefore typically be queried by AT more
 199          * often than other positions.  Because it does not represent an existing character
 200          * its bounding box is defined in relation to preceding characters.  It should be
 201          * roughly equivalent to the bounding box of some character when inserted at the
 202          * end of the text; its height typically being the maximal height of all the
 203          * characters in the text or the height of the preceding character, its width
 204          * being at least one pixel so that the bounding box is not degenerate.
 205          * </p>
 206          *
 207          * @param e an event object containing the following fields:<ul>
 208          * <li>[in] start - the 0 based offset of the first character of the substring in the bounding box</li>
 209          * <li>[in] end - the 0 based offset after the last character of the substring in the bounding box</li>
 210          * <li>[typical out] x - the X coordinate of the top left corner of the bounding box of the specified substring</li>
 211          * <li>[typical out] y - the Y coordinate of the top left corner of the bounding box of the specified substring</li>
 212          * <li>[typical out] width - the width of the bounding box of the specified substring</li>
 213          * <li>[typical out] height - the height of the bounding box of the specified substring</li>
 214          * <li>[optional out] rectangles - a set of disjoint bounding rectangles, if the specified text range includes
 215          *              partial lines</li>
 216          * </ul>
 217          */
 218         @Override
 219         public void getTextBounds(AccessibleTextEvent e) {}
 220
 221         /**
 222          * Returns the visible text range(s).
 223          * <p>
 224          * Partially visible characters are included in the returned ranges.
 225          * </p>
 226          *
 227          * @param e an event object containing the following fields:<ul>
 228          * <li>[typical out] start - the 0 based offset of the first character of the visible substring</li>
 229          * <li>[typical out] end - the 0 based offset after the last character of the visible substring</li>
 230          * <li>[optional out] ranges - an array of pairs specifying the start and end offsets of each range,
 231          *              if the visible text range is clipped</li>
 232          * </ul>
 233          */
 234         @Override
 235         public void getVisibleRanges(AccessibleTextEvent e) {}
 236
 237         /**
 238          * Deselects a range of text.
 239          *
 240          * @param e an event object containing the following fields:<ul>
 241          * <li>[in] index - the 0 based index of selection to remove</li>
 242          * <li>[out] result - set to {@link ACC#OK} if the range of text was deselected</li>
 243          * </ul>
 244          */
 245         @Override
 246         public void removeSelection(AccessibleTextEvent e) {}
 247
 248         /**
 249          * Scrolls a specific part of a substring according to the scroll type.
 250          *
 251          * @param e an event object containing the following fields:<ul>
 252          * <li>[in] start - the 0 based offset of the first character of the substring</li>
 253          * <li>[in] end - the 0 based offset after the last character of the substring</li>
 254          * <li>[in] type - a scroll type indicating where the substring should be placed
 255          *              on the screen. One of:<ul>
 256          *              <li> {@link ACC#SCROLL_TYPE_TOP_LEFT}</li>
 257          *              <li> {@link ACC#SCROLL_TYPE_BOTTOM_RIGHT}</li>
 258          *              <li> {@link ACC#SCROLL_TYPE_TOP_EDGE}</li>
 259          *              <li> {@link ACC#SCROLL_TYPE_BOTTOM_EDGE}</li>
 260          *              <li> {@link ACC#SCROLL_TYPE_LEFT_EDGE}</li>
 261          *              <li> {@link ACC#SCROLL_TYPE_RIGHT_EDGE}</li>
 262          *              <li> {@link ACC#SCROLL_TYPE_ANYWHERE}</li>
 263          *              <li> {@link ACC#SCROLL_TYPE_POINT}</li>
 264          *              </ul></li>
 265          * <li>[optional in] x - for SCROLL_TYPE_POINT, the X coordinate of the destination point in display coordinates</li>
 266          * <li>[optional in] y - for SCROLL_TYPE_POINT, the Y coordinate of the destination point in display coordinates</li>
 267          * <li>[out] result - set to {@link ACC#OK} if the text was scrolled</li>
 268          * </ul>
 269          */
 270         @Override
 271         public void scrollText(AccessibleTextEvent e) {}
 272
 273         /**
 274          * Sets the position of the caret.
 275          * <p>
 276          * The caret position is that of the character logically following it,
 277          * e.g. to the right of it in a left to right language.
 278          * The caret is actually placed to the leading side of the character with
 279          * that offset. An offset of 0 places the caret so that the next insertion
 280          * goes before the first character. An offset of getCharacterCount places
 281          * the caret so that the next insertion goes after the last character.
 282          * </p><p>
 283          * Setting the caret position may or may not alter the current selection.  A
 284          * change of the selection is notified to the accessibility event listeners with
 285          * an EVENT_TEXT_SELECTION_CHANGED event.
 286          * </p><p>
 287          * When the new caret position differs from the old one, this is notified to the
 288          * accessibility event listeners with an EVENT_TEXT_CARET_MOVED event.
 289          * </p>
 290          *
 291          * @param e an event object containing the following fields:<ul>
 292          * <li>[in] offset - the new offset of the caret</li>
 293          * <li>[out] result - set to {@link ACC#OK} if the caret position was set</li>
 294          * </ul>
 295          */
 296         @Override
 297         public void setCaretOffset(AccessibleTextEvent e) {}
 298
 299         /**
 300          * Changes the bounds of an existing selection.
 301          *
 302          * @param e an event object containing the following fields:<ul>
 303          * <li>[in] index - the 0 based index of the selection to change</li>
 304          * <li>[in] start - the new 0 based offset of the first character of the selection</li>
 305          * <li>[in] end - the new 0 based offset after the last character of the selection</li>
 306          * <li>[out] result - set to {@link ACC#OK} if the selection was set</li>
 307          * </ul>
 308          */
 309         @Override
 310         public void setSelection(AccessibleTextEvent e) {}
 311 }