< prev index next >

src/java.desktop/share/classes/javax/swing/text/Document.java

Print this page




  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>Content</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>


  83  * <li>{@link #getRootElements()}
  84  * </ul>
  85  *
  86  * <p><b>Mutations</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>Notification</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>Properties</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.


 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


 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 }


  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} 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>Content</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>


  83  * <li>{@link #getRootElements()}
  84  * </ul>
  85  *
  86  * <p><b>Mutations</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>Notification</b>
 102  * <p>
 103  * Mutations to the {@code Document} 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} through its api,
 114  * a {@code DocumentEvent} will be sent to all of the registered
 115  * {@code DocumentListeners}.  If the {@code Document}
 116  * implementation supports undo/redo capabilities, an
 117  * {@code UndoableEditEvent} will be sent
 118  * to all of the registered {@code UndoableEditListener}s.
 119  * If an undoable edit is undone, a {@code DocumentEvent} should be
 120  * fired from the Document to indicate it has changed again.
 121  * In this case however, there should be no {@code UndoableEditEvent}
 122  * generated since that edit is actually the source of the change
 123  * rather than a mutation to the {@code Document} 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>Properties</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} came from,
 161  * and the <a href="#TitleProperty">TitleProperty</a>, which can be used to
 162  * name the {@code Document}.  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} 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.


 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} 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}</a> and
 243      * <a href="#TitleProperty">{@code TitleProperty}</a>.
 244      * Other properties, such as author, may also be defined.
 245      *
 246      * @param key the non-{@code null} 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} 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


 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} 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 }
< prev index next >