1. /*
  2. * @(#)Document.java 1.40 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.swing.text;
  8. import javax.swing.event.*;
  9. /**
  10. * <p>
  11. * The <code>Document</code> is a container for text that serves
  12. * as the model for swing text components. The goal for this
  13. * interface is to scale from very simple needs (a plain text textfield)
  14. * to complex needs (an HTML or XML document, for example).
  15. *
  16. * <p><b><font size=+1>Content</font></b>
  17. * <p>
  18. * At the simplest level, text can be
  19. * modeled as a linear sequence of characters. To support
  20. * internationalization, the Swing text model uses
  21. * <a href="http://www.unicode.org/">unicode</a> characters.
  22. * The sequence of characters displayed in a text component is
  23. * generally referred to as the component's <em>content</em>.
  24. * <p>
  25. * To refer to locations within the sequence, the coordinates
  26. * used are the location between two characters. As the diagram
  27. * below shows, a location in a text document can be referred to
  28. * as a position, or an offset. This position is zero-based.
  29. * <p align=center><img src="doc-files/Document-coord.gif"
  30. * alt="The following text describes this graphic.">
  31. * <p>
  32. * In the example, if the content of a document is the
  33. * sequence "The quick brown fox," as shown in the preceding diagram,
  34. * the location just before the word "The" is 0, and the location after
  35. * the word "The" and before the whitespace that follows it is 3.
  36. * The entire sequence of characters in the sequence "The" is called a
  37. * <em>range</em>.
  38. * <p>The following methods give access to the character data
  39. * that makes up the content.
  40. * <ul>
  41. * <li><a href="#getLength()">getLength()</a>
  42. * <li><a href="#getText(int, int)">getText(int, int)</a>
  43. * <li><a href="#getText(int, int, javax.swing.text.Segment)">getText(int, int, Segment)</a>
  44. * </ul>
  45. * <p><b><font size=+1>Structure</font></b>
  46. * <p>
  47. * Text is rarely represented simply as featureless content. Rather,
  48. * text typically has some sort of structure associated with it.
  49. * Exactly what structure is modeled is up to a particular Document
  50. * implementation. It might be as simple as no structure (i.e. a
  51. * simple text field), or it might be something like diagram below.
  52. * <p align=center><img src="doc-files/Document-structure.gif"
  53. * alt="Diagram shows Book->Chapter->Paragraph">
  54. * <p>
  55. * The unit of structure (i.e. a node of the tree) is referred to
  56. * by the <a href="Element.html">Element</a> interface. Each Element
  57. * can be tagged with a set of attributes. These attributes
  58. * (name/value pairs) are defined by the
  59. * <a href="AttributeSet.html">AttributeSet</a> interface.
  60. * <p>The following methods give access to the document structure.
  61. * <ul>
  62. * <li><a href="#getDefaultRootElement()">getDefaultRootElement</a>
  63. * <li><a href="#getRootElements()">getRootElements</a>
  64. * </ul>
  65. *
  66. * <p><b><font size=+1>Mutations</font></b>
  67. * <p>
  68. * All documents need to be able to add and remove simple text.
  69. * Typically, text is inserted and removed via gestures from
  70. * a keyboard or a mouse. What effect the insertion or removal
  71. * has upon the document structure is entirely up to the
  72. * implementation of the document.
  73. * <p>The following methods are related to mutation of the
  74. * document content:
  75. * <ul>
  76. * <li><a href="#insertString(int, java.lang.String, javax.swing.text.AttributeSet)">insertString(int, String, AttributeSet)</a>
  77. * <li><a href="#remove(int, int)">remove(int, int)</a>
  78. * <li><a href="#createPosition(int)">createPosition(int)</a>
  79. * </ul>
  80. *
  81. * <p><b><font size=+1>Notification</font></b>
  82. * <p>
  83. * Mutations to the <code>Document</code> must be communicated to
  84. * interested observers. The notification of change follows the event model
  85. * guidelines that are specified for JavaBeans. In the JavaBeans
  86. * event model, once an event notification is dispatched, all listeners
  87. * must be notified before any further mutations occur to the source
  88. * of the event. Further, order of delivery is not guaranteed.
  89. * <p>
  90. * Notification is provided as two separate events,
  91. * <a href="../event/DocumentEvent.html">DocumentEvent<a>, and
  92. * <a href="../event/UndoableEditEvent.html">UndoableEditEvent</a>.
  93. * If a mutation is made to a <code>Document</code> through its api,
  94. * a <code>DocumentEvent</code> will be sent to all of the registered
  95. * <code>DocumentListeners</code>. If the <code>Document</code>
  96. * implementation supports undo/redo capabilities, an
  97. * <code>UndoableEditEvent</code> will be sent
  98. * to all of the registered <code>UndoableEditListener</code>s.
  99. * If an undoable edit is undone, a <code>DocumentEvent</code> should be
  100. * fired from the Document to indicate it has changed again.
  101. * In this case however, there should be no <code>UndoableEditEvent</code>
  102. * generated since that edit is actually the source of the change
  103. * rather than a mutation to the <code>Document</code> made through its
  104. * api.
  105. * <p align=center><img src="doc-files/Document-notification.gif"
  106. * alt="The preceeding text describes this graphic.">
  107. * <p>
  108. * Referring to the above diagram, suppose that the component shown
  109. * on the left mutates the document object represented by the blue
  110. * rectangle. The document responds by dispatching a DocumentEvent to
  111. * both component views and sends an UndoableEditEvent to the listening
  112. * logic, which maintains a history buffer.
  113. * <p>
  114. * Now suppose that the component shown on the right mutates the same
  115. * document. Again, the document dispatches a DocumentEvent to both
  116. * component views and sends an UndoableEditEvent to the listening logic
  117. * that is maintaining the history buffer.
  118. * <p>
  119. * If the history buffer is then rolled back (i.e. the last UndoableEdit
  120. * undone), a DocumentEvent is sent to both views, causing both of them to
  121. * reflect the undone mutation to the document (that is, the
  122. * removal of the right component's mutation). If the history buffer again
  123. * rolls back another change, another DocumentEvent is sent to both views,
  124. * causing them to reflect the undone mutation to the document -- that is,
  125. * the removal of the left component's mutation.
  126. * <p>
  127. * The methods related to observing mutations to the document are:
  128. * <ul>
  129. * <li><a href="#addDocumentListener(javax.swing.event.DocumentListener)">addDocumentListener(DocumentListener)</a>
  130. * <li><a href="#removeDocumentListener(javax.swing.event.DocumentListener)">removeDocumentListener(DocumentListener)</a>
  131. * <li><a href="#addUndoableEditListener(javax.swing.event.UndoableEditListener)">addUndoableEditListener(UndoableEditListener)</a>
  132. * <li><a href="#removeUndoableEditListener(javax.swing.event.UndoableEditListener)">removeUndoableEditListener(UndoableEditListener)</a>
  133. * </ul>
  134. *
  135. * <p><b><font size=+1>Properties</font></b>
  136. * <p>
  137. * Document implementations will generally have some set of properties
  138. * associated with them at runtime. Two well known properties are the
  139. * <a href="#StreamDescriptionProperty">StreamDescriptionProperty</a>,
  140. * which can be used to describe where the <code>Document</code> came from,
  141. * and the <a href="#TitleProperty">TitleProperty</a>, which can be used to
  142. * name the <code>Document</code>. The methods related to the properties are:
  143. * <ul>
  144. * <li><a href="#getProperty(java.lang.Object)">getProperty(Object)</a>
  145. * <li><a href="#putProperty(java.lang.Object, java.lang.Object)">putProperty(Object, Object)</a>
  146. * </ul>
  147. *
  148. * <p>For more information on the <code>Document</code> class, see
  149. * <a href="http://java.sun.com/products/jfc/tsc">The Swing Connection</a>
  150. * and most particularly the article,
  151. * <a href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">
  152. * The Element Interface</a>.
  153. *
  154. * @author Timothy Prinzing
  155. * @version 1.40 01/23/03
  156. *
  157. * @see javax.swing.event.DocumentEvent
  158. * @see javax.swing.event.DocumentListener
  159. * @see javax.swing.event.UndoableEditEvent
  160. * @see javax.swing.event.UndoableEditListener
  161. * @see Element
  162. * @see Position
  163. * @see AttributeSet
  164. */
  165. public interface Document {
  166. /**
  167. * Returns number of characters of content currently
  168. * in the document.
  169. *
  170. * @return number of characters >= 0
  171. */
  172. public int getLength();
  173. /**
  174. * Registers the given observer to begin receiving notifications
  175. * when changes are made to the document.
  176. *
  177. * @param listener the observer to register
  178. * @see Document#removeDocumentListener
  179. */
  180. public void addDocumentListener(DocumentListener listener);
  181. /**
  182. * Unregisters the given observer from the notification list
  183. * so it will no longer receive change updates.
  184. *
  185. * @param listener the observer to register
  186. * @see Document#addDocumentListener
  187. */
  188. public void removeDocumentListener(DocumentListener listener);
  189. /**
  190. * Registers the given observer to begin receiving notifications
  191. * when undoable edits are made to the document.
  192. *
  193. * @param listener the observer to register
  194. * @see javax.swing.event.UndoableEditEvent
  195. */
  196. public void addUndoableEditListener(UndoableEditListener listener);
  197. /**
  198. * Unregisters the given observer from the notification list
  199. * so it will no longer receive updates.
  200. *
  201. * @param listener the observer to register
  202. * @see javax.swing.event.UndoableEditEvent
  203. */
  204. public void removeUndoableEditListener(UndoableEditListener listener);
  205. /**
  206. * Gets the properties associated with the document.
  207. *
  208. * @param key a non-<code>null</code> property key
  209. * @return the properties
  210. * @see #putProperty(Object, Object)
  211. */
  212. public Object getProperty(Object key);
  213. /**
  214. * Associates a property with the document. Two standard
  215. * property keys provided are: <a href="#StreamDescriptionProperty">
  216. * <code>StreamDescriptionProperty</code></a> and
  217. * <a href="#TitleProperty"><code>TitleProperty</code></a>.
  218. * Other properties, such as author, may also be defined.
  219. *
  220. * @param key the non-<code>null</code> property key
  221. * @param value the property value
  222. * @see #getProperty(Object)
  223. */
  224. public void putProperty(Object key, Object value);
  225. /**
  226. * Removes a portion of the content of the document.
  227. * This will cause a DocumentEvent of type
  228. * DocumentEvent.EventType.REMOVE to be sent to the
  229. * registered DocumentListeners, unless an exception
  230. * is thrown. The notification will be sent to the
  231. * listeners by calling the removeUpdate method on the
  232. * DocumentListeners.
  233. * <p>
  234. * To ensure reasonable behavior in the face
  235. * of concurrency, the event is dispatched after the
  236. * mutation has occurred. This means that by the time a
  237. * notification of removal is dispatched, the document
  238. * has already been updated and any marks created by
  239. * <code>createPosition</code> have already changed.
  240. * For a removal, the end of the removal range is collapsed
  241. * down to the start of the range, and any marks in the removal
  242. * range are collapsed down to the start of the range.
  243. * <p align=center><img src="doc-files/Document-remove.gif"
  244. * alt="Diagram shows removal of 'quick' from 'The quick brown fox.'">
  245. * <p>
  246. * If the Document structure changed as result of the removal,
  247. * the details of what Elements were inserted and removed in
  248. * response to the change will also be contained in the generated
  249. * DocumentEvent. It is up to the implementation of a Document
  250. * to decide how the structure should change in response to a
  251. * remove.
  252. * <p>
  253. * If the Document supports undo/redo, an UndoableEditEvent will
  254. * also be generated.
  255. *
  256. * @param offs the offset from the beginning >= 0
  257. * @param len the number of characters to remove >= 0
  258. * @exception BadLocationException some portion of the removal range
  259. * was not a valid part of the document. The location in the exception
  260. * is the first bad position encountered.
  261. * @see javax.swing.event.DocumentEvent
  262. * @see javax.swing.event.DocumentListener
  263. * @see javax.swing.event.UndoableEditEvent
  264. * @see javax.swing.event.UndoableEditListener
  265. */
  266. public void remove(int offs, int len) throws BadLocationException;
  267. /**
  268. * Inserts a string of content. This will cause a DocumentEvent
  269. * of type DocumentEvent.EventType.INSERT to be sent to the
  270. * registered DocumentListers, unless an exception is thrown.
  271. * The DocumentEvent will be delivered by calling the
  272. * insertUpdate method on the DocumentListener.
  273. * The offset and length of the generated DocumentEvent
  274. * will indicate what change was actually made to the Document.
  275. * <p align=center><img src="doc-files/Document-insert.gif"
  276. * alt="Diagram shows insertion of 'quick' in 'The quick brown fox'">
  277. * <p>
  278. * If the Document structure changed as result of the insertion,
  279. * the details of what Elements were inserted and removed in
  280. * response to the change will also be contained in the generated
  281. * DocumentEvent. It is up to the implementation of a Document
  282. * to decide how the structure should change in response to an
  283. * insertion.
  284. * <p>
  285. * If the Document supports undo/redo, an UndoableEditEvent will
  286. * also be generated.
  287. *
  288. * @param offset the offset into the document to insert the content >= 0.
  289. * All positions that track change at or after the given location
  290. * will move.
  291. * @param str the string to insert
  292. * @param a the attributes to associate with the inserted
  293. * content. This may be null if there are no attributes.
  294. * @exception BadLocationException the given insert position is not a valid
  295. * position within the document
  296. * @see javax.swing.event.DocumentEvent
  297. * @see javax.swing.event.DocumentListener
  298. * @see javax.swing.event.UndoableEditEvent
  299. * @see javax.swing.event.UndoableEditListener
  300. */
  301. public void insertString(int offset, String str, AttributeSet a) throws BadLocationException;
  302. /**
  303. * Fetches the text contained within the given portion
  304. * of the document.
  305. *
  306. * @param offset the offset into the document representing the desired
  307. * start of the text >= 0
  308. * @param length the length of the desired string >= 0
  309. * @return the text, in a String of length >= 0
  310. * @exception BadLocationException some portion of the given range
  311. * was not a valid part of the document. The location in the exception
  312. * is the first bad position encountered.
  313. */
  314. public String getText(int offset, int length) throws BadLocationException;
  315. /**
  316. * Fetches the text contained within the given portion
  317. * of the document.
  318. * <p>
  319. * If the partialReturn property on the txt parameter is false, the
  320. * data returned in the Segment will be the entire length requested and
  321. * may or may not be a copy depending upon how the data was stored.
  322. * If the partialReturn property is true, only the amount of text that
  323. * can be returned without creating a copy is returned. Using partial
  324. * returns will give better performance for situations where large
  325. * parts of the document are being scanned. The following is an example
  326. * of using the partial return to access the entire document:
  327. * <p>
  328. * <pre><code>
  329. *
  330. *   int nleft = doc.getDocumentLength();
  331. *   Segment text = new Segment();
  332. *   int offs = 0;
  333. *   text.setPartialReturn(true);
  334. *   while (nleft > 0) {
  335. *   doc.getText(offs, nleft, text);
  336. *   // do someting with text
  337. *   nleft -= text.count;
  338. *   offs += text.count;
  339. *   }
  340. *
  341. * </code></pre>
  342. *
  343. * @param offset the offset into the document representing the desired
  344. * start of the text >= 0
  345. * @param length the length of the desired string >= 0
  346. * @param txt the Segment object to return the text in
  347. *
  348. * @exception BadLocationException Some portion of the given range
  349. * was not a valid part of the document. The location in the exception
  350. * is the first bad position encountered.
  351. */
  352. public void getText(int offset, int length, Segment txt) throws BadLocationException;
  353. /**
  354. * Returns a position that represents the start of the document. The
  355. * position returned can be counted on to track change and stay
  356. * located at the beginning of the document.
  357. *
  358. * @return the position
  359. */
  360. public Position getStartPosition();
  361. /**
  362. * Returns a position that represents the end of the document. The
  363. * position returned can be counted on to track change and stay
  364. * located at the end of the document.
  365. *
  366. * @return the position
  367. */
  368. public Position getEndPosition();
  369. /**
  370. * This method allows an application to mark a place in
  371. * a sequence of character content. This mark can then be
  372. * used to tracks change as insertions and removals are made
  373. * in the content. The policy is that insertions always
  374. * occur prior to the current position (the most common case)
  375. * unless the insertion location is zero, in which case the
  376. * insertion is forced to a position that follows the
  377. * original position.
  378. *
  379. * @param offs the offset from the start of the document >= 0
  380. * @return the position
  381. * @exception BadLocationException if the given position does not
  382. * represent a valid location in the associated document
  383. */
  384. public Position createPosition(int offs) throws BadLocationException;
  385. /**
  386. * Returns all of the root elements that are defined.
  387. * <p>
  388. * Typically there will be only one document structure, but the interface
  389. * supports building an arbitrary number of structural projections over the
  390. * text data. The document can have multiple root elements to support
  391. * multiple document structures. Some examples might be:
  392. * </p>
  393. * <ul>
  394. * <li>Text direction.
  395. * <li>Lexical token streams.
  396. * <li>Parse trees.
  397. * <li>Conversions to formats other than the native format.
  398. * <li>Modification specifications.
  399. * <li>Annotations.
  400. * </ul>
  401. *
  402. * @return the root element
  403. */
  404. public Element[] getRootElements();
  405. /**
  406. * Returns the root element that views should be based upon,
  407. * unless some other mechanism for assigning views to element
  408. * structures is provided.
  409. *
  410. * @return the root element
  411. */
  412. public Element getDefaultRootElement();
  413. /**
  414. * This allows the model to be safely rendered in the presence
  415. * of currency, if the model supports being updated asynchronously.
  416. * The given runnable will be executed in a way that allows it
  417. * to safely read the model with no changes while the runnable
  418. * is being executed. The runnable itself may <em>not</em>
  419. * make any mutations.
  420. *
  421. * @param r a Runnable used to render the model
  422. */
  423. public void render(Runnable r);
  424. /**
  425. * The property name for the description of the stream
  426. * used to initialize the document. This should be used
  427. * if the document was initialized from a stream and
  428. * anything is known about the stream.
  429. */
  430. public static final String StreamDescriptionProperty = "stream";
  431. /**
  432. * The property name for the title of the document, if
  433. * there is one.
  434. */
  435. public static final String TitleProperty = "title";
  436. }