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