_global_
Class zk

java.lang.Object
  extended by _global_.zk

public class zk
extends java.lang.Object

A collection of ZK core utilities. The utilities are mostly related to the language enhancement we added to JavaScript, such as $extends(zk.Class, _global_.Map, _global_.Map) and $package(_global_.String).

Refer to jq for DOM related utilities.


Field Summary
static String agent
          The user agent of the browser.
static java.lang.Boolean air
          Whether it is Adobe AIR.
static boolean alerting
          Indicates whether an OS-level modal dialog is opened.
static String appName
          The application's name, which will be initialized as server-side's WebApp.getAppName().
static boolean booted
          Indicates whether ZK Client Engine has been booted and created the initial widgets.
static String build
          The build of ZK, such as '08113021'
static int busy
          Indicates if the application is busy.
static Offset clickPointer
          The last position that the mouse was clicked (including left and right clicks).
static java.lang.Boolean css3
          Whether it supports CSS3.
static Widget currentFocus
          The widget that gains the focus now, or null if no one gains focus now.
static Window currentModal
          The topmost modal window, or null if no modal window at all.
static Offset currentPointer
          The position of the mouse (including mouse move and click).
static char DECIMAL
          The character used for decimal sign.
static java.lang.Double ff
          Returns the version as double (only the first two part of the version, such as 3.6) if it is Firefox, such as Firefox.
static java.lang.Double gecko
          Returns the version as double (only the first two part of the version, such as 3.5) if it is Gecko-based browsers, such as Firefox.
static char GROUPING
          The character used for thousands separator.
static java.lang.Double ie
          Returns the DOM API's version if the browser is Internet Explorer, or null if not.
static java.lang.Boolean ie6_
          Whether it is Internet Exploer 6 (excluding 7 or others).
static java.lang.Boolean ie7
          Whether it is Internet Exploer 7 or later.
static java.lang.Boolean ie7_
          Whether it is Internet Exploer 7 (excluding 8 or others).
static java.lang.Boolean ie8
          Whether it is Internet Exploer 8 or later.
static java.lang.Boolean ie8c
          Whether it is Internet Exploer 8 or later, and running in Internet Explorer 7 compatible mode.
static java.lang.Boolean ie9
          Whether it is Internet Exploer 9 or later.
static java.lang.Double iex
          Returns the browser's version as double (only the first two part of the version, such as 8) if the browser is Internet Explorer, or null if not.
static Widget keyCapture
          The widget that captures the keystrokes.
static int loading
          The number of widget packages (i.e., JavaScript files) being loaded (and not yet complete).
static char MINUS
          The character used to represent minus sign.
static boolean mounting
          Whether ZK Client Engine has been mounting the peer widgets.
static Widget mouseCapture
          The widget that captures the mouse events.
static java.lang.Double opera
          Returns the version as double (only the first two part of the version, such as 10.1) if it is Opera, or null if not.
static char PER_MILL
          The character used for mille percent sign.
static char PERCENT
          The character used for percent sign.
static int procDelay
          The delay before showing the processing prompt (unit: milliseconds).
static boolean processing
          Whether Client Engine is processing something, such as processing an AU response.
static int resendTimeout
          The timeout for re-sending AU request (unit: milliseconds).
static java.lang.Double safari
          Returns the version as double (only the first two part of the version, such as 533.1) if it is Safari-based, or null if not.
static boolean spaceless
          Indicates whether Widget.id is always the same as Widget.uuid.
static int tipDelay
          The delay before showing a tooltip (unit: milliseconds).
static boolean unloading
          Indicates whether the browser is unloading this document.
static String version
          The version of ZK, such as '5.0.0'
 
Method Summary
static Map $default(Map opts, Map defaults)
          Provides the default values for the specified options.
static Class $extends(Class sueprclass, Map members, Map staticMembers)
          Defines a class.
static java.lang.Object $import(String name)
          Imports a class or a package.
static java.lang.Object $import(String name, Function fn)
          Imports a package or class, and load it if fn is specified.
static Package $package(String name)
          Defines a package.
static void $void()
          A does-nothing-but-returns-false function.
static boolean afterAnimate(Function fn, int delay)
          Executes a function only when no animation is taking place.
static boolean afterLoad(Function func)
          Declares a function that shall be executed after all requested packages are loaded (i.e., loading is 0).
static void afterLoad(String pkgs, Function func)
          Declares a function that shall be executed only if the specified package(s) are loaded (and loading is 0).
static boolean afterMount(Function fn, int delay)
          Adds a function that will be executed after the mounting is done.
static void afterResize(Function fn)
          Adds a function that will be executed after all of the onSize events are done.
static String ajaxURI(String uri, Map opts)
          Encodes and returns the URI to communicate with the server.
static boolean animating()
          Returns whether there is some animation taking place.
static void beforeUnload(Function fn, Map opts)
          Adds a function that will be executed when the browser is about to unload the document.
