Selection Event"

From Documentation
(16 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
  
These events involves changing selection range of cells.
 
  
* '''onCellFocused'''
+
__TOC__
*: This event is fired when a cell gets focused when a user clicks on it. When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellEvent</javadoc> object is passed as an argument.
+
  
* '''onCellSelection'''
+
= Overview =
*: This event is fired when a user select a cell or a group of cell by dragging mouse. It is also fired if a user selects a row or column by clicking their headers. When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellSelectionEvent</javadoc> object is passed as an argument.
 
  
* '''onCellSelectionUpdate'''
+
The following events involve changing selected range of cells.
*: This event is fired when a user moves or change the range of a selection. When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellSelectionUpdateEvent</javadoc> object is passed as an argument.
 
*: There are two features, "auto fill" and "move cells' content", depend on this event. They listen the event and perform their operation like filling cells. Notice that your event listener might affect these features.
 
  
 +
== onCellFocus ==
 +
This event is fired when a cell gets focused by mouse clicking or using key. When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellEvent</javadoc> object is passed as an argument.
 +
 +
== onCellSelection ==
 +
This event is fired when a user selects a cell by clicking or a group of cells by dragging mouse. It is also fired if a user selects a row or a column by clicking their headers which means selecting the whole row (or column). When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellSelectionEvent</javadoc> object is passed as an argument.
 +
 +
== onCellSelectionUpdate ==
 +
This event is fired when a user drags to move cells or drags the fill handle. When a corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.CellSelectionUpdateEvent</javadoc> object is passed as an argument.
 +
 +
There are two features, "auto fill" and "move cells' content", depend on this event. They listen the event and perform their operation like filling cells. Notice that your event listener might affect these features.
  
 
= Event Monitor Example =
 
= Event Monitor Example =
Line 27: Line 33:
 
//omitted codes...
 
//omitted codes...
  
@Listen("onCellFocused = spreadsheet")
+
@Listen("onCellFocus = #ss")
public void onCellFocused(CellEvent event){
+
public void onCellFocus(CellEvent event){
 
StringBuilder info = new StringBuilder();
 
StringBuilder info = new StringBuilder();
 
info.append("Focus on[")
 
info.append("Focus on[")
.append(Ranges.getCellReference(event.getRow(),event.getColumn())).append("]");
+
.append(Ranges.getCellRefString(event.getRow(),event.getColumn())).append("]");
 
 
 
//show info...
 
//show info...
 
}
 
}
 
 
@Listen("onCellSelection = spreadsheet")
+
@Listen("onCellSelection = #ss")
 
public void onCellSelection(CellSelectionEvent event){
 
public void onCellSelection(CellSelectionEvent event){
 
StringBuilder info = new StringBuilder();
 
StringBuilder info = new StringBuilder();
 
info.append("Select on[")
 
info.append("Select on[")
.append(Ranges.getAreaReference(event.getArea())).append("]");
+
.append(Ranges.getAreaRefString(event.getSheet(), event.getArea())).append("]");
 
 
 
//show info...
 
//show info...
 
}
 
}
 
 
@Listen("onCellSelectionUpdate = spreadsheet")
+
@Listen("onCellSelectionUpdate = #ss")
 
public void onCellSelectionUpdate(CellSelectionUpdateEvent event){
 
public void onCellSelectionUpdate(CellSelectionUpdateEvent event){
 
StringBuilder info = new StringBuilder();
 
StringBuilder info = new StringBuilder();
 
info.append("Selection update from[")
 
info.append("Selection update from[")
.append(Ranges.getAreaReference(event.getOrigRow(),event.getOrigColumn()
+
.append(Ranges.getAreaRefString(event.getOrigRow(),event.getOrigColumn()
 
, event.getOrigLastRow(),event.getOrigLastColumn()))
 
, event.getOrigLastRow(),event.getOrigLastColumn()))
 
.append("] to [")
 
.append("] to [")
.append(Ranges.getAreaReference(event.getArea())).append("]");
+
.append(Ranges.getAreaRefString(event.getSheet(), event.getArea())).append("]");
  
 
//show info...
 
//show info...
Line 60: Line 66:
 
}
 
}
 
</source>
 
</source>
* Line 4, 13, 22: Apply <tt>@Listen</tt> to listen an event with the syntax <tt>[EVENT NAME] = [COMPONENT SELECTOR]</tt>. All event name can be found in <javadoc directory="zss">org.zkoss.zss.ui.event.Events</javadoc>. The "spreadsheet" is the component selector which means all Spreadsheet on the ZUL page. (SelectorComposer supports various selector syntax that let you select components easily. Please refer to [[ZK Developer's Reference/MVC/Controller/Wire Components]]) .
+
* Line 4, 13, 22: Apply <tt>@Listen</tt> to listen an event with the syntax <tt>[EVENT NAME] = [COMPONENT SELECTOR]</tt>. All event name can be found in <javadoc directory="zss">org.zkoss.zss.ui.event.Events</javadoc>. The "#ss" is the component selector which means the component with id <tt>ss</tt>  on the ZUL page. (SelectorComposer supports various selector syntax that let you select components easily. Please refer to [[ZK Developer's Reference/MVC/Controller/Wire Components]]) .
 
* Line 8: You can get focused cell's row and column index (0-based).
 
* Line 8: You can get focused cell's row and column index (0-based).
* Line 17: You can get selection area.
+
* Line 17: You can get selection area by <tt>event.getArea()</tt>.
 
* Line 26: You can get the selection area before and after it changes.
 
* Line 26: You can get the selection area before and after it changes.
 +
 +
 +
= Range Selection Example =
 +
A pratical use case of <tt>onCellSelection</tt> event is to build a range selection dialog, e.g. let users select a cell range for futher processing without entering it by a keyboard. An example is showed by the screenshot below:
 +
 +
[[File:zss-essentials-rangeSelectionDialog.png | center]]
 +
 +
When opening the dialog to select a range, we can hide edit UI and cancel <tt>onStartEditing</tt> event to forbid users editing.
 +
 +
In the code below, we put cell address string converted from <tt>CellSelectionEvent</tt> in the Textbox of the dialog.
 +
 +
<source lang='java'>
 +
    @Listen("onCellSelection = #dialog")
 +
    public void onCellSelection(CellSelectionEvent event){
 +
        Textbox rangeBox  = (Textbox)dialog.getFellow("rangeBox");
 +
        Range selection =Ranges.range(event.getSheet(), event.getArea());
 +
        if (selection.isWholeRow()){
 +
            rangeBox.setValue(Ranges.getRowRefString(event.getRow()));
 +
        }else if (selection.isWholeColumn()){
 +
            rangeBox.setValue(Ranges.getColumnRefString(event.getColumn()));
 +
        }else{
 +
            rangeBox.setValue(Ranges.getAreaRefString(event.getSheet(), event.getArea()));
 +
        }
 +
    }
 +
</source>
 +
 +
You can find the implementation detail in our example source code.
 +
 +
 +
 +
 +
{{ZKSpreadsheetEssentialsPageFooter}}

Revision as of 08:52, 21 March 2019




Overview

The following events involve changing selected range of cells.

onCellFocus

This event is fired when a cell gets focused by mouse clicking or using key. When a corresponding event listener is invoked, a CellEvent object is passed as an argument.

onCellSelection

This event is fired when a user selects a cell by clicking or a group of cells by dragging mouse. It is also fired if a user selects a row or a column by clicking their headers which means selecting the whole row (or column). When a corresponding event listener is invoked, a CellSelectionEvent object is passed as an argument.

onCellSelectionUpdate

This event is fired when a user drags to move cells or drags the fill handle. When a corresponding event listener is invoked, a CellSelectionUpdateEvent object is passed as an argument.

There are two features, "auto fill" and "move cells' content", depend on this event. They listen the event and perform their operation like filling cells. Notice that your event listener might affect these features.

Event Monitor Example

In our Event Monitor application, you can see the mouse pointer becomes a 4-direction arrow pointer. That means we move the selection area. Thus, you can selection update message on the right hand side panel.

Zss-essentials-events-selection.png


The following codes demonstrate how to listen above events and get related data from them.

public class EventsComposer extends SelectorComposer<Component>{
	//omitted codes...

	@Listen("onCellFocus = #ss")
	public void onCellFocus(CellEvent event){
		StringBuilder info = new StringBuilder();
		info.append("Focus on[")
		.append(Ranges.getCellRefString(event.getRow(),event.getColumn())).append("]");
		
		//show info...
	}
	
	@Listen("onCellSelection = #ss")
	public void onCellSelection(CellSelectionEvent event){
		StringBuilder info = new StringBuilder();
		info.append("Select on[")
		.append(Ranges.getAreaRefString(event.getSheet(), event.getArea())).append("]");
		
		//show info...
	}
	
	@Listen("onCellSelectionUpdate = #ss")
	public void onCellSelectionUpdate(CellSelectionUpdateEvent event){
		StringBuilder info = new StringBuilder();
		info.append("Selection update from[")
		.append(Ranges.getAreaRefString(event.getOrigRow(),event.getOrigColumn()
				, event.getOrigLastRow(),event.getOrigLastColumn()))
		.append("] to [")
		.append(Ranges.getAreaRefString(event.getSheet(), event.getArea())).append("]");

		//show info...
	}


}
  • Line 4, 13, 22: Apply @Listen to listen an event with the syntax [EVENT NAME] = [COMPONENT SELECTOR]. All event name can be found in Events. The "#ss" is the component selector which means the component with id ss on the ZUL page. (SelectorComposer supports various selector syntax that let you select components easily. Please refer to ZK Developer's Reference/MVC/Controller/Wire Components) .
  • Line 8: You can get focused cell's row and column index (0-based).
  • Line 17: You can get selection area by event.getArea().
  • Line 26: You can get the selection area before and after it changes.


Range Selection Example

A pratical use case of onCellSelection event is to build a range selection dialog, e.g. let users select a cell range for futher processing without entering it by a keyboard. An example is showed by the screenshot below:

Zss-essentials-rangeSelectionDialog.png

When opening the dialog to select a range, we can hide edit UI and cancel onStartEditing event to forbid users editing.

In the code below, we put cell address string converted from CellSelectionEvent in the Textbox of the dialog.

    @Listen("onCellSelection = #dialog")
    public void onCellSelection(CellSelectionEvent event){
        Textbox rangeBox  = (Textbox)dialog.getFellow("rangeBox");
        Range selection =Ranges.range(event.getSheet(), event.getArea()); 
        if (selection.isWholeRow()){
            rangeBox.setValue(Ranges.getRowRefString(event.getRow()));
        }else if (selection.isWholeColumn()){
            rangeBox.setValue(Ranges.getColumnRefString(event.getColumn()));
        }else{
            rangeBox.setValue(Ranges.getAreaRefString(event.getSheet(), event.getArea()));
        }
    }

You can find the implementation detail in our example source code.



All source code listed in this book is at Github.


Last Update : 2019/03/21

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