Difference between revisions of "SWTBot/Keyboard Layouts"
m (using templates for creating links) |
(Revised keyboard documentation, please proof-read) |
||
| Line 2: | Line 2: | ||
= Keyboard Layouts in SWTBot = | = Keyboard Layouts in SWTBot = | ||
| − | == | + | == Keyboard strategies == |
| − | + | ||
| − | + | SWTBot can send keyboard events. Sending the keyboard notifications is carried out by SWTBot's keyboard strategies: | |
| − | + | ||
| − | + | * 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. | ||
| − | + | These different strategies are made available because keyboard support is a brittle thing in general. Your mileage may vary depending on whether you use the 'swt/awt/mock' keyboard type, your specific swt version, your jre version and the specific bugs that are associated with those versions. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | == 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 | ||
| − | + | SWTBot comes with '.keyboard' files which define a mapping from characters to keys, for example from character '!' to the keystrokes 'SHIFT+1'. 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 might be not available as of now. | |
| − | + | == 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. | ||
| + | |||
| + | 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.US or com.foo.bar.MAC.FR. 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. | ||
| + | |||
| + | == 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. | ||
| + | |||
| + | Keyboard layouts can be created using a generator class in the 'org.eclipse.swtbot.swt.finder.test' bundle. You need to get this from the SWTBot repository, see [[SWTBot/Contributing]]. To create keyboard mappings for your keyboard: | ||
| + | |||
| + | * Change Keys#specialChars() accordingly for your keyboard. | ||
| + | * Execute KeyboardLayoutGenerator followed by KeyboardLayoutFilter | ||
| + | * Files keyboard.layout and keyboard.layout.filtered will be generated in the root of the plug-in. | ||
| + | * Rename keyboard.layout.filtered to [COUNTRY_CODE].keyboard. | ||
| + | * You probably need to check and edit this file manually. | ||
| + | * 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 == | ||
| + | |||
| + | .keyboard files are simple text files with the following format: | ||
<pre> | <pre> | ||
| Line 29: | Line 53: | ||
</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. |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | For example: | |
<pre> | <pre> | ||
! shift + 1 | ! shift + 1 | ||
Revision as of 08:19, 11 April 2010
| SWTBot |
| Website |
| Update Sites |
| Community |
| Mailing List |
| Forums/Newsgroups |
| IRC |
| Contribute |
| Open Bugzilla tickets |
| Open Gerrit reviews |
| Browse Source |
| Continuous Integration |
Contents
Keyboard Layouts in SWTBot
Keyboard strategies
SWTBot can send keyboard events. Sending the keyboard notifications is carried out by SWTBot's keyboard strategies:
- AWTKeyboardStrategy uses the AWT Robot class, which works independently from the widget toolkit.
- SWTKeyboardStrategy uses SWT Display#post, see 273624: Provide native keyboard support for use with Display.post.
- MockKeyboardStrategy uses Widget#notifyListeners.
These different strategies are made available because keyboard support is a brittle thing in general. Your mileage may vary depending on whether you use the 'swt/awt/mock' keyboard type, your specific swt version, your jre version and the specific bugs that are associated with those versions.
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
SWTBot comes with '.keyboard' files which define a mapping from characters to keys, for example from character '!' to the keystrokes 'SHIFT+1'. 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 might be not available as of now.
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.
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.US or com.foo.bar.MAC.FR. 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.
Creating keyboard layouts
If your keyboard is missing, please file a bug for SWTBot in Bugzilla. Please mention the country code and operation system.
Keyboard layouts can be created using a generator class in the 'org.eclipse.swtbot.swt.finder.test' bundle. You need to get this from the SWTBot repository, see SWTBot/Contributing. To create keyboard mappings for your keyboard:
- Change Keys#specialChars() accordingly for your keyboard.
- Execute KeyboardLayoutGenerator followed by KeyboardLayoutFilter
- Files keyboard.layout and keyboard.layout.filtered will be generated in the root of the plug-in.
- Rename keyboard.layout.filtered to [COUNTRY_CODE].keyboard.
- You probably need to check and edit this file manually.
- 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
.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