Document


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