1 /* 2 * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.accessibility; 27 28 import java.awt.Point; 29 import java.awt.Rectangle; 30 31 import javax.swing.text.AttributeSet; 32 33 /** 34 * The {@code AccessibleText} interface should be implemented by all classes 35 * that present textual information on the display. This interface provides the 36 * standard mechanism for an assistive technology to access that text via its 37 * content, attributes, and spatial location. Applications can determine if an 38 * object supports the {@code AccessibleText} interface by first obtaining its 39 * {@code AccessibleContext} (see {@link Accessible}) and then calling the 40 * {@link AccessibleContext#getAccessibleText} method of 41 * {@code AccessibleContext}. If the return value is not {@code null}, the 42 * object supports this interface. 43 * 44 * @author Peter Korn 45 * @see Accessible 46 * @see Accessible#getAccessibleContext 47 * @see AccessibleContext 48 * @see AccessibleContext#getAccessibleText 49 */ 50 public interface AccessibleText { 51 52 /** 53 * Constant used to indicate that the part of the text that should be 54 * retrieved is a character. 55 * 56 * @see #getAtIndex 57 * @see #getAfterIndex 58 * @see #getBeforeIndex 59 */ 60 public static final int CHARACTER = 1; 61 62 /** 63 * Constant used to indicate that the part of the text that should be 64 * retrieved is a word. 65 * 66 * @see #getAtIndex 67 * @see #getAfterIndex 68 * @see #getBeforeIndex 69 */ 70 public static final int WORD = 2; 71 72 /** 73 * Constant used to indicate that the part of the text that should be 74 * retrieved is a sentence. 75 * <p> 76 * A sentence is a string of words which expresses an assertion, a question, 77 * a command, a wish, an exclamation, or the performance of an action. In 78 * English locales, the string usually begins with a capital letter and 79 * concludes with appropriate end punctuation; such as a period, question or 80 * exclamation mark. Other locales may use different capitalization and/or 81 * punctuation. 82 * 83 * @see #getAtIndex 84 * @see #getAfterIndex 85 * @see #getBeforeIndex 86 */ 87 public static final int SENTENCE = 3; 88 89 /** 90 * Given a point in local coordinates, return the zero-based index of the 91 * character under that point. If the point is invalid, this method returns 92 * -1. 93 * 94 * @param p the point in local coordinates 95 * @return the zero-based index of the character under {@code Point p}; if 96 * point is invalid return -1. 97 */ getIndexAtPoint(Point p)98 public int getIndexAtPoint(Point p); 99 100 /** 101 * Determines the bounding box of the character at the given index into the 102 * string. The bounds are returned in local coordinates. If the index is 103 * invalid an empty rectangle is returned. 104 * 105 * @param i the index into the string 106 * @return the screen coordinates of the character's bounding box, if index 107 * is invalid return an empty rectangle. 108 */ getCharacterBounds(int i)109 public Rectangle getCharacterBounds(int i); 110 111 /** 112 * Returns the number of characters (valid indicies). 113 * 114 * @return the number of characters 115 */ getCharCount()116 public int getCharCount(); 117 118 /** 119 * Returns the zero-based offset of the caret. 120 * <p> 121 * Note: That to the right of the caret will have the same index value as 122 * the offset (the caret is between two characters). 123 * 124 * @return the zero-based offset of the caret 125 */ getCaretPosition()126 public int getCaretPosition(); 127 128 /** 129 * Returns the {@code String} at a given index. 130 * 131 * @param part the CHARACTER, WORD, or SENTENCE to retrieve 132 * @param index an index within the text 133 * @return the letter, word, or sentence 134 */ getAtIndex(int part, int index)135 public String getAtIndex(int part, int index); 136 137 /** 138 * Returns the {@code String} after a given index. 139 * 140 * @param part the CHARACTER, WORD, or SENTENCE to retrieve 141 * @param index an index within the text 142 * @return the letter, word, or sentence 143 */ getAfterIndex(int part, int index)144 public String getAfterIndex(int part, int index); 145 146 /** 147 * Returns the {@code String} before a given index. 148 * 149 * @param part the CHARACTER, WORD, or SENTENCE to retrieve 150 * @param index an index within the text 151 * @return the letter, word, or sentence 152 */ getBeforeIndex(int part, int index)153 public String getBeforeIndex(int part, int index); 154 155 /** 156 * Returns the {@code AttributeSet} for a given character at a given index. 157 * 158 * @param i the zero-based index into the text 159 * @return the {@code AttributeSet} of the character 160 */ getCharacterAttribute(int i)161 public AttributeSet getCharacterAttribute(int i); 162 163 /** 164 * Returns the start offset within the selected text. If there is no 165 * selection, but there is a caret, the start and end offsets will be the 166 * same. 167 * 168 * @return the index into the text of the start of the selection 169 */ getSelectionStart()170 public int getSelectionStart(); 171 172 /** 173 * Returns the end offset within the selected text. If there is no 174 * selection, but there is a caret, the start and end offsets will be the 175 * same. 176 * 177 * @return the index into the text of the end of the selection 178 */ getSelectionEnd()179 public int getSelectionEnd(); 180 181 /** 182 * Returns the portion of the text that is selected. 183 * 184 * @return the {@code String} portion of the text that is selected 185 */ getSelectedText()186 public String getSelectedText(); 187 } 188