src/dom/events.h

   1 #ifndef __EVENTS_H__
   2 #define __EVENTS_H__
   3
   4 /**
   5  * Phoebe DOM Implementation.
   6  *
   7  * This is a C++ approximation of the W3C DOM model, which follows
   8  * fairly closely the specifications in the various .idl files, copies of
   9  * which are provided for reference.  Most important is this one:
  10  *
  11  * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/idl-definitions.html
  12  *
  13  * Authors:
  14  *   Bob Jamison
  15  *
  16  * Copyright (C) 2005-2008 Bob Jamison
  17  *
  18  *  This library is free software; you can redistribute it and/or
  19  *  modify it under the terms of the GNU Lesser General Public
  20  *  License as published by the Free Software Foundation; either
  21  *  version 2.1 of the License, or (at your option) any later version.
  22  *
  23  *  This library is distributed in the hope that it will be useful,
  24  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  26  *  Lesser General Public License for more details.
  27  *
  28  *  You should have received a copy of the GNU Lesser General Public
  29  *  License along with this library; if not, write to the Free Software
  30  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  31  *
  32  * ========================================================================
  33  * NOTES
  34  *
  35  * This Events API follows somewhat this specification:
  36  * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html
  37  *
  38  * Some of the comments are excerpted from that document.
  39  *
  40  *
  41  */
  42
  43
  44 #include "dom.h"
  45 #include "views.h"
  46
  47
  48
  49
  50 namespace org    {
  51 namespace w3c    {
  52 namespace dom    {
  53 namespace events {
  54
  55
  56
  57
  58 //Local definitions
  59 typedef dom::DOMString DOMString;
  60 typedef dom::DOMTimeStamp DOMTimeStamp;
  61 typedef dom::NodePtr  NodePtr ;
  62
  63
  64
  65
  66 //forward declarations
  67 class Event;
  68 class EventTarget;
  69 class EventListener;
  70 class DocumentEvent;
  71 class CustomEvent;
  72 class UIEvent;
  73 class TextEvent;
  74 class MouseEvent;
  75 class KeyboardEvent;
  76 class MutationEvent;
  77 class MutationNameEvent;
  78
  79
  80
  81 /*#########################################################################
  82 ## EventException
  83 #########################################################################*/
  84
  85 /**
  86  * Event operations may throw an EventException as specified in their
  87  *  method descriptions.
  88  */
  89 class EventException
  90 {
  91 public:
  92
  93     /**
  94      * An integer indicating the type of error generated.
  95      */
  96     typedef enum
  97         {
  98         UNSPECIFIED_EVENT_TYPE_ERR = 0,
  99         DISPATCH_REQUEST_ERR       = 1
 100         } EventExceptionCode;
 101
 102     unsigned short code;
 103
 104
 105     //##################
 106     //# Non-API methods
 107     //##################
 108
 109     EventException(short theCode)
 110         {
 111             code = theCode;
 112         }
 113
 114     virtual ~EventException() throw()
 115        {}
 116
 117 };
 118
 119
 120
 121
 122 /*#########################################################################
 123 ## Event
 124 #########################################################################*/
 125
 126 /**
 127  * The Event interface is used to provide contextual information about an event
 128  * to the listener processing the event. An object which implements the Event
 129  * interface is passed as the parameter to an EventListener. More specific
 130  * context information is passed to event listeners by deriving additional
 131  * interfaces from Event which contain information directly relating to the type
 132  * of event they represent. These derived interfaces are also implemented by the
 133  * object passed to the event listener.
 134  *
 135  * To create an instance of the Event interface, use the
 136  * DocumentEvent.createEvent("Event") method call.
 137  */
 138 class Event
 139 {
 140 public:
 141
 142     /**
 143      * An integer indicating which phase of the event flow is being processed
 144      *   as defined in DOM event flow.
 145      */
 146     typedef enum
 147         {
 148         CAPTURING_PHASE = 1,
 149         AT_TARGET       = 2,
 150         BUBBLING_PHASE  = 3
 151         } PhaseType;
 152
 153     /**
 154      * The name should be an NCName  as defined in [XML Namespaces] and is
 155      * case-sensitive.
 156      * If the attribute Event.namespaceURI is different from null, this
 157      * attribute represents a local name.
 158      */
 159     virtual DOMString getType() const
 160         { return eventType; }
 161
 162     /**
 163      * Used to indicate the event target. This attribute contains the target
 164      * node when used with the DOM event flow.
 165      */
 166     virtual EventTarget *getTarget()
 167         { return target; }
 168
 169     /**
 170      * Used to indicate the EventTarget whose EventListeners are currently
 171      * being processed. This is particularly useful during the capture and
 172      * bubbling phases. This attribute could contain the target node or a
 173      * target ancestor when used with the DOM event flow.
 174      */
 175     virtual EventTarget *getCurrentTarget()
 176         { return currentTarget; }
 177
 178     /**
 179      * Used to indicate which phase of event flow is currently being accomplished.
 180      */
 181     virtual unsigned short getEventPhase()
 182         { return eventPhase; }
 183
 184     /**
 185      * Used to indicate whether or not an event is a bubbling event. If the
 186      * event can bubble the value is true, otherwise the value is false.
 187      */
 188     virtual bool getBubbles()
 189         { return canBubble; }
 190
 191     /**
 192      * Used to indicate whether or not an event can have its default action
 193      * prevented (see also Default actions and cancelable events). If the
 194      * default action can be prevented the value is true, otherwise the
 195      * value is false.
 196      */
 197     virtual bool getCancelable()
 198         { return cancelable; }
 199
 200     /**
 201      * Used to specify the time (in milliseconds relative to the epoch) at which the
 202      * event was created. Due to the fact that some systems may not provide this
 203      * information the value of timeStamp may be not available for all events. When
 204      * not available, a value of 0 will be returned. Examples of epoch time are the
 205      * time of the system start or 0:0:0 UTC 1st January 1970.
 206      */
 207     virtual DOMTimeStamp getTimeStamp()
 208         { return timeStamp; }
 209
 210     /**
 211      * This method is used to prevent event listeners of the same group to be
 212      * triggered but its effect is deferred until all event listeners attached on the
 213      * currentTarget have been triggered (see Event propagation and event groups).
 214      * Once it has been called, further calls to that method have no additional effect.
 215      */
 216     virtual void stopPropagation()
 217         {
 218         }
 219
 220     /**
 221      * If an event is cancelable, the preventDefault method is used to signify that
 222      * the event is to be canceled, meaning any default action normally taken by the
 223      * implementation as a result of the event will not occur (see also Default
 224      * actions and cancelable events), and thus independently of event groups.
 225      * Calling this method for a non-cancelable event has no effect.
 226      */
 227     virtual void preventDefault()
 228         {
 229         }
 230
 231     /**
 232      * The initEvent method is used to initialize the value of an Event created
 233      * through the DocumentEvent.createEvent method. This method may only be called
 234      * before the Event has been dispatched via the EventTarget.dispatchEvent()
 235      * method. If the method is called several times before invoking
 236      * EventTarget.dispatchEvent, only the final invocation takes precedence. This
 237      * method has no effect if called after the event has been dispatched. If called
 238      * from a subclass of the Event interface only the values specified in this
 239      * method are modified, all other attributes are left unchanged.
 240      *
 241      * This method sets the Event.type attribute to eventTypeArg, and
 242      * Event.namespaceURI to null. To initialize an event with a namespace URI, use
 243      * the Event.initEventNS(namespaceURIArg, eventTypeArg, ...) method.
 244      */
 245     virtual void initEvent(const DOMString &eventTypeArg,
 246                            bool canBubbleArg,
 247                            bool cancelableArg)
 248         {
 249         namespaceURI = "";
 250         eventType    = eventTypeArg;
 251         canBubble    = canBubbleArg;
 252         cancelable   = cancelableArg;
 253         }
 254
 255
 256     /**
 257      * The namespace URI  associated with this event at creation time, or
 258      *  null if it is unspecified.
 259      */
 260     virtual DOMString getNamespaceURI() const
 261         { return namespaceURI; }
 262
 263     /**
 264      * This method will always return false, unless the event implements
 265      * the CustomEvent interface.
 266      */
 267     virtual bool isCustom()
 268         { return custom; }
 269
 270     /**
 271      * This method is used to prevent event listeners of the same group to be
 272      * triggered and, unlike stopPropagation its effect is immediate (see Event
 273      * propagation and event groups). Once it has been called, further calls to that
 274      * method have no additional effect.
 275      *
 276      * Note: This method does not prevent the default action from being invoked; use
 277      * Event.preventDefault() for that effect.
 278      */
 279     virtual void stopImmediatePropagation()
 280         {
 281         }
 282
 283     /**
 284      * This method will return true if the method Event.preventDefault()
 285      * has been called for this event, false otherwise.
 286      */
 287     virtual bool isDefaultPrevented()
 288         { return defaultPrevented; }
 289
 290     /**
 291      * The initEventNS method is used to initialize the value of an Event
 292      *  object and has the same behavior as Event.initEvent().
 293      */
 294     virtual void initEventNS(const DOMString &namespaceURIArg,
 295                              const DOMString &eventTypeArg,
 296                              bool canBubbleArg,
 297                              bool cancelableArg)
 298         {
 299         namespaceURI = namespaceURIArg;
 300         eventType    = eventTypeArg;
 301         canBubble    = canBubbleArg;
 302         cancelable   = cancelableArg;
 303         }
 304
 305     //##################
 306     //# Non-API methods
 307     //##################
 308
 309     /**
 310      *
 311      */
 312     Event()
 313         {
 314         init();
 315         }
 316
 317     /**
 318      *
 319      */
 320     Event(const DOMString &eventTypeArg)
 321         {
 322         init();
 323         eventType     = eventTypeArg;
 324         }
 325
 326
 327     /**
 328      *
 329      */
 330     Event(const Event &other)
 331         {
 332         eventType        = other.eventType;
 333         target           = other.target;
 334         currentTarget    = other.currentTarget;
 335         eventPhase       = other.eventPhase;
 336         canBubble        = other.canBubble;
 337         cancelable       = other.cancelable;
 338         timeStamp        = other.timeStamp;
 339         namespaceURI     = other.namespaceURI;
 340         custom           = other.custom;
 341         defaultPrevented = other.defaultPrevented;
 342         }
 343
 344     /**
 345      *
 346      */
 347     virtual ~Event() {}
 348
 349 protected:
 350
 351     /**
 352      *
 353      */
 354     void init()
 355         {
 356         eventType        = "";
 357         target           = NULL;
 358         currentTarget    = NULL;
 359         eventPhase       = 0;
 360         canBubble        = false;
 361         cancelable       = false;
 362         //timeStamp      = other.timeStamp;
 363         namespaceURI     = "";
 364         custom           = false;
 365         defaultPrevented = false;
 366         }
 367
 368     DOMString      eventType;
 369     EventTarget    *target;
 370     EventTarget    *currentTarget;
 371     unsigned short eventPhase;
 372     bool           canBubble;
 373     bool           cancelable;
 374     DOMTimeStamp   timeStamp;
 375     DOMString      namespaceURI;
 376     bool           custom;
 377     bool           defaultPrevented;
 378
 379 };
 380
 381
 382
 383
 384 /*#########################################################################
 385 ## EventListener
 386 #########################################################################*/
 387
 388 /**
 389  * The EventListener interface is the primary way for handling events. Users
 390  * implement the EventListener interface and register their event listener on an
 391  * EventTarget. The users should also remove their EventListener from its
 392  * EventTarget after they have completed using the listener.
 393  *
 394  * Copying a Node, with methods such as Node.cloneNode or Range.cloneContents,
 395  * does not copy the event listeners attached to it. Event listeners must be
 396  * attached to the newly created Node afterwards if so desired.
 397  *
 398  * Moving a Node, with methods Document.adoptNode, Node.appendChild, or
 399  * Range.extractContents, does not affect the event listeners attached to it.
 400  */
 401 class EventListener
 402 {
 403 public:
 404
 405     /**
 406      * This method is called whenever an event occurs of the event type
 407      * for which the EventListener interface was registered.
 408      */
 409     virtual void handleEvent(const Event &/*evt*/)
 410         {}
 411
 412     //##################
 413     //# Non-API methods
 414     //##################
 415
 416     /**
 417      *
 418      */
 419     virtual ~EventListener() {}
 420 };
 421
 422
 423
 424
 425
 426
 427 /*#########################################################################
 428 ## EventTarget
 429 #########################################################################*/
 430
 431
 432 /**
 433  * The EventTarget interface is implemented by all the objects which could be
 434  * event targets in an implementation which supports the Event flows. The
 435  * interface allows registration, removal or query of event listeners, and
 436  * dispatch of events to an event target.
 437  *
 438  * When used with DOM event flow, this interface is implemented by all target
 439  * nodes and target ancestors, i.e. all DOM Nodes of the tree support this
 440  * interface when the implementation conforms to DOM Level 3 Events and,
 441  * therefore, this interface can be obtained by using binding-specific casting
 442  * methods on an instance of the Node interface.
 443  *
 444  * Invoking addEventListener or addEventListenerNS multiple times on the same
 445  * EventTarget with the same parameters (namespaceURI, type, listener, and
 446  * useCapture) is considered to be a no-op and thus independently of the event
 447  * group. They do not cause the EventListener to be called more than once and do
 448  * not cause a change in the triggering order. In order to guarantee that an
 449  * event listener will be added to the event target for the specified event group,
 450  * one needs to invoke removeEventListener or removeEventListenerNS first.
 451  */
 452 class EventTarget
 453 {
 454 private:
 455
 456         class EventListenerEntry
 457         {
 458         public:
 459             EventListenerEntry(const DOMString &namespaceURIArg,
 460                                const DOMString &eventTypeArg,
 461                                const EventListener *listenerArg,
 462                                bool useCaptureArg)
 463                 {
 464                 namespaceURI = namespaceURIArg;
 465                 eventType    = eventTypeArg;
 466                 listener     = (EventListener *)listenerArg;
 467                 useCapture   = useCaptureArg;
 468                 }
 469
 470             EventListenerEntry(const EventListenerEntry &other)
 471                 {
 472                 namespaceURI = other.namespaceURI;
 473                 eventType    = other.eventType;
 474                 listener     = other.listener;
 475                 useCapture   = other.useCapture;
 476                 }
 477
 478             virtual ~EventListenerEntry() {}
 479
 480             DOMString namespaceURI;
 481             DOMString eventType;
 482             EventListener *listener;
 483             bool useCapture;
 484         };
 485
 486
 487
 488 public:
 489
 490     /**
 491      * This method allows the registration of an event listener in the default group
 492      * and, depending on the useCapture parameter, on the capture phase of the DOM
 493      * event flow or its target and bubbling phases.
 494      */
 495     virtual void addEventListener(const DOMString &type,
 496                                   const EventListener *listener,
 497                                   bool useCapture)
 498         {
 499         EventListenerEntry entry("", type, listener, useCapture);
 500         listeners.push_back(entry);
 501         }
 502
 503     /**
 504      * This method allows the removal of event listeners from the default group.
 505      * Calling removeEventListener with arguments which do not identify any currently
 506      * registered EventListener on the EventTarget has no effect.
 507      */
 508     virtual void removeEventListener(const DOMString &type,
 509                                      const EventListener *listener,
 510                                      bool useCapture)
 511         {
 512         std::vector<EventListenerEntry>::iterator iter;
 513         for (iter = listeners.begin() ; iter != listeners.end() ; iter++)
 514             {
 515             EventListenerEntry entry = *iter;
 516             if (entry.eventType == type &&
 517                 entry.listener  == listener &&
 518                 useCapture && entry.useCapture)
 519                 listeners.erase(iter);
 520             }
 521         }
 522
 523     /**
 524      * This method allows the dispatch of events into the implementation's event
 525      * model. The event target of the event is the EventTarget object on which
 526      * dispatchEvent is called.
 527      */
 528     virtual bool dispatchEvent(const Event &evt) throw(EventException)
 529         {
 530
 531         for (unsigned int i=0 ; i<listeners.size() ; i++)
 532             {
 533             EventListenerEntry listener = listeners[i];
 534             if (listener.namespaceURI == evt.getNamespaceURI()  &&
 535                 listener.eventType    == evt.getType())
 536                 {
 537                 if (listener.listener)
 538                     listener.listener->handleEvent(evt);
 539                 }
 540             }
 541         return true;
 542         }
 543
 544
 545     /**
 546      * This method allows the registration of an event listener in a specified group
 547      * or the default group and, depending on the useCapture parameter, on the
 548      * capture phase of the DOM event flow or its target and bubbling phases.
 549      */
 550     virtual void addEventListenerNS(const DOMString &namespaceURI,
 551                                     const DOMString &type,
 552                                     const EventListener *listener,
 553                                     bool useCapture)
 554         {
 555         EventListenerEntry entry(namespaceURI, type, listener, useCapture);
 556         listeners.push_back(entry);
 557         }
 558
 559     /**
 560      * This method allows the removal of an event listener, independently of the
 561      * associated event group.
 562      * Calling removeEventListenerNS with arguments which do not identify any
 563      * currently registered EventListener on the EventTarget has no effect.
 564      */
 565     virtual void removeEventListenerNS(const DOMString &namespaceURI,
 566                                        const DOMString &type,
 567                                        const EventListener *listener,
 568                                        bool useCapture)
 569         {
 570         std::vector<EventListenerEntry>::iterator iter;
 571         for (iter = listeners.begin() ; iter != listeners.end() ; iter++)
 572             {
 573             EventListenerEntry entry = *iter;
 574             if (entry.namespaceURI == namespaceURI &&
 575                 entry.eventType    == type &&
 576                 entry.listener     == listener &&
 577                 useCapture && entry.useCapture)
 578                 listeners.erase(iter);
 579             }
 580         }
 581
 582     /**
 583      * This method allows the DOM application to know if an event listener, attached
 584      * to this EventTarget or one of its ancestors, will be triggered by the
 585      * specified event type during the dispatch of the event to this event target or
 586      * one of its descendants.
 587      */
 588     virtual bool willTriggerNS(const DOMString &namespaceURI,
 589                                const DOMString &type)
 590         {
 591         std::vector<EventListenerEntry>::iterator iter;
 592         for (iter = listeners.begin() ; iter != listeners.end() ; iter++)
 593             {
 594             EventListenerEntry entry = *iter;
 595             if (entry.namespaceURI == namespaceURI &&
 596                 entry.eventType    == type)
 597                 return true;
 598             }
 599         return false;
 600         }
 601
 602     /**
 603      * This method allows the DOM application to know if this EventTarget contains an
 604      * event listener registered for the specified event type. This is useful for
 605      * determining at which nodes within a hierarchy altered handling of specific
 606      * event types has been introduced, but should not be used to determine whether
 607      * the specified event type triggers an event listener (see
 608      * EventTarget.willTriggerNS()).
 609      */
 610     virtual bool hasEventListenerNS(const DOMString &namespaceURI,
 611                                     const DOMString &type)
 612         {
 613         std::vector<EventListenerEntry>::iterator iter;
 614         for (iter = listeners.begin() ; iter != listeners.end() ; iter++)
 615             {
 616             EventListenerEntry entry = *iter;
 617             if (entry.namespaceURI == namespaceURI &&
 618                 entry.eventType    == type)
 619                 return true;
 620             }
 621         return false;
 622         }
 623
 624
 625     //##################
 626     //# Non-API methods
 627     //##################
 628
 629     /**
 630      *
 631      */
 632     EventTarget() {}
 633
 634     /**
 635      *
 636      */
 637     EventTarget(const EventTarget &other)
 638         {
 639         listeners = other.listeners;
 640         }
 641
 642     /**
 643      *
 644      */
 645     virtual ~EventTarget() {}
 646
 647 protected:
 648
 649     std::vector<EventListenerEntry> listeners;
 650
 651 };
 652
 653
 654
 655
 656 /*#########################################################################
 657 ## DocumentEvent
 658 #########################################################################*/
 659
 660 /**
 661  * The DocumentEvent interface provides a mechanism by which the user can create
 662  * an Event object of a type supported by the implementation. If the feature
 663  * "Events" is supported by the Document object, the DocumentEvent interface must
 664  * be implemented on the same object. If the feature "+Events" is supported by
 665  * the Document object, an object that supports the DocumentEvent interface must
 666  * be returned by invoking the method Node.getFeature("+Events", "3.0") on the
 667  * Document object.
 668  */
 669 class DocumentEvent : virtual public Event
 670 {
 671 public:
 672
 673     /**
 674      * Create an event with the current document
 675      */
 676     virtual Event createEvent(const DOMString &/*eventType*/)
 677                                throw (dom::DOMException)
 678         {
 679         Event event;
 680         return event;
 681         }
 682
 683     /**
 684      * Test if the implementation can generate events of a specified type.
 685      */
 686     virtual bool canDispatch(const DOMString &/*namespaceURI*/,
 687                              const DOMString &/*type*/)
 688         {
 689         return dispatchable;
 690         }
 691
 692     //##################
 693     //# Non-API methods
 694     //##################
 695
 696     /**
 697      *
 698      */
 699     DocumentEvent() {}
 700
 701     /**
 702      *
 703      */
 704     DocumentEvent(const DocumentEvent &other) : Event(other)
 705         {
 706         dispatchable = other.dispatchable;
 707         }
 708
 709     /**
 710      *
 711      */
 712     virtual ~DocumentEvent() {}
 713
 714 protected:
 715
 716     bool dispatchable;
 717
 718
 719 };
 720
 721
 722 /*#########################################################################
 723 ## CustomEvent
 724 #########################################################################*/
 725
 726 /**
 727  * The CustomEvent interface gives access to the attributes Event.currentTarget
 728  * and Event.eventPhase. It is intended to be used by the DOM Events
 729  * implementation to access the underlying current target and event phase while
 730  * dispatching a custom Event in the tree; it is also intended to be implemented,
 731  * and not used, by DOM applications.
 732  *
 733  * The methods contained in this interface are not intended to be used by a DOM
 734  * application, especially during the dispatch on the Event object. Changing the
 735  * current target or the current phase may result in unpredictable results of the
 736  * event flow. The DOM Events implementation should ensure that both methods
 737  * return the appropriate current target and phase before invoking each event
 738  * listener on the current target to protect DOM applications from malicious
 739  * event listeners.
 740  *
 741  * Note: If this interface is supported by the event object, Event.isCustom()
 742  * must return true.
 743 */
 744 class CustomEvent : virtual public Event
 745 {
 746 public:
 747
 748     /**
 749      * The setDispatchState method is used by the DOM Events implementation to set
 750      * the values of Event.currentTarget and Event.eventPhase. It also reset the
 751      * states of isPropagationStopped and isImmediatePropagationStopped.
 752      */
 753     virtual void setDispatchState(const EventTarget */*target*/,
 754                                   unsigned short /*phase*/)
 755         {
 756         }
 757
 758     /**
 759      * This method will return true if the method stopPropagation() has been
 760      * called for this event, false in any other cases.
 761      */
 762     virtual bool isPropagationStopped()
 763         {
 764         return propagationStopped;
 765         }
 766
 767     /**
 768      * The isImmediatePropagationStopped method is used by the DOM Events
 769      * implementation to know if the method stopImmediatePropagation() has been
 770      * called for this event. It returns true if the method has been called, false
 771      * otherwise.
 772      */
 773     virtual bool isImmediatePropagationStopped()
 774         {
 775         return immediatePropagationStopped;
 776         }
 777
 778
 779     //##################
 780     //# Non-API methods
 781     //##################
 782
 783     /**
 784      *
 785      */
 786     CustomEvent() {}
 787
 788     /**
 789      *
 790      */
 791     CustomEvent(const CustomEvent &other) : Event(other)
 792         {
 793         propagationStopped          = other.propagationStopped;
 794         immediatePropagationStopped = other.immediatePropagationStopped;
 795         }
 796
 797     /**
 798      *
 799      */
 800     virtual ~CustomEvent() {}
 801
 802 protected:
 803
 804     bool propagationStopped;
 805     bool immediatePropagationStopped;
 806
 807
 808
 809 };
 810
 811
 812
 813
 814 /*#########################################################################
 815 ## UIEvent
 816 #########################################################################*/
 817
 818 /**
 819  * The UIEvent interface provides specific contextual information associated with
 820  * User Interface events.
 821  *
 822  * To create an instance of the UIEvent interface, use the
 823  * DocumentEvent.createEvent("UIEvent") method call.
 824  *
 825  * NOTE:
 826  * For dom level 2 and 3, note that views.idl and events.idl disagree on the
 827  *  name of Views.  We are using level -2- Views
 828  */
 829 class UIEvent : virtual public Event
 830 {
 831 public:
 832
 833     /**
 834      * The view attribute identifies the AbstractView from which the
 835      * event was generated.
 836      */
 837     virtual views::AbstractView getView()
 838         { return view; }
 839
 840     /**
 841      * Specifies some detail information about the Event, depending on
 842      * the type of event.
 843      */
 844     virtual long getDetail()
 845         { return detail; }
 846
 847     /**
 848      * The initUIEvent method is used to initialize the value of a UIEvent object and
 849      * has the same behavior as Event.initEvent().
 850      */
 851     virtual void initUIEvent(const DOMString &/*typeArg*/,
 852                              bool /*canBubbleArg*/,
 853                              bool /*cancelableArg*/,
 854                              const views::AbstractView */*viewArg*/,
 855                              long /*detailArg*/)
 856         {
 857         }
 858
 859     /**
 860      * The initUIEventNS method is used to initialize the value of a UIEvent object
 861      * and has the same behavior as Event.initEventNS().
 862      */
 863     virtual void initUIEventNS(const DOMString &/*namespaceURI*/,
 864                                const DOMString &/*typeArg*/,
 865                                bool /*canBubbleArg*/,
 866                                bool /*cancelableArg*/,
 867                                const views::AbstractView */*viewArg*/,
 868                                long /*detailArg*/)
 869         {
 870         }
 871
 872     //##################
 873     //# Non-API methods
 874     //##################
 875
 876     /**
 877      *
 878      */
 879     UIEvent() {}
 880
 881     /**
 882      *
 883      */
 884     UIEvent(const UIEvent &other) : Event(other)
 885         {
 886         view   = other.view;
 887         detail = other.detail;
 888         }
 889
 890     /**
 891      *
 892      */
 893     virtual ~UIEvent() {}
 894
 895 protected:
 896
 897     views::AbstractView view;
 898     long detail;
 899 };
 900
 901
 902
 903
 904 /*#########################################################################
 905 ## TextEvent
 906 #########################################################################*/
 907
 908 /**
 909  * The TextEvent interface provides specific contextual information associated
 910  * with Text Events.
 911  *
 912  * To create an instance of the TextEvent interface, use the
 913  * DocumentEvent.createEvent("TextEvent") method call.
 914  */
 915 class TextEvent : virtual public UIEvent
 916 {
 917 public:
 918
 919     /**
 920      * data holds the value of the characters generated by the character device. This
 921      * may be a single Unicode character or a non-empty sequence of Unicode
 922      * characters [Unicode]. Characters should be normalized as defined by the
 923      * Unicode normalization form NFC, defined in [UTR #15]. This attribute cannot be
 924      * null or contain the empty string.
 925      */
 926     virtual DOMString getData()
 927         { return data; }
 928
 929     /**
 930      * The initTextEvent method is used to initialize the value of a TextEvent object
 931      * and has the same behavior as UIEvent.initUIEvent(). The value of
 932      * UIEvent.detail remains undefined.
 933      */
 934     virtual void initTextEvent(const DOMString &/*typeArg*/,
 935                                bool /*canBubbleArg*/,
 936                                bool /*cancelableArg*/,
 937                                const views::AbstractView */*viewArg*/,
 938                                long /*detailArg*/)
 939         {
 940         }
 941
 942     /**
 943      * The initTextEventNS method is used to initialize the value of a TextEvent
 944      * object and has the same behavior as UIEvent.initUIEventNS(). The value of
 945      * UIEvent.detail remains undefined.
 946      */
 947     virtual void initTextEventNS(const DOMString &/*namespaceURI*/,
 948                                  const DOMString &/*typeArg*/,
 949                                  bool /*canBubbleArg*/,
 950                                  bool /*cancelableArg*/,
 951                                  const views::AbstractView */*viewArg*/,
 952                                  long /*detailArg*/)
 953         {
 954         }
 955
 956     //##################
 957     //# Non-API methods
 958     //##################
 959
 960     /**
 961      *
 962      */
 963     TextEvent() {}
 964
 965     /**
 966      *
 967      */
 968     TextEvent(const TextEvent &other) : Event(other), UIEvent(other)
 969         {
 970         data = other.data;
 971         }
 972
 973     /**
 974      *
 975      */
 976     virtual ~TextEvent() {}
 977
 978 protected:
 979
 980     DOMString data;
 981
 982 };
 983
 984
 985
 986
 987
 988
 989
 990
 991 /*#########################################################################
 992 ## MouseEvent
 993 #########################################################################*/
 994
 995 /**
 996  * The MouseEvent interface provides specific contextual information associated
 997  * with Mouse events.
 998  *
 999  * In the case of nested elements mouse events are always targeted at the most
1000  * deeply nested element. Ancestors of the targeted element may use bubbling to
1001  * obtain notification of mouse events which occur within theirs descendent
1002  * elements.
1003  *
1004  * To create an instance of the MouseEvent interface, use the
1005  * DocumentEvent.createEvent("MouseEvent") method call.
1006  */
1007 class MouseEvent : virtual public UIEvent
1008 {
1009 public:
1010
1011     /**
1012      * The horizontal coordinate at which the event occurred relative to the
1013      * origin of the screen coordinate system.
1014      */
1015     virtual long getScreenX()
1016         { return screenX; }
1017
1018     /**
1019      * The vertical coordinate at which the event occurred relative to the
1020      *  origin of the screen coordinate system.
1021      */
1022     virtual long getScreenY()
1023         { return screenY; }
1024
1025     /**
1026      * The horizontal coordinate at which the event occurred relative to the
1027      *  DOM implementation's client area.
1028      */
1029     virtual long getClientX()
1030         { return clientX; }
1031
1032     /**
1033      * The vertical coordinate at which the event occurred relative to the
1034      * DOM implementation's client area.
1035      */
1036     virtual long getClientY()
1037         { return clientY; }
1038
1039     /**
1040      * true if the control (Ctrl) key modifier is activated.
1041      */
1042     virtual bool getCtrlKey()
1043         { return ctrlKey; }
1044
1045     /**
1046      * true if the shift (Shift) key modifier is activated.
1047      */
1048     virtual bool getShiftKey()
1049         { return shiftKey; }
1050
1051     /**
1052      * true if the alt (alternative) key modifier is activated.
1053      */
1054     virtual bool getAltKey()
1055         { return altKey; }
1056
1057     /**
1058      * true if the meta (Meta) key modifier is activated.
1059      */
1060     virtual bool getMetaKey()
1061         { return metaKey; }
1062
1063     /**
1064      * During mouse events caused by the depression or release of a mouse button,
1065      * button is used to indicate which mouse button changed state. 0 indicates the
1066      * normal button of the mouse (in general on the left or the one button on
1067      * Macintosh mice, used to activate a button or select text). 2 indicates the
1068      * contextual property (in general on the right, used to display a context menu)
1069      * button of the mouse if present. 1 indicates the extra (in general in the
1070      * middle and often combined with the mouse wheel) button. Some mice may provide
1071      * or simulate more buttons, and values higher than 2 can be used to represent
1072      * such buttons.
1073      */
1074     virtual unsigned short getButton()
1075         { return button; }
1076
1077     /**
1078      * Used to identify a secondary EventTarget related to a UI event. Currently this
1079      * attribute is used with the mouseover event to indicate the EventTarget which
1080      * the pointing device exited and with the mouseout event to indicate the
1081      * EventTarget which the pointing device entered.
1082      */
1083     virtual EventTarget *getRelatedTarget()
1084         { return relatedTarget; }
1085
1086
1087     /**
1088      * This methods queries the state of a modifier using a key identifier.
1089      * The argument is a modifier key identifier, as defined by the
1090      * KeyboardEvent.keyIdentifier attribute. Common modifier keys are "Alt",
1091      * "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift".
1092      */
1093     virtual bool getModifierState(const DOMString &/*id*/)
1094         { return false; }
1095
1096     /**
1097      * The initMouseEvent method is used to initialize the value of a MouseEvent
1098      * object and has the same behavior as UIEvent.initUIEvent().
1099      */
1100     virtual void initMouseEvent(const DOMString &/*typeArg*/,
1101                                 bool /*canBubbleArg*/,
1102                                 bool /*cancelableArg*/,
1103                                 const views::AbstractView */*viewArg*/,
1104                                 long /*detailArg*/,
1105                                 long /*screenXArg*/,
1106                                 long /*screenYArg*/,
1107                                 long /*clientXArg*/,
1108                                 long /*clientYArg*/,
1109                                 bool /*ctrlKeyArg*/,
1110                                 bool /*altKeyArg*/,
1111                                 bool /*shiftKeyArg*/,
1112                                 bool /*metaKeyArg*/,
1113                                 unsigned short /*buttonArg*/,
1114                                 const EventTarget */*relatedTargetArg*/)
1115         {
1116         }
1117
1118
1119     /**
1120      * The initMouseEventNS method is used to initialize the value of a
1121      * MouseEvent object and has the same behavior as UIEvent.initUIEventNS().
1122      */
1123     virtual void initMouseEventNS(const DOMString &/*namespaceURI*/,
1124                                   const DOMString &/*typeArg*/,
1125                                   bool /*canBubbleArg*/,
1126                                   bool /*cancelableArg*/,
1127                                   const views::AbstractView */*viewArg*/,
1128                                   long /*detailArg*/,
1129                                   long /*screenXArg*/,
1130                                   long /*screenYArg*/,
1131                                   long /*clientXArg*/,
1132                                   long /*clientYArg*/,
1133                                   unsigned short /*buttonArg*/,
1134                                   const EventTarget */*relatedTargetArg*/,
1135                                   const DOMString &/*modifiersList*/)
1136         {
1137         }
1138
1139
1140     //##################
1141     //# Non-API methods
1142     //##################
1143
1144     /**
1145      *
1146      */
1147     MouseEvent() {}
1148
1149     /**
1150      *
1151      */
1152     MouseEvent(const MouseEvent &other) : Event(other), UIEvent(other)
1153         {
1154         screenX       = other.screenX;
1155         screenY       = other.screenY;
1156         clientX       = other.clientX;
1157         clientY       = other.clientY;
1158         ctrlKey       = other.ctrlKey;
1159         shiftKey      = other.shiftKey;
1160         altKey        = other.altKey;
1161         metaKey       = other.metaKey;
1162         button        = other.button;
1163         relatedTarget = other.relatedTarget;
1164         }
1165
1166     /**
1167      *
1168      */
1169     virtual ~MouseEvent() {}
1170
1171 protected:
1172
1173     long screenX;
1174     long screenY;
1175     long clientX;
1176     long clientY;
1177     bool ctrlKey;
1178     bool shiftKey;
1179     bool altKey;
1180     bool metaKey;
1181     unsigned short button;
1182     EventTarget *relatedTarget;
1183 };
1184
1185
1186
1187
1188 /*#########################################################################
1189 ## KeyboardEvent
1190 #########################################################################*/
1191
1192 /**
1193  * The KeyboardEvent interface provides specific contextual information
1194  * associated with keyboard devices. Each keyboard event references a key using
1195  * an identifier. Keyboard events are commonly directed at the element that has
1196  * the focus.
1197  *
1198  * The KeyboardEvent interface provides convenient attributes for some common
1199  * modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey,
1200  * KeyboardEvent.altKey, KeyboardEvent.metaKey. These attributes are equivalent
1201  * to use the method KeyboardEvent.getModifierState(keyIdentifierArg) with
1202  * "Control", "Shift", "Alt", or "Meta" respectively.
1203  *
1204  * To create an instance of the KeyboardEvent interface, use the
1205  * DocumentEvent.createEvent("KeyboardEvent") method call.
1206  */
1207 class KeyboardEvent : virtual public UIEvent
1208 {
1209 public:
1210
1211     /**
1212      * This set of constants is used to indicate the location of a key on
1213      * the device. In case a DOM implementation wishes to provide a new
1214      * location information, a value different from the following constant
1215      * values must be used.
1216      */
1217     typedef enum
1218         {
1219         DOM_KEY_LOCATION_STANDARD      = 0x00,
1220         DOM_KEY_LOCATION_LEFT          = 0x01,
1221         DOM_KEY_LOCATION_RIGHT         = 0x02,
1222         DOM_KEY_LOCATION_NUMPAD        = 0x03
1223         } KeyLocationCode;
1224
1225     /**
1226      * keyIdentifier holds the identifier of the key.
1227      * Key identifiers can be found here:
1228      * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/keyset.html#KeySet-Set
1229      * Implementations that are unable to identify a key must use the key
1230      * identifier "Unidentified".
1231      */
1232     virtual DOMString getKeyIdentifier()
1233         { return keyIdentifier; }
1234
1235     /**
1236      * The keyLocation attribute contains an indication of the location of
1237      * they key on the device, as described in:
1238      * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html#ID-KeyboardEvent-KeyLocationCode
1239      */
1240     virtual unsigned long getKeyLocation()
1241         { return keyLocation; }
1242
1243     /**
1244      * true if the control (Ctrl) key modifier is activated.
1245      */
1246     virtual bool getCtrlKey()
1247         { return ctrlKey; }
1248
1249     /**
1250      * true if the shift (Shift) key modifier is activated.
1251      */
1252     virtual bool getShiftKey()
1253         { return shiftKey; }
1254
1255     /**
1256      * true if the alternative (Alt) key modifier is activated.
1257      */
1258     virtual bool getAltKey()
1259         { return altKey; }
1260
1261     /**
1262      * true if the meta (Meta) key modifier is activated.
1263      */
1264     virtual bool getMetaKey()
1265         { return metaKey; }
1266
1267     /**
1268      * This methods queries the state of a modifier using a key identifier.
1269      * The argument is a modifier key identifier. Common modifier keys are "Alt",
1270      * "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift".
1271      */
1272     virtual bool getModifierState(const DOMString &/*id*/)
1273         { return false; }
1274
1275     /**
1276      * The initKeyboardEvent method is used to initialize the value of a
1277      * KeyboardEvent object and has the same behavior as UIEvent.initUIEvent(). The
1278      * value of UIEvent.detail remains undefined.
1279      */
1280     virtual void initKeyboardEvent(const DOMString &/*typeArg*/,
1281                                    bool /*canBubbleArg*/,
1282                                    bool /*cancelableArg*/,
1283                                    const views::AbstractView */*viewArg*/,
1284                                    const DOMString &/*keyIdentifier*/,
1285                                    unsigned long /*keyLocation*/,
1286                                    const DOMString /*modifiersList*/)
1287         {
1288         }
1289
1290
1291
1292     /**
1293      * The initKeyboardEventNS method is used to initialize the value of a
1294      * KeyboardEvent object and has the same behavior as UIEvent.initUIEventNS(). The
1295      * value of UIEvent.detail remains undefined.
1296      */
1297     virtual void initKeyboardEventNS(const DOMString &/*namespaceURI*/,
1298                                      const DOMString &/*typeArg*/,
1299                                      bool /*canBubbleArg*/,
1300                                      bool /*cancelableArg*/,
1301                                      const views::AbstractView */*viewArg*/,
1302                                      const DOMString &/*keyIdentifier*/,
1303                                      unsigned long /*keyLocation*/,
1304                                      const DOMString /*modifiersList*/)
1305         {
1306         }
1307
1308
1309
1310     //##################
1311     //# Non-API methods
1312     //##################
1313
1314     /**
1315      *
1316      */
1317     KeyboardEvent() {}
1318
1319     /**
1320      *
1321      */
1322     KeyboardEvent(const KeyboardEvent &other) : Event(other), UIEvent(other)
1323         {
1324         keyIdentifier = other.keyIdentifier;
1325         keyLocation   = other.keyLocation;
1326         ctrlKey       = other.ctrlKey;
1327         shiftKey      = other.shiftKey;
1328         altKey        = other.altKey;
1329         metaKey       = other.metaKey;
1330         }
1331
1332     /**
1333      *
1334      */
1335     virtual ~KeyboardEvent() {}
1336
1337 protected:
1338
1339     DOMString keyIdentifier;
1340     unsigned long keyLocation;
1341     bool ctrlKey;
1342     bool shiftKey;
1343     bool altKey;
1344     bool metaKey;
1345 };
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355 /*#########################################################################
1356 ## MutationEvent
1357 #########################################################################*/
1358
1359 /**
1360  * The MutationEvent interface provides specific contextual information
1361  * associated with Mutation events.
1362  *
1363  * To create an instance of the MutationEvent interface, use the
1364  * DocumentEvent.createEvent("MutationEvent") method call.
1365  */
1366 class MutationEvent : virtual public Event
1367 {
1368 public:
1369
1370     /**
1371      * An integer indicating in which way the Attr was changed.
1372      */
1373     typedef enum
1374         {
1375         MODIFICATION = 1,
1376         ADDITION     = 2,
1377         REMOVAL      = 3
1378         } AttrChangeType;
1379
1380     /**
1381      * relatedNode is used to identify a secondary node related to a mutation event.
1382      * For example, if a mutation event is dispatched to a node indicating that its
1383      * parent has changed, the relatedNode is the changed parent. If an event is
1384      * instead dispatched to a subtree indicating a node was changed within it, the
1385      * relatedNode is the changed node. In the case of the
1386      * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event it indicates
1387      * the Attr node which was modified, added, or removed.
1388      */
1389     virtual NodePtr getRelatedNode()
1390         { return relatedNodePtr ; }
1391
1392     /**
1393      * prevValue indicates the previous value of the Attr node in
1394      * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the
1395      * CharacterData node in {"http://www.w3.org/2001/xml-events",
1396      * "DOMCharacterDataModified"} events.
1397      */
1398     virtual DOMString getPrevValue()
1399         { return prevValue; }
1400
1401     /**
1402      * newValue indicates the new value of the Attr node in
1403      * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the
1404      * CharacterData node in {"http://www.w3.org/2001/xml-events",
1405      * "DOMCharacterDataModified"} events.
1406      */
1407     virtual DOMString getNewValue()
1408         { return newValue; }
1409
1410     /**
1411      * attrName indicates the name of the changed Attr node in a
1412      * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event.
1413      */
1414     virtual DOMString getAttrName()
1415         { return attrName; }
1416
1417     /**
1418      * attrChange indicates the type of change which triggered the
1419      * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event. The values can
1420      * be MODIFICATION, ADDITION, or REMOVAL.
1421      */
1422     virtual unsigned short getAttrChange()
1423         {
1424         return attrChange;
1425         }
1426
1427     /**
1428      * The initMutationEvent method is used to initialize the value of a
1429      * MutationEvent object and has the same behavior as Event.initEvent().
1430      */
1431     virtual void initMutationEvent(const DOMString &/*typeArg*/,
1432                                    bool /*canBubbleArg*/,
1433                                    bool /*cancelableArg*/,
1434                                    const NodePtr   /*relatedNodeArg*/,
1435                                    const DOMString &/*prevValueArg*/,
1436                                    const DOMString &/*newValueArg*/,
1437                                    const DOMString &/*attrNameArg*/,
1438                                    unsigned short /*attrChangeArg*/)
1439         {
1440         }
1441
1442     /**
1443      * The initMutationEventNS method is used to initialize the value of a
1444      * MutationEvent object and has the same behavior as Event.initEventNS().
1445      */
1446     virtual void initMutationEventNS(const DOMString &/*namespaceURI*/,
1447                                      const DOMString &/*typeArg*/,
1448                                      bool /*canBubbleArg*/,
1449                                      bool /*cancelableArg*/,
1450                                      const NodePtr   /*relatedNodeArg*/,
1451                                      const DOMString &/*prevValueArg*/,
1452                                      const DOMString &/*newValueArg*/,
1453                                      const DOMString &/*attrNameArg*/,
1454                                      unsigned short /*attrChangeArg*/)
1455         {
1456         }
1457
1458
1459     //##################
1460     //# Non-API methods
1461     //##################
1462
1463     /**
1464      *
1465      */
1466     MutationEvent()
1467         {
1468         relatedNodePtr  = NULL;
1469         }
1470
1471     /**
1472      *
1473      */
1474     MutationEvent(const MutationEvent &other) : Event(other)
1475         {
1476         relatedNodePtr  = other.relatedNodePtr ;
1477         prevValue   = other.prevValue;
1478         newValue    = other.newValue;
1479         attrName    = other.attrName;
1480         attrChange  = other.attrChange;
1481         }
1482
1483     /**
1484      *
1485      */
1486     virtual ~MutationEvent() {}
1487
1488 protected:
1489
1490     NodePtr   relatedNodePtr ;
1491     DOMString prevValue;
1492     DOMString newValue;
1493     DOMString attrName;
1494     unsigned short attrChange;
1495
1496 };
1497
1498
1499
1500
1501 /*#########################################################################
1502 ## MutationNameEvent
1503 #########################################################################*/
1504
1505 /**
1506  * The MutationNameEvent interface provides specific contextual information
1507  * associated with Mutation name event types.
1508  *
1509  * To create an instance of the MutationNameEvent interface, use the
1510  * Document.createEvent("MutationNameEvent") method call.
1511  */
1512 class MutationNameEvent : virtual public MutationEvent
1513 {
1514 public:
1515
1516     /**
1517      * The previous value of the relatedNode's namespaceURI.
1518      */
1519     virtual DOMString getPrevNamespaceURI()
1520         { return prevNamespaceURI; }
1521
1522     /**
1523      * The previous value of the relatedNode's nodeName.
1524      */
1525     virtual DOMString getPrevNodeName()
1526         { return prevNodeName; }
1527
1528     /**
1529      * The initMutationNameEvent method is used to initialize the value of a
1530      * MutationNameEvent object and has the same behavior as
1531      * MutationEvent.initMutationEvent().
1532      */
1533     virtual void initMutationNameEvent(const DOMString &/*typeArg*/,
1534                                        bool /*canBubbleArg*/,
1535                                        bool /*cancelableArg*/,
1536                                        const NodePtr   /*relatedNodeArg*/,
1537                                        const DOMString &/*prevNamespaceURIArg*/,
1538                                        const DOMString &/*prevNodeNameArg*/)
1539         {
1540         }
1541
1542
1543     /**
1544      * The initMutationNameEventNS method is used to initialize the value of a
1545      * MutationNameEvent object and has the same behavior as
1546      * MutationEvent.initMutationEventNS().
1547      */
1548     virtual void initMutationNameEventNS(const DOMString &/*namespaceURI*/,
1549                                          const DOMString &/*typeArg*/,
1550                                          bool /*canBubbleArg*/,
1551                                          bool /*cancelableArg*/,
1552                                          const NodePtr   /*relatedNodeArg*/,
1553                                          const DOMString &/*prevNamespaceURIArg*/,
1554                                          const DOMString &/*prevNodeNameArg*/)
1555         {
1556         }
1557
1558
1559
1560     //##################
1561     //# Non-API methods
1562     //##################
1563
1564     /**
1565      *
1566      */
1567     MutationNameEvent() {}
1568
1569
1570     /**
1571      *
1572      */
1573     MutationNameEvent(const MutationNameEvent &other)
1574                           : Event(other), MutationEvent(other)
1575         {
1576         prevNamespaceURI  = other.prevNamespaceURI;
1577         prevNodeName      = other.prevNodeName;
1578         }
1579
1580
1581     /**
1582      *
1583      */
1584     virtual ~MutationNameEvent() {}
1585
1586 protected:
1587
1588     DOMString prevNamespaceURI;
1589     DOMString prevNodeName;
1590
1591
1592 };
1593
1594
1595
1596
1597
1598
1599 }  //namespace events
1600 }  //namespace dom
1601 }  //namespace w3c
1602 }  //namespace org
1603
1604 #endif   /* __EVENTS_H__ */
1605
1606 /*#########################################################################
1607 ## E N D    O F    F I L E
1608 #########################################################################*/
1609