Editing Events"

From Documentation
(Created page with '{{ZKSpreadsheetEssentialsPageHeader}} __TOC__ Users can write event listeners for editing events such as onStartEditing and onStopEditing to control and/or limit what is being …')
 
 
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
{{ZKSpreadsheetEssentialsPageHeader}}
 
{{ZKSpreadsheetEssentialsPageHeader}}
 +
 +
 +
{{Deprecated|url=http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials}}
  
 
__TOC__
 
__TOC__
  
 
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.
 
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==
+
===Purpose===
 
Implement onStartEditing, onStopEditing and onEditboxEditing event listeners.
 
Implement onStartEditing, onStopEditing and onEditboxEditing event listeners.
==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 <code>org.zkoss.zss.ui.event.StartEditingEvent</code> 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 <code>org.zkoss.zss.ui.event.StopEditingEvent</code> 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 <code>org.zkoss.zss.ui.event.EditboxEditingEvent</code> 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==
+
 
Editing events can be registered to ZK Spreadsheet using <code>Spreadsheet#addEventListener()</code> as shown below
+
===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 [[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">
 
...
 
...
ss.addEventListener(Events.ON_START_EDITING,
+
ss.addEventListener(org.zkoss.zss.ui.event.Events.ON_START_EDITING,
 
new EventListener() {
 
new EventListener() {
 
public void onEvent(Event event) throws Exception {
 
public void onEvent(Event event) throws Exception {
Line 24: Line 28:
 
</source>
 
</source>
 
'''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.
==Example==
+
 
 +
Here is an example shown using the second way.
 +
<source lang="java">
 +
...
 +
public void onStartEditing$ss(StartEditingEvent event) {
 +
// for example you can restrict which cells can be edited here
 +
}
 +
...
 +
</source>
 +
 
 +
===ZUML===
 
Here is a sample example ZUL file
 
Here is a sample example 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 Editing Events" border="normal" width="100%" height="100%" apply="org.zkoss.zss.example.EditEventComposer">
+
<window title="ZSS Editing Events" border="normal" width="100%"
        <spreadsheet id="ss" width="800px" height="800px" maxrows="20" maxcolumns="10" src="/test2/xls/edit.xlsx"></spreadsheet>
+
height="100%" apply="org.zkoss.zssessentials.events.EditingEventsComposer">
    </window>
+
<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></source>
 
</zk></source>
In your composer.
+
 
 +
===Composer===
 +
In your composer,
 
<source lang="java">
 
<source lang="java">
public class EditEventComposer extends GenericForwardComposer {
+
public class EditingEventsComposer extends GenericForwardComposer {
  
 
private transient Spreadsheet ss;
 
private transient Spreadsheet ss;
Line 65: Line 88:
 
}
 
}
 
private void doStartEditingEvent(StartEditingEvent event) {
 
private void doStartEditingEvent(StartEditingEvent event) {
// you can restrict which cells can be edited here
+
// for example you can restrict which cells can be edited here
 
}
 
}
 
private void doStopEditingEvent(StopEditingEvent event) {
 
private void doStopEditingEvent(StopEditingEvent event) {
// you can apply value or style transformation here on entered value
+
// for example you can apply value or style transformation here on entered value
 
}
 
}
 
}
 
}
 
</source>
 
</source>
  
Each of the editing events gives you currently editing value by calling <code>getEditingValue()</code> 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]
  
 
=Version History=
 
=Version History=

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.