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

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

Implement 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 user left clicks on ZK Spreadsheet cell. Event listeners are provided with org.zkoss.zss.ui.event.CellMouseEvent in the event listener.
• onCellDoubleClick - This event is fired when user double clicks on ZK Spreadsheet cell. Event listeners are provided with org.zkoss.zss.ui.event.CellMouseEvent in the event listener.
• onCellRightClick - This event is fired when user right clicks on ZK Spreadsheet cell. Event listeners are provided with org.zkoss.zss.ui.event.CellMouseEvent in the event listener.

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

• onHeaderClick - This event is fired when user left clicks on ZK Spreadsheet header. Event listeners are provided with org.zkoss.zss.ui.event.HeaderMouseEvent in the event listener.
• onHeaderDoubleClick - This event is fired when user double clicks on ZK Spreadsheet header. Event listeners are provided with org.zkoss.zss.ui.event.HeaderMouseEvent in the event listener.
• onHeaderRightClick - This event is fired when user right clicks on ZK Spreadsheet header. Event listeners are provided with org.zkoss.zss.ui.event.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 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 org.zkoss.zss.ui.event.Events class. For example for onCellClick event there is org.zkoss.zss.ui.event.Events.ON_CELL_CLICK and so on.

Here is an example shown using 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());
		}
	}
}

Above example shows both ways of registering mouse events. When user click on a cell onCellClick event is fired and event listener for this event is notified. Similarly hen 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 event.getClientx() and event.getClienty().

For cell specific events CellMouseEvent also identifies cell associated with event so event listeners can utilize event.getSheet(),event.getRow() and event.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 event.getType() to determine whether it is top or left header.

Version History

Version	Date	Content

All source code listed in this book is at Github.