Client Activity Watches"

From Documentation
 
(24 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
In addtion to widget events (<javadoc directory="jsdoc">zk.Event</javadoc>) and DOM events (<javadoc directory="jsdoc">jq.Event</javadoc>), there are some special notifications called client activity watches. They are used to notify special activities, such as when a widget becomes invisible, or a window is brought to the top. This kind of activity can be listened by so-called watch (<javadoc directory="jsdoc">_global_.zWatch</javadoc>)
 
In addtion to widget events (<javadoc directory="jsdoc">zk.Event</javadoc>) and DOM events (<javadoc directory="jsdoc">jq.Event</javadoc>), there are some special notifications called client activity watches. They are used to notify special activities, such as when a widget becomes invisible, or a window is brought to the top. This kind of activity can be listened by so-called watch (<javadoc directory="jsdoc">_global_.zWatch</javadoc>)
  
=Listen and Unlisten=
+
=Listen to Client Activities =
  
 
To add a watch (i.e., listen to a client activity), you could use <javadoc method="listen(_global_.Map)" directory="jsdoc">_global_.zWatch</javadoc> as follows:
 
To add a watch (i.e., listen to a client activity), you could use <javadoc method="listen(_global_.Map)" directory="jsdoc">_global_.zWatch</javadoc> as follows:
Line 19: Line 19:
 
As shown, the key of each entry in the given map is the name of the client activity (aka., the watch name), and the value could be one of the following:
 
As shown, the key of each entry in the given map is the name of the client activity (aka., the watch name), and the value could be one of the following:
  
* An object that has a method with the same name. In the above case, '''this''' must have the <tt>onSize</tt> and <tt>onShow</tt> methods
+
* An object that has a method with the same name. In the above case, '''this''' must have the <code>onSize</code> and <code>onShow</code> methods
 
* A two-element array, where the first element is the target, and the second is the method
 
* A two-element array, where the first element is the target, and the second is the method
  
The signature of the method is as follows.
+
 
 +
= Listener Object =
 +
Here is an example of a client activity listener:
 +
<syntaxhighlight lang='js'>
 +
var listener = {
 +
    onCommandReady: function(controller) {
 +
        zk.log(arguments[0].name);
 +
    },
 +
    onResponse: function(controller) {
 +
        zk.log(arguments[0].name);
 +
    },
 +
    onFloatUp: function(controller) {
 +
        zk.log(`focus on ${controller.origin.widgetName}` )
 +
    },
 +
}
 +
 
 +
zWatch.listen({onCommandReady: listener,
 +
              onResponse: listener,
 +
              onFloatUp: listener,
 +
              });
 +
</syntaxhighlight>
 +
 
 +
==Size Event Listener==
 +
<syntaxhighlight lang='js' line highlight='6-8'>
 +
var sizeListener = {
 +
    onSize: function(controller) {
 +
        zk.log(arguments[0].name);
 +
        //ctrl.origin is null
 +
    },
 +
    isWatchable_: function() { //required for a size event listener
 +
        return true;
 +
    }
 +
};
 +
</syntaxhighlight>
 +
* Line 6-8: you need to add this function to listen to those size related events
 +
 
 +
<!--
 +
zWatch = function () {
 +
  var _visiEvts = {
 +
    onFitSize: true,
 +
    onSize: true,
 +
    onShow: true,
 +
    onHide: true,
 +
    beforeSize: true,
 +
    afterSize: true
 +
  },
 +
-->
 +
 
 +
=== Listener Function ===
 +
The signature of the listener function is as follows.
  
 
<source lang="java">
 
<source lang="java">
function onWhatever(ctl, arg0, arg1...) {
+
function onWhatever(controller, arg0, arg1...) {
   //ctl.origin: the object passed as the first argument to zWatch.fire or zWatch.fireDown
+
   //controller.origin: the object passed as the first argument to zWatch.fire or zWatch.fireDown
   //ctl.fireDown(something) and ctl.fire(something):
+
   //controller.fireDown(something) and controller.fire(something):
 
   //   
 
   //   
 
}
 
}
 
</source>
 
</source>
  
where <tt>ctl</tt> is a controller allowing you to have better control of the invocation sequence of the listeners, and <tt>arg0</tt> and others are the arguments that passed to <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>.
+
Where <code>controller</code> is a controller allowing you to control of the invocation sequence of the listeners, and <code>arg0</code> and others are the arguments that passed to <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>.
  
The controller has two methods: fire and fireDown, and one field: origin. The fire and fireDown methods are used to fore the remaining listeners (caused by the same invocation of of <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>) to be invoked. If your listener doesn't call any of them, the other listeners are called in the same order of registration.
+
Here is the pseudo-code for the controller:
 
+
<syntaxhighlight line lang="java">
Here is the pseudo code for the controller:
 
<source lang="java">
 
 
interface Controller {
 
interface Controller {
   /** Usually zk.Widget (unless fire and fireDown was called with a different object) */
+
  /** event name */
 +
  name;
 +
   /** Usually zk.Widget (unless fire() and fireDown() is called with a different object) */
 
   Object origin;
 
   Object origin;
 
   /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
 
   /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
Line 46: Line 95:
 
   void fireDown(Object ref, Object...);
 
   void fireDown(Object ref, Object...);
 
}
 
}
</source>
+
</syntaxhighlight>
  
where <tt>ref</tt> is optional. If specified, it will invoke only the listeners for the given object (and its descendants if fireDown) that are not invoked yet. If null, it will invokes all the listeners that are not invoked yet.
+
* Line 5: it is the original object (usually a widget, <javadoc directory="jsdoc">zk.Widget</javadoc>) passed as the first argument when <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> was called. In other words, it is the one that causes the client activity, e.g. the widget being dragged, shown, or sized. It is null if not available.
 
+
* Line 7, 9: The fire() and fireDown() are used to fore the remaining listeners (caused by the same invocation of of <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>) to be invoked. If your listener doesn't call any of them, the other listeners are called in the same order of registration. The <code>ref</code> is optional. If specified, it will invoke only the listeners for the given object (and its descendants if fireDown) that are not invoked yet. If null, it will invoke all the listeners that are not invoked yet.
The origin field (<tt>ctl.origin</tt>) is the original object (usually a widget, <javadoc directory="jsdoc">zk.Widget</javadoc>) passed as the first argument when <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> was called. In other words, it is the one causes the client activity. It is null if not available.
 
  
 +
= Unlisten =
 
To unlisten, you could use <javadoc method="unlisten(_global_.Map)" directory="jsdoc">_global_.zWatch</javadoc> as follows:
 
To unlisten, you could use <javadoc method="unlisten(_global_.Map)" directory="jsdoc">_global_.zWatch</javadoc> as follows:
  
Line 64: Line 113:
 
=Fire=
 
=Fire=
  
The client activity is triggered (aka., fired) by either <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> or <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>.
+
The client activity is triggered (aka., fired) by one of the following 2 functions:
 +
 
 +
* <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>: will invoke the listeners on the target object
 +
* <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc>: will invokes the listeners on the target object and all of '''its descendants''' (i.e., the target object's children, grandchildren...).
 +
 
  
<javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> will invoke the listeners for the target object (the first argument), while <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> will invokes the listeners for the target object and all of its descendants (i.e., the target object's children, grandchildren...).
 
  
 
For example, if a widget resizes itself, it could fire down onSize as follows.
 
For example, if a widget resizes itself, it could fire down onSize as follows.
Line 77: Line 129:
  
 
=Client Activities=
 
=Client Activities=
Here is the list of client activities that you could watch.
+
Here is the list of client activities that you could watch (in alphabetic order).
  
== beforeSize ==
+
== afterSize ==
 
  [fireDown]
 
  [fireDown]
 +
{{versionSince| 8.5.2}}
  
It is called right before the browser window or the parent widget is resized.  
+
It is called right after the browser window or the parent widget is resized.
  
beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.
+
<code>beforeSize</code>, <code>onFitSize</code>, <code>onSize</code>, and <code>afterSize</code> are fired when a browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.
  
 
Notice <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> must be used to fire this event, so only the listeners of descendants of the specified widget will be called.
 
Notice <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> must be used to fire this event, so only the listeners of descendants of the specified widget will be called.
 +
 +
Don't do anything that would interfere the position of other components in this event. For example: changing size/content or adding/removing/moving the DOM node. The typical usage is to recalculate the position of popup/notification.
  
 
* Parameters
 
* Parameters
** ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.
+
** <code>ctl.origin</code> - the widget that causes the resizing. If null, it means the whole browser is resized.
 +
 
  
== afterSize ==
+
== beforeSize ==
 
  [fireDown]
 
  [fireDown]
[since 8.5.2]
 
  
It is called right after the browser window or the parent widget is resized.
+
It is called right before the browser window or the parent widget is resized.  
  
 
beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.
 
beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.
  
 
Notice <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> must be used to fire this event, so only the listeners of descendants of the specified widget will be called.
 
Notice <javadoc method="fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> must be used to fire this event, so only the listeners of descendants of the specified widget will be called.
 
Don't do anything that would interfere the position of other components in this event. For example: changing size/content or adding/removing/moving the DOM node. The typical usage is to recalculate the position of popup/notification.
 
  
 
* Parameters
 
* Parameters
 
** ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.
 
** ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.
  
== onBindLevelChange ==
+
== onBeforeDestroy ==
 +
{{versionSince| 9.6.0}}
 +
 
 +
It is called before the desktop is removed.
 +
For example,  it can be used in embedded ZK.
 +
 
 +
<source lang="javascript" >
 +
desktop.listen({onBeforeDestroy:function(){
 +
console.log("before destroy this desktop")
 +
}});
 +
</source>
 +
 
 +
== onBindLevelMove ==
 
  [fire]
 
  [fire]
  
It is called if the bind level of a widget (<javadoc directory="jsdoc">zk.Widget</javadoc>'s <code>bindLevel</code>) is changed due to moving from one parent to another.
+
It is called if a <javadoc directory="jsdoc">zk.Widget</javadoc>'s <code>bindLevel</code> is changed due to moving from one parent to another.
  
Notice it won't be called if it is unbound and bound (i.e., detached and attached).
+
Notice it won't be called if the widget is unbound and bound (i.e., detached and attached).
  
 
Notice <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 
Notice <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 +
 +
== onCommandReady ==
 +
{{versionSince| 7.0.5}}
 +
[fire]
 +
 +
It is called after the AU commands are processed and before "onResponse". In other words, the "onCommandReady" is fired without "setTimeout" which is triggered directly. Unlike "onResponse" will be triggered with a "setTimeout".
 +
 +
Notice the <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 +
 +
 +
== onEndDrag ==
 +
[fire]
 +
 +
It's fired after an end-user stops dragging a component by releasing a mouse button.
  
 
== onFitSize ==
 
== onFitSize ==
 
  [fireDown; reverse order]
 
  [fireDown; reverse order]
[since 5.0.8]
+
{{versionSince| 5.0.8}}
  
 
It is called between beforeSize and onSize.
 
It is called between beforeSize and onSize.
  
beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.
+
beforeSize, onFitSize, onSize, and afterSize are fired when a browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset the style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.
  
Notice that the listeners of onFitSize are called in the reverse order, i.e., the child is called before the parent. However, superclass's listener of the same widget will still be called first (like onSize and other events).
+
Notice that the listeners of onFitSize are called in the reverse order, i.e., the child is called before the parent. However, the superclass' listener of the same widget will still be called first (like onSize and other events).
  
 
* Parameters
 
* Parameters
** ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.
+
** <code>ctl.origin</code> - the widget that causes the resizing. If null, it means the whole browser is resized.
 +
 
 +
== onFloatUp ==
 +
[fire]
 +
 
 +
It is called after a widget has gained the focus. It means the 'float' widget that is the parent of the focus widget shall become topmost.
 +
 
 +
Notice <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 +
 
 +
* Parameters
 +
** ctl.origin - the widget gains the focus.
 +
 
  
 
== onHide ==
 
== onHide ==
Line 141: Line 231:
 
** [[#onShow]]
 
** [[#onShow]]
  
== onFloatUp ==
+
 
 +
== onMove ==
 
  [fire]
 
  [fire]
  
It is called after a widget has gained the focus. It means the 'float' widget that is the parent of the focus widget shall become topmost.
+
It is called after you finish dragging a component in a browser.
  
Notice <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 
 
* Parameters
 
** ctl.origin - the widget gains the focus.
 
  
 
== onResponse ==
 
== onResponse ==
 
  [fire]
 
  [fire]
  
It is called after the response of the AU request has been sent back from the server, and processed.
+
It is called after the response of the AU request has been sent back from the server and processed.
 
 
Notice the <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 
 
 
== onCommandReady ==
 
[since 7.0.5]
 
[fire]
 
 
 
It is called after the AU commands processed and before "onResponse". In other words, the "onCommandReady" is fired without "setTimeout" which is triggered directly. Unlike "onResponse" will be triggered with a "setTimeout".
 
  
 
Notice the <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
 
Notice the <javadoc method="fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)" directory="jsdoc">_global_.zWatch</javadoc> is used, so all listeners are invoked.
Line 201: Line 280:
 
  [fireDown]
 
  [fireDown]
  
It is called when the browser window and a widget is resized.
+
It is called when a browser window is resized.
  
beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.
+
beforeSize, onFitSize, onSize, and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset the style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.
  
 
Notice that a layout widget (such as Borderlayout and Hbox) must fire both <code>beforeSize</code> and <code>onSize</code> when it resizes.
 
Notice that a layout widget (such as Borderlayout and Hbox) must fire both <code>beforeSize</code> and <code>onSize</code> when it resizes.
Line 220: Line 299:
  
 
* Parameters
 
* Parameters
** ctl.origin - the widget has become visible
+
** ctl.origin - the widget that becomes visible
  
 
* See Also
 
* See Also
 
** [[#onHide]]
 
** [[#onHide]]
 +
 +
== onStartDrag ==
 +
[fire]
 +
 +
It's fired after an end-user drags a component with a mouse.
  
 
== onVParent ==
 
== onVParent ==
 
  [fireDown]
 
  [fireDown]
[since 5.0.8]
+
{{versionSince| 5.0.8}}
  
 
It is called when <javadoc directory="jsdoc" method="makeVParent()">_global_.jqzk</javadoc> or <javadoc directory="jsdoc" method="undoVParent()">_global_.jqzk</javadoc> is called to move a DOM element to/from <code>document.body</code>.
 
It is called when <javadoc directory="jsdoc" method="makeVParent()">_global_.jqzk</javadoc> or <javadoc directory="jsdoc" method="undoVParent()">_global_.jqzk</javadoc> is called to move a DOM element to/from <code>document.body</code>.
  
It is rarely required but to fix the browser's bug if any. Furthermore, if you listen to onVParent, it is likely you have to listen onRestore too.
+
It is rarely required but could be used to fix a browser's bug if any. Furthermore, if you listen to onVParent, it is likely you have to listen to onRestore too.
  
 
* Parameters
 
* Parameters
Line 238: Line 322:
 
* See Also
 
* See Also
 
** [[#onRestore]]
 
** [[#onRestore]]
 
== desktop#onBeforeDestroy ==
 
[since 9.6.0]
 
 
It is called before the desktop removed.
 
 
It can be used in embedded ZK.
 
 
<source lang="javascript" >
 
desktop.listen({onBeforeDestroy:function(){
 
console.log("before destroy this desktop")
 
}});
 
</source>
 
  
 
=Version History=
 
=Version History=

Latest revision as of 08:04, 7 August 2023


Client Activity Watches



In addtion to widget events (Event) and DOM events (Event), there are some special notifications called client activity watches. They are used to notify special activities, such as when a widget becomes invisible, or a window is brought to the top. This kind of activity can be listened by so-called watch (zWatch)

Listen to Client Activities

To add a watch (i.e., listen to a client activity), you could use zWatch.listen(Map) as follows:

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

As shown, the key of each entry in the given map is the name of the client activity (aka., the watch name), and the value could be one of the following:

  • An object that has a method with the same name. In the above case, this must have the onSize and onShow methods
  • A two-element array, where the first element is the target, and the second is the method


Listener Object

Here is an example of a client activity listener:

var listener = {
    onCommandReady: function(controller) {
        zk.log(arguments[0].name);
    },
    onResponse: function(controller) {
        zk.log(arguments[0].name);
    },
    onFloatUp: function(controller) {
        zk.log(`focus on ${controller.origin.widgetName}` )
    },
}

zWatch.listen({onCommandReady: listener,
               onResponse: listener,
               onFloatUp: listener,
               });

Size Event Listener

1 var sizeListener = {
2     onSize: function(controller) {
3         zk.log(arguments[0].name);
4         //ctrl.origin is null
5     },
6     isWatchable_: function() { //required for a size event listener
7         return true;
8     }
9 };
  • Line 6-8: you need to add this function to listen to those size related events


Listener Function

The signature of the listener function is as follows.

function onWhatever(controller, arg0, arg1...) {
  //controller.origin: the object passed as the first argument to zWatch.fire or zWatch.fireDown
  //controller.fireDown(something) and controller.fire(something):
  //   
}

Where controller is a controller allowing you to control of the invocation sequence of the listeners, and arg0 and others are the arguments that passed to zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map).

Here is the pseudo-code for the controller:

 1 interface Controller {
 2   /** event name */
 3   name;
 4   /** Usually zk.Widget (unless fire() and fireDown() is called with a different object) */
 5   Object origin;
 6   /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
 7   void fire(Object ref, Object...);
 8   /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
 9   void fireDown(Object ref, Object...);
10 }
  • Line 5: it is the original object (usually a widget, Widget) passed as the first argument when zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map) was called. In other words, it is the one that causes the client activity, e.g. the widget being dragged, shown, or sized. It is null if not available.
  • Line 7, 9: The fire() and fireDown() are used to fore the remaining listeners (caused by the same invocation of of zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map)) to be invoked. If your listener doesn't call any of them, the other listeners are called in the same order of registration. The ref is optional. If specified, it will invoke only the listeners for the given object (and its descendants if fireDown) that are not invoked yet. If null, it will invoke all the listeners that are not invoked yet.

Unlisten

To unlisten, you could use zWatch.unlisten(Map) as follows:

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

Fire

The client activity is triggered (aka., fired) by one of the following 2 functions:


For example, if a widget resizes itself, it could fire down onSize as follows.

zWatch.fireDown("onSize", wgt);

The target object could be anything as long as the listener recognizes it, but ZK's standard widgets use Widget only.

Client Activities

Here is the list of client activities that you could watch (in alphabetic order).

afterSize

[fireDown]

Since 8.5.2

It is called right after the browser window or the parent widget is resized.

beforeSize, onFitSize, onSize, and afterSize are fired when a browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of the specified widget will be called.

Don't do anything that would interfere the position of other components in this event. For example: changing size/content or adding/removing/moving the DOM node. The typical usage is to recalculate the position of popup/notification.

  • Parameters
    • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.


beforeSize

[fireDown]

It is called right before the browser window or the parent widget is resized.

beforeSize, onFitSize, onSize and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimal allowed size. And the the listener of onSize can change it to the correct size. Finally, the the listener of afterSize could move the floating elements such as popups to the correct position.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of the specified widget will be called.

  • Parameters
    • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onBeforeDestroy

Since 9.6.0

It is called before the desktop is removed. For example, it can be used in embedded ZK.

desktop.listen({onBeforeDestroy:function(){
	console.log("before destroy this desktop")
}});

onBindLevelMove

[fire]

It is called if a Widget's bindLevel is changed due to moving from one parent to another.

Notice it won't be called if the widget is unbound and bound (i.e., detached and attached).

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onCommandReady

Since 7.0.5

[fire]

It is called after the AU commands are processed and before "onResponse". In other words, the "onCommandReady" is fired without "setTimeout" which is triggered directly. Unlike "onResponse" will be triggered with a "setTimeout".

Notice the zWatch.fire(String, Object, Map) is used, so all listeners are invoked.


onEndDrag

[fire]

It's fired after an end-user stops dragging a component by releasing a mouse button.

onFitSize

[fireDown; reverse order]

Since 5.0.8

It is called between beforeSize and onSize.

beforeSize, onFitSize, onSize, and afterSize are fired when a browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset the style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.

Notice that the listeners of onFitSize are called in the reverse order, i.e., the child is called before the parent. However, the superclass' listener of the same widget will still be called first (like onSize and other events).

  • Parameters
    • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onFloatUp

[fire]

It is called after a widget has gained the focus. It means the 'float' widget that is the parent of the focus widget shall become topmost.

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

  • Parameters
    • ctl.origin - the widget gains the focus.


onHide

[fireDown]

It is called before a widget is going to become invisible.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

  • Parameters
    • ctl.origin - the widget is becoming invisible


onMove

[fire]

It is called after you finish dragging a component in a browser.


onResponse

[fire]

It is called after the response of the AU request has been sent back from the server and processed.

Notice the zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onRestore

[fireDown]

It is called when Skipper restores the DOM elements.

It is rarely required but to fix the browser's bug if any. Furthermore, if you listen to onRestore, it is likely you have to listen onVParent too.

  • Parameters
    • ctl.origin - the widget has become visible

onScroll

[fire]

It is called when the browser window or the specified widget is scrolling.

Notice the zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

  • Parameters
    • ctl.origin - the widget that is scrolling (i.e., causing the onScroll watch), or null if the whole browser window is scrolling

onSend

[fire]

It is called before sending the AU request to the server. The implicit argument indicates whether all AU requests being sent are implicit.

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onSize

[fireDown]

It is called when a browser window is resized.

beforeSize, onFitSize, onSize, and afterSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset the style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to calculate the minimum allowed size. And the listener of onSize can change it to the correct size. Finally, the listener of afterSize could move the floating elements such as popups to the correct position.

Notice that a layout widget (such as Borderlayout and Hbox) must fire both beforeSize and onSize when it resizes.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

  • Parameters
    • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onShow

[fireDown]

It is called after a widget has become visible.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

  • Parameters
    • ctl.origin - the widget that becomes visible

onStartDrag

[fire]

It's fired after an end-user drags a component with a mouse.

onVParent

[fireDown]

Since 5.0.8

It is called when jqzk.makeVParent() or jqzk.undoVParent() is called to move a DOM element to/from document.body.

It is rarely required but could be used to fix a browser's bug if any. Furthermore, if you listen to onVParent, it is likely you have to listen to onRestore too.

  • Parameters
    • ctl.origin - the widget has become visible

Version History

Last Update : 2023/08/07


Version Date Content
5.0.8 August 2011 onFitSize and onVParent was introduced.
7.0.5 February 2015 Support onCommandReady
8.5.2 July 2018 ZK-3943 afterSize was introduced.



Last Update : 2023/08/07

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.