Import

zk.Widget Represents the object returned by the zk function, or by jq.zk. For example, zk('#id');

Refer to JQZK.jq for more information.

Other Extension

  • JQZK.jq - the object returned by `jq(...)`. The original jQuery API.
  • JQZK.jq - DOM utilities (such as, jq.innerX
  • jq.Event - the event object passed to the event listener

Hierarchy (view full)

Constructors

Properties

jq: JQuery<HTMLElement>

The associated instance of JQZK.jq, the object returned by jq(...).

eventTypes: Record<string, undefined | string> = ...
src0: string = ''

Methods

  • A short cut for looking up ZK Widget from jQuery object. Now the code zk.Widget.$(jq("@listbox")) could be replaced with zk("@listbox").$()

    Type Parameters

    Parameters

    • Optional opts: Partial<{
          child: boolean;
          exact: boolean;
          strict: boolean;
      }>

    Returns T

  • Makes the position of the first selected element as absolute. In addition to changing the style's position to absolute, it will store the location such that it can be restored later when relativize is called.

    zk('abc').absolutize()
    

    Returns this

  • Fixes DOM elements when a widget's unbind_ is called and it will hide the DOM element (display="none" or visibility="hidden").

    For firefox, it has to reset the src attribute of iframe (Bug 3076384)

    Returns unknown

  • Returns number

    the summation of the border height of the first matched element.

  • Returns number

    the summation of the border width of the first matched element.

  • Returns number

    the index of the first selected (table) cell in the cells collection of a (table) row.

    Note: The function fixed the problem of IE that cell.cellIndex returns a wrong index if there is a hidden cell in the table.

    See

    ncols

  • jq(el).zk.center('left top');
    jq(el).zk.center('left center');
    jq(el).zk.center('left'); //not to change the Y coordinate
    jq(el).zk.center(); //same as 'center'

    Positions the first selected element at the particular location of the browser window.

    jq(el).zk.center('left top');
    jq(el).zk.center('left center');
    jq(el).zk.center('left'); //not to change the Y coordinate
    jq(el).zk.center(); //same as 'center'

    Parameters

    • Optional flags: string

      A combination of center, left, right, top and bottom. If omitted, center is assumed.

    Returns this

  • Cleans, i.e., reset, the visibility (of the CSS style) for the matched elements. Depending on the browser, the reset visibility is either visible or inherit.

    Returns JQuery<HTMLElement>

  • Clears the CSS styles (excluding the inherited styles).

    Returns this

    Since

    5.0.2

  • Returns number

    the actual client height rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the client height. The value will not be rounded.

    Since

    9.5.1

  • Returns number

    the actual client width rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the client width. The value will not be rounded.

    Since

    9.5.1

  • Returns Offset

    the cumulative offset of the first matched element from the top left corner of the document.

    It actually adds the cumulative offsetLeft and offsetTop of an element and all its parents.

    Note that it ignores the scroll offset. If you want the element's coordinate, use revisedOffset instead.

    Note that all values are returned as numbers only although they are expressed in pixels.

  • Parameters

    • Optional excludeMargin: boolean

      whether to subtract the margins, too.

    Returns number

    the content height of the element, which substracted the height of its CSS border or padding, unlike revisedHeight, the contentHeight will ignore the box-sizing with border-box.

    Since

    7.0.0

  • Parameters

    • Optional excludeMargin: boolean

      whether to subtract the margins, too.

    Returns number

    the content width of the element, which substracted the width of its CSS border or padding, unlike revisedWidth, the contentWidth will ignore the box-sizing with border-box.

    Since

    7.0.0

  • Initializes the animation with the default effect, such as firing the onSize watch.

    Example:
    `zk(n).defaultAnimaOpts(wgt, opts, prop, true).jq.css(css).show().animate(...);`

    Parameters

    • wgt: Widget<HTMLElement>

      the widget

    • opts: SlideOptions

      the options. Ignored if not specified. It depends on the effect being taken

    • prop: string[]

      an array of properties, such ['top', 'left', 'position'].

    • Optional visible: boolean

      whether the result of the animation will make the DOM element visible

    Returns this

    Since

    5.0.6

  • Detaches all child elements and return them as an array.

    Returns undefined | HTMLElement[]

    an array of DOMElement that are detached, or null if no element is selected.

    Since

    5.0.10

  • Parameters

    • Optional revised: boolean

      if revised is true, revisedOffset will be used (i.e., the offset is calibrated).

    Returns Dimension

    the dimension of the specified element.

    If revised not specified (i.e., not to calibrate), the left and top are the offsetLeft and offsetTop of the element.

  • Disallows the user to select a portion of its content. You usually invoke this method to disable the selection for button-like widgets. By default, all elements can be selected (unless disabled with CSS -- which not all browsers support).

    If you disable the selection in Widget#bind_, you shall enable it back in Widget#unbind_ since this method will register a DOM-level listener for certain browsers.

    Returns this

  • Allows the user to select a portion of its content. You usually invoke this method to undo disableSelection. By default, all elements can be selected (unless disabled with CSS -- which not all browsers support).

    Returns this

  • Sets the focus to the first matched element. It is the same as jq(n).focus() and n.focus, except

    • it doesn't throw any exception (rather, returns false).
    • it can set the focus later (by use of timeout).
    • it maintains zk#currentFocus.

    In general, it is suggested to use zk(n).focus(), unless n does not belong to any widget.

    Parameters

    • Optional timeout: number

      the number of milliseconds to delay before setting the focus. If omitted or negative, the focus is set immediately.

    Returns boolean

    whether the focus is allowed to set to the element. Currently, only SELECT, BUTTON, INPUT and IFRAME is allowed.

    See

    select

  • Get the value of animation speed assigned through client attribute "data-animationspeed"

    Parameters

    • Optional defaultValue: number | "slow" | "fast"

      default value if widget doesn't have this attribute.

      Allowed values:

      `Integer`
      It can be any integer value
      `String`
      This value can be "slow" or "fast", which is the same as jQuery Animation

    Returns number | "slow" | "fast"

    an Integer or String.

    Since

    7.0.3

  • Returns Offset

    the selection range of the specified input-type element. The selection range is returned as a two-element array, where the first item is the starting index, and the second item is the ending index (excluding).

    If an exception occurs, [0, 0] is returned.

  • Returns boolean

    whether the first matched DOM element has the horizontal scrollbar

    Since

    5.0.8

  • Check if element has virtual parent

    Returns boolean

    Since

    7.0.3

  • Returns boolean

    whether the first matched DOM element has the vertical scrollbar

    Since

    5.0.8

  • Tests if all elements are input elements (including textarea).

    Returns boolean

    Since

    5.0.8

  • Tests if the first matched element is overlapped with the specified element.

    Parameters

    • el: HTMLElement

      the element to check with

    • Optional tolerant: number

      tolerant value for the calculation

    Returns boolean

    true if they are overlapped.

  • Checks whether the element is shown in the current viewport (consider both native and fake scrollbar).

    Parameters

    • Optional opt: boolean

    Returns boolean

    if false, it means the element is not shown.

    Since

    7.0.6

  • Parameters

    • Optional strict: boolean

      whether the visibility property must not be hidden, too. If false, only the style.display property is tested. If true, both the style.display and style.visibility properties are tested.

    Returns boolean

    whether the first match element is really visible. By real visible we mean the element and all its ancestors are visible.

  • Checks whether the element is shown in the current viewport.

    Parameters

    • Optional recursive: boolean

    Returns boolean

    if false, it means the element is not shown.

    Since

    6.5.2

  • Parameters

    • Optional strict: boolean

      whether the visibility property must not be hidden, too. If false, only the style.display property is tested. If true, both the style.display and style.visibility properties are tested.

    Returns boolean

    whether the first matched element is visible. false if not exist; true if no style attribute.

  • Creates a virtual parent for the specified element. Creating a virtual parent makes the specified element able to appear above any other element (such as a menu popup). By default, the Z order of an element is decided by its parent and ancestors (if any of them has the relative or absolute position). If you want to resolve this limitation, you can create a virtual parent for it with this method.

    To undo the creation of the virtual parent, use undoVParent.

    Notice that, due to browser's limitation, creating a virtual parent is still not enough to make an element appear on top of all others in all conditions. For example, it cannot in IE6 if there is a SELECT element underneath. To really solve this, you have to create a so-called stackup, which is actually an IFRAME element. By position the iframe right under the element, you can really want it appear on top. Refer to jq.newStackup for more information.

    What Really Happens

    This method actually moves the element to the topmost level in the DOM tree (i.e., as the child of document.body), and then the original parent (the parent before calling this method) becomes the virtual parent, which can be retrieved by vparentNode.

    When to Use

    When you implement a widget that appears above others, such as an overlapped window, a menu popup and a dropdown list, you can invoke this method when Widget#bind_ is called. And then, restore it by calling undoVParent when Widget#unbind_ is called.

    Returns this

  • Returns number

    the summation of the margin height of the first matched element.

    Since

    7.0.0

  • Returns number

    the summation of the margin width of the first matched element.

    Since

    7.0.0

  • Parameters

    • Optional visibleOnly: boolean

      whether not count invisible cells

    Returns number

    the number of columns of a row. Notice that it, unlike row.cells.length, calculate colSpan, too. In addition, it can filter out invisible cells.

  • Returns number

    the offset height. It is similar to el.offsetHeight, except it solves some browser's bug or limitation.

  • Returns number

    the actual offset height rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the offset height. The value will not be rounded.

    Since

    8.5.1

  • Returns number

    the offset left. It is similar to el.offsetLeft, except it solves some browser's bug or limitation.

  • Returns number

    the actual offset left rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the offset left. The value will not be rounded.

    Since

    8.5.1

  • Returns number

    the offset top. It is similar to el.offsetTop, except it solves some browser's bug or limitation.

  • Returns number

    the actual offset top rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the offset top. The value will not be rounded.

    Since

    8.5.1

  • Returns number

    the offset width. It is similar to el.offsetWidth, except it solves some browser's bug or limitation.

  • Returns number

    the actual offset width rounded "up" to the closest integer.

    Since

    9.6.3

  • Returns number

    the offset width. The value will not be rounded.

    Since

    8.5.1

  • Returns number

    the summation of the padding height and the border height of the first matched element.

  • Returns number

    the summation of the padding width and the border width of the first matched element.

  • Returns number

    the summation of the padding height of the first matched element.

  • Returns number

    the summation of the padding width of the first matched element.

  • Position the first matched element to the specified location.

    Parameters

    • Optional dim: Dimension

      the dimension of the anchor location

    • Optional where: string

      where to position. Default: overlap
      Allowed values:

      • before_start
        the element appears above the anchor, aligned to the left.
      • before_center
        the element appears above the anchor, aligned to the center.
      • before_end
        the element appears above the anchor, aligned to the right.
      • after_start
        the element appears below the anchor, aligned to the left.
      • after_center
        the element appears below the anchor, aligned to the center.
      • after_end
        the element appears below the anchor, aligned to the right.
      • start_before
        the element appears to the left of the anchor, aligned to the top.
      • start_center
        the element appears to the left of the anchor, aligned to the middle.
      • start_after
        the element appears to the left of the anchor, aligned to the bottom.
      • end_before
        the element appears to the right of the anchor, aligned to the top.
      • end_center
        the element appears to the right of the anchor, aligned to the middle.
      • end_after
        the element appears to the right of the anchor, aligned to the bottom.
      • overlap/top_left
        the element overlaps the anchor, with anchor and element aligned at top-left.
      • top_center
        the element overlaps the anchor, with anchor and element aligned at top-center.
      • overlap_end/top_right
        the element overlaps the anchor, with anchor and element aligned at top-right.
      • middle_left
        the element overlaps the anchor, with anchor and element aligned at middle-left.
      • middle_center
        the element overlaps the anchor, with anchor and element aligned at middle-center.
      • middle_right
        the element overlaps the anchor, with anchor and element aligned at middle-right.
      • overlap_before/bottom_left
        the element overlaps the anchor, with anchor and element aligned at bottom-left.
      • bottom_center
        the element overlaps the anchor, with anchor and element aligned at bottom-center.
      • overlap_after/bottom_right
        the element overlaps the anchor, with anchor and element aligned at bottom-right.
      • at_pointer
        the element appears with the upper-left aligned with the mouse cursor.
      • after_pointer
        the element appears with the top aligned with the bottom of the mouse cursor, with the left side of the element at the horizontal position of the mouse cursor.
    • Optional opts: PositionOptions

      a map of addition options. Allowed values include

      1. overflow
        whether to allow the element being scrolled out of the visible area (Default: false, i.e., not allowed). If not specified (or false), the popup always remains visible even if the user scrolls the anchor widget out of the visible area

    Returns this

    See

    center

  • Position the first matched element to the specified location.

    Parameters

    • Optional dim: Element

      the element used to get the dimension of the achor location. (by use of dimension)

    • Optional where: string

      where to position. Default: overlap
      Allowed values: refer to position.

    • Optional opts: PositionOptions

      a map of addition options.
      Allowed values: refer to position.

    Returns this

    See

    center

  • Forces the browser to redo (re-apply) CSS of all matched elements.

    Notice that calling this method might introduce some performance penality.

    Parameters

    • Optional timeout: number

      number of milliseconds to wait before really re-applying CSS. 100 is assumed if not specified , -1 means re-applying css right now.

    • Optional opts: Partial<RedoCSSOptions>

    Returns this

  • Forces the browser to re-load the resource specified in the src attribute for all matched elements.

    Returns this

  • Makes the position of the element as relative. In addition to changing the style's position to relative, it tries to restore the location before calling absolutize.

    Returns this

  • Parameters

    • size: number

      the height to be assigned to the first matched element.

    • Optional excludeMargin: boolean

      whether to subtract the margins, too. You rarely need this unless the height is specified in term of the parent's perspective.

    Returns number

    the revised (calibrated) height, which subtracted the height of its CSS border or padding, for the first matched element if the box-sizing is not in the border-box mode.

    It is usually used to assign the height to an element (since we have to subtract the padding). ```ts el.style.height = zk(parentEL).revisedHeight(100); ```

  • Converts the specified offset in the element's coordinate to to the browser window's coordinateReturns the revised (calibrated) offset, i.e., the offset of the element related to the screen.

    It is calculated by subtracting the offset of the scrollbar (scrollOffset and jq.innerX), for the first matched element.

    Parameters

    • Optional ofs: Offset

      the offset to revise. If not specified, the first matched element's bounding rectange is assumed.

    Returns Offset

    the revised (i.e., browser's coordinate) offset of the selected element. In other words, it is the offset of the left-top corner related to the browser window.

  • Parameters

    • size: number

      the width to be assigned to the specified element.

    • Optional excludeMargin: boolean

      whether to subtract the margins, too. You rarely need this unless the width is specified in term of the parent's perspective.

    Returns number

    the revised (calibrated) width, which subtracted the width of its CSS border or padding, for the first matched element if the box-sizing is not in the border-box mode.

    It is usually used to assign the width to an element (since we have to subtract the padding). ```ts el.style.width = zk(parentEL).revisedWidth(100); ```

  • Causes the first matched element to scroll into view.

    Parameters

    • Optional parent: Element

      scrolls the first matched element into the parent's view, if any. Otherwise, document.body is assumed.

    Returns this

  • Calculates the cumulative scroll offset of the first matched element in nested scrolling containers. It adds the cumulative scrollLeft and scrollTop of an element and all its parents.

    It is used for calculating the scroll offset of an element that is in more than one scroll container (e.g., a draggable in a scrolling container which is itself part of a scrolling document).

    Note that all values are returned as numbers only although they are expressed in pixels.

    Returns Offset

    the cumulative scroll offset.

  • Scrolls the browser window to make the first matched element visible.

    Notice that it scrolls only the browser window. If the element is obscured by another element, it is still not visible. To really make it visible, use el.scrollIntoView() instead.

    Returns this

  • Selects the first matched element. It is the same as DOMElement.select, except it won't throws an exception (rather, returns false), and can delay the execution for the specified number of milliseconds.

    Parameters

    • Optional timeout: number

      the number of milliseconds to delay before setting the focus. If omitted or negative, the focus is set immediately.

    Returns boolean

    whether the element supports the select method. In other words, it returns false if the object doesn't have the select method.

  • Sets the selection range of the specified input-type element.

    Parameters

    • start: number

      the starting index of the selection range

    • Optional end: number

      the ending index of the selection rane (excluding). In other words, the text between start and (end-1) is selected.

    Returns this

  • Sets the CSS style with a map of style names and values. For example,

    jq(el).css({width:'100px', paddingTop: "1px", "border-left": "2px"});
    jq(el).css(jq.parseStyle(jq.filterTextStle('width:100px;font-size:10pt')));

    To parse a style (e.g., 'width:10px;padding:2px') to a map of style names and values, use jq.parseStyle.

    Parameters

    • styles: PlainObject<string | number | ((this, index, value) => undefined | string | number)>

    Returns this

    Deprecated

    As of release 5.0.2, use jq.css(map) instead

  • Slides down (show) of the matched DOM element(s).

    Parameters

    • wgt: Widget<HTMLElement>

      the widget that owns the DOM element

    • Optional opts: SlideOptions

      the options. Ignored if not specified. Allowed options:

      anchor
      The anchor position which can be `t`, `b`, `l`, and `r`. Default: `t`.
      easing
      The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".
      duration
      The duration of animation (unit: milliseconds). Default: 400
      afterAnima
      The function to invoke after the animation.

    Returns this

  • Slides in (show) of the matched DOM element(s).

    Parameters

    • wgt: Widget<HTMLElement>

      the widget that owns the DOM element

    • Optional opts: SlideOptions

      the options. Ignored if not specified. Allowed options:

      anchor
      The anchor position which can be `t`, `b`, `l`, and `r`. Default: `t`.
      easing
      The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".
      duration
      The duration of animation (unit: milliseconds). Default: 400
      afterAnima
      The function to invoke after the animation.

    Returns this

  • Slides out (hide) of the matched DOM element(s).

    Parameters

    • wgt: Widget<HTMLElement>

      the widget that owns the DOM element

    • Optional opts: SlideOptions

      the options. Ignored if not specified. Allowed options:

      anchor
      The anchor position which can be `t`, `b`, `l`, and `r`. Default: `t`.
      easing
      The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".
      duration
      The duration of animation (unit: milliseconds). Default: 400
      afterAnima
      The function to invoke after the animation.

    Returns this

  • Slides up (hide) of the matched DOM element(s).

    Parameters

    • wgt: Widget<HTMLElement>

      the widget that owns the DOM element

    • Optional opts: SlideOptions

      the options. Ignored if not specified. Allowed options:

      anchor
      The anchor position which can be `t`, `b`, `l`, and `r`. Default: `t`.
      easing
      The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".
      duration
      The duration of animation (unit: milliseconds). Default: 400
      afterAnima
      The function to invoke after the animation.

    Returns this

  • Submit the selected form.

    Returns this

    Since

    5.0.4

  • Parameters

    • areas: string

      the areas is abbreviation for left "l", right "r", top "t", and bottom "b". So you can specify to be "lr" or "tb" or more.

    • styles: Record<string, string>

      an array of styles, such as jq.paddings, jq.margins or jq.borders.

    Returns number

    the summation of the specified styles. For example,

    jq(el).zk.sumStyles("lr", jq.paddings);
    //sums the style values of jq.paddings['l'] and jq.paddings['r'].
  • Parameters

    • Optional text: string

      the content text

    Returns Offset

    the size of the text if it is placed inside the first matched element.

    Deprecated

    Use textWidth instead for better performance.

  • Parameters

    • Optional text: string

      the content text. The text of the first matched element if omitted

    Returns number

    the width of the text if it is placed inside the first matched element.

    Since

    9.0.1

    See

    Stack Overflow

  • Converts an offset (x,y) from absolute coordination to the element's style coordination, such that you can assign them to the style (el.style).

    Parameters

    • x: number

      the X coordinate

    • y: number

      the Y coordinate

    Returns Offset

    the offset

  • Undoes the creation of a virtual parent of the first matched element.

    Refer to makeVParent for more information.

    Returns this

  • Returns number

    the maximal allowed height of the first matched element. In other words, it is the client height of the parent minus all sibling's.

  • Parameters

    • Optional real: boolean

      whether to return DOM element's parentNode if no virtual parent. In other words, zk(n).vparentNode(true) is the same as zk(n).vparentNode()||n.parentNode.

    Returns undefined | HTMLElement

    the virtual parent of the first matched element.

    Refer to makeVParent for more information.

  • Parameters

    • el: Element

    Returns void

  • Parameters

    • el: Element | Widget<HTMLElement>

    Returns number