1 /*

     1 /*

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     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

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     7  * published by the Free Software Foundation.  Oracle designates this

    31  * The <code>Document</code> is a container for text that serves

    31  * The <code>Document</code> is a container for text that serves

    32  * as the model for swing text components.  The goal for this

    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)

    33  * interface is to scale from very simple needs (a plain text textfield)

    34  * to complex needs (an HTML or XML document, for example).

    34  * to complex needs (an HTML or XML document, for example).

    35  *

    35  *

    37  * <p>

    37  * <p>

    38  * At the simplest level, text can be

    38  * At the simplest level, text can be

    39  * modeled as a linear sequence of characters. To support

    39  * modeled as a linear sequence of characters. To support

    40  * internationalization, the Swing text model uses

    40  * internationalization, the Swing text model uses

    41  * <a href="http://www.unicode.org/">unicode</a> characters.

    41  * <a href="http://www.unicode.org/">unicode</a> characters.

    60  * <ul>

    60  * <ul>

    61  * <li>{@link #getLength()}

    61  * <li>{@link #getLength()}

    62  * <li>{@link #getText(int, int)}

    62  * <li>{@link #getText(int, int)}

    63  * <li>{@link #getText(int, int, javax.swing.text.Segment)}

    63  * <li>{@link #getText(int, int, javax.swing.text.Segment)}

    64  * </ul>

    64  * </ul>

    66  * <p>

    66  * <p>

    67  * Text is rarely represented simply as featureless content. Rather,

    67  * Text is rarely represented simply as featureless content. Rather,

    68  * text typically has some sort of structure associated with it.

    68  * text typically has some sort of structure associated with it.

    69  * Exactly what structure is modeled is up to a particular Document

    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

    70  * implementation.  It might be as simple as no structure (i.e. a

    81  * <ul>

    81  * <ul>

    82  * <li>{@link #getDefaultRootElement()}

    82  * <li>{@link #getDefaultRootElement()}

    83  * <li>{@link #getRootElements()}

    83  * <li>{@link #getRootElements()}

    84  * </ul>

    84  * </ul>

    85  *

    85  *

    87  * <p>

    87  * <p>

    88  * All documents need to be able to add and remove simple text.

    88  * All documents need to be able to add and remove simple text.

    89  * Typically, text is inserted and removed via gestures from

    89  * Typically, text is inserted and removed via gestures from

    90  * a keyboard or a mouse.  What effect the insertion or removal

    90  * a keyboard or a mouse.  What effect the insertion or removal

    91  * has upon the document structure is entirely up to the

    91  * has upon the document structure is entirely up to the

    96  * <li>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)}

    96  * <li>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)}

    97  * <li>{@link #remove(int, int)}

    97  * <li>{@link #remove(int, int)}

    98  * <li>{@link #createPosition(int)}

    98  * <li>{@link #createPosition(int)}

    99  * </ul>

    99  * </ul>

   100  *

   100  *

   102  * <p>

   102  * <p>

   103  * Mutations to the <code>Document</code> must be communicated to

   103  * Mutations to the <code>Document</code> must be communicated to

   104  * interested observers.  The notification of change follows the event model

   104  * interested observers.  The notification of change follows the event model

   105  * guidelines that are specified for JavaBeans.  In the JavaBeans

   105  * guidelines that are specified for JavaBeans.  In the JavaBeans

   106  * event model, once an event notification is dispatched, all listeners

   106  * event model, once an event notification is dispatched, all listeners

   150  * <li><a href="#removeDocumentListener(javax.swing.event.DocumentListener)">removeDocumentListener(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>

   151  * <li><a href="#addUndoableEditListener(javax.swing.event.UndoableEditListener)">addUndoableEditListener(UndoableEditListener)</a>

   152  * <li><a href="#removeUndoableEditListener(javax.swing.event.UndoableEditListener)">removeUndoableEditListener(UndoableEditListener)</a>

   152  * <li><a href="#removeUndoableEditListener(javax.swing.event.UndoableEditListener)">removeUndoableEditListener(UndoableEditListener)</a>

   153  * </ul>

   153  * </ul>

   154  *

   154  *

   156  * <p>

   156  * <p>

   157  * Document implementations will generally have some set of properties

   157  * Document implementations will generally have some set of properties

   158  * associated with them at runtime.  Two well known properties are the

   158  * associated with them at runtime.  Two well known properties are the

   159  * <a href="#StreamDescriptionProperty">StreamDescriptionProperty</a>,

   159  * <a href="#StreamDescriptionProperty">StreamDescriptionProperty</a>,

   160  * which can be used to describe where the <code>Document</code> came from,

   160  * which can be used to describe where the <code>Document</code> came from,