001 /*
002 * Copyright 1997-2000 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.event;
026
027 import javax.swing.undo.*;
028 import javax.swing.text.*;
029
030 /**
031 * Interface for document change notifications. This provides
032 * detailed information to Document observers about how the
033 * Document changed. It provides high level information such
034 * as type of change and where it occurred, as well as the more
035 * detailed structural changes (What Elements were inserted and
036 * removed).
037 *
038 * @author Timothy Prinzing
039 * @version 1.30 05/05/07
040 * @see javax.swing.text.Document
041 * @see DocumentListener
042 */
043 public interface DocumentEvent {
044
045 /**
046 * Returns the offset within the document of the start
047 * of the change.
048 *
049 * @return the offset >= 0
050 */
051 public int getOffset();
052
053 /**
054 * Returns the length of the change.
055 *
056 * @return the length >= 0
057 */
058 public int getLength();
059
060 /**
061 * Gets the document that sourced the change event.
062 *
063 * @return the document
064 */
065 public Document getDocument();
066
067 /**
068 * Gets the type of event.
069 *
070 * @return the type
071 */
072 public EventType getType();
073
074 /**
075 * Gets the change information for the given element.
076 * The change information describes what elements were
077 * added and removed and the location. If there were
078 * no changes, null is returned.
079 * <p>
080 * This method is for observers to discover the structural
081 * changes that were made. This means that only elements
082 * that existed prior to the mutation (and still exist after
083 * the mutatino) need to have ElementChange records.
084 * The changes made available need not be recursive.
085 * <p>
086 * For example, if the an element is removed from it's
087 * parent, this method should report that the parent
088 * changed and provide an ElementChange implementation
089 * that describes the change to the parent. If the
090 * child element removed had children, these elements
091 * do not need to be reported as removed.
092 * <p>
093 * If an child element is insert into a parent element,
094 * the parent element should report a change. If the
095 * child element also had elements inserted into it
096 * (grandchildren to the parent) these elements need
097 * not report change.
098 *
099 * @param elem the element
100 * @return the change information, or null if the
101 * element was not modified
102 */
103 public ElementChange getChange(Element elem);
104
105 /**
106 * Enumeration for document event types
107 */
108 public static final class EventType {
109
110 private EventType(String s) {
111 typeString = s;
112 }
113
114 /**
115 * Insert type.
116 */
117 public static final EventType INSERT = new EventType("INSERT");
118
119 /**
120 * Remove type.
121 */
122 public static final EventType REMOVE = new EventType("REMOVE");
123
124 /**
125 * Change type.
126 */
127 public static final EventType CHANGE = new EventType("CHANGE");
128
129 /**
130 * Converts the type to a string.
131 *
132 * @return the string
133 */
134 public String toString() {
135 return typeString;
136 }
137
138 private String typeString;
139 }
140
141 /**
142 * Describes changes made to a specific element.
143 */
144 public interface ElementChange {
145
146 /**
147 * Returns the element represented. This is the element
148 * that was changed.
149 *
150 * @return the element
151 */
152 public Element getElement();
153
154 /**
155 * Fetches the index within the element represented.
156 * This is the location that children were added
157 * and/or removed.
158 *
159 * @return the index >= 0
160 */
161 public int getIndex();
162
163 /**
164 * Gets the child elements that were removed from the
165 * given parent element. The element array returned is
166 * sorted in the order that the elements used to lie in
167 * the document, and must be contiguous.
168 *
169 * @return the child elements
170 */
171 public Element[] getChildrenRemoved();
172
173 /**
174 * Gets the child elements that were added to the given
175 * parent element. The element array returned is in the
176 * order that the elements lie in the document, and must
177 * be contiguous.
178 *
179 * @return the child elements
180 */
181 public Element[] getChildrenAdded();
182
183 }
184 }
|