001 /*
002 * Copyright 1996-2007 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
026 package java.awt.event;
027
028 import java.awt.Container;
029 import java.awt.Component;
030
031 /**
032 * A low-level event which indicates that a container's contents
033 * changed because a component was added or removed.
034 * <P>
035 * Container events are provided for notification purposes ONLY;
036 * The AWT will automatically handle changes to the containers
037 * contents internally so that the program works properly regardless of
038 * whether the program is receiving these events or not.
039 * <P>
040 * This low-level event is generated by a container object (such as a
041 * Panel) when a component is added to it or removed from it.
042 * The event is passed to every <code>ContainerListener</code>
043 * or <code>ContainerAdapter</code> object which registered to receive such
044 * events using the component's <code>addContainerListener</code> method.
045 * (<code>ContainerAdapter</code> objects implement the
046 * <code>ContainerListener</code> interface.) Each such listener object
047 * gets this <code>ContainerEvent</code> when the event occurs.
048 *
049 * @see ContainerAdapter
050 * @see ContainerListener
051 * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/containerlistener.html">Tutorial: Writing a Container Listener</a>
052 *
053 * @author Tim Prinzing
054 * @author Amy Fowler
055 * @version 1.28 06/05/07
056 * @since 1.1
057 */
058 public class ContainerEvent extends ComponentEvent {
059
060 /**
061 * The first number in the range of ids used for container events.
062 */
063 public static final int CONTAINER_FIRST = 300;
064
065 /**
066 * The last number in the range of ids used for container events.
067 */
068 public static final int CONTAINER_LAST = 301;
069
070 /**
071 * This event indicates that a component was added to the container.
072 */
073 public static final int COMPONENT_ADDED = CONTAINER_FIRST;
074
075 /**
076 * This event indicates that a component was removed from the container.
077 */
078 public static final int COMPONENT_REMOVED = 1 + CONTAINER_FIRST;
079
080 /**
081 * The non-null component that is being added or
082 * removed from the Container.
083 *
084 * @serial
085 * @see #getChild()
086 */
087 Component child;
088
089 /*
090 * JDK 1.1 serialVersionUID
091 */
092 private static final long serialVersionUID = -4114942250539772041L;
093
094 /**
095 * Constructs a <code>ContainerEvent</code> object.
096 * <p>Note that passing in an invalid <code>id</code> results in
097 * unspecified behavior. This method throws an
098 * <code>IllegalArgumentException</code> if <code>source</code>
099 * is <code>null</code>.
100 *
101 * @param source the <code>Component</code> object (container)
102 * that originated the event
103 * @param id an integer indicating the type of event
104 * @param child the component that was added or removed
105 * @throws IllegalArgumentException if <code>source</code> is null
106 */
107 public ContainerEvent(Component source, int id, Component child) {
108 super (source, id);
109 this .child = child;
110 }
111
112 /**
113 * Returns the originator of the event.
114 *
115 * @return the <code>Container</code> object that originated
116 * the event, or <code>null</code> if the object is not a
117 * <code>Container</code>.
118 */
119 public Container getContainer() {
120 return (source instanceof Container) ? (Container) source
121 : null;
122 }
123
124 /**
125 * Returns the component that was affected by the event.
126 *
127 * @return the Component object that was added or removed
128 */
129 public Component getChild() {
130 return child;
131 }
132
133 /**
134 * Returns a parameter string identifying this event.
135 * This method is useful for event-logging and for debugging.
136 *
137 * @return a string identifying the event and its attributes
138 */
139 public String paramString() {
140 String typeStr;
141 switch (id) {
142 case COMPONENT_ADDED:
143 typeStr = "COMPONENT_ADDED";
144 break;
145 case COMPONENT_REMOVED:
146 typeStr = "COMPONENT_REMOVED";
147 break;
148 default:
149 typeStr = "unknown type";
150 }
151 return typeStr + ",child=" + child.getName();
152 }
153 }
|