Package org.zkoss.zk.ui.event

Class Events

java.lang.Object
org.zkoss.zk.ui.event.Events
public class Events extends Object
Utilities to handle events.
Author:
tomyeh

  • Field Details

  • Method Details

    • isValid

      public static final boolean isValid(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, 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<? extends org.zkoss.zk.ui.event.Event>) and Page.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener<? extends org.zkoss.zk.ui.event.Event>).

      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:

    • 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(String name, Component target, 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:

    • postEvent

      public static final void postEvent(String name, Component target, 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

      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, String name, Component target, 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(String name, Component target, 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:

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

    • echoEvent

      public static final void echoEvent(String name, Component target, 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:

    • addEventListeners

      public static final void addEventListeners(Component comp, 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:

    • 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