/src/com/greensock/loading/data/CSSLoaderVars.as

https://bitbucket.org/HopeSky/mars_nd2d · ActionScript · 184 lines · 77 code · 28 blank · 79 comment · 6 complexity · 177b3e3b0070ae0d804ed3c6421676f9 MD5 · raw file

  1. /**
  2. * VERSION: 1.2
  3. * DATE: 2011-03-23
  4. * AS3
  5. * UPDATES AND DOCS AT: http://www.greensock.com/loadermax/
  6. **/
  7. package com.greensock.loading.data {
  8. import flash.display.DisplayObject;
  9. /**
  10. * Can be used instead of a generic Object to define the <code>vars</code> parameter of a CSSLoader's constructor. <br /><br />
  11. *
  12. * There are 2 primary benefits of using a CSSLoaderVars instance to define your CSSLoader variables:
  13. * <ol>
  14. * <li> In most code editors, code hinting will be activated which helps remind you which special properties are available in CSSLoader</li>
  15. * <li> It enables strict data typing for improved debugging (ensuring, for example, that you don't define a Boolean value for <code>onComplete</code> where a Function is expected).</li>
  16. * </ol><br />
  17. *
  18. * The down side, of course, is that the code is more verbose and the CSSLoaderVars class adds slightly more kb to your swf.
  19. *
  20. * <b>USAGE:</b><br /><br />
  21. * Note that each method returns the CSSLoaderVars instance, so you can reduce the lines of code by method chaining (see example below).<br /><br />
  22. *
  23. * <b>Without CSSLoaderVars:</b><br /><code>
  24. * new CSSLoader("styles.css", {name:"css", estimatedBytes:1500, onComplete:completeHandler, onProgress:progressHandler})</code><br /><br />
  25. *
  26. * <b>With CSSLoaderVars</b><br /><code>
  27. * new CSSLoader("styles.css", new CSSLoaderVars().name("css").estimatedBytes(1500).onComplete(completeHandler).onProgress(progressHandler))</code><br /><br />
  28. *
  29. * <b>NOTES:</b><br />
  30. * <ul>
  31. * <li> To get the generic vars object that CSSLoaderVars builds internally, simply access its "vars" property.
  32. * In fact, if you want maximum backwards compatibility, you can tack ".vars" onto the end of your chain like this:<br /><code>
  33. * new CSSLoader("styles.css", new CSSLoaderVars().name("css").estimatedBytes(1500).vars);</code></li>
  34. * <li> Using CSSLoaderVars is completely optional. If you prefer the shorter synatax with the generic Object, feel
  35. * free to use it. The purpose of this class is simply to enable code hinting and to allow for strict data typing.</li>
  36. * </ul>
  37. *
  38. * <b>Copyright 2011, GreenSock. All rights reserved.</b> This work is subject to the terms in <a href="http://www.greensock.com/terms_of_use.html">http://www.greensock.com/terms_of_use.html</a> or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.
  39. *
  40. * @author Jack Doyle, jack@greensock.com
  41. */
  42. public class CSSLoaderVars {
  43. /** @private **/
  44. public static const version:Number = 1.2;
  45. /** @private **/
  46. protected var _vars:Object;
  47. /**
  48. * Constructor
  49. * @param vars A generic Object containing properties that you'd like to add to this CSSLoaderVars instance.
  50. */
  51. public function CSSLoaderVars(vars:Object=null) {
  52. _vars = {};
  53. if (vars != null) {
  54. for (var p:String in vars) {
  55. _vars[p] = vars[p];
  56. }
  57. }
  58. }
  59. /** @private **/
  60. protected function _set(property:String, value:*):CSSLoaderVars {
  61. if (value == null) {
  62. delete _vars[property]; //in case it was previously set
  63. } else {
  64. _vars[property] = value;
  65. }
  66. return this;
  67. }
  68. /**
  69. * Adds a dynamic property to the vars object containing any value you want. This can be useful
  70. * in situations where you need to associate certain data with a particular loader. Just make sure
  71. * that the property name is a valid variable name (starts with a letter or underscore, no special characters, etc.)
  72. * and that it doesn't use a reserved property name like "name" or "onComplete", etc.
  73. *
  74. * For example, to set an "index" property to 5, do:
  75. *
  76. * <code>prop("index", 5);</code>
  77. *
  78. * @param property Property name
  79. * @param value Value
  80. */
  81. public function prop(property:String, value:*):CSSLoaderVars {
  82. return _set(property, value);
  83. }
  84. //---- LOADERCORE PROPERTIES -----------------------------------------------------------------
  85. /** When <code>autoDispose</code> is <code>true</code>, the loader will be disposed immediately after it completes (it calls the <code>dispose()</code> method internally after dispatching its <code>COMPLETE</code> event). This will remove any listeners that were defined in the vars object (like onComplete, onProgress, onError, onInit). Once a loader is disposed, it can no longer be found with <code>LoaderMax.getLoader()</code> or <code>LoaderMax.getContent()</code> - it is essentially destroyed but its content is not unloaded (you must call <code>unload()</code> or <code>dispose(true)</code> to unload its content). The default <code>autoDispose</code> value is <code>false</code>.**/
  86. public function autoDispose(value:Boolean):CSSLoaderVars {
  87. return _set("autoDispose", value);
  88. }
  89. /** A name that is used to identify the loader instance. This name can be fed to the <code>LoaderMax.getLoader()</code> or <code>LoaderMax.getContent()</code> methods or traced at any time. Each loader's name should be unique. If you don't define one, a unique name will be created automatically, like "loader21". **/
  90. public function name(value:String):CSSLoaderVars {
  91. return _set("name", value);
  92. }
  93. /** A handler function for <code>LoaderEvent.CANCEL</code> events which are dispatched when loading is aborted due to either a failure or because another loader was prioritized or <code>cancel()</code> was manually called. Make sure your onCancel function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). **/
  94. public function onCancel(value:Function):CSSLoaderVars {
  95. return _set("onCancel", value);
  96. }
  97. /** A handler function for <code>LoaderEvent.COMPLETE</code> events which are dispatched when the loader has finished loading successfully. Make sure your onComplete function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). **/
  98. public function onComplete(value:Function):CSSLoaderVars {
  99. return _set("onComplete", value);
  100. }
  101. /** A handler function for <code>LoaderEvent.ERROR</code> events which are dispatched whenever the loader experiences an error (typically an IO_ERROR or SECURITY_ERROR). An error doesn't necessarily mean the loader failed, however - to listen for when a loader fails, use the <code>onFail</code> special property. Make sure your onError function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). **/
  102. public function onError(value:Function):CSSLoaderVars {
  103. return _set("onError", value);
  104. }
  105. /** A handler function for <code>LoaderEvent.FAIL</code> events which are dispatched whenever the loader fails and its <code>status</code> changes to <code>LoaderStatus.FAILED</code>. Make sure your onFail function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). **/
  106. public function onFail(value:Function):CSSLoaderVars {
  107. return _set("onFail", value);
  108. }
  109. /** A handler function for <code>LoaderEvent.HTTP_STATUS</code> events. Make sure your onHTTPStatus function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). You can determine the httpStatus code using the LoaderEvent's <code>target.httpStatus</code> (LoaderItems keep track of their <code>httpStatus</code> when possible, although certain environments prevent Flash from getting httpStatus information).**/
  110. public function onHTTPStatus(value:Function):CSSLoaderVars {
  111. return _set("onHTTPStatus", value);
  112. }
  113. /** A handler function for <code>LoaderEvent.IO_ERROR</code> events which will also call the onError handler, so you can use that as more of a catch-all whereas <code>onIOError</code> is specifically for LoaderEvent.IO_ERROR events. Make sure your onIOError function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). **/
  114. public function onIOError(value:Function):CSSLoaderVars {
  115. return _set("onIOError", value);
  116. }
  117. /** A handler function for <code>LoaderEvent.OPEN</code> events which are dispatched when the loader begins loading. Make sure your onOpen function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>).**/
  118. public function onOpen(value:Function):CSSLoaderVars {
  119. return _set("onOpen", value);
  120. }
  121. /** A handler function for <code>LoaderEvent.PROGRESS</code> events which are dispatched whenever the <code>bytesLoaded</code> changes. Make sure your onProgress function accepts a single parameter of type <code>LoaderEvent</code> (<code>com.greensock.events.LoaderEvent</code>). You can use the LoaderEvent's <code>target.progress</code> to get the loader's progress value or use its <code>target.bytesLoaded</code> and <code>target.bytesTotal</code>.**/
  122. public function onProgress(value:Function):CSSLoaderVars {
  123. return _set("onProgress", value);
  124. }
  125. /** LoaderMax supports <i>subloading</i>, where an object can be factored into a parent's loading progress. If you want LoaderMax to require this loader as part of its parent SWFLoader's progress, you must set the <code>requireWithRoot</code> property to your swf's <code>root</code>. For example, <code>vars.requireWithRoot = this.root;</code>. **/
  126. public function requireWithRoot(value:DisplayObject):CSSLoaderVars {
  127. return _set("requireWithRoot", value);
  128. }
  129. //---- LOADERITEM PROPERTIES -------------------------------------------------------------
  130. /** If you define an <code>alternateURL</code>, the loader will initially try to load from its original <code>url</code> and if it fails, it will automatically (and permanently) change the loader's <code>url</code> to the <code>alternateURL</code> and try again. Think of it as a fallback or backup <code>url</code>. It is perfectly acceptable to use the same <code>alternateURL</code> for multiple loaders (maybe a default image for various ImageLoaders for example). **/
  131. public function alternateURL(value:String):CSSLoaderVars {
  132. return _set("alternateURL", value);
  133. }
  134. /** Initially, the loader's <code>bytesTotal</code> is set to the <code>estimatedBytes</code> value (or <code>LoaderMax.defaultEstimatedBytes</code> if one isn't defined). Then, when the loader begins loading and it can accurately determine the bytesTotal, it will do so. Setting <code>estimatedBytes</code> is optional, but the more accurate the value, the more accurate your loaders' overall progress will be initially. If the loader is inserted into a LoaderMax instance (for queue management), its <code>auditSize</code> feature can attempt to automatically determine the <code>bytesTotal</code> at runtime (there is a slight performance penalty for this, however - see LoaderMax's documentation for details). **/
  135. public function estimatedBytes(value:uint):CSSLoaderVars {
  136. return _set("estimatedBytes", value);
  137. }
  138. /** If <code>true</code>, a "gsCacheBusterID" parameter will be appended to the url with a random set of numbers to prevent caching (don't worry, this info is ignored when you <code>LoaderMax.getLoader()</code> or <code>LoaderMax.getContent()</code> by <code>url</code> or when you're running locally). **/
  139. public function noCache(value:Boolean):CSSLoaderVars {
  140. return _set("noCache", value);
  141. }
  142. /** Normally, the URL will be parsed and any variables in the query string (like "?name=test&amp;state=il&amp;gender=m") will be placed into a URLVariables object which is added to the URLRequest. This avoids a few bugs in Flash, but if you need to keep the entire URL intact (no parsing into URLVariables), set <code>allowMalformedURL:true</code>. For example, if your URL has duplicate variables in the query string like <code>http://www.greensock.com/?c=S&amp;c=SE&amp;c=SW</code>, it is technically considered a malformed URL and a URLVariables object can't properly contain all the duplicates, so in this case you'd want to set <code>allowMalformedURL</code> to <code>true</code>. **/
  143. public function allowMalformedURL(value:Boolean):CSSLoaderVars {
  144. return _set("allowMalformedURL", value);
  145. }
  146. //---- GETTERS / SETTERS -----------------------------------------------------------------
  147. /** The generic Object populated by all of the method calls in the CSSLoaderVars instance. This is the raw data that gets passed to the loader. **/
  148. public function get vars():Object {
  149. return _vars;
  150. }
  151. /** @private **/
  152. public function get isGSVars():Boolean {
  153. return true;
  154. }
  155. }
  156. }