Mouse 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 mouse event listeners for mouse events such as cell click, cell double click, cell right click, header click, header double click and header right click.

Purpose

Implementing mouse event listeners for cell click, cell double click, cell right click, header click, header double click and header right click.

Mouse events

There are two types of Mouse events. One is cell mouse events such as onCellClick, onCellDoubleClick and onCellRightClick

• onCellClick - This event is fired when the user left clicks on ZK Spreadsheet cell. Event listeners are provided with CellMouseEvent in the event listener.
• onCellDoubleClick - This event is fired when the user double clicks on ZK Spreadsheet cell. Event listeners are provided with CellMouseEvent in the event listener.
• onCellRightClick - This event is fired when the user right clicks on ZK Spreadsheet cell. Event listeners are provided with CellMouseEvent in the event listener.

and the other is header mouse events such as onHeaderClick, onHeaderDoubleClick and onHeaderRightClick.

• onHeaderClick - This event is fired when the user left clicks on ZK Spreadsheet header. Event listeners are provided with HeaderMouseEvent in the event listener.
• onHeaderDoubleClick - This event is fired when the user double clicks on ZK Spreadsheet header. Event listeners are provided with HeaderMouseEvent in the event listener.
• onHeaderRightClick - This event is fired when the user right clicks on ZK Spreadsheet header. Event listeners are provided with HeaderMouseEvent in the event listener.

Registering Mouse Events

Mouse 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 <mouse-event-name>$<component-id>. Here is an example shown using the first way.

...
ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_CELL_CLICK,
		new EventListener() {
			public void onEvent(Event event) throws Exception {
				doCellClickEvent((CellMouseEvent) event);
			}
		});
...

Note: All ZK Spreadsheet supported mouse events have a corresponding static constants declared in Events class. For example for onCellClick event there is Events.ON_CELL_CLICK and so on.

Here is an example shown using the second way.

...
public void onCellRightClick$ss(CellMouseEvent event) {
	cellMenu.open(event.getClientx(),  event.getClienty());
}
...

ZUML

Here is a sample example ZUL file.

<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
<zk>
	<window title="ZSS Mouse Events" border="normal" width="100%"
		height="100%" apply="org.zkoss.zssessentials.events.MouseEventsComposer">
		<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>
		<menupopup id="cellMenu">
			<menuitem id="cutMenu" label="Cut" />
			<menuitem id="copyMenu" label="Copy" />
			<menuitem id="pasteMenu" label="Paste" />
		</menupopup>
		<menupopup id="topHeaderMenu">
			<menuitem id="insertLeftMenu" label="Insert Left" />
			<menuitem id="insertRightMenu" label="Insert Right" />
			<menuitem id="deleteColumnMenu" label="Delete" />
		</menupopup>
		<menupopup id="leftHeaderMenu">
			<menuitem id="insertAboveMenu" label="Insert Above" />
			<menuitem id="insertBelowMenu" label="Insert Below" />
			<menuitem id="deleteRowMenu" label="Delete" />
		</menupopup>
	</window>
</zk>

Composer

In your composer.

public class MouseEventsComposer extends GenericForwardComposer {

	private transient Spreadsheet ss;
	private transient Textbox editBox;
	private transient Menupopup cellMenu;
	private transient Menupopup topHeaderMenu;
	private transient Menupopup leftHeaderMenu;

	public void doAfterCompose(Component comp) throws Exception {
		super.doAfterCompose(comp);
		ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_CELL_CLICK,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doCellClickEvent((CellMouseEvent) event);
					}
				});
		ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_CELL_RIGHT_CLICK,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doCellRightClickEvent((CellMouseEvent) event);
					}
				});
	}

	private void doCellClickEvent(CellMouseEvent event) {
		Range range = Ranges.range(event.getSheet(),event.getRow(),event.getColumn());
		editBox.setValue(range.getEditText());
	}
	private void doCellRightClickEvent(CellMouseEvent event) {
		cellMenu.open(event.getClientx(),  event.getClienty());
	}
	public void onHeaderRightClick$ss(HeaderMouseEvent event) {
		if (HeaderEvent.TOP_HEADER == event.getType()) {
			topHeaderMenu.open(event.getClientx(),  event.getClienty());
		} else if ((HeaderEvent.LEFT_HEADER == event.getType())) {
			leftHeaderMenu.open(event.getClientx(),  event.getClienty());
		}
	}
}

The example above shows both ways of registering mouse events. When the user clicks on a cell onCellClick event is fired and the event listener for this event is notified. Similarly when the user right clicks on a cell or top/left header corresponding event listerns are notified. Event listeners can use CellMouseEvent or HeaderMouseEvent to determine mouse position using CellMouseEvent.getClientx() and HeaderMouseEvent.getClienty().

For cell specific events CellMouseEvent also identifies cell associated with event so event listeners can utilize CellMouseEvent.getSheet(), CellMouseEvent.getRow() and CellMouseEvent.getColumn() to construct Range instances which in turn allows you to access cell contents.

For header specific events HeaderMouseEvent also identifies which header event is associated with. Event listeners can utilize HeaderMouseEvent.getType() to determine whether it is top or left header.

View the complete source code of composer here

Version History

Version	Date	Content

All source code listed in this book is at Github.