yui/docs/EventProvider.js.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4         <title>API: event   EventProvider.js  (YUI Library)</title>
   5         <link rel="stylesheet" type="text/css" href="assets/api.css">
   6 </head>
   7
   8 <body id="yahoo-com">
   9 <div id="doc3" class="yui-t2">
  10
  11         <div id="hd">
  12         <h1>Yahoo! UI Library</h1>
  13         <h3>Event Utility&nbsp; <span class="subtitle">2.2.0</span></h3>
  14         <p>
  15         <a href="./index.html">Yahoo! UI Library</a>
  16             &gt; <a href="./module_event.html">event</a>
  17
  18                  &gt; EventProvider.js (source view)
  19             </p>
  20         </div>
  21
  22         <div id="bd">
  23                 <div id="yui-main">
  24                         <div class="yui-b">
  25
  26                     <div id="srcout">
  27 <div class="highlight" ><pre><span class="c">/**</span>
  28 <span class="c"> * EventProvider is designed to be used with YAHOO.augment to wrap </span>
  29 <span class="c"> * CustomEvents in an interface that allows events to be subscribed to </span>
  30 <span class="c"> * and fired by name.  This makes it possible for implementing code to</span>
  31 <span class="c"> * subscribe to an event that either has not been created yet, or will</span>
  32 <span class="c"> * not be created at all.</span>
  33 <span class="c"> *</span>
  34 <span class="c"> * @Class EventProvider</span>
  35 <span class="c"> */</span>
  36 <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">util</span><span class="o">.</span><span class="nx">EventProvider</span> <span class="o">=</span> <span class="k">function</span><span class="o">()</span> <span class="o">{</span> <span class="o">};</span>
  37
  38 <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">util</span><span class="o">.</span><span class="nx">EventProvider</span><span class="o">.</span><span class="nx">prototype</span> <span class="o">=</span> <span class="o">{</span>
  39
  40     <span class="c">/**</span>
  41 <span class="c">     * Private storage of custom events</span>
  42 <span class="c">     * @property __yui_events</span>
  43 <span class="c">     * @type Object[]</span>
  44 <span class="c">     * @private</span>
  45 <span class="c">     */</span>
  46     <span class="nx">__yui_events</span><span class="o">:</span> <span class="kc">null</span><span class="o">,</span>
  47
  48     <span class="c">/**</span>
  49 <span class="c">     * Private storage of custom event subscribers</span>
  50 <span class="c">     * @property __yui_subscribers</span>
  51 <span class="c">     * @type Object[]</span>
  52 <span class="c">     * @private</span>
  53 <span class="c">     */</span>
  54     <span class="nx">__yui_subscribers</span><span class="o">:</span> <span class="kc">null</span><span class="o">,</span>
  55
  56     <span class="c">/**</span>
  57 <span class="c">     * Subscribe to a CustomEvent by event type</span>
  58 <span class="c">     *</span>
  59 <span class="c">     * @method subscribe</span>
  60 <span class="c">     * @param p_type     {string}   the type, or name of the event</span>
  61 <span class="c">     * @param p_fn       {function} the function to exectute when the event fires</span>
  62 <span class="c">     * @param p_obj</span>
  63 <span class="c">     * @param p_obj      {Object}   An object to be passed along when the event </span>
  64 <span class="c">     *                              fires</span>
  65 <span class="c">     * @param p_override {boolean}  If true, the obj passed in becomes the </span>
  66 <span class="c">     *                              execution scope of the listener</span>
  67 <span class="c">     */</span>
  68     <span class="nx">subscribe</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">p_type</span><span class="o">,</span> <span class="nx">p_fn</span><span class="o">,</span> <span class="nx">p_obj</span><span class="o">,</span> <span class="nx">p_override</span><span class="o">)</span> <span class="o">{</span>
  69
  70         <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">||</span> <span class="o">{};</span>
  71         <span class="k">var</span> <span class="nx">ce</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">];</span>
  72
  73         <span class="k">if</span> <span class="o">(</span><span class="nx">ce</span><span class="o">)</span> <span class="o">{</span>
  74             <span class="nx">ce</span><span class="o">.</span><span class="nx">subscribe</span><span class="o">(</span><span class="nx">p_fn</span><span class="o">,</span> <span class="nx">p_obj</span><span class="o">,</span> <span class="nx">p_override</span><span class="o">);</span>
  75         <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
  76             <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span> <span class="o">||</span> <span class="o">{};</span>
  77             <span class="k">var</span> <span class="nx">subs</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span><span class="o">;</span>
  78             <span class="k">if</span> <span class="o">(!</span><span class="nx">subs</span><span class="o">[</span><span class="nx">p_type</span><span class="o">])</span> <span class="o">{</span>
  79                 <span class="nx">subs</span><span class="o">[</span><span class="nx">p_type</span><span class="o">]</span> <span class="o">=</span> <span class="o">[];</span>
  80             <span class="o">}</span>
  81             <span class="nx">subs</span><span class="o">[</span><span class="nx">p_type</span><span class="o">].</span><span class="nx">push</span><span class="o">(</span>
  82                 <span class="o">{</span> <span class="nx">fn</span><span class="o">:</span> <span class="nx">p_fn</span><span class="o">,</span> <span class="nx">obj</span><span class="o">:</span> <span class="nx">p_obj</span><span class="o">,</span> <span class="nx">override</span><span class="o">:</span> <span class="nx">p_override</span> <span class="o">}</span> <span class="o">);</span>
  83         <span class="o">}</span>
  84     <span class="o">},</span>
  85
  86     <span class="c">/**</span>
  87 <span class="c">     * Unsubscribes one or more listeners the from the specified event</span>
  88 <span class="c">     * @method unsubscribe</span>
  89 <span class="c">     * @param p_type {string}   The type, or name of the event</span>
  90 <span class="c">     * @param p_fn   {Function} The subscribed function to unsubscribe, if not</span>
  91 <span class="c">     *                          supplied, all subscribers will be removed.</span>
  92 <span class="c">     * @param p_obj  {Object}   The custom object passed to subscribe.  This is</span>
  93 <span class="c">     *                        optional, but if supplied will be used to</span>
  94 <span class="c">     *                        disambiguate multiple listeners that are the same</span>
  95 <span class="c">     *                        (e.g., you subscribe many object using a function</span>
  96 <span class="c">     *                        that lives on the prototype)</span>
  97 <span class="c">     * @return {boolean} true if the subscriber was found and detached.</span>
  98 <span class="c">     */</span>
  99     <span class="nx">unsubscribe</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">p_type</span><span class="o">,</span> <span class="nx">p_fn</span><span class="o">,</span> <span class="nx">p_obj</span><span class="o">)</span> <span class="o">{</span>
 100         <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">||</span> <span class="o">{};</span>
 101         <span class="k">var</span> <span class="nx">ce</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">];</span>
 102         <span class="k">if</span> <span class="o">(</span><span class="nx">ce</span><span class="o">)</span> <span class="o">{</span>
 103             <span class="k">return</span> <span class="nx">ce</span><span class="o">.</span><span class="nx">unsubscribe</span><span class="o">(</span><span class="nx">p_fn</span><span class="o">,</span> <span class="nx">p_obj</span><span class="o">);</span>
 104         <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
 105             <span class="k">return</span> <span class="kc">false</span><span class="o">;</span>
 106         <span class="o">}</span>
 107     <span class="o">},</span>
 108
 109     <span class="c">/**</span>
 110 <span class="c">     * Removes all listeners from the specified event</span>
 111 <span class="c">     * @method unsubscribeAll</span>
 112 <span class="c">     * @param p_type {string}   The type, or name of the event</span>
 113 <span class="c">     */</span>
 114     <span class="nx">unsubscribeAll</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">p_type</span><span class="o">)</span> <span class="o">{</span>
 115         <span class="k">return</span> <span class="k">this</span><span class="o">.</span><span class="nx">unsubscribe</span><span class="o">(</span><span class="nx">p_type</span><span class="o">);</span>
 116     <span class="o">},</span>
 117
 118     <span class="c">/**</span>
 119 <span class="c">     * Creates a new custom event of the specified type.  If a custom event</span>
 120 <span class="c">     * by that name already exists, it will not be re-created.  In either</span>
 121 <span class="c">     * case the custom event is returned. </span>
 122 <span class="c">     *</span>
 123 <span class="c">     * @method createEvent</span>
 124 <span class="c">     *</span>
 125 <span class="c">     * @param p_type {string} the type, or name of the event</span>
 126 <span class="c">     * @param p_config {object} optional config params.  Valid properties are:</span>
 127 <span class="c">     *</span>
 128 <span class="c">     *  &lt;ul&gt;</span>
 129 <span class="c">     *    &lt;li&gt;</span>
 130 <span class="c">     *      scope: defines the default execution scope.  If not defined</span>
 131 <span class="c">     *      the default scope will be this instance.</span>
 132 <span class="c">     *    &lt;/li&gt;</span>
 133 <span class="c">     *    &lt;li&gt;</span>
 134 <span class="c">     *      silent: if true, the custom event will not generate log messages.</span>
 135 <span class="c">     *      This is false by default.</span>
 136 <span class="c">     *    &lt;/li&gt;</span>
 137 <span class="c">     *    &lt;li&gt;</span>
 138 <span class="c">     *      onSubscribeCallback: specifies a callback to execute when the</span>
 139 <span class="c">     *      event has a new subscriber.  This will fire immediately for</span>
 140 <span class="c">     *      each queued subscriber if any exist prior to the creation of</span>
 141 <span class="c">     *      the event.</span>
 142 <span class="c">     *    &lt;/li&gt;</span>
 143 <span class="c">     *  &lt;/ul&gt;</span>
 144 <span class="c">     *</span>
 145 <span class="c">     *  @return {CustomEvent} the custom event</span>
 146 <span class="c">     *</span>
 147 <span class="c">     */</span>
 148     <span class="nx">createEvent</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">p_type</span><span class="o">,</span> <span class="nx">p_config</span><span class="o">)</span> <span class="o">{</span>
 149
 150         <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">||</span> <span class="o">{};</span>
 151         <span class="k">var</span> <span class="nx">opts</span> <span class="o">=</span> <span class="nx">p_config</span> <span class="o">||</span> <span class="o">{};</span>
 152         <span class="k">var</span> <span class="nx">events</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">;</span>
 153
 154         <span class="k">if</span> <span class="o">(</span><span class="nx">events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">])</span> <span class="o">{</span>
 155             <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">log</span><span class="o">(</span><span class="s2">&quot;EventProvider: error, event already exists&quot;</span><span class="o">);</span>
 156         <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
 157
 158             <span class="k">var</span> <span class="nx">scope</span>  <span class="o">=</span> <span class="nx">opts</span><span class="o">.</span><span class="nx">scope</span>  <span class="o">||</span> <span class="k">this</span><span class="o">;</span>
 159             <span class="k">var</span> <span class="nx">silent</span> <span class="o">=</span> <span class="nx">opts</span><span class="o">.</span><span class="nx">silent</span> <span class="o">||</span> <span class="kc">null</span><span class="o">;</span>
 160
 161             <span class="k">var</span> <span class="nx">ce</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">util</span><span class="o">.</span><span class="nx">CustomEvent</span><span class="o">(</span><span class="nx">p_type</span><span class="o">,</span> <span class="nx">scope</span><span class="o">,</span> <span class="nx">silent</span><span class="o">,</span>
 162                     <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">util</span><span class="o">.</span><span class="nx">CustomEvent</span><span class="o">.</span><span class="nx">FLAT</span><span class="o">);</span>
 163             <span class="nx">events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">]</span> <span class="o">=</span> <span class="nx">ce</span><span class="o">;</span>
 164
 165             <span class="k">if</span> <span class="o">(</span><span class="nx">opts</span><span class="o">.</span><span class="nx">onSubscribeCallback</span><span class="o">)</span> <span class="o">{</span>
 166                 <span class="nx">ce</span><span class="o">.</span><span class="nx">subscribeEvent</span><span class="o">.</span><span class="nx">subscribe</span><span class="o">(</span><span class="nx">opts</span><span class="o">.</span><span class="nx">onSubscribeCallback</span><span class="o">);</span>
 167             <span class="o">}</span>
 168
 169             <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span> <span class="o">||</span> <span class="o">{};</span>
 170             <span class="k">var</span> <span class="nx">qs</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_subscribers</span><span class="o">[</span><span class="nx">p_type</span><span class="o">];</span>
 171
 172             <span class="k">if</span> <span class="o">(</span><span class="nx">qs</span><span class="o">)</span> <span class="o">{</span>
 173                 <span class="k">for</span> <span class="o">(</span><span class="k">var</span> <span class="nx">i</span><span class="o">=</span><span class="m">0</span><span class="o">;</span> <span class="nx">i</span><span class="o">&lt;</span><span class="nx">qs</span><span class="o">.</span><span class="nx">length</span><span class="o">;</span> <span class="o">++</span><span class="nx">i</span><span class="o">)</span> <span class="o">{</span>
 174                     <span class="nx">ce</span><span class="o">.</span><span class="nx">subscribe</span><span class="o">(</span><span class="nx">qs</span><span class="o">[</span><span class="nx">i</span><span class="o">].</span><span class="nx">fn</span><span class="o">,</span> <span class="nx">qs</span><span class="o">[</span><span class="nx">i</span><span class="o">].</span><span class="nx">obj</span><span class="o">,</span> <span class="nx">qs</span><span class="o">[</span><span class="nx">i</span><span class="o">].</span><span class="nx">override</span><span class="o">);</span>
 175                 <span class="o">}</span>
 176             <span class="o">}</span>
 177         <span class="o">}</span>
 178
 179         <span class="k">return</span> <span class="nx">events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">];</span>
 180     <span class="o">},</span>
 181
 182
 183    <span class="c">/**</span>
 184 <span class="c">     * Fire a custom event by name.  The callback functions will be executed</span>
 185 <span class="c">     * from the scope specified when the event was created, and with the </span>
 186 <span class="c">     * following parameters:</span>
 187 <span class="c">     *   &lt;ul&gt;</span>
 188 <span class="c">     *   &lt;li&gt;The first argument fire() was executed with&lt;/li&gt;</span>
 189 <span class="c">     *   &lt;li&gt;The custom object (if any) that was passed into the subscribe() </span>
 190 <span class="c">     *       method&lt;/li&gt;</span>
 191 <span class="c">     *   &lt;/ul&gt;</span>
 192 <span class="c">     * @method fireEvent</span>
 193 <span class="c">     * @param p_type    {string}  the type, or name of the event</span>
 194 <span class="c">     * @param arguments {Object*} an arbitrary set of parameters to pass to </span>
 195 <span class="c">     *                            the handler.</span>
 196 <span class="c">     * @return {boolean} the return value from CustomEvent.fire, or null if </span>
 197 <span class="c">     *                   the custom event does not exist.</span>
 198 <span class="c">     */</span>
 199     <span class="nx">fireEvent</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">p_type</span><span class="o">,</span> <span class="nx">arg1</span><span class="o">,</span> <span class="nx">arg2</span><span class="o">,</span> <span class="nx">etc</span><span class="o">)</span> <span class="o">{</span>
 200
 201         <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span> <span class="o">||</span> <span class="o">{};</span>
 202         <span class="k">var</span> <span class="nx">ce</span> <span class="o">=</span> <span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">[</span><span class="nx">p_type</span><span class="o">];</span>
 203
 204         <span class="k">if</span> <span class="o">(</span><span class="nx">ce</span><span class="o">)</span> <span class="o">{</span>
 205             <span class="k">var</span> <span class="nx">args</span> <span class="o">=</span> <span class="o">[];</span>
 206             <span class="k">for</span> <span class="o">(</span><span class="k">var</span> <span class="nx">i</span><span class="o">=</span><span class="m">1</span><span class="o">;</span> <span class="nx">i</span><span class="o">&lt;</span><span class="nx">arguments</span><span class="o">.</span><span class="nx">length</span><span class="o">;</span> <span class="o">++</span><span class="nx">i</span><span class="o">)</span> <span class="o">{</span>
 207                 <span class="nx">args</span><span class="o">.</span><span class="nx">push</span><span class="o">(</span><span class="nx">arguments</span><span class="o">[</span><span class="nx">i</span><span class="o">]);</span>
 208             <span class="o">}</span>
 209             <span class="k">return</span> <span class="nx">ce</span><span class="o">.</span><span class="nx">fire</span><span class="o">.</span><span class="nx">apply</span><span class="o">(</span><span class="nx">ce</span><span class="o">,</span> <span class="nx">args</span><span class="o">);</span>
 210         <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
 211             <span class="nx">YAHOO</span><span class="o">.</span><span class="nx">log</span><span class="o">(</span><span class="s2">&quot;EventProvider.fire could not find event: &quot;</span> <span class="o">+</span> <span class="nx">p_type</span><span class="o">);</span>
 212             <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
 213         <span class="o">}</span>
 214     <span class="o">},</span>
 215
 216     <span class="c">/**</span>
 217 <span class="c">     * Returns true if the custom event of the provided type has been created</span>
 218 <span class="c">     * with createEvent.</span>
 219 <span class="c">     * @method hasEvent</span>
 220 <span class="c">     * @param type {string} the type, or name of the event</span>
 221 <span class="c">     */</span>
 222     <span class="nx">hasEvent</span><span class="o">:</span> <span class="k">function</span><span class="o">(</span><span class="nx">type</span><span class="o">)</span> <span class="o">{</span>
 223         <span class="k">if</span> <span class="o">(</span><span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">)</span> <span class="o">{</span>
 224             <span class="k">if</span> <span class="o">(</span><span class="k">this</span><span class="o">.</span><span class="nx">__yui_events</span><span class="o">[</span><span class="nx">type</span><span class="o">])</span> <span class="o">{</span>
 225                 <span class="k">return</span> <span class="kc">true</span><span class="o">;</span>
 226             <span class="o">}</span>
 227         <span class="o">}</span>
 228         <span class="k">return</span> <span class="kc">false</span><span class="o">;</span>
 229     <span class="o">}</span>
 230
 231 <span class="o">};</span>
 232 </pre></div>
 233                     </div>
 234                         </div>
 235                 </div>
 236                 <div class="yui-b">
 237             <div class="nav">
 238
 239                     <div class="module">
 240                         <h4>Modules</h4>
 241                         <ul class="content">
 242
 243                                 <li class=""><a href="module_animation.html">animation</a></li>
 244
 245                                 <li class=""><a href="module_autocomplete.html">autocomplete</a></li>
 246
 247                                 <li class=""><a href="module_button.html">button</a></li>
 248
 249                                 <li class=""><a href="module_calendar.html">calendar</a></li>
 250
 251                                 <li class=""><a href="module_connection.html">connection</a></li>
 252
 253                                 <li class=""><a href="module_container.html">container</a></li>
 254
 255                                 <li class=""><a href="module_datasource.html">datasource</a></li>
 256
 257                                 <li class=""><a href="module_datatable.html">datatable</a></li>
 258
 259                                 <li class=""><a href="module_dom.html">dom</a></li>
 260
 261                                 <li class=""><a href="module_dragdrop.html">dragdrop</a></li>
 262
 263                                 <li class=""><a href="module_element.html">element</a></li>
 264
 265                                 <li class="selected"><a href="module_event.html">event</a></li>
 266
 267                                 <li class=""><a href="module_history.html">history</a></li>
 268
 269                                 <li class=""><a href="module_logger.html">logger</a></li>
 270
 271                                 <li class=""><a href="module_menu.html">menu</a></li>
 272
 273                                 <li class=""><a href="module_slider.html">slider</a></li>
 274
 275                                 <li class=""><a href="module_tabview.html">tabview</a></li>
 276
 277                                 <li class=""><a href="module_treeview.html">treeview</a></li>
 278
 279                                 <li class=""><a href="module_yahoo.html">yahoo</a></li>
 280                         </ul>
 281                     </div>
 282
 283                     <div class="module">
 284                         <h4>Classes</h4>
 285                         <ul class="content">
 286                                 <li class=""><a href="YAHOO.util.CustomEvent.html">YAHOO.util.CustomEvent</a></li>
 287                                 <li class=""><a href="YAHOO.util.Event.html">YAHOO.util.Event</a></li>
 288                                 <li class=""><a href="YAHOO.util.EventProvider.html">YAHOO.util.EventProvider</a></li>
 289                                 <li class=""><a href="YAHOO.util.Subscriber.html">YAHOO.util.Subscriber</a></li>
 290                         </ul>
 291                     </div>
 292
 293                     <div class="module">
 294                         <h4>Files</h4>
 295                         <ul class="content">
 296                                 <li class=""><a href="CustomEvent.js.html">CustomEvent.js</a></li>
 297                                 <li class=""><a href="Event.js.html">Event.js</a></li>
 298                                 <li class="selected"><a href="EventProvider.js.html">EventProvider.js</a></li>
 299                         </ul>
 300                     </div>
 301
 302
 303
 304
 305
 306             </div>
 307                 </div>
 308         </div>
 309         <div id="ft">
 310         <hr />
 311         Copyright &copy; 2007 Yahoo! Inc. All rights reserved.
 312         </div>
 313 </div>
 314 </body>
 315 </html>