[Scummvm-devel] Keymapper Update

[Stephen Kennedy]

Hi all,

As you may or may not know, the major part of my Summer of Code
project is to develop the long-awaited generalised keymapper module
for ScummVM. Within the last few days I have been familiarising myself
with the requirements for this by looking at the wiki page on it, and
also looking through the archive of the -devel list to understand what
has been discussed previously. However, I thought it would be a good
idea to post my conclusions to the mailing list, to confirm I have got
the key facts right. This will also provide the perfect opportunity
for anyone to share any new ideas with me.

--------------------------------------------------------------------------------

Engine interface:

- When an engine starts it will notify the keymapper of all the
mappings that the current game requires (e.g.
normal_mode/fight_mode/...)
- For each of these mappings the engine will tell the keymapper the
set of keys that are required, in the form of a list of UserAction
structs
- The UserAction struct will look something like this:

struct UserAction {
  UserActionClass class;
  UserActionType type;
  String description; // Human readable description, for a GUI config dialog
  Event event; // event to be sent when mapped key is pressed
  int priority; // how vital is this action?
  int group; // optional field to group similar actions together
(e.g. volume up/down, direction left/right/up/down)
  int flags; // for future additions...
};

- the UserActionType enum is there to provide consistency for common
actions. If the UserAction is specific to a game then UserActionClass
can be used to help map to a good area of the hardware.

enum UserActionType {
  kGenericUserAction,
  // common actions
  kDirectionUpUserAction,
  kDirectionDownUserAction,
  kDirectionLeftUserAction,
  kDirectionRightUserAction,
  kLeftClickUserAction,
  kRightClickUserAction,
  kSaveUserAction,
  kMenuUserAction,
  ...
};

enum UserActionClass {
  // classes of action - probably need to be slightly more specific than this
  kInGameUserAction,   // effects the actual gameplay
  kSystemUserAction,  //show a menu / change volume / etc
  ...
};

--------------------------------------------------------------------------------

Backend interface:

- backend must also register with keymapper and provide it with a list
of the hardware keys, along with some information to help the
keymapper. This will be in the form of a HardwareKey struct, something
like this:

struct HardwareKey {
  KeyState key;
  // enum values to aid automatic mapping to UserActions
  UserActionType preferredType;
  UserActionClass preferredClass;
  int group; // used to group buttons that are close to each other
};

--------------------------------------------------------------------------------

Keymapper functionality:

- when a new game is run, it will be the keymapper's responsibility to
try to autoassign each UserAction that the engine requires to a
hardware key. The global mapping, as well the data specified in the
UserAction struct will help this rather difficult process.
- the global mapping, and the game-specific mappings will be saved to
the global .ini file
- these mappings will be editable through a backend-independent GUI
dialog, which I will develop
- an engine will be able to call a method on the keymapper to switch
to a different game-specific mapping (e.g. normal/fight_mode)
- when it comes to the actual mapping the keymapper will *not*
generate events of type EVENT_USERACTION, instead it will just map
from one keypress event (with a KeyState that was defined in a
HardwareKey struct) to the event of the matching UserAction. The
UserAction event will probably be a keypress event (e.g. for SCUMM's
Menu UserAction the event will be an F5 keypress)

--------------------------------------------------------------------------------

Other points / ideas:

- integration with virtual keyboard - do we want virtual keyboard to
always produce the key press events of its keys, or do we want them to
be run though the keymapper? Im pretty sure its the former, because
when entering a save game name, we don't want a virtual key press to
be mapped to a different key
- if there are too many UserActions for the number of hardware keys
then we could have one key reserved to display a pop-up menu for all
the UserActions that could not be mapped

--------------------------------------------------------------------------------

That sums up my understanding at the moment. Would be great to get
everyone's input on this before I start thinking about the actual
implementation.

Cheers,
Stephen