How to handle accesskeys and DO elements

Table of contents

Overview

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.

The OpAccessKeyListener interface

See Doxygen documentation.

Handling of "Normal" accesskeys

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 1http://example.com/
(h)Title 2http://example.com/
(2)Title 3http://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");

How WML DO elements are reported

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 DO

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:

  1. Platform specific OP_KEY
  2. Predefined range of DO OP_KEYS

Platform specific OP_KEY

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);

Predefined range of DO OP_KEYS

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 key values

Other values should be treated as normal accesskeys.

How accesskeys are sent to core

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.

Remapped keys

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.

stighal, 2008-04-17