001 /* Document.java --
002 Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.swing.text;
039
040 import javax.swing.event.DocumentListener;
041 import javax.swing.event.UndoableEditListener;
042
043 /**
044 * A Document is the model that backs up all text components in Swing.
045 * This interface supports different kinds of implementations, from
046 * simple plain text model up to complex styled HTML or RTF models.
047 */
048 public interface Document
049 {
050 /**
051 * The key for the property that describes the source of a document.
052 */
053 String StreamDescriptionProperty = "stream";
054
055 /**
056 * The key for the property that is the title of a document.
057 */
058 String TitleProperty = "title";
059
060 /**
061 * Adds a {@link DocumentListener} to this document.
062 *
063 * @param listener the DocumentListener to add
064 */
065 void addDocumentListener(DocumentListener listener);
066
067 /**
068 * Adds an {@link UndoableEditListener} to this document.
069 *
070 * @param listener the UndoableEditListener to add
071 */
072 void addUndoableEditListener(UndoableEditListener listener);
073
074 /**
075 * Creates a mark in the character content at the specified offset.
076 *
077 * @param offs the offset where to place the mark
078 *
079 * @return the created Position object
080 *
081 * @throws BadLocationException of the specified offset is not a valid
082 * position in the documents content
083 */
084 Position createPosition(int offs)
085 throws BadLocationException;
086
087 /**
088 * Returns the default root element. Views should be using this element
089 * unless other mechanisms for assigning views to element structure is
090 * provided.
091 *
092 * @return the default root element
093 */
094 Element getDefaultRootElement();
095
096 /**
097 * Returns the position that marks the end of the document.
098 *
099 * @return the position that marks the end of the document
100 */
101 Position getEndPosition();
102
103 /**
104 * Returns the length of the document content.
105 *
106 * @return the length of the document content
107 */
108 int getLength();
109
110 /**
111 * Returns a document property with the specified key.
112 *
113 * @param key the (non-null) key for the property to fetch
114 *
115 * @return the property for <code>key</code> or null if no such property
116 * is stored
117 */
118 Object getProperty(Object key);
119
120 /**
121 * Returns the root elements of the document content.
122 *
123 * @return the root elements of the document content
124 */
125 Element[] getRootElements();
126
127 /**
128 * Returns the position that marks the beginning of the document
129 * content.
130 *
131 * @return the start position
132 */
133 Position getStartPosition();
134
135 /**
136 * Returns the textual content starting at <code>offset</code> with
137 * a length of <code>length</code>.
138 *
139 * @param offset the beginning of the text fragment to fetch
140 * @param length the length of the text fragment to fetch
141 *
142 * @return the text fragment starting at <code>offset</code> with
143 * a length of <code>length</code>
144 *
145 * @throws BadLocationException if <code>offset</code> or <code>length</code>
146 * are no valid locations in the document content
147 */
148 String getText(int offset, int length)
149 throws BadLocationException;
150
151 /**
152 * Fetch the textual content starting at <code>offset</code> with
153 * a length of <code>length</code> and store it in <code>txt</code>.
154 *
155 * @param offset the beginning of the text fragment to fetch
156 * @param length the length of the text fragment to fetch
157 * @param txt the Segment where to store the text fragment
158 *
159 * @throws BadLocationException if <code>offset</code> or <code>length</code>
160 * are no valid locations in the document content
161 */
162 void getText(int offset, int length, Segment txt)
163 throws BadLocationException;
164
165 /**
166 * Inserts a piece of text with an AttributeSet at the specified
167 * <code>offset</code>.
168 *
169 * @param offset the location where to insert the content
170 * @param str the textual content to insert
171 * @param a the Attributes associated with the piece of text
172 *
173 * @throws BadLocationException if <code>offset</code>
174 * is not a valid location in the document content
175 */
176 void insertString(int offset, String str, AttributeSet a)
177 throws BadLocationException;
178
179 /**
180 * Sets a document property.
181 *
182 * @param key the key of the property
183 * @param value the value of the property
184 */
185 void putProperty(Object key, Object value);
186
187 /**
188 * Removes a piece of content.
189 *
190 * @param offs the location of the fragment to remove
191 * @param len the length of the fragment to remove
192 *
193 * @throws BadLocationException if <code>offs</code> or <code>len</code>
194 * are no valid locations in the document content
195 */
196 void remove(int offs, int len)
197 throws BadLocationException;
198
199 /**
200 * Removes a DocumentListener from this Document.
201 *
202 * @param listener the DocumentListener to remove
203 */
204 void removeDocumentListener(DocumentListener listener);
205
206 /**
207 * Removes an UndoableEditListener from this Document.
208 *
209 * @param listener the UndoableEditListener to remove
210 */
211 void removeUndoableEditListener(UndoableEditListener listener);
212
213 /**
214 * This allows the Document to be rendered safely. It is made sure that
215 * the Runnable can read the document without any changes while reading.
216 * The Runnable is not allowed to change the Document itself.
217 *
218 * @param r the Runnable that renders the Document
219 */
220 void render(Runnable r);
221 }