KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > event > DocumentEvent


1 /*
2  * @(#)DocumentEvent.java 1.23 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package javax.swing.event;
8
9 import javax.swing.undo.*;
10 import javax.swing.text.*;
11
12 /**
13  * Interface for document change notifications. This provides
14  * detailed information to Document observers about how the
15  * Document changed. It provides high level information such
16  * as type of change and where it occurred, as well as the more
17  * detailed structural changes (What Elements were inserted and
18  * removed).
19  *
20  * @author Timothy Prinzing
21  * @version 1.23 12/19/03
22  * @see javax.swing.text.Document
23  * @see DocumentListener
24  */
25 public interface DocumentEvent {
26
27     /**
28      * Returns the offset within the document of the start
29      * of the change.
30      *
31      * @return the offset >= 0
32      */
33     public int getOffset();
34
35     /**
36      * Returns the length of the change.
37      *
38      * @return the length >= 0
39      */
40     public int getLength();
41
42     /**
43      * Gets the document that sourced the change event.
44      *
45      * @return the document
46      */
47     public Document getDocument();
48
49     /**
50      * Gets the type of event.
51      *
52      * @return the type
53      */
54     public EventType getType();
55
56     /**
57      * Gets the change information for the given element.
58      * The change information describes what elements were
59      * added and removed and the location. If there were
60      * no changes, null is returned.
61      * <p>
62      * This method is for observers to discover the structural
63      * changes that were made. This means that only elements
64      * that existed prior to the mutation (and still exist after
65      * the mutatino) need to have ElementChange records.
66      * The changes made available need not be recursive.
67      * <p>
68      * For example, if the an element is removed from it's
69      * parent, this method should report that the parent
70      * changed and provide an ElementChange implementation
71      * that describes the change to the parent. If the
72      * child element removed had children, these elements
73      * do not need to be reported as removed.
74      * <p>
75      * If an child element is insert into a parent element,
76      * the parent element should report a change. If the
77      * child element also had elements inserted into it
78      * (grandchildren to the parent) these elements need
79      * not report change.
80      *
81      * @param elem the element
82      * @return the change information, or null if the
83      * element was not modified
84      */
85     public ElementChange getChange(Element elem);
86
87     /**
88      * Enumeration for document event types
89      */
90     public static final class EventType {
91
92         private EventType(String JavaDoc s) {
93         typeString = s;
94     }
95
96         /**
97          * Insert type.
98          */
99     public static final EventType INSERT = new EventType("INSERT");
100
101         /**
102          * Remove type.
103          */
104     public static final EventType REMOVE = new EventType("REMOVE");
105
106         /**
107          * Change type.
108          */
109     public static final EventType CHANGE = new EventType("CHANGE");
110
111         /**
112          * Converts the type to a string.
113          *
114          * @return the string
115          */
116         public String JavaDoc toString() {
117         return typeString;
118     }
119
120     private String JavaDoc typeString;
121     }
122
123     /**
124      * Describes changes made to a specific element.
125      */
126     public interface ElementChange {
127
128     /**
129      * Returns the element represented. This is the element
130      * that was changed.
131          *
132          * @return the element
133      */
134     public Element getElement();
135
136     /**
137      * Fetches the index within the element represented.
138      * This is the location that children were added
139      * and/or removed.
140          *
141          * @return the index >= 0
142      */
143     public int getIndex();
144
145     /**
146      * Gets the child elements that were removed from the
147      * given parent element. The element array returned is
148      * sorted in the order that the elements used to lie in
149      * the document, and must be contiguous.
150      *
151      * @return the child elements
152      */
153         public Element[] getChildrenRemoved();
154
155     /**
156      * Gets the child elements that were added to the given
157      * parent element. The element array returned is in the
158      * order that the elements lie in the document, and must
159      * be contiguous.
160      *
161      * @return the child elements
162      */
163         public Element[] getChildrenAdded();
164
165     }
166 }
167
Popular Tags