How to use KeyBundles in Bindows
Johan Lund posted in Developing in Bindows on November 3rd, 2010
Bindows has many built in behaviors that trigger when a user is pressing a key. A great example is a selection model that gives you the ability to select and deselect, multiple and discontinuous items in a list. For many years Bindows has modeled its behavior and copied all the keyboard shortcuts from the Windows environment. But hard coded keyboard shortcuts are no longer a viable solution in a changing landscape. Mac users use the Command key instead of the Control key and Control+Click equals right click on the Mac. Sometimes developers/users don’t agree with more esoteric shortcuts such as F2 for editing a tree item. Language reasons could be another motive for having different shortcuts. For example the word ”Bold” in English systems has the keyboard shortcut Ctrl+B while in Swedish it’s called ”Fetstil” and the shortcut Ctrl+F is used. New versions of accessibility software such as JAWS have also been known to introduce new conflicting shortcuts. We need a central location for keeping and easily maintaining these keyboard shortcuts. Up until now, if a keyboard shortcut was implemented in Bindows you had to override methods in Bindows in order to change it. Knowing which methods, and how, wasn’t always straight forward. That’s why we have implemented ”key bundles” in Bindows 4.1.
BiKeyBundle & C.O
Starting with Bindows 4.1 there are no hard coded keyboard shortcuts scattered across the code anymore. Instead, we have the BiKeyBundle object that contains many BiKeystroke objects, which in turn are used internally by Bindows. The BiKeyBundle object is serialized from a file called DefaultKeyboardBundle.js at startup. If you want to change the default shortcuts you can make your own version of DefaultKeyboardBundle.js and overwrite the one that comes with Bindows. Another option - create a small file with the few shortcuts you want to add or change, and merge it with the default bundle.
A keybundle file is a simple associative array that BiKeyBundle understands. You can include it in your application in several ways. I think it would be best to look at an example.
1. Here the shortcut keys have been put straight into the ADF. Because the ”merge” property hasn’t been set it, will default to overwrite. This actually means that the DefaultKeboardBundle won’t load at all which means that Bindows will only know about the shortcuts you specified here and nothing else. For this little application it is fine, and it will actually get rid of some bloat. The keystrokes consist of an identifier, that is associated with a behavior in some Bindows components, and the actual keys that will trigger it. Some actions can also be triggered by multiple keys. All the keystrokes in the first example belong to a section called ”keystrokes”. You don’t actually have to specify it as it is the default section. There are other sections such as the ”modifiers” which is used together with mouse clicks. You are welcome to snoop around in the DefaultKeyBundle.js for more info, if you are interested.
2. Actually the same as the first section but this time using ”merge” so we do not destroy what we did in section one. Also note that we omitted the ”keystrokes” section here.
3. This time we merge changes that we load from a json file called KeyBundleTest_overrides.json. The file is simplistic in nature.
To see if Ctrl+P (defined as custom.key in the json file) was pressed, you ask the event if the key pressed matched that identifier by using the ”e.matchesBundleShortcut” method.
Sample Application (KeyBundleTest.xml)