Jump to: navigation, search

Difference between revisions of "SWTBot/Keyboard Layouts"

(added a page for keyboard layouts)
 
m (fixed a link)
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{SWTBot}}
 
= Keyboard Layouts in SWTBot =
 
= Keyboard Layouts in SWTBot =
  
== Introduction ==
+
== Keyboard strategies ==
Since the changes in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=273624 bug 273624: Provide native keyboard support for use with Display.post] it is now possible to send native keyboard events to widgets. SWTBot provides for pluggable strategies to be able to send events to your applications. Some strategies require that they understand different types of keyboard layouts.
+
  
== Why keyboard layouts are important ==
+
SWTBot can send keyboard events using different strategies:
Assuming that CAPS LOCK is turned off, if you need to type the string 'Hello'. You need to press the following key sequence: SHIFT+H, E, L, L, O. Similarly special characters like !, #, $, :, " etc need special treatment.
+
  
The keyboard layout determines how these characters are typed on the keyboard. A SHIFT+3 on a UK keyboard represents a '#' while on a UK keyboard it represents a '£'.
+
* AWTKeyboardStrategy uses the AWT Robot class, which works independently from the widget toolkit.
 +
* SWTKeyboardStrategy uses SWT Display#post, see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=273624 273624: Provide native keyboard support for use with Display.post].
 +
* MockKeyboardStrategy uses Widget#notifyListeners.
  
