--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/swing/text/Document.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,476 @@
+/*
+ * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+package javax.swing.text;
+
+import javax.swing.event.*;
+
+/**
+ * <p>
+ * The <code>Document</code> is a container for text that serves
+ * as the model for swing text components. The goal for this
+ * interface is to scale from very simple needs (a plain text textfield)
+ * to complex needs (an HTML or XML document, for example).
+ *
+ * <p><b><font size=+1>Content</font></b>
+ * <p>
+ * At the simplest level, text can be
+ * modeled as a linear sequence of characters. To support
+ * internationalization, the Swing text model uses
+ * <a href="http://www.unicode.org/">unicode</a> characters.
+ * The sequence of characters displayed in a text component is
+ * generally referred to as the component's <em>content</em>.
+ * <p>
+ * To refer to locations within the sequence, the coordinates
+ * used are the location between two characters. As the diagram
+ * below shows, a location in a text document can be referred to
+ * as a position, or an offset. This position is zero-based.
+ * <p align=center><img src="doc-files/Document-coord.gif"
+ * alt="The following text describes this graphic.">
+ * <p>
+ * In the example, if the content of a document is the
+ * sequence "The quick brown fox," as shown in the preceding diagram,
+ * the location just before the word "The" is 0, and the location after
+ * the word "The" and before the whitespace that follows it is 3.
+ * The entire sequence of characters in the sequence "The" is called a
+ * <em>range</em>.
+ * <p>The following methods give access to the character data
+ * that makes up the content.
+ * <ul>
+ * <li><a href="#getLength()">getLength()</a>
+ * <li><a href="#getText(int, int)">getText(int, int)</a>
+ * <li><a href="#getText(int, int, javax.swing.text.Segment)">getText(int, int, Segment)</a>
+ * </ul>
+ * <p><b><font size=+1>Structure</font></b>
+ * <p>
+ * Text is rarely represented simply as featureless content. Rather,
+ * text typically has some sort of structure associated with it.
+ * Exactly what structure is modeled is up to a particular Document
+ * implementation. It might be as simple as no structure (i.e. a
+ * simple text field), or it might be something like diagram below.
+ * <p align=center><img src="doc-files/Document-structure.gif"
+ * alt="Diagram shows Book->Chapter->Paragraph">
+ * <p>
+ * The unit of structure (i.e. a node of the tree) is referred to
+ * by the <a href="Element.html">Element</a> interface. Each Element
+ * can be tagged with a set of attributes. These attributes
+ * (name/value pairs) are defined by the
+ * <a href="AttributeSet.html">AttributeSet</a> interface.
+ * <p>The following methods give access to the document structure.
+ * <ul>
+ * <li><a href="#getDefaultRootElement()">getDefaultRootElement</a>
+ * <li><a href="#getRootElements()">getRootElements</a>
+ * </ul>
+ *
+ * <p><b><font size=+1>Mutations</font></b>
+ * <p>
+ * All documents need to be able to add and remove simple text.
+ * Typically, text is inserted and removed via gestures from
+ * a keyboard or a mouse. What effect the insertion or removal
+ * has upon the document structure is entirely up to the
+ * implementation of the document.
+ * <p>The following methods are related to mutation of the
+ * document content:
+ * <ul>
+ * <li><a href="#insertString(int, java.lang.String, javax.swing.text.AttributeSet)">insertString(int, String, AttributeSet)</a>
+ * <li><a href="#remove(int, int)">remove(int, int)</a>
+ * <li><a href="#createPosition(int)">createPosition(int)</a>
+ * </ul>
+ *
+ * <p><b><font size=+1>Notification</font></b>
+ * <p>
+ * Mutations to the <code>Document</code> must be communicated to
+ * interested observers. The notification of change follows the event model
+ * guidelines that are specified for JavaBeans. In the JavaBeans
+ * event model, once an event notification is dispatched, all listeners
+ * must be notified before any further mutations occur to the source
+ * of the event. Further, order of delivery is not guaranteed.
+ * <p>
+ * Notification is provided as two separate events,
+ * <a href="../event/DocumentEvent.html">DocumentEvent</a>, and
+ * <a href="../event/UndoableEditEvent.html">UndoableEditEvent</a>.
+ * If a mutation is made to a <code>Document</code> through its api,
+ * a <code>DocumentEvent</code> will be sent to all of the registered
+ * <code>DocumentListeners</code>. If the <code>Document</code>
+ * implementation supports undo/redo capabilities, an
+ * <code>UndoableEditEvent</code> will be sent
+ * to all of the registered <code>UndoableEditListener</code>s.
+ * If an undoable edit is undone, a <code>DocumentEvent</code> should be
+ * fired from the Document to indicate it has changed again.
+ * In this case however, there should be no <code>UndoableEditEvent</code>
+ * generated since that edit is actually the source of the change
+ * rather than a mutation to the <code>Document</code> made through its
+ * api.
+ * <p align=center><img src="doc-files/Document-notification.gif"
+ * alt="The preceeding text describes this graphic.">
+ * <p>
+ * Referring to the above diagram, suppose that the component shown
+ * on the left mutates the document object represented by the blue
+ * rectangle. The document responds by dispatching a DocumentEvent to
+ * both component views and sends an UndoableEditEvent to the listening
+ * logic, which maintains a history buffer.
+ * <p>
+ * Now suppose that the component shown on the right mutates the same
+ * document. Again, the document dispatches a DocumentEvent to both
+ * component views and sends an UndoableEditEvent to the listening logic
+ * that is maintaining the history buffer.
+ * <p>
+ * If the history buffer is then rolled back (i.e. the last UndoableEdit
+ * undone), a DocumentEvent is sent to both views, causing both of them to
+ * reflect the undone mutation to the document (that is, the
+ * removal of the right component's mutation). If the history buffer again
+ * rolls back another change, another DocumentEvent is sent to both views,
+ * causing them to reflect the undone mutation to the document -- that is,
+ * the removal of the left component's mutation.
+ * <p>
+ * The methods related to observing mutations to the document are:
+ * <ul>
+ * <li><a href="#addDocumentListener(javax.swing.event.DocumentListener)">addDocumentListener(DocumentListener)</a>
+ * <li><a href="#removeDocumentListener(javax.swing.event.DocumentListener)">removeDocumentListener(DocumentListener)</a>
+ * <li><a href="#addUndoableEditListener(javax.swing.event.UndoableEditListener)">addUndoableEditListener(UndoableEditListener)</a>
+ * <li><a href="#removeUndoableEditListener(javax.swing.event.UndoableEditListener)">removeUndoableEditListener(UndoableEditListener)</a>
+ * </ul>
+ *
+ * <p><b><font size=+1>Properties</font></b>
+ * <p>
+ * Document implementations will generally have some set of properties
+ * associated with them at runtime. Two well known properties are the
+ * <a href="#StreamDescriptionProperty">StreamDescriptionProperty</a>,
+ * which can be used to describe where the <code>Document</code> came from,
+ * and the <a href="#TitleProperty">TitleProperty</a>, which can be used to
+ * name the <code>Document</code>. The methods related to the properties are:
+ * <ul>
+ * <li><a href="#getProperty(java.lang.Object)">getProperty(Object)</a>
+ * <li><a href="#putProperty(java.lang.Object, java.lang.Object)">putProperty(Object, Object)</a>
+ * </ul>
+ *
+ * <p>For more information on the <code>Document</code> class, see
+ * <a href="http://java.sun.com/products/jfc/tsc">The Swing Connection</a>
+ * and most particularly the article,
+ * <a href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">
+ * The Element Interface</a>.
+ *
+ * @author Timothy Prinzing
+ *
+ * @see javax.swing.event.DocumentEvent
+ * @see javax.swing.event.DocumentListener
+ * @see javax.swing.event.UndoableEditEvent
+ * @see javax.swing.event.UndoableEditListener
+ * @see Element
+ * @see Position
+ * @see AttributeSet
+ */
+public interface Document {
+
+ /**
+ * Returns number of characters of content currently
+ * in the document.
+ *
+ * @return number of characters >= 0
+ */
+ public int getLength();
+
+ /**
+ * Registers the given observer to begin receiving notifications
+ * when changes are made to the document.
+ *
+ * @param listener the observer to register
+ * @see Document#removeDocumentListener
+ */
+ public void addDocumentListener(DocumentListener listener);
+
+ /**
+ * Unregisters the given observer from the notification list
+ * so it will no longer receive change updates.
+ *
+ * @param listener the observer to register
+ * @see Document#addDocumentListener
+ */
+ public void removeDocumentListener(DocumentListener listener);
+
+ /**
+ * Registers the given observer to begin receiving notifications
+ * when undoable edits are made to the document.
+ *
+ * @param listener the observer to register
+ * @see javax.swing.event.UndoableEditEvent
+ */
+ public void addUndoableEditListener(UndoableEditListener listener);
+
+ /**
+ * Unregisters the given observer from the notification list
+ * so it will no longer receive updates.
+ *
+ * @param listener the observer to register
+ * @see javax.swing.event.UndoableEditEvent
+ */
+ public void removeUndoableEditListener(UndoableEditListener listener);
+
+ /**
+ * Gets the properties associated with the document.
+ *
+ * @param key a non-<code>null</code> property key
+ * @return the properties
+ * @see #putProperty(Object, Object)
+ */
+ public Object getProperty(Object key);
+
+ /**
+ * Associates a property with the document. Two standard
+ * property keys provided are: <a href="#StreamDescriptionProperty">
+ * <code>StreamDescriptionProperty</code></a> and
+ * <a href="#TitleProperty"><code>TitleProperty</code></a>.
+ * Other properties, such as author, may also be defined.
+ *
+ * @param key the non-<code>null</code> property key
+ * @param value the property value
+ * @see #getProperty(Object)
+ */
+ public void putProperty(Object key, Object value);
+
+ /**
+ * Removes a portion of the content of the document.
+ * This will cause a DocumentEvent of type
+ * DocumentEvent.EventType.REMOVE to be sent to the
+ * registered DocumentListeners, unless an exception
+ * is thrown. The notification will be sent to the
+ * listeners by calling the removeUpdate method on the
+ * DocumentListeners.
+ * <p>
+ * To ensure reasonable behavior in the face
+ * of concurrency, the event is dispatched after the
+ * mutation has occurred. This means that by the time a
+ * notification of removal is dispatched, the document
+ * has already been updated and any marks created by
+ * <code>createPosition</code> have already changed.
+ * For a removal, the end of the removal range is collapsed
+ * down to the start of the range, and any marks in the removal
+ * range are collapsed down to the start of the range.
+ * <p align=center><img src="doc-files/Document-remove.gif"
+ * alt="Diagram shows removal of 'quick' from 'The quick brown fox.'">
+ * <p>
+ * If the Document structure changed as result of the removal,
+ * the details of what Elements were inserted and removed in
+ * response to the change will also be contained in the generated
+ * DocumentEvent. It is up to the implementation of a Document
+ * to decide how the structure should change in response to a
+ * remove.
+ * <p>
+ * If the Document supports undo/redo, an UndoableEditEvent will
+ * also be generated.
+ *
+ * @param offs the offset from the beginning >= 0
+ * @param len the number of characters to remove >= 0
+ * @exception BadLocationException some portion of the removal range
+ * was not a valid part of the document. The location in the exception
+ * is the first bad position encountered.
+ * @see javax.swing.event.DocumentEvent
+ * @see javax.swing.event.DocumentListener
+ * @see javax.swing.event.UndoableEditEvent
+ * @see javax.swing.event.UndoableEditListener
+ */
+ public void remove(int offs, int len) throws BadLocationException;
+
+ /**
+ * Inserts a string of content. This will cause a DocumentEvent
+ * of type DocumentEvent.EventType.INSERT to be sent to the
+ * registered DocumentListers, unless an exception is thrown.
+ * The DocumentEvent will be delivered by calling the
+ * insertUpdate method on the DocumentListener.
+ * The offset and length of the generated DocumentEvent
+ * will indicate what change was actually made to the Document.
+ * <p align=center><img src="doc-files/Document-insert.gif"
+ * alt="Diagram shows insertion of 'quick' in 'The quick brown fox'">
+ * <p>
+ * If the Document structure changed as result of the insertion,
+ * the details of what Elements were inserted and removed in
+ * response to the change will also be contained in the generated
+ * DocumentEvent. It is up to the implementation of a Document
+ * to decide how the structure should change in response to an
+ * insertion.
+ * <p>
+ * If the Document supports undo/redo, an UndoableEditEvent will
+ * also be generated.
+ *
+ * @param offset the offset into the document to insert the content >= 0.
+ * All positions that track change at or after the given location
+ * will move.
+ * @param str the string to insert
+ * @param a the attributes to associate with the inserted
+ * content. This may be null if there are no attributes.
+ * @exception BadLocationException the given insert position is not a valid
+ * position within the document
+ * @see javax.swing.event.DocumentEvent
+ * @see javax.swing.event.DocumentListener
+ * @see javax.swing.event.UndoableEditEvent
+ * @see javax.swing.event.UndoableEditListener
+ */
+ public void insertString(int offset, String str, AttributeSet a) throws BadLocationException;
+
+ /**
+ * Fetches the text contained within the given portion
+ * of the document.
+ *
+ * @param offset the offset into the document representing the desired
+ * start of the text >= 0
+ * @param length the length of the desired string >= 0
+ * @return the text, in a String of length >= 0
+ * @exception BadLocationException some portion of the given range
+ * was not a valid part of the document. The location in the exception
+ * is the first bad position encountered.
+ */
+ public String getText(int offset, int length) throws BadLocationException;
+
+ /**
+ * Fetches the text contained within the given portion
+ * of the document.
+ * <p>
+ * If the partialReturn property on the txt parameter is false, the
+ * data returned in the Segment will be the entire length requested and
+ * may or may not be a copy depending upon how the data was stored.
+ * If the partialReturn property is true, only the amount of text that
+ * can be returned without creating a copy is returned. Using partial
+ * returns will give better performance for situations where large
+ * parts of the document are being scanned. The following is an example
+ * of using the partial return to access the entire document:
+ * <p>
+ * <pre><code>
+ *
+ * int nleft = doc.getDocumentLength();
+ * Segment text = new Segment();
+ * int offs = 0;
+ * text.setPartialReturn(true);
+ * while (nleft > 0) {
+ * doc.getText(offs, nleft, text);
+ * // do someting with text
+ * nleft -= text.count;
+ * offs += text.count;
+ * }
+ *
+ * </code></pre>
+ *
+ * @param offset the offset into the document representing the desired
+ * start of the text >= 0
+ * @param length the length of the desired string >= 0
+ * @param txt the Segment object to return the text in
+ *
+ * @exception BadLocationException Some portion of the given range
+ * was not a valid part of the document. The location in the exception
+ * is the first bad position encountered.
+ */
+ public void getText(int offset, int length, Segment txt) throws BadLocationException;
+
+ /**
+ * Returns a position that represents the start of the document. The
+ * position returned can be counted on to track change and stay
+ * located at the beginning of the document.
+ *
+ * @return the position
+ */
+ public Position getStartPosition();
+
+ /**
+ * Returns a position that represents the end of the document. The
+ * position returned can be counted on to track change and stay
+ * located at the end of the document.
+ *
+ * @return the position
+ */
+ public Position getEndPosition();
+
+ /**
+ * This method allows an application to mark a place in
+ * a sequence of character content. This mark can then be
+ * used to tracks change as insertions and removals are made
+ * in the content. The policy is that insertions always
+ * occur prior to the current position (the most common case)
+ * unless the insertion location is zero, in which case the
+ * insertion is forced to a position that follows the
+ * original position.
+ *
+ * @param offs the offset from the start of the document >= 0
+ * @return the position
+ * @exception BadLocationException if the given position does not
+ * represent a valid location in the associated document
+ */
+ public Position createPosition(int offs) throws BadLocationException;
+
+ /**
+ * Returns all of the root elements that are defined.
+ * <p>
+ * Typically there will be only one document structure, but the interface
+ * supports building an arbitrary number of structural projections over the
+ * text data. The document can have multiple root elements to support
+ * multiple document structures. Some examples might be:
+ * </p>
+ * <ul>
+ * <li>Text direction.
+ * <li>Lexical token streams.
+ * <li>Parse trees.
+ * <li>Conversions to formats other than the native format.
+ * <li>Modification specifications.
+ * <li>Annotations.
+ * </ul>
+ *
+ * @return the root element
+ */
+ public Element[] getRootElements();
+
+ /**
+ * Returns the root element that views should be based upon,
+ * unless some other mechanism for assigning views to element
+ * structures is provided.
+ *
+ * @return the root element
+ */
+ public Element getDefaultRootElement();
+
+ /**
+ * Allows the model to be safely rendered in the presence
+ * of concurrency, if the model supports being updated asynchronously.
+ * The given runnable will be executed in a way that allows it
+ * to safely read the model with no changes while the runnable
+ * is being executed. The runnable itself may <em>not</em>
+ * make any mutations.
+ *
+ * @param r a <code>Runnable</code> used to render the model
+ */
+ public void render(Runnable r);
+
+ /**
+ * The property name for the description of the stream
+ * used to initialize the document. This should be used
+ * if the document was initialized from a stream and
+ * anything is known about the stream.
+ */
+ public static final String StreamDescriptionProperty = "stream";
+
+ /**
+ * The property name for the title of the document, if
+ * there is one.
+ */
+ public static final String TitleProperty = "title";
+
+
+}