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

Users can write selection event listeners for events such as cell or number of cells selection, column or row selection and even for select all.

Purpose

Implement selection event listener to select cell(s),row and column.

Selection event

onCellSelection - This event is fired when user select a cell or group of cell by dragging mouse across specific area of spreadsheet. It is also fired if user select a row or column by clicking on top or left headers. Event listeners are provided with CellSelectionEvent in the event listener. onSelectionChange - This event is fired when user move or modify range of a selection. Event listeners are provided with SelectionChangeEvent in the event listener.

Registering Selection Event

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

...
ss.addEventListener(Events.ON_CELL_SELECTION,
		new EventListener() {
			public void onEvent(Event event) throws Exception {
				doSelectionEvent((CellSelectionEvent) 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 doSelectionEvent(CellSelectionEvent event) {
      // get selection using Spreadsheet#getSelection();
}
...

ZUML

Here is a sample example ZUL file.

<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
<zk>
	<window title="ZSS Selection Events" border="normal" width="100%"
		height="100%" apply="org.zkoss.zssessentials.events.SelectionEventsComposer">
		<hlayout>
			<label value="Current Selection:"></label>
			<label id="currentAreaLbl" value="None" width="200px"></label>
			<label value="Original Selection:"></label>
			<label id="origAreaLbl" value="None" width="200px"></label>
			<button id="selectbtn" label="Select"/>
		</hlayout>
		<spreadsheet id="ss" width="800px" height="800px" maxrows="35"
			maxcolumns="10" src="/WEB-INF/excel/events/events.xlsx">
		</spreadsheet>
	</window>
</zk>

Composer

In composer there are two event handlers for onCellSelection and onSelectionChange. First take a look at onCellSelection event handler.

	public void onCellSelection$ss(CellSelectionEvent event) {
		int s = event.getSelectionType();
		
		Rect rect = ss.getSelection();
		String area = "None";
		switch (s) {
		case CellSelectionEvent.SELECT_CELLS:
			area = ss.getColumntitle(rect.getLeft()) + ss.getRowtitle(rect.getTop()) + ":" + 
				ss.getColumntitle(rect.getRight()) + ss.getRowtitle(rect.getBottom());
			break;
		case CellSelectionEvent.SELECT_COLUMN:
			area = "COL:" + ss.getColumntitle(rect.getLeft());
			break;
		case CellSelectionEvent.SELECT_ROW:
			area = "ROW:" + ss.getRowtitle(rect.getTop());
			break;
		case CellSelectionEvent.SELECT_ALL:
			break;
		}
		currentAreaLbl.setValue(area);
	}

In above code first we determine selection type by CellSelectionEvent.getSelectionType() which tells us if if it is a group of cells selection, row,column or all area selection. Currently selected area can be retrieved by Spreadsheet.getSelection().

Below we define event handler for onSelectionChange Above example example we define event handler ZK MVC way. When user selects a cell or group of cells onCellSelection event is fired and event handler for this event is notified. User can use event.getSelectionType() to differentiate between certain selection such as cell(s) selection, column selection, row selection or select all selection.

Current selection can be retrieved using Spreadsheet#getSelection().

Version History

Version	Date	Content

All source code listed in this book is at Github.