Keystroke Handling"

From Documentation
Line 41: Line 41:
 
Also notice that, if a button gains the focus, ENTER will be intercepted by the browser and interpreted as pressed. For example, if you move the focus to the Reset button and press ENTER, you will receive <tt>onCancel</tt> rather than <tt>onOK</tt> (since <tt>onClick</tt> will be fired and it is converted to <tt>onCancel</tt> because of [[ZUML Reference/ZUML/Attributes/forward|the forward attribute]] specified).
 
Also notice that, if a button gains the focus, ENTER will be intercepted by the browser and interpreted as pressed. For example, if you move the focus to the Reset button and press ENTER, you will receive <tt>onCancel</tt> rather than <tt>onOK</tt> (since <tt>onClick</tt> will be fired and it is converted to <tt>onCancel</tt> because of [[ZUML Reference/ZUML/Attributes/forward|the forward attribute]] specified).
 
=Control Keys=
 
=Control Keys=
 +
 +
To handle the control keys, you have to specify the keystrokes you want to handle with <javadoc method="setCtrlKeys(java.lang.String)">org.zkoss.zul.impl.XulElement</javadoc>. Then, if any child component gains the focus and the user presses a keystroke matches the combination, then the <tt>onCtrlKey</tt> will be sent to the component with an instance of <javadoc>org.zkoss.zk.ui.event.KeyEvent</javadoc>.
 +
 +
Like ENTER and ESC, you could specify the listener and the <tt>ctrlKeys</tt> property in one of the ancestor. ZK will search the component having the focus, its parent, its parent's parent and so on to find if any of them specifies the <tt>ctrlKeys</tt> property that matches the keystroke.
 +
 +
For example,
 +
 +
<source lang="xml">
 +
<vlayout ctrlKeys="@c^a#f10^#f3" onCtrlKey="doSomething(event.getKeyCode())">
 +
    <textbox/>
 +
    <datebox/>
 +
</vlayout>
 +
</source>
 +
 +
As shown, you could use <javadoc method="getKeyCode()">org.zkoss.zk.ui.event.KeyEvent</javadoc> to know which key was pressed.
 +
 +
== Allowed Control Keys ==
 +
 +
{| border="1" | width="100%"
 +
| <center>'''Key'''</center>
 +
| <center>'''Description'''</center>
 +
 +
|-
 +
| <center>^k</center>
 +
| The control key, i.e., <tt>Ctrl+k</tt>, where <tt>k</tt> can be a~z, 0~9, #n and ~n.
 +
 +
|-
 +
| <center>@k</center>
 +
| The alt key, i.e., <tt>Alt+k</tt>, where <tt>k</tt> can be a~z, 0~9, #n and ~n.
 +
 +
|-
 +
| <center>$k</center>
 +
| The shift key, i.e., <tt>Shift+k</tt>, can <tt>k</tt> could be #n and ~n.
 +
 +
|-
 +
| <center>#n</center>
 +
| A special key as follows.
 +
 +
 +
{| border="1" | width="100%"
 +
| <center>#home</center>
 +
| <center>Home</center>
 +
| <center>#end</center>
 +
| <center>End</center>
 +
| <center>#ins</center>
 +
| <center>Insert</center>
 +
 +
|-
 +
| <center>#del</center>
 +
| <center>Delete</center>
 +
| <center>#left</center>
 +
| <center>←</center>
 +
| <center>#right</center>
 +
| <center>→</center>
 +
 +
|-
 +
| <center>#up</center>
 +
| <center>↑</center>
 +
| <center>#down</center>
 +
| <center>↓</center>
 +
| <center>#pgup</center>
 +
| <center>PgUp</center>
 +
 +
|-
 +
| <center>#pgdn</center>
 +
| <center>PgDn</center>
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
| <center>#f''n''</center>
 +
| colspan="5" |  A function key. #f1, #f2, ... #f12 for F1, F2,... F12.
 +
 +
|}
 +
|}
 +
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}

Revision as of 09:01, 21 December 2010


Keystroke Handling


Keystroke handling is generic. Any component inherited from XulElement can handle the key event in the same way.

ENTER and ESC

To handle ENTER, you could listen to the onOK event (notice O and K are both in upper case). To handle ESC, you could listen to the onCancel event. For example,

<grid id="form" apply="foo.Login">
    <rows>
        <row>Username: <textbox id="username"/></row>
        <row>Password: <textbox id="password" type="password"/></row>
        <row><button label="Login" forward="form.onOK"/><button label="Reset" forward="form.onCancel"/></row>
    </rows>
</grid>

Then, you could implement a composer as follows.

package foo;
import org.zkoss.zul.*;
public class Login extends org.zkoss.zk.ui.util.GenericForwardComposer {
    Textbox username;
    Textbox password;
    public void onOK() {
        //handle login
    }
    public void onCancel() {
        username.setValue("");
        password.setValue("");
    }
}

Notice that the onOK and onCancel events are sent to the nearest ancestor of the component that has the focus. In other words, if you press ENTER in a textbox, then ZK will look up the textbox, its parent, its parent's parent and so on to see if any of them has been registered a listener for onOK. If found, the event is sent to it. If not found, nothing happens.

Also notice that, if a button gains the focus, ENTER will be intercepted by the browser and interpreted as pressed. For example, if you move the focus to the Reset button and press ENTER, you will receive onCancel rather than onOK (since onClick will be fired and it is converted to onCancel because of the forward attribute specified).

Control Keys

To handle the control keys, you have to specify the keystrokes you want to handle with XulElement.setCtrlKeys(String). Then, if any child component gains the focus and the user presses a keystroke matches the combination, then the onCtrlKey will be sent to the component with an instance of KeyEvent.

Like ENTER and ESC, you could specify the listener and the ctrlKeys property in one of the ancestor. ZK will search the component having the focus, its parent, its parent's parent and so on to find if any of them specifies the ctrlKeys property that matches the keystroke.

For example,

<vlayout ctrlKeys="@c^a#f10^#f3" onCtrlKey="doSomething(event.getKeyCode())">
    <textbox/>
    <datebox/>
</vlayout>

As shown, you could use KeyEvent.getKeyCode() to know which key was pressed.

Allowed Control Keys

Key
Description
^k
The control key, i.e., Ctrl+k, where k can be a~z, 0~9, #n and ~n.
@k
The alt key, i.e., Alt+k, where k can be a~z, 0~9, #n and ~n.
$k
The shift key, i.e., Shift+k, can k could be #n and ~n.
#n
A special key as follows.


#home
Home
#end
End
#ins
Insert
#del
Delete
#left
#right
#up
#down
#pgup
PgUp
#pgdn
PgDn
#fn
A function key. #f1, #f2, ... #f12 for F1, F2,... F12.

Version History

Last Update : 2010/12/21


Version Date Content
     


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