org.zkoss.zk.ui.event
Class Events

java.lang.Object
  extended by org.zkoss.zk.ui.event.Events

public class Events
extends java.lang.Object

Utilities to handle events.

Author:
tomyeh

Field Summary
static java.lang.String ON_AFTER_SIZE
          The onAfterSize event (used with AfterSizeEvent).
static java.lang.String ON_BLUR
          The onBlur event (used with Event).
static java.lang.String ON_BOOKMARK_CHANGE
          The onBookmarkChange event (used with BookmarkEvent) to notify that user pressed BACK, FORWARD or specified URL directly that causes the bookmark is changed (but still in the same desktop).
static java.lang.String ON_CANCEL
          The onCancel event (used with KeyEvent).
static java.lang.String ON_CHANGE
          The onChange event (used with InputEvent).
static java.lang.String ON_CHANGING
          The onChanging event (used with InputEvent).
static java.lang.String ON_CHECK
          The onCheck event (used with CheckEvent).
static java.lang.String ON_CLICK
          The onClick event (used with MouseEvent).
static java.lang.String ON_CLIENT_INFO
          The onClientInfo event (used with ClientInfoEvent).
static java.lang.String ON_CLOSE
          The onClose event (used with Event) used to denote the close button is pressed.
static java.lang.String ON_CREATE
          The onCreate event (used with CreateEvent) to notify a component that it (and its children) has been created by ZK's evaluating a ZUML page.
static java.lang.String ON_CTRL_KEY
          The onCtrlKey event (used with KeyEvent).
static java.lang.String ON_DESKTOP_RECYCLE
          The onDesktopRecycle event (used with Event) to notify that a desktop has been recycled.
static java.lang.String ON_DOUBLE_CLICK
          The onDoubleClick event (used with MouseEvent).
static java.lang.String ON_DROP
          The onDrop event (used with DropEvent).
static java.lang.String ON_ERROR
          The onError event (used with ErrorEvent).
static java.lang.String ON_FOCUS
          The onFocus event (used with Event).
static java.lang.String ON_FULFILL
          The onFulfill event (used with FulfillEvent) to denote a fulfill condition has been applied.
static java.lang.String ON_GROUP
          The onGroup event (used with Event) to notify a request for grouping.
static java.lang.String ON_MAXIMIZE
          The onMaximize event (used with MaximizeEvent).
static java.lang.String ON_MINIMIZE
          The onMinimize event (used with MinimizeEvent).
static java.lang.String ON_MODAL
          The onModal event (used with Event) to notify a component shall become modal.
static java.lang.String ON_MOUSE_OUT
          The onMouseOut event (used with MouseEvent).
static java.lang.String ON_MOUSE_OVER
          The onMouseOver event (used with MouseEvent).
static java.lang.String ON_MOVE
          The onMove event (used with MoveEvent).
static java.lang.String ON_NOTIFY
          The onNotify event (used with Event).
static java.lang.String ON_OK
          The onOK event (used with KeyEvent).
static java.lang.String ON_OPEN
          The onOpen event (used with OpenEvent).
static java.lang.String ON_PIGGYBACK
          The onPiggyback event (used with Event) used to notify a root component that the client has sent a request to the server.
static java.lang.String ON_RENDER
          The onRender request.
static java.lang.String ON_RIGHT_CLICK
          The onRightClick event (used with MouseEvent).
static java.lang.String ON_SCROLL
          The onScroll event (used with ScrollEvent).
static java.lang.String ON_SCROLLING
          The onScrolling event (used with ScrollEvent).
static java.lang.String ON_SELECT
          The onSelect event (used with SelectEvent).
static java.lang.String ON_SELECTION
          The onSelection event (used with SelectionEvent).
static java.lang.String ON_SIZE
          The onSize event (used with SizeEvent).
static java.lang.String ON_SORT
          The onSort event (used with Event) to notify a request for sorting.
static java.lang.String ON_STUB
          The onStub event (used with StubEvent) to denote an event sent from the peer widget of a stub component (at the client).
static java.lang.String ON_SWIPE
          The onSwipe event (used with SwipeEvent).
static java.lang.String ON_TIMER
          The onTimer event (used with Event).
static java.lang.String ON_UNGROUP
          The onUngroup event (used with Event) to notify a request for ungrouping.
