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 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 */
25public interface Editable
26extends 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.  As a special case, the cursor
44     * position is preserved even when the entire range where it is
45     * located is replaced.
46     * @return  a reference to this object.
47     */
48    public Editable replace(int st, int en, CharSequence source, int start, int end);
49
50    /**
51     * Convenience for replace(st, en, text, 0, text.length())
52     * @see #replace(int, int, CharSequence, int, int)
53     */
54    public Editable replace(int st, int en, CharSequence text);
55
56    /**
57     * Convenience for replace(where, where, text, start, end)
58     * @see #replace(int, int, CharSequence, int, int)
59     */
60    public Editable insert(int where, CharSequence text, int start, int end);
61
62    /**
63     * Convenience for replace(where, where, text, 0, text.length());
64     * @see #replace(int, int, CharSequence, int, int)
65     */
66    public Editable insert(int where, CharSequence text);
67
68    /**
69     * Convenience for replace(st, en, "", 0, 0)
70     * @see #replace(int, int, CharSequence, int, int)
71     */
72    public Editable delete(int st, int en);
73
74    /**
75     * Convenience for replace(length(), length(), text, 0, text.length())
76     * @see #replace(int, int, CharSequence, int, int)
77     */
78    public Editable append(CharSequence text);
79
80    /**
81     * Convenience for replace(length(), length(), text, start, end)
82     * @see #replace(int, int, CharSequence, int, int)
83     */
84    public Editable append(CharSequence text, int start, int end);
85
86    /**
87     * Convenience for append(String.valueOf(text)).
88     * @see #replace(int, int, CharSequence, int, int)
89     */
90    public Editable append(char text);
91
92    /**
93     * Convenience for replace(0, length(), "", 0, 0)
94     * @see #replace(int, int, CharSequence, int, int)
95     * Note that this clears the text, not the spans;
96     * use {@link #clearSpans} if you need that.
97     */
98    public void clear();
99
100    /**
101     * Removes all spans from the Editable, as if by calling
102     * {@link #removeSpan} on each of them.
103     */
104    public void clearSpans();
105
106    /**
107     * Sets the series of filters that will be called in succession
108     * whenever the text of this Editable is changed, each of which has
109     * the opportunity to limit or transform the text that is being inserted.
110     */
111    public void setFilters(InputFilter[] filters);
112
113    /**
114     * Returns the array of input filters that are currently applied
115     * to changes to this Editable.
116     */
117    public InputFilter[] getFilters();
118
119    /**
120     * Factory used by TextView to create new Editables.  You can subclass
121     * it to provide something other than SpannableStringBuilder.
122     */
123    public static class Factory {
124        private static Editable.Factory sInstance = new Editable.Factory();
125
126        /**
127         * Returns the standard Editable Factory.
128         */
129        public static Editable.Factory getInstance() {
130            return sInstance;
131        }
132
133        /**
134         * Returns a new SpannedStringBuilder from the specified
135         * CharSequence.  You can override this to provide
136         * a different kind of Spanned.
137         */
138        public Editable newEditable(CharSequence source) {
139            return new SpannableStringBuilder(source);
140        }
141    }
142}
143