Class Draggable

A draggable object used to make a DOM element draggable.

Hierarchy (view full)

Constructors

  • Parameters

    • control: undefined | ZKObject & {
          node?: HTMLElement;
      }

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

    • node: undefined | HTMLElement

      the DOM element that is made to be draggable. If omitted and control is a widget, zk.Widget.$n is assumed.

    • opts: DraggableOptions

      options. Refer to opts for allowed options.

    Returns Draggable

Properties

$oid: number = 0

The object ID. Each object has its own unique $oid. It is mainly used for debugging purpose.

Trick: you can test if a JavaScript object is a ZK object by examining this property, such as `if (o.$oid) alert('o is a ZK object');`

Notice: zk.Class extends from zk.Object (so a class also has $oid)

control?: ZKObject

The control object for this draggable.

dead?: boolean
delta: Offset
dragging: boolean
handle?: HTMLElement

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.

lastScrolled?: Date
node?: HTMLElement

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

offset: Offset
opts: DraggableOptions

The options of this draggable.

Allowed options

handle

```ts {@link 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 Value

null (i.e., node is used.

snap

```java {@link zk.Offset} snap; int snap; Offset snap({@link zk.Draggable} dg, {@link zk.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 Value

null

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

starteffect

```java void starteffect({@link zk.Draggable} dg); ```

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

Default Value

a default action. To disable it, pass zk.$void.

endeffect

```java void endeffect({@link zk.Draggable} dg, {@link zk.Event} evt); ```

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

Default Value

a default action. To disable it, pass zk.$void.

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

reverteffect

```java void reverteffect({@link zk.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 Value

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

```java boolean revert; boolean revert({@link zk.Draggable} dg, {@link zk.Offset} pointer, {@link zk.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 Value

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

```java String constraint; {@link zk.Offset} constraint({@link zk.Draggable} dg, {@link zk.Offset} pos, {@link zk.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

```java boolean ghosting; {@link DOMElement} ghosting({@link zk.Draggable dg}, {@link zk.Offset} pos, {@link zk.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 Value

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

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

Example: ```ts var html = '

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

```java void endghosting({@link zk.Draggable} dg, {@link 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 zk.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 Value

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

```java 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 Value

false

stackup

```java boolean stackup; ```

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

Default Value

false

zIndex

```java int zIndex; int zIndex({@link zk.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 Value

not assign any value to z-index

change

```java void change({@link zk.Draggable} dg, {@link zk.Offset} pointer, {@link zk.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

```java void draw({@link zk.Draggable} dg, {@link zk.Offset} pos, {@link zk.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 Value

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

```java {@link 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 Value

null

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

scrollSensitivity

```java int scrollSensitivity; ```

The scroll sensitivity.

Default Value

20

scrollSpeed

```java int scrollSpeed; ```

The scroll speed.

Default Value

15

orgScrlLeft?: number
orgScrlTop?: number
orgZ?: number
orgnode?: HTMLElement
scrollInterval?: number
scrollSpeed: Offset
stackup?: HTMLDivElement
z_box?: {
    height: number;
    left: number;
    minHeight: number;
    minWidth: number;
    top: number;
    width: number;
}

Type declaration

  • height: number
  • left: number
  • minHeight: number
  • minWidth: number
  • top: number
  • width: number
z_dir?: number
z_orgpos?: string
z_orgzi?: string
z_scrl?: Offset
z_szofs?: {
    height: string;
    left: string;
    top: string;
    width: string;
}

Type declaration

  • height: string
  • left: string
  • top: string
  • width: string
$oid: any

Accessors

  • get $class(): typeof ZKObject
  • The class that this object belongs to.

    Returns typeof ZKObject

Methods

  • The constructor.

    Parameters

    • Optional props: Record<string, unknown> | (() => void)

    Returns void

    Default Value

    it does nothing so the subclass needs not to copy back
    (also harmless to call back).

    See

    afterInit

    Deprecated

    as of 10.0 released. Using ES6 constructor instead.

  • Determines if this object is an instance of the class represented by the specified Class parameter. Example:

    if (obj.$instanceof(zul.wgt.Label, zul.wgt.Image)) {
    }

    Parameters

    • Rest ...klass: any[]

      the Class object to be checked. Any number of arguments can be specified.

    Returns boolean

    true if this object is an instance of the class

  • Invokes a method defined in the superclass with any number of arguments. It is like Function's call() that takes any number of arguments.

    Example: ```ts multiply: function (n) { return this.$super('multiply', n + 2); } ```

    Type Parameters

    • M extends "$init" | "$supers" | "_$ais" | "_$supers" | "_$proxies" | "_$super" | "_importantEvts" | "afterCreated_" | "afterInit" | "$class" | "get$Class" | "$oid" | "$instanceof" | "$super" | "proxy" | "opts" | "_isScrollChild" | "delta" | "dragging" | "_suicide" | "dead" | "lastScrolled" | "scrollSpeed" | "offset" | "scrollInterval" | "_innerOfs" | "stackup" | "_stackup" | "orgnode" | "z_scrl" | "z_orgpos" | "orgZ" | "orgScrlLeft" | "orgScrlTop" | "_clone" | "_lastDropTo" | "_lastDrop" | "_orgcursor" | "_zszofs" | "_zmin" | "_wndoffs" | "z_szofs" | "z_dir" | "z_orgzi" | "z_box" | "_point" | "_rootoffs" | "_lastSteps" | "_timer" | "_epos" | "_scale" | "_endStep" | "_steps" | "_isVer" | "_start" | "_end" | "_lastPos" | "_step" | "_diff" | "_ghost" | "control" | "handle" | "node" | "_dragImg" | "destroy" | "_currentDelta" | "_startDrag" | "_syncStackup" | "_updateDrag" | "_finishDrag" | "_mousedown" | "_keypress" | "_endDrag" | "_draw" | "_stopScrolling" | "_startScrolling" | "_scroll" | "_updateInnerOfs" | "_getWndScroll" | "snap_" | "_zoffs" | "_cns" | "_columns" | "_widths"

    • F extends any

    Parameters

    • mtd: M

      the method name to invoke

    • Rest ...args: Parameters<F>

      any number of arguments

    Returns ReturnType<F>

    the object being returned by the method of the superclass.

  • Invokes a method defined in the superclass with any number of arguments. It is like Function's call() that takes any number of arguments.

    It is similar to ZKObject.$super, but this method works even if the superclass calls back the same member method. In short, it is tedious but safer.

    Example: ```ts foo.MyClass = zk.$extends(foo.MySuper, { multiply: function (n) { return this.$super(foo.MyClass, 'multiply', n + 2); } ```

    Notice that the class specified in the first argument is not the super class having the method. Rather, it is the class that invokes this method.

    Type Parameters

    • M extends "$init" | "$supers" | "_$ais" | "_$supers" | "_$proxies" | "_$super" | "_importantEvts" | "afterCreated_" | "afterInit" | "$class" | "get$Class" | "$oid" | "$instanceof" | "$super" | "proxy" | "opts" | "_isScrollChild" | "delta" | "dragging" | "_suicide" | "dead" | "lastScrolled" | "scrollSpeed" | "offset" | "scrollInterval" | "_innerOfs" | "stackup" | "_stackup" | "orgnode" | "z_scrl" | "z_orgpos" | "orgZ" | "orgScrlLeft" | "orgScrlTop" | "_clone" | "_lastDropTo" | "_lastDrop" | "_orgcursor" | "_zszofs" | "_zmin" | "_wndoffs" | "z_szofs" | "z_dir" | "z_orgzi" | "z_box" | "_point" | "_rootoffs" | "_lastSteps" | "_timer" | "_epos" | "_scale" | "_endStep" | "_steps" | "_isVer" | "_start" | "_end" | "_lastPos" | "_step" | "_diff" | "_ghost" | "control" | "handle" | "node" | "_dragImg" | "destroy" | "_currentDelta" | "_startDrag" | "_syncStackup" | "_updateDrag" | "_finishDrag" | "_mousedown" | "_keypress" | "_endDrag" | "_draw" | "_stopScrolling" | "_startScrolling" | "_scroll" | "_updateInnerOfs" | "_getWndScroll" | "snap_" | "_zoffs" | "_cns" | "_columns" | "_widths"

    • F extends any

    Parameters

    • klass: typeof ZKObject

      the class that invokes this method.

    • mtd: M

      the method name to invoke

    • Rest ...args: Parameters<F>

      any number of arguments

    Returns ReturnType<F>

    the object being returned by the method of the superclass.

    See

    zk.Object.$supers

    Since

    5.0.2

  • Invokes a method defined in the superclass with an array of arguments. It is like Function's apply() that takes an array of arguments.

    Example: ```ts multiply: function () { return this.$supers('multiply', arguments); } ```

    Type Parameters

    • M extends "$init" | "$supers" | "_$ais" | "_$supers" | "_$proxies" | "_$super" | "_importantEvts" | "afterCreated_" | "afterInit" | "$class" | "get$Class" | "$oid" | "$instanceof" | "$super" | "proxy" | "opts" | "_isScrollChild" | "delta" | "dragging" | "_suicide" | "dead" | "lastScrolled" | "scrollSpeed" | "offset" | "scrollInterval" | "_innerOfs" | "stackup" | "_stackup" | "orgnode" | "z_scrl" | "z_orgpos" | "orgZ" | "orgScrlLeft" | "orgScrlTop" | "_clone" | "_lastDropTo" | "_lastDrop" | "_orgcursor" | "_zszofs" | "_zmin" | "_wndoffs" | "z_szofs" | "z_dir" | "z_orgzi" | "z_box" | "_point" | "_rootoffs" | "_lastSteps" | "_timer" | "_epos" | "_scale" | "_endStep" | "_steps" | "_isVer" | "_start" | "_end" | "_lastPos" | "_step" | "_diff" | "_ghost" | "control" | "handle" | "node" | "_dragImg" | "destroy" | "_currentDelta" | "_startDrag" | "_syncStackup" | "_updateDrag" | "_finishDrag" | "_mousedown" | "_keypress" | "_endDrag" | "_draw" | "_stopScrolling" | "_startScrolling" | "_scroll" | "_updateInnerOfs" | "_getWndScroll" | "snap_" | "_zoffs" | "_cns" | "_columns" | "_widths"

    • F extends any

    Parameters

    • name: M

      the method name to invoke

    • args: Parameters<F>

      an array of arguments. In most case, you just pass arguments (the built-in variable).

    Returns ReturnType<F>

    the object being returned by the method of the superclass.

  • Invokes a method defined in the superclass with an array of arguments. It is like Function's apply() that takes an array of arguments.

    It is similar to zk.Object.$supers, but this method works even if the superclass calls back the same member method. In short, it is tedious but safer.

    Example: ```ts foo.MyClass = zk.$extends(foo.MySuper, { multiply: function () { return this.$supers(foo.MyClass, 'multiply', arguments); } ```

    Notice that the class specified in the first argument is not the super class having the method. Rather, it is the class that invokes this method.

    Type Parameters

    • M extends "$init" | "$supers" | "_$ais" | "_$supers" | "_$proxies" | "_$super" | "_importantEvts" | "afterCreated_" | "afterInit" | "$class" | "get$Class" | "$oid" | "$instanceof" | "$super" | "proxy" | "opts" | "_isScrollChild" | "delta" | "dragging" | "_suicide" | "dead" | "lastScrolled" | "scrollSpeed" | "offset" | "scrollInterval" | "_innerOfs" | "stackup" | "_stackup" | "orgnode" | "z_scrl" | "z_orgpos" | "orgZ" | "orgScrlLeft" | "orgScrlTop" | "_clone" | "_lastDropTo" | "_lastDrop" | "_orgcursor" | "_zszofs" | "_zmin" | "_wndoffs" | "z_szofs" | "z_dir" | "z_orgzi" | "z_box" | "_point" | "_rootoffs" | "_lastSteps" | "_timer" | "_epos" | "_scale" | "_endStep" | "_steps" | "_isVer" | "_start" | "_end" | "_lastPos" | "_step" | "_diff" | "_ghost" | "control" | "handle" | "node" | "_dragImg" | "destroy" | "_currentDelta" | "_startDrag" | "_syncStackup" | "_updateDrag" | "_finishDrag" | "_mousedown" | "_keypress" | "_endDrag" | "_draw" | "_stopScrolling" | "_startScrolling" | "_scroll" | "_updateInnerOfs" | "_getWndScroll" | "snap_" | "_zoffs" | "_cns" | "_columns" | "_widths"

    • F extends any

    Parameters

    • klass: typeof ZKObject

      the class that invokes this method.

    • name: M

      the method name to invoke

    • args: Parameters<F>

      an array of arguments. In most case, you just pass arguments (the built-in variable).

    Returns ReturnType<F>

    the object being returned by the method of the superclass.

    See

    zk.Object.$super

    Since

    5.0.2

  • Specifies a function that shall be called after the object is initialized, i.e., after zk.Object.$init is called. This method can be called only during the execution of zk.Object.$init.

    It is an advance feature that is used to allow a base class to do something that needs to wait for all deriving classes have been initialized.

    Invocation Sequence:

    • The most derived class's $init (subclass)
    • The based class's $init (if the derived class's $init invokes this.$supers('$init', arguments))
    • The first function, if any, be added with afterInit, then the second (in the same order that afterInit was called)...

    Parameters

    • func: CallableFunction

      the function to register for execution later

    Returns void

    See

    zk.Object.$init

    Deprecated

    as of 10.0 released. Using afterCreated_ instead.

  • 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.

    Returns void

  • Type Parameters

    Returns T

    the class of the subsclass which extends from zk.Class.

    Since

    10.0.0

  • Proxies a member function such that it can be called with this object in a context that this object is not available. It sounds a bit strange at beginning but useful when passing a member of an object that will be executed as a global function.

    Example: Let us say if you want a member function to be called periodically, you can do as follows. ```ts setInterval(wgt.proxy(wgt.doIt), 1000); //assume doIt is a member function of wgt ```

    With proxy, when doIt is called, this references to wgt. On the other hand, the following won't work since this doesn't reference to wgt, when doIt is called. ```ts setInterval(wgt.doIt, 1000); //WRONG! doIt will not be called with wgt ```

    Notice that this method caches the result so that it will return the same proxied function, if you pass the same function again.

    Type Parameters

    • A extends unknown[]

    • R

    Parameters

    • func: ((...args) => R)

      a method member of this object

        • (...args): R
        • Parameters

          • Rest ...args: A

          Returns R

    Returns ((...args) => R)

    a function that can be called as a global function (that actually have this referencing to this object).

      • (...args): R
      • Parameters

        • Rest ...args: A

        Returns R

  • Type Parameters

    • A0

    • A extends unknown[]

    • R

    Parameters

    • func: ((arg0, ...args) => R)
        • (arg0, ...args): R
        • Parameters

          • arg0: A0
          • Rest ...args: A

          Returns R

    Returns ((arg0, ...args) => R)

      • (arg0, ...args): R
      • Parameters

        • arg0: A0
        • Rest ...args: A

        Returns R

  • Type Parameters

    • A0

    • A1

    • A extends unknown[]

    • R

    Parameters

    • func: ((arg0, arg1, ...args) => R)
        • (arg0, arg1, ...args): R
        • Parameters

          • arg0: A0
          • arg1: A1
          • Rest ...args: A

          Returns R

    Returns ((arg0, arg1, ...args) => R)

      • (arg0, arg1, ...args): R
      • Parameters

        • arg0: A0
        • arg1: A1
        • Rest ...args: A

        Returns R

  • Type Parameters

    • A0

    • A1

    • A2

    • A extends unknown[]

    • R

    Parameters

    • func: ((arg0, arg1, arg2, ...args) => R)
        • (arg0, arg1, arg2, ...args): R
        • Parameters

          • arg0: A0
          • arg1: A1
          • arg2: A2
          • Rest ...args: A

          Returns R

    Returns ((arg0, arg1, arg2, ...args) => R)

      • (arg0, arg1, arg2, ...args): R
      • Parameters

        • arg0: A0
        • arg1: A1
        • arg2: A2
        • Rest ...args: A

        Returns R

  • Type Parameters

    • A0

    • A1

    • A2

    • A3

    • A extends unknown[]

    • R

    Parameters

    • func: ((arg0, arg1, arg2, arg3, ...args) => R)
        • (arg0, arg1, arg2, arg3, ...args): R
        • Parameters

          • arg0: A0
          • arg1: A1
          • arg2: A2
          • arg3: A3
          • Rest ...args: A

          Returns R

    Returns ((arg0, arg1, arg2, arg3, ...args) => R)

      • (arg0, arg1, arg2, arg3, ...args): R
      • Parameters

        • arg0: A0
        • arg1: A1
        • arg2: A2
        • arg3: A3
        • Rest ...args: A

        Returns R

  • Returns boolean

  • Returns undefined | boolean | Event<unknown>

  • Parameters

    • target: HTMLElement

    Returns boolean

    Deprecated

    since 8.0.2 not to remove the function for backward compatibility (just in case)

  • Determines if the class by this Class object is either the same as, or is a superclass of, the class represented by the specified Class parameter. Example:

    if (klass1.isAssignableFrom(klass2)) {
    }

    Parameters

    • cls: typeof ZKObject

      the Class object to be checked, such as zk.Widget.

    Returns boolean

    true if assignable

  • Determines if the specified Object is assignment-compatible with this Class. This method is equivalent to [[zk.Object#$instanceof]. Example:

    if (klass.isInstance(obj)) {
    }

    Type Parameters

    Parameters

    • this: T
    • o: unknown

      the object to check

    Returns o is InstanceType<T>

    true if the object is an instance