1/*
2 * Copyright (c) 2003, 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.Rectangle;
29
30/**
31 * The {@code AccessibleExtendedText} interface contains additional methods not
32 * provided by the {@code AccessibleText} interface.
33 * <p>
34 * Applications can determine if an object supports the
35 * {@code AccessibleExtendedText} interface by first obtaining its
36 * {@code AccessibleContext} (see {@link Accessible}) and then calling the
37 * {@link AccessibleContext#getAccessibleText} method of
38 * {@code AccessibleContext}. If the return value is an instance of
39 * {@code AccessibleExtendedText}, the object supports this interface.
40 *
41 * @author Peter Korn
42 * @author Lynn Monsanto
43 * @see Accessible
44 * @see Accessible#getAccessibleContext
45 * @see AccessibleContext
46 * @see AccessibleContext#getAccessibleText
47 * @since 1.5
48 */
49public interface AccessibleExtendedText {
50
51    /**
52     * Constant used to indicate that the part of the text that should be
53     * retrieved is a line of text.
54     *
55     * @see AccessibleText#getAtIndex
56     * @see AccessibleText#getAfterIndex
57     * @see AccessibleText#getBeforeIndex
58     */
59    public static final int LINE = 4; // BugID: 4849720
60
61    /**
62     * Constant used to indicate that the part of the text that should be
63     * retrieved is contiguous text with the same text attributes.
64     *
65     * @see AccessibleText#getAtIndex
66     * @see AccessibleText#getAfterIndex
67     * @see AccessibleText#getBeforeIndex
68     */
69    public static final int ATTRIBUTE_RUN = 5; // BugID: 4849720
70
71    /**
72     * Returns the text between two indices.
73     *
74     * @param  startIndex the start index in the text
75     * @param  endIndex the end index in the text
76     * @return the text string if the indices are valid. Otherwise, {@code null}
77     *         is returned.
78     */
79    public String getTextRange(int startIndex, int endIndex);
80
81    /**
82     * Returns the {@code AccessibleTextSequence} at a given index.
83     *
84     * @param  part the {@code CHARACTER}, {@code WORD}, {@code SENTENCE},
85     *         {@code LINE} or {@code ATTRIBUTE_RUN} to retrieve
86     * @param  index an index within the text
87     * @return an {@code AccessibleTextSequence} specifying the text if
88     *         {@code part} and {@code index} are valid. Otherwise, {@code null}
89     *         is returned.
90     * @see AccessibleText#CHARACTER
91     * @see AccessibleText#WORD
92     * @see AccessibleText#SENTENCE
93     */
94    public AccessibleTextSequence getTextSequenceAt(int part, int index);
95
96    /**
97     * Returns the {@code AccessibleTextSequence} after a given index.
98     *
99     * @param  part the {@code CHARACTER}, {@code WORD}, {@code SENTENCE},
100     *         {@code LINE} or {@code ATTRIBUTE_RUN} to retrieve
101     * @param  index an index within the text
102     * @return an {@code AccessibleTextSequence} specifying the text if
103     *         {@code part} and {@code index} are valid. Otherwise, {@code null}
104     *         is returned.
105     * @see AccessibleText#CHARACTER
106     * @see AccessibleText#WORD
107     * @see AccessibleText#SENTENCE
108     */
109    public AccessibleTextSequence getTextSequenceAfter(int part, int index);
110
111    /**
112     * Returns the {@code AccessibleTextSequence} before a given index.
113     *
114     * @param  part the {@code CHARACTER}, {@code WORD}, {@code SENTENCE},
115     *         {@code LINE} or {@code ATTRIBUTE_RUN} to retrieve
116     * @param  index an index within the text
117     * @return an {@code AccessibleTextSequence} specifying the text if
118     *         {@code part} and {@code index} are valid. Otherwise, {@code null}
119     *         is returned.
120     * @see AccessibleText#CHARACTER
121     * @see AccessibleText#WORD
122     * @see AccessibleText#SENTENCE
123     */
124    public AccessibleTextSequence getTextSequenceBefore(int part, int index);
125
126    /**
127     * Returns the bounding rectangle of the text between two indices.
128     *
129     * @param  startIndex the start index in the text
130     * @param  endIndex the end index in the text
131     * @return the bounding rectangle of the text if the indices are valid.
132     *         Otherwise, {@code null} is returned.
133     */
134    public Rectangle getTextBounds(int startIndex, int endIndex);
135}
136