ZK Spreadsheet Essentials/Working with ZK Spreadsheet/Implement ZK Spreadsheet Event Listeners/Selection 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 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 the user select a cell or group of cell by dragging mouse across specific area of spreadsheet. It is also fired if the user selects 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 the user moves or modifies the range of a selection. Event listeners are provided with SelectionChangeEvent in the event listener.

Registering Selection Events

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 onCellSelection event there is org.zkoss.zss.ui.event.Events.ON_CELL_SELECTION and so on.

Here is an example shown using second way

...
public void onCellSelection$$ss(CellSelectionEvent event) {
      // get selection using Spreadsheet#getSelection();
}
...

ZUML

Here is a sample example of 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 let's take a look at onCellSelection event handler. When the user selects a cell or group of cells onCellSelection event is fired and event handler for this event is notified.

	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().

Next we define event handler for onSelectionChange that is fired if you move or modify range of current selection. While current selection can be retrieved using Spreadsheet.getSelection(), SelectionChangeEvent provides methods to retrieve original selection as shown below.

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

View the complete source code of composer here

Version History

Version	Date	Content

All source code listed in this book is at Github.