Javadocced shortcuts

svn changeset:12421/svn branch:6.3

5 files changed, 238 insertions, 13 deletions

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.
+ * <p>
+ * The ShortcutAction is triggered when the user presses a given key in
+ * combination with the (optional) given modifier keys.
+ * </p>
+ * <p>
+ * 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}.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
  * 
  * @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. <br/>
+     * 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. <br/>
+     * 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.<br/>
+     * 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.<br/>
+     * 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.<br/>
+     * 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.
+     * 
+     * <pre>
+     * <code>
+     *  // within the window using helper
+     *  subWindow.setCloseShortcut(KeyCode.ESCAPE, null);
+     *  
+     *  // or globally
+     *  getWindow().addAction(new Window.CloseShortcut(subWindow, KeyCode.ESCAPE));
+     * </code>
+     * </pre>
+     * 
+     */
     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);
         }