== How do you define your own keyboard layout ? ==
+
These different strategies are made available because the keyboard handling is very different depending on the native widget toolkit, keyboard layout and operating system / JRE / SWT version. Not all strategies work in all cases, see [http://www.eclipse.org/forums/index.php?t=msg&&th=166090#msg_526484 KeyboardTest & non EN keyboards] to learn more about the reasons why different strategies are provided.
To define your keyboard layout either:
+
* set the system property "org.eclipse.swtbot.keyboard.layout" OR
+
* set the variable SWTBotPreferences#KEYBOARD_LAYOUT
+
  
The value of this property should be of the form foo.bar.baz.[MAC.][upper-case-two-character-country-code]. For e.g. com.foo.bar.US or com.foo.bar.MAC.FR. The prefix ".MAC" is required for macosx keyboard.
+
== Keyboard layouts ==
  
Once you've defined the property, it is required to define the keyboard layout. For this purpose you need to create a config file called [MAC.][upper-case-two-character-country-code].keyboard in the package com.foo.bar.baz. For e.g. com/foo/bar/US.keyboard or com/foo/bar/MAC.FR.keyboard.
+
The Keyboard strategies need to send events with key codes, not with characters. For example, for a QWERTY/Z keyboard layout, to type the character '!', you need to press "SHIFT+1" and these events will be generated:
  
See [http://github.com/ketan/swtbot/blob/85bc95a52c70fb3ce4702734cf584a74148d4b14/org.eclipse.swtbot.swt.finder.test/src/org/eclipse/swtbot/swt/finder/keyboard/KeyboardLayoutTest.java#L28 KeyboardLayoutTest] for how this is defined and [http://github.com/ketan/swtbot/tree/master/org.eclipse.swtbot.swt.finder.test/src/com/foo/bar the folder containing the layouts] for an example.
+
* KeyDown Shift
 +
* KeyDown 1
 +
* KeyUp 1
 +
* KeyUp Shift
  
== Configuration file format ==
+
This effectively closely simulates a normal human being typing at a keyboard. In order to configure SWTBot to work with various keyboard layouts, SWTBot contains '.keyboard' files which define a mapping from characters to keys combinations, for example the character '!' maps to the keystrokes 'SHIFT+1' (on a US keyboard). This mapping is different depending on the keyboard layout of the system executing the tests. SWTBot includes some keyboard layouts, but the layout for your keyboard may be not available as of now. Please read further in case your layout is unavailable.
  
Next comes the configuration file format. The file is a simple text file with the following format:
+
== Keyboard configuration ==
 +
 
 +
By default, SWTBot uses the AWT keyboard strategy. This can be configured using the system property "org.eclipse.swtbot.keyboard.strategy" or the variable [http://download.eclipse.org/technology/swtbot/helios/dev-build/apidocs/org/eclipse/swtbot/swt/finder/utils/SWTBotPreferences.html#KEYBOARD_STRATEGY SWTBotPreferences#KEYBOARD_STRATEGY].
 +
 
 +
== Creating keyboard layouts ==
 +
 
 +
If your keyboard is missing, please file a bug for SWTBot in [http://bugs.eclipse.org Bugzilla]. Please mention the country code and operation system.
 +
 
 +
The keyboard layout is automatically detected from the system. To define the keyboard layout explicitly, you can set the system property "org.eclipse.swtbot.keyboard.layout" or set the variable [http://download.eclipse.org/technology/swtbot/helios/dev-build/apidocs/org/eclipse/swtbot/swt/finder/utils/SWTBotPreferences.html#KEYBOARD_LAYOUT SWTBotPreferences#KEYBOARD_LAYOUT].
 +
 
 +
The value of the keyboard layout property should be of the form [package.name.][MAC.][upper-case-two-character-country-code]. For e.g. com.foo.bar.DE (for a German keyboard) or com.foo.bar.MAC.FR (for a French keyboard on a mac). If the package name is omitted, the layout is loaded from the SWTBot package org.eclipse.swtbot.swt.finder.keyboard. The prefix "MAC." marks keyboard layouts for Mac keyboards.
 +
 
 +
Keyboard layouts can be created using the [http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.swt.finder.test/src/org/eclipse/swtbot/swt/finder/keyboard/KeyboardLayoutGenerator.java KeyboardLayoutGenerator] class in the 'org.eclipse.swtbot.swt.finder.test' bundle. This class is not packaged with SWTBot, you will need to download this from the [[SWTBot/Contributing | SWTBot source repository]].
 +
 
 +
To create keyboard mappings for your keyboard:
 +
 
 +
* Checkout the bundle 'org.eclipse.swtbot.swt.finder.test'
 +
* Change method Keys#specialChars() for your keyboard.
 +
* Execute KeyboardLayoutGenerator, this will generate a file 'keyboard.layout' containing keyboard mappings.
 +
* Execute KeyboardLayoutFilter, this will generate a file keyboard.layout.filtered containing filtered keyboard mappings.
 +
* Ensure that keyboard.layout.filtered is correct and not missing anything obvious, edit if necessary.
 +
* Rename keyboard.layout.filtered to [COUNTRY_CODE].keyboard.
 +
* You should execute the SWTKeyboardTest and/or AWTKeyboardTest test classes to check if your .keyboard file is working properly.
 +
* Please file a bug to contribute the keyboard layout once you got it working or attach it to your bug for the missing keyboard layout!
 +
 
 +
== .keyboard file format ==
 +
 
 +
See [http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.swt.finder/src/org/eclipse/swtbot/swt/finder/keyboard/EN_US.keyboard EN_US.keyboard] for an example of the US English keyboard layout, and [http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.swt.finder/src/org/eclipse/swtbot/swt/finder/keyboard/MAC_EN_US.keyboard MAC_EN_US.keyboard] for the corresponding keyboard layout on a mac.
 +
 
 +
.keyboard files are simple text files with the following format:
  
 
<pre>
 
<pre>
Line 28: Line 58:
 
</pre>
 
</pre>
  
The <CHARACTER> is the complex character that needs to be typed, and the <KEY_COMBINATION> is the combination that types the <CHARACTER>. Valid <KEY_COMBINATION>s are:
+
The <CHARACTER> is the complex character that needs to be typed, and the <KEY_COMBINATION> is the combination that types the <CHARACTER>. Valid <KEY_COMBINATION>s are: CTRL, SHIFT, ALT, COMMAND and all other keys on the keyboard, capitalized ( 'T' is valid, 't' is not). Similarly '3' on a US keyboard is valid, '#' is not.
* CTRL
+
* SHIFT
+
* ALT
+
* COMMAND
+
* any other keys on the keyboard, capitalized. 'T' is valid, 't' is not. Similarly '3' on a US keyboard is valid '#' is not.
+
  
An example is:
+
For example:
 
<pre>
 
<pre>
 
! shift + 1
 
! shift + 1
Line 42: Line 67:
 
$ shift + 4
 
$ shift + 4
 
</pre>
 
</pre>
[[Category: SWTBot]]
 

Revision as of 10:17, 9 July 2010


SWTBot
Website
Update Sites
Community
Mailing List
Forums/Newsgroups
IRC
Contribute
Open Bugzilla tickets
Open Gerrit reviews
Browse Source
Continuous Integration


Keyboard Layouts in SWTBot

Keyboard strategies

SWTBot can send keyboard events using different strategies:

These different strategies are made available because the keyboard handling is very different depending on the native widget toolkit, keyboard layout and operating system / JRE / SWT version. Not all strategies work in all cases, see KeyboardTest & non EN keyboards to learn more about the reasons why different strategies are provided.

Keyboard layouts

The Keyboard strategies need to send events with key codes, not with characters. For example, for a QWERTY/Z keyboard layout, to type the character '!', you need to press "SHIFT+1" and these events will be generated:

  • KeyDown Shift
  • KeyDown 1
  • KeyUp 1
  • KeyUp Shift

This effectively closely simulates a normal human being typing at a keyboard. In order to configure SWTBot to work with various keyboard layouts, SWTBot contains '.keyboard' files which define a mapping from characters to keys combinations, for example the character '!' maps to the keystrokes 'SHIFT+1' (on a US keyboard). This mapping is different depending on the keyboard layout of the system executing the tests. SWTBot includes some keyboard layouts, but the layout for your keyboard may be not available as of now. Please read further in case your layout is unavailable.

Keyboard configuration

By default, SWTBot uses the AWT keyboard strategy. This can be configured using the system property "org.eclipse.swtbot.keyboard.strategy" or the variable SWTBotPreferences#KEYBOARD_STRATEGY.

Creating keyboard layouts

If your keyboard is missing, please file a bug for SWTBot in Bugzilla. Please mention the country code and operation system.

The keyboard layout is automatically detected from the system. To define the keyboard layout explicitly, you can set the system property "org.eclipse.swtbot.keyboard.layout" or set the variable SWTBotPreferences#KEYBOARD_LAYOUT.

The value of the keyboard layout property should be of the form [package.name.][MAC.][upper-case-two-character-country-code]. For e.g. com.foo.bar.DE (for a German keyboard) or com.foo.bar.MAC.FR (for a French keyboard on a mac). If the package name is omitted, the layout is loaded from the SWTBot package org.eclipse.swtbot.swt.finder.keyboard. The prefix "MAC." marks keyboard layouts for Mac keyboards.

Keyboard layouts can be created using the KeyboardLayoutGenerator class in the 'org.eclipse.swtbot.swt.finder.test' bundle. This class is not packaged with SWTBot, you will need to download this from the SWTBot source repository.

To create keyboard mappings for your keyboard:

  • Checkout the bundle 'org.eclipse.swtbot.swt.finder.test'
  • Change method Keys#specialChars() for your keyboard.
  • Execute KeyboardLayoutGenerator, this will generate a file 'keyboard.layout' containing keyboard mappings.
  • Execute KeyboardLayoutFilter, this will generate a file keyboard.layout.filtered containing filtered keyboard mappings.
  • Ensure that keyboard.layout.filtered is correct and not missing anything obvious, edit if necessary.
  • Rename keyboard.layout.filtered to [COUNTRY_CODE].keyboard.
  • You should execute the SWTKeyboardTest and/or AWTKeyboardTest test classes to check if your .keyboard file is working properly.
  • Please file a bug to contribute the keyboard layout once you got it working or attach it to your bug for the missing keyboard layout!

.keyboard file format

See EN_US.keyboard for an example of the US English keyboard layout, and MAC_EN_US.keyboard for the corresponding keyboard layout on a mac.

.keyboard files are simple text files with the following format:

<CHARACTER> <KEY_COMBINATION>

The <CHARACTER> is the complex character that needs to be typed, and the <KEY_COMBINATION> is the combination that types the <CHARACTER>. Valid <KEY_COMBINATION>s are: CTRL, SHIFT, ALT, COMMAND and all other keys on the keyboard, capitalized ( 'T' is valid, 't' is not). Similarly '3' on a US keyboard is valid, '#' is not.

For example:

! shift + 1
@ shift + 2
# shift + 3
$ shift + 4