zk

Class Draggable

java.lang.Object

zk.Object

zk.Draggable

public class Draggable
extends Object

A draggable object used to make a DOM element draggable.

Field Summary

Fields

Modifier and Type	Field and Description
Object	control The control object for this draggable.
DOMElement	handle The DOM element that represents the handle that the user can drag the whole element (node.
DOMElement	node The DOM element that is draggable (the whole element).
Map	opts The options of this draggable.

Fields inherited from class zk.Object

$class, $oid

Method Summary

Modifier and Type	Method and Description
void	$init(Object control, DOMElement node, Map opts) Constructor.
void	currentDelta() [left, right] of this node.
void	destroy() Destroys this draggable object.
protected Offset	snap_(Offset ofs) Snaps the dragging position.

Methods inherited from class zk.Object

$init, $instanceof, $super, $super, $supers, $supers, afterInit, isAssignableFrom, isInstance, proxy

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

control

public Object control

The control object for this draggable.

handle

public DOMElement handle

The DOM element that represents the handle that the user can drag the whole element (node. It is either node or a child element of it.

node

public DOMElement node

The DOM element that is draggable (the whole element).

opts

public Map opts

The options of this draggable.

Allowed options

handle

DOMElement handle

A child DOM element that the user can drag the whole element. Specify one if not the whole element (the node argument) can be dragged. It becomes the value of handle if specified.

Default: null (i.e., node is used.

snap

Offset snap;
int snap;
Offset snap(Draggable dg, Offset pos);

Specifies how many pixels to snap the dragging. For example, if the snap is 10, then the dragging has no effect if the offset is only 4, and the dragging offset is considered as 10 if it was 5.

The first format specifies the snaps for the x and y coordinate, such as [5, 3]. The second format specifies the snap for both x and y coordinate. The third format is used to calculate the snap dynamically based on the current position.

Default: null

• dg - the draggable object
• pos - the position of the element being dragged

starteffect

void starteffect(Draggable dg);

Specifies the effect to execute when the dragging is started. It usually generates an animation effect.

Default: a default action. To disable it, pass zk.

endeffect

void endeffect(Draggable dg, Event evt);

Specifies the effect to execute when the dragging is finished. It usually generates an animation effect.

Default: a default action. To disable it, pass zk.

• evt - the DOM event. It is null if caused by scrolling. It is not null if caused by dragging.

reverteffect

void reverteffect(Draggable dg, int dx, int dy);

The function to do the revert effect. Notice that it is ignored if the revert option is false (or returns false).

Default: null.

• dx - the number of pixels that the element has been dragged in the X coordinate
• dy - the number of pixels that the element has been dragged in the Y coordinate

revert

boolean revert;

boolean revert(Draggable dg, Offset pointer, Event evt);

The revert option could be a boolean, or a function that returns a boolean value. The boolean value decides whether to revert the dragging after dragged. If true, the element is reverted to its original location.

Default: false

To have a custom revert effect, you can specify a function as the #reverteffect option. It is usually an animation effect; see zEffect;

• pointer - the offset of the mouse pointer
• evt - the DOM event. It is null if caused by scrolling. It is a mouse event if caused by dragging.

constraint

String constraint;

Offset constraint(Draggable dg, Offset pos, Event evt);

Specifies the constraint. The first format specifies either 'vertical' or 'horizontal' to indicate that it can be dragged only in the vertical or horizontal direction.

The second format specified a function that can modify the position dynamically. For example, you can limit the drag at the diagonal direction.

• pos - the position of the element being dragged. It is the position going to assign to node's left and top.
• evt - the mouse event.

Returns real position, or null if the pos argument is correct

ghosting

boolean ghosting;

DOMElement ghosting(dg, Offset pos, Event evt);

Specified whether to make a copy of the element and then drag the copy instead of the element itself.

If true is specified (the first format), node is cloned and the cloned element will be dragged.

If a function is specified (the second format), the function is called and it shall create and return a DOM element (so called a ghost or a copy)that will be used for dragging. Furthermore, after dragging, endghosting, if specified, will be called to clean up.

Default: null (the element, node, will be dragged directly.

• pos - the position of the new created element, i.e., the left-top corner.

Example:

 var html = '<div style="left:' + pos[0] + 'px;top:' + pos[1] +'px"';
 //...
 

Returns the ghost element. This element will become node, and the original node will be restored after the dragging is finished (also after function specified in endghosting is called).

endghosting

void endghosting(Draggable dg, DOMElement origin);

Called after the dragging is finished to clean up what have been done by the function specified in ghosting.

It is optional since Draggable will remove the DOM element created by the function specified in ghosting.

Notice that it is ignored if the ghosting option is not specified with a function.

Default: null

• origin - the original element (node) before the function specified in ghosting. Notice node is switched to the ghost element during dragging, and restored after endghosting was called.

overlay

boolean overlay;

Specifies whether to create a DIV to cover the whole browser window when dragging. The DIV is helpful if the browser window contains iframe and other objects that will 'eat' the mousemove effect (and cause the dragging stopped abruptly).

Default: false

stackup

boolean stackup;

Specifies whether to create a stackup (actually an iframe) that makes sure the element being dragging is on top of others.

Default: false

zIndex

int zIndex;

int zIndex(Draggable dg);

The z-index that will be assigned when dragging the element. If it is a function, it is assumed to be a function returning the z-index (or -1 if it prefer not to change z-index) Default: not assign any value to z-index

change

void change(Draggable dg, Offset pointer, Event evt);

Called after the dragging has changed the position of the element (node). It is called after the function specified in the snap and draw or constraint option. It is also called it has been scrolled.

• pointer - the offset of the mouse pointer
• evt - the DOM event. It is null if cauased by scrolling. It is a mouse event if caused by dragging.

draw

void draw(Draggable dg, Offset pos, Event evt);

Used to override the default change of the element's position. If not specified, the constraint option is, if any, called and then node's position (left and top) are changed. You can provide your own way to change the position.

Default: null

• pos - the position of the element being dragged. It is the position going to assign to node's left and top.
• evt - the mouse event

scroll

DOMElement scroll;
String scroll; //DOM Element's ID

Specify which DOM element to consider its scrollLeft and scrollTop. In other words, it is the element with scrollbar that affects the location of the draggable element (zk.Draggable#node).

Default: null

Notice that scroll could be DOM element, including window, or its ID.

scrollSensitivity

int scrollSensitivity;

The scroll sensitivity.

Default: 20

scrollSpeed

int scrollSpeed;

The scroll speed.

Default: 15

Method Detail

$init

public void $init(Object control,
                  DOMElement node,
                  Map opts)

Constructor.

Parameters:

control - the control object for this draggable. It can be anything, but it is usually a widget (Widget).

node - [optional] the DOM element that is made to be draggable. If omitted and control is a widget, Widget.$n(_global_.String) is assumed.

opts - [optional] options. Refer to opts for allowed options.

destroy

public void destroy()

Destroys this draggable object. This method must be called to clean up, if you don't want to associate the draggable feature to a DOM element.

currentDelta

public void currentDelta()

[left, right] of this node.

snap_

protected Offset snap_(Offset ofs)

Snaps the dragging position. It is the default snapping. For individual snapping, use the snap or constraint options of Draggable. Notice this method is always called no matter if the snap or constraint options are specified.

Default: return pos (i.e., not changing at all)

Parameters:

ofs - the offset of the dragging position

Returns:

Offset the offset after snapped