Docs/Types/DOMEvent.md

   1 Type: DOMEvent {#Event}
   2 ====================
   3
   4 MooTools DOMEvent Methods.
   5
   6 DOMEvent Method: constructor {#DOMEvent:constructor}
   7 ----------------------------------------------------
   8
   9 ### Syntax:
  10
  11         new DOMEvent([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.
  27 * target        - (*element*) The event target.
  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', 'tab', '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 type.
  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 - `event.key` is only reliable with `keydown` or `keyup` events. See [PPK](http://www.quirksmode.org/js/keys.html).
  49
  50 DOMEvent Method: stop {#DOMEvent: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 DOMEvent 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), [DOMEvent.stopPropagation](#DOMEvent:stopPropagation), [DOMEvent.preventDefault](#DOMEvent:preventDefault), [Function:delay][]
  86
  87
  88 DOMEvent Method: stopPropagation {#DOMEvent:stopPropagation}
  89 ------------------------------------------------------------
  90
  91 Cross browser method to stop the propagation of an event (this stops the event from bubbling up through the DOM).
  92
  93 ### Syntax:
  94
  95         myEvent.stopPropagation();
  96
  97 ### Returns:
  98
  99 * (*object*) This DOMEvent object.
 100
 101 ### Examples:
 102
 103 "#myChild" does not cover the same area as myElement. Therefore, the 'click' differs from parent and child depending on the click location:
 104
 105 ##### HTML:
 106
 107         <div id="myElement">
 108                 <div id="myChild"></div>
 109         </div>
 110
 111 ##### JavaScript
 112
 113         $('myElement').addEvent('click', function(){
 114                 alert('click');
 115                 return false; //equivalent to stopPropagation.
 116         });
 117         $('myChild').addEvent('click', function(event){
 118                 event.stopPropagation(); //prevents the event from bubbling up, and fires the parent's click event.
 119         });
 120
 121 ### See Also:
 122
 123 - [Element:addEvent][]
 124 - [MDN event.stopPropagation][]
 125
 126
 127 DOMEvent Method: preventDefault {#DOMEvent:preventDefault}
 128 --------------------------------------------
 129
 130 Cross browser method to prevent the default action of the event.
 131
 132 ### Syntax:
 133
 134         myEvent.preventDefault();
 135
 136 ### Returns:
 137
 138 * (*object*) This DOMEvent object.
 139
 140 ### Examples:
 141
 142 ##### HTML:
 143
 144         <form>
 145                 <input id="myCheckbox" type="checkbox" />
 146         </form>
 147
 148 ##### JavaScript
 149
 150         $('myCheckbox').addEvent('click', function(event){
 151                 event.preventDefault(); //prevents the checkbox from being "checked".
 152         });
 153
 154 ### See Also:
 155
 156 - [Element:addEvent][]
 157 - [MDN event.preventDefault][]
 158
 159
 160 Function: DOMEvent.defineKey {#DOMEvent:DOMEvent-defineKey}
 161 -----------------------------------------------------------
 162
 163 This function allows to add an additional event key code.
 164
 165 #### Example:
 166
 167         DOMEvent.defineKey(16, 'shift');
 168     $('myInput').addEvent('keydown', function(event){
 169             if (event.key == 'shift') alert('You pressed shift.');
 170     });
 171
 172 #### Predefined keys:
 173
 174 - enter
 175 - up
 176 - down
 177 - left
 178 - right
 179 - esc
 180 - space
 181 - backspace
 182 - tab
 183 - delete
 184
 185 ### See Also:
 186
 187 - [MooTools More Keyboard][]
 188
 189
 190 Function: DOMEvent.defineKeys {#DOMEvent:DOMEvent-defineKey}
 191 -----------------------------------------------------------
 192
 193 This function allows to add additional event key codes.
 194
 195 #### Example:
 196
 197         DOMEvent.defineKeys({
 198                 '16': 'shift',
 199                 '17': 'control'
 200         });
 201     $('myInput').addEvent('keydown', function(event){
 202             if (event.key == 'control') alert('You pressed control.');
 203     });
 204
 205
 206 [Element:addEvent]: /core/Element/Element.Event#Element:addEvent
 207 [Function]: /core/Types/Function
 208 [Function:bind]: /core/Types/Function/#Function:bind
 209 [Function:pass]: /core/Types/Function/#Function:pass
 210 [Function:delay]: /core/Types/Function/#Function:delay
 211 [MooTools More Keyboard]: /more/Interface/Keyboard
 212
 213 [MDN event.stopPropagation]: https://developer.mozilla.org/en/DOM/event.stopPropagation
 214 [MDN event.preventDefault]: https://developer.mozilla.org/en/DOM/event.preventDefault