yui/docs/YAHOO.util.EventProvider.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  YAHOO.util.EventProvider   (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                  &gt; YAHOO.util.EventProvider
  18
  19             </p>
  20         </div>
  21
  22         <div id="bd">
  23                 <div id="yui-main">
  24                         <div class="yui-b">
  25
  26
  27                     <h2>
  28
  29
  30
  31
  32                             Class <b>YAHOO.util.EventProvider</b>
  33                         <span class="extends">
  34                         </span>
  35
  36                         <span class="extends">
  37                         </span>
  38
  39                         </code>
  40                     </h2>
  41                     <!-- class tree goes here -->
  42
  43
  44
  45
  46                     <div class="summary description">
  47                         EventProvider is designed to be used with YAHOO.augment to wrap
  48 CustomEvents in an interface that allows events to be subscribed to
  49 and fired by name.  This makes it possible for implementing code to
  50 subscribe to an event that either has not been created yet, or will
  51 not be created at all.
  52                     </div>
  53
  54
  55                         <div class="section field details">
  56                             <h3><a name="field_detail">Properties</a></h3>
  57                             <div class="content">
  58                                     <h4><a name="__yui_events">__yui_events</a>
  59                                         <code>- private Object[]</code>
  60                                     </h4>
  61                                     <div class="detail">
  62                                         <div class="description">
  63                                             Private storage of custom events
  64                                         </div>
  65                                     </div>
  66
  67
  68
  69
  70                                     <hr />
  71                                     <h4><a name="__yui_subscribers">__yui_subscribers</a>
  72                                         <code>- private Object[]</code>
  73                                     </h4>
  74                                     <div class="detail">
  75                                         <div class="description">
  76                                             Private storage of custom event subscribers
  77                                         </div>
  78                                     </div>
  79
  80
  81
  82
  83                                     <hr />
  84
  85
  86                             </div>
  87                         </div>
  88
  89
  90                         <div class="section method details">
  91                             <h3><a name="methodDetails">Methods</a></h3>
  92                             <div class="content">
  93                                     <h4>
  94                                         <a name="createEvent">createEvent</a></h4>
  95                                     <div class="detail">
  96                                         <code>
  97
  98
  99
 100                                         CustomEvent
 101                                             <strong>createEvent</strong>
 102                                            (
 103
 104
 105                                                          p_type
 106
 107
 108                                                         ,
 109                                                          p_config
 110
 111
 112                                             )
 113                                         </code>
 114
 115                                         <div class="description">
 116                                             Creates a new custom event of the specified type.  If a custom event
 117 by that name already exists, it will not be re-created.  In either
 118 case the custom event is returned.
 119                                         </div>
 120
 121                                         <div class="description">
 122
 123                                                 <dl>
 124                                                     <dt>Parameters:</dt>
 125                                                         <dd>
 126                                                             <code>p_type &lt;string&gt;</code>
 127                                                               the type, or name of the event
 128                                                         </dd>
 129                                                         <dd>
 130                                                             <code>p_config &lt;object&gt;</code>
 131                                                               optional config params.  Valid properties are:
 132 <ul>
 133 <li>
 134 scope: defines the default execution scope.  If not defined
 135 the default scope will be this instance.
 136 </li>
 137 <li>
 138 silent: if true, the custom event will not generate log messages.
 139 This is false by default.
 140 </li>
 141 <li>
 142 onSubscribeCallback: specifies a callback to execute when the
 143 event has a new subscriber.  This will fire immediately for
 144 each queued subscriber if any exist prior to the creation of
 145 the event.
 146 </li>
 147 </ul>
 148                                                         </dd>
 149                                                 </dl>
 150
 151                                                 <dl>
 152                                                     <dt>Returns:
 153                                                     <code>
 154                                                         CustomEvent
 155                                                     </code></dt>
 156                                                     <dd>the custom event</dd>
 157                                                 </dl>
 158
 159                                         </div>
 160
 161                                     </div>
 162                                     <hr />
 163                                     <h4>
 164                                         <a name="fireEvent">fireEvent</a></h4>
 165                                     <div class="detail">
 166                                         <code>
 167
 168
 169
 170                                         boolean
 171                                             <strong>fireEvent</strong>
 172                                            (
 173
 174
 175                                                          p_type
 176
 177
 178                                                         ,
 179                                                          arguments
 180
 181
 182                                             )
 183                                         </code>
 184
 185                                         <div class="description">
 186                                             Fire a custom event by name.  The callback functions will be executed
 187 from the scope specified when the event was created, and with the
 188 following parameters:
 189 <ul>
 190 <li>The first argument fire() was executed with</li>
 191 <li>The custom object (if any) that was passed into the subscribe()
 192 method</li>
 193 </ul>
 194                                         </div>
 195
 196                                         <div class="description">
 197
 198                                                 <dl>
 199                                                     <dt>Parameters:</dt>
 200                                                         <dd>
 201                                                             <code>p_type &lt;string&gt;</code>
 202                                                                   the type, or name of the event
 203                                                         </dd>
 204                                                         <dd>
 205                                                             <code>arguments &lt;Object*&gt;</code>
 206                                                               an arbitrary set of parameters to pass to
 207 the handler.
 208                                                         </dd>
 209                                                 </dl>
 210
 211                                                 <dl>
 212                                                     <dt>Returns:
 213                                                     <code>
 214                                                         boolean
 215                                                     </code></dt>
 216                                                     <dd>the return value from CustomEvent.fire, or null if
 217 the custom event does not exist.</dd>
 218                                                 </dl>
 219
 220                                         </div>
 221
 222                                     </div>
 223                                     <hr />
 224                                     <h4>
 225                                         <a name="hasEvent">hasEvent</a></h4>
 226                                     <div class="detail">
 227                                         <code>
 228
 229
 230
 231                                         void
 232                                             <strong>hasEvent</strong>
 233                                            (
 234
 235
 236                                                          type
 237
 238
 239                                             )
 240                                         </code>
 241
 242                                         <div class="description">
 243                                             Returns true if the custom event of the provided type has been created
 244 with createEvent.
 245                                         </div>
 246
 247                                         <div class="description">
 248
 249                                                 <dl>
 250                                                     <dt>Parameters:</dt>
 251                                                         <dd>
 252                                                             <code>type &lt;string&gt;</code>
 253                                                               the type, or name of the event
 254                                                         </dd>
 255                                                 </dl>
 256
 257                                                 <dl>
 258                                                     <dt>Returns:
 259                                                     <code>
 260                                                         void
 261                                                     </code></dt>
 262                                                     <dd></dd>
 263                                                 </dl>
 264
 265                                         </div>
 266
 267                                     </div>
 268                                     <hr />
 269                                     <h4>
 270                                         <a name="subscribe">subscribe</a></h4>
 271                                     <div class="detail">
 272                                         <code>
 273
 274
 275
 276                                         void
 277                                             <strong>subscribe</strong>
 278                                            (
 279
 280
 281                                                          p_type
 282
 283
 284                                                         ,
 285                                                          p_fn
 286
 287
 288                                                         ,
 289                                                          p_obj
 290
 291
 292
 293
 294                                                         ,
 295                                                          p_override
 296
 297
 298                                             )
 299                                         </code>
 300
 301                                         <div class="description">
 302                                             Subscribe to a CustomEvent by event type
 303                                         </div>
 304
 305                                         <div class="description">
 306
 307                                                 <dl>
 308                                                     <dt>Parameters:</dt>
 309                                                         <dd>
 310                                                             <code>p_type &lt;string&gt;</code>
 311                                                                     the type, or name of the event
 312                                                         </dd>
 313                                                         <dd>
 314                                                             <code>p_fn &lt;function&gt;</code>
 315                                                                     the function to exectute when the event fires
 316                                                         </dd>
 317                                                         <dd>
 318                                                             <code>p_obj &lt;object&gt;</code>
 319
 320                                                         </dd>
 321                                                         <dd>
 322                                                             <code>p_obj &lt;Object&gt;</code>
 323                                                                      An object to be passed along when the event
 324 fires
 325                                                         </dd>
 326                                                         <dd>
 327                                                             <code>p_override &lt;boolean&gt;</code>
 328                                                                If true, the obj passed in becomes the
 329 execution scope of the listener
 330                                                         </dd>
 331                                                 </dl>
 332
 333                                                 <dl>
 334                                                     <dt>Returns:
 335                                                     <code>
 336                                                         void
 337                                                     </code></dt>
 338                                                     <dd></dd>
 339                                                 </dl>
 340
 341                                         </div>
 342
 343                                     </div>
 344                                     <hr />
 345                                     <h4>
 346                                         <a name="unsubscribe">unsubscribe</a></h4>
 347                                     <div class="detail">
 348                                         <code>
 349
 350
 351
 352                                         boolean
 353                                             <strong>unsubscribe</strong>
 354                                            (
 355
 356
 357                                                          p_type
 358
 359
 360                                                         ,
 361                                                          p_fn
 362
 363
 364                                                         ,
 365                                                          p_obj
 366
 367
 368                                             )
 369                                         </code>
 370
 371                                         <div class="description">
 372                                             Unsubscribes one or more listeners the from the specified event
 373                                         </div>
 374
 375                                         <div class="description">
 376
 377                                                 <dl>
 378                                                     <dt>Parameters:</dt>
 379                                                         <dd>
 380                                                             <code>p_type &lt;string&gt;</code>
 381                                                                 The type, or name of the event
 382                                                         </dd>
 383                                                         <dd>
 384                                                             <code>p_fn &lt;Function&gt;</code>
 385                                                                 The subscribed function to unsubscribe, if not
 386 supplied, all subscribers will be removed.
 387                                                         </dd>
 388                                                         <dd>
 389                                                             <code>p_obj &lt;Object&gt;</code>
 390                                                                  The custom object passed to subscribe.  This is
 391 optional, but if supplied will be used to
 392 disambiguate multiple listeners that are the same
 393 (e.g., you subscribe many object using a function
 394 that lives on the prototype)
 395                                                         </dd>
 396                                                 </dl>
 397
 398                                                 <dl>
 399                                                     <dt>Returns:
 400                                                     <code>
 401                                                         boolean
 402                                                     </code></dt>
 403                                                     <dd>true if the subscriber was found and detached.</dd>
 404                                                 </dl>
 405
 406                                         </div>
 407
 408                                     </div>
 409                                     <hr />
 410                                     <h4>
 411                                         <a name="unsubscribeAll">unsubscribeAll</a></h4>
 412                                     <div class="detail">
 413                                         <code>
 414
 415
 416
 417                                         void
 418                                             <strong>unsubscribeAll</strong>
 419                                            (
 420
 421
 422                                                          p_type
 423
 424
 425                                             )
 426                                         </code>
 427
 428                                         <div class="description">
 429                                             Removes all listeners from the specified event
 430                                         </div>
 431
 432                                         <div class="description">
 433
 434                                                 <dl>
 435                                                     <dt>Parameters:</dt>
 436                                                         <dd>
 437                                                             <code>p_type &lt;string&gt;</code>
 438                                                                 The type, or name of the event
 439                                                         </dd>
 440                                                 </dl>
 441
 442                                                 <dl>
 443                                                     <dt>Returns:
 444                                                     <code>
 445                                                         void
 446                                                     </code></dt>
 447                                                     <dd></dd>
 448                                                 </dl>
 449
 450                                         </div>
 451
 452                                     </div>
 453                                     <hr />
 454                             </div>
 455                         </div>
 456
 457
 458
 459
 460
 461
 462
 463                         </div>
 464                 </div>
 465                 <div class="yui-b">
 466             <div class="nav">
 467
 468                     <div class="module">
 469                         <h4>Modules</h4>
 470                         <ul class="content">
 471
 472                                 <li class=""><a href="module_animation.html">animation</a></li>
 473
 474                                 <li class=""><a href="module_autocomplete.html">autocomplete</a></li>
 475
 476                                 <li class=""><a href="module_button.html">button</a></li>
 477
 478                                 <li class=""><a href="module_calendar.html">calendar</a></li>
 479
 480                                 <li class=""><a href="module_connection.html">connection</a></li>
 481
 482                                 <li class=""><a href="module_container.html">container</a></li>
 483
 484                                 <li class=""><a href="module_datasource.html">datasource</a></li>
 485
 486                                 <li class=""><a href="module_datatable.html">datatable</a></li>
 487
 488                                 <li class=""><a href="module_dom.html">dom</a></li>
 489
 490                                 <li class=""><a href="module_dragdrop.html">dragdrop</a></li>
 491
 492                                 <li class=""><a href="module_element.html">element</a></li>
 493
 494                                 <li class="selected"><a href="module_event.html">event</a></li>
 495
 496                                 <li class=""><a href="module_history.html">history</a></li>
 497
 498                                 <li class=""><a href="module_logger.html">logger</a></li>
 499
 500                                 <li class=""><a href="module_menu.html">menu</a></li>
 501
 502                                 <li class=""><a href="module_slider.html">slider</a></li>
 503
 504                                 <li class=""><a href="module_tabview.html">tabview</a></li>
 505
 506                                 <li class=""><a href="module_treeview.html">treeview</a></li>
 507
 508                                 <li class=""><a href="module_yahoo.html">yahoo</a></li>
 509                         </ul>
 510                     </div>
 511
 512                     <div class="module">
 513                         <h4>Classes</h4>
 514                         <ul class="content">
 515                                 <li class=""><a href="YAHOO.util.CustomEvent.html">YAHOO.util.CustomEvent</a></li>
 516                                 <li class=""><a href="YAHOO.util.Event.html">YAHOO.util.Event</a></li>
 517                                 <li class="selected"><a href="YAHOO.util.EventProvider.html">YAHOO.util.EventProvider</a></li>
 518                                 <li class=""><a href="YAHOO.util.Subscriber.html">YAHOO.util.Subscriber</a></li>
 519                         </ul>
 520                     </div>
 521
 522                     <div class="module">
 523                         <h4>Files</h4>
 524                         <ul class="content">
 525                                 <li class=""><a href="CustomEvent.js.html">CustomEvent.js</a></li>
 526                                 <li class=""><a href="Event.js.html">Event.js</a></li>
 527                                 <li class=""><a href="EventProvider.js.html">EventProvider.js</a></li>
 528                         </ul>
 529                     </div>
 530
 531                     <div class="module">
 532                         <h4>Properties</h4>
 533                         <ul class="content">
 534                                 <li><a href="#__yui_events">__yui_events</a>
 535                                         <!--<code>&lt;Object[]&gt;</code>-->
 536                                 </li>
 537                                 <li><a href="#__yui_subscribers">__yui_subscribers</a>
 538                                         <!--<code>&lt;Object[]&gt;</code>-->
 539                                 </li>
 540                         </ul>
 541                     </div>
 542
 543                     <div class="module">
 544                         <h4>Methods</h4>
 545                         <ul class="content">
 546                                 <li><!--<code>CustomEvent</code>-->
 547                                 <a href="#createEvent">createEvent</a>
 548                                 </li>
 549                                 <li><!--<code>boolean</code>-->
 550                                 <a href="#fireEvent">fireEvent</a>
 551                                 </li>
 552                                 <li><!--<code>void</code>-->
 553                                 <a href="#hasEvent">hasEvent</a>
 554                                 </li>
 555                                 <li><!--<code>void</code>-->
 556                                 <a href="#subscribe">subscribe</a>
 557                                 </li>
 558                                 <li><!--<code>boolean</code>-->
 559                                 <a href="#unsubscribe">unsubscribe</a>
 560                                 </li>
 561                                 <li><!--<code>void</code>-->
 562                                 <a href="#unsubscribeAll">unsubscribeAll</a>
 563                                 </li>
 564                         </ul>
 565                     </div>
 566
 567
 568
 569             </div>
 570                 </div>
 571         </div>
 572         <div id="ft">
 573         <hr />
 574         Copyright &copy; 2007 Yahoo! Inc. All rights reserved.
 575         </div>
 576 </div>
 577 </body>
 578 </html>