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>{@link #addDocumentListener(DocumentListener)} 150 * <li>{@link #removeDocumentListener(DocumentListener)} 151 * <li>{@link #addUndoableEditListener(UndoableEditListener)} 152 * <li>{@link #removeUndoableEditListener(UndoableEditListener)} 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><b>Overview and Programming Tips</b> 169 * <p><u>{@link javax.swing.text.Element}</u> is an important interface used in constructing a Document. 170 * It has the power to describe various structural parts of a document, 171 * such as paragraphs, lines of text, or even (in HTML documents) items in lists. 172 * Conceptually, the Element interface captures some of the spirit of an SGML document. 173 * So if you know SGML, you may already have some understanding of Swing's Element interface. 174 * <p>In the Swing text API's document model, the interface Element defines a structural piece of a Document, 175 * like a paragraph, a line of text, or a list item in an HTML document. 176 * <p>Every Element is either a <i>branch</i> or a <i>leaf</i>. If an element is a branch, 177 * the <code>isLeaf()</code> method returns false. If an element is a a leaf, <code>isLeaf()</code> returns true. 178 * <p>Branches can have any number of children. Leaves do not have children. 179 * To determine how many children a branch has, you can call <code>getElementCount()</code>. 180 * To determine the parent of an Element, you can call <code>getParentElement()</code>. 181 * Root elements don't have parents, so calling <code>getParentElement()</code> on a root returns null. 182 * <p>An Element represents a specific region in a Document that begins with startOffset 183 * and ends just before endOffset. 184 * The start offset of a branch Element is usually the start offset of its first child. 185 * Similarly, the end offset of a branch Element is usually the end offset of its last child. 186 * <p>Every Element is associated with an AttributeSet that you can access by calling <code>getAttributes()</code>. 187 * In an Element, and AttributeSet is essentially a set of key/value pairs. 188 * These pairs are generally used for markup -- such as determining the Element's 189 * foreground color, font size, and so on. But it is up to the model, and the developer, 190 * to determine what is stored in the AttributeSet. 191 * <p>You can obtain the root Element (or Elements) of a Document by calling the 192 * methods <code>getDefaultRootElement()</code> and <code>getRootElements()</code>, which are defined in the Document interface. 193 * <p>The Document interface is responsible for translating a linear view of the 194 * characters into Element operations. It is up to each Document implementation 195 * to define what the Element structure is. 196 * 197 * <p><b>The PlainDocument class</b> 198 * <p>The <u>{@link javax.swing.text.PlainDocument}</u> class defines an Element 199 * structure in which the root node has a child node for each line of text in the model. 200 * <u>Figure 1</u> shows how two lines of text would be modeled by a PlainDocument 201 * <p style="text-align:center"><img src="doc-files/plain1.gif" 202 * alt="The preceding text describes this graphic."> 203 * <p><u>Figure 2</u> shows how how those same two lines of text might map to actual content: 204 * <p style="text-align:center"><img src="doc-files/plain2.gif" 205 * alt="The preceding text describes this graphic."> 206 * 207 * <p><b>Inserting text into a PlainDocument</b> 208 * <p>As just mentioned, a PlainDocument contains a root Element, which in turn 209 * contains an Element for each line of text. 210 * When text is inserted into a PlainDocument, it creates the Elements that 211 * are needed for an Element to exist for each newline. 212 * To illustrate, let's say you wanted to insert a newline at offset 2 in <u>Figure 2</u>, above. 213 * To accomplish this objective, you could use the Document method <code>insertString()</code>, 214 * using this syntax: 215 * <pre><code>document.insertString(2, "\n", null);</code></pre> 216 * <p>After invoking the <code>insertString()</code> method, the Element structure would look 217 * like the one shown in <u>Figure 3</u>. 218 * <p style="text-align:center"><img src="doc-files/plain3.gif" 219 * alt="The preceding text describes this graphic."> 220 * <p>As another example, let's say you wanted to insert the pattern "new\ntext\n" 221 * at offset 2 as shown previously in <u>Figure 2</u>. This operation would have the 222 * result shown in <u>Figure 4</u>. 223 * <p style="text-align:center"><img src="doc-files/plain4.gif" 224 * alt="The preceding text describes this graphic."> 225 * <p>In the preceding illustrations, the name of the line Elements is changed 226 * after the insertion to match the line numbers. 227 * But notice that when this is done, the AttributeSets remain the same. 228 * For example, in <u>Figure 2</u>, the AttributeSet of Line 2 matches that of the 229 * AttributeSet of Line 4 in <u>Figure 4</u>. 230 * 231 * <p><b>Removing text from a PlainDocument</b> 232 * <p>Removal of text results in a structure change if the deletion spans more than one line. 233 * Consider a deletion of seven characters starting at Offset 1 shown previously in <u>Figure 3</u>. 234 * In this case, the Element representing Line 2 is completely removed, as the 235 * region it represents is contained in the deleted region. 236 * The Elements representing Lines 1 and 3 are joined, as they are partially 237 * contained in the deleted region. Thus, we have the result: 238 * <p style="text-align:center"><img src="doc-files/plain5.gif" 239 * alt="The preceding text describes this graphic."> 240 * 241 * <p><b>The Default StyledDocument Class</b> 242 * <p>The <u>{@link javax.swing.text.DefaultStyledDocument}</u> class, used for styled text, 243 * contains another level of Elements. 244 * This extra level is needed so that each paragraph can contain different styles of text. 245 * In the two paragraphs shown in <u>Figure 6</u>, the first paragraph contains 246 * two styles and the second paragraph contains three styles. 247 * <p style="text-align:center"><img src="doc-files/plain6.gif" 248 * alt="The preceding text describes this graphic."> 249 * <p><u>Figure 7</u> shows how those same Elements might map to content. 250 * <p style="text-align:center"><img src="doc-files/plain7.gif" 251 * alt="The preceding text describes this graphic."> 252 * 253 * <p><b>Inserting text into a DefaultStyledDocument</b> 254 * <p>As previously mentioned, DefaultStyledDocument maintains an Element structure 255 * such that the root Element 256 * contains a child Element for each paragraph. In turn, each of these 257 * paragraph Elements contains an Element for each style of text in the paragraph. 258 * As an example, let's say you had a document containing one paragraph, 259 * and that this paragraph contained two styles, as shown in <u>Figure 8</u>. 260 * <p style="text-align:center"><img src="doc-files/plain8.gif" 261 * alt="The preceding text describes this graphic."> 262 * <p>If you then wanted to insert a newline at offset 2, you would again use the 263 * method <code>insertString()</code>, as follows: 264 * 265 * <pre><code> styledDocument.insertString(2, "\n", 266 styledDocument.getCharacterElement(0).getAttributes());</code></pre> 267 268 * <p>This operation would have the result shown in <u>Figure 9</u>. 269 * <p style="text-align:center"><img src="doc-files/plain9.gif" 270 * alt="The preceding text describes this graphic."> 271 * <p>It's important to note that the AttributeSet passed to <code>insertString()</code> matches 272 * that of the attributes of Style 1. If the AttributeSet passed to <code>insertString()</code> 273 * did not match, the result would be the situation shown in <u>Figure 10</u>. 274 * <p style="text-align:center"><img src="doc-files/plain10.gif" 275 * alt="The preceding text describes this graphic."> 276 * <p><b>Removing text from a DefaultStyledDocument</b> 277 * <p>Removing text from a DefaultStyledDocument is similar to removing text from 278 * a PlainDocument. The only difference is the extra level of Elements. 279 * Consider what would happen if you deleted two characters at Offset 1 280 * from Figure 10, above. Since the the second Element of Paragraph 1 is 281 * completely contained in the deleted region, it would be removed. 282 * Assuming the attributes of Paragraph 1's first child matched those of 283 * Paragraph2's first child, the results would be those shown in <u>Figure 11</u>. 284 * <p style="text-align:center"><img src="doc-files/plain11.gif" 285 * alt="The preceding text describes this graphic."> 286 * <p>If the attributes did not match, we would get the results shown in <u>Figure 12</u>. 287 * <p style="text-align:center"><img src="doc-files/plain12.gif" 288 * alt="The preceding text describes this graphic."> 289 * 290 * <p><b>The StyledDocument Class</b> 291 * <p>The <u>{@link javax.swing.text.StyledDocument}</u> class provides a method 292 * named <code>setCharacterAttributes()</code>, which allows you to set the attributes 293 * on the character Elements in a given range: 294 295 * <pre><code> public void setCharacterAttributes 296 * (int offset, int length, AttributeSet s, boolean replace);</code></pre> 297 * 298 * <p>Recall that in the diagrams shown in the previous section, all leaf Elements 299 * shown in the drawings were also character Elements. 300 * That means that the <code>setCharacterAttributes()</code> method could be used to set their attributes. 301 * <p>The <code>setCharacterAttributes()</code> method takes four arguments . 302 * The first and second arguments identify a region in the Document that is 303 * to be changed. The third argument specifies the new attributes 304 * (as an AttributeSet), and the fourth argument determines if the new attributes 305 * should be added to the existing attributes (a value of false) or 306 * if the character Element should replace its existing attributes 307 * with the new attributes (a value of true). 308 * <p>As an example, let's say you wanted to change the attributes of the 309 * first three characters in <u>Figure 9</u>, shown previously. 310 * The first two arguments passed to <code>setCharacterAttributes()</code> would be 0 and 3. 311 * The third argument would be the AttributeSet containing the new attributes. 312 * In the example we are considering, it doesn't matter what the fourth argument is. 313 * <p>As the start and end offsets of the changed region (0 and 3) fall on 314 * character Element boundaries, no structure change is needed. 315 * That is, only the attributes of the character Element style 1 will change. 316 * <p>Now let's look at an example that requires a structure change. 317 * Instead of changing the first three characters shown in <u>Figure 9</u>, 318 * let's change the first two characters. 319 * Because the end change offset (2) does not fall on a character Element boundary, 320 * the Element at offset 2 must be split in such a way 321 * that offset 2 is the boundary of two Elements. 322 * Invoking <code>setCharacterAttributes()</code> with a start offset of 0 323 * and length of 2 has the result shown earlier in <u>Figure 10</u>. 324 * <p><b>Changing Paragraph Attributes in a StyledDocument</b> 325 * <p>The StyledDocument class provides a method named <code>setParagraphAttributes()</code>, 326 * which can be used to change the attributes of a paragraph Element: 327 328 * <pre><code> public void setParagraphAttributes 329 * (int offset, int length, AttributeSet s, boolean replace);</code></pre> 330 * 331 * <p>This method is similar to <code>setCharacterAttributes()</code>, 332 * but it allows you to change the attributes of paragraph Elements. 333 * It is up to the implementation of a StyledDocument to define which Elements 334 * are paragraphs. DefaultStyledDocument interprets paragraph Elements 335 * to be the parent Element of the character Element. 336 * Invoking this method does not result in a structure change; 337 * only the attributes of the paragraph Element change. 338 * 339 * <p>It is recommended to look into {@link javax.swing.text.EditorKit} and 340 * {@link javax.swing.text.View}. 341 * View is responsible for rendering a particular Element, and 342 * EditorKit is responsible for a ViewFactory that is able to decide what 343 * View should be created based on an Element. 344 * 345 * @author Timothy Prinzing 346 * 347 * @see javax.swing.event.DocumentEvent 348 * @see javax.swing.event.DocumentListener 349 * @see javax.swing.event.UndoableEditEvent 350 * @see javax.swing.event.UndoableEditListener 351 * @see Element 352 * @see Position 353 * @see AttributeSet 354 */ 355 public interface Document { 356 357 /** 358 * Returns number of characters of content currently 359 * in the document. 360 * 361 * @return number of characters >= 0 362 */ getLength()363 public int getLength(); 364 365 /** 366 * Registers the given observer to begin receiving notifications 367 * when changes are made to the document. 368 * 369 * @param listener the observer to register 370 * @see Document#removeDocumentListener 371 */ addDocumentListener(DocumentListener listener)372 public void addDocumentListener(DocumentListener listener); 373 374 /** 375 * Unregisters the given observer from the notification list 376 * so it will no longer receive change updates. 377 * 378 * @param listener the observer to register 379 * @see Document#addDocumentListener 380 */ removeDocumentListener(DocumentListener listener)381 public void removeDocumentListener(DocumentListener listener); 382 383 /** 384 * Registers the given observer to begin receiving notifications 385 * when undoable edits are made to the document. 386 * 387 * @param listener the observer to register 388 * @see javax.swing.event.UndoableEditEvent 389 */ addUndoableEditListener(UndoableEditListener listener)390 public void addUndoableEditListener(UndoableEditListener listener); 391 392 /** 393 * Unregisters the given observer from the notification list 394 * so it will no longer receive updates. 395 * 396 * @param listener the observer to register 397 * @see javax.swing.event.UndoableEditEvent 398 */ removeUndoableEditListener(UndoableEditListener listener)399 public void removeUndoableEditListener(UndoableEditListener listener); 400 401 /** 402 * Gets the properties associated with the document. 403 * 404 * @param key a non-<code>null</code> property key 405 * @return the properties 406 * @see #putProperty(Object, Object) 407 */ getProperty(Object key)408 public Object getProperty(Object key); 409 410 /** 411 * Associates a property with the document. Two standard 412 * property keys provided are: <a href="#StreamDescriptionProperty"> 413 * <code>StreamDescriptionProperty</code></a> and 414 * <a href="#TitleProperty"><code>TitleProperty</code></a>. 415 * Other properties, such as author, may also be defined. 416 * 417 * @param key the non-<code>null</code> property key 418 * @param value the property value 419 * @see #getProperty(Object) 420 */ putProperty(Object key, Object value)421 public void putProperty(Object key, Object value); 422 423 /** 424 * Removes a portion of the content of the document. 425 * This will cause a DocumentEvent of type 426 * DocumentEvent.EventType.REMOVE to be sent to the 427 * registered DocumentListeners, unless an exception 428 * is thrown. The notification will be sent to the 429 * listeners by calling the removeUpdate method on the 430 * DocumentListeners. 431 * <p> 432 * To ensure reasonable behavior in the face 433 * of concurrency, the event is dispatched after the 434 * mutation has occurred. This means that by the time a 435 * notification of removal is dispatched, the document 436 * has already been updated and any marks created by 437 * <code>createPosition</code> have already changed. 438 * For a removal, the end of the removal range is collapsed 439 * down to the start of the range, and any marks in the removal 440 * range are collapsed down to the start of the range. 441 * <p style="text-align:center"><img src="doc-files/Document-remove.gif" 442 * alt="Diagram shows removal of 'quick' from 'The quick brown fox.'"> 443 * <p> 444 * If the Document structure changed as result of the removal, 445 * the details of what Elements were inserted and removed in 446 * response to the change will also be contained in the generated 447 * DocumentEvent. It is up to the implementation of a Document 448 * to decide how the structure should change in response to a 449 * remove. 450 * <p> 451 * If the Document supports undo/redo, an UndoableEditEvent will 452 * also be generated. 453 * 454 * @param offs the offset from the beginning >= 0 455 * @param len the number of characters to remove >= 0 456 * @exception BadLocationException some portion of the removal range 457 * was not a valid part of the document. The location in the exception 458 * is the first bad position encountered. 459 * @see javax.swing.event.DocumentEvent 460 * @see javax.swing.event.DocumentListener 461 * @see javax.swing.event.UndoableEditEvent 462 * @see javax.swing.event.UndoableEditListener 463 */ remove(int offs, int len)464 public void remove(int offs, int len) throws BadLocationException; 465 466 /** 467 * Inserts a string of content. This will cause a DocumentEvent 468 * of type DocumentEvent.EventType.INSERT to be sent to the 469 * registered DocumentListers, unless an exception is thrown. 470 * The DocumentEvent will be delivered by calling the 471 * insertUpdate method on the DocumentListener. 472 * The offset and length of the generated DocumentEvent 473 * will indicate what change was actually made to the Document. 474 * <p style="text-align:center"><img src="doc-files/Document-insert.gif" 475 * alt="Diagram shows insertion of 'quick' in 'The quick brown fox'"> 476 * <p> 477 * If the Document structure changed as result of the insertion, 478 * the details of what Elements were inserted and removed in 479 * response to the change will also be contained in the generated 480 * DocumentEvent. It is up to the implementation of a Document 481 * to decide how the structure should change in response to an 482 * insertion. 483 * <p> 484 * If the Document supports undo/redo, an UndoableEditEvent will 485 * also be generated. 486 * 487 * @param offset the offset into the document to insert the content >= 0. 488 * All positions that track change at or after the given location 489 * will move. 490 * @param str the string to insert 491 * @param a the attributes to associate with the inserted 492 * content. This may be null if there are no attributes. 493 * @exception BadLocationException the given insert position is not a valid 494 * position within the document 495 * @see javax.swing.event.DocumentEvent 496 * @see javax.swing.event.DocumentListener 497 * @see javax.swing.event.UndoableEditEvent 498 * @see javax.swing.event.UndoableEditListener 499 */ insertString(int offset, String str, AttributeSet a)500 public void insertString(int offset, String str, AttributeSet a) throws BadLocationException; 501 502 /** 503 * Fetches the text contained within the given portion 504 * of the document. 505 * 506 * @param offset the offset into the document representing the desired 507 * start of the text >= 0 508 * @param length the length of the desired string >= 0 509 * @return the text, in a String of length >= 0 510 * @exception BadLocationException some portion of the given range 511 * was not a valid part of the document. The location in the exception 512 * is the first bad position encountered. 513 */ getText(int offset, int length)514 public String getText(int offset, int length) throws BadLocationException; 515 516 /** 517 * Fetches the text contained within the given portion 518 * of the document. 519 * <p> 520 * If the partialReturn property on the txt parameter is false, the 521 * data returned in the Segment will be the entire length requested and 522 * may or may not be a copy depending upon how the data was stored. 523 * If the partialReturn property is true, only the amount of text that 524 * can be returned without creating a copy is returned. Using partial 525 * returns will give better performance for situations where large 526 * parts of the document are being scanned. The following is an example 527 * of using the partial return to access the entire document: 528 * 529 * <pre><code> 530 * 531 * int nleft = doc.getDocumentLength(); 532 * Segment text = new Segment(); 533 * int offs = 0; 534 * text.setPartialReturn(true); 535 * while (nleft > 0) { 536 * doc.getText(offs, nleft, text); 537 * // do someting with text 538 * nleft -= text.count; 539 * offs += text.count; 540 * } 541 * 542 * </code></pre> 543 * 544 * @param offset the offset into the document representing the desired 545 * start of the text >= 0 546 * @param length the length of the desired string >= 0 547 * @param txt the Segment object to return the text in 548 * 549 * @exception BadLocationException Some portion of the given range 550 * was not a valid part of the document. The location in the exception 551 * is the first bad position encountered. 552 */ getText(int offset, int length, Segment txt)553 public void getText(int offset, int length, Segment txt) throws BadLocationException; 554 555 /** 556 * Returns a position that represents the start of the document. The 557 * position returned can be counted on to track change and stay 558 * located at the beginning of the document. 559 * 560 * @return the position 561 */ getStartPosition()562 public Position getStartPosition(); 563 564 /** 565 * Returns a position that represents the end of the document. The 566 * position returned can be counted on to track change and stay 567 * located at the end of the document. 568 * 569 * @return the position 570 */ getEndPosition()571 public Position getEndPosition(); 572 573 /** 574 * This method allows an application to mark a place in 575 * a sequence of character content. This mark can then be 576 * used to tracks change as insertions and removals are made 577 * in the content. The policy is that insertions always 578 * occur prior to the current position (the most common case) 579 * unless the insertion location is zero, in which case the 580 * insertion is forced to a position that follows the 581 * original position. 582 * 583 * @param offs the offset from the start of the document >= 0 584 * @return the position 585 * @exception BadLocationException if the given position does not 586 * represent a valid location in the associated document 587 */ createPosition(int offs)588 public Position createPosition(int offs) throws BadLocationException; 589 590 /** 591 * Returns all of the root elements that are defined. 592 * <p> 593 * Typically there will be only one document structure, but the interface 594 * supports building an arbitrary number of structural projections over the 595 * text data. The document can have multiple root elements to support 596 * multiple document structures. Some examples might be: 597 * </p> 598 * <ul> 599 * <li>Text direction. 600 * <li>Lexical token streams. 601 * <li>Parse trees. 602 * <li>Conversions to formats other than the native format. 603 * <li>Modification specifications. 604 * <li>Annotations. 605 * </ul> 606 * 607 * @return the root element 608 */ getRootElements()609 public Element[] getRootElements(); 610 611 /** 612 * Returns the root element that views should be based upon, 613 * unless some other mechanism for assigning views to element 614 * structures is provided. 615 * 616 * @return the root element 617 */ getDefaultRootElement()618 public Element getDefaultRootElement(); 619 620 /** 621 * Allows the model to be safely rendered in the presence 622 * of concurrency, if the model supports being updated asynchronously. 623 * The given runnable will be executed in a way that allows it 624 * to safely read the model with no changes while the runnable 625 * is being executed. The runnable itself may <em>not</em> 626 * make any mutations. 627 * 628 * @param r a <code>Runnable</code> used to render the model 629 */ render(Runnable r)630 public void render(Runnable r); 631 632 /** 633 * The property name for the description of the stream 634 * used to initialize the document. This should be used 635 * if the document was initialized from a stream and 636 * anything is known about the stream. 637 */ 638 public static final String StreamDescriptionProperty = "stream"; 639 640 /** 641 * The property name for the title of the document, if 642 * there is one. 643 */ 644 public static final String TitleProperty = "title"; 645 646 647 } 648
