001/* Document.java --
002   Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.swing.text;
039
040import javax.swing.event.DocumentListener;
041import 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 */
048public 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}