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
26package javax.accessibility;
27
28import java.awt.Point;
29import java.awt.Rectangle;
30
31import 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 */
50public 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     */
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     */
109    public Rectangle getCharacterBounds(int i);
110
111    /**
112     * Returns the number of characters (valid indicies).
113     *
114     * @return the number of characters
115     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
186    public String getSelectedText();
187}
188