mochikit_v14/doc/rst/MochiKit/DragAndDrop.rst

   1 .. title:: MochiKit.DragAndDrop - drag and drop elements with MochiKit
   2
   3 Name
   4 ====
   5
   6 MochiKit.DragAndDrop - drag and drop elements with MochiKit
   7
   8 Synopsis
   9 ========
  10
  11 ::
  12
  13     // Create a draggable
  14     new Draggable('mydrag');
  15
  16     // Create a corresponding droppable
  17     new Droppable('mydrop', {
  18         accept: ['drag-class'],
  19         ondrop: function (element) {
  20             alert('"' + element.id + '" was dropped on me');
  21         }
  22     });
  23
  24 Description
  25 ===========
  26
  27 MochiKit.DragAndDrop enables you the power of dragging elements
  28 through your pages, for richer interfaces.
  29
  30 Dependencies
  31 ============
  32
  33 - :mochiref:`MochiKit.Base`
  34 - :mochiref:`MochiKit.Iter`
  35 - :mochiref:`MochiKit.DOM`
  36 - :mochiref:`MochiKit.Color`
  37 - :mochiref:`MochiKit.Visual`
  38 - :mochiref:`MochiKit.Signal`
  39
  40 Overview
  41 ========
  42
  43 The implementation was adapted from Scriptaculous_.
  44
  45 .. _Scriptaculous: http://script.aculo.us
  46
  47 API Reference
  48 =============
  49
  50 Constructors
  51 ------------
  52
  53 :mochidef:`Draggable(element[, options])`:
  54
  55     A object that can be drag with the mouse.
  56
  57     You have the following options, with corresponding default values:
  58
  59     ``handle (false)``:
  60         Option for giving the element where starting the drag. By
  61         default it's the element itself, but you can either put a
  62         class of a subelement or the id of another element as handle.
  63
  64     ``starteffect (MochiKit.Visual.Opacity)``:
  65         Function called once the drag has begun, taking the dragged
  66         element as argument. It's an effect by default but you can
  67         define any callback.
  68
  69     ``reverteffect (MochiKit.Visual.Move)``:
  70         Effect applied when drag is cancelled. You have to define the
  71         ``revert`` option to enable the call. By default it brings the
  72         element back to its initial position, so you should know what
  73         you want when you modify this. The function should return an
  74         effect that can be cancelled.
  75
  76     ``endeffect (MochiKit.Visual.Opacity)``:
  77         Pending part of starteffect. If you have modified your element
  78         during start, you'd usually want to revert it in the function.
  79
  80     ``zindex (1000)``:
  81         Zindex of the drag element. By default it brings it to front.
  82
  83     ``revert (false)``:
  84         Indicate if the reverteffect function should be called. If you
  85         define a function here, this function will be called before
  86         reverteffect, with the element as first argument.
  87
  88     ``snap (false)``:
  89         Define the behaviour of the drag element when moving. It can
  90         either be a function, a value or an array of two values. If
  91         it's a function, it should take the (x, y) position of the
  92         element as arguments, and return the position draw in the
  93         browser. If its a value, it's used as a modulo for each
  94         coordinates. If it's an array, each value is applied for the
  95         corresponding coordinate.
  96
  97     ``selectclass (null)``:
  98         If defined, name of CSS class applied during the drag.
  99
 100     ``ghosting (null)``:
 101         Make a ghost from the draggable: clone it at start, then
 102         remove the clone at end.
 103
 104     ``onchange  (MochiKit.Base.noop)``:
 105         Function called when updates are made on the draggable object.
 106
 107     ``scroll (false)``:
 108         Element to scroll around, if precised. For example, 'window'
 109         will allow the draggable to scroll in the page.
 110
 111     ``scrollSensitivity (20)``:
 112         Scroll sensitivity, used when scroll is used.
 113
 114     ``scrollSpeed (15)``:
 115         Scroll speed, used when scroll is used.
 116
 117     A draggable generates some signals during its lifetime: start, drag and
 118     end. They are available through the Draggables handler, and are called
 119     with a draggable as argument. You can register a callback for these events
 120     like this::
 121
 122         onStart = function (draggable) {
 123             // Do some stuff
 124         };
 125
 126         connect(Draggables, 'start', onStart);
 127
 128
 129     *Availability*:
 130         Available in MochiKit 1.4+
 131
 132
 133 :mochidef:`Droppable(element[, options])`:
 134
 135     A object where you can drop a draggable.
 136
 137     You have the following options, with corresponding default values:
 138
 139     ``greedy (true)``:
 140         Stop on this droppable when a draggable drops over it.
 141
 142     ``hoverclass (null)``:
 143         If defined, name of CSS class applied when a draggable is
 144         hover the droppable element (hover state).
 145
 146     ``hoverfunc (MochiKit.Base.noop)``:
 147         Function called on hover state.
 148
 149     ``accept (null)``:
 150         Array of CSS classes allowed to drop on this.
 151
 152     ``activeclass (null)``:
 153         If defined, name of CSS class applied if a possible draggable
 154         begins its start (active state).
 155
 156     ``onactive (MochiKit.Base.noop)``:
 157         Function called on active state.
 158
 159     ``containment ([])``:
 160         Specify a list of elements to check for active state: only the
 161         children of the specified elements can be dropped. Mainly
 162         useful for Sortable.
 163
 164     ``onhover (MochiKit.Base.noop)``:
 165         Specific hover function, mainly used for Sortable.
 166
 167     ``ondrop (MochiKit.Base.noop)``:
 168         Function called when a draggable is dropped. The function
 169         takes three arguments: the draggable element, the droppable
 170         element, and the event that raised the drop.
 171
 172     *Availability*:
 173         Available in MochiKit 1.4+
 174
 175
 176 Authors
 177 =======
 178
 179 - Thomas Herve <therve@gmail.com>
 180 - Bob Ippolito <bob@redivi.com>
 181 - Originally adapted from Script.aculo.us <http://script.aculo.us/>
 182
 183 Copyright
 184 =========
 185
 186 Copyright 2005 Bob Ippolito <bob@redivi.com>.  This program is
 187 dual-licensed free software; you can redistribute it and/or modify it
 188 under the terms of the `MIT License`_ or the `Academic Free License
 189 v2.1`_.
 190
 191 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
 192 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php
 193
 194 Portions adapted from `Scriptaculous`_ are available under the terms
 195 of the `MIT License`_.
 196
 197