# Class zWatch

#### Import

zk.Widget

An utility to manage watches.

A watch is a system-level event, such as onSize and beforeSize. For example, when an AU request is going to be sent to the server, the onSend watch is fired so the client application and/or the widget implementation can listen to it.

Here is a full list of Client Activity Watches.

### Add a Watch

To add a listener to a watch, use listen. The listener must implement a method with the same as the action name. For example, ```ts MyListener = zk.$extends(zk.Object, { onSend: function() { } }); var ml = new MyListener(); zWatch.listen({onSend: ml}) ```

Then, ml.onSend will be called when sending an AU request.

### Invocation Sequence

#### Sequence of fireDown

The watch listener is added in the parent-first sequence if it has a method called getParent, or a member called parent (a typical example is Widget). Thus, the parent will be called before its children, if they are all registered to the same action.

#####
Index

### Constructors

constructor

### Methods

fire
fireDown
listen
onBindLevelMove
unlisten
unlistenAll

## Constructors

### constructor

- new zWatch(): zWatch

- #### Returns zWatch

## Methods

### `Static` fire

- fire(name, org, opts?, ...vararg): void

- Fires an watch that invokes all listeners of the watch.

  For example, zWatch.fire('onX', null, 'a', 123) will cause ml.onX(ctl, 'a', 123) being called -- assuming ml is a listener of onX.

  Notice that the first argument (ctl in the above example) is a special controller. The first two argument of fire become part of the control (as the name and origin fields). In additions, the control can be used to control the invocation sequence. For example, the invocation sequence is, by default, evaluated in the order of fist-listen-first-call, and you can use the controller to force the listeners of a certain target to be called first as follows.

      onX: function (ctl) {
        ctl.fire(specialTarget); //enforce the listeners of specialTarget to execute first
        ...
      }

  If you want the listeners of descendants to execute too, use fireDown instead as follows:

      onX: function (ctl) {
      ctl.fireDown(specialTarget); //enforce the listeners of specialTarget and descendants to execute first
      ....
      }

  #### Parameters

  - ##### name: string

    the watch name, such as onFloatUp.

  - ##### org: ZKObject

  - ##### `Optional` opts: unknown

    options:

    - reverse - whether to reverse the execution order. If false or omitted, the parent is called first. If true, the child is called first. Notice that there is a limitation: if reverse, you can invoke `ctl.fire` in the callback.
    - timeout - how many miliseconds to wait before calling the listeners. If Omitted or negative, the listeners are invoked immediately.

  - ##### `Rest` ...vararg: unknown[]

    any number of arguments to pass to the listener. They will become the second, third and following arguments when the listener is called.

  #### Returns void

### `Static` fireDown

- fireDown(name, org, opts?, ...vararg): void

- Fires an watch but invokes only the listeners that are a descendant of the specified origin.

  By descendant we mean the watch listener is the same or an descendant of the specified origin. In other words, if the specified origin is not the ancestor of a watch listener, the listener won't be called.

  Notice that it assumes:

  1. The watch listener's parent can be retrieved by either a method called getParent, or a property called parent.
  2. It has a data member called bindLevel indicating which level the object in the parent-child tree.

  Widget is a typical example (Widget#parent and Widget#bindLevel).

  For example, zWatch.fireDown('onX', wgt, opts, 'a', 123) will cause ml.onX(ctl, opts, 'a', 123) being called -- assuming ml is a listener of onX and zUtl.isAncestor(wgt, ml) is true (zUtl#isAncestor).

  Notice that the first argument (ctl in the above example) is a special controller that a listen can use to do further control. For example, origin (of fire()) can be retrieved by accessing the member of the controller called origin. ```ts onSize: function (ctl) { if (ctl.origin) //retrieve the origin ... } ```

  Notice that the second argument (opts in the above example) is also a special argument used to pass optional control info to the zWatch engine.

  The invocation sequence is, by default, evaluated in the order of parent-first, and you can use the controller to change it. For example, the following will cause the listener of specialTarget, if any, to execute first. ```ts onX: function (ctl) { ctl.fire(specialTarget); //enfore the listeners of specialTarget to execute first ... } ```

  If you want the listeners of descendants to execute too, use fireDown instead as follows: ```ts onX: function (ctl) { ctl.fireDown(specialTarget); //enfore the listeners of specialTarget and descendants to execute first ... } ```

  It is useful if a listener depends some of its children's listeners to complete (notice that the parent's listener is, by default, called first). For example, when onSize of a widget is called, it might want some of its children's onSiz to be called first (so he can have their updated size).

  #### Parameters

  - ##### name: string

    the watch name, such as onShow.

  - ##### org: ZKObject

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

    options:

    - reverse - whether to reverse the execution order. If false or omitted, the parent is called first. If true, the child is called first. Notice that there is a limitation: if reverse, you can invoke `ctl.fireDown` in the callback.
    - timeout - how many miliseconds to wait before calling the listeners. If Omitted or negative, the listeners are invoked immediately.

  - ##### `Rest` ...vararg: unknown[]

    any number of arguments to pass to the listener. They will become the third, forth, and following arguments when the listener is called.

  #### Returns void

### `Static` listen

- listen(infs): void

-     zWatch.listen({
        onSize: this,
        onShow: this,
        onHide: [this, this._onHide]
      });

  Registers watch listener(s). For example,

      zWatch.listen({
        onSize: this,
        onShow: this,
        onHide: [this, this._onHide]
      });

  As shown above, each key of the infs map is the watch name, and each value is the target against which the watch listener will be called, or a two-element array, where the first element is the target and the second the listener function. For example, `zWatch({onSize: foo})` will cause foo.onSize to be called when onSize is fired. The arguments passed are the same as fire/fireDown.

  Note: the order is parent-first (if the watch has a method called getParent or a member called parent), so the invocation (fire) is from the parent to the child if both are registered.

  #### Parameters

  - ##### infs: Partial<ClientActivity>

    a map of the watch listeners. Each key of the map is the watch name, and each value is the target or a two-element array, where the first element is the target and the second the listener function. It assumes the target implements the method with the same name as the watch name. In addition, when the method is called, this references to the target.

  #### Returns void

### `Static` onBindLevelMove

- onBindLevelMove(): void

- #### Returns void

### `Static` unlisten

- unlisten(infs): void

- Removes watch listener(s).

  #### Parameters

  - ##### infs: Partial<ClientActivity>

    a map of watch listeners. Each key is the watch name, and each value is the target or or a two-element array, where the first element is the target and the second the listener function.

  #### Returns void

### `Static` unlistenAll

- unlistenAll(name): void

- Removes all listener of the specified watch.

  #### Parameters

  - ##### name: keyof ClientActivity

    the watch name, such as onShow

  #### Returns void