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    }