libjava/java/awt/event/HierarchyEvent.java

   1 /* HierarchyEvent.java -- generated for a change in hierarchy
   2    Copyright (C) 2000, 2002 Free Software Foundation
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.awt.event;
  39 import java.awt.*;
  40
  41 /**
  42  * This class represents an event generated for an ancestor component which
  43  * may affect this component. These events normally do not need to be handled
  44  * by the application, since the AWT system automatically takes care of them.
  45  *
  46  * <p>There are two types of hierarchy events. The first type is handled by
  47  * HierarchyListener, and includes addition or removal of an ancestor, or
  48  * an ancestor changing its on-screen status (visible and/or displayble). The
  49  * second type is handled by HierarchyBoundsListener, and includes resizing
  50  * or moving of an ancestor.
  51  *
  52  * @author Bryce McKinlay
  53  * @see HierarchyListener
  54  * @see HierarchyBoundsAdapter
  55  * @see HierarchyBoundsListener
  56  * @since 1.3
  57  * @status updated to 1.4
  58  */
  59 public class HierarchyEvent extends AWTEvent
  60 {
  61   /**
  62    * Compatible with JDK 1.3+.
  63    */
  64   private static final long serialVersionUID = -5337576970038043990L;
  65
  66   /** This is the first id in the range of ids used by this class. */
  67   public static final int HIERARCHY_FIRST = 1400;
  68
  69   /** This id indicates that the hierarchy tree changed. */
  70   public static final int HIERARCHY_CHANGED = 1400;
  71
  72   /** This id indicates that an ancestor was moved. */
  73   public static final int ANCESTOR_MOVED = 1401;
  74
  75   /** This id indicates that an ancestor was resized. */
  76   public static final int ANCESTOR_RESIZED = 1402;
  77
  78   /** This is the last id in the range of ids used by this class. */
  79   public static final int HIERARCHY_LAST = 1402;
  80
  81   /** This indicates that the HIERARCHY_CHANGED is a changed parent. */
  82   public static final int PARENT_CHANGED = 1;
  83
  84   /**
  85    * This indicates that the HIERARCHY_CHANGED is caused by a change in
  86    * displayability.
  87    *
  88    * @see Component#isDisplayable()
  89    * @see Component#addNotify()
  90    * @see Component#removeNotify()
  91    */
  92   public static final int DISPLAYABILITY_CHANGED = 2;
  93
  94   /**
  95    * This indicates that the HIERARCHY_CHANGED is a changed visibility.
  96    *
  97    * @see Component#isShowing()
  98    * @see Component#addNotify()
  99    * @see Component#removeNotify()
 100    * @see Component#show()
 101    * @see Component#hide()
 102    */
 103   public static final int SHOWING_CHANGED = 4;
 104
 105   /**
 106    * The component at the top of the changed hierarchy.
 107    *
 108    * @serial the top component changed
 109    */
 110   private final Component changed;
 111
 112   /**
 113    * The parent of this component, either before or after the change depending
 114    * on the type of change.
 115    *
 116    * @serial the parent component changed
 117    */
 118   private final Container changedParent;
 119
 120   /**
 121    * The bitmask of HIERARCHY_CHANGED event types.
 122    *
 123    * @serial the change flags
 124    */
 125   private final long changeFlags;
 126
 127   /**
 128    * Initializes a new instance of <code>HierarchyEvent</code> with the
 129    * specified parameters. Note that an invalid id leads to unspecified
 130    * results.
 131    *
 132    * @param source the component whose hierarchy changed
 133    * @param id the event id
 134    * @param changed the top component in the tree of changed hierarchy
 135    * @param changedParent the updated parent of this object
 136    * @throws IllegalArgumentException if source is null
 137    */
 138   public HierarchyEvent(Component source, int id, Component changed,
 139                         Container changedParent)
 140   {
 141     this(source, id, changed, changedParent, 0);
 142   }
 143
 144   /**
 145    * Initializes a new instance of <code>HierarchyEvent</code> with the
 146    * specified parameters. Note that an invalid id leads to unspecified
 147    * results.
 148    *
 149    * @param source the component whose hierarchy changed
 150    * @param id the event id
 151    * @param changed the top component in the tree of changed hierarchy
 152    * @param changedParent the updated parent of this object
 153    * @param changeFlags the bitmask of specific HIERARCHY_CHANGED events
 154    * @throws IllegalArgumentException if source is null
 155    */
 156   public HierarchyEvent(Component source, int id, Component changed,
 157                         Container changedParent, long changeFlags)
 158   {
 159     super(source, id);
 160     this.changed = changed;
 161     this.changedParent = changedParent;
 162     this.changeFlags = changeFlags;
 163   }
 164
 165   /**
 166    * This method returns the event source as a <code>Component</code>. If the
 167    * source has subsequently been modified to a non-Component, this returns
 168    * null.
 169    *
 170    * @return the event source as a <code>Component</code>, or null
 171    */
 172   public Component getComponent()
 173   {
 174     return source instanceof Component ? (Component) source : null;
 175   }
 176
 177   /**
 178    * Returns the component at the top of the hierarchy which changed.
 179    *
 180    * @return the top changed component
 181    */
 182   public Component getChanged()
 183   {
 184     return changed;
 185   }
 186
 187   /**
 188    * Returns the parent of the component listed in <code>getChanged()</code>.
 189    * If the cause of this event was <code>Container.add</code>, this is the
 190    * new parent; if the cause was <code>Container.remove</code>, this is the
 191    * old parent; otherwise it is the unchanged parent.
 192    *
 193    * @return the parent container of the changed component
 194    */
 195   public Container getChangedParent()
 196   {
 197     return changedParent;
 198   }
 199
 200   /**
 201    * If this is a HIERARCHY_CHANGED event, this returns a bitmask of the
 202    * types of changes that took place.
 203    *
 204    * @return the bitwise or of hierarchy change types, or 0
 205    * @see #PARENT_CHANGED
 206    * @see #DISPLAYABILITY_CHANGED
 207    * @see #SHOWING_CHANGED
 208    */
 209   public long getChangeFlags()
 210   {
 211     return changeFlags;
 212   }
 213
 214   /**
 215    * This method returns a string identifying this event. This is the field
 216    * name of the id type, followed by a parenthesized listing of the changed
 217    * component and its parent container. In addition, if the type is
 218    * HIERARCHY_CHANGED, the flags preceed the changed component, in the
 219    * order PARENT_CHANGED, DISPLAYABILITY_CHANGED, and SHOWING_CHANGED.
 220    *
 221    * @return a string identifying this event
 222    */
 223   public String paramString()
 224   {
 225     StringBuffer r = new StringBuffer();
 226     switch (id)
 227       {
 228       case HIERARCHY_CHANGED:
 229         r.append("HIERARCHY_CHANGED (");
 230         if ((changeFlags & PARENT_CHANGED) != 0)
 231           r.append("PARENT_CHANGED,");
 232         if ((changeFlags & DISPLAYABILITY_CHANGED) != 0)
 233           r.append("DISPLAYABILITY_CHANGED,");
 234         if ((changeFlags & SHOWING_CHANGED) != 0)
 235           r.append("SHOWING_CHANGED,");
 236         break;
 237       case ANCESTOR_MOVED:
 238         r.append("ANCESTOR_MOVED (");
 239         break;
 240       case ANCESTOR_RESIZED:
 241         r.append("ANCESTOR_RESIZED (");
 242         break;
 243       default:
 244         return "unknown type";
 245       }
 246     r.append(changed).append(',').append(changedParent).append(')');
 247     return r.toString();
 248   }
 249 } // class HierarchyEvent