1. /*
  2. * @(#)ContainerEvent.java 1.18 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt.event;
  8. import java.awt.AWTEvent;
  9. import java.awt.Container;
  10. import java.awt.Component;
  11. /**
  12. * A low-level event which indicates that a container's contents
  13. * changed because a component was added or removed.
  14. * <P>
  15. * Container events are provided for notification purposes ONLY;
  16. * The AWT will automatically handle changes to the containers
  17. * contents internally so that the program works properly regardless of
  18. * whether the program is receiving these events or not.
  19. * <P>
  20. * This low-level event is generated by a container object (such as a
  21. * Panel) when a component is added to it or removed from it.
  22. * The event is passed to every <code>ContainerListener</code>
  23. * or <code>ContainerAdapter</code> object which registered to receive such
  24. * events using the component's <code>addContainerListener</code> method.
  25. * (<code>ContainerAdapter</code> objects implement the
  26. * <code>ContainerListener</code> interface.) Each such listener object
  27. * gets this <code>ContainerEvent</code> when the event occurs.
  28. *
  29. * @see ContainerAdapter
  30. * @see ContainerListener
  31. * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/containerlistener.html">Tutorial: Writing a Container Listener</a>
  32. * @see <a href="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>
  33. *
  34. * @author Tim Prinzing
  35. * @author Amy Fowler
  36. * @version 1.18 12/19/03
  37. * @since 1.1
  38. */
  39. public class ContainerEvent extends ComponentEvent {
  40. /**
  41. * The first number in the range of ids used for container events.
  42. */
  43. public static final int CONTAINER_FIRST = 300;
  44. /**
  45. * The last number in the range of ids used for container events.
  46. */
  47. public static final int CONTAINER_LAST = 301;
  48. /**
  49. * This event indicates that a component was added to the container.
  50. */
  51. public static final int COMPONENT_ADDED = CONTAINER_FIRST;
  52. /**
  53. * This event indicates that a component was removed from the container.
  54. */
  55. public static final int COMPONENT_REMOVED = 1 + CONTAINER_FIRST;
  56. /**
  57. * The non-null component that is being added or
  58. * removed from the Container.
  59. *
  60. * @serial
  61. * @see #getChild()
  62. */
  63. Component child;
  64. /*
  65. * JDK 1.1 serialVersionUID
  66. */
  67. private static final long serialVersionUID = -4114942250539772041L;
  68. /**
  69. * Constructs a <code>ContainerEvent</code> object.
  70. * <p>Note that passing in an invalid <code>id</code> results in
  71. * unspecified behavior. This method throws an
  72. * <code>IllegalArgumentException</code> if <code>source</code>
  73. * is <code>null</code>.
  74. *
  75. * @param source the <code>Component</code> object (container)
  76. * that originated the event
  77. * @param id an integer indicating the type of event
  78. * @param child the component that was added or removed
  79. * @throws IllegalArgumentException if <code>source</code> is null
  80. */
  81. public ContainerEvent(Component source, int id, Component child) {
  82. super(source, id);
  83. this.child = child;
  84. }
  85. /**
  86. * Returns the originator of the event.
  87. *
  88. * @return the <code>Container</code> object that originated
  89. * the event, or <code>null</code> if the object is not a
  90. * <code>Container</code>.
  91. */
  92. public Container getContainer() {
  93. return (source instanceof Container) ? (Container)source : null;
  94. }
  95. /**
  96. * Returns the component that was affected by the event.
  97. *
  98. * @return the Component object that was added or removed
  99. */
  100. public Component getChild() {
  101. return child;
  102. }
  103. /**
  104. * Returns a parameter string identifying this event.
  105. * This method is useful for event-logging and for debugging.
  106. *
  107. * @return a string identifying the event and its attributes
  108. */
  109. public String paramString() {
  110. String typeStr;
  111. switch(id) {
  112. case COMPONENT_ADDED:
  113. typeStr = "COMPONENT_ADDED";
  114. break;
  115. case COMPONENT_REMOVED:
  116. typeStr = "COMPONENT_REMOVED";
  117. break;
  118. default:
  119. typeStr = "unknown type";
  120. }
  121. return typeStr + ",child="+child.getName();
  122. }
  123. }