-
Notifications
You must be signed in to change notification settings - Fork 73
/
draggable.xml
228 lines (227 loc) · 12.6 KB
/
draggable.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
<?xml version="1.0"?>
<entry name="draggable" type="widget" widget-element="draggable element" event-prefix="drag">
<title>Draggable Widget</title>
<desc>Allow elements to be moved using the mouse.</desc>
<longdesc>
<p>Make the selected elements draggable by mouse. If you want not just drag, but drag & drop, see the <a href="/droppable/">jQuery UI Droppable plugin</a>, which provides a drop target for draggables.</p>
<h3>Dependencies</h3>
<ul>
<li><a href="/category/ui-core/">UI Core</a></li>
<li><a href="/jQuery.widget/">Widget Factory</a></li>
<li><a href="/mouse/">Mouse Interaction</a></li>
</ul>
</longdesc>
<added>1.0</added>
<options>
<option name="addClasses" type="Boolean" default="true" example-value="false">
<desc>If set to <code>false</code>, will prevent the <code>ui-draggable</code> class from being added. This may be desired as a performance optimization when calling <code>.draggable()</code> on hundreds of elements.</desc>
</option>
<option name="appendTo" default='"parent"' example-value='"body"'>
<desc>Which element the draggable helper should be appended to while dragging.</desc>
<type name="jQuery">
<desc>A jQuery object containing the element to append the helper to.</desc>
</type>
<type name="Element">
<desc>The element to append the helper to.</desc>
</type>
<type name="Selector">
<desc>A selector specifying which element to append the helper to.</desc>
</type>
<type name="String">
<desc>The string <code>"parent"</code> will cause the helper to be a sibling of the draggable.</desc>
</type>
</option>
<option name="axis" type="String" default="false" example-value='"x"'>
<desc>Constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: <code>"x"</code>, <code>"y"</code>.</desc>
</option>
<option name="cancel" type="Selector" default='"input,textarea,button,select,option"' example-value='".title"'>
<desc>Prevents dragging from starting on specified elements.</desc>
</option>
<option name="connectToSortable" type="Selector" default="false" example-value='"#my-sortable"'>
<desc>Allows the draggable to be dropped onto the specified sortables. If this option is used, a draggable can be dropped onto a sortable list and then becomes part of it. Note: The <a href="#option-helper"><code>helper</code></a> option must be set to <code>"clone"</code> in order to work flawlessly. Requires the <a href="/sortable/">jQuery UI Sortable plugin</a> to be included.</desc>
</option>
<option name="containment" default="false" example-value='"parent"'>
<desc>Constrains dragging to within the bounds of the specified element or region.</desc>
<type name="Selector">
<desc>The draggable element will be contained to the bounding box of the first element found by the selector. If no element is found, no containment will be set.</desc>
</type>
<type name="Element">
<desc>The draggable element will be contained to the bounding box of this element.</desc>
</type>
<type name="String">
<desc>Possible values: <code>"parent"</code>, <code>"document"</code>, <code>"window"</code>.</desc>
</type>
<type name="Array">
<desc>An array defining a bounding box in the form <code>[ x1, y1, x2, y2 ]</code>.</desc>
</type>
</option>
<option name="cursor" type="String" default='"auto"' example-value='"crosshair"'>
<desc>The CSS cursor during the drag operation.</desc>
</option>
<option name="cursorAt" type="Object" default="false" example-value="{ left: 5 }">
<desc>Sets the offset of the dragging helper relative to the mouse cursor. Coordinates can be given as a hash using a combination of one or two keys: <code>{ top, left, right, bottom }</code>.</desc>
</option>
<option name="delay" type="Number" default="0" example-value="300">
<desc>Time in milliseconds after mousedown until dragging should start. This option can be used to prevent unwanted drags when clicking on an element.</desc>
</option>
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<option name="distance" type="Number" default="1" example-value="10">
<desc>Distance in pixels after mousedown the mouse must move before dragging should start. This option can be used to prevent unwanted drags when clicking on an element.</desc>
</option>
<option name="grid" type="Array" default="false" example-value="[ 50, 20 ]">
<desc>Snaps the dragging helper to a grid, every x and y pixels. The array must be of the form <code>[ x, y ]</code>.</desc>
</option>
<option name="handle" default="false" example-value='"h2"'>
<desc>If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s). Only elements that descend from the draggable element are permitted.</desc>
<type name="Selector"/>
<type name="Element"/>
</option>
<option name="helper" default='"original"' example-value='"clone"'>
<desc>Allows for a helper element to be used for dragging display.</desc>
<type name="String">
<desc>If set to <code>"clone"</code>, then the element will be cloned and the clone will be dragged.</desc>
</type>
<type name="Function">
<desc>A function that will return a DOMElement to use while dragging.</desc>
</type>
</option>
<option name="iframeFix" default="false" example-value="true">
<desc>Prevent iframes from capturing the mousemove events during a drag. Useful in combination with the <a href="#option-cursorAt"><code>cursorAt</code></a> option, or in any case where the mouse cursor may not be over the helper.</desc>
<type name="Boolean">
<desc>When set to <code>true</code>, transparent overlays will be placed over all iframes on the page.</desc>
</type>
<type name="Selector">
<desc>Any iframes matching the selector will be covered by transparent overlays.</desc>
</type>
</option>
<option name="opacity" type="Number" default="false" example-value="0.35">
<desc>Opacity for the helper while being dragged.</desc>
</option>
<option name="refreshPositions" type="Boolean" default="false" example-value="true">
<desc>
If set to <code>true</code>, all droppable positions are calculated on every mousemove.
<em>Caution: This solves issues on highly dynamic pages, but dramatically decreases performance.</em>
</desc>
</option>
<option name="revert" default="false" example-value="true">
<desc>Whether the element should revert to its start position when dragging stops.</desc>
<type name="Boolean">
<desc>If set to <code>true</code> the element will always revert.</desc>
</type>
<type name="String">
<desc>If set to <code>"invalid"</code>, revert will only occur if the draggable has not been dropped on a droppable. For <code>"valid"</code>, it's the other way around.</desc>
</type>
<type name="Function">
<desc>A function to determine whether the element should revert to its start position. The function must return <code>true</code> to revert the element.</desc>
</type>
</option>
<option name="revertDuration" type="Number" default="500" example-value="200">
<desc>The duration of the revert animation, in milliseconds. Ignored if the <a href="#option-revert"><code>revert</code></a> option is <code>false</code>.</desc>
</option>
<option name="scope" type="String" default='"default"' example-value='"tasks"'>
<desc>Used to group sets of draggable and droppable items, in addition to droppable's <a href="/droppable#option-accept"><code>accept</code></a> option. A draggable with the same <code>scope</code> value as a droppable will be accepted by the droppable.</desc>
</option>
<option name="scroll" type="Boolean" default="true" example-value="false">
<desc>If set to <code>true</code>, container auto-scrolls while dragging.</desc>
</option>
<option name="scrollSensitivity" type="Number" default="20" example-value="100">
<desc>Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to pointer, not the draggable. Ignored if the <a href="#option-scroll"><code>scroll</code></a> option is <code>false</code>.</desc>
</option>
<option name="scrollSpeed" type="Number" default="20" example-value="100">
<desc>The speed at which the window should scroll once the mouse pointer gets within the <a href="#option-scrollSensitivity"><code>scrollSensitivity</code></a> distance. Ignored if the <a href="#option-scroll"><code>scroll</code></a> option is <code>false</code>.</desc>
</option>
<option name="snap" default="false" example-value="true">
<desc>Whether the element should snap to other elements.</desc>
<type name="Boolean">
<desc>When set to <code>true</code>, the element will snap to all other draggable elements.</desc>
</type>
<type name="Selector">
<desc>A selector specifying which elements to snap to.</desc>
</type>
</option>
<option name="snapMode" type="String" default='"both"' example-value='"inner"'>
<desc>Determines which edges of snap elements the draggable will snap to. Ignored if the <a href="#option-snap"><code>snap</code></a> option is <code>false</code>. Possible values: <code>"inner"</code>, <code>"outer"</code>, <code>"both"</code>.</desc>
</option>
<option name="snapTolerance" type="Number" default="20" example-value="30">
<desc>The distance in pixels from the snap element edges at which snapping should occur. Ignored if the <a href="#option-snap"><code>snap</code></a> option is <code>false</code>.</desc>
</option>
<option name="stack" type="Selector" default="false" example-value='".products"'>
<desc>Controls the z-index of the set of elements that match the selector, always brings the currently dragged item to the front. Very useful in things like window managers.</desc>
</option>
<option name="zIndex" type="Number" default="false" example-value="100">
<desc>Z-index for the helper while being dragged.</desc>
</option>
</options>
<events>
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<event name="start">
<desc>Triggered when dragging starts.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper that's being dragged.</desc>
</property>
<property name="position" type="Object">
<desc>Current CSS position of the helper as <code>{ top, left }</code> object.</desc>
</property>
<property name="offset" type="Object">
<desc>Current offset position of the helper as <code>{ top, left }</code> object.</desc>
</property>
</argument>
</event>
<event name="drag">
<desc>Triggered while the mouse is moved during the dragging.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper that's being dragged.</desc>
</property>
<property name="position" type="Object">
<desc>Current CSS position of the helper as <code>{ top, left }</code> object.</desc>
</property>
<property name="offset" type="Object">
<desc>Current offset position of the helper as <code>{ top, left }</code> object.</desc>
</property>
</argument>
</event>
<event name="stop">
<desc>Triggered when dragging stops.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper that's being dragged.</desc>
</property>
<property name="position" type="Object">
<desc>Current CSS position of the helper as <code>{ top, left }</code> object.</desc>
</property>
<property name="offset" type="Object">
<desc>Current offset position of the helper as <code>{ top, left }</code> object.</desc>
</property>
</argument>
</event>
</events>
<methods>
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<example>
<desc>A simple jQuery UI Draggable</desc>
<css><![CDATA[
#draggable {
width: 100px;
height: 100px;
background: #ccc;
}
]]></css>
<code><![CDATA[
$( "#draggable" ).draggable();
]]></code>
<html><![CDATA[
<div id="draggable">Drag me</div>
]]></html>
</example>
<category slug="interactions"/>
</entry>