View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 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.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 mutation) 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 &gt;= 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 }