View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  package javax.swing.text;
26  
27  import javax.swing.event.*;
28  
29  /**
30   * <p>
31   * The <code>Document</code> is a container for text that serves
32   * as the model for swing text components.  The goal for this
33   * interface is to scale from very simple needs (a plain text textfield)
34   * to complex needs (an HTML or XML document, for example).
35   *
36   * <p><b><font size=+1>Content</font></b>
37   * <p>
38   * At the simplest level, text can be
39   * modeled as a linear sequence of characters. To support
40   * internationalization, the Swing text model uses
41   * <a href="http://www.unicode.org/">unicode</a> characters.
42   * The sequence of characters displayed in a text component is
43   * generally referred to as the component's <em>content</em>.
44   * <p>
45   * To refer to locations within the sequence, the coordinates
46   * used are the location between two characters.  As the diagram
47   * below shows, a location in a text document can be referred to
48   * as a position, or an offset. This position is zero-based.
49   * <p style="text-align:center"><img src="doc-files/Document-coord.gif"
50   * alt="The following text describes this graphic.">
51   * <p>
52   * In the example, if the content of a document is the
53   * sequence "The quick brown fox," as shown in the preceding diagram,
54   * the location just before the word "The" is 0, and the location after
55   * the word "The" and before the whitespace that follows it is 3.
56   * The entire sequence of characters in the sequence "The" is called a
57   * <em>range</em>.
58   * <p>The following methods give access to the character data
59   * that makes up the content.
60   * <ul>
61   * <li>{@link #getLength()}
62   * <li>{@link #getText(int, int)}
63   * <li>{@link #getText(int, int, javax.swing.text.Segment)}
64   * </ul>
65   * <p><b><font size=+1>Structure</font></b>
66   * <p>
67   * Text is rarely represented simply as featureless content. Rather,
68   * text typically has some sort of structure associated with it.
69   * Exactly what structure is modeled is up to a particular Document
70   * implementation.  It might be as simple as no structure (i.e. a
71   * simple text field), or it might be something like diagram below.
72   * <p style="text-align:center"><img src="doc-files/Document-structure.gif"
73   * alt="Diagram shows Book->Chapter->Paragraph">
74   * <p>
75   * The unit of structure (i.e. a node of the tree) is referred to
76   * by the <a href="Element.html">Element</a> interface.  Each Element
77   * can be tagged with a set of attributes.  These attributes
78   * (name/value pairs) are defined by the
79   * <a href="AttributeSet.html">AttributeSet</a> interface.
80   * <p>The following methods give access to the document structure.
81   * <ul>
82   * <li>{@link #getDefaultRootElement()}
83   * <li>{@link #getRootElements()}
84   * </ul>
85   *
86   * <p><b><font size=+1>Mutations</font></b>
87   * <p>
88   * All documents need to be able to add and remove simple text.
89   * Typically, text is inserted and removed via gestures from
90   * a keyboard or a mouse.  What effect the insertion or removal
91   * has upon the document structure is entirely up to the
92   * implementation of the document.
93   * <p>The following methods are related to mutation of the
94   * document content:
95   * <ul>
96   * <li>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)}
97   * <li>{@link #remove(int, int)}
98   * <li>{@link #createPosition(int)}
99   * </ul>
100  *
101  * <p><b><font size=+1>Notification</font></b>
102  * <p>
103  * Mutations to the <code>Document</code> must be communicated to
104  * interested observers.  The notification of change follows the event model
105  * guidelines that are specified for JavaBeans.  In the JavaBeans
106  * event model, once an event notification is dispatched, all listeners
107  * must be notified before any further mutations occur to the source
108  * of the event.  Further, order of delivery is not guaranteed.
109  * <p>
110  * Notification is provided as two separate events,
111  * <a href="../event/DocumentEvent.html">DocumentEvent</a>, and
112  * <a href="../event/UndoableEditEvent.html">UndoableEditEvent</a>.
113  * If a mutation is made to a <code>Document</code> through its api,
114  * a <code>DocumentEvent</code> will be sent to all of the registered
115  * <code>DocumentListeners</code>.  If the <code>Document</code>
116  * implementation supports undo/redo capabilities, an
117  * <code>UndoableEditEvent</code> will be sent
118  * to all of the registered <code>UndoableEditListener</code>s.
119  * If an undoable edit is undone, a <code>DocumentEvent</code> should be
120  * fired from the Document to indicate it has changed again.
121  * In this case however, there should be no <code>UndoableEditEvent</code>
122  * generated since that edit is actually the source of the change
123  * rather than a mutation to the <code>Document</code> made through its
124  * api.
125  * <p style="text-align:center"><img src="doc-files/Document-notification.gif"
126  * alt="The preceding text describes this graphic.">
127  * <p>
128  * Referring to the above diagram, suppose that the component shown
129  * on the left mutates the document object represented by the blue
130  * rectangle. The document responds by dispatching a DocumentEvent to
131  * both component views and sends an UndoableEditEvent to the listening
132  * logic, which maintains a history buffer.
133  * <p>
134  * Now suppose that the component shown on the right mutates the same
135  * document.  Again, the document dispatches a DocumentEvent to both
136  * component views and sends an UndoableEditEvent to the listening logic
137  * that is maintaining the history buffer.
138  * <p>
139  * If the history buffer is then rolled back (i.e. the last UndoableEdit
140  * undone), a DocumentEvent is sent to both views, causing both of them to
141  * reflect the undone mutation to the document (that is, the
142  * removal of the right component's mutation). If the history buffer again
143  * rolls back another change, another DocumentEvent is sent to both views,
144  * causing them to reflect the undone mutation to the document -- that is,
145  * the removal of the left component's mutation.
146  * <p>
147  * The methods related to observing mutations to the document are:
148  * <ul>
149  * <li><a href="#addDocumentListener(javax.swing.event.DocumentListener)">addDocumentListener(DocumentListener)</a>
150  * <li><a href="#removeDocumentListener(javax.swing.event.DocumentListener)">removeDocumentListener(DocumentListener)</a>
151  * <li><a href="#addUndoableEditListener(javax.swing.event.UndoableEditListener)">addUndoableEditListener(UndoableEditListener)</a>
152  * <li><a href="#removeUndoableEditListener(javax.swing.event.UndoableEditListener)">removeUndoableEditListener(UndoableEditListener)</a>
153  * </ul>
154  *
155  * <p><b><font size=+1>Properties</font></b>
156  * <p>
157  * Document implementations will generally have some set of properties
158  * associated with them at runtime.  Two well known properties are the
159  * <a href="#StreamDescriptionProperty">StreamDescriptionProperty</a>,
160  * which can be used to describe where the <code>Document</code> came from,
161  * and the <a href="#TitleProperty">TitleProperty</a>, which can be used to
162  * name the <code>Document</code>.  The methods related to the properties are:
163  * <ul>
164  * <li>{@link #getProperty(java.lang.Object)}
165  * <li>{@link #putProperty(java.lang.Object, java.lang.Object)}
166  * </ul>
167  *
168  * <p>For more information on the <code>Document</code> class, see
169  * <a href="http://java.sun.com/products/jfc/tsc">The Swing Connection</a>
170  * and most particularly the article,
171  * <a href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">
172  * The Element Interface</a>.
173  *
174  * @author  Timothy Prinzing
175  *
176  * @see javax.swing.event.DocumentEvent
177  * @see javax.swing.event.DocumentListener
178  * @see javax.swing.event.UndoableEditEvent
179  * @see javax.swing.event.UndoableEditListener
180  * @see Element
181  * @see Position
182  * @see AttributeSet
183  */
184 public interface Document {
185 
186     /**
187      * Returns number of characters of content currently
188      * in the document.
189      *
190      * @return number of characters &gt;= 0
191      */
192     public int getLength();
193 
194     /**
195      * Registers the given observer to begin receiving notifications
196      * when changes are made to the document.
197      *
198      * @param listener the observer to register
199      * @see Document#removeDocumentListener
200      */
201     public void addDocumentListener(DocumentListener listener);
202 
203     /**
204      * Unregisters the given observer from the notification list
205      * so it will no longer receive change updates.
206      *
207      * @param listener the observer to register
208      * @see Document#addDocumentListener
209      */
210     public void removeDocumentListener(DocumentListener listener);
211 
212     /**
213      * Registers the given observer to begin receiving notifications
214      * when undoable edits are made to the document.
215      *
216      * @param listener the observer to register
217      * @see javax.swing.event.UndoableEditEvent
218      */
219     public void addUndoableEditListener(UndoableEditListener listener);
220 
221     /**
222      * Unregisters the given observer from the notification list
223      * so it will no longer receive updates.
224      *
225      * @param listener the observer to register
226      * @see javax.swing.event.UndoableEditEvent
227      */
228     public void removeUndoableEditListener(UndoableEditListener listener);
229 
230     /**
231      * Gets the properties associated with the document.
232      *
233      * @param key a non-<code>null</code> property key
234      * @return the properties
235      * @see #putProperty(Object, Object)
236      */
237     public Object getProperty(Object key);
238 
239     /**
240      * Associates a property with the document.  Two standard
241      * property keys provided are: <a href="#StreamDescriptionProperty">
242      * <code>StreamDescriptionProperty</code></a> and
243      * <a href="#TitleProperty"><code>TitleProperty</code></a>.
244      * Other properties, such as author, may also be defined.
245      *
246      * @param key the non-<code>null</code> property key
247      * @param value the property value
248      * @see #getProperty(Object)
249      */
250     public void putProperty(Object key, Object value);
251 
252     /**
253      * Removes a portion of the content of the document.
254      * This will cause a DocumentEvent of type
255      * DocumentEvent.EventType.REMOVE to be sent to the
256      * registered DocumentListeners, unless an exception
257      * is thrown.  The notification will be sent to the
258      * listeners by calling the removeUpdate method on the
259      * DocumentListeners.
260      * <p>
261      * To ensure reasonable behavior in the face
262      * of concurrency, the event is dispatched after the
263      * mutation has occurred. This means that by the time a
264      * notification of removal is dispatched, the document
265      * has already been updated and any marks created by
266      * <code>createPosition</code> have already changed.
267      * For a removal, the end of the removal range is collapsed
268      * down to the start of the range, and any marks in the removal
269      * range are collapsed down to the start of the range.
270      * <p style="text-align:center"><img src="doc-files/Document-remove.gif"
271      *  alt="Diagram shows removal of 'quick' from 'The quick brown fox.'">
272      * <p>
273      * If the Document structure changed as result of the removal,
274      * the details of what Elements were inserted and removed in
275      * response to the change will also be contained in the generated
276      * DocumentEvent. It is up to the implementation of a Document
277      * to decide how the structure should change in response to a
278      * remove.
279      * <p>
280      * If the Document supports undo/redo, an UndoableEditEvent will
281      * also be generated.
282      *
283      * @param offs  the offset from the beginning &gt;= 0
284      * @param len   the number of characters to remove &gt;= 0
285      * @exception BadLocationException  some portion of the removal range
286      *   was not a valid part of the document.  The location in the exception
287      *   is the first bad position encountered.
288      * @see javax.swing.event.DocumentEvent
289      * @see javax.swing.event.DocumentListener
290      * @see javax.swing.event.UndoableEditEvent
291      * @see javax.swing.event.UndoableEditListener
292      */
293     public void remove(int offs, int len) throws BadLocationException;
294 
295     /**
296      * Inserts a string of content.  This will cause a DocumentEvent
297      * of type DocumentEvent.EventType.INSERT to be sent to the
298      * registered DocumentListers, unless an exception is thrown.
299      * The DocumentEvent will be delivered by calling the
300      * insertUpdate method on the DocumentListener.
301      * The offset and length of the generated DocumentEvent
302      * will indicate what change was actually made to the Document.
303      * <p style="text-align:center"><img src="doc-files/Document-insert.gif"
304      *  alt="Diagram shows insertion of 'quick' in 'The quick brown fox'">
305      * <p>
306      * If the Document structure changed as result of the insertion,
307      * the details of what Elements were inserted and removed in
308      * response to the change will also be contained in the generated
309      * DocumentEvent.  It is up to the implementation of a Document
310      * to decide how the structure should change in response to an
311      * insertion.
312      * <p>
313      * If the Document supports undo/redo, an UndoableEditEvent will
314      * also be generated.
315      *
316      * @param offset  the offset into the document to insert the content &gt;= 0.
317      *    All positions that track change at or after the given location
318      *    will move.
319      * @param str    the string to insert
320      * @param a      the attributes to associate with the inserted
321      *   content.  This may be null if there are no attributes.
322      * @exception BadLocationException  the given insert position is not a valid
323      * position within the document
324      * @see javax.swing.event.DocumentEvent
325      * @see javax.swing.event.DocumentListener
326      * @see javax.swing.event.UndoableEditEvent
327      * @see javax.swing.event.UndoableEditListener
328      */
329     public void insertString(int offset, String str, AttributeSet a) throws BadLocationException;
330 
331     /**
332      * Fetches the text contained within the given portion
333      * of the document.
334      *
335      * @param offset  the offset into the document representing the desired
336      *   start of the text &gt;= 0
337      * @param length  the length of the desired string &gt;= 0
338      * @return the text, in a String of length &gt;= 0
339      * @exception BadLocationException  some portion of the given range
340      *   was not a valid part of the document.  The location in the exception
341      *   is the first bad position encountered.
342      */
343     public String getText(int offset, int length) throws BadLocationException;
344 
345     /**
346      * Fetches the text contained within the given portion
347      * of the document.
348      * <p>
349      * If the partialReturn property on the txt parameter is false, the
350      * data returned in the Segment will be the entire length requested and
351      * may or may not be a copy depending upon how the data was stored.
352      * If the partialReturn property is true, only the amount of text that
353      * can be returned without creating a copy is returned.  Using partial
354      * returns will give better performance for situations where large
355      * parts of the document are being scanned.  The following is an example
356      * of using the partial return to access the entire document:
357      *
358      * <pre><code>
359      *
360      * &nbsp; int nleft = doc.getDocumentLength();
361      * &nbsp; Segment text = new Segment();
362      * &nbsp; int offs = 0;
363      * &nbsp; text.setPartialReturn(true);
364      * &nbsp; while (nleft &gt; 0) {
365      * &nbsp;     doc.getText(offs, nleft, text);
366      * &nbsp;     // do someting with text
367      * &nbsp;     nleft -= text.count;
368      * &nbsp;     offs += text.count;
369      * &nbsp; }
370      *
371      * </code></pre>
372      *
373      * @param offset  the offset into the document representing the desired
374      *   start of the text &gt;= 0
375      * @param length  the length of the desired string &gt;= 0
376      * @param txt the Segment object to return the text in
377      *
378      * @exception BadLocationException  Some portion of the given range
379      *   was not a valid part of the document.  The location in the exception
380      *   is the first bad position encountered.
381      */
382     public void getText(int offset, int length, Segment txt) throws BadLocationException;
383 
384     /**
385      * Returns a position that represents the start of the document.  The
386      * position returned can be counted on to track change and stay
387      * located at the beginning of the document.
388      *
389      * @return the position
390      */
391     public Position getStartPosition();
392 
393     /**
394      * Returns a position that represents the end of the document.  The
395      * position returned can be counted on to track change and stay
396      * located at the end of the document.
397      *
398      * @return the position
399      */
400     public Position getEndPosition();
401 
402     /**
403      * This method allows an application to mark a place in
404      * a sequence of character content. This mark can then be
405      * used to tracks change as insertions and removals are made
406      * in the content. The policy is that insertions always
407      * occur prior to the current position (the most common case)
408      * unless the insertion location is zero, in which case the
409      * insertion is forced to a position that follows the
410      * original position.
411      *
412      * @param offs  the offset from the start of the document &gt;= 0
413      * @return the position
414      * @exception BadLocationException  if the given position does not
415      *   represent a valid location in the associated document
416      */
417     public Position createPosition(int offs) throws BadLocationException;
418 
419     /**
420      * Returns all of the root elements that are defined.
421      * <p>
422      * Typically there will be only one document structure, but the interface
423      * supports building an arbitrary number of structural projections over the
424      * text data. The document can have multiple root elements to support
425      * multiple document structures.  Some examples might be:
426      * </p>
427      * <ul>
428      * <li>Text direction.
429      * <li>Lexical token streams.
430      * <li>Parse trees.
431      * <li>Conversions to formats other than the native format.
432      * <li>Modification specifications.
433      * <li>Annotations.
434      * </ul>
435      *
436      * @return the root element
437      */
438     public Element[] getRootElements();
439 
440     /**
441      * Returns the root element that views should be based upon,
442      * unless some other mechanism for assigning views to element
443      * structures is provided.
444      *
445      * @return the root element
446      */
447     public Element getDefaultRootElement();
448 
449     /**
450      * Allows the model to be safely rendered in the presence
451      * of concurrency, if the model supports being updated asynchronously.
452      * The given runnable will be executed in a way that allows it
453      * to safely read the model with no changes while the runnable
454      * is being executed.  The runnable itself may <em>not</em>
455      * make any mutations.
456      *
457      * @param r a <code>Runnable</code> used to render the model
458      */
459     public void render(Runnable r);
460 
461     /**
462      * The property name for the description of the stream
463      * used to initialize the document.  This should be used
464      * if the document was initialized from a stream and
465      * anything is known about the stream.
466      */
467     public static final String StreamDescriptionProperty = "stream";
468 
469     /**
470      * The property name for the title of the document, if
471      * there is one.
472      */
473     public static final String TitleProperty = "title";
474 
475 
476 }