ZK Spreadsheet Essentials/Working with ZK Spreadsheet/Implement ZK Spreadsheet Event Listeners/Editing Events

This article is out of date, please refer to http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials for more up to date information.

Users can write event listeners for editing events such as onStartEditing and onStopEditing to control and/or limit what is being entered in specific ZK Spreadsheet cell and also apply some style/value transformation.

Purpose

Implement onStartEditing, onStopEditing and onEditboxEditing event listeners.

Editing events

There are three editing events that ZK Spreadsheet supports.

• onStartEditing - This event is fired when the user starts editing a cell. It is fired only once at the beginning when the first key is pressed when the user starts editing. Event listeners are provided with StartEditingEvent on receiving this event.
• onStopEditing - This event is fired when the user has finished editing a cell. It is identified by the user hitting the enter key or clicking outside of the editing cell. Event listeners are provided with StopEditingEvent on receiving this event.
• onEditboxEditing - This event is fired when the user is ediing a cell and it is similar to textbox component onChanging event. Event listeners are provided with EditboxEditingEvent on receiving this event.

Registering Editing Events

Editing events can be registered to ZK Spreadsheet either by calling AbstractComponent.addEventListener(String, EventListener) or by using ZK MVC way i.e. using naming convention of <editing-event-name>$<component-id>. Here is an example shown using the first way.

...
ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_START_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStartEditingEvent((StartEditingEvent) event);
					}
				});
...

Note: All ZK Spreadsheet supported events have a corresponding static constants declared in org.zkoss.zss.ui.event.Events class. For example for onStartEditing event there is org.zkoss.zss.ui.event.Events.ON_START_EDITING and so on.

Here is an example shown using the second way.

...
	public void onStartEditing$ss(StartEditingEvent event) {
		// for example you can restrict which cells can be edited here
	}
...

ZUML

Here is a sample example ZUL file

<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
<zk>
	<window title="ZSS Editing Events" border="normal" width="100%"
		height="100%" apply="org.zkoss.zssessentials.events.EditingEventsComposer">
		<hlayout>
		<label value="Edit Box:"></label>
		<textbox id="editBox"></textbox>
		</hlayout>
		<spreadsheet id="ss" width="800px" height="800px" maxrows="20"
			maxcolumns="10" src="/WEB-INF/excel/events/events.xlsx">
		</spreadsheet>
	</window>
</zk>

Composer

In your composer,

public class EditingEventsComposer extends GenericForwardComposer {

	private transient Spreadsheet ss;
	private transient Textbox editBox;
	
	public void doAfterCompose(Component comp) throws Exception {
		super.doAfterCompose(comp);
		ss.addEventListener(Events.ON_EDITBOX_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doEditboxEditingEvent((EditboxEditingEvent) event);
					}
				});
		ss.addEventListener(Events.ON_START_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStartEditingEvent((StartEditingEvent) event);
					}
				});
		ss.addEventListener(Events.ON_STOP_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStopEditingEvent((StopEditingEvent) event);
					}
				});
	}
	private void doEditboxEditingEvent(EditboxEditingEvent event) {
		editBox.setValue((String) event.getEditingValue());
	}
	private void doStartEditingEvent(StartEditingEvent event) {
		// for example you can restrict which cells can be edited here
	}
	private void doStopEditingEvent(StopEditingEvent event) {
		// for example you can apply value or style transformation here on entered value
	}
}

Each of the editing events gives you the currently editing value by calling EditboxEditingEvent.getEditingValue() on editing event. View the complete source code for composer here

Version History

Version	Date	Content

All source code listed in this book is at Github.