|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292 |
- ---
- title: Shortcut Keys
- order: 5
- layout: page
- ---
-
- [[advanced.shortcuts]]
- = Shortcut Keys
-
- Vaadin provides simple ways to define shortcut keys for field components, as
- well as to a default button, and a lower-level generic shortcut API based on
- actions.
-
- A __shortcut__ is an action that is executed when a key or key combination is
- pressed within a specific scope in the UI. The scope can be the entire
- [classname]#UI# or a [classname]#Window# inside it.
-
- [[advanced.shortcuts.defaultbutton]]
- == Shortcut Keys for Default Buttons
-
- You can add a __click shortcut__ to a button to set it as "default" button;
- pressing the defined key, typically Enter, in any component in the scope
- (sub-window or UI) causes a click event for the button to be fired.
-
- You can define a click shortcut with the [methodname]#setClickShortcut()#
- shorthand method:
-
-
- [source, java]
- ----
- // Have an OK button and set it as the default button
- Button ok = new Button("OK");
- ok.setClickShortcut(KeyCode.ENTER);
- ok.addStyleName(ValoTheme.BUTTON_PRIMARY);
- ----
-
- The [methodname]#setClickShortcut()# is a shorthand method to create, add, and
- manage a [classname]#ClickShortcut#, rather than to add it with
- [methodname]#addShortcutListener()#.
-
- Themes offer special button styles to show that a button is special. In the Valo
- theme, you can use the [literal]#++BUTTON_PRIMARY++# style name. The result can
- be seen in <<figure.advanced.shortcuts.defaultbutton>>.
-
- [[figure.advanced.shortcuts.defaultbutton]]
- .Default Button with Click Shortcut
- image::img/shortcut-defaultbutton.png[]
-
-
- [[advanced.shortcuts.focus]]
- == Field Focus Shortcuts
-
- You can define a shortcut key that sets the focus to a field component (any
- component that inherits [classname]#AbstractField#) by adding a
- [classname]#FocusShortcut# as a shortcut listener to the field.
-
- The constructor of the [classname]#FocusShortcut# takes the field component as
- its first parameter, followed by the key code, and an optional list of modifier
- keys, as listed in <<advanced.shortcuts.keycodes>>.
-
-
- [source, java]
- ----
- // A field with Alt+N bound to it
- TextField name = new TextField("Name (Alt+N)");
- name.addShortcutListener(
- new AbstractField.FocusShortcut(name, KeyCode.N,
- ModifierKey.ALT));
- layout.addComponent(name);
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#advanced.shortcut.focus[on-line example, window="_blank"].
-
- You can also specify the shortcut by a shorthand notation, where the shortcut
- key is indicated with an ampersand ( [literal]#++&++#).
-
-
- [source, java]
- ----
- // A field with Alt+A bound to it, using shorthand notation
- TextField address = new TextField("Address (Alt+A)");
- address.addShortcutListener(
- new AbstractField.FocusShortcut(address, "&Address"));
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#advanced.shortcut.focus[on-line example, window="_blank"].
-
- This is especially useful for internationalization, so that you can determine
- the shortcut key from the localized string.
-
-
- [[advanced.shortcuts.actions]]
- == Generic Shortcut Actions
-
- Shortcut keys can be defined as __actions__ using the
- [classname]#ShortcutAction# class. It extends the generic [classname]#Action#
- class that is used for example in [classname]#Tree# and [classname]#Table# for
- context menus. Currently, the only classes that accept
- [classname]#ShortcutAction#s are [classname]#Window# and [classname]#Panel#.
-
- To handle key presses, you need to define an action handler by implementing the
- [classname]#Handler# interface. The interface has two methods that you need to
- implement: [methodname]#getActions()# and [methodname]#handleAction()#.
-
- The [methodname]#getActions()# method must return an array of
- [classname]#Action# objects for the component, specified with the second
- parameter for the method, the [parameter]#sender# of an action. For a keyboard
- shortcut, you use a [classname]#ShortcutAction#. The implementation of the
- method could be following:
-
-
- [source, java]
- ----
- // Have the unmodified Enter key cause an event
- Action action_ok = new ShortcutAction("Default key",
- ShortcutAction.KeyCode.ENTER, null);
-
- // Have the C key modified with Alt cause an event
- Action action_cancel = new ShortcutAction("Alt+C",
- ShortcutAction.KeyCode.C,
- new int[] { ShortcutAction.ModifierKey.ALT });
-
- Action[] actions = new Action[] {action_cancel, action_ok};
-
- public Action[] getActions(Object target, Object sender) {
- if (sender == myPanel)
- return actions;
-
- return null;
- }
- ----
-
- The returned [classname]#Action# array may be static or you can create it
- dynamically for different senders according to your needs.
-
- The constructor of [classname]#ShortcutAction# takes a symbolic caption for the
- action; this is largely irrelevant for shortcut actions in their current
- implementation, but might be used later if implementors use them both in menus
- and as shortcut actions. The second parameter is the key code and the third a
- list of modifier keys, which are listed in <<advanced.shortcuts.keycodes>>.
-
- The following example demonstrates the definition of a default button for a user
- interface, as well as a normal shortcut key, AltC for clicking the
- [guibutton]#Cancel# button.
-
-
- [source, java]
- ----
- public class DefaultButtonExample extends CustomComponent
- implements Handler {
- // Define and create user interface components
- Panel panel = new Panel("Login");
- FormLayout formlayout = new FormLayout();
- TextField username = new TextField("Username");
- TextField password = new TextField("Password");
- HorizontalLayout buttons = new HorizontalLayout();
-
- // Create buttons and define their listener methods.
- Button ok = new Button("OK", this, "okHandler");
- Button cancel = new Button("Cancel", this, "cancelHandler");
-
- // Have the unmodified Enter key cause an event
- Action action_ok = new ShortcutAction("Default key",
- ShortcutAction.KeyCode.ENTER, null);
-
- // Have the C key modified with Alt cause an event
- Action action_cancel = new ShortcutAction("Alt+C",
- ShortcutAction.KeyCode.C,
- new int[] { ShortcutAction.ModifierKey.ALT });
-
- public DefaultButtonExample() {
- // Set up the user interface
- setCompositionRoot(panel);
- panel.addComponent(formlayout);
- formlayout.addComponent(username);
- formlayout.addComponent(password);
- formlayout.addComponent(buttons);
- buttons.addComponent(ok);
- buttons.addComponent(cancel);
-
- // Set focus to username
- username.focus();
-
- // Set this object as the action handler
- panel.addActionHandler(this);
- }
-
- /**
- * Retrieve actions for a specific component. This method
- * will be called for each object that has a handler; in
- * this example just for login panel. The returned action
- * list might as well be static list.
- */
- public Action[] getActions(Object target, Object sender) {
- System.out.println("getActions()");
- return new Action[] { action_ok, action_cancel };
- }
-
- /**
- * Handle actions received from keyboard. This simply directs
- * the actions to the same listener methods that are called
- * with ButtonClick events.
- */
- public void handleAction(Action action, Object sender,
- Object target) {
- if (action == action_ok) {
- okHandler();
- }
- if (action == action_cancel) {
- cancelHandler();
- }
- }
-
- public void okHandler() {
- // Do something: report the click
- formlayout.addComponent(new Label("OK clicked. "
- + "User=" + username.getValue() + ", password="
- + password.getValue()));
- }
-
- public void cancelHandler() {
- // Do something: report the click
- formlayout.addComponent(new Label("Cancel clicked. User="
- + username.getValue() + ", password="
- + password.getValue()));
- }
- }
- ----
-
- Notice that the keyboard actions can currently be attached only to
- [classname]#Panel#s and [classname]#Window#s. This can cause problems if you
- have components that require a certain key. For example, multi-line
- [classname]#TextField# requires the Enter key. There is currently no way to
- filter the shortcut actions out while the focus is inside some specific
- component, so you need to avoid such conflicts.
-
-
- [[advanced.shortcuts.keycodes]]
- == Supported Key Codes and Modifier Keys
-
- The shortcut key definitions require a key code to identify the pressed key and
- modifier keys, such as Shift, Alt, or Ctrl, to specify a key combination.
-
- The key codes are defined in the [classname]#ShortcutAction.KeyCode# interface
- and are:
-
- Keys [parameter]#A#to[parameter]#Z#:: Normal letter keys
- [parameter]#F1#to[parameter]#F12#:: Function keys
-
- [parameter]#BACKSPACE#,[parameter]#DELETE#,[parameter]#ENTER#,[parameter]#ESCAPE#,[parameter]#INSERT#,[parameter]#TAB#:: Control keys
-
- [parameter]#NUM0#to[parameter]#NUM9#:: Number pad keys
-
- [parameter]#ARROW_DOWN#,[parameter]#ARROW_UP#,[parameter]#ARROW_LEFT#,[parameter]#ARROW_RIGHT#:: Arrow keys
-
- [parameter]#HOME#,[parameter]#END#,[parameter]#PAGE_UP#,[parameter]#PAGE_DOWN#:: Other movement keys
-
-
-
- Modifier keys are defined in [classname]#ShortcutAction.ModifierKey# and are:
-
- [parameter]#ModifierKey.ALT#:: Alt key
- [parameter]#ModifierKey.CTRL#:: Ctrl key
- [parameter]#ModifierKey.SHIFT#:: Shift key
-
-
- All constructors and methods accepting modifier keys take them as a variable
- argument list following the key code, separated with commas. For example, the
- following defines a CtrlShiftN key combination for a shortcut.
-
-
- [source, java]
- ----
- TextField name = new TextField("Name (Ctrl+Shift+N)");
- name.addShortcutListener(
- new AbstractField.FocusShortcut(name, KeyCode.N,
- ModifierKey.CTRL,
- ModifierKey.SHIFT));
- ----
-
- === Supported Key Combinations
-
- The actual possible key combinations vary greatly between browsers, as most
- browsers have a number of built-in shortcut keys, which can not be used in web
- applications. For example, Mozilla Firefox allows binding almost any key
- combination, while Opera does not even allow binding Alt shortcuts. Other
- browsers are generally in between these two. Also, the operating system can
- reserve some key combinations and some computer manufacturers define their own
- system key combinations.
-
-
-
-
-
|