Key Event"

From Documentation
Line 6: Line 6:
  
 
* '''onCtrlKey'''
 
* '''onCtrlKey'''
*:  This event is fired when a user presses a key specified in <tt>ctrlKeys</tt> attribute. By default, Spreadsheet handles keys including '''ctrl+z, ctrl+y, ctrl+x, ctrl+c, ctrl+v,  ctrl+b, ctrl+i, ctrl+u, and delete key''' without specifying <tt>ctrlKeys</tt> on <tt><spreadsheet></tt>. If you want to override the default setting, please remember to append these default control keys (<tt>^Z^Y^X^C^V^B^I^U#del</tt>) to your setting. For example, if you want to support more keys like ctrl+a, you should set <tt>ctrlKeys</tt> to <tt>'''^A'''^Z^Y^X^C^V^B^I^U#del</tt>. Thus, you can still benefit from built-in key handling function. For syntax to set <tt>ctrlKeys</tt>, please refer to [[ZK Developer%27s Reference/UI Patterns/Keystroke Handling]]. When the corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.KeyEvent</javadoc> object is passed as an argument.
+
*:  This event is fired when a user presses a key specified in <tt>ctrlKeys</tt> attribute. By default, Spreadsheet handles keys including '''ctrl+z, ctrl+y, ctrl+x, ctrl+c, ctrl+v,  ctrl+b, ctrl+i, ctrl+u, and delete key''' without specifying <tt>ctrlKeys</tt> on <tt><spreadsheet></tt>.
  
 
= Event Monitor Example =
 
= Event Monitor Example =
Line 34: Line 34:
 
* Line 8~12: Except knowing which key is pressed, we can also know that control, alt, or shift key are pressed or not via <tt>KeyEvent</tt>.
 
* Line 8~12: Except knowing which key is pressed, we can also know that control, alt, or shift key are pressed or not via <tt>KeyEvent</tt>.
  
== Known issue ==
+
 
 +
=Add More Shortcut Keys =
 +
If you want to add more shortcut keys to a ZSS component, remember to append the default control keys, <tt>^Z^Y^X^C^V^B^I^U#del</tt>. For example, if you want to add a shortcut key like '''ctrl+a,''' you should set <tt>ctrlKeys</tt> to <tt>'''^A'''^Z^Y^X^C^V^B^I^U#del</tt>. Thus, you can still benefit from built-in key handling function. For syntax used at the property <tt>ctrlKeys</tt>, please refer to [[ZK Developer%27s Reference/UI Patterns/Keystroke Handling]]. When the corresponding event listener is invoked, a <javadoc directory="zss">org.zkoss.zss.ui.event.KeyEvent</javadoc> object is passed as an argument.
 +
 
 +
 
 +
 
 +
=Overrideing Existing Shortcut Keys=
 +
Every shortcut key has a corresponding <javadoc directory='zss'>org.zkoss.zss.ui.UserActionHandler</javadoc> to perform its function like <javadoc directory='zss'> org.zkoss.zss.ui.impl.ua.CopyHandler</javadoc>. Implementing your key event listener cannot override existing shortcut keys' function because the listener is executed after UserActionHandler. Therefore, to override it you need to hook up your own UserActionHandler like:
 +
 
 +
<source lang='java' high='4'>
 +
Spreadsheet ss;
 +
//...
 +
UserActionManager manager = ss.getUserActionManager();
 +
manager.registerHandler(Category.KEYSTROKE.getName(), "^V", new MyCustomPasteHandler());
 +
</source>
 +
 
 +
Another way is:
 +
<source lang='java' high='4'>
 +
Spreadsheet ss;
 +
//...
 +
UserActionManager actionManager = ss.getUserActionManager();
 +
actionManager.setHandler(Category.KEYSTROKE.getName(), "^V", new MyCustomPasteHandler());
 +
</source>
 +
 
 +
Please refer to [[ZK_Spreadsheet_Essentials/Working_with_Spreadsheet/Advanced/Toolbar Customization| Toolbar_Customization]] for how to implement a UserActionHandler and the difference between <tt>registerHandler()</tt> and <tt>setHandler()</tt>
 +
 
 +
 
 +
 
 +
= Known issue =
 
There is a known issue [http://tracker.zkoss.org/browse/ZSS-920 ZSS-920], when you add spreadsheet as the child of root, you may trigger onCtrlEvent to server once you press delete key on BODY. To solve this issue, you can enclose spreadsheet tag by any other tags like DIV:
 
There is a known issue [http://tracker.zkoss.org/browse/ZSS-920 ZSS-920], when you add spreadsheet as the child of root, you may trigger onCtrlEvent to server once you press delete key on BODY. To solve this issue, you can enclose spreadsheet tag by any other tags like DIV:
  

Revision as of 08:44, 24 April 2015



Overview

There is one key event that ZK Spreadsheet supports:

  • onCtrlKey
    This event is fired when a user presses a key specified in ctrlKeys attribute. By default, Spreadsheet handles keys including ctrl+z, ctrl+y, ctrl+x, ctrl+c, ctrl+v, ctrl+b, ctrl+i, ctrl+u, and delete key without specifying ctrlKeys on <spreadsheet>.

Event Monitor Example

Zss-essentials-events-key.png

In Event Monitor example, the messages show that ctrl+c is pressed first then ctrl+v. Let's see how to make it:

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

	@Listen("onCtrlKey = #ss")
	public void onCtrlKey(KeyEvent event){
		StringBuilder info = new StringBuilder();
		
		info.append("Keys : ").append(event.getKeyCode())
			.append(", Ctrl:").append(event.isCtrlKey())
			.append(", Alt:").append(event.isAltKey())
			.append(", Shift:").append(event.isShiftKey());
		
		//display info...
	}
}
  • Line 4: 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~12: Except knowing which key is pressed, we can also know that control, alt, or shift key are pressed or not via KeyEvent.


Add More Shortcut Keys

If you want to add more shortcut keys to a ZSS component, remember to append the default control keys, ^Z^Y^X^C^V^B^I^U#del. For example, if you want to add a shortcut key like ctrl+a, you should set ctrlKeys to ^A^Z^Y^X^C^V^B^I^U#del. Thus, you can still benefit from built-in key handling function. For syntax used at the property ctrlKeys, please refer to ZK Developer's Reference/UI Patterns/Keystroke Handling. When the corresponding event listener is invoked, a KeyEvent object is passed as an argument.


Overrideing Existing Shortcut Keys

Every shortcut key has a corresponding UserActionHandler to perform its function like CopyHandler. Implementing your key event listener cannot override existing shortcut keys' function because the listener is executed after UserActionHandler. Therefore, to override it you need to hook up your own UserActionHandler like:

Spreadsheet ss;
//...
UserActionManager manager = ss.getUserActionManager();
manager.registerHandler(Category.KEYSTROKE.getName(), "^V", new MyCustomPasteHandler());

Another way is:

Spreadsheet ss;
//...
UserActionManager actionManager = ss.getUserActionManager();
actionManager.setHandler(Category.KEYSTROKE.getName(), "^V", new MyCustomPasteHandler());

Please refer to Toolbar_Customization for how to implement a UserActionHandler and the difference between registerHandler() and setHandler()


Known issue

There is a known issue ZSS-920, when you add spreadsheet as the child of root, you may trigger onCtrlEvent to server once you press delete key on BODY. To solve this issue, you can enclose spreadsheet tag by any other tags like DIV:

<zk>
	<div>
	   	<spreadsheet src="/issue3/book/blank.xlsx" height="300px" width="300px" 
   			showSheetbar="true" showContextMenu="true" showFormulabar="true"/>
	</div>
</zk>


All source code listed in this book is at Github.


Last Update : 2015/04/24

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