001 /*
002 * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.swing.text;
026
027 import javax.swing.event.*;
028
029 /**
030 * <p>
031 * The <code>Document</code> is a container for text that serves
032 * as the model for swing text components. The goal for this
033 * interface is to scale from very simple needs (a plain text textfield)
034 * to complex needs (an HTML or XML document, for example).
035 *
036 * <p><b><font size=+1>Content</font></b>
037 * <p>
038 * At the simplest level, text can be
039 * modeled as a linear sequence of characters. To support
040 * internationalization, the Swing text model uses
041 * <a href="http://www.unicode.org/">unicode</a> characters.
042 * The sequence of characters displayed in a text component is
043 * generally referred to as the component's <em>content</em>.
044 * <p>
045 * To refer to locations within the sequence, the coordinates
046 * used are the location between two characters. As the diagram
047 * below shows, a location in a text document can be referred to
048 * as a position, or an offset. This position is zero-based.
049 * <p align=center><img src="doc-files/Document-coord.gif"
050 * alt="The following text describes this graphic.">
051 * <p>
052 * In the example, if the content of a document is the
053 * sequence "The quick brown fox," as shown in the preceding diagram,
054 * the location just before the word "The" is 0, and the location after
055 * the word "The" and before the whitespace that follows it is 3.
056 * The entire sequence of characters in the sequence "The" is called a
057 * <em>range</em>.
058 * <p>The following methods give access to the character data
059 * that makes up the content.
060 * <ul>
061 * <li><a href="#getLength()">getLength()</a>
062 * <li><a href="#getText(int, int)">getText(int, int)</a>
063 * <li><a href="#getText(int, int, javax.swing.text.Segment)">getText(int, int, Segment)</a>
064 * </ul>
065 * <p><b><font size=+1>Structure</font></b>
066 * <p>
067 * Text is rarely represented simply as featureless content. Rather,
068 * text typically has some sort of structure associated with it.
069 * Exactly what structure is modeled is up to a particular Document
070 * implementation. It might be as simple as no structure (i.e. a
071 * simple text field), or it might be something like diagram below.
072 * <p align=center><img src="doc-files/Document-structure.gif"
073 * alt="Diagram shows Book->Chapter->Paragraph">
074 * <p>
075 * The unit of structure (i.e. a node of the tree) is referred to
076 * by the <a href="Element.html">Element</a> interface. Each Element
077 * can be tagged with a set of attributes. These attributes
078 * (name/value pairs) are defined by the
079 * <a href="AttributeSet.html">AttributeSet</a> interface.
080 * <p>The following methods give access to the document structure.
081 * <ul>
082 * <li><a href="#getDefaultRootElement()">getDefaultRootElement</a>
083 * <li><a href="#getRootElements()">getRootElements</a>
084 * </ul>
085 *
086 * <p><b><font size=+1>Mutations</font></b>
087 * <p>
088 * All documents need to be able to add and remove simple text.
089 * Typically, text is inserted and removed via gestures from
090 * a keyboard or a mouse. What effect the insertion or removal
091 * has upon the document structure is entirely up to the
092 * implementation of the document.
093 * <p>The following methods are related to mutation of the
094 * document content:
095 * <ul>
096 * <li><a href="#insertString(int, java.lang.String, javax.swing.text.AttributeSet)">insertString(int, String, AttributeSet)</a>
097 * <li><a href="#remove(int, int)">remove(int, int)</a>
098 * <li><a href="#createPosition(int)">createPosition(int)</a>
099 * </ul>
100 *
101 * <p><b><font size=+1>Notification</font></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 align=center><img src="doc-files/Document-notification.gif"
126 * alt="The preceeding 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><font size=+1>Properties</font></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><a href="#getProperty(java.lang.Object)">getProperty(Object)</a>
165 * <li><a href="#putProperty(java.lang.Object, java.lang.Object)">putProperty(Object, Object)</a>
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 * @version 1.50 05/05/07
176 *
177 * @see javax.swing.event.DocumentEvent
178 * @see javax.swing.event.DocumentListener
179 * @see javax.swing.event.UndoableEditEvent
180 * @see javax.swing.event.UndoableEditListener
181 * @see Element
182 * @see Position
183 * @see AttributeSet
184 */
185 public interface Document {
186
187 /**
188 * Returns number of characters of content currently
189 * in the document.
190 *
191 * @return number of characters >= 0
192 */
193 public int getLength();
194
195 /**
196 * Registers the given observer to begin receiving notifications
197 * when changes are made to the document.
198 *
199 * @param listener the observer to register
200 * @see Document#removeDocumentListener
201 */
202 public void addDocumentListener(DocumentListener listener);
203
204 /**
205 * Unregisters the given observer from the notification list
206 * so it will no longer receive change updates.
207 *
208 * @param listener the observer to register
209 * @see Document#addDocumentListener
210 */
211 public void removeDocumentListener(DocumentListener listener);
212
213 /**
214 * Registers the given observer to begin receiving notifications
215 * when undoable edits are made to the document.
216 *
217 * @param listener the observer to register
218 * @see javax.swing.event.UndoableEditEvent
219 */
220 public void addUndoableEditListener(UndoableEditListener listener);
221
222 /**
223 * Unregisters the given observer from the notification list
224 * so it will no longer receive updates.
225 *
226 * @param listener the observer to register
227 * @see javax.swing.event.UndoableEditEvent
228 */
229 public void removeUndoableEditListener(UndoableEditListener listener);
230
231 /**
232 * Gets the properties associated with the document.
233 *
234 * @param key a non-<code>null</code> property key
235 * @return the properties
236 * @see #putProperty(Object, Object)
237 */
238 public Object getProperty(Object key);
239
240 /**
241 * Associates a property with the document. Two standard
242 * property keys provided are: <a href="#StreamDescriptionProperty">
243 * <code>StreamDescriptionProperty</code></a> and
244 * <a href="#TitleProperty"><code>TitleProperty</code></a>.
245 * Other properties, such as author, may also be defined.
246 *
247 * @param key the non-<code>null</code> property key
248 * @param value the property value
249 * @see #getProperty(Object)
250 */
251 public void putProperty(Object key, Object value);
252
253 /**
254 * Removes a portion of the content of the document.
255 * This will cause a DocumentEvent of type
256 * DocumentEvent.EventType.REMOVE to be sent to the
257 * registered DocumentListeners, unless an exception
258 * is thrown. The notification will be sent to the
259 * listeners by calling the removeUpdate method on the
260 * DocumentListeners.
261 * <p>
262 * To ensure reasonable behavior in the face
263 * of concurrency, the event is dispatched after the
264 * mutation has occurred. This means that by the time a
265 * notification of removal is dispatched, the document
266 * has already been updated and any marks created by
267 * <code>createPosition</code> have already changed.
268 * For a removal, the end of the removal range is collapsed
269 * down to the start of the range, and any marks in the removal
270 * range are collapsed down to the start of the range.
271 * <p align=center><img src="doc-files/Document-remove.gif"
272 * alt="Diagram shows removal of 'quick' from 'The quick brown fox.'">
273 * <p>
274 * If the Document structure changed as result of the removal,
275 * the details of what Elements were inserted and removed in
276 * response to the change will also be contained in the generated
277 * DocumentEvent. It is up to the implementation of a Document
278 * to decide how the structure should change in response to a
279 * remove.
280 * <p>
281 * If the Document supports undo/redo, an UndoableEditEvent will
282 * also be generated.
283 *
284 * @param offs the offset from the beginning >= 0
285 * @param len the number of characters to remove >= 0
286 * @exception BadLocationException some portion of the removal range
287 * was not a valid part of the document. The location in the exception
288 * is the first bad position encountered.
289 * @see javax.swing.event.DocumentEvent
290 * @see javax.swing.event.DocumentListener
291 * @see javax.swing.event.UndoableEditEvent
292 * @see javax.swing.event.UndoableEditListener
293 */
294 public void remove(int offs, int len) throws BadLocationException;
295
296 /**
297 * Inserts a string of content. This will cause a DocumentEvent
298 * of type DocumentEvent.EventType.INSERT to be sent to the
299 * registered DocumentListers, unless an exception is thrown.
300 * The DocumentEvent will be delivered by calling the
301 * insertUpdate method on the DocumentListener.
302 * The offset and length of the generated DocumentEvent
303 * will indicate what change was actually made to the Document.
304 * <p align=center><img src="doc-files/Document-insert.gif"
305 * alt="Diagram shows insertion of 'quick' in 'The quick brown fox'">
306 * <p>
307 * If the Document structure changed as result of the insertion,
308 * the details of what Elements were inserted and removed in
309 * response to the change will also be contained in the generated
310 * DocumentEvent. It is up to the implementation of a Document
311 * to decide how the structure should change in response to an
312 * insertion.
313 * <p>
314 * If the Document supports undo/redo, an UndoableEditEvent will
315 * also be generated.
316 *
317 * @param offset the offset into the document to insert the content >= 0.
318 * All positions that track change at or after the given location
319 * will move.
320 * @param str the string to insert
321 * @param a the attributes to associate with the inserted
322 * content. This may be null if there are no attributes.
323 * @exception BadLocationException the given insert position is not a valid
324 * position within the document
325 * @see javax.swing.event.DocumentEvent
326 * @see javax.swing.event.DocumentListener
327 * @see javax.swing.event.UndoableEditEvent
328 * @see javax.swing.event.UndoableEditListener
329 */
330 public void insertString(int offset, String str, AttributeSet a)
331 throws BadLocationException;
332
333 /**
334 * Fetches the text contained within the given portion
335 * of the document.
336 *
337 * @param offset the offset into the document representing the desired
338 * start of the text >= 0
339 * @param length the length of the desired string >= 0
340 * @return the text, in a String of length >= 0
341 * @exception BadLocationException some portion of the given range
342 * was not a valid part of the document. The location in the exception
343 * is the first bad position encountered.
344 */
345 public String getText(int offset, int length)
346 throws BadLocationException;
347
348 /**
349 * Fetches the text contained within the given portion
350 * of the document.
351 * <p>
352 * If the partialReturn property on the txt parameter is false, the
353 * data returned in the Segment will be the entire length requested and
354 * may or may not be a copy depending upon how the data was stored.
355 * If the partialReturn property is true, only the amount of text that
356 * can be returned without creating a copy is returned. Using partial
357 * returns will give better performance for situations where large
358 * parts of the document are being scanned. The following is an example
359 * of using the partial return to access the entire document:
360 * <p>
361 * <pre><code>
362 *
363 * int nleft = doc.getDocumentLength();
364 * Segment text = new Segment();
365 * int offs = 0;
366 * text.setPartialReturn(true);
367 * while (nleft > 0) {
368 * doc.getText(offs, nleft, text);
369 * // do someting with text
370 * nleft -= text.count;
371 * offs += text.count;
372 * }
373 *
374 * </code></pre>
375 *
376 * @param offset the offset into the document representing the desired
377 * start of the text >= 0
378 * @param length the length of the desired string >= 0
379 * @param txt the Segment object to return the text in
380 *
381 * @exception BadLocationException Some portion of the given range
382 * was not a valid part of the document. The location in the exception
383 * is the first bad position encountered.
384 */
385 public void getText(int offset, int length, Segment txt)
386 throws BadLocationException;
387
388 /**
389 * Returns a position that represents the start of the document. The
390 * position returned can be counted on to track change and stay
391 * located at the beginning of the document.
392 *
393 * @return the position
394 */
395 public Position getStartPosition();
396
397 /**
398 * Returns a position that represents the end of the document. The
399 * position returned can be counted on to track change and stay
400 * located at the end of the document.
401 *
402 * @return the position
403 */
404 public Position getEndPosition();
405
406 /**
407 * This method allows an application to mark a place in
408 * a sequence of character content. This mark can then be
409 * used to tracks change as insertions and removals are made
410 * in the content. The policy is that insertions always
411 * occur prior to the current position (the most common case)
412 * unless the insertion location is zero, in which case the
413 * insertion is forced to a position that follows the
414 * original position.
415 *
416 * @param offs the offset from the start of the document >= 0
417 * @return the position
418 * @exception BadLocationException if the given position does not
419 * represent a valid location in the associated document
420 */
421 public Position createPosition(int offs)
422 throws BadLocationException;
423
424 /**
425 * Returns all of the root elements that are defined.
426 * <p>
427 * Typically there will be only one document structure, but the interface
428 * supports building an arbitrary number of structural projections over the
429 * text data. The document can have multiple root elements to support
430 * multiple document structures. Some examples might be:
431 * </p>
432 * <ul>
433 * <li>Text direction.
434 * <li>Lexical token streams.
435 * <li>Parse trees.
436 * <li>Conversions to formats other than the native format.
437 * <li>Modification specifications.
438 * <li>Annotations.
439 * </ul>
440 *
441 * @return the root element
442 */
443 public Element[] getRootElements();
444
445 /**
446 * Returns the root element that views should be based upon,
447 * unless some other mechanism for assigning views to element
448 * structures is provided.
449 *
450 * @return the root element
451 */
452 public Element getDefaultRootElement();
453
454 /**
455 * Allows the model to be safely rendered in the presence
456 * of concurrency, if the model supports being updated asynchronously.
457 * The given runnable will be executed in a way that allows it
458 * to safely read the model with no changes while the runnable
459 * is being executed. The runnable itself may <em>not</em>
460 * make any mutations.
461 *
462 * @param r a <code>Runnable</code> used to render the model
463 */
464 public void render(Runnable r);
465
466 /**
467 * The property name for the description of the stream
468 * used to initialize the document. This should be used
469 * if the document was initialized from a stream and
470 * anything is known about the stream.
471 */
472 public static final String StreamDescriptionProperty = "stream";
473
474 /**
475 * The property name for the title of the document, if
476 * there is one.
477 */
478 public static final String TitleProperty = "title";
479
480 }
|