Docs/Types/Event.md

   1 Type: Event {#Event}
   2 ====================
   3
   4 MooTools Event Methods.
   5
   6 Event Method: constructor {#Event:constructor}
   7 ----------------------------------------------
   8
   9 ### Syntax:
  10
  11         new Event([event[, win]]);
  12
  13 ### Arguments:
  14
  15 1. event - (*event*, required) An HTMLEvent Object.
  16 2. win   - (*window*, optional: defaults to window) The context of the event.
  17
  18 #### Properties:
  19
  20 * page.x        - (*number*) The x position of the mouse, relative to the full window.
  21 * page.y        - (*number*) The y position of the mouse, relative to the full window.
  22 * client.x      - (*number*) The x position of the mouse, relative to the viewport.
  23 * client.y      - (*number*) The y position of the mouse, relative to the viewport.
  24 * rightClick    - (*boolean*) True if the user clicked the right mousebutton
  25 * wheel         - (*number*) The amount of third button scrolling.
  26 * relatedTarget - (*element*) The event related target, NOT `extended` with [$][].
  27 * target        - (*element*) The event target, not extended with [$][] for performance reasons.
  28 * code          - (*number*) The keycode of the key pressed.
  29 * key           - (*string*) The key pressed as a lowercase string. key can be 'enter', 'up', 'down', 'left', 'right', 'space', 'backspace', 'delete', and 'esc'.
  30 * shift         - (*boolean*) True if the user pressed the shift key.
  31 * control       - (*boolean*) True if the user pressed the control key.
  32 * alt           - (*boolean*) True if the user pressed the alt key.
  33 * meta          - (*boolean*) True if the user pressed the meta key.
  34
  35 ### Examples:
  36
  37         $('myLink').addEvent('keydown', function(event){
  38                 // the passed event parameter is already an instance of the Event class.
  39                 alert(event.key);   // returns the lowercase letter pressed.
  40                 alert(event.shift); // returns true if the key pressed is shift.
  41                 if (event.key == 's' && event.control) alert('Document saved.'); //executes if the user presses Ctr+S.
  42         });
  43
  44 ### Notes:
  45
  46 - Accessing event.page / event.client requires the page to be in [Standards Mode](http://hsivonen.iki.fi/doctype/).
  47 - Every event added with addEvent gets the MooTools method automatically, without the need to manually instance it.
  48
  49
  50 Event Method: stop {#Event:stop}
  51 --------------------------------
  52
  53 Stop an Event from propagating and also executes preventDefault.
  54
  55 ### Syntax:
  56
  57         myEvent.stop();
  58
  59 ### Returns:
  60
  61 * (*object*) This Event instance.
  62
  63 ### Examples:
  64
  65 ##### HTML:
  66
  67         <a id="myAnchor" href="http://google.com/">Visit Google.com</a>
  68
  69 ##### JavaScript
  70
  71         $('myAnchor').addEvent('click', function(event){
  72                 event.stop(); //Prevents the browser from following the link.
  73                 this.set('text', 'Where do you think you\'re going?'); //'this' is Element that fires the Event.
  74                 (function(){
  75                         this.set('text','Instead visit the Blog.').set('href', 'http://blog.mootools.net');
  76                 }).delay(500, this);
  77         });
  78
  79 ### Notes:
  80
  81 - Returning false within the function can also stop the propagation of the Event.
  82
  83 ### See Also:
  84
  85 - [Element.addEvent](#Element:addEvent), [Element.stopPropagation](#Event:stopPropagation), [Event.preventDefault](#Event:preventDefault), [Function:delay][]
  86
  87
  88
  89 Event Method: stopPropagation {#Event:stopPropagation}
  90 ------------------------------------------------------
  91
  92 Cross browser method to stop the propagation of an event (this stops the event from bubbling up through the DOM).
  93
  94 ### Syntax:
  95
  96         myEvent.stopPropagation();
  97
  98 ### Returns:
  99
 100 * (*object*) This Event object.
 101
 102 ### Examples:
 103
 104 "#myChild" does not cover the same area as myElement. Therefore, the 'click' differs from parent and child depending on the click location:
 105
 106 ##### HTML:
 107
 108         <div id="myElement">
 109                 <div id="myChild"></div>
 110         </div>
 111
 112 ##### JavaScript
 113
 114         $('myElement').addEvent('click', function(){
 115                 alert('click');
 116                 return false; //equivalent to stopPropagation.
 117         });
 118         $('myChild').addEvent('click', function(event){
 119                 event.stopPropagation(); //prevents the event from bubbling up, and fires the parent's click event.
 120         });
 121
 122 ### See Also:
 123
 124 - [Element:addEvent][]
 125 - [MDC event.stopPropagation](http://developer.mozilla.org/en/docs/DOM:event.stopPropagation)
 126
 127
 128
 129 Event Method: preventDefault {#Event:preventDefault}
 130 ----------------------------------------------------
 131
 132 Cross browser method to prevent the default action of the event.
 133
 134 ### Syntax:
 135
 136         myEvent.preventDefault();
 137
 138 ### Returns:
 139
 140 * (*object*) This Event object.
 141
 142 ### Examples:
 143
 144 ##### HTML:
 145
 146         <form>
 147                 <input id="myCheckbox" type="checkbox" />
 148         </form>
 149
 150 ##### JavaScript
 151
 152         $('myCheckbox').addEvent('click', function(event){
 153                 event.preventDefault(); //prevents the checkbox from being "checked".
 154         });
 155
 156 ### See Also:
 157
 158 - [Element:addEvent][]
 159 - [MDC event.preventDefault](http://developer.mozilla.org/en/docs/DOM:event.preventDefault)
 160
 161
 162 Object: Event.Keys {#Event-Keys}
 163 ==============================
 164
 165 Additional Event key codes can be added by adding properties to the Event.Keys Object.
 166
 167 #### Example:
 168
 169     Event.Keys.shift = 16;
 170     $('myInput').addEvent('keydown', function(event){
 171             if (event.key == 'shift') alert('You pressed shift.');
 172     });
 173
 174 #### Possible Keys:
 175
 176 - enter
 177 - up
 178 - down
 179 - left
 180 - right
 181 - esc
 182 - space
 183 - backspace
 184 - tab
 185 - delete
 186
 187 ### See Also:
 188
 189 - [MooTools More Keyboard][]
 190
 191 ### Note:
 192
 193 Since MooTools 1.3 this is a native JavaScript Object and not an instance of the deprecated Hash
 194
 195
 196 [Element:addEvent]: /core/Element/Element.Event#Element:addEvent
 197 [Function]: /core/Types/Function
 198 [Function:bind]: /core/Types/Function/#Function:bind
 199 [Function:pass]: /core/Types/Function/#Function:pass
 200 [Function:delay]: /core/Types/Function/#Function:delay
 201 [MooTools More Keyboard]: /more/Interface/Keyboard