static void classes()
          A map of all classes, Map.
static java.lang.Object copy(java.lang.Object dst, java.lang.Object src)
          Copies a map of properties (or options) from one object to another.
static java.lang.Object copy(java.lang.Object dst, java.lang.Object src, Map backup)
          Copies a map of properties (or options) from one object to another and copies the original value to another map.
static java.lang.Object cut(Map props, String nm)
          Retrieves and removes the value of the specified name of the given map.
static Class define(Class klass, Map props)
          Defines the setter and getter methods.
static void depends(String a, String b)
          Declare a package that must be loaded when loading another package.
static void disableESC()
          Disable the default behavior of ESC.
static void enableESC()
          Enables the default behavior of ESC (i.e., stop loading from the server).
static void endProcessing()
          Clears a flag, processing, to indicate that it the processing has done.
static void error(String msg)
          Display an error message to indicate an error.
static void errorDismiss()
          Closes all error messages shown by error(_global_.String).
static java.lang.Object get(java.lang.Object o, String name)
          Retrieves a value from the specified property.
static String getHost(String pkg, boolean js)
          Returns the URI of the server (so called host) for the specified package.
static String getVersion(String pkg)
          Returns the version of the specified package, or null if not available.
static void isClass(java.lang.Object cls)
          Returns if the given JS object is a class (Class).
static boolean isLoaded(String pkg, boolean loading)
          Tests if a package is loaded (or being loaded).
static void isObject(java.lang.Object o)
          Returns whether the given JS object is a ZK object (Object).
static boolean load(String pkg, Desktop dt, Function func)
          Loads the specified package(s).
static boolean load(String pkg, Function func)
          Loads the specified package(s).
static zk loadScript(String src, String name, String charset)
          Loads a JavaScript file.
static void log(java.lang.Object... detailed)
          Logs an message for debugging purpose.
static Function override(Function oldfunc, Function newfunc)
          Overrides a particular method.
static java.lang.Object override(java.lang.Object dst, Map backup, Map src)
          Overrides the properties of a map.
static java.lang.Object override(java.lang.Object dst, String nm, java.lang.Object val)
          Overrides a particular method or data member.
static double parseFloat(String v)
          Parses a string to a floating number.
static int parseInt(String v, int b)
          Parses a string to an integer.
static java.lang.Object set(java.lang.Object dst, java.lang.Object src, Array props, boolean ignoreUndefined)
          Sets the given properties from one object to another.
static java.lang.Object set(java.lang.Object o, String name, java.lang.Object value, java.lang.Object extra)
          Assigns a value to the specified property.
static void setHost(String host, String updURI, Array pkgs)
          Defines the URL of the host for serving the specified packages.
static void setScriptLoaded(String name)
          Notify ZK that the name of the JavaScript file is loaded.
static void setVersion(String pkg, String ver)
          Sets the version of the specified package.
static void stamp()
          Logs the information of all stamps made by stamp(String, boolean).
static void stamp(String name, boolean noAutoLog)
          Make a time stamp for this momemt; used for performance tuning.
static void startProcessing(int timeout)
          Set a flag, processing, to indicate that it starts a processing.
static Desktop stateless(String dtid, String contextURI, String updateURI, String reqURI)
          Declares the desktop is used for the stateless context.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

procDelay

public static int procDelay
The delay before showing the processing prompt (unit: milliseconds).

Default: 900 (depending on the server's configuration)


tipDelay

public static int tipDelay
The delay before showing a tooltip (unit: milliseconds). Default: 800 (depending on the server's configuration)


resendTimeout

public static int resendTimeout
The timeout for re-sending AU request (unit: milliseconds). Default: 200 (depending on the server's configuration)

Since:
6.5.2

clickPointer

public static Offset clickPointer
The last position that the mouse was clicked (including left and right clicks).


currentPointer

public static Offset currentPointer
The position of the mouse (including mouse move and click).


loading

public static int loading
The number of widget packages (i.e., JavaScript files) being loaded (and not yet complete).

When the JavaScript files of widgets are loading, you shall not create any widget. Rather, you can use afterLoad(_global_.String, _global_.Function) to execute the creation and other tasks after all required JavaScript files are loaded.

See Also:
load(_global_.String, zk.Desktop, _global_.Function), afterLoad(_global_.String, _global_.Function), processing, mounting

busy

public static int busy
Indicates if the application is busy. It is actually a number that is increased when AuCmd0.showBusy(String) is called, and decreased when AuCmd0.clearBusy() is called. In other words, it is set by the application, and used to indicate the application (rather than ZK) is busy.

Since:
5.0.1

appName

public static String appName
The application's name, which will be initialized as server-side's WebApp.getAppName(). It will be used as title of jq.alert(_global_.String, _global_.Map).

Since:
5.0.6

currentFocus

public static Widget currentFocus
The widget that gains the focus now, or null if no one gains focus now.


currentModal

public static Window currentModal
The topmost modal window, or null if no modal window at all.


mounting

public static boolean mounting
Whether ZK Client Engine has been mounting the peer widgets. By mounting we mean the creation of the peer widgets under the control of the server. To run after the mounting of the peer widgets, use afterMount(_global_.Function, int)

See Also:
afterMount(_global_.Function, int), processing, loading, booted

processing

public static boolean processing
Whether Client Engine is processing something, such as processing an AU response. This flag is set when startProcessing(int) is called, and cleaned when endProcessing() is called.

See Also:
startProcessing(int), loading, mounting

booted

public static boolean booted
Indicates whether ZK Client Engine has been booted and created the initial widgets. It is useful to know if it is caused by an asynchronous update (i.e., zk.booted is true).

See Also:
mounting, unloading

unloading

public static boolean unloading
Indicates whether the browser is unloading this document. Note: when the function registered with beforeUnload(_global_.Function, _global_.Map) is called, this flag is not set yet.

See Also:
loading, booted

version

public static String version
The version of ZK, such as '5.0.0'


build

public static String build
The build of ZK, such as '08113021'


agent

public static String agent
The user agent of the browser.


ie

public static java.lang.Double ie
Returns the DOM API's version if the browser is Internet Explorer, or null if not.

Note: it is DOM API's version, not the browser version. In other words, it depends on if the browser is running in a compatible mode. FOr the browser's version, please use iex instead.


iex

public static java.lang.Double iex
Returns the browser's version as double (only the first two part of the version, such as 8) if the browser is Internet Explorer, or null if not.

Notice that this is the browser's version, which might not be the version of DOM API. For DOM API's version, please use ie instead.

Since:
5.0.7

ie6_

public static java.lang.Boolean ie6_
Whether it is Internet Exploer 6 (excluding 7 or others).


ie7

public static java.lang.Boolean ie7
Whether it is Internet Exploer 7 or later.


ie7_

public static java.lang.Boolean ie7_
Whether it is Internet Exploer 7 (excluding 8 or others).


ie8

public static java.lang.Boolean ie8
Whether it is Internet Exploer 8 or later.


ie8c

public static java.lang.Boolean ie8c
Whether it is Internet Exploer 8 or later, and running in Internet Explorer 7 compatible mode.


ie9

public static java.lang.Boolean ie9
Whether it is Internet Exploer 9 or later.

Since:
5.0.5

gecko

public static java.lang.Double gecko
Returns the version as double (only the first two part of the version, such as 3.5) if it is Gecko-based browsers, such as Firefox.


ff

public static java.lang.Double ff
Returns the version as double (only the first two part of the version, such as 3.6) if it is Firefox, such as Firefox. Notice that it is Firefox's version, such as 3.5, 3.6 and 4.0. If not a firefox, it is null.

Since:
5.0.6

safari

public static java.lang.Double safari
Returns the version as double (only the first two part of the version, such as 533.1) if it is Safari-based, or null if not.


opera

public static java.lang.Double opera
Returns the version as double (only the first two part of the version, such as 10.1) if it is Opera, or null if not.


air

public static java.lang.Boolean air
Whether it is Adobe AIR.


css3

public static java.lang.Boolean css3
Whether it supports CSS3.


DECIMAL

public static char DECIMAL
The character used for decimal sign.


GROUPING

public static char GROUPING
The character used for thousands separator.


MINUS

public static char MINUS
The character used to represent minus sign.


PER_MILL

public static char PER_MILL
The character used for mille percent sign.


PERCENT

public static char PERCENT
The character used for percent sign.


alerting

public static boolean alerting
Indicates whether an OS-level modal dialog is opened. In this case, onblur will be called so a widget can use it to decide whether to validate.


spaceless

public static boolean spaceless
Indicates whether Widget.id is always the same as Widget.uuid.

By default, it is false.

You could enable it if the pure-client approach is taken, since it is more convenient. However, it also means the concept of ID space is no longer valid.


keyCapture

public static Widget keyCapture
The widget that captures the keystrokes. Used to specify a widget that shall receive the following the onKeyPress and onKeyUp events, no matter what widget the event occurs on.

doKeyDown_: function () {
 zk.keyCapture = this;
 this.$supers('doKeyDown_', arguments);
}

Notice that the key capture is reset automatically after processing onKeyUp_.

See Also:
mouseCapture

mouseCapture

public static Widget mouseCapture
The widget that captures the mouse events. Used to specify a widget that shall receive the following the onMouseMove and onMouseUp events, no matter what widget the event occurs on.

doMouseDown_: function () {
 zk.mouseCapture = this;
 this.$supers('doMouseDown_', arguments);
}

Notice that the mouse capture is reset automatically after processing onMouseUp_.

See Also:
keyCapture
Method Detail

isClass

public static void isClass(java.lang.Object cls)
Returns if the given JS object is a class (Class).

Parameters:
cls - the object to test whether it is a class (aka., a ZK class)
Since:
5.0.9

isObject

public static void isObject(java.lang.Object o)
Returns whether the given JS object is a ZK object (Object).

Parameters:
o - the object to test whether it is a ZK object
Since:
5.0.9

cut

public static java.lang.Object cut(Map props,
                                   String nm)
Retrieves and removes the value of the specified name of the given map.

Parameters:
props - a map of properties
nm - the name to retrieve the value
Returns:
Object the value.
Since:
5.0.2

$package

public static Package $package(String name)
Defines a package. It creates and returns the package if not defined yet. If the package is already defined, it does nothing but returns the package. It is similar to Java's package statement except it returns the package object.

Notice the package is usually defined automatically by use of $import(String), load(_global_.String, zk.Desktop, _global_.Function)


$import

public static java.lang.Object $import(String name,
                                       Function fn)
Imports a package or class, and load it if fn is specified. It returns null if the package or class is not defined yet and fn is null.

If an additional function, fn is specified, this method assumes name is a class and it will load the package of the class first. If not found. Then, invoke the function after the class is loaded. For example, the following creates a Listbox widget after loading the package.


zk.$import('zul.sel.Listbox', function (cls) {new cls();});

Parameters:
name - The name of the package or the class.
fn - The function to call after the class is loaded. If specified, it assumes name is a class, and it will load the package of the class automatically. In additions, the function is called with the class as the argument.
Returns:
Object a package (Package) or a class (Class)
See Also:
$package(_global_.String), $import(String), load(_global_.String, zk.Desktop, _global_.Function)

$import

public static java.lang.Object $import(String name)
Imports a class or a package. It returns null if the package or class is not defined yet.

Example:


var foo = zk.$import('com.foo');
var cool = new foo.Cool();
var Cool = zk.$import('com.foo.Cooler');
var cooler = new Cooler();

Parameters:
name - The name of the package or the class.
Returns:
Object a package (Package) or a class (Class)
See Also:
$package(_global_.String), load(_global_.String, zk.Desktop, _global_.Function), $import(String, Function)

$extends

public static Class $extends(Class sueprclass,
                             Map members,
                             Map staticMembers)
Defines a class. It returns the class being defined.

Example:


zul.Label = zk.$extends(zk.Widget, {
 _value: '',
 getValue() {
  return this._value;
 },
 setValue(value) {
  this._value = value;
 }
});

$define

To simplify the declaration of the getters and setters, $define is introduced. It is shortcut to invoke define. For example,

foo.Widget = zk.$extends(zk.Widget, {
  _value: '',
  $define: {
    name: null,
    value: null
  },
  bind_: function () {
    //
  }
});

is equivalent to


foo.Widget = zk.$extends(zk.Widget, {
  _value: '',
  bind_: function () {
    //
  }
});
zk.define(foo.Widget, {
    name: null,
    value: null
});

is equivalent to


foo.Widget = zk.$extends(zk.Widget, {
  _value: '',
  getName: function () {
    return this._name;
  },
  setName: function (v) {
    this._name = v;
    return this;
  },
  getValue: function () {
    return this._value;
  },
  setValue: function (v) {
    this._value = v;
    return this;
  },
  bind_: function () {
    //
  }
});

Parameters:
sueprclass - the super class to extend from
members - a map of non-static members
staticMembers - a map of static members. Ignored if omitted.
Returns:
Class the class being defined
See Also:
define(zk.Class, _global_.Map), override(java.lang.Object, _global_.String, java.lang.Object)

$default

public static Map $default(Map opts,
                           Map defaults)
Provides the default values for the specified options.

Example:


process: function (opts, defaultOptions) {
 opts = zk.$default(opts, defaultOptions);
}

opts = zk.$default(opts, {timeout: 100, max: true});
 //timeout and max are assigned to opts only if no such property found in opts

Parameters:
opts - a map of options to which default options will be added If null, an empty map is created automatically.
defaults - a map of default options
Returns:
Map the merged options
See Also:
copy(java.lang.Object, java.lang.Object, _global_.Map)

override

public static java.lang.Object override(java.lang.Object dst,
                                        String nm,
                                        java.lang.Object val)
Overrides a particular method or data member. The old method will be stored in method called $nm (assuming nm is the method name to override. For example,
zk.override(zul.inp.Combobox.prototype, "open",
  function () {
    this.$open.apply(this, arguments);
    //do whatever you want
  });

Parameters:
dst - the destination object to override
nm - the method name to override
val - the value of the method. To override a method, it has to be an instance of Function.
Returns:
Object the destination object
Since:
5.0.2
See Also:
override(Function, Function), override(Object, Map, Map)

override

public static Function override(Function oldfunc,
                                Function newfunc)
Overrides a particular method. The old method will be returned, and the caller could store it for calling back. For example,
var superopen = zk.override(zul.inp.Combobox.prototype.open,
  function () {
    superopen.apply(this, arguments);
    //do whatever you want
  });

Parameters:
oldfunc - the old function that will be replaced
newfunc - the new function that will replace the old function
Returns:
Function the old function (i.e., oldfunc)
Since:
5.0.6
See Also:
override(Object, Map, Map)

override

public static java.lang.Object override(java.lang.Object dst,
                                        Map backup,
                                        Map src)
Overrides the properties of a map. It is similar to copy(java.lang.Object, java.lang.Object, _global_.Map), except
  1. It preserves the original member (method or data) in the backup argument.
  2. It handles the class extensions ($extends(zk.Class, _global_.Map, _global_.Map)) well. For example, the members of all deriving classes will be overriden too, if necessary.

Example,


var _xCombobox = {}
zk.override(zul.inp.Combobox.prototype, _xCombobox, {
        redrawpp_: function (out) {
                if (!_redrawpp(this, out))
                        _xCombobox.redrawpp_.apply(this, arguments); //call the original method
        },
        open: function () {
                _renderpp(this);
                _xCombobox.open.apply(this, arguments); //call the original method
        }
});

Parameters:
dst - the destination object to override
backup - the map used to store the original members (or properties)
src - the source map providing the new members
Returns:
Object the destination object
See Also:
override(Function, Function), override(Object, String, Object)

define

public static Class define(Class klass,
                           Map props)
Defines the setter and getter methods.

Notice that you rarely need to invoke this method directly. Rather, you can specify them in a property named $define, when calling #$extends.

For example, the following code snippet


zk.define(zul.wgt.Button, {
  disabled: null
});
is equivalent to define three methods, isDisabled, getDisabled and setDisabled, as follows:

zul.wgt.Button = zk.$extends(zk.Widget, {
  isDisabled: _zkf = function () {
    return this._disabled;
  },
  isDisabled: _zkf,
  setDisabled: function (v) {
    this._disabled = v;
    return this;
  }
});
If you want to do something when the value is changed in the setter, you can specify a function as the value in the props argument. For example,

zk.define(zul.wgt.Button, {
  disabled: function () {
    if (this.desktop) this.rerender();
  }
});
will cause the setter to be equivalent to

setDisabled: function (v, opts) {
  this._disabled = v;
  if (this._disabled !== v || (opts && opts.force))
    if (this.desktop) this.rerender();
  return this;
}
If you want to pre-process the value, you can specify a two-element array. The first element is the function to pre-process the value, while the second is to post-process if the value is changed, as described above. For example,

zk.define(zul.wgt.Button, {
  disabled: [
        function (v) {
                return v != null && v != false;
        },
        function () {
            if (this.desktop) this.rerender();
        }
  ]
});
will cause the setter to equivalent to

setDisabled: function (v) {
  v = v != null && v != false;
  this._disabled = v;
  if (this._disabled !== v || (opts && opts.force))
    if (this.desktop) this.rerender();
  return this;
}
Notice that when the function (specified in props) is called, the arguments are the same as the arguments passed to the setter (including additional arguments. For example, if button.setDisabled(true, false) is called, then the specified function is called with two arguments, true and false. In additions, as shown above, you can enforce the invocation of the function by passing a map with force as true.

wgt.setSomething(somevalue, {force:true});

Parameters:
klass - the class to define the members
props - the map of members (aka., properties)
Returns:
Class the class being defined
See Also:
$extends(zk.Class, _global_.Map, _global_.Map)

$void

public static void $void()
A does-nothing-but-returns-false function.


parseInt

public static int parseInt(String v,
                           int b)
Parses a string to an integer.

It is the same as the built-in parseInt method except it never return NaN (rather, it returns 0).

Parameters:
v - the text to parse
b - represent the base of the number in the string. 10 is assumed if omitted.
Returns:
int the integer

parseFloat

public static double parseFloat(String v)
Parses a string to a floating number.

It is the same as the built-in parseFloat method except it never return NaN (rather, it returns 0).

Parameters:
v - the text to parse
Returns:
double the floating number
Since:
5.0.2

set

public static java.lang.Object set(java.lang.Object dst,
                                   java.lang.Object src,
                                   Array props,
                                   boolean ignoreUndefined)
Sets the given properties from one object to another. Example:

zk.set(dst, src, ["foo", "mike"]);
If dst has a method called setFoo and src has method called getMike, then it is equivalent to

        dst.setFoo("foo", src["foo"]);
        dst["mike"] = src.getMike();

Parameters:
dst - the destination object to copy properties to
src - the source object to copy properties from
props - an array of property names (String)
ignoreUndefined - whether to ignore undefined. Optional (if not specified, false is assumed). If true and src[name] is undefined, then dst[name] won't be assigned.
Returns:
Object the destination object
Since:
5.0.3
See Also:
copy(java.lang.Object, java.lang.Object, _global_.Map)

set

public static java.lang.Object set(java.lang.Object o,
                                   String name,
                                   java.lang.Object value,
                                   java.lang.Object extra)
Assigns a value to the specified property.

For example, zk.set(obj, "x", 123):
If setX is defined in obj, obj.setX(123) is called. If not defined, obj.x = 123 is called.

Anotehr example:


zk.set(o, 'value', true); //set a single property

Parameters:
o - the object to assign values to
name - the property's name
value - the property's value
extra - an extra argument to pass to the setX method as the extra argument (the second argument). For example, zk.set(obj, 'x', 123, true) invokes obj.setX(123, true).
Returns:
Object the destination object
See Also:
get(java.lang.Object, _global_.String)

get

public static java.lang.Object get(java.lang.Object o,
                                   String name)
Retrieves a value from the specified property.

For example, zk.get(obj, "x"):
If getX or isX is defined in obj, obj.isX() or obj.getX() is returned. If not defined, obj.x is returned.

Another example:


zk.get(o, 'value');

Parameters:
o - the object to retreive value from
name - the name
Returns:
Object the value of the property

startProcessing

public static void startProcessing(int timeout)
Set a flag, processing, to indicate that it starts a processing. It also shows a message to indicate "processing" after the specified timeout.

Example:


zk.startProcessing(1000);
//do the lengthy operation
zk.endProcessing();

Parameters:
timeout - the delay before showing a message to indicate "processing".
See Also:
processing, endProcessing()

endProcessing

public static void endProcessing()
Clears a flag, processing, to indicate that it the processing has done. It also removes a message, if any, that indicates "processing".

Example:


zk.startProcessing(1000);
//do the lengthy operation
zk.endProcessing();

See Also:
startProcessing(int)

disableESC

public static void disableESC()
Disable the default behavior of ESC. In other words, after called, the user cannot abort the loading from the server.

To enable ESC, you have to invoke enableESC() and the number of invocations shall be the same.

See Also:
enableESC()

enableESC

public static void enableESC()
Enables the default behavior of ESC (i.e., stop loading from the server).

See Also:
disableESC()

error

public static void error(String msg)
Display an error message to indicate an error. Example:
zk.error('Oops! Something wrong:(');

Parameters:
msg - the error message
See Also:
errorDismiss(), log(java.lang.Object...), stamp(String, boolean)

errorDismiss

public static void errorDismiss()
Closes all error messages shown by error(_global_.String). Example:
zk.errorDismiss();

See Also:
error(_global_.String)

log

public static void log(java.lang.Object... detailed)
Logs an message for debugging purpose. Example:

zk.log('reach here');
zk.log('value is", value);

Parameters:
detailed - varient number of arguments to log
See Also:
stamp(String, boolean)

stamp

public static void stamp()
Logs the information of all stamps made by stamp(String, boolean). After the invocation, all stamps are reset.


stamp

public static void stamp(String name,
                         boolean noAutoLog)
Make a time stamp for this momemt; used for performance tuning. A time stamp is represented by a name. It is an easy way to measure the performance. At the end of executions, the time spent between any two stamps (including beginning and ending) will be logged (with log(java.lang.Object...)).

Parameters:
name - the unique name to represent a time stamp
noAutoLog - whehter not to auto log the result. If omitted or false, stamp() will be invoked automatically to log the info and clean up all stamps after mounting is completed. Turn it off, if you prefer to invoke it manually.

ajaxURI

public static String ajaxURI(String uri,
                             Map opts)
Encodes and returns the URI to communicate with the server. Example:
document.createElement("script").src = zk.ajaxURI('/web/js/com/foo/mine.js',{au:true});

Parameters:
uri - - the URI related to the AU engine. If null, the base URI is returned.
opts - [optinal] the options. Allowed values:
  • au - whether to generate an URI for accessing the ZK update engine. If not specified, it is used to generate an URL to access any servlet
  • desktop - the desktop or its ID. If null, the first desktop is used.
  • ignoreSession - whether to handle the session ID in the base URI.
Returns:
String the encoded URI

stateless

public static Desktop stateless(String dtid,
                                String contextURI,
                                String updateURI,
                                String reqURI)
Declares the desktop is used for the stateless context. By stateless we mean the server doesn't maintain any widget at all.

Parameters:
dtid - the ID of the desktop to create
contextURI - the context URI, such as /zkdemo
updateURI - the update URI, such as /zkdemo/zkau
reqURI - the URI of the request path.
Returns:
Desktop the stateless desktop being created

classes

public static void classes()
A map of all classes, Map.

Since:
5.0.8

copy

public static java.lang.Object copy(java.lang.Object dst,
                                    java.lang.Object src,
                                    Map backup)
Copies a map of properties (or options) from one object to another and copies the original value to another map. Example: copy style and restore back

var backup = {};
zk.copy(n.style, {
        visibility: 'hidden',
        position: 'absolute',
        display: 'block'
        }, backup);
try {
        //do whatever
} finally {
        zk.copy(n.style, backup);
}

Notice that copy(java.lang.Object, java.lang.Object, _global_.Map) copies the properties directly regardless if the target object has a setter or not. It is fast but if you want to go thru the setter, if any, use set(Object, Object, Array, boolean) instead.

Parameters:
dst - the destination object to copy properties to
src - the source object to copy properties from
backup - the map to stor the original value
Returns:
Object the destination object
Since:
5.0.3

copy

public static java.lang.Object copy(java.lang.Object dst,
                                    java.lang.Object src)
Copies a map of properties (or options) from one object to another. Example: extending Array

zk.copy(Array.prototoype, {
 $addAll: function (o) {
  return this.push.apply(this, o);
 }
});

Notice that copy(java.lang.Object, java.lang.Object, _global_.Map) copies the properties directly regardless if the target object has a setter or not. It is fast but if you want to go thru the setter, if any, use set(Object, Object, Array, boolean) instead.

Parameters:
dst - the destination object to copy properties to
src - the source object to copy properties from
Returns:
Object the destination object

animating

public static boolean animating()
Returns whether there is some animation taking place. If you'd like to have a function to be called only when no animation is taking place (such as waiting for sliding down to be completed), you could use afterMount(_global_.Function, int).

Returns:
boolean
See Also:
afterAnimate(_global_.Function, int)

afterAnimate

public static boolean afterAnimate(Function fn,
                                   int delay)
Executes a function only when no animation is taking place. If there is some animation, the specified function will be queued and invoked after the animation is done.

If the delay argument is not specified and no animation is taking place, the function is executed with setTimeout(fn, 0).

Parameters:
fn - the function to execute
delay - how many milliseconds to wait before execute if there is no animation is taking place. If omitted, 0 is assumed. If negative, the function is executed immediately.
Returns:
boolean true if this method has been called before return (delay must be negative, and no animation); otherwise, undefined is returned.
Since:
5.0.6
See Also:
animating()

isLoaded

public static boolean isLoaded(String pkg,
                               boolean loading)
Tests if a package is loaded (or being loaded).

Parameters:
pkg - the package name
loading - [Optional; default: false] If true is specified, this method returns true if the package is loaded or being loaded. If false or omitted, it returns true only if the package is loaded.
Returns:
boolean true if loaded
See Also:
load(_global_.String, zk.Desktop, _global_.Function)

load

public static boolean load(String pkg,
                           Desktop dt,
                           Function func)
Loads the specified package(s). This method is called automatically when mounting the peer widgets. However, if an application developer wants to access JavaScript packages that are not loaded, he has to invoke this method.

The loading of a package is asynchronous, so you cannot create the widget immediately. Rather, use the func argument, func, or use #afterLoad to execute.

Parameters:
pkg - the package name
dt - [optional] the desktop used to get URI of the JavaScript file (ajaxURI(_global_.String, _global_.Map)). If null, the first desktop is assumed.
func - [optional] the function to execute after all packages are loaded. Ignored if omitted. Notice that func won't be executed until all requested packages are loaded; not just what are specified here.
Returns:
boolean true if all required packages are loaded
See Also:
load(String, Function)

load

public static boolean load(String pkg,
                           Function func)
Loads the specified package(s). This method is called automatically when mounting the peer widgets. However, if an application developer wants to access JavaScript packages that are not loaded, he has to invoke this method.

The loading of a package is asynchronous, so you cannot create the widget immediately. Rather, use the func argument, func, or use #afterLoad to execute.


zk.load('zul.utl', function () {
  new zul.utl.Timer();
});

Parameters:
pkg - the package name
func - [optional] the function to execute after all packages are loaded. Ignored if omitted. Notice that func won't be executed until all requested packages are loaded; not just what are specified here.
Returns:
boolean true if all required packages are loaded

loadScript

public static zk loadScript(String src,
                            String name,
                            String charset)
Loads a JavaScript file.

Parameters:
src - the URL of the JavaScript file.
name - the name to shown up in the progressing dialog. Specify a non-empty string if you want ZK not to create widgets until this file is loaded. Ignored if not specified or null. If you specify a name here, you have to call setScriptLoaded(_global_.String) when the script is loaded. Otherwise, @{link zk#loading} won't be zero and ZK Client Engine is halted.
charset - the charset. UTF-8 is assumed if null.
Returns:
zk

getVersion

public static String getVersion(String pkg)
Returns the version of the specified package, or null if not available.

Parameters:
pkg - the package name
Returns:
String the version

setVersion

public static void setVersion(String pkg,
                              String ver)
Sets the version of the specified package.

Parameters:
pkg - the package name
ver - the version

depends

public static void depends(String a,
                           String b)
Declare a package that must be loaded when loading another package.

Notice that it doesn't guarantee the loading order of the two packages. Thus, it is better to do in #afterLoad if a code snippet depends on both packages.

Parameters:
a - the name of the package that depends another package. In other words, calling #loading against this package will cause dependedPkgnn being loaded.
b - the name of the package that shall be loaded if another package is being loaded. In other words, it reads "a depends on b".
See Also:
afterLoad(_global_.String, _global_.Function)

afterLoad

public static void afterLoad(String pkgs,
                             Function func)
Declares a function that shall be executed only if the specified package(s) are loaded (and loading is 0). Notice that it won't cause the package(s) to execute. Rather, it defers the execution of the specified function until someone else loads the package (by use of load(_global_.String, zk.Desktop, _global_.Function)).

See also JavaScript Packaging

To know whether all requested packages are loaded (i.e., ZK is not loading any package), you can check loading if it is 0.

Notice that functions specified in the second format execute before those specified in the first format.

Example


zk.afterLoad('foo', function() {new foo.Foo();});
zk.afterLoad('foo1,foo2', function() {new foo1.Foo(foo2.Foo);});
zk.afterLoad(function() {});

Parameters:
pkgs - the package(s) that the specified function depends on. In other words, the function is evaluated only if the package(s) are loaded. If you want to specify multiple packages, separate them with comma.
func - the function to execute
See Also:
afterLoad(Function), depends(_global_.String, _global_.String), load(_global_.String, zk.Desktop, _global_.Function)

afterLoad

public static boolean afterLoad(Function func)
Declares a function that shall be executed after all requested packages are loaded (i.e., loading is 0). If all packages has been loaded, the function is executed immediately and this method returns true.

Parameters:
func - the function to execute
Returns:
boolean whether func has been executed
See Also:
afterLoad(String, Function), depends(_global_.String, _global_.String), load(_global_.String, zk.Desktop, _global_.Function)

getHost

public static String getHost(String pkg,
                             boolean js)
Returns the URI of the server (so called host) for the specified package.

ZK Client Engine loads the packages from the same server that returns the HTML page. If a package might be loaded from a different server, you can invoke #setHost to specify it and then #getHost will return the correct URL for the specified package.

Parameters:
pkg - the package name
js - whether the returned URL is used to load the JavaScript file. load(_global_.String, zk.Desktop, _global_.Function) will pass true to this argument to indicate the URI is used to load the JavaScript file. However, if you just want the URL to send the request back (such as json-p with jQuery's json), don't pass anything (or pass false) to this argument.
Returns:
String the URI
See Also:
setHost(_global_.String, _global_.String, _global_.Array)

setHost

public static void setHost(String host,
                           String updURI,
                           Array pkgs)
Defines the URL of the host for serving the specified packages.

Parameters:
host - the host, such as http://www.zkoss.org.
updURI - the update URI, such as /zkdemo/zkau, that is used to load the JavaScript files
pkgs - an array of pckage names (String)
See Also:
getHost(_global_.String, boolean)

setScriptLoaded

public static void setScriptLoaded(String name)
Notify ZK that the name of the JavaScript file is loaded. This method is designed to be used with loadScript(_global_.String, _global_.String, _global_.String), such that ZK Client knows if a JavaScript file is loaded.

Parameters:
name - the name of the JavaScript file. It must be the same as the one passed to loadScript(_global_.String, _global_.String, _global_.String).

beforeUnload

public static void beforeUnload(Function fn,
                                Map opts)
Adds a function that will be executed when the browser is about to unload the document. In other words, it is called when window.onbeforeunload is called.

To remove the function, invoke this method by specifying remove to the opts argument.

zk.beforeUnload(fn, {remove: true});

Parameters:
fn - the function to execute. The function shall return null if it is OK to close, or a message (String) if it wants to show it to the end user for confirmation.
opts - [optional] a map of options. Allowed vlaues:
  • remove: whether to remove instead of add.

afterMount

public static boolean afterMount(Function fn,
                                 int delay)
Adds a function that will be executed after the mounting is done. By mounting we mean the creation of peer widgets.

By mounting we mean the creation of the peer widgets under the control of the server. To run after the mounting of the peer widgets,

If the delay argument is not specified and no mounting is taking place, the function is executed with setTimeout(fn, 0).

Parameters:
fn - the function to execute after mounted
delay - (since 5.0.6) how many milliseconds to wait before execute if there is no mounting taking place. If omitted, 0 is assumed. If negative, the function is executed immediately (if no mounting is taking place).
Returns:
boolean true if this method has been called before return (delay must be negative, and no mounting); otherwise, undefined is returned.
See Also:
mounting, afterLoad(_global_.String, _global_.Function), afterAnimate(_global_.Function, int)

afterResize

public static void afterResize(Function fn)
Adds a function that will be executed after all of the onSize events are done.

Here lists the execution phases:

  1. After the page loaded, the function added in the afterResze() will be invoked
  2. After the browser resized, the function added in the afterResze() will be invoked
  3. After zWatch.fire/fireDown('onSize'), the function added in the afterResze() will be invoked

Parameters:
fn - the function to execute after resized
Since:
6.5.2


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo