1 /* 2 * Copyright (c) 1997, 2013, 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>Content</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 style="text-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>{@link #getLength()} 62 * <li>{@link #getText(int, int)} 63 * <li>{@link #getText(int, int, javax.swing.text.Segment)} 64 * </ul> 65 * <p><b>Structure</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 style="text-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>{@link #getDefaultRootElement()} 83 * <li>{@link #getRootElements()} 84 * </ul> 85 * 86 * <p><b>Mutations</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>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)} 97 * <li>{@link #remove(int, int)} 98 * <li>{@link #createPosition(int)} 99 * </ul> 100 * 101 * <p><b>Notification</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 style="text-align:center"><img src="doc-files/Document-notification.gif" 126 * alt="The preceding 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>Properties</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>{@link #getProperty(java.lang.Object)} 165 * <li>{@link #putProperty(java.lang.Object, java.lang.Object)} 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 style="text-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 style="text-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 * 358 * <pre><code> 359 * 360 * int nleft = doc.getDocumentLength(); 361 * Segment text = new Segment(); 362 * int offs = 0; 363 * text.setPartialReturn(true); 364 * while (nleft > 0) { 365 * doc.getText(offs, nleft, text); 366 * // do someting with text 367 * nleft -= text.count; 368 * offs += text.count; 369 * } 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 }