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>
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.
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
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 }
|
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} 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>
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} 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} through its api,
114 * a {@code DocumentEvent} will be sent to all of the registered
115 * {@code DocumentListeners}. If the {@code Document}
116 * implementation supports undo/redo capabilities, an
117 * {@code UndoableEditEvent} will be sent
118 * to all of the registered {@code UndoableEditListener}s.
119 * If an undoable edit is undone, a {@code DocumentEvent} should be
120 * fired from the Document to indicate it has changed again.
121 * In this case however, there should be no {@code UndoableEditEvent}
122 * generated since that edit is actually the source of the change
123 * rather than a mutation to the {@code Document} 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} came from,
161 * and the <a href="#TitleProperty">TitleProperty</a>, which can be used to
162 * name the {@code Document}. 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} 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.
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} 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}</a> and
243 * <a href="#TitleProperty">{@code TitleProperty}</a>.
244 * Other properties, such as author, may also be defined.
245 *
246 * @param key the non-{@code null} 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} 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
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} 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 }
|