org.eesgmbh.gimv.client.controls
Class KeystrokeControl

java.lang.Object
  extended by org.eesgmbh.gimv.client.controls.KeystrokeControl

public class KeystrokeControl
extends Object

This control can be used to move the image with keystrokes, eg. with the arrow keys.

It is implemented as a Event.NativePreviewHandler, which will do something if the target Element of the keystroke (the receiver of the key event) is one of the elements registered here. To register an Element invoke addTargetElement(Element). The target element of the browser's key events is the one which is currently focused, e.g. because the user clicked on the element. Not all elements are focusable (e.g. an image is not, wheras a drop down menu is). If the user clicked on a non-focusable element, the target element is the document's HTML section (in FF) or the BODY section (in Chrome), IE seems to be able to focus on any element but its behavior is generally quirky.

If you register no element at all, the control will take action on the registered key strokes ignoring the target element. You may encounter problems with that approach. E.g. if the user scrolls through a drop down menu using the arrow keys the GIMV-image will react as well.

For optimal user experience register focusable elements like Viewport and also invoke addDocumentAndBodyAsTarget(). Test your setup by clicking on your user interface and verify that the keystroke control is still working (or not working where it should not). There might also be differences across browsers.

After target elements are specified, the respective keys including modifier key state can be registered in registerKey(int, Direction, int) or registerKey(int, boolean, boolean, boolean, boolean, Direction, int) with the respective move operations that should be invoked

A delay for firing LoadImageDataEvent can be specified. The default is 500ms. This means that (possibly expensive) image rendering is only triggered after the user did not hit a key for 500ms. The value can be change with setLoadImageDataEventFiringDelay(int). Thus, when the user presses a key, only the last of the resulting successive key events will lead to a LoadImageDataEvent.

Registers with the HandlerManager to receive the following events

Fires the following events


Constructor Summary
KeystrokeControl(HandlerManager handlerManager)
          Instantiates the control with default configuration.
 
Method Summary
 void addDocumentAndBodyAsTarget()
          React to keystroke events, even if the browser does not have an element under focus.
 void addTargetElement(Element element)
          Adds a target element.
 void registerKey(int keycode, boolean ctrl, boolean alt, boolean shift, boolean meta, Direction direction, int offsetInPixel)
          Registers a keystroke with a move operations.
 void registerKey(int keycode, Direction direction, int offsetInPixel)
          Registers a keystroke with a move operations.
 void setCancelEvent(boolean cancelEvent)
          Specify whether keystroke events will be canceled.
 void setFireChangeImagePixelBoundsEvent(boolean fireChangeImagePixelBoundsEvent)
          Specify whether the image gets immediately repositioned prior to loading the newly rendered one.
 void setFireLoadImageDataEvent(boolean fireLoadImageDataEvent)
          Specify whether a LoadImageDataEvent is fired.
 void setLoadImageDataEventFiringDelay(int delayInMillis)
          Sets the time in milliseconds for how long to defer firing a LoadImageDataEvent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeystrokeControl

public KeystrokeControl(HandlerManager handlerManager)
Instantiates the control with default configuration.

Parameters:
handlerManager - A HandlerManager
Method Detail

addTargetElement

public void addTargetElement(Element element)
Adds a target element.

Parameters:
element - Target element. Can be obtained from a widget by calling UIObject.getElement()

addDocumentAndBodyAsTarget

public void addDocumentAndBodyAsTarget()
React to keystroke events, even if the browser does not have an element under focus. Has an effect in FF and Chrome.


registerKey

public void registerKey(int keycode,
                        Direction direction,
                        int offsetInPixel)
Registers a keystroke with a move operations. By default no modifier key like CTRL or ALT must be down.

Parameters:
keycode - One of the constants in KeyCodes
direction - The direction to move the image to
offsetInPixel - How much to move the image in pixels

registerKey

public void registerKey(int keycode,
                        boolean ctrl,
                        boolean alt,
                        boolean shift,
                        boolean meta,
                        Direction direction,
                        int offsetInPixel)
Registers a keystroke with a move operations. The state of the modifier keys can be specified.

Parameters:
keycode - One of the constants in KeyCodes
ctrl - Should the modifier be down
alt - Should the modifier be down
shift - Should the modifier be down
meta - Should the modifier be down
direction - The direction to move the image to
offsetInPixel - How much to move the image in pixels

setCancelEvent

public void setCancelEvent(boolean cancelEvent)
Specify whether keystroke events will be canceled.

This means that if you register the arrow keys and set cancelEvent to true, scrolling the browser's window with the arrow keys becomes impossible (as the browser is not informed about the keystroke).

The default is false.

Parameters:
cancelEvent -

setFireLoadImageDataEvent

public void setFireLoadImageDataEvent(boolean fireLoadImageDataEvent)

Specify whether a LoadImageDataEvent is fired.

Default is true.

Parameters:
fireLoadImageDataEvent - fire it, or not

setFireChangeImagePixelBoundsEvent

public void setFireChangeImagePixelBoundsEvent(boolean fireChangeImagePixelBoundsEvent)

Specify whether the image gets immediately repositioned prior to loading the newly rendered one.

Default is true.

Parameters:
fireChangeImagePixelBoundsEvent -

setLoadImageDataEventFiringDelay

public void setLoadImageDataEventFiringDelay(int delayInMillis)
Sets the time in milliseconds for how long to defer firing a LoadImageDataEvent.

The default value is 500 ms. This means that 500 ms have to pass after the last keystroke until a LoadImageDataEvent is fired causing the image to be newly rendered. If multiple keystrokes were received during that period, the new image bounds will be the 'sum' of all these keystrokes.
The value of 500ms was chosen to match the auto-repeat of most keyboards.

This helps to reduce server load where image rendering might take place.

Parameters:
delayInMillis - A millisecond value. Pass in 0 (zero) to deactivate delayed firing of LoadImageDataEvent


Copyright © 2010 - EES GmbH