libjava/javax/swing/text/Document.java

   1 /* Document.java --
   2    Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.swing.text;
  39
  40 import javax.swing.event.DocumentListener;
  41 import javax.swing.event.UndoableEditListener;
  42
  43 /**
  44  * A Document is the model that backs up all text components in Swing.
  45  * This interface supports different kinds of implementations, from
  46  * simple plain text model up to complex styled HTML or RTF models.
  47  */
  48 public interface Document
  49 {
  50   /**
  51    * The key for the property that describes the source of a document.
  52    */
  53   String StreamDescriptionProperty = "stream";
  54
  55   /**
  56    * The key for the property that is the title of a document.
  57    */
  58   String TitleProperty = "title";
  59
  60   /**
  61    * Adds a {@link DocumentListener} to this document.
  62    *
  63    * @param listener the DocumentListener to add
  64    */
  65   void addDocumentListener(DocumentListener listener);
  66
  67   /**
  68    * Adds an {@link UndoableEditListener} to this document.
  69    *
  70    * @param listener the UndoableEditListener to add
  71    */
  72   void addUndoableEditListener(UndoableEditListener listener);
  73
  74   /**
  75    * Creates a mark in the character content at the specified offset.
  76    *
  77    * @param offs the offset where to place the mark
  78    *
  79    * @return the created Position object
  80    *
  81    * @throws BadLocationException of the specified offset is not a valid
  82    *         position in the documents content
  83    */
  84   Position createPosition(int offs)
  85     throws BadLocationException;
  86
  87   /**
  88    * Returns the default root element. Views should be using this element
  89    * unless other mechanisms for assigning views to element structure is
  90    * provided.
  91    *
  92    * @return the default root element
  93    */
  94   Element getDefaultRootElement();
  95
  96   /**
  97    * Returns the position that marks the end of the document.
  98    *
  99    * @return the position that marks the end of the document
 100    */
 101   Position getEndPosition();
 102
 103   /**
 104    * Returns the length of the document content.
 105    *
 106    * @return the length of the document content
 107    */
 108   int getLength();
 109
 110   /**
 111    * Returns a document property with the specified key.
 112    *
 113    * @param key the (non-null) key for the property to fetch
 114    *
 115    * @return the property for <code>key</code> or null if no such property
 116    *         is stored
 117    */
 118   Object getProperty(Object key);
 119
 120   /**
 121    * Returns the root elements of the document content.
 122    *
 123    * @return the root elements of the document content
 124    */
 125   Element[] getRootElements();
 126
 127   /**
 128    * Returns the position that marks the beginning of the document
 129    * content.
 130    *
 131    * @return the start position
 132    */
 133   Position getStartPosition();
 134
 135   /**
 136    * Returns the textual content starting at <code>offset</code> with
 137    * a length of <code>length</code>.
 138    *
 139    * @param offset the beginning of the text fragment to fetch
 140    * @param length the length of the text fragment to fetch
 141    *
 142    * @return the text fragment starting at <code>offset</code> with
 143    *         a length of <code>length</code>
 144    *
 145    * @throws BadLocationException if <code>offset</code> or <code>length</code>
 146    *         are no valid locations in the document content
 147    */
 148   String getText(int offset, int length)
 149     throws BadLocationException;
 150
 151   /**
 152    * Fetch the textual content starting at <code>offset</code> with
 153    * a length of <code>length</code> and store it in <code>txt</code>.
 154    *
 155    * @param offset the beginning of the text fragment to fetch
 156    * @param length the length of the text fragment to fetch
 157    * @param txt the Segment where to store the text fragment
 158    *
 159    * @throws BadLocationException if <code>offset</code> or <code>length</code>
 160    *         are no valid locations in the document content
 161    */
 162   void getText(int offset, int length, Segment txt)
 163     throws BadLocationException;
 164
 165   /**
 166    * Inserts a piece of text with an AttributeSet at the specified
 167    * <code>offset</code>.
 168    *
 169    * @param offset the location where to insert the content
 170    * @param str the textual content to insert
 171    * @param a the Attributes associated with the piece of text
 172    *
 173    * @throws BadLocationException if <code>offset</code>
 174    *         is not a valid location in the document content
 175    */
 176   void insertString(int offset, String str, AttributeSet a)
 177     throws BadLocationException;
 178
 179   /**
 180    * Sets a document property.
 181    *
 182    * @param key the key of the property
 183    * @param value the value of the property
 184    */
 185   void putProperty(Object key, Object value);
 186
 187   /**
 188    * Removes a piece of content.
 189    *
 190    * @param offs the location of the fragment to remove
 191    * @param len the length of the fragment to remove
 192    *
 193    * @throws BadLocationException if <code>offs</code> or <code>len</code>
 194    *         are no valid locations in the document content
 195    */
 196   void remove(int offs, int len)
 197     throws BadLocationException;
 198
 199   /**
 200    * Removes a DocumentListener from this Document.
 201    *
 202    * @param listener the DocumentListener to remove
 203    */
 204   void removeDocumentListener(DocumentListener listener);
 205
 206   /**
 207    * Removes an UndoableEditListener from this Document.
 208    *
 209    * @param listener the UndoableEditListener to remove
 210    */
 211   void removeUndoableEditListener(UndoableEditListener listener);
 212
 213   /**
 214    * This allows the Document to be rendered safely. It is made sure that
 215    * the Runnable can read the document without any changes while reading.
 216    * The Runnable is not allowed to change the Document itself.
 217    *
 218    * @param r the Runnable that renders the Document
 219    */
 220   void render(Runnable r);
 221 }