diff options
Diffstat (limited to 'src/share/classes/javax/swing/text/Document.java')
| -rw-r--r-- | src/share/classes/javax/swing/text/Document.java | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/src/share/classes/javax/swing/text/Document.java b/src/share/classes/javax/swing/text/Document.java new file mode 100644 index 000000000..b98d6e372 --- /dev/null +++ b/src/share/classes/javax/swing/text/Document.java @@ -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"; + + +} |