1 /* 2 * Copyright (c) 1996, 2008, 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 26 package java.awt.event; 27 28 import java.awt.Container; 29 import java.awt.Component; 30 31 /** 32 * A low-level event which indicates that a container's contents 33 * changed because a component was added or removed. 34 * <P> 35 * Container events are provided for notification purposes ONLY; 36 * The AWT will automatically handle changes to the containers 37 * contents internally so that the program works properly regardless of 38 * whether the program is receiving these events or not. 39 * <P> 40 * This low-level event is generated by a container object (such as a 41 * Panel) when a component is added to it or removed from it. 42 * The event is passed to every <code>ContainerListener</code> 43 * or <code>ContainerAdapter</code> object which registered to receive such 44 * events using the component's <code>addContainerListener</code> method. 45 * (<code>ContainerAdapter</code> objects implement the 46 * <code>ContainerListener</code> interface.) Each such listener object 47 * gets this <code>ContainerEvent</code> when the event occurs. 48 * <p> 49 * An unspecified behavior will be caused if the {@code id} parameter 50 * of any particular {@code ContainerEvent} instance is not 51 * in the range from {@code CONTAINER_FIRST} to {@code CONTAINER_LAST}. 52 * 53 * @see ContainerAdapter 54 * @see ContainerListener 55 * @see <a href="http://docs.oracle.com/javase/tutorial/uiswing/events/containerlistener.html">Tutorial: Writing a Container Listener</a> 56 * 57 * @author Tim Prinzing 58 * @author Amy Fowler 59 * @since 1.1 60 */ 61 public class ContainerEvent extends ComponentEvent { 62 63 /** 64 * The first number in the range of ids used for container events. 65 */ 66 public static final int CONTAINER_FIRST = 300; 67 68 /** 69 * The last number in the range of ids used for container events. 70 */ 71 public static final int CONTAINER_LAST = 301; 72 73 /** 74 * This event indicates that a component was added to the container. 75 */ 76 public static final int COMPONENT_ADDED = CONTAINER_FIRST; 77 78 /** 79 * This event indicates that a component was removed from the container. 80 */ 81 public static final int COMPONENT_REMOVED = 1 + CONTAINER_FIRST; 82 83 /** 84 * The non-null component that is being added or 85 * removed from the Container. 86 * 87 * @serial 88 * @see #getChild() 89 */ 90 Component child; 91 92 /* 93 * JDK 1.1 serialVersionUID 94 */ 95 private static final long serialVersionUID = -4114942250539772041L; 96 97 /** 98 * Constructs a <code>ContainerEvent</code> object. 99 * <p> This method throws an 100 * <code>IllegalArgumentException</code> if <code>source</code> 101 * is <code>null</code>. 102 * 103 * @param source The <code>Component</code> object (container) 104 * that originated the event 105 * @param id An integer indicating the type of event. 106 * For information on allowable values, see 107 * the class description for {@link ContainerEvent} 108 * @param child the component that was added or removed 109 * @throws IllegalArgumentException if <code>source</code> is null 110 * @see #getContainer() 111 * @see #getID() 112 * @see #getChild() 113 */ 114 public ContainerEvent(Component source, int id, Component child) { 115 super(source, id); 116 this.child = child; 117 } 118 119 /** 120 * Returns the originator of the event. 121 * 122 * @return the <code>Container</code> object that originated 123 * the event, or <code>null</code> if the object is not a 124 * <code>Container</code>. 125 */ 126 public Container getContainer() { 127 return (source instanceof Container) ? (Container)source : null; 128 } 129 130 /** 131 * Returns the component that was affected by the event. 132 * 133 * @return the Component object that was added or removed 134 */ 135 public Component getChild() { 136 return child; 137 } 138 139 /** 140 * Returns a parameter string identifying this event. 141 * This method is useful for event-logging and for debugging. 142 * 143 * @return a string identifying the event and its attributes 144 */ 145 public String paramString() { 146 String typeStr; 147 switch(id) { 148 case COMPONENT_ADDED: 149 typeStr = "COMPONENT_ADDED"; 150 break; 151 case COMPONENT_REMOVED: 152 typeStr = "COMPONENT_REMOVED"; 153 break; 154 default: 155 typeStr = "unknown type"; 156 } 157 return typeStr + ",child="+child.getName(); 158 } 159 }