Editing Events"

From Documentation
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{ZKSpreadsheetEssentialsPageHeader}}
 
{{ZKSpreadsheetEssentialsPageHeader}}
 +
 +
 +
{{Deprecated|url=http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials}}
  
 
__TOC__
 
__TOC__
Line 8: Line 11:
 
===Editing events===
 
===Editing events===
 
There are three editing events that ZK Spreadsheet supports.
 
There are three editing events that ZK Spreadsheet supports.
* '''onStartEditing''' - This event is fired when user starts editing a cell. It is fired only once at the beginning when first key is pressed when user starts editing. Event listeners are provided with <javadoc directory="zss"  directory="zss">org.zkoss.zss.ui.event.StartEditingEvent</javadoc> on receiving this event.
+
* '''onStartEditing''' - This event is fired when the user starts editing a cell. It is fired only once at the beginning when the first key is pressed when the user starts editing. Event listeners are provided with <javadoc directory="zss"  directory="zss">org.zkoss.zss.ui.event.StartEditingEvent</javadoc> on receiving this event.
* '''onStopEditing''' - This event is fired when user has finished editing a cell. It is identified by user hitting enter key or clicking outside of the editing cell.  Event listeners are provided with <javadoc directory="zss" directory="zss">org.zkoss.zss.ui.event.StopEditingEvent</javadoc> on receiving this event.
+
* '''onStopEditing''' - This event is fired when the user has finished editing a cell. It is identified by the user hitting the enter key or clicking outside of the editing cell.  Event listeners are provided with <javadoc directory="zss" directory="zss">org.zkoss.zss.ui.event.StopEditingEvent</javadoc> on receiving this event.
* '''onEditboxEditing''' - This event is fired when user is ediing a cell and it is similar to textbox component onChanging event. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.EditboxEditingEvent</javadoc> on receiving this event.
+
* '''onEditboxEditing''' - This event is fired when the user is ediing a cell and it is similar to textbox component onChanging event. Event listeners are provided with <javadoc directory="zss">org.zkoss.zss.ui.event.EditboxEditingEvent</javadoc> on receiving this event.
  
 
===Registering Editing Events===
 
