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 
17 package android.text;
18 
19 /**
20  * This is the interface for text whose content and markup
21  * can be changed (as opposed
22  * to immutable text like Strings).  If you make a {@link DynamicLayout}
23  * of an Editable, the layout will be reflowed as the text is changed.
24  */
25 public interface Editable
26 extends CharSequence, GetChars, Spannable, Appendable
27 {
28     /**
29      * Replaces the specified range (<code>st&hellip;en</code>) of text in this
30      * Editable with a copy of the slice <code>start&hellip;end</code> from
31      * <code>source</code>.  The destination slice may be empty, in which case
32      * the operation is an insertion, or the source slice may be empty,
33      * in which case the operation is a deletion.
34      * <p>
35      * Before the change is committed, each filter that was set with
36      * {@link #setFilters} is given the opportunity to modify the
37      * <code>source</code> text.
38      * <p>
39      * If <code>source</code>
40      * is Spanned, the spans from it are preserved into the Editable.
41      * Existing spans within the Editable that entirely cover the replaced
42      * range are retained, but any that were strictly within the range
43      * that was replaced are removed. If the <code>source</code> contains a span
44      * with {@link Spanned#SPAN_PARAGRAPH} flag, and it does not satisfy the
45      * paragraph boundary constraint, it is not retained. As a special case, the
46      * cursor position is preserved even when the entire range where it is located
47      * is replaced.
48      * @return  a reference to this object.
49      *
50      * @see Spanned#SPAN_PARAGRAPH
51      */
replace(int st, int en, CharSequence source, int start, int end)52     public Editable replace(int st, int en, CharSequence source, int start, int end);
53 
54     /**
55      * Convenience for replace(st, en, text, 0, text.length())
56      * @see #replace(int, int, CharSequence, int, int)
57      */
replace(int st, int en, CharSequence text)58     public Editable replace(int st, int en, CharSequence text);
59 
60     /**
61      * Convenience for replace(where, where, text, start, end)
62      * @see #replace(int, int, CharSequence, int, int)
63      */
insert(int where, CharSequence text, int start, int end)64     public Editable insert(int where, CharSequence text, int start, int end);
65 
66     /**
67      * Convenience for replace(where, where, text, 0, text.length());
68      * @see #replace(int, int, CharSequence, int, int)
69      */
insert(int where, CharSequence text)70     public Editable insert(int where, CharSequence text);
71 
72     /**
73      * Convenience for replace(st, en, "", 0, 0)
74      * @see #replace(int, int, CharSequence, int, int)
75      */
delete(int st, int en)76     public Editable delete(int st, int en);
77 
78     /**
79      * Convenience for replace(length(), length(), text, 0, text.length())
80      * @see #replace(int, int, CharSequence, int, int)
81      */
append(CharSequence text)82     public Editable append(CharSequence text);
83 
84     /**
85      * Convenience for replace(length(), length(), text, start, end)
86      * @see #replace(int, int, CharSequence, int, int)
87      */
append(CharSequence text, int start, int end)88     public Editable append(CharSequence text, int start, int end);
89 
90     /**
91      * Convenience for append(String.valueOf(text)).
92      * @see #replace(int, int, CharSequence, int, int)
93      */
append(char text)94     public Editable append(char text);
95 
96     /**
97      * Convenience for replace(0, length(), "", 0, 0).
98      * Note that this clears the text, not the spans;
99      * use {@link #clearSpans} if you need that.
100      * @see #replace(int, int, CharSequence, int, int)
101      */
clear()102     public void clear();
103 
104     /**
105      * Removes all spans from the Editable, as if by calling
106      * {@link #removeSpan} on each of them.
107      */
clearSpans()108     public void clearSpans();
109 
110     /**
111      * Sets the series of filters that will be called in succession
112      * whenever the text of this Editable is changed, each of which has
113      * the opportunity to limit or transform the text that is being inserted.
114      */
setFilters(InputFilter[] filters)115     public void setFilters(InputFilter[] filters);
116 
117     /**
118      * Returns the array of input filters that are currently applied
119      * to changes to this Editable.
120      */
getFilters()121     public InputFilter[] getFilters();
122 
123     /**
124      * Factory used by TextView to create new {@link Editable Editables}. You can subclass
125      * it to provide something other than {@link SpannableStringBuilder}.
126      *
127      * @see android.widget.TextView#setEditableFactory(Factory)
128      */
129     public static class Factory {
130         private static Editable.Factory sInstance = new Editable.Factory();
131 
132         /**
133          * Returns the standard Editable Factory.
134          */
getInstance()135         public static Editable.Factory getInstance() {
136             return sInstance;
137         }
138 
139         /**
140          * Returns a new SpannedStringBuilder from the specified
141          * CharSequence.  You can override this to provide
142          * a different kind of Spanned.
143          */
newEditable(CharSequence source)144         public Editable newEditable(CharSequence source) {
145             return new SpannableStringBuilder(source);
146         }
147     }
148 }
149