Class Events


  • public class Events
    extends java.lang.Object
    Utilities to handle events.
    Author:
    tomyeh
    • Field Detail

      • 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_TARGET_CLICK

        public static final java.lang.String ON_TARGET_CLICK
        The onTargetClick event (used with MouseEvent).
        Since:
        9.0.0
        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_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_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_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
      • ON_DEFERRED_EVALUATION

        public static final java.lang.String ON_DEFERRED_EVALUATION
        The onDeferredEvaluation event (used with Event) to notify a component the Composer.doAfterCompose(Component) phase is done, and can evaluate deferred expressions if any.
        Since:
        8.0.0
        See Also:
        Constant Field Values
      • ON_SLIDE

        public static final java.lang.String ON_SLIDE
        The onSlide event (used with Event).
        Since:
        8.0.2
        See Also:
        Constant Field Values
      • ON_SEARCHING

        public static final java.lang.String ON_SEARCHING
        The onSearching event (used with InputEvent).
        Since:
        9.0.0
        See Also:
        Constant Field Values
      • ON_INNER_WIDTH

        public static final java.lang.String ON_INNER_WIDTH
        The onInnerWidth event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_SCROLL_POS

        public static final java.lang.String ON_SCROLL_POS
        The onScrollPos event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_TOP_PAD

        public static final java.lang.String ON_TOP_PAD
        The onTopPad event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_DATA_LOADING

        public static final java.lang.String ON_DATA_LOADING
        The onDataLoading event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_WEEK_CLICK

        public static final java.lang.String ON_WEEK_CLICK
        The onWeekClick event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_TIME_ZONE_CHANGE

        public static final java.lang.String ON_TIME_ZONE_CHANGE
        The onTimeZoneChange event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_ANCHOR_POS

        public static final java.lang.String ON_ANCHOR_POS
        The onAnchorPos event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_ACROSS_PAGE

        public static final java.lang.String ON_ACROSS_PAGE
        The onAcrossPage event used with Event.
        Since:
        10.0.0
        See Also:
        Constant Field Values
      • ON_CHECK_SELECT_ALL

        public static final java.lang.String ON_CHECK_SELECT_ALL
        The onCheckSelectAll event used with Event.
        Since:
        10.0.0
        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.
      • 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​(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.

        Since 10.0.0, ZK EE opened InaccessableWidgetBlockService by default, so it will block echo event for disabled and invisible component, to disable it, set library property `org.zkoss.zkmax.au.IWBS.disable` to `true`.

        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 10.0.0, ZK EE opened InaccessableWidgetBlockService by default, so it will block echo event for disabled and invisible component, to disable it, set library property `org.zkoss.zkmax.au.IWBS.disable` to `true`.

        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.

        Since 10.0.0, ZK EE opened InaccessableWidgetBlockService by default, so it will block echo event for disabled and invisible component, to disable it, set library property `org.zkoss.zkmax.au.IWBS.disable` to `true`.

        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