Component Events

From Documentation

Events

Whether an event is supported or not depends upon the component. Additionally an event is sent after the component’s content is updated.

Mouse Events

Keystroke Events

The keystroke events are sent to the nearest window that has registered an event listener for the specified events. It is designed to implement submit, cancel and shortcut functions.

As illustrated below, doB() is invoked if the user presses ENTER when T1 has focus, and doA() is invoked if the user pressesENTER when T2 has focus.

<window id="A" onOK="doA()">
	<window id="B" onOK="doB()">
		<textbox id="T1"/>
	</window>
	<textbox id="T2"/>
</window>

A window doesn't receive the keystroke events that are sent for the inner window unless you post them manually. In the above example, if T1 has focus the event won't be sent to window A, no matter whether the onOK handler is declared for window B or not.

The ctrlKeys Property

To receive the onCtrlKey event, you must specify what key strokes to intercept using the ctrlKeys property. In other words, only key strokes specified in the ctrlKeys property are sent back to the server. For example, the onCtrlKey event is sent if a user presses Alt+C, Ctrl+A, F10, or Ctrl+F3.

<window ctrlKeys="@c^a#f10^#f3">

The following is the syntax of the ctrlKeys property.

You can use the function getKeyCode() to retrieve which key was pressed in the KeyEvent. a example

Input Events

List and Tree Events

Drag and Drop

ZK allows a user to drag particular components around the user interface. For example, dragging files to other directories, or dragging an item to a shopping cart.

A component is droppable, if a user could drop a draggable component to it.

Note: ZK does not assume any behavior about what shall take place after dropping. It is up to application developers by writing the onDrop event listener.

If an application doesn't nothing, the dragged component is simply moved back where it is originated from.

The draggable and droppable Properties

With ZK, you could make a component draggable by assigning any value, other than "false", to the draggable property. To disable it, assign it with "false".

<image draggable="true"/>

Similarly, you could make a component droppable by assigning "true" to the droppable property.

<hbox droppable="true"/>

Then, user could drag a draggable component, and then drop it to a droppable component.

The onDrop Event

Once user has dragged a component and dropped it to another component, the component that the user dropped the component to will be notified by the onDrop event. The onDrop event is an instance of org.zkoss.ui.event.DropEvent. By calling the getDragged method, you could retrieve what has been dragged (and dropped).

Notice that the target of the onDrop event is the droppable component, not the component being dragged.

The following is a simple example that allows users to reorder list items by drag-and-drop.

<window title="Reorder by Drag-and-Drop" border="normal">
    Unique Visitors of ZK:
    <listbox id="src" multiple="true" width="300px">
        <listhead>
            <listheader label="Country/Area"/>
            <listheader align="right" label="Visits"/>
            <listheader align="right" label="%"/>
        </listhead>
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">
            <listcell label="United States"/>
            <listcell label="5,093"/>
            <listcell label="19.39%"/>
        </listitem>
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">
            <listcell label="China"/>
            <listcell label="4,274"/>
            <listcell label="16.27%"/>
        </listitem>
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">
            <listcell label="France"/>
            <listcell label="1,892"/>
            <listcell label="7.20%"/>
        </listitem>
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">
            <listcell label="Germany"/>
            <listcell label="1,846"/>
            <listcell label="7.03%"/>
        </listitem>
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">
            <listcell label="(other)"/>
            <listcell label="13,162"/>
            <listcell label="50.01%"/>
        </listitem>
        <listfoot>
            <listfooter label="Total 132"/>
            <listfooter label="26,267"/>
            <listfooter label="100.00%"/>
        </listfoot>
    </listbox>
    <zscript>
		void move(Component dragged) {
			self.parent.insertBefore(dragged, self);
		}
    </zscript>
</window>

Dragging with Multiple Selections

When a user drag-and-drops a list item or a tree item, the selection status of these items won't be changed. Visually only the dragged item is moved, but you can handle all selected items at once by looking up the set of all selected items as depicted below.

public void onDrop(DropEvent evt) {
	Set selected = ((Listitem)evt.getDragged()).getListbox().getSelectedItems();
	//then, you can handle the whole set at once
}

Notice that the dragged item may not be selected. Thus, you may prefer to change the selection to the dragged item for this case, as shown below.

Listitem li = (Listitem)evt.getDragged();
	if (li.isSelected()) {
		Set selected = ((Listitem)evt.getDragged()).getListbox().getSelectedItems();
		//then, you can handle the whole set at once
	} else {
		li.setSelected(true);
		//handle li only
}

Multiple Types of Draggable Components

It is common that a droppable component doesn't accept all draggable components. For example, an e-mail folder accepts only e-mails and it rejects contacts or others. You could silently ignore non-acceptable components or alert an message, when onDrop is invoked.

To have better visual effect, you could identify each type of draggable components with an identifier, and then assign the identifier to the draggable property.

<listitem draggable="email"/>
 ...
<listitem draggable="contact"/>

Then, you could specify a list of identifiers to the droppable property to limit what can be dropped. For example, the following image accepts only email and contact.

<image src="/img/send.png" droppable="email, contact" onDrop="send(event.dragged)"/>

To accept any kind of draggable components, you could specify "true" to the droppable property. For example, the following image accepts any kind of draggable components.

<image src="/img/trash.png" droppable="true" onDrop="remove(event.dragged)"/>

On the other hand, if the draggable property is "true", it means the component belongs to anonymous type. Furthermore, only components with the droppable property assigned to "true" could accept it.

Slider and Scroll Events

Other Events

Echo Event

Echo event allows you to provide more richer message before doing long operation.

<window id="w" width="200px" title="Test echoEvent" border="normal">
  <attribute name="onLater">
  Thread.sleep(5000);
  Clients.showBusy(null, false);
  new Label("Done.").setParent(w);
  </attribute>
 
  <button label="Echo Event">
  <attribute name="onClick">
  Clients.showBusy("Execute... (about 5 sec.)", true);
  Events.echoEvent("onLater", w, null);
  </attribute>
  </button>
</window>

For more information, please refer to this small talk.

The Event Flow of radio and radiogroup

For developer's convenience, the onCheck event is sent to raido first and then to radiogroup^[1]. Thus, you could add listener either to the radio group or to each radio button.

<radiogroup onCheck="fruit.value = self.selectedItem.label">
	<radio label="Apple"/>
	<radio label="Orange"/>
</radiogroup>

You have selected : <tt><label id="fruit"/>

The above sample has the same effect as follows.

<radiogroup>
	<radio label="Apple" onCheck="fruit.value = self.label"/>
	<radio label="Orange" onCheck="fruit.value = self.label"/>
</radiogroup>

You have selected : <label id="fruit"/>

1. ↑ The internal implementation is done by adding a listener when a radio is added to a radiogroup.

How to know what events a component has?

You can find events for components in developer reference, chapter 4. The XUL Components

If you want to look it up in the source code. getOuterAttrs() in Button.java is a good example. Events are likely to be registered like "appendAsapAttr(sb, Events.ON_FOCUS);"

See Also

From ZK Forum:

• How to get the current location (x, y) of mouse cursor?