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