Mouse Events"

From Documentation
Line 8: Line 8:
 
===Mouse events===
 
===Mouse events===
 
There are two types of Mouse events. One is cell mouse events such as onCellClick, onCellDoubleClick and onCellRightClick  
 
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 <javadoc>org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
+
* '''onCellClick''' - This event is fired when user left clicks on ZK Spreadsheet cell. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
* '''onCellDoubleClick''' - This event is fired when user double clicks on ZK Spreadsheet cell. Event listeners are provided with <javadoc>org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
+
* '''onCellDoubleClick''' - This event is fired when user double clicks on ZK Spreadsheet cell. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
* '''onCellRightClick''' - This event is fired when user right clicks on ZK Spreadsheet cell. Event listeners are provided with <javadoc>org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
+
* '''onCellRightClick''' - This event is fired when user right clicks on ZK Spreadsheet cell. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> in the event listener.
  
 
and other is header mouse events such as onHeaderClick, onHeaderDoubleClick and onHeaderRightClick.
 
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 <javadoc>org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
+
* '''onHeaderClick''' - This event is fired when user left clicks on ZK Spreadsheet header. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
* '''onHeaderDoubleClick''' - This event is fired when user double clicks on ZK Spreadsheet header. Event listeners are provided with <javadoc>org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
+
* '''onHeaderDoubleClick''' - This event is fired when user double clicks on ZK Spreadsheet header. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
* '''onHeaderRightClick''' - This event is fired when user right clicks on ZK Spreadsheet header. Event listeners are provided with <javadoc>org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
+
* '''onHeaderRightClick''' - This event is fired when user right clicks on ZK Spreadsheet header. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> in the event listener.
  
 
===Registering Mouse Events===
 
===Registering Mouse Events===
Mouse events 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 <mouse-event-name>$<component-id>. Here is an example shown using first way
+
Mouse events 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 MVC way i.e. using naming convention of <mouse-event-name>$<component-id>. Here is an example shown using first way
  
 
<source lang="java">
 
<source lang="java">
Line 30: Line 30:
 
...
 
...
 
</source>
 
</source>
'''Note''': All ZK Spreadsheet supported mouse events have a corresponding static constants declared in <javadoc>org.zkoss.zss.ui.event.Events</javadoc> class. For example for onCellClick event there is <javadoc>org.zkoss.zss.ui.event.Events.ON_CELL_CLICK</javadoc> and so on.
+
'''Note''': All ZK Spreadsheet supported mouse events have a corresponding static constants declared in <javadoc directory="zss">org.zkoss.zss.ui.event.Events</javadoc> class. For example for onCellClick event there is <javadoc directory="zss">org.zkoss.zss.ui.event.Events.ON_CELL_CLICK</javadoc> and so on.
  
 
Here is an example shown using second way
 
Here is an example shown using second way
Line 119: Line 119:
 
</source>
 
</source>
  
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 <javadoc>org.zkoss.zss.ui.event.CellMouseEvent</javadoc> or <javadoc>org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> to determine mouse position using <javadoc method="getClientx()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> and  <javadoc method="getClienty()">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc>.  
+
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 <javadoc directory="zss">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> or <javadoc directory="zss">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> to determine mouse position using <javadoc directory="zss" method="getClientx()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> and  <javadoc directory="zss" method="getClienty()">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc>.  
  
For cell specific events CellMouseEvent also identifies cell associated with event so event listeners can utilize <javadoc method="getSheet()>org.zkoss.zss.ui.event.CellMouseEvent</javadoc>, <javadoc method="getRow()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> and <javadoc method="getColumn()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> to construct Range instances which in turn allows you to access cell contents.  
+
For cell specific events CellMouseEvent also identifies cell associated with event so event listeners can utilize <javadoc directory="zss" method="getSheet()>org.zkoss.zss.ui.event.CellMouseEvent</javadoc>, <javadoc directory="zss" method="getRow()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> and <javadoc directory="zss" method="getColumn()">org.zkoss.zss.ui.event.CellMouseEvent</javadoc> 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 <javadoc method="getType()">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> to determine whether it is top or left  
+
For header specific events HeaderMouseEvent also identifies which header event is associated with. Event listeners can utilize <javadoc directory="zss" method="getType()">org.zkoss.zss.ui.event.HeaderMouseEvent</javadoc> to determine whether it is top or left  
 
header.
 
header.
  

Revision as of 01:13, 20 December 2010


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 CellMouseEvent in the event listener.
  • onCellDoubleClick - This event is fired when user double clicks on ZK Spreadsheet cell. Event listeners are provided with CellMouseEvent in the event listener.
  • onCellRightClick - This event is fired when user right clicks on ZK Spreadsheet cell. Event listeners are provided with 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 HeaderMouseEvent in the event listener.
  • onHeaderDoubleClick - This event is fired when user double clicks on ZK Spreadsheet header. Event listeners are provided with HeaderMouseEvent in the event listener.
  • onHeaderRightClick - This event is fired when user right clicks on ZK Spreadsheet header. Event listeners are provided with 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 Events class. For example for onCellClick event there is 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 CellMouseEvent.getClientx() and HeaderMouseEvent.getClienty().

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

View the complete source code of composer here

Version History

Last Update : 2010/12/20


Version Date Content
     


All source code listed in this book is at Github.


Last Update : 2010/12/20

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