libjava/classpath/gnu/xml/dom/DomEvent.java

   1 /* DomEvent.java --
   2    Copyright (C) 1999,2000,2001 Free Software Foundation, Inc.
   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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 gnu.xml.dom;
  39
  40 import gnu.java.lang.CPStringBuilder;
  41
  42 import org.w3c.dom.Node;
  43
  44 import org.w3c.dom.events.Event;
  45 import org.w3c.dom.events.EventTarget;
  46 import org.w3c.dom.events.MutationEvent;
  47 import org.w3c.dom.events.UIEvent;
  48
  49 import org.w3c.dom.views.AbstractView;          // used by UIEvent
  50
  51 /**
  52  * "Event" implementation.  Events are
  53  * created (through DocumentEvent interface methods on the document object),
  54  * and are sent to any target node in the document.
  55  *
  56  * <p> Applications may define application specific event subclasses, but
  57  * should otherwise use the <em>DocumentTraversal</em> interface to acquire
  58  * event objects.
  59  *
  60  * @author David Brownell
  61  */
  62 public class DomEvent
  63   implements Event
  64 {
  65
  66   String  type;  // init
  67   EventTarget  target;
  68   EventTarget  currentNode;
  69   short  eventPhase;
  70   boolean  bubbles; // init
  71   boolean  cancelable; // init
  72   long  timeStamp; // ?
  73
  74   /** Returns the event's type (name) as initialized */
  75   public final String getType()
  76   {
  77     return type;
  78   }
  79
  80   /**
  81    * Returns event's target; delivery of an event is initiated
  82    * by a <em>target.dispatchEvent(event)</em> invocation.
  83    */
  84   public final EventTarget getTarget()
  85   {
  86     return target;
  87   }
  88
  89   /**
  90    * Returns the target to which events are currently being
  91    * delivered.  When capturing or bubbling, this will not
  92    * be what <em>getTarget</em> returns.
  93    */
  94   public final EventTarget getCurrentTarget()
  95   {
  96     return currentNode;
  97   }
  98
  99   /**
 100    * Returns CAPTURING_PHASE, AT_TARGET, or BUBBLING;
 101    * only meaningful within EventListener.handleEvent
 102    */
 103   public final short getEventPhase()
 104   {
 105     return eventPhase;
 106   }
 107
 108   /**
 109    * Returns true if the news of the event bubbles to tree tops
 110    * (as specified during initialization).
 111    */
 112   public final boolean getBubbles()
 113   {
 114     return bubbles;
 115   }
 116
 117   /**
 118    * Returns true if the default handling may be canceled
 119    * (as specified during initialization).
 120    */
 121   public final boolean getCancelable()
 122   {
 123     return cancelable;
 124   }
 125
 126   /**
 127    * Returns the event's timestamp.
 128    */
 129   public final long getTimeStamp()
 130   {
 131     return timeStamp;
 132   }
 133
 134   boolean stop;
 135   boolean doDefault;
 136
 137   /**
 138    * Requests the event no longer be captured or bubbled; only
 139    * listeners on the event target will see the event, if they
 140    * haven't yet been notified.
 141    *
 142    * <p> <em> Avoid using this </em> except for application-specific
 143    * events, for which you the protocol explicitly "blesses" the use
 144    * of this with some event types.  Otherwise, you are likely to break
 145    * algorithms which depend on event notification either directly or
 146    * through bubbling or capturing.  </p>
 147    *
 148    * <p> Note that this method is not final, specifically to enable
 149    * enforcing of policies about events always propagating. </p>
 150    */
 151   public void stopPropagation()
 152   {
 153     stop = true;
 154   }
 155
 156   /**
 157    * Requests that whoever dispatched the event not perform their
 158    * default processing when event delivery completes.  Initializes
 159    * event timestamp.
 160    */
 161   public final void preventDefault()
 162   {
 163     doDefault = false;
 164   }
 165
 166   /** Initializes basic event state.  */
 167   public void initEvent(String typeArg,
 168                         boolean canBubbleArg,
 169                         boolean cancelableArg)
 170   {
 171     eventPhase = 0;
 172     type = typeArg;
 173     bubbles = canBubbleArg;
 174     cancelable = cancelableArg;
 175     timeStamp = System.currentTimeMillis();
 176   }
 177
 178   /** Constructs, but does not initialize, an event. */
 179   public DomEvent(String type)
 180   {
 181     this.type = type;
 182   }
 183
 184   /**
 185    * Returns a basic printable description of the event's type,
 186    * state, and delivery conditions
 187    */
 188   public String toString()
 189   {
 190     CPStringBuilder buf = new CPStringBuilder("[Event ");
 191     buf.append(type);
 192     switch (eventPhase)
 193       {
 194       case CAPTURING_PHASE:
 195         buf.append(", CAPTURING");
 196         break;
 197       case AT_TARGET:
 198         buf.append(", AT TARGET");
 199         break;
 200       case BUBBLING_PHASE:
 201         buf.append(", BUBBLING");
 202         break;
 203       default:
 204         buf.append(", (inactive)");
 205         break;
 206       }
 207     if (bubbles && eventPhase != BUBBLING_PHASE)
 208       {
 209         buf.append(", bubbles");
 210       }
 211     if (cancelable)
 212       {
 213         buf.append(", can cancel");
 214       }
 215     // were we to provide subclass info, this's where it'd live
 216     buf.append("]");
 217     return buf.toString();
 218   }
 219
 220   /**
 221    * "MutationEvent" implementation.
 222    */
 223   public static final class DomMutationEvent
 224     extends DomEvent
 225     implements MutationEvent
 226   {
 227
 228     // package private
 229     Node   relatedNode; // init
 230
 231     private String  prevValue; // init
 232     private String  newValue; // init
 233
 234     private String  attrName; // init
 235     private short  attrChange; // init
 236
 237     /** Returns any "related" node provided by this type of event */
 238     public final Node getRelatedNode()
 239     {
 240       return relatedNode;
 241     }
 242
 243     /** Returns any "previous value" provided by this type of event */
 244     public final String getPrevValue()
 245     {
 246       return prevValue;
 247     }
 248
 249     /** Returns any "new value" provided by this type of event */
 250     public final String getNewValue()
 251     {
 252       return newValue;
 253     }
 254
 255     /** For attribute change events, returns the attribute's name */
 256     public final String getAttrName()
 257     {
 258       return attrName;
 259     }
 260
 261     /** For attribute change events, returns how the attribuet changed */
 262     public final short getAttrChange()
 263     {
 264       return attrChange;
 265     }
 266
 267     /** Initializes a mutation event */
 268     public final void initMutationEvent(String typeArg,
 269                                         boolean canBubbleArg,
 270                                         boolean cancelableArg,
 271                                         Node relatedNodeArg,
 272                                         String prevValueArg,
 273                                         String newValueArg,
 274                                         String attrNameArg,
 275                                         short attrChangeArg)
 276     {
 277       // super.initEvent is inlined here for speed
 278       // (mutation events are issued on all DOM changes)
 279       eventPhase = 0;
 280       type = typeArg;
 281       bubbles = canBubbleArg;
 282       cancelable = cancelableArg;
 283       timeStamp = System.currentTimeMillis();
 284
 285       relatedNode = relatedNodeArg;
 286       prevValue = prevValueArg;
 287       newValue = newValueArg;
 288       attrName = attrNameArg;
 289       attrChange = attrChangeArg;
 290     }
 291
 292     // clear everything that should be GC-able
 293     void clear()
 294     {
 295       type = null;
 296       target = null;
 297       relatedNode = null;
 298       currentNode = null;
 299       prevValue = newValue = attrName = null;
 300     }
 301
 302     /** Constructs an uninitialized mutation event. */
 303     public DomMutationEvent(String type)
 304     {
 305       super(type);
 306     }
 307
 308   }
 309
 310   /**
 311    * "UIEvent" implementation.
 312    */
 313   public static class DomUIEvent
 314     extends DomEvent
 315     implements UIEvent
 316   {
 317
 318     private AbstractView view;  // init
 319     private int  detail;  // init
 320
 321     /** Constructs an uninitialized User Interface (UI) event */
 322     public DomUIEvent (String type) { super (type); }
 323
 324     public final AbstractView getView () { return view; }
 325     public final int getDetail () { return detail; }
 326
 327     /** Initializes a UI event */
 328     public final void initUIEvent(String typeArg,
 329                                   boolean canBubbleArg,
 330                                   boolean cancelableArg,
 331                                   AbstractView viewArg,
 332                                   int detailArg)
 333     {
 334       super.initEvent(typeArg, canBubbleArg, cancelableArg);
 335       view = viewArg;
 336       detail = detailArg;
 337     }
 338
 339   }
 340
 341     /*
 342
 343     static final class DomMouseEvent extends DomUIEvent
 344  implements MouseEvent
 345     {
 346  // another half dozen state variables/accessors
 347     }
 348
 349     */
 350
 351 }
 352