1
edit
Changes
no edit summary
==Overview: How to develop accessible extensions, modules, and plugins for the BigBlueButton Flash client==
Accessibility is an important part of the BigBlueButton application. Not only does it allow users with disabilities to run and participate in meetings, it's also mandated by law that if we CAN make it accessible, we HAVE to. For our purposes, disabilities fall into three main categories: Visual, Auditory, and Motor. This guide focuses mostly on Visual and Motor, simply because of the nature of BigBlueButton and what the CDOT team has run into so far.
===Global Shortcuts===
Before we get into creating global shortcuts within BigBlueButton, first be sure that you have already added the ASCII codes for your hotkeys into the locale file, as described above in the section about the Shortcut Help Window. Also, make sure that you have added constants as necessary to ShortcutEvent.as, as described in "Deciding what hotkeys to add." Once you've done that, we can proceed.
Global shortcuts, in the context of BigBlueButton, are hotkeys that can be used from anywhere within the application, such as the hotkey to focus into the Presentation window. Compare this to local shortcuts which can only be used within the module they affect, such as the hotkey WITHIN the Presentation window to advance to the next slide.
'''REMINDER:''' As the table in the Shortcut Keys overview shows, global and local shortcut keys also use separate modifiers, to allow the entire keyboard to be used in the global scope and again in each module.
All global shortcuts begin in /bigbluebutton-client/src/BigBlueButton.mxml. The framework for shortcut keys is already present, so all you need to worry about is adding your hotkeys to that framework. Moving forward, we will continue the example from the Shortcut Help Window section of the fictional Opinion module. In BigBlueButton.mxml, find the loadKeyCombos() method. This collects all available global shortcuts into an object called keyCombos. The Opinion module has only one global shortcut, so the only line we need to add to this method is:<code>keyCombos[modifier+(ResourceUtil.getInstance().getString('bbb.shortcutkey.focus.opinion') as String)] =ShortcutEvent.FOCUS_OPINION_MODULE;</code> '''NOTE: Generally, your module's only global shortcut will be to move the applications focus into your module, although this is not a rule by any means.''' That's it, that's all you need to add to BigBlueButton.mxml. The framework for detecting whether the user has pressed the correct keys to dispatch the event and then actually dispatching it is already coded in. If you are curious how it all fits together, we'll get into that in the "Local Hotkeys" section below. Now, you need to set up a listener for that event you've just dispatched. Assuming that the Opinion module is an MDIWindow like the other main modules, you'll want to open the main MXML file for it. Between the opening <MDIWindow> tag and the opening <mx:Script> tag, you need to add a <mate:Listener> tag like so:<code><mate:Listener type="{ShortcutEvent.FOCUS_OPINION_MODULE}" method=Testing==="focusWindow" /></code> Then define the method to be called when the Listener picks up the ShortcutEvent. In this case, the method draws focus to the window's titlebar, from which the user can quickly tab into the module itself. Make sure that you have imported org.bigbluebutton.main.events.ShortcutEvent into the target MXML:<pre>private function focusWindow(e:ShortcutEvent):void{ focusManager.setFocus(titleBarOverlay);}</pre>
===Local Shortcuts===
Adding local shortcuts to your module is a more involved process, as you need to build the framework that is already present for global shortcuts. We'll start in the MDIWindow for your module.
'''NOTE: Some modules, like the Chat module, have a more complex structure with specific hotkeys for each one. If your module is built in a similar manner, you will need to repeat this for each MXML in your module which dispatches it's own shortcuts.'''
Make sure you've imported org.bigbluebutton.main.events.ShortcutEvent into the MXML file, and declare an instance variable of class Dispatcher. You've already set up a method bound to creationComplete of your MDIWindow when you set up the Tab Order earlier in this guide; instantiate the Dispatcher to new Dispatcher() in that method. Now, make sure that your MXML has a loadKeyCombos method. If not, add one like so: (still working with our example of the Opinion module)
<pre>
private function loadKeyCombos(modifier:String):void {
keyCombos = new Object(); // always start with a fresh array
keyCombos[modifier+(ResourceUtil.getInstance().getString('bbb.shortcutkey.opinion.focusInput') as String)] = ShortcutEvent.FOCUS_OPINION_INPUT;
keyCombos[modifier+(ResourceUtil.getInstance().getString('bbb.shortcutkey.opinion.submit') as String)] = ShortcutEvent.OPINION_SUBMIT;
}
</pre>
Notice that we are still using the string from the locale file that contains the ASCII code for whichever key is used in the shortcut. Much like how we set up an array to populate the Help window DataGrid to display information about our hotkeys, this sets up this part of your module with an Object full of keycodes to watch out for. Next, add a hotKeyCapture() method which will add a keyDown listener to the module, as well as a locale-change listener in case the user switches the language they're operating in:
<pre>
private function hotkeyCapture():void{
this.addEventListener(KeyboardEvent.KEY_DOWN, handleKeyDown);
ResourceUtil.getInstance().addEventListener(Event.CHANGE, localeChanged); // Listen for locale changing
}
</pre>
Return to your creationComplete method, and after the Dispatcher has been instantiated, call your new hotKeyCapture() method. This makes sure the listeners are in place as soon as the application is done loading.
Finally, one last method to bring everything together: the handleKeyDown() method from the keyDown listener:
<pre>
private function handleKeyDown(e:KeyboardEvent) :void {
var modifier:String = ExternalInterface.call("determineLocalModifier");
loadKeyCombos(modifier);
var keyPress:String = (e.ctrlKey ? "control+" : "") +
(e.shiftKey ? "shift+" : "") +
(e.altKey ? "alt+" : "") + e.keyCode;
if (keyCombos[keyPress]) {
disp.dispatchEvent(new ShortcutEvent(keyCombos[keyPress]));
}
}
</pre>
This is where it all comes together. When the user presses a key, the listener catches the event, and determines which modifier it should be looking for with a call to a simple piece of JavaScript which determines which browser the user is running. It then calls the loadKeyCombos method and passes in that modifier; loadKeyCombos brings in the ASCII codes from the locale file and plugs them into the keyCombos object. Control returns to handleKeyDown, which compares the keys being pressed to the key combinations present in keyCombos. If one of those combinations matches, it uses the Dispatcher (disp, in our example) to dispatch the event to the application. Because the keyDown listener was added to the "this" scope rather than to the global "stage," these events are only dispatched when you are in the appropriate scope.
Listening for these events is done the same way as for global shortcuts, with a <mate:Listener> tag in the MXML file where the hotkey is meant to take effect.
===Testing===
Testing your shortcuts happens in two stages. First, you need to make sure that your hotkey combinations call the correct methods and actually do what they're supposed to do and how they're supposed to do it. Second, you need to make sure that your hotkeys are available in the correct scope. Global hotkeys, of course, should work as long as the Flash application has focus. If you can move focus into the Chat module and still use the local hotkey you set up for your custom module, something has gone wrong.
==Conclusion==
With all you've done in this guide, your module is now accessible to users with disabilities, and you have built a strong framework into your code which can expand as needed to suit any future development. Of course, even with the testing guidelines provided here, there is a good chance you may overlook something. There is a large community of users around the world, who have been using technology with disabilities for years and who you can reach out to to perform real-world testing of what you've developed.
