Home » openjdk-7 » javax » swing » text » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2003, 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 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><a href="#getLength()">getLength()</a>
   62    * <li><a href="#getText(int, int)">getText(int, int)</a>
   63    * <li><a href="#getText(int, int, javax.swing.text.Segment)">getText(int, int, Segment)</a>
   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 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><a href="#getDefaultRootElement()">getDefaultRootElement</a>
   83    * <li><a href="#getRootElements()">getRootElements</a>
   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><a href="#insertString(int, java.lang.String, javax.swing.text.AttributeSet)">insertString(int, String, AttributeSet)</a>
   97    * <li><a href="#remove(int, int)">remove(int, int)</a>
   98    * <li><a href="#createPosition(int)">createPosition(int)</a>
   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 align=center><img src="doc-files/Document-notification.gif"
  126    * alt="The preceeding 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><a href="#getProperty(java.lang.Object)">getProperty(Object)</a>
  165    * <li><a href="#putProperty(java.lang.Object, java.lang.Object)">putProperty(Object, Object)</a>
  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 >= 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 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 >= 0
  284        * @param len   the number of characters to remove >= 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 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 >= 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 >= 0
  337        * @param length  the length of the desired string >= 0
  338        * @return the text, in a String of length >= 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        * <p>
  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 > 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 >= 0
  375        * @param length  the length of the desired string >= 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 >= 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   }

Home » openjdk-7 » javax » swing » text » [javadoc | source]