Spanned.java revision 26b62d432101084c832f5587798cfd24a4ed9c59 
1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.text;
18
19/**
20 * This is the interface for text that has markup objects attached to
21 * ranges of it.  Not all text classes have mutable markup or text;
22 * see {@link Spannable} for mutable markup and {@link Editable} for
23 * mutable text.
24 */
25public interface Spanned
26extends CharSequence
27{
28    /**
29     * Bitmask of bits that are relevent for controlling point/mark behavior
30     * of spans.
31     *
32     * MARK and POINT are conceptually located <i>between</i> two adjacent characters.
33     * A MARK is "attached" to the character on the left hand side, while a POINT
34     * tends to stick to the character on the right hand side.
35     */
36    public static final int SPAN_POINT_MARK_MASK = 0x33;
37
38    /**
39     * 0-length spans with type SPAN_MARK_MARK behave like text marks:
40     * they remain at their original offset when text is inserted
41     * at that offset. Conceptually, the text is added after the mark.
42     */
43    public static final int SPAN_MARK_MARK =   0x11;
44    /**
45     * SPAN_MARK_POINT is a synonym for {@link #SPAN_INCLUSIVE_INCLUSIVE}.
46     */
47    public static final int SPAN_MARK_POINT =  0x12;
48    /**
49     * SPAN_POINT_MARK is a synonym for {@link #SPAN_EXCLUSIVE_EXCLUSIVE}.
50     */
51    public static final int SPAN_POINT_MARK =  0x21;
52
53    /**
54     * 0-length spans with type SPAN_POINT_POINT behave like cursors:
55     * they are pushed forward by the length of the insertion when text
56     * is inserted at their offset.
57     * The text is conceptually inserted before the point.
58     */
59    public static final int SPAN_POINT_POINT = 0x22;
60
61    /**
62     * SPAN_PARAGRAPH behaves like SPAN_INCLUSIVE_EXCLUSIVE
63     * (SPAN_MARK_MARK), except that if either end of the span is
64     * at the end of the buffer, that end behaves like _POINT
65     * instead (so SPAN_INCLUSIVE_INCLUSIVE if it starts in the
66     * middle and ends at the end, or SPAN_EXCLUSIVE_INCLUSIVE
67     * if it both starts and ends at the end).
68     * <p>
69     * Its endpoints must be the start or end of the buffer or
70     * immediately after a \n character, and if the \n
71     * that anchors it is deleted, the endpoint is pulled to the
72     * next \n that follows in the buffer (or to the end of
73     * the buffer).
74     */
75    public static final int SPAN_PARAGRAPH =   0x33;
76
77    /**
78     * Non-0-length spans of type SPAN_INCLUSIVE_EXCLUSIVE expand
79     * to include text inserted at their starting point but not at their
80     * ending point.  When 0-length, they behave like marks.
81     */
82    public static final int SPAN_INCLUSIVE_EXCLUSIVE = SPAN_MARK_MARK;
83
84    /**
85     * Spans of type SPAN_INCLUSIVE_INCLUSIVE expand
86     * to include text inserted at either their starting or ending point.
87     */
88    public static final int SPAN_INCLUSIVE_INCLUSIVE = SPAN_MARK_POINT;
89
90    /**
91     * Spans of type SPAN_EXCLUSIVE_EXCLUSIVE do not expand
92     * to include text inserted at either their starting or ending point.
93     * They can never have a length of 0 and are automatically removed
94     * from the buffer if all the text they cover is removed.
95     */
96    public static final int SPAN_EXCLUSIVE_EXCLUSIVE = SPAN_POINT_MARK;
97
98    /**
99     * Non-0-length spans of type SPAN_EXCLUSIVE_INCLUSIVE expand
100     * to include text inserted at their ending point but not at their
101     * starting point.  When 0-length, they behave like points.
102     */
103    public static final int SPAN_EXCLUSIVE_INCLUSIVE = SPAN_POINT_POINT;
104
105    /**
106     * This flag is set on spans that are being used to apply temporary
107     * styling information on the composing text of an input method, so that
108     * they can be found and removed when the composing text is being
109     * replaced.
110     */
111    public static final int SPAN_COMPOSING = 0x100;
112
113    /**
114     * This flag will be set for intermediate span changes, meaning there
115     * is guaranteed to be another change following it.  Typically it is
116     * used for {@link Selection} which automatically uses this with the first
117     * offset it sets when updating the selection.
118     */
119    public static final int SPAN_INTERMEDIATE = 0x200;
120
121    /**
122     * The bits numbered SPAN_USER_SHIFT and above are available
123     * for callers to use to store scalar data associated with their
124     * span object.
125     */
126    public static final int SPAN_USER_SHIFT = 24;
127    /**
128     * The bits specified by the SPAN_USER bitfield are available
129     * for callers to use to store scalar data associated with their
130     * span object.
131     */
132    public static final int SPAN_USER = 0xFFFFFFFF << SPAN_USER_SHIFT;
133
134    /**
135     * The bits numbered just above SPAN_PRIORITY_SHIFT determine the order
136     * of change notifications -- higher numbers go first.  You probably
137     * don't need to set this; it is used so that when text changes, the
138     * text layout gets the chance to update itself before any other
139     * callbacks can inquire about the layout of the text.
140     */
141    public static final int SPAN_PRIORITY_SHIFT = 16;
142    /**
143     * The bits specified by the SPAN_PRIORITY bitmap determine the order
144     * of change notifications -- higher numbers go first.  You probably
145     * don't need to set this; it is used so that when text changes, the
146     * text layout gets the chance to update itself before any other
147     * callbacks can inquire about the layout of the text.
148     */
149    public static final int SPAN_PRIORITY = 0xFF << SPAN_PRIORITY_SHIFT;
150
151    /**
152     * Return an array of the markup objects attached to the specified
153     * slice of this CharSequence and whose type is the specified type
154     * or a subclass of it.  Specify Object.class for the type if you
155     * want all the objects regardless of type.
156     */
157    public <T> T[] getSpans(int start, int end, Class<T> type);
158
159    /**
160     * Return the beginning of the range of text to which the specified
161     * markup object is attached, or -1 if the object is not attached.
162     */
163    public int getSpanStart(Object tag);
164
165    /**
166     * Return the end of the range of text to which the specified
167     * markup object is attached, or -1 if the object is not attached.
168     */
169    public int getSpanEnd(Object tag);
170
171    /**
172     * Return the flags that were specified when {@link Spannable#setSpan} was
173     * used to attach the specified markup object, or 0 if the specified
174     * object has not been attached.
175     */
176    public int getSpanFlags(Object tag);
177
178    /**
179     * Return the first offset greater than or equal to <code>start</code>
180     * where a markup object of class <code>type</code> begins or ends,
181     * or <code>limit</code> if there are no starts or ends greater than or
182     * equal to <code>start</code> but less than <code>limit</code>.  Specify
183     * <code>null</code> or Object.class for the type if you want every
184     * transition regardless of type.
185     */
186    public int nextSpanTransition(int start, int limit, Class type);
187}
188