# Keys

## What does the key system do?

The key system provides a list of virtual keys (enum OpKey::Code) and a mapping between these keys and their string representation. A set of virtual keys and their fixed values is pre-defined by Opera in hardcore, which together with any extensions that a product wishes to support, is processed by a script to make up the keys system for a configuration. The script producing the OpKey::Code enum along with the mapping functions as output.

Along side the definition of the keys, each product must decide if the keys found in the combined set of module.keys files should be enabled or not.

## What is module.keys?

Each module, or most common, platform, can add a module.keys file. This is an example of a module.keys file:

    # The format ("[..]" indicating an optional field):
    #
    # keycode           [offset(hex)] keyname(string)  [flags]
    OP_KEY_BACKSPACE    0x08          Backspace        standard, function
    OP_KEY_TAB                        Tab              standard
    OP_KEY_ENTER        0x0c          Enter            standard, key_synonym=OP_KEY_RETURN
    OP_KEY_F1                         F1               standard, function
    OP_KEY_HOME                       Home             standard, function
    OP_KEY_ALT          0x12          Alt              modifier
    OP_KEY_SPACE        0x20          Space            standard

One key per line, giving the virtual key symbolic keycode along with a key name. Optionally, the virtual key value (offset) -- the enum tag's value -- can be specified. Derived, if not given. A number of optional flags can also be supplied in a comma-separated list. Please see the documentation at the top of the module.keys for a complete list. It is available as hardcore/documentation/module.keys.txt.

## How does the product decide which keys should be available?

By setting the macro `PRODUCT_OPKEY_FILE` to the path of a header file that states for each key if it is to be enabled or not. An example of such a header file is:

    /* Copyright Opera Software 2006, do not distribute. */

    #define ENABLE_OP_KEY_F1                   YES
    #define ENABLE_OP_KEY_HOME                 YES
    #define ENABLE_OP_KEY_END                  YES
    #define ENABLE_OP_KEY_PAGEUP               YES
    #define ENABLE_OP_KEY_PAGEDOWN             YES
    #define ENABLE_OP_KEY_UP                   YES
    #define ENABLE_OP_KEY_DOWN                 YES

## Required keys

If `FEATURE_MOUSE` is enabled, the platform must declare and enable at least the keys `OP_KEY_MOUSE_BUTTON_1` and `OP_KEY_MOUSE_BUTTON_2` as these are used with special meaning by core code. They represent the primary and secondary, that is, typically the left and right, mouse buttons. These buttons, and any other `OP_KEY_MOUSE_BUTTON_x` keys defined should of course be flagged as mouse buttons using the `mouse_button` flag.