===Registering Editing Events===
Editing 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 [http://books.zkoss.org/wiki/ZK_Developer's_Reference/MVC ZK MVC] way i.e. using naming convention of <editing-event-name>$<component-id>. Here is an example shown using first way
+
Editing 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_Developer's_Reference/MVC| ZK MVC]] way i.e. using naming convention of <editing-event-name>$<component-id>. Here is an example shown using the first way.
 
<source lang="java">
 
<source lang="java">
 
...
 
...
Line 26: Line 29:
 
'''Note''': All ZK Spreadsheet supported events have a corresponding static constants declared in <code>org.zkoss.zss.ui.event.Events</code> class. For example for onStartEditing event there is <code>org.zkoss.zss.ui.event.Events.ON_START_EDITING</code> and so on.
 
'''Note''': All ZK Spreadsheet supported events have a corresponding static constants declared in <code>org.zkoss.zss.ui.event.Events</code> class. For example for onStartEditing event there is <code>org.zkoss.zss.ui.event.Events.ON_START_EDITING</code> and so on.
  
Here is an example shown using second way
+
Here is an example shown using the second way.
 
<source lang="java">
 
<source lang="java">
 
...
 
...
Line 41: Line 44:
 
<zk>
 
<zk>
 
<window title="ZSS Editing Events" border="normal" width="100%"
 
<window title="ZSS Editing Events" border="normal" width="100%"
height="100%" apply="org.zkoss.zssessentials.events.EditingEventsComposer"">
+
height="100%" apply="org.zkoss.zssessentials.events.EditingEventsComposer">
 
<hlayout>
 
<hlayout>
 
<label value="Edit Box:"></label>
 
<label value="Edit Box:"></label>
Line 53: Line 56:
  
 
===Composer===
 
===Composer===
In your composer.
+
In your composer,
 
<source lang="java">
 
<source lang="java">
 
public class EditingEventsComposer extends GenericForwardComposer {
 
public class EditingEventsComposer extends GenericForwardComposer {
Line 93: Line 96:
 
</source>
 
</source>
  
Each of the editing events gives you currently editing value by calling <javadoc directory="zss" method="getEditingValue()">org.zkoss.zss.ui.event.EditboxEditingEvent</javadoc> on editing event.
+
Each of the editing events gives you the currently editing value by calling <javadoc directory="zss" method="getEditingValue()">org.zkoss.zss.ui.event.EditboxEditingEvent</javadoc> on editing event.
 
View the complete source code for composer [https://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/src/org/zkoss/zssessentials/events/EditingEventsComposer.java here]
 
View the complete source code for composer [https://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/src/org/zkoss/zssessentials/events/EditingEventsComposer.java here]
  

Latest revision as of 06:42, 22 August 2013



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 event listeners for editing events such as onStartEditing and onStopEditing to control and/or limit what is being entered in specific ZK Spreadsheet cell and also apply some style/value transformation.

Purpose

Implement onStartEditing, onStopEditing and onEditboxEditing event listeners.

Editing events

There are three editing events that ZK Spreadsheet supports.

  • onStartEditing - This event is fired when the user starts editing a cell. It is fired only once at the beginning when the first key is pressed when the user starts editing. Event listeners are provided with StartEditingEvent on receiving this event.
  • onStopEditing - This event is fired when the user has finished editing a cell. It is identified by the user hitting the enter key or clicking outside of the editing cell. Event listeners are provided with StopEditingEvent on receiving this event.
  • onEditboxEditing - This event is fired when the user is ediing a cell and it is similar to textbox component onChanging event. Event listeners are provided with EditboxEditingEvent on receiving this event.

Registering Editing Events

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

...
ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_START_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStartEditingEvent((StartEditingEvent) event);
					}
				});
...

Note: All ZK Spreadsheet supported events have a corresponding static constants declared in org.zkoss.zss.ui.event.Events class. For example for onStartEditing event there is org.zkoss.zss.ui.event.Events.ON_START_EDITING and so on.

Here is an example shown using the second way.

...
	public void onStartEditing$ss(StartEditingEvent event) {
		// for example you can restrict which cells can be edited here
	}
...

ZUML

Here is a sample example ZUL file

<?page title="ZSS" contentType="text/html;charset=UTF-8"?>
<zk>
	<window title="ZSS Editing Events" border="normal" width="100%"
		height="100%" apply="org.zkoss.zssessentials.events.EditingEventsComposer">
		<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>
	</window>
</zk>

Composer

In your composer,

public class EditingEventsComposer extends GenericForwardComposer {

	private transient Spreadsheet ss;
	private transient Textbox editBox;
	
	public void doAfterCompose(Component comp) throws Exception {
		super.doAfterCompose(comp);
		ss.addEventListener(Events.ON_EDITBOX_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doEditboxEditingEvent((EditboxEditingEvent) event);
					}
				});
		ss.addEventListener(Events.ON_START_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStartEditingEvent((StartEditingEvent) event);
					}
				});
		ss.addEventListener(Events.ON_STOP_EDITING,
				new EventListener() {
					public void onEvent(Event event) throws Exception {
						doStopEditingEvent((StopEditingEvent) event);
					}
				});
	}
	private void doEditboxEditingEvent(EditboxEditingEvent event) {
		editBox.setValue((String) event.getEditingValue());
	}
	private void doStartEditingEvent(StartEditingEvent event) {
		// for example you can restrict which cells can be edited here
	}
	private void doStopEditingEvent(StopEditingEvent event) {
		// for example you can apply value or style transformation here on entered value
	}
}

Each of the editing events gives you the currently editing value by calling EditboxEditingEvent.getEditingValue() on editing event. View the complete source code for composer here

Version History

Last Update : 2013/08/22


Version Date Content
     


All source code listed in this book is at Github.


Last Update : 2013/08/22

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