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