Selection Events"

From Documentation
(Created page with '{{ZKSpreadsheetEssentialsPageHeader}} __TOC__ Users can write selection event listeners for events such as cell or number of cells selection, column or row selection and even f…')
 
m (correct highlight (via JWB))
 
(20 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{ZKSpreadsheetEssentialsPageHeader}}
 
{{ZKSpreadsheetEssentialsPageHeader}}
 +
 +
 +
{{Deprecated|url=http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials}}
  
 
__TOC__
 
__TOC__
  
 
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.
 
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==
+
===Purpose===
 
Implement selection event listener to select cell(s),row and column.
 
Implement selection event listener to select cell(s),row and column.
==Selection event==
+
===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 <code>org.zkoss.zss.ui.event.CellSelectionEvent</code> in the event listener.
+
'''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 <javadoc directory="zss">org.zkoss.zss.ui.event.CellSelectionEvent</javadoc> 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 <javadoc directory="zss">org.zkoss.zss.ui.event.SelectionChangeEvent</javadoc> in the event listener.
  
==Registering Selection Event==
+
===Registering Selection Events===
Selection event can be registered to ZK Spreadsheet either by calling <javadoc method="addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)">org.zkoss.zk.ui.AbstractComponent</javadoc> 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
+
Selection event can be registered to ZK Spreadsheet either by calling <javadoc directory="zss" method="addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)">org.zkoss.zk.ui.AbstractComponent</javadoc> or by using [[ZK_Developer's_Reference/MVC| ZK MVC]] way i.e. using naming convention of <selection-event-name>$<component-id>. Here is an example shown using first way
  
 
<source lang="java">
 
<source lang="java">
Line 22: Line 27:
 
...
 
...
 
</source>
 
</source>
'''Note''': All ZK Spreadsheet supported mouse events have a corresponding static constants declared in <code>org.zkoss.zss.ui.event.Events</code> class. For example for onCellClick event there is <code>org.zkoss.zss.ui.event.Events.ON_CELL_CLICK</code> and so on.
+
'''Note''': All ZK Spreadsheet supported mouse events have a corresponding static constants declared in <code>org.zkoss.zss.ui.event.Events</code> class. For example for onCellSelection event there is <code>org.zkoss.zss.ui.event.Events.ON_CELL_SELECTION</code> and so on.
  
 
Here is an example shown using second way
 
Here is an example shown using second way
 
<source lang="java">
 
<source lang="java">
 
...
 
...
public void doSelectionEvent(CellSelectionEvent event) {
+
public void onCellSelection$$ss(CellSelectionEvent event) {
 
       // get selection using Spreadsheet#getSelection();
 
       // get selection using Spreadsheet#getSelection();
 
}
 
}
Line 33: Line 38:
 
</source>
 
</source>
  
==Example==
+
===ZUML===
Here is a sample example ZUL file.
+
Here is a sample example of ZUL file.
 
<source lang="xml">
 
<source lang="xml">
 
<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
 
<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
 
<zk>
 
<zk>
 
<window title="ZSS Selection Events" border="normal" width="100%"
 
<window title="ZSS Selection Events" border="normal" width="100%"
height="100%" apply="org.zkoss.zss.example.SelectionEventComposer">
+
height="100%" apply="org.zkoss.zssessentials.events.SelectionEventsComposer">
 
<hlayout>
 
<hlayout>
<label value="Selected Area:"></label>
+
<label value="Current Selection:"></label>
<label id="areaLbl" value="None"></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>
 
</hlayout>
<spreadsheet id="ss" width="800px" height="800px" maxrows="20"
+
<spreadsheet id="ss" width="800px" height="800px" maxrows="35"
maxcolumns="10" src="/test2/xls/mouse.xlsx">
+
maxcolumns="10" src="/WEB-INF/excel/events/events.xlsx">
 
</spreadsheet>
 
</spreadsheet>
 
</window>
 
</window>
Line 51: Line 59:
 
</source>
 
</source>
  
In your composer.
+
===Composer===
<source lang="java" high="11,17,33,34,35">
+
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 class SelectionEventComposer extends GenericForwardComposer {
+
<source lang="java" highlight="2,4">
 
 
Spreadsheet ss;
 
Label areaLbl;
 
 
 
 
public void onCellSelection$ss(CellSelectionEvent event) {
 
public void onCellSelection$ss(CellSelectionEvent event) {
 
int s = event.getSelectionType();
 
int s = event.getSelectionType();
 +
 
Rect rect = ss.getSelection();
 
Rect rect = ss.getSelection();
 
String area = "None";
 
String area = "None";
Line 76: Line 81:
 
break;
 
break;
 
}
 
}
areaLbl.setValue(area);
+
currentAreaLbl.setValue(area);
 
}
 
}
}
 
 
</source>
 
</source>
  
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 <code>event.getSelectionType()</code> to differentiate between certain selection such as cell(s) selection, column selection, row selection or select all selection.
+
In above code first we determine selection type by <javadoc directory="zss" method="getSelectionType()">org.zkoss.zss.ui.event.CellSelectionEvent</javadoc> 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 <javadoc directory="zss" method="getSelection()">org.zkoss.zss.ui.Spreadsheet</javadoc>.
 +
 
 +
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 <javadoc directory="zss" method="getSelection()">org.zkoss.zss.ui.Spreadsheet</javadoc>, <javadoc directory="zss">org.zkoss.zss.ui.event.SelectionChangeEvent</javadoc> provides methods to retrieve original selection as shown below.
 +
<source lang="java" highlight="9,10">
 +
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);
 +
}
 +
</source>
  
Current selection can be retrieved using <code>Spreadsheet#getSelection()</code>.
+
View the complete source code of composer [https://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/src/org/zkoss/zssessentials/events/SelectionEventsComposer.java here]
  
 
=Version History=
 
=Version History=

Latest revision as of 12:57, 19 January 2022



Stop.png 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

Last Update : 2022/01/19


Version Date Content
     


All source code listed in this book is at Github.


Last Update : 2022/01/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.