The UI will be notified when accesskeys are added or removed through the
AccesskeyListener in the windowcommander module. The UI will be notified about
WML DO elements in the same way.
The UI must then chose how to display to the user the different keys.
When the registered accesskey is triggered by the user it must be sent to the core through the input action system as described in modules/inputmanager/inputmanager.h.
See Doxygen documentation.
There is no standard way of presenting the active accesskeys to the user in the UI. But we have a few examples are how different browsers do it.
The Quick version of Opera will show a list of the accesskeys with their caption and URLs when accesskey mode is enabled, like this:
| (a) | Title 1 | http://example.com/ |
| (h) | Title 2 | http://example.com/ |
| (2) | Title 3 | http://example.com/ |
Safari will show the accesskey in a small tooltip box next to the actual link that the key is bound to, like this:
This is a link with accesskey "a"a
In the end it is up to the platform to use whichever way they want to display (or not) the accesskeys to the user. But it is important that the accesskey can be triggered somehow.
Example
<a href="someurl" accesskey="g" title="nice title">Link text</a>
Would result in this call:
OnAccessKeyAdded(commander, 'g', "nice title", "someurl");
The WML DO elements are handled as access keys for making use of already existing APIs and datastructures in core.
When OnAccessKeyAdded() is called for a DO element it will contain the value of the label attribute in the caption argument and the URL, if applicable, in the url argument.
The most important part here is the value of the key argument, which indicates how it is to be shown by the UI. The different cases are described below:
If the key value corresponds to a device specific key as defined in modules/hardcore/keys/OpKeys.h or in the product opkey file as documented in modules/hardcore/keys/README.txt, it should be displayed in the UI as a key binding for that key would normally be displayed. That could be not at all, as a softkey, a menu entry or any other way. How it is displayed is not important as long as the same key value is sent back to core when it is triggered by the user.
Example
<wml>
<card id="xmp">
<do label="Text" type="bs">
<prev />
</do>
</card>
</wml>
Would result in this call:
OnAccessKeyAdded(commander, OP_KEY_BACKSPACE, "Text", NULL);
If the key value is in the range between OP_KEY_FIRST_DO_UNSPECIFIED and OP_KEY_LAST_DO_UNSPECIFIED specified in the modules/hardcore/keys/OpKeys.h file or in the product opkey file as documented in modules/hardcore/keys/README.txt, it should be displayed as a softkey / dynamic menu on the device.
The UI code can assign whichever key code to the actual key used on the device, but when triggered by the user, it needs to be mapped back to the corresponding OP_KEY value that was used as the key argument to the OnAccessKeyAdded() call when sent to the input action system.
Example
<wml>
<card id="xmp">
<do label="Text" type="unbound">
<prev />
</do>
</card>
</wml>
Could result in this call:
OnAccessKeyAdded(commander, OP_KEY_FIRST_DO_UNSPECIFIED + 1, "Text", NULL);
The pseudo code to check in UI:
void PlatformImpl::OnAccessKeyAdded(commander, key, caption, url)
{
if (key >= OP_KEY_FIRST_DO_UNSPECIFIED && key < OP_KEY_LAST_DO_UNSPECIFIED)
{
int platform_key_code = PlatformAddSoftkey(caption);
Map key_map;
key_map->Map(platform_key_code, key);
}
else
{
PlatformBindKnownKeyToUI(key);
}
}
Other values should be treated as normal accesskeys.
When the UI code receives a key they have to send it to the core through the input action system described in modules/inputmanger/inputmanager.h.
If an accesskey is reported with a value in the WML DO range, it will most probably have to be remapped to a real keycode on the platform. That platform key cannot be sent back to core directly as it would not be matched to the correct element. So when the key is triggered by the user it needs to be mapped back to the value it was reported as in the call to OnAccessKeyAdded() and then sent to core.