Docs/Element/Element.Event.md

   1 Type: Element {#Element}
   2 ==========================
   3
   4 - Custom Type to allow all of its methods to be used with any DOM element via the dollar function [$][].
   5 - These methods are also available on window and document.
   6
   7 ### Notes:
   8 - Internet Explorer fires element events in random order if they are not fired by [Element:fireEvent](#Element:fireEvent).
   9
  10
  11 Element Method: addEvent {#Element:addEvent}
  12 --------------------------------------------
  13
  14 Attaches an event listener to a DOM element.
  15
  16 ### Syntax:
  17
  18         myElement.addEvent(type, fn);
  19
  20 ### Arguments:
  21
  22 1. type - (*string*) The event name to monitor ('click', 'load', etc) without the prefix 'on'.
  23 2. fn   - (*function*) The function to execute.
  24
  25 ### Returns:
  26
  27 * (*element*) This Element.
  28
  29 ### Examples:
  30
  31 ##### HTML:
  32
  33         <div id="myElement">Click me.</div>
  34
  35 ##### JavaScript
  36
  37         $('myElement').addEvent('click', function(){
  38                 alert('clicked!');
  39         });
  40
  41 ### Notes:
  42
  43 - You can stop the Event by returning false in the listener or calling [Event:stop](#Event:stop).
  44 - This method is also attached to Document and Window.
  45
  46 ### See Also:
  47
  48 - [w3schools Event Attributes](http://www.w3schools.com/html/html_eventattributes.asp)
  49
  50
  51
  52 Element Method: removeEvent {#Element:removeEvent}
  53 --------------------------------------------------
  54
  55 Works as Element.addEvent, but instead removes the specified event listener.
  56
  57 ### Syntax:
  58
  59         myElement.removeEvent(type, fn);
  60
  61 ### Arguments:
  62
  63 1. type - (*string*) The event name.
  64 2. fn   - (*function*) The function to remove.
  65
  66 ### Returns:
  67
  68 * (*element*) This Element.
  69
  70 ### Examples:
  71
  72 #### Standard usage:
  73
  74         var destroy = function(){ alert('Boom: ' + this.id); } // this refers to the Element.
  75         $('myElement').addEvent('click', destroy);
  76
  77         //later...
  78         $('myElement').removeEvent('click', destroy);
  79
  80
  81 #### Examples with bind:
  82
  83         var destroy = function(){ alert('Boom: ' + this.id); }
  84         var boundDestroy = destroy.bind($('anotherElement'));
  85         $('myElement').addEvent('click', boundDestroy);
  86
  87         //later...
  88         $('myElement').removeEvent('click', destroy); // this won't remove the event.
  89         $('myElement').removeEvent('click', destroy.bind($('anotherElement')); // this won't remove the event either.
  90         $('myElement').removeEvent('click', boundDestroy); // the correct way to remove the event.
  91
  92 ### Notes:
  93
  94 - When the function is added using [Function:bind][] or [Function:pass][], etc, a new reference is created.  For removeEvent to work, you must pass a reference to the exact function to be removed.
  95 - This method is also attached to Document and Window.
  96
  97
  98
  99 Element Method: addEvents {#Element:addEvents}
 100 ----------------------------------------------
 101
 102 The same as [Element:addEvent](#Element:addEvent), but accepts an object to add multiple events at once.
 103
 104 ### Syntax:
 105
 106         myElement.addEvents(events);
 107
 108 ### Arguments:
 109
 110 1. events - (*object*) An object with key/value representing: key the event name, and value the function that is called when the Event occurs.
 111
 112 ### Returns:
 113
 114 * (*element*) This Element.
 115
 116 ### Examples:
 117
 118         $('myElement').addEvents({
 119                 mouseover: function(){
 120                         alert('mouseover');
 121                 },
 122                 click: function(){
 123                         alert('click');
 124                 }
 125         });
 126
 127 ### Notes:
 128
 129 - This method is also attached to Document and Window.
 130
 131 ### See Also:
 132
 133 - [Element:addEvent](#Element:addEvent)
 134
 135
 136
 137 Element Method: removeEvents {#Element:removeEvents}
 138 ----------------------------------------------------
 139
 140 Removes all events of a certain type from an Element. If no argument is passed, removes all events of all types.
 141
 142 ### Syntax:
 143
 144         myElements.removeEvents([events]);
 145
 146 ### Arguments:
 147
 148 1. events - (optional) if not passed removes all events from the element.
 149         - (*string*) The event name (e.g. 'click'). Removes all events of that type.
 150         - (*object*) An object of type function pairs. Like the one passed to [Element:addEvent](#Element:addEvent).
 151
 152 ### Returns:
 153
 154 * (*element*) This Element.
 155
 156 ### Examples:
 157
 158         var myElement = $('myElement');
 159         myElement.addEvents({
 160                 mouseover: function(){
 161                         alert('mouseover');
 162                 },
 163                 click: function(){
 164                         alert('click');
 165                 }
 166         });
 167
 168         myElement.addEvent('click', function(){ alert('clicked again'); });
 169         myElement.addEvent('click', function(){ alert('clicked and again :('); });
 170         //addEvent will keep appending each function.
 171         //Unfortunately for the visitor, there will be three alerts they'll have to click on.
 172         myElement.removeEvents('click'); // saves the visitor's finger by removing every click event.
 173
 174 ### Notes:
 175
 176 - This method is also attached to Document and Window.
 177
 178 ### See Also:
 179
 180 - [Element:removeEvent](#Element:removeEvent)
 181
 182 Element Method: fireEvent {#Element:fireEvent}
 183 ----------------------------------------------
 184
 185 Executes all events of the specified type present in the Element.
 186
 187 ### Syntax:
 188
 189         myElement.fireEvent(type[, args[, delay]]);
 190
 191 ### Arguments:
 192
 193 1. type  - (*string*) The event name (e.g. 'click')
 194 2. args  - (*mixed*, optional) Array or single object, arguments to pass to the function. If more than one argument, must be an array.
 195 3. delay - (*number*, optional) Delay (in ms) to wait to execute the event.
 196
 197 ### Returns:
 198
 199 * (*element*) This Element.
 200
 201 ### Examples:
 202         // fires all the added 'click' events and passes the Element 'anElement' after one second
 203         $('myElement').fireEvent('click', $('anElement'), 1000);
 204
 205 ### Notes:
 206
 207 - This will not fire the DOM Event (this concerns all inline events ie. onmousedown="..").
 208 - This method is also attached to Document and Window.
 209
 210 Element Method: cloneEvents {#Element:cloneEvents}
 211 --------------------------------------------------
 212
 213 Clones all events from an Element to this Element.
 214
 215 ### Syntax:
 216
 217         myElement.cloneEvents(from[, type]);
 218
 219 ### Arguments:
 220
 221 1. from - (*element*) Copy all events from this Element.
 222 2. type - (*string*, optional) Copies only events of this type. If null, copies all events.
 223
 224 ### Returns:
 225
 226 * (*element*) This Element.
 227
 228 ### Examples:
 229
 230         var myElement = $('myElement');
 231         var myClone = myElement.clone().cloneEvents(myElement); // clones the element and its events
 232
 233 ### Notes:
 234
 235 - This method is also attached to Document and Window.
 236
 237 Object: Element.Events {#Element-Events}
 238 ========================================
 239
 240 You can add additional custom events by adding properties (objects) to the Element.Events Object
 241
 242 ### Arguments:
 243
 244 The Element.Events.yourProperty (object) can have:
 245
 246 1. base - (*string*, optional) the base event the custom event will listen to. Its not optional if condition is set.
 247 2. condition - (*function*, optional) the condition from which we determine if the custom event can be fired. Is bound to the element you add the event to. The Event is passed in.
 248 3. onAdd - (*function*, optional) the function that will get fired when the custom event is added. Is bound to the element you add the event to.
 249 4. onRemove - (*function*, optional) the function that will get fired when the custom event is removed. Is bound to the element you add the event to.
 250
 251 ### Examples:
 252
 253         Element.Events.shiftclick = {
 254                 base: 'click', // the base event type
 255                 condition: function(event){ //a function to perform additional checks
 256                         return (event.shift == true); // this means the event is free to fire
 257                 }
 258         };
 259
 260         $('myInput').addEvent('shiftclick', function(event){
 261                 log('the user clicked the left mouse button while holding the shift key');
 262         });
 263
 264 ### Notes:
 265
 266 - There are different types of custom Events you can create:
 267  1. Custom Events with only base: they will just be a redirect to the base event.
 268  2. Custom Events with base and condition: they will be redirect to the base event, but only fired if the condition is met.
 269  3. Custom Events with onAdd and/or onRemove and any other of the above: they will also perform additional functions when the event is added/removed.
 270 - Since MooTools 1.3 this is a native JavaScript Object and not an instance of the deprecated Hash
 271
 272 ### Warning:
 273
 274 If you use the condition option you NEED to specify a base type, unless you plan to overwrite a native event.
 275 (highly unrecommended: use only when you know exactly what you're doing).
 276
 277
 278
 279 Built-in Custom Events
 280 ----------------------
 281
 282
 283 ### Event: mouseenter {#Element-Events:mouseenter}
 284
 285 This event fires when the mouse enters the area of the DOM Element and will not be fired again if the mouse crosses over children of the Element (unlike mouseover).
 286
 287 #### Examples:
 288
 289         $('myElement').addEvent('mouseenter', myFunction);
 290
 291 #### See Also:
 292
 293 - [Element:addEvent](#Element:addEvent)
 294
 295 ### Event: mouseleave {#Element-Events:mouseleave}
 296
 297 This event fires when the mouse leaves the area of the DOM Element and will not be fired if the mouse crosses over children of the Element (unlike mouseout).
 298
 299 #### Examples:
 300
 301         $('myElement').addEvent('mouseleave', myFunction);
 302
 303 #### See Also:
 304
 305 - [Element:addEvent](#Element:addEvent)
 306
 307 ### Event: mousewheel {#Element-Events:mousewheel}
 308
 309 This event fires when the mouse wheel is rotated;
 310
 311 #### Examples:
 312
 313         $('myElement').addEvent('mousewheel', myFunction);
 314
 315 #### Notes:
 316
 317 - This custom event just redirects DOMMouseScroll (Mozilla) to mousewheel (Opera, Internet Explorer), making it work across browsers.
 318
 319 #### See Also:
 320
 321 - [Element:addEvent](#Element:addEvent)
 322
 323
 324
 325 Deprecated Functions {#Deprecated-Functions}
 326 ============================================
 327
 328
 329 [$]: /core/Element/Element#Window:dollar
 330 [Function]: /core/Types/Function
 331 [Function:bind]: /core/Types/Function/#bind
 332 [Function:pass]: /core/Types/Function/#pass
 333 [Function:delay]: /core/Types/Function/#delay