Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

226 lines (224 sloc) 12.681 kb
<?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 &amp; 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).</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>
</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>
Jump to Line
Something went wrong with that request. Please try again.