static java.lang.String ON_UPLOAD
          The onUpload event (used with UploadEvent.
static java.lang.String ON_URI_CHANGE
          The onURIChange event (used with URIEvent) to notify that the associated URI of a component is changed.
static java.lang.String ON_USER
          The onUser event.
static java.lang.String ON_VISIBILITY_CHANGE
          The onVisibilityChange event (used with VisibilityChangeEvent).
static java.lang.String ON_Z_INDEX
          The onZIndex event (used with ZIndexEvent).
 
Method Summary
static void addEventListeners(Component comp, java.lang.Object controller)
          Add onXxx event handler defined in controller object to the specified component.
static void echoEvent(Event event)
          Echos an event.
static void echoEvent(java.lang.String name, Component target, java.lang.Object data)
          Echos an event.
static void echoEvent(java.lang.String name, Component target, java.lang.String data)
          Echos an event.
static Event getRealOrigin(ForwardEvent event)
          Returns the real origin event of a forwarded event.
static boolean inEventListener()
          Returns whether the current thread is an event listener.
static boolean isListened(Component comp, java.lang.String evtnm, boolean asap)
          Returns whether an event handler or listener is available for the specified component and event.
static boolean isValid(java.lang.String name)
          Returns whether an event name is valid.
static void postEvent(Component realTarget, Event event)
          Queues the give event for the specified target to this execution.
static void postEvent(Event event)
          Posts an event to the current execution.
static void postEvent(int priority, Component realTarget, Event event)
          Queues the give event for the specified target to this execution.
static void postEvent(int priority, Event event)
          Posts an event to the current execution with the specified priority.
static void postEvent(int priority, java.lang.String name, Component target, java.lang.Object data)
          Posts an instance of Event to the current execution with the specified priority.
static void postEvent(java.lang.String name, Component target, java.lang.Object data)
          Posts an instance of Event to the current execution.
static void sendEvent(Component comp, Event event)
          Sends the event to the specified component and process it immediately.
static void sendEvent(Event event)
          Sends the event to the target specified in the event, and processes it immediately.
static void sendEvent(java.lang.String name, Component target, java.lang.Object data)
          Sends the event to the target, and processes it immediately.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ON_CLICK

public static final java.lang.String ON_CLICK
The onClick event (used with MouseEvent).

See Also:
Constant Field Values

ON_RIGHT_CLICK

public static final java.lang.String ON_RIGHT_CLICK
The onRightClick event (used with MouseEvent).

See Also:
Constant Field Values

ON_DOUBLE_CLICK

public static final java.lang.String ON_DOUBLE_CLICK
The onDoubleClick event (used with MouseEvent).

See Also:
Constant Field Values

ON_MOUSE_OVER

public static final java.lang.String ON_MOUSE_OVER
The onMouseOver event (used with MouseEvent).

Notice, if Internet connection is too far, the user might already move the mouse out of a widget when the server receives onMouseOver.

Since:
5.0.3
See Also:
Constant Field Values

ON_MOUSE_OUT

public static final java.lang.String ON_MOUSE_OUT
The onMouseOut event (used with MouseEvent).

Since:
5.0.3
See Also:
Constant Field Values

ON_OK

public static final java.lang.String ON_OK
The onOK event (used with KeyEvent).

See Also:
Constant Field Values

ON_CANCEL

public static final java.lang.String ON_CANCEL
The onCancel event (used with KeyEvent).

See Also:
Constant Field Values

ON_CTRL_KEY

public static final java.lang.String ON_CTRL_KEY
The onCtrlKey event (used with KeyEvent).

See Also:
Constant Field Values

ON_CHANGE

public static final java.lang.String ON_CHANGE
The onChange event (used with InputEvent).

See Also:
Constant Field Values

ON_CHANGING

public static final java.lang.String ON_CHANGING
The onChanging event (used with InputEvent).

See Also:
Constant Field Values

ON_ERROR

public static final java.lang.String ON_ERROR
The onError event (used with ErrorEvent).

See Also:
Constant Field Values

ON_SCROLL

public static final java.lang.String ON_SCROLL
The onScroll event (used with ScrollEvent).

See Also:
Constant Field Values

ON_SCROLLING

public static final java.lang.String ON_SCROLLING
The onScrolling event (used with ScrollEvent).

See Also:
Constant Field Values

ON_SWIPE

public static final java.lang.String ON_SWIPE
The onSwipe event (used with SwipeEvent).

Since:
6.5.0
See Also:
Constant Field Values

ON_SELECT

public static final java.lang.String ON_SELECT
The onSelect event (used with SelectEvent).

See Also:
Constant Field Values

ON_SELECTION

public static final java.lang.String ON_SELECTION
The onSelection event (used with SelectionEvent).

See Also:
Constant Field Values

ON_CHECK

public static final java.lang.String ON_CHECK
The onCheck event (used with CheckEvent).

See Also:
Constant Field Values

ON_MOVE

public static final java.lang.String ON_MOVE
The onMove event (used with MoveEvent).

See Also:
Constant Field Values

ON_SIZE

public static final java.lang.String ON_SIZE
The onSize event (used with SizeEvent).

See Also:
Constant Field Values

ON_AFTER_SIZE

public static final java.lang.String ON_AFTER_SIZE
The onAfterSize event (used with AfterSizeEvent).

Since:
6.5.2
See Also:
Constant Field Values

ON_Z_INDEX

public static final java.lang.String ON_Z_INDEX
The onZIndex event (used with ZIndexEvent).

See Also:
Constant Field Values

ON_OPEN

public static final java.lang.String ON_OPEN
The onOpen event (used with OpenEvent).

See Also:
Constant Field Values

ON_CLOSE

public static final java.lang.String ON_CLOSE
The onClose event (used with Event) used to denote the close button is pressed.

See Also:
Constant Field Values

ON_RENDER

public static final java.lang.String ON_RENDER
The onRender request. There is no event associated with this AU request.

See Also:
Constant Field Values

ON_TIMER

public static final java.lang.String ON_TIMER
The onTimer event (used with Event). Sent when a timer is up.

See Also:
Constant Field Values

ON_FOCUS

public static final java.lang.String ON_FOCUS
The onFocus event (used with Event). Sent when a component gets a focus.

See Also:
Constant Field Values

ON_BLUR

public static final java.lang.String ON_BLUR
The onBlur event (used with Event). Sent when a component loses a focus.

See Also:
Constant Field Values

ON_DROP

public static final java.lang.String ON_DROP
The onDrop event (used with DropEvent). Sent when a component is dragged and drop to another.

See Also:
Constant Field Values

ON_NOTIFY

public static final java.lang.String ON_NOTIFY
The onNotify event (used with Event). It is not used by any component, but it is, rather, designed to let users add customized events.

See Also:
Constant Field Values

ON_SORT

public static final java.lang.String ON_SORT
The onSort event (used with Event) to notify a request for sorting.

See Also:
Constant Field Values

ON_GROUP

public static final java.lang.String ON_GROUP
The onGroup event (used with Event) to notify a request for grouping.

Since:
5.0.0
See Also:
Constant Field Values

ON_UNGROUP

public static final java.lang.String ON_UNGROUP
The onUngroup event (used with Event) to notify a request for ungrouping.

Since:
6.5.0
See Also:
Constant Field Values

ON_UPLOAD

public static final java.lang.String ON_UPLOAD
The onUpload event (used with UploadEvent.

See Also:
Constant Field Values

ON_BOOKMARK_CHANGE

public static final java.lang.String ON_BOOKMARK_CHANGE
The onBookmarkChange event (used with BookmarkEvent) to notify that user pressed BACK, FORWARD or specified URL directly that causes the bookmark is changed (but still in the same desktop).

All root components of all pages of the desktop will receive this event.

Since:
3.0.8
See Also:
Constant Field Values

ON_URI_CHANGE

public static final java.lang.String ON_URI_CHANGE
The onURIChange event (used with URIEvent) to notify that the associated URI of a component is changed. Currently only the iframe component supports this event.

Since:
3.5.0
See Also:
Constant Field Values

ON_CLIENT_INFO

public static final java.lang.String ON_CLIENT_INFO
The onClientInfo event (used with ClientInfoEvent).

See Also:
Constant Field Values

ON_VISIBILITY_CHANGE

public static final java.lang.String ON_VISIBILITY_CHANGE
The onVisibilityChange event (used with VisibilityChangeEvent). Only for browsers that support HTML 5 Page Visibility API

Since:
6.5.1
See Also:
Constant Field Values

ON_CREATE

public static final java.lang.String ON_CREATE
The onCreate event (used with CreateEvent) to notify a component that it (and its children) has been created by ZK's evaluating a ZUML page.

See Also:
Constant Field Values

ON_MODAL

public static final java.lang.String ON_MODAL
The onModal event (used with Event) to notify a component shall become modal. Currently, only ZUL's window components support it.

Notice that it is not fired if the event thread is disabled (default).

See Also:
Constant Field Values

ON_PIGGYBACK

public static final java.lang.String ON_PIGGYBACK
The onPiggyback event (used with Event) used to notify a root component that the client has sent a request to the server. It is meaningful only if it is registered to the root component. Once registered, it is called each time the client sends a request to the server. The onPiggyback's event listener is processed after all other events are processed.

The onPiggyback event is designed to let developers piggyback the least-emergent UI updates to the client.

Since:
2.4.0
See Also:
Constant Field Values

ON_USER

public static final java.lang.String ON_USER
The onUser event. It is a generic event that an application developer might send from the client. ZK doesn't use this event.

See Also:
Constant Field Values

ON_MINIMIZE

public static final java.lang.String ON_MINIMIZE
The onMinimize event (used with MinimizeEvent).

Since:
3.5.0
See Also:
Constant Field Values

ON_MAXIMIZE

public static final java.lang.String ON_MAXIMIZE
The onMaximize event (used with MaximizeEvent).

Since:
3.5.0
See Also:
Constant Field Values

ON_FULFILL

public static final java.lang.String ON_FULFILL
The onFulfill event (used with FulfillEvent) to denote a fulfill condition has been applied. Developer usually listens to this event to process the new created children. For example, you might invoke Components.wireFellows(org.zkoss.zk.ui.IdSpace, java.lang.Object) to process these new components.

Since:
3.0.8
See Also:
Constant Field Values

ON_STUB

public static final java.lang.String ON_STUB
The onStub event (used with StubEvent) to denote an event sent from the peer widget of a stub component (at the client).

Since:
6.0.0
See Also:
Constant Field Values

ON_DESKTOP_RECYCLE

public static final java.lang.String ON_DESKTOP_RECYCLE
The onDesktopRecycle event (used with Event) to notify that a desktop has been recycled. All top-level components will receive this event when recycled.

Refer to DesktopRecycle for desktop recycling.

Since:
5.0.2
See Also:
Constant Field Values
Method Detail

isValid

public static final boolean isValid(java.lang.String name)
Returns whether an event name is valid.

The event name must start with on and the third character must be upper case.


inEventListener

public static final boolean inEventListener()
Returns whether the current thread is an event listener.


isListened

public static boolean isListened(Component comp,
                                 java.lang.String evtnm,
                                 boolean asap)
Returns whether an event handler or listener is available for the specified component and event.

A event handler is either a public method named onXxx or a ZUL attribute named onXxx, where onXxx is the event name. A event listener is EventListener being added by Component.addEventListener(int, java.lang.String, org.zkoss.zk.ui.event.EventListener) and Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener).

Unlike Component.isListenerAvailable(java.lang.String, boolean), which checks only the event listener, this method check both event handlers and listeners, i.e., the onXxx members defined in ZUML, the onXxx method defined in the implementation class, and the event listener registered.

Parameters:
asap - whether to check only non-deferrable listener, i.e., not implementing Deferrable, or Deferrable.isDeferrable() is false.
See Also:
Deferrable, Component.isListenerAvailable(java.lang.String, boolean)

sendEvent

public static void sendEvent(Component comp,
                             Event event)
Sends the event to the specified component and process it immediately. This method can only be called when processing an event. It is OK to send event to component from another page as long as they are in the same desktop.


sendEvent

public static void sendEvent(Event event)
Sends the event to the target specified in the event, and processes it immediately.

Note: Event.getTarget() cannot be null.


sendEvent

public static void sendEvent(java.lang.String name,
                             Component target,
                             java.lang.Object data)
Sends the event to the target, and processes it immediately.

Parameters:
target - the target of the event (never null)
Since:
5.0.4

postEvent

public static final void postEvent(Event event)
Posts an event to the current execution.

The priority of the event is assumed to be 0. Refer to postEvent(int, Event).

On the other hand, the event sent by sendEvent(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is processed immediately without posting it to the queue.

Note: if the target of an event is not attached to the page yet, the event is ignored silently.

See Also:
sendEvent(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), echoEvent(String, Component, Object), postEvent(int, Event)

postEvent

public static final void postEvent(java.lang.String name,
                                   Component target,
                                   java.lang.Object data)
Posts an instance of Event to the current execution.

The priority of the event is assumed to be 0. Refer to postEvent(int, String, Component, Object).

See Also:
postEvent(Event), postEvent(int, String, Component, Object)

postEvent

public static final void postEvent(int priority,
                                   Event event)
Posts an event to the current execution with the specified priority.

The posted events are processed from the higher priority to the lower one. If two events are posted with the same priority, the earlier the event being posted is processed earlier (first-in-first-out).

Parameters:
priority - the priority of the event. The higher the priority is, the earlier it is handled.
The priority posted by postEvent(Event) is 0. Applications shall not use the priority higher than 10,000 and lower than -10,000 since they are reserved for component development.
Since:
3.0.7

postEvent

public static final void postEvent(int priority,
                                   Component realTarget,
                                   Event event)
Queues the give event for the specified target to this execution. The target could be different from Event.getTarget().

Parameters:
priority - the priority of the event. The default priority is 0 and the higher value means higher priority.
realTarget - the target component that will receive the event. If null, it means broadcast, i.e., all root components will receive this event.
Notice that postEvent(n, event) is the same as postEvent(n, event.getTarget(), event), but different from postEvent(n, 0, event).
Since:
5.0.7

postEvent

public static final void postEvent(Component realTarget,
                                   Event event)
Queues the give event for the specified target to this execution. The target could be different from Event.getTarget().

Parameters:
realTarget - the target component that will receive the event. If null, it means broadcast, i.e., all root components will receive this event.
Notice that postEvent(n, event) is the same as postEvent(n, event.getTarget(), event), but different from postEvent(n, 0, event).
Since:
5.0.7

postEvent

public static final void postEvent(int priority,
                                   java.lang.String name,
                                   Component target,
                                   java.lang.Object data)
Posts an instance of Event to the current execution with the specified priority.

The posted events are processed from the higher priority to the lower one. If two events are posted with the same priority, the earlier the event being posted is processed earlier (first-in-first-out).

The priority posted by posted by postEvent(Event) is 0. Applications shall not use the priority higher than 10,000 and lower than -10,000 since they are reserved for component development.

Parameters:
priority - the priority of the event.
Since:
3.0.7

echoEvent

public static final void echoEvent(java.lang.String name,
                                   Component target,
                                   java.lang.String data)
Echos an event. By echo we mean the event is fired after the client receives the AU responses and then echoes back. In other words, the event won't be processed in the current execution. Rather, it executes after the client receives the AU responses and then echoes back the event back.

It is usually if you want to prompt the user before doing a long operation. A typical case is to open a highlighted window to prevent the user from clicking any button before the operation gets done.

It is the same as echoEvent(name, target, (Object)data).

Parameters:
name - the event name, such as onSomething
target - the component to receive the event (never null).
data - the extra information, or null if not available. It will become Event.getData().
Since:
3.0.2
See Also:
sendEvent(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), echoEvent(String, Component, Object)

echoEvent

public static final void echoEvent(Event event)
Echos an event. By echo we mean the event is fired after the client receives the AU responses and then echoes back. In other words, the event won't be processed in the current execution. Rather, it executes after the client receives the AU responses and then echoes back the event back.

It is usually if you want to prompt the user before doing a long operation. A typical case is to open a highlighted window to prevent the user from clicking any button before the operation gets done.

Since:
5.0.4
See Also:
sendEvent(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event)

echoEvent

public static final void echoEvent(java.lang.String name,
                                   Component target,
                                   java.lang.Object data)
Echos an event. By echo we mean the event is fired after the client receives the AU responses and then echoes back. In other words, the event won't be processed in the current execution. Rather, it executes after the client receives the AU responses and then echoes back the event back.

It is usually if you want to prompt the user before doing a long operation. A typical case is to open a highlighted window to prevent the user from clicking any button before the operation gets done.

Parameters:
name - the event name, such as onSomething
target - the component to receive the event (never null).
data - the extra information, or null if not available. It will become Event.getData().
Since:
5.0.4
See Also:
sendEvent(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event)

addEventListeners

public static final void addEventListeners(Component comp,
                                           java.lang.Object controller)

Add onXxx event handler defined in controller object to the specified component. The controller is a POJO file with onXxx methods(the event handler codes). This utility method registers these onXxx events to the specified component so you don't have to implement and add EventListener into the component one by one.

All public methods whose names start with "on" in controller object are considered as event handlers and the corresponding event is listened. For example, if the controller object has a method named onOK, then the onOK event is listened and the onOK method is called when the event is received.

Since 3.0.8, this method treats ForwardEvent specially. If the event argument going to be passed into the onXxx event listener is a ForwardEvent and the onXxx event listener defined in the controller specifies a specific event class as its parameter rather than generic Event or ForwardEvent class, then this method will unwrap the ForwardEvent automatically (see ForwardEvent.getOrigin()) and pass the original forwarded event to the defined onXxx event listener.

This is a useful tool for MVC design practice. You can write onXxx event handler codes in controller object and use this utility to register the events to the specified component.

Parameters:
comp - the component to be registered the events
controller - a POJO file with onXxx methods(event handlers)
Since:
3.0.6
See Also:
GenericEventListener

getRealOrigin

public static final Event getRealOrigin(ForwardEvent event)
Returns the real origin event of a forwarded event. By real we mean the last non-forward event in the chain of ForwardEvent.getOrigin(). Notice that a forward event might be forwarded again, so ForwardEvent.getOrigin() might not be the real origin.

Since:
3.5.1


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