/*

 * Copyright (c) 1997, 2003, Oracle and/or its affiliates. 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.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.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.

 * 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>{@link #getLength()}

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

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

 * </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.

 * 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>{@link #getDefaultRootElement()}

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

 * </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>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)}

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

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

 * </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.

 * 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>{@link #getProperty(java.lang.Object)}

 * <li>{@link #putProperty(java.lang.Object, java.lang.Object)}

 * </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.

     *  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.

     *  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";

}