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
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;
}
}
+ /**
+ * 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;
}
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;
* 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();
}
}
+ /**
+ * 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);
}
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;
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);
}
}
+ /**
+ * 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);
}
* 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);
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;
*/
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);
}
}
+ /**
+ * 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);
}
projects / vaadin-framework.git / commitdiff