EaselJS v1.0.0 API Documentation : createjs/events/Event.js

API Documentation for: 1.0.0
Show:

File:Event.js

  1. /*
  2. * Event
  3. * Visit http://createjs.com/ for documentation, updates and examples.
  4. *
  5. * Copyright (c) 2010 gskinner.com, inc.
  6. *
  7. * Permission is hereby granted, free of charge, to any person
  8. * obtaining a copy of this software and associated documentation
  9. * files (the "Software"), to deal in the Software without
  10. * restriction, including without limitation the rights to use,
  11. * copy, modify, merge, publish, distribute, sublicense, and/or sell
  12. * copies of the Software, and to permit persons to whom the
  13. * Software is furnished to do so, subject to the following
  14. * conditions:
  15. *
  16. * The above copyright notice and this permission notice shall be
  17. * included in all copies or substantial portions of the Software.
  18. *
  19. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  20. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  21. * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  22. * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  23. * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  24. * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  25. * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  26. * OTHER DEALINGS IN THE SOFTWARE.
  27. */
  28.  
  29. /**
  30. * A collection of Classes that are shared across all the CreateJS libraries. The classes are included in the minified
  31. * files of each library and are available on the createjs namespace directly.
  32. *
  33. * <h4>Example</h4>
  34. *
  35. * myObject.addEventListener("change", createjs.proxy(myMethod, scope));
  36. *
  37. * @module CreateJS
  38. * @main CreateJS
  39. */
  40.  
  41. // namespace:
  42. this.createjs = this.createjs||{};
  43.  
  44. (function() {
  45. "use strict";
  46.  
  47. // constructor:
  48. /**
  49. * Contains properties and methods shared by all events for use with
  50. * {{#crossLink "EventDispatcher"}}{{/crossLink}}.
  51. *
  52. * Note that Event objects are often reused, so you should never
  53. * rely on an event object's state outside of the call stack it was received in.
  54. * @class Event
  55. * @param {String} type The event type.
  56. * @param {Boolean} bubbles Indicates whether the event will bubble through the display list.
  57. * @param {Boolean} cancelable Indicates whether the default behaviour of this event can be cancelled.
  58. * @constructor
  59. **/
  60. function Event(type, bubbles, cancelable) {
  61. // public properties:
  62. /**
  63. * The type of event.
  64. * @property type
  65. * @type String
  66. **/
  67. this.type = type;
  68. /**
  69. * The object that generated an event.
  70. * @property target
  71. * @type Object
  72. * @default null
  73. * @readonly
  74. */
  75. this.target = null;
  76. /**
  77. * The current target that a bubbling event is being dispatched from. For non-bubbling events, this will
  78. * always be the same as target. For example, if childObj.parent = parentObj, and a bubbling event
  79. * is generated from childObj, then a listener on parentObj would receive the event with
  80. * target=childObj (the original target) and currentTarget=parentObj (where the listener was added).
  81. * @property currentTarget
  82. * @type Object
  83. * @default null
  84. * @readonly
  85. */
  86. this.currentTarget = null;
  87. /**
  88. * For bubbling events, this indicates the current event phase:<OL>
  89. * <LI> capture phase: starting from the top parent to the target</LI>
  90. * <LI> at target phase: currently being dispatched from the target</LI>
  91. * <LI> bubbling phase: from the target to the top parent</LI>
  92. * </OL>
  93. * @property eventPhase
  94. * @type Number
  95. * @default 0
  96. * @readonly
  97. */
  98. this.eventPhase = 0;
  99. /**
  100. * Indicates whether the event will bubble through the display list.
  101. * @property bubbles
  102. * @type Boolean
  103. * @default false
  104. * @readonly
  105. */
  106. this.bubbles = !!bubbles;
  107. /**
  108. * Indicates whether the default behaviour of this event can be cancelled via
  109. * {{#crossLink "Event/preventDefault"}}{{/crossLink}}. This is set via the Event constructor.
  110. * @property cancelable
  111. * @type Boolean
  112. * @default false
  113. * @readonly
  114. */
  115. this.cancelable = !!cancelable;
  116. /**
  117. * The epoch time at which this event was created.
  118. * @property timeStamp
  119. * @type Number
  120. * @default 0
  121. * @readonly
  122. */
  123. this.timeStamp = (new Date()).getTime();
  124. /**
  125. * Indicates if {{#crossLink "Event/preventDefault"}}{{/crossLink}} has been called
  126. * on this event.
  127. * @property defaultPrevented
  128. * @type Boolean
  129. * @default false
  130. * @readonly
  131. */
  132. this.defaultPrevented = false;
  133. /**
  134. * Indicates if {{#crossLink "Event/stopPropagation"}}{{/crossLink}} or
  135. * {{#crossLink "Event/stopImmediatePropagation"}}{{/crossLink}} has been called on this event.
  136. * @property propagationStopped
  137. * @type Boolean
  138. * @default false
  139. * @readonly
  140. */
  141. this.propagationStopped = false;
  142. /**
  143. * Indicates if {{#crossLink "Event/stopImmediatePropagation"}}{{/crossLink}} has been called
  144. * on this event.
  145. * @property immediatePropagationStopped
  146. * @type Boolean
  147. * @default false
  148. * @readonly
  149. */
  150. this.immediatePropagationStopped = false;
  151. /**
  152. * Indicates if {{#crossLink "Event/remove"}}{{/crossLink}} has been called on this event.
  153. * @property removed
  154. * @type Boolean
  155. * @default false
  156. * @readonly
  157. */
  158. this.removed = false;
  159. }
  160. var p = Event.prototype;
  161.  
  162. // public methods:
  163. /**
  164. * Sets {{#crossLink "Event/defaultPrevented:property"}}{{/crossLink}} to true if the event is cancelable.
  165. * Mirrors the DOM level 2 event standard. In general, cancelable events that have `preventDefault()` called will
  166. * cancel the default behaviour associated with the event.
  167. * @method preventDefault
  168. **/
  169. p.preventDefault = function() {
  170. this.defaultPrevented = this.cancelable&&true;
  171. };
  172.  
  173. /**
  174. * Sets {{#crossLink "Event/propagationStopped:property"}}{{/crossLink}} to true.
  175. * Mirrors the DOM event standard.
  176. * @method stopPropagation
  177. **/
  178. p.stopPropagation = function() {
  179. this.propagationStopped = true;
  180. };
  181.  
  182. /**
  183. * Sets {{#crossLink "Event/propagationStopped:property"}}{{/crossLink}} and
  184. * {{#crossLink "Event/immediatePropagationStopped:property"}}{{/crossLink}} to true.
  185. * Mirrors the DOM event standard.
  186. * @method stopImmediatePropagation
  187. **/
  188. p.stopImmediatePropagation = function() {
  189. this.immediatePropagationStopped = this.propagationStopped = true;
  190. };
  191. /**
  192. * Causes the active listener to be removed via removeEventListener();
  193. *
  194. * myBtn.addEventListener("click", function(evt) {
  195. * // do stuff...
  196. * evt.remove(); // removes this listener.
  197. * });
  198. *
  199. * @method remove
  200. **/
  201. p.remove = function() {
  202. this.removed = true;
  203. };
  204. /**
  205. * Returns a clone of the Event instance.
  206. * @method clone
  207. * @return {Event} a clone of the Event instance.
  208. **/
  209. p.clone = function() {
  210. return new Event(this.type, this.bubbles, this.cancelable);
  211. };
  212. /**
  213. * Provides a chainable shortcut method for setting a number of properties on the instance.
  214. *
  215. * @method set
  216. * @param {Object} props A generic object containing properties to copy to the instance.
  217. * @return {Event} Returns the instance the method is called on (useful for chaining calls.)
  218. * @chainable
  219. */
  220. p.set = function(props) {
  221. for (var n in props) { this[n] = props[n]; }
  222. return this;
  223. };
  224.  
  225. /**
  226. * Returns a string representation of this object.
  227. * @method toString
  228. * @return {String} a string representation of the instance.
  229. **/
  230. p.toString = function() {
  231. return "[Event (type="+this.type+")]";
  232. };
  233.  
  234. createjs.Event = Event;
  235. }());
  236.