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 */ getOffset()50 public int getOffset(); 51 52 /** 53 * Returns the length of the change. 54 * 55 * @return the length >= 0 56 */ getLength()57 public int getLength(); 58 59 /** 60 * Gets the document that sourced the change event. 61 * 62 * @return the document 63 */ getDocument()64 public Document getDocument(); 65 66 /** 67 * Gets the type of event. 68 * 69 * @return the type 70 */ getType()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 */ getChange(Element elem)102 public ElementChange getChange(Element elem); 103 104 /** 105 * Enumeration for document event types 106 */ 107 public static final class EventType { 108 EventType(String s)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 */ toString()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 */ getElement()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 */ getIndex()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 */ getChildrenRemoved()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 */ getChildrenAdded()180 public Element[] getChildrenAdded(); 181 182 } 183 } 184