[Summary view] [Print] [Text view]

   1  
   2  <ul class="UIAPIPlugin-toc">
   3  <li><a href="#overview">Overview</a></li>
   4  <li><a href="#options">Options</a></li>
   5  <li><a href="#events">Events</a></li>
   6  <li><a href="#methods">Methods</a></li>
   7  <li><a href="#theming">Theming</a></li>
   8  </ul>
   9  <div class="UIAPIPlugin">
  10    <h1>jQuery UI Selectable</h1>
  11    <div id="overview">
  12      <h2 class="top-header">Overview</h2>
  13      <div id="overview-main">
  14          <p>The jQuery UI Selectable plugin allows for elements to be selected by dragging a box (sometimes called a lasso) with the mouse over the elements. Also, elements can be selected by click or drag while holding the Ctrl/Meta key, allowing for multiple (non-contiguous) selections.</p>
  15      </div>
  16      <div id="overview-dependencies">
  17          <h3>Dependencies</h3>
  18          <ul>
  19  <li>UI Core</li>
  20  </ul>
  21      </div>
  22      <div id="overview-example">
  23          <h3>Example</h3>
  24          <div id="overview-example" class="example">
  25  <ul><li><a href="#demo"><span>Demo</span></a></li><li><a href="#source"><span>View Source</span></a></li></ul>
  26  <p><div id="demo" class="tabs-container" rel="">
  27  A simple jQuery UI Selectable.<br />
  28  </p>
  29  <pre>$(&quot;#selectable&quot;).selectable();
  30  </pre>
  31  <p></div><div id="source" class="tabs-container">
  32  </p>
  33  <pre>&lt;!DOCTYPE html&gt;
  34  &lt;html&gt;
  35  &lt;head&gt;
  36    &lt;link type=&quot;text/css&quot; href=&quot;http://jqueryui.com/latest/themes/base/ui.all.css&quot; rel=&quot;stylesheet&quot; /&gt;
  37    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/jquery-1.3.2.js&quot;&gt;&lt;/script&gt;
  38    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/ui.core.js&quot;&gt;&lt;/script&gt;
  39    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/ui.selectable.js&quot;&gt;&lt;/script&gt;
  40    &lt;script type="text/javascript"&gt;
  41    $(document).ready(function(){
  42      $(&quot;#selectable&quot;).selectable();
  43    });
  44    &lt;/script&gt;
  45  &lt;/head&gt;
  46  &lt;body style="font-size:62.5%;"&gt;
  47    
  48  &lt;div id=&quot;selectable&quot;&gt;&lt;/div&gt;
  49  
  50  &lt;/body&gt;
  51  &lt;/html&gt;
  52  </pre>
  53  <p></div>
  54  </p><p></div>
  55      </div>
  56    </div>
  57    <div id="options">
  58      <h2 class="top-header">Options</h2>
  59      <ul class="options-list">
  60        
  61  <li class="option" id="option-autoRefresh">
  62    <div class="option-header">
  63      <h3 class="option-name"><a href="#option-autoRefresh">autoRefresh</a></h3>
  64      <dl>
  65        <dt class="option-type-label">Type:</dt>
  66          <dd class="option-type">Boolean</dd>
  67        
  68        <dt class="option-default-label">Default:</dt>
  69          <dd class="option-default">true</dd>
  70        
  71      </dl>
  72    </div>
  73    <div class="option-description">
  74      <p>This determines whether to refresh (recalculate) the position and size of each selectee at the beginning of each select operation. If you have many many items, you may want to set this to false and call the refresh method manually.</p>
  75    </div>
  76    <div class="option-examples">
  77      <h4>Code examples</h4>
  78      <dl class="option-examples-list">
  79      
  80  <dt>
  81    Initialize a selectable with the <code>autoRefresh</code> option specified.
  82  </dt>
  83  <dd>
  84  <pre><code>$('.selector').selectable({ autoRefresh: false });</code></pre>
  85  </dd>
  86  
  87      
  88  <dt>
  89    Get or set the <code>autoRefresh</code> option, after init.
  90  </dt>
  91  <dd>
  92  <pre><code>//getter
  93  var autoRefresh = $('.selector').selectable('option', 'autoRefresh');
  94  //setter
  95  $('.selector').selectable('option', 'autoRefresh', false);</code></pre>
  96  </dd>
  97  
  98      </dl>
  99    </div>
 100  </li>
 101  
 102  
 103  <li class="option" id="option-cancel">
 104    <div class="option-header">
 105      <h3 class="option-name"><a href="#option-cancel">cancel</a></h3>
 106      <dl>
 107        <dt class="option-type-label">Type:</dt>
 108          <dd class="option-type">Selector</dd>
 109        
 110        <dt class="option-default-label">Default:</dt>
 111          <dd class="option-default">':input,option'</dd>
 112        
 113      </dl>
 114    </div>
 115    <div class="option-description">
 116      <p>Prevents selecting if you start on elements matching the selector.</p>
 117    </div>
 118    <div class="option-examples">
 119      <h4>Code examples</h4>
 120      <dl class="option-examples-list">
 121      
 122  <dt>
 123    Initialize a selectable with the <code>cancel</code> option specified.
 124  </dt>
 125  <dd>
 126  <pre><code>$('.selector').selectable({ cancel: ':input,option' });</code></pre>
 127  </dd>
 128  
 129      
 130  <dt>
 131    Get or set the <code>cancel</code> option, after init.
 132  </dt>
 133  <dd>
 134  <pre><code>//getter
 135  var cancel = $('.selector').selectable('option', 'cancel');
 136  //setter
 137  $('.selector').selectable('option', 'cancel', ':input,option');</code></pre>
 138  </dd>
 139  
 140      </dl>
 141    </div>
 142  </li>
 143  
 144  
 145  <li class="option" id="option-delay">
 146    <div class="option-header">
 147      <h3 class="option-name"><a href="#option-delay">delay</a></h3>
 148      <dl>
 149        <dt class="option-type-label">Type:</dt>
 150          <dd class="option-type">Integer</dd>
 151        
 152        <dt class="option-default-label">Default:</dt>
 153          <dd class="option-default">0</dd>
 154        
 155      </dl>
 156    </div>
 157    <div class="option-description">
 158      <p>Time in milliseconds to define when the selecting should start. It helps preventing unwanted selections when clicking on an element.</p>
 159    </div>
 160    <div class="option-examples">
 161      <h4>Code examples</h4>
 162      <dl class="option-examples-list">
 163      
 164  <dt>
 165    Initialize a selectable with the <code>delay</code> option specified.
 166  </dt>
 167  <dd>
 168  <pre><code>$('.selector').selectable({ delay: 20 });</code></pre>
 169  </dd>
 170  
 171      
 172  <dt>
 173    Get or set the <code>delay</code> option, after init.
 174  </dt>
 175  <dd>
 176  <pre><code>//getter
 177  var delay = $('.selector').selectable('option', 'delay');
 178  //setter
 179  $('.selector').selectable('option', 'delay', 20);</code></pre>
 180  </dd>
 181  
 182      </dl>
 183    </div>
 184  </li>
 185  
 186  
 187  <li class="option" id="option-distance">
 188    <div class="option-header">
 189      <h3 class="option-name"><a href="#option-distance">distance</a></h3>
 190      <dl>
 191        <dt class="option-type-label">Type:</dt>
 192          <dd class="option-type">Integer</dd>
 193        
 194        <dt class="option-default-label">Default:</dt>
 195          <dd class="option-default">0</dd>
 196        
 197      </dl>
 198    </div>
 199    <div class="option-description">
 200      <p>Tolerance, in pixels, for when selecting should start. If specified, selecting will not start until after mouse is dragged beyond distance.</p>
 201    </div>
 202    <div class="option-examples">
 203      <h4>Code examples</h4>
 204      <dl class="option-examples-list">
 205      
 206  <dt>
 207    Initialize a selectable with the <code>distance</code> option specified.
 208  </dt>
 209  <dd>
 210  <pre><code>$('.selector').selectable({ distance: 20 });</code></pre>
 211  </dd>
 212  
 213      
 214  <dt>
 215    Get or set the <code>distance</code> option, after init.
 216  </dt>
 217  <dd>
 218  <pre><code>//getter
 219  var distance = $('.selector').selectable('option', 'distance');
 220  //setter
 221  $('.selector').selectable('option', 'distance', 20);</code></pre>
 222  </dd>
 223  
 224      </dl>
 225    </div>
 226  </li>
 227  
 228  
 229  <li class="option" id="option-filter">
 230    <div class="option-header">
 231      <h3 class="option-name"><a href="#option-filter">filter</a></h3>
 232      <dl>
 233        <dt class="option-type-label">Type:</dt>
 234          <dd class="option-type">Selector</dd>
 235        
 236        <dt class="option-default-label">Default:</dt>
 237          <dd class="option-default">'*'</dd>
 238        
 239      </dl>
 240    </div>
 241    <div class="option-description">
 242      <p>The matching child elements will be made selectees (able to be selected).</p>
 243    </div>
 244    <div class="option-examples">
 245      <h4>Code examples</h4>
 246      <dl class="option-examples-list">
 247      
 248  <dt>
 249    Initialize a selectable with the <code>filter</code> option specified.
 250  </dt>
 251  <dd>
 252  <pre><code>$('.selector').selectable({ filter: 'li' });</code></pre>
 253  </dd>
 254  
 255      
 256  <dt>
 257    Get or set the <code>filter</code> option, after init.
 258  </dt>
 259  <dd>
 260  <pre><code>//getter
 261  var filter = $('.selector').selectable('option', 'filter');
 262  //setter
 263  $('.selector').selectable('option', 'filter', 'li');</code></pre>
 264  </dd>
 265  
 266      </dl>
 267    </div>
 268  </li>
 269  
 270  
 271  <li class="option" id="option-tolerance">
 272    <div class="option-header">
 273      <h3 class="option-name"><a href="#option-tolerance">tolerance</a></h3>
 274      <dl>
 275        <dt class="option-type-label">Type:</dt>
 276          <dd class="option-type">String</dd>
 277        
 278        <dt class="option-default-label">Default:</dt>
 279          <dd class="option-default">'touch'</dd>
 280        
 281      </dl>
 282    </div>
 283    <div class="option-description">
 284      <p>Possible values: 'touch', 'fit'.
 285  </p>
 286  <ul>
 287  <li><b>fit</b>: draggable overlaps the droppable entirely</li>
 288  <li><b>touch</b>: draggable overlaps the droppable any amount</li>
 289  </ul>
 290  <p></p>
 291    </div>
 292    <div class="option-examples">
 293      <h4>Code examples</h4>
 294      <dl class="option-examples-list">
 295      
 296  <dt>
 297    Initialize a selectable with the <code>tolerance</code> option specified.
 298  </dt>
 299  <dd>
 300  <pre><code>$('.selector').selectable({ tolerance: 'fit' });</code></pre>
 301  </dd>
 302  
 303      
 304  <dt>
 305    Get or set the <code>tolerance</code> option, after init.
 306  </dt>
 307  <dd>
 308  <pre><code>//getter
 309  var tolerance = $('.selector').selectable('option', 'tolerance');
 310  //setter
 311  $('.selector').selectable('option', 'tolerance', 'fit');</code></pre>
 312  </dd>
 313  
 314      </dl>
 315    </div>
 316  </li>
 317  
 318      </ul>
 319    </div>
 320    <div id="events">
 321      <h2 class="top-header">Events</h2>
 322      <ul class="events-list">
 323        
 324  <li class="event" id="event-selected">
 325    <div class="event-header">
 326      <h3 class="event-name"><a href="#event-selected">selected</a></h3>
 327      <dl>
 328        <dt class="event-type-label">Type:</dt>
 329          <dd class="event-type">selected</dd>
 330      </dl>
 331    </div>
 332    <div class="event-description">
 333      <p>This event is triggered at the end of the select operation, on each element added to the selection.</p>
 334    </div>
 335    <div class="event-examples">
 336      <h4>Code examples</h4>
 337      <dl class="event-examples-list">
 338      
 339  <dt>
 340    Supply a callback function to handle the <code>selected</code> event as an init option.
 341  </dt>
 342  <dd>
 343  <pre><code>$('.selector').selectable({
 344     selected: function(event, ui) { ... }
 345  });</code></pre>
 346  </dd>
 347  
 348      
 349  <dt>
 350    Bind to the <code>selected</code> event by type: <code>selected</code>.
 351  </dt>
 352  <dd>
 353  <pre><code>$('.selector').bind('selected', function(event, ui) {
 354    ...
 355  });</code></pre>
 356  </dd>
 357  
 358      </dl>
 359    </div>
 360  </li>
 361  
 362  
 363  <li class="event" id="event-selecting">
 364    <div class="event-header">
 365      <h3 class="event-name"><a href="#event-selecting">selecting</a></h3>
 366      <dl>
 367        <dt class="event-type-label">Type:</dt>
 368          <dd class="event-type">selecting</dd>
 369      </dl>
 370    </div>
 371    <div class="event-description">
 372      <p>This event is triggered during the select operation, on each element added to the selection.</p>
 373    </div>
 374    <div class="event-examples">
 375      <h4>Code examples</h4>
 376      <dl class="event-examples-list">
 377      
 378  <dt>
 379    Supply a callback function to handle the <code>selecting</code> event as an init option.
 380  </dt>
 381  <dd>
 382  <pre><code>$('.selector').selectable({
 383     selecting: function(event, ui) { ... }
 384  });</code></pre>
 385  </dd>
 386  
 387      
 388  <dt>
 389    Bind to the <code>selecting</code> event by type: <code>selecting</code>.
 390  </dt>
 391  <dd>
 392  <pre><code>$('.selector').bind('selecting', function(event, ui) {
 393    ...
 394  });</code></pre>
 395  </dd>
 396  
 397      </dl>
 398    </div>
 399  </li>
 400  
 401  
 402  <li class="event" id="event-start">
 403    <div class="event-header">
 404      <h3 class="event-name"><a href="#event-start">start</a></h3>
 405      <dl>
 406        <dt class="event-type-label">Type:</dt>
 407          <dd class="event-type">selectablestart</dd>
 408      </dl>
 409    </div>
 410    <div class="event-description">
 411      <p>This event is triggered at the beginning of the select operation.</p>
 412    </div>
 413    <div class="event-examples">
 414      <h4>Code examples</h4>
 415      <dl class="event-examples-list">
 416      
 417  <dt>
 418    Supply a callback function to handle the <code>start</code> event as an init option.
 419  </dt>
 420  <dd>
 421  <pre><code>$('.selector').selectable({
 422     start: function(event, ui) { ... }
 423  });</code></pre>
 424  </dd>
 425  
 426      
 427  <dt>
 428    Bind to the <code>start</code> event by type: <code>selectablestart</code>.
 429  </dt>
 430  <dd>
 431  <pre><code>$('.selector').bind('selectablestart', function(event, ui) {
 432    ...
 433  });</code></pre>
 434  </dd>
 435  
 436      </dl>
 437    </div>
 438  </li>
 439  
 440  
 441  <li class="event" id="event-stop">
 442    <div class="event-header">
 443      <h3 class="event-name"><a href="#event-stop">stop</a></h3>
 444      <dl>
 445        <dt class="event-type-label">Type:</dt>
 446          <dd class="event-type">selectablestop</dd>
 447      </dl>
 448    </div>
 449    <div class="event-description">
 450      <p>This event is triggered at the end of the select operation.</p>
 451    </div>
 452    <div class="event-examples">
 453      <h4>Code examples</h4>
 454      <dl class="event-examples-list">
 455      
 456  <dt>
 457    Supply a callback function to handle the <code>stop</code> event as an init option.
 458  </dt>
 459  <dd>
 460  <pre><code>$('.selector').selectable({
 461     stop: function(event, ui) { ... }
 462  });</code></pre>
 463  </dd>
 464  
 465      
 466  <dt>
 467    Bind to the <code>stop</code> event by type: <code>selectablestop</code>.
 468  </dt>
 469  <dd>
 470  <pre><code>$('.selector').bind('selectablestop', function(event, ui) {
 471    ...
 472  });</code></pre>
 473  </dd>
 474  
 475      </dl>
 476    </div>
 477  </li>
 478  
 479  
 480  <li class="event" id="event-unselected">
 481    <div class="event-header">
 482      <h3 class="event-name"><a href="#event-unselected">unselected</a></h3>
 483      <dl>
 484        <dt class="event-type-label">Type:</dt>
 485          <dd class="event-type">unselected</dd>
 486      </dl>
 487    </div>
 488    <div class="event-description">
 489      <p>This event is triggered at the end of the select operation, on each element removed from the selection.</p>
 490    </div>
 491    <div class="event-examples">
 492      <h4>Code examples</h4>
 493      <dl class="event-examples-list">
 494      
 495  <dt>
 496    Supply a callback function to handle the <code>unselected</code> event as an init option.
 497  </dt>
 498  <dd>
 499  <pre><code>$('.selector').selectable({
 500     unselected: function(event, ui) { ... }
 501  });</code></pre>
 502  </dd>
 503  
 504      
 505  <dt>
 506    Bind to the <code>unselected</code> event by type: <code>unselected</code>.
 507  </dt>
 508  <dd>
 509  <pre><code>$('.selector').bind('unselected', function(event, ui) {
 510    ...
 511  });</code></pre>
 512  </dd>
 513  
 514      </dl>
 515    </div>
 516  </li>
 517  
 518  
 519  <li class="event" id="event-unselecting">
 520    <div class="event-header">
 521      <h3 class="event-name"><a href="#event-unselecting">unselecting</a></h3>
 522      <dl>
 523        <dt class="event-type-label">Type:</dt>
 524          <dd class="event-type">unselecting</dd>
 525      </dl>
 526    </div>
 527    <div class="event-description">
 528      <p>This event is triggered during the select operation, on each element removed from the selection.</p>
 529    </div>
 530    <div class="event-examples">
 531      <h4>Code examples</h4>
 532      <dl class="event-examples-list">
 533      
 534  <dt>
 535    Supply a callback function to handle the <code>unselecting</code> event as an init option.
 536  </dt>
 537  <dd>
 538  <pre><code>$('.selector').selectable({
 539     unselecting: function(event, ui) { ... }
 540  });</code></pre>
 541  </dd>
 542  
 543      
 544  <dt>
 545    Bind to the <code>unselecting</code> event by type: <code>unselecting</code>.
 546  </dt>
 547  <dd>
 548  <pre><code>$('.selector').bind('unselecting', function(event, ui) {
 549    ...
 550  });</code></pre>
 551  </dd>
 552  
 553      </dl>
 554    </div>
 555  </li>
 556  
 557      </ul>
 558    </div>
 559    <div id="methods">
 560      <h2 class="top-header">Methods</h2>
 561      <ul class="methods-list">
 562        
 563  <li class="method" id="method-destroy">
 564    <div class="method-header">
 565      <h3 class="method-name"><a href="#method-destroy">destroy</a></h3>
 566      <dl>
 567        <dt class="method-signature-label">Signature:</dt>
 568          <dd class="method-signature">.selectable( 'destroy'
 569  
 570  
 571  
 572  
 573  
 574  
 575  
 576  )</dd>
 577      </dl>
 578    </div>
 579    <div class="method-description">
 580      <p>Remove the selectable functionality completely. This will return the element back to its pre-init state.</p>
 581    </div>
 582  </li>
 583  
 584  
 585  <li class="method" id="method-disable">
 586    <div class="method-header">
 587      <h3 class="method-name"><a href="#method-disable">disable</a></h3>
 588      <dl>
 589        <dt class="method-signature-label">Signature:</dt>
 590          <dd class="method-signature">.selectable( 'disable'
 591  
 592  
 593  
 594  
 595  
 596  
 597  
 598  )</dd>
 599      </dl>
 600    </div>
 601    <div class="method-description">
 602      <p>Disable the selectable.</p>
 603    </div>
 604  </li>
 605  
 606  
 607  <li class="method" id="method-enable">
 608    <div class="method-header">
 609      <h3 class="method-name"><a href="#method-enable">enable</a></h3>
 610      <dl>
 611        <dt class="method-signature-label">Signature:</dt>
 612          <dd class="method-signature">.selectable( 'enable'
 613  
 614  
 615  
 616  
 617  
 618  
 619  
 620  )</dd>
 621      </dl>
 622    </div>
 623    <div class="method-description">
 624      <p>Enable the selectable.</p>
 625    </div>
 626  </li>
 627  
 628  
 629  <li class="method" id="method-option">
 630    <div class="method-header">
 631      <h3 class="method-name"><a href="#method-option">option</a></h3>
 632      <dl>
 633        <dt class="method-signature-label">Signature:</dt>
 634          <dd class="method-signature">.selectable( 'option'
 635  
 636  , optionName
 637  
 638  , <span class="optional">[</span>value<span class="optional">] </span>
 639  
 640  
 641  
 642  )</dd>
 643      </dl>
 644    </div>
 645    <div class="method-description">
 646      <p>Get or set any selectable option. If no value is specified, will act as a getter.</p>
 647    </div>
 648  </li>
 649  
 650  
 651  <li class="method" id="method-refresh">
 652    <div class="method-header">
 653      <h3 class="method-name"><a href="#method-refresh">refresh</a></h3>
 654      <dl>
 655        <dt class="method-signature-label">Signature:</dt>
 656          <dd class="method-signature">.selectable( 'refresh'
 657  
 658  
 659  
 660  
 661  
 662  
 663  
 664  )</dd>
 665      </dl>
 666    </div>
 667    <div class="method-description">
 668      <p>Refresh the position and size of each selectee element. This method can be used to manually recalculate the position and size of each selectee element. Very useful if autoRefresh is set to false.</p>
 669    </div>
 670  </li>
 671  
 672      </ul>
 673    </div>
 674    <div id="theming">
 675      <h2 class="top-header">Theming</h2>
 676      <p>The jQuery UI Selectable plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.
 677  </p>
 678    <p>If a deeper level of customization is needed, there are widget-specific classes referenced within the ui.selectable.css stylesheet that can be modified. These classes are highlighed in bold below.
 679  </p>
 680      
 681    <h3>Sample markup with jQuery UI CSS Framework classes</h3>
 682    &lt;ul class=&quot;<strong>ui-selectable</strong>&quot;&gt;<br />
 683  &#160;&#160;&#160;&lt;li class=&quot;<strong>ui-selectee</strong>&quot;&gt;&lt;/li&gt;<br />
 684  &#160;&#160;&#160;&lt;li class=&quot;<strong>ui-selectee</strong>&quot;&gt;&lt;/li&gt;<br />
 685  &#160;&#160;&#160;&lt;li class=&quot;<strong>ui-selectee</strong>&quot;&gt;&lt;/li&gt;<br />
 686  &lt;/ul&gt;
 687    <p class="theme-note">
 688      <strong>
 689        Note: This is a sample of markup generated by the selectable plugin, not markup you should use to create a selectable. The only markup needed for that is <br />&lt;ul&gt;<br />
 690  &#160;&#160;&#160;&lt;li&gt;&lt;/li&gt;<br />
 691  &#160;&#160;&#160;&lt;li&gt;&lt;/li&gt;<br />
 692  &#160;&#160;&#160;&lt;li&gt;&lt;/li&gt;<br />
 693  &lt;/ul&gt;.
 694      </strong>
 695    </p>
 696  
 697    </div>
 698  </div>
 699  
 700  </p><!-- 
 701  Pre-expand include size: 28549 bytes
 702  Post-expand include size: 45102 bytes
 703  Template argument size: 24967 bytes
 704  Maximum: 2097152 bytes
 705  -->
 706  
 707  <!-- Saved in parser cache with key jqdocs_docs:pcache:idhash:3343-1!1!0!!en!2 and timestamp 20090604112214 -->