# Class zUtl

#### Import

zk.Widget

#### Import

zk.xml.Utl The basic utilities.

For more utilities, refer to Utl.

#####
Index

### Constructors

constructor

### Properties

cellps0
i0
img0

### Methods

appendAttr
convertDataURLtoBlob
debounce
decodeXML
destroyProgressbox
encodeURL
encodeXML
encodeXMLAttribute
fireShown
fireSized
frames
getDevicePixelRatio
getUserMedia
getWeekOfYear
go
intsToString
isAncestor
isChar
isEqualObject
isImageLoading
loadImage
mapToString
parseMap
progressbox
stringToInts
throttle
today

## Constructors

### constructor

- new zUtl(): zUtl

- #### Returns zUtl

## Properties

### `Static` cellps0

cellps0: string = ' cellpadding="0" cellspacing="0" border="0"'

A shortcut of `' cellpadding="0" cellspacing="0" border="0"'`.

### `Static` i0

i0: string = '<i style="height:0;width:0"></i>'

A shortcut of `'<i style="height:0;width:0"/>'`.

### `Static` img0

img0: string = '<img style="height:0;width:0" aria-hidden="true"/>'

A shortcut of `'<img style="height:0;width:0"/>'`.

## Methods

### `Static` appendAttr

- appendAttr(nm, val): string

- Appends an attribute. Notice that the attribute won't be appended if val is empty or false. In other words, it is equivalent to
  `val ? ' ' + nm + '="' + val + '"': ""`.

  If you want to generate the attribute no matter what val is, use (appendAttr:ARGS_3).

  #### Parameters

  - ##### nm: string

    the name of the attribute

  - ##### val: unknown

    the value of the attribute

  #### Returns string

  #### Since

  5.0.3

- appendAttr(nm, val, force): string

- Appends an attribute. Notice that the attribute won't be appended.

  #### Parameters

  - ##### nm: string

    the name of the attribute

  - ##### val: unknown

    the value of the attribute

  - ##### force: boolean

    whether to append attribute no matter what value it is. If false (or omitted), it is the same as (appendAttr:ARGS_2).

  #### Returns string

  #### Since

  5.0.3

### `Static` convertDataURLtoBlob

- convertDataURLtoBlob(dataURL): Blob

- Converts the dataURL to Blob object. This function is not supported in IE9 and below.

  #### Parameters

  - ##### dataURL: string

  #### Returns Blob

### `Static` debounce

- debounce<T, A, R>(func, wait, immediate?): ((this, ...args) => R)

- Creates and returns a new debounced version of the passed function which will postpone its execution until after wait milliseconds have elapsed since the last time it was invoked. Useful for implementing behavior that should only happen after the input has stopped arriving.

  Copied from debounce, MIT license.

  #### Type Parameters

  - #### T

  - #### A extends unknown[]

  - #### R

  #### Parameters

  - ##### func: ((this, ...args) => R)

    the passed function

    - - (this, ...args): R

      - #### Parameters

        - ##### this: T

        - ##### `Rest` ...args: A

        #### Returns R

  - ##### wait: number

    wait milliseconds

  - ##### `Optional` immediate: boolean

    trigger the function on the leading instead of the trailing edge of the wait interval

  #### Returns ((this, ...args) => R)

  a new debounced version of the passed function

  - - (this, ...args): R

    - #### Parameters

      - ##### this: T

      - ##### `Rest` ...args: A

      #### Returns R

  #### Since

  9.6.0

### `Static` decodeXML

- decodeXML(txt): string

- Decodes the XML string into a normal string. For example, `&lt;` is convert to `<`

  #### Parameters

  - ##### txt: string

    the text to decode

  #### Returns string

  the decoded string

### `Static` destroyProgressbox

- destroyProgressbox(id, opts?): void

- Removes the message box created by progressbox.

  #### Parameters

  - ##### id: string

    the ID of the DOM element of the message box

  - ##### `Optional` opts: Partial<ProgressboxOptions>

  #### Returns void

### `Static` encodeURL

- encodeURL(url): string

- Encodes the string to a valid URL string.

  #### Parameters

  - ##### url: string

    the url to encode

  #### Returns string

  #### Since

  10.0.0

### `Static` encodeXML

- encodeXML(txt, opts?): string

- Encodes the string to a valid XML string. Refer to Utl for more XML utilities.

  #### Parameters

  - ##### txt: null | string

    the text to encode

  - ##### `Optional` opts: EncodeXmlOptions

    the options. Allowd value:

    - pre - whether to replace whitespace with ` `
    - multiline - whether to replace linefeed with `
      `
    - maxlength - the maximal allowed length of the text

  #### Returns string

  the encoded text.

### `Static` encodeXMLAttribute

- encodeXMLAttribute(txt): string

- Encodes the string to a valid XML attribute string. Refer to Utl for more XML utilities.

  #### Parameters

  - ##### txt: string

    the text to encode

  #### Returns string

  the encoded text.

  #### Since

  8.0.0

### `Static` fireShown

- fireShown(wgt, bfsz?): void

- Fires beforeSize, onShow, onFitSize, onSize and afterSize

  #### Parameters

  - ##### wgt: Widget<HTMLElement>

    the widget which the zWatch event will be fired against.

  - ##### `Optional` bfsz: number

    the beforeSize mode:

    - 0 (null/undefined/false): beforeSize sent normally.
    - -1: beforeSize won't be sent.
    - 1: beforeSize will be sent with an additional cleanup option, which will clean up the cached minimal size (if flex=min).

  #### Returns void

  #### Since

  5.0.8

### `Static` fireSized

- fireSized(wgt, bfsz?): void

- Fires beforeSize, onFitSize, onSize and afterSize

  #### Parameters

  - ##### wgt: Widget<HTMLElement>

    the widget which the zWatch event will be fired against.

  - ##### `Optional` bfsz: number

    the beforeSize mode:

    - 0 (null/undefined/false): beforeSize sent normally.
    - -1: beforeSize won't be sent.
    - 1: beforeSize will be sent with an additional cleanup option, which will clean up the cached minimal size (if flex=min).

  #### Returns void

  #### Since

  5.0.8

### `Static` frames

- frames(w): Window[]

- #### Parameters

  - ##### w: Window

    the browser window

  #### Returns Window[]

  all descendant frames of the given window.

  To retrieve all, invoke `zUtl.frames(top)`. Notice: w is included in the returned array. If you want to exclude it, invoke `zUtl.frames(w).$remove(w)`.

  #### Since

  5.0.4

### `Static` getDevicePixelRatio

- getDevicePixelRatio(): number

- #### Returns number

  the ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device. For more information, please visit https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio

  #### Since

  8.6.0

### `Static` getUserMedia

- getUserMedia(constraints): Promise<MediaStream>

- #### Parameters

  - ##### constraints: MediaStreamConstraints

    a constraints object specifying the types of media to request

  #### Returns Promise<MediaStream>

  the Promise whose fulfillment handler receives a MediaStream object when the requested media has successfully been obtained. Note: this function may returns a Promise that is rejected, if this browser not support getUserMedia. For more information, please visit https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia

  #### Since

  8.6.1

### `Static` getWeekOfYear

- getWeekOfYear(year, month, date, firstDayOfWeek, minimalDaysInFirstWeek): number

- Get week numbers of year for a specific date

  #### Parameters

  - ##### year: number

  - ##### month: number

  - ##### date: number

  - ##### firstDayOfWeek: number

  - ##### minimalDaysInFirstWeek: number

  #### Returns number

  #### Since

  8.5.1

### `Static` go

- go(url, opts?): void

- Navigates to the specified URL.

  #### Parameters

  - ##### url: string

    the URL to go to

  - ##### `Optional` opts: Partial<GoOptions>

    the options. Allowed values:

    - target - the name of the target browser window. The same browswer window is assumed if omitted. You can use any value allowed in the target attribute of the HTML FORM tag, such as _self, _blank, _parent and _top.
    - overwrite - whether load a new page in the current browser window. If true, the new page replaces the previous page's position in the history list.

  #### Returns void

### `Static` intsToString

- intsToString(ary): string

- Converts an integer array to a string.

  #### Parameters

  - ##### ary: undefined | number[]

    the integer array to convert. If null, an empty string is returned.

  #### Returns string

  #### See

  stringToInts

  #### Deprecated

  Use `[].join()` instead.

### `Static` isAncestor

- isAncestor(p?, c?): boolean

- #### Parameters

  - ##### `Optional` p: ZKObject

    the parent. This method return true if p is null or p is the same as c

  - ##### `Optional` c: ZKObject & {
    getParent?(): Widget<HTMLElement>;
    }

    the child

  #### Returns boolean

  if one is ancestor of the other. It assumes the object has either a method called `getParent` or a field called `parent`. A typical example is used to test the widgets (Widget).

  Notice that, if you want to test DOM elements, please use jq.isAncestor instead.

  #### See

  jq.isAncestor

### `Static` isChar

- isChar(cc, opts): boolean

- #### Parameters

  - ##### cc: string

    the character

  - ##### opts: Partial<IsCharOptions>

    the options.

    Allowed Options
    Name | Allowed Values | Description
    --- | --- | ---
    digit | true, false | Specifies the character is digit only.
    upper | true, false | Specifies the character is upper case only.
    lower | true, false | Specifies the character is lower case only.
    whitespace | true, false | Specifies the character is whitespace only.
    opts[cc] | true, false | Specifies the character is allowed only.

  #### Returns boolean

  whether the character is according to its opts.

### `Static` isEqualObject

- isEqualObject(a, b): boolean

- Check if the two objects has the same value ref: undersore isEqual

  #### Parameters

  - ##### a: unknown

    object

  - ##### b: unknown

    object

  #### Returns boolean

  the two object is the same or not

  #### Since

  10.0.0

### `Static` isImageLoading

- isImageLoading(): boolean

- Checks whether all the loading images are finish.

  #### Returns boolean

  #### See

  loadImage

  #### Since

  6.0.0

### `Static` loadImage

- loadImage(url): void

- Loads an image before ZK client engine to calculate the widget's layout.

  #### Parameters

  - ##### url: string

    the loading image's localation

  #### Returns void

  #### Since

  6.0.0

### `Static` mapToString

- mapToString(map, assign?, separator?): string

- Converts a map to a string

  #### Parameters

  - ##### map: Record<string, string>

    the map to convert

  - ##### `Optional` assign: string

    the symbol for assignment. If omitted, '=' is assumed.

  - ##### `Optional` separator: string

    the symbol for separator. If omitted, ',' is assumed.

  #### Returns string

  #### See

  intsToString

### `Static` parseMap

- parseMap(text, separator?, quote?): Record<string, string>

- Parses the specifie text into a map. For example

      zUtl.parseMap("a=b,c=d");
      zUtl.parseMap("a='b c',c=de", ',', "'\"");

  #### Parameters

  - ##### text: string

    the text to parse

  - ##### `Optional` separator: string

    the separator. If omitted, `','` is assumed

  - ##### `Optional` quote: string

    the quote to handle. Ignored if omitted.

  #### Returns Record<string, string>

  the map

### `Static` progressbox

- progressbox(id, msg, mask?, icon?, opts?): void

- Creates a message box to indicate something is being processed

  #### Parameters

  - ##### id: string

    the ID of the DOM element being created

  - ##### msg: string

    the message to shown

  - ##### `Optional` mask: boolean

    whether to show sem-transparent mask to prevent the user from accessing it.

  - ##### `Optional` icon: string

    the CSS class used to shown an icon in the box. Ignored if not specified.

  - ##### `Optional` opts: Partial<ProgressboxOptions>

  #### Returns void

  #### See

  destroyProgressbox

### `Static` stringToInts

- stringToInts(text, defaultValue): undefined | number[]

- Converts a string separated by comma to an array of integers.

  #### Parameters

  - ##### text: undefined | string

    the string to convert. If null, null is returned.

  - ##### defaultValue: number

    the default value used if the value is not specified. For example, zUtl.stringToInts("1,,3", 2) returns [1, 2, 3].

  #### Returns undefined | number[]

  #### See

  intsToString

### `Static` throttle

- throttle<T, A, R>(func, wait): ((this, ...args) => R)

- Creates and returns a new, throttled version of the passed function, that, when invoked repeatedly, will only actually call the original function at most once per every wait milliseconds. Useful for rate-limiting events that occur faster than you can keep up with.

  Copied from underscore.js, MIT license.

  #### Type Parameters

  - #### T

  - #### A extends unknown[]

  - #### R

  #### Parameters

  - ##### func: ((this, ...args) => R)

    the passed function

    - - (this, ...args): R

      - #### Parameters

        - ##### this: T

        - ##### `Rest` ...args: A

        #### Returns R

  - ##### wait: number

    wait milliseconds

  #### Returns ((this, ...args) => R)

  a new, throttled version of the passed function

  - - (this, ...args): R

    - #### Parameters

      - ##### this: T

      - ##### `Rest` ...args: A

      #### Returns R

  #### Since

  9.6.0

### `Static` today

- today(full, tz?): DateImpl

- #### Parameters

  - ##### full: boolean

    if true, returns the full time, else only returns year, month, and day. If omitted, false is assumed

  - ##### `Optional` tz: string

  #### Returns DateImpl

  today.

- today(fmt, tz?): DateImpl

- #### Parameters

  - ##### fmt: string

    the time format, such as HH:mm:ss.SSS If a time element such as seconds not specified in the format, it will be considered as 0. For example, if the format is "HH:mm", then the returned object will be today, this hour and this minute, but the second and milliseconds will be zero.

  - ##### `Optional` tz: string

  #### Returns DateImpl

  today.

  #### Since

  5.0.6