From: Marc Englund Date: Fri, 9 Apr 2010 08:45:41 +0000 (+0000) Subject: Javadocced shortcuts X-Git-Tag: 6.7.0.beta1~1763 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=d3b01e81254ae0da3028820524abba23866f7f7d;p=vaadin-framework.git Javadocced shortcuts svn changeset:12421/svn branch:6.3 --- diff --git a/src/com/vaadin/event/ShortcutAction.java b/src/com/vaadin/event/ShortcutAction.java index 25212bc590..7b167420ae 100644 --- a/src/com/vaadin/event/ShortcutAction.java +++ b/src/com/vaadin/event/ShortcutAction.java @@ -8,10 +8,34 @@ import java.io.Serializable; import java.util.regex.Matcher; import java.util.regex.Pattern; +import com.vaadin.event.Action.Handler; +import com.vaadin.event.Action.Notifier; import com.vaadin.terminal.Resource; +import com.vaadin.ui.ComponentContainer; +import com.vaadin.ui.Panel; +import com.vaadin.ui.Window; /** - * Extends Action class with keyboard bindings. TODO: fix documentation. + * Shortcuts are a special type of {@link Action}s used to create keyboard + * shortcuts. + *

+ * The ShortcutAction is triggered when the user presses a given key in + * combination with the (optional) given modifier keys. + *

+ *

+ * ShortcutActions can be global (by attaching to the {@link Window}), or + * attached to different parts of the UI so that a specific shortcut is only + * valid in part of the UI. For instance, one can attach shortcuts to a specific + * {@link Panel} - look for {@link ComponentContainer}s implementing + * {@link Handler Action.Handler} or {@link Notifier Action.Notifier}. + *

+ *

+ * ShortcutActions have a caption that may be used to display the shortcut + * visually. This allows the ShortcutAction to be used as a plain Action while + * still reacting to a keyboard shortcut. Note that this functionality is not + * very well supported yet, but it might still be a good idea to give a caption + * to the shortcut. + *

* * @author IT Mill Ltd. * @version @@ -24,12 +48,40 @@ public class ShortcutAction extends Action { private final int[] modifiers; + /** + * Creates a shortcut that reacts to the given {@link KeyCode} and + * (optionally) {@link ModifierKey}s.
+ * The shortcut might be shown in the UI (e.g context menu), in which case + * the caption will be used. + * + * @param caption + * used when displaying the shortcut visually + * @param kc + * KeyCode that the shortcut reacts to + * @param m + * optional modifier keys + */ public ShortcutAction(String caption, int kc, int[] m) { super(caption); keyCode = kc; modifiers = m; } + /** + * Creates a shortcut that reacts to the given {@link KeyCode} and + * (optionally) {@link ModifierKey}s.
+ * The shortcut might be shown in the UI (e.g context menu), in which case + * the caption and icon will be used. + * + * @param caption + * used when displaying the shortcut visually + * @param icon + * used when displaying the shortcut visually + * @param kc + * KeyCode that the shortcut reacts to + * @param m + * optional modifier keys + */ public ShortcutAction(String caption, Resource icon, int kc, int[] m) { super(caption, icon); keyCode = kc; @@ -156,10 +208,21 @@ public class ShortcutAction extends Action { } } + /** + * Get the {@link KeyCode} that this shortcut reacts to (in combination with + * the {@link ModifierKey}s). + * + * @return keycode for this shortcut + */ public int getKeyCode() { return keyCode; } + /** + * Get the {@link ModifierKey}s required for the shortcut to react. + * + * @return modifier keys for this shortcut + */ public int[] getModifiers() { return modifiers; } diff --git a/src/com/vaadin/ui/AbstractField.java b/src/com/vaadin/ui/AbstractField.java index b2b38ffc65..17e82e86e4 100644 --- a/src/com/vaadin/ui/AbstractField.java +++ b/src/com/vaadin/ui/AbstractField.java @@ -20,6 +20,7 @@ import com.vaadin.data.Validator; import com.vaadin.data.Validator.InvalidValueException; import com.vaadin.event.Action; import com.vaadin.event.ActionManager; +import com.vaadin.event.ShortcutAction; import com.vaadin.event.ShortcutListener; import com.vaadin.terminal.CompositeErrorMessage; import com.vaadin.terminal.ErrorMessage; @@ -1189,6 +1190,12 @@ public abstract class AbstractField extends AbstractComponent implements Field, * Actions */ + /** + * Gets the {@link ActionManager} used to manage the + * {@link ShortcutListener}s added to this {@link Field}. + * + * @return the ActionManager in use + */ protected ActionManager getActionManager() { if (actionManager == null) { actionManager = new ActionManager(); @@ -1209,19 +1216,52 @@ public abstract class AbstractField extends AbstractComponent implements Field, } } + /** + * A ready-made {@link ShortcutListener} that focuses the given + * {@link Focusable} (usually a {@link Field}) when the keyboard shortcut is + * invoked. + * + */ public static class FocusShortcut extends ShortcutListener { protected Focusable focusable; + /** + * Creates a keyboard shortcut for focusing the given {@link Focusable} + * using the shorthand notation defined in {@link ShortcutAction}. + * + * @param focusable + * to focused when the shortcut is invoked + * @param shorthandCaption + * caption with keycode and modifiers indicated + */ public FocusShortcut(Focusable focusable, String shorthandCaption) { super(shorthandCaption); this.focusable = focusable; } + /** + * Creates a keyboard shortcut for focusing the given {@link Focusable}. + * + * @param focusable + * to focused when the shortcut is invoked + * @param keyCode + * keycode that invokes the shortcut + * @param modifiers + * modifiers required to invoke the shortcut + */ public FocusShortcut(Focusable focusable, int keyCode, int... modifiers) { super(null, keyCode, modifiers); this.focusable = focusable; } + /** + * Creates a keyboard shortcut for focusing the given {@link Focusable}. + * + * @param focusable + * to focused when the shortcut is invoked + * @param keyCode + * keycode that invokes the shortcut + */ public FocusShortcut(Focusable focusable, int keyCode) { this(focusable, keyCode, null); } diff --git a/src/com/vaadin/ui/Button.java b/src/com/vaadin/ui/Button.java index 038186ce16..2a38348105 100644 --- a/src/com/vaadin/ui/Button.java +++ b/src/com/vaadin/ui/Button.java @@ -10,12 +10,15 @@ import java.lang.reflect.Method; import java.util.Map; import com.vaadin.data.Property; -import com.vaadin.event.ShortcutListener; import com.vaadin.event.FieldEvents; +import com.vaadin.event.ShortcutAction; +import com.vaadin.event.ShortcutListener; import com.vaadin.event.FieldEvents.BlurEvent; import com.vaadin.event.FieldEvents.BlurListener; import com.vaadin.event.FieldEvents.FocusEvent; import com.vaadin.event.FieldEvents.FocusListener; +import com.vaadin.event.ShortcutAction.KeyCode; +import com.vaadin.event.ShortcutAction.ModifierKey; import com.vaadin.terminal.PaintException; import com.vaadin.terminal.PaintTarget; import com.vaadin.terminal.gwt.client.ui.VButton; @@ -379,23 +382,36 @@ public class Button extends AbstractField implements FieldEvents.BlurNotifier, removeListener(FocusEvent.EVENT_ID, FocusEvent.class, listener); } - + /* * Actions */ protected ClickShortcut clickShortcut; - public ClickShortcut setClickShortcut(int keyCode, int... modifiers) { - ClickShortcut old = clickShortcut; - if (old != null) { - removeShortcutListener(old); + /** + * Makes it possible to invoke a click on this button by pressing the given + * {@link KeyCode} and (optional) {@link ModifierKey}s.
+ * The shortcut is global (bound to the containing Window). + * + * @param keyCode + * the keycode for invoking the shortcut + * @param modifiers + * the (optional) modifiers for invoking the shortcut, null for + * none + */ + public void setClickShortcut(int keyCode, int... modifiers) { + if (clickShortcut != null) { + removeShortcutListener(clickShortcut); } clickShortcut = new ClickShortcut(this, keyCode, modifiers); addShortcutListener(clickShortcut); - return old; } + /** + * Removes the keyboard shortcut previously set with + * {@link #setClickShortcut(int, int...)}. + */ public void removeClickShortcut() { if (clickShortcut != null) { removeShortcutListener(clickShortcut); @@ -403,19 +419,53 @@ public class Button extends AbstractField implements FieldEvents.BlurNotifier, } } + /** + * A {@link ShortcutListener} specifically made to define a keyboard + * shortcut that invokes a click on the given button. + * + */ public static class ClickShortcut extends ShortcutListener { protected Button button; + /** + * Creates a keyboard shortcut for clicking the given button using the + * shorthand notation defined in {@link ShortcutAction}. + * + * @param button + * to be clicked when the shortcut is invoked + * @param shorthandCaption + * the caption with shortcut keycode and modifiers indicated + */ public ClickShortcut(Button button, String shorthandCaption) { super(shorthandCaption); this.button = button; } + /** + * Creates a keyboard shortcut for clicking the given button using the + * given {@link KeyCode} and {@link ModifierKey}s. + * + * @param button + * to be clicked when the shortcut is invoked + * @param keyCode + * KeyCode to react to + * @param modifiers + * optional modifiers for shortcut + */ public ClickShortcut(Button button, int keyCode, int... modifiers) { super(null, keyCode, modifiers); this.button = button; } + /** + * Creates a keyboard shortcut for clicking the given button using the + * given {@link KeyCode}. + * + * @param button + * to be clicked when the shortcut is invoked + * @param keyCode + * KeyCode to react to + */ public ClickShortcut(Button button, int keyCode) { this(button, keyCode, null); } diff --git a/src/com/vaadin/ui/Form.java b/src/com/vaadin/ui/Form.java index 009fc46cdc..0929c05b68 100644 --- a/src/com/vaadin/ui/Form.java +++ b/src/com/vaadin/ui/Form.java @@ -1282,6 +1282,16 @@ public class Form extends AbstractField implements Item.Editor, Buffered, Item, * ACTIONS */ + /** + * Gets the {@link ActionManager} responsible for handling {@link Action}s + * added to this Form.
+ * Note that Form has another ActionManager inherited from + * {@link AbstractField}. The ownActionManager handles Actions attached to + * this Form specifically, while the ActionManager in AbstractField + * delegates to the containing Window (i.e global Actions). + * + * @return + */ protected ActionManager getOwnActionManager() { if (ownActionManager == null) { ownActionManager = new ActionManager(this); diff --git a/src/com/vaadin/ui/Window.java b/src/com/vaadin/ui/Window.java index bfc36a5178..46074fb0ba 100644 --- a/src/com/vaadin/ui/Window.java +++ b/src/com/vaadin/ui/Window.java @@ -17,7 +17,10 @@ import java.util.Map; import java.util.Set; import com.vaadin.Application; +import com.vaadin.event.ShortcutAction; import com.vaadin.event.ShortcutListener; +import com.vaadin.event.ShortcutAction.KeyCode; +import com.vaadin.event.ShortcutAction.ModifierKey; import com.vaadin.terminal.DownloadStream; import com.vaadin.terminal.PaintException; import com.vaadin.terminal.PaintTarget; @@ -1804,16 +1807,31 @@ public class Window extends Panel implements URIHandler, ParameterHandler { */ protected CloseShortcut closeShortcut; - public CloseShortcut setCloseShortcut(int keyCode, int... modifiers) { - CloseShortcut old = closeShortcut; - if (old != null) { - removeAction(old); + /** + * Makes is possible to close the window by pressing the given + * {@link KeyCode} and (optional) {@link ModifierKey}s.
+ * Note that this shortcut only reacts while the window has focus, closing + * itself - if you want to close a subwindow from a parent window, use + * {@link #addAction(com.vaadin.event.Action)} of the parent window instead. + * + * @param keyCode + * the keycode for invoking the shortcut + * @param modifiers + * the (optional) modifiers for invoking the shortcut, null for + * none + */ + public void setCloseShortcut(int keyCode, int... modifiers) { + if (closeShortcut != null) { + removeAction(closeShortcut); } closeShortcut = new CloseShortcut(this, keyCode, modifiers); addAction(closeShortcut); - return old; } + /** + * Removes the keyboard shortcut previously set with + * {@link #setCloseShortcut(int, int...)}. + */ public void removeCloseShortcut() { if (closeShortcut != null) { removeAction(closeShortcut); @@ -1821,19 +1839,63 @@ public class Window extends Panel implements URIHandler, ParameterHandler { } } + /** + * A {@link ShortcutListener} specifically made to define a keyboard + * shortcut that closes the window. + * + * 
+     * 
+     *  // within the window using helper
+     *  subWindow.setCloseShortcut(KeyCode.ESCAPE, null);
+     *  
+     *  // or globally
+     *  getWindow().addAction(new Window.CloseShortcut(subWindow, KeyCode.ESCAPE));
+     * 
+     *
+ * + */ public static class CloseShortcut extends ShortcutListener { protected Window window; + /** + * Creates a keyboard shortcut for closing the given window using the + * shorthand notation defined in {@link ShortcutAction}. + * + * @param window + * to be closed when the shortcut is invoked + * @param shorthandCaption + * the caption with shortcut keycode and modifiers indicated + */ public CloseShortcut(Window window, String shorthandCaption) { super(shorthandCaption); this.window = window; } + /** + * Creates a keyboard shortcut for closing the given window using the + * given {@link KeyCode} and {@link ModifierKey}s. + * + * @param window + * to be closed when the shortcut is invoked + * @param keyCode + * KeyCode to react to + * @param modifiers + * optional modifiers for shortcut + */ public CloseShortcut(Window window, int keyCode, int... modifiers) { super(null, keyCode, modifiers); this.window = window; } + /** + * Creates a keyboard shortcut for closing the given window using the + * given {@link KeyCode}. + * + * @param window + * to be closed when the shortcut is invoked + * @param keyCode + * KeyCode to react to + */ public CloseShortcut(Window window, int keyCode) { this(window, keyCode, null); }