KEYMAPPER: Introduce custom engine actions

Custom engine actions are a new type of event the Keymapper can produce.
When an engine declares its keymap, it can declare it wants to receive
custom action events when the corresponding key is pressed, instead of
the originating hardware input events.

This system allows:
* Key bindings to be specified only once when declaring the keymap,
  instead of twice (when handling the events).
* To truly rebind keys in the keymaps dialog. When using traditional
  event mapping, the keymapper remaps the user keypress to the keypress
  expected by the game engine to perform the action. However, the engine
  still accepts the original keys.

The new concept of 'standard actions' defines a set of engine actions
that are commonly available in the games supported by ScummVM. Backends
can define default bindings for the standard actions to hardware
specific input devices.

backends/keymapper/action.cpp

@@ -33,6 +33,10 @@ Action::Action(const char *i, const String &des) :
 }
 
 void Action::addDefaultInputMapping(const String &hwId) {
+	if (hwId.empty()) {
+		return;
+	}
+
 	// Don't allow an input to map to the same action multiple times
 	Array<String>::const_iterator found = find(_defaultInputMapping.begin(), _defaultInputMapping.end(), hwId);
 	if (found == _defaultInputMapping.end()) {

backends/keymapper/action.h

@@ -68,6 +68,12 @@ public:
 		event.customType = evtType;
 	}
 
+	void setCustomEngineActionEvent(const CustomEventType evtType) {
+		event = Event();
+		event.type = EVENT_CUSTOM_ENGINE_ACTION_START;
+		event.customType = evtType;
+	}
+
 	void setKeyEvent(const KeyState &ks) {
 		event = Event();
 		event.type = EVENT_KEYDOWN;

backends/keymapper/keymap.cpp

@@ -134,6 +134,13 @@ void Keymap::registerBackendDefaultMappings() {
 		Action *action = *it;
 		Common::String defaultHwId = _backendDefaultBindings->getDefaultBinding(_name, action->id);
 
+		if (!defaultHwId.empty()) {
+			action->addDefaultInputMapping(defaultHwId);
+			continue;
+		}
+
+		// If no keymap-specific default mapping was found, look for a standard action binding
+		defaultHwId = _backendDefaultBindings->getDefaultBinding(kStandardActionsKeymapName, action->id);
 		if (!defaultHwId.empty()) {
 			action->addDefaultInputMapping(defaultHwId);
 		}

backends/keymapper/keymap.h

@@ -33,6 +33,8 @@
 
 namespace Common {
 
+const char *const kStandardActionsKeymapName = "standard-actions";
+
 class Action;
 struct HardwareInput;
 class HardwareInputSet;

backends/keymapper/keymapper.cpp

@@ -180,6 +180,13 @@ List<Event> Keymapper::mapEvent(const Event &ev) {
 		}
 	}
 
+	// Ignore keyboard repeat events. Repeat event are meant for text input,
+	// the keymapper / keymaps are supposed to be disabled during text input.
+	// TODO: Add a way to keep repeat events if needed.
+	if (!mappedEvents.empty() && ev.type == EVENT_KEYDOWN && ev.kbdRepeat) {
+		return List<Event>();
+	}
+
 	if (mappedEvents.empty()) {
 		// if it didn't get mapped, just pass it through
 		mappedEvents.push_back(ev);
@@ -245,6 +252,9 @@ EventType Keymapper::convertStartToEnd(EventType type) {
 	case EVENT_CUSTOM_BACKEND_ACTION_START:
 		result = EVENT_CUSTOM_BACKEND_ACTION_END;
 		break;
+	case EVENT_CUSTOM_ENGINE_ACTION_START:
+		result = EVENT_CUSTOM_ENGINE_ACTION_END;
+		break;
 	default:
 		break;
 	}

backends/keymapper/standard-actions.cpp

@@ -0,0 +1,38 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ */
+
+#include "backends/keymapper/standard-actions.h"
+
+namespace Common {
+
+const char *kStandardActionSkip          = "SKIP";
+const char *kStandardActionPause         = "PAUSE";
+const char *kStandardActionMoveForward   = "FWD";
+const char *kStandardActionMoveBackwards = "BWD";
+const char *kStandardActionTurnLeft      = "TL";
+const char *kStandardActionTurnRight     = "TR";
+const char *kStandardActionMoveUpwards   = "UP";
+const char *kStandardActionMoveDownwards = "DOWN";
+const char *kStandardActionOpenDebugger  = "DBG";
+const char *kStandardActionOpenMainMenu  = "MENU";
+
+} //namespace Common

backends/keymapper/standard-actions.h

@@ -0,0 +1,52 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ */
+
+#ifndef BACKENDS_KEYMAPPER_STANDARD_ACTIONS_H
+#define BACKENDS_KEYMAPPER_STANDARD_ACTIONS_H
+
+/**
+ * @file
+ * @brief A set of well known keymapper actions.
+ *
+ * The actions in this file are meant to be used by game engines
+ * when defining their key mappings.
+ * Backends can provide default key mappings for some of these actions
+ * so users don't have to manually configure the action mappings for
+ * the input devices.
+ */
+
+namespace Common {
+
+extern const char *kStandardActionSkip;
+extern const char *kStandardActionPause;
+extern const char *kStandardActionMoveForward;
+extern const char *kStandardActionMoveBackwards;
+extern const char *kStandardActionTurnLeft;
+extern const char *kStandardActionTurnRight;
+extern const char *kStandardActionMoveUpwards;
+extern const char *kStandardActionMoveDownwards;
+extern const char *kStandardActionOpenDebugger;
+extern const char *kStandardActionOpenMainMenu;
+
+} //namespace Common
+
+#endif // BACKENDS_KEYMAPPER_STANDARD_ACTIONS_H

backends/module.mk

@@ -14,6 +14,7 @@ MODULE_OBJS := \
 	keymapper/keymap.o \
 	keymapper/keymapper.o \
 	keymapper/remap-widget.o \
+	keymapper/standard-actions.o \
 	log/log.o \
 	midi/alsa.o \
 	midi/dmedia.o \

backends/platform/maemo/maemo.cpp

@@ -196,10 +196,7 @@ Common::KeymapArray OSystem_SDL_Maemo::getGlobalKeymaps() {
 	Action *act;
 
 	act = new Action("CLKM", _("Click Mode"));
-	Event evt = Event();
-	evt.type = EVENT_CUSTOM_BACKEND_ACTION_START;
-	evt.customType = Maemo::kEventClickMode;
-	act->setEvent(evt);
+	act->setCustomBackendActionEvent(Maemo::kEventClickMode);
 	globalMap->addAction(act);
 
 	act = new Action("LCLK", _("Left Click"));

common/EventDispatcher.cpp

@@ -60,6 +60,9 @@ void EventDispatcher::dispatch() {
 				// to be the output of the event mapper.
 				assert(event.type != EVENT_CUSTOM_BACKEND_ACTION_START);
 				assert(event.type != EVENT_CUSTOM_BACKEND_ACTION_END);
+				assert(event.type != EVENT_CUSTOM_ENGINE_ACTION_START);
+				assert(event.type != EVENT_CUSTOM_ENGINE_ACTION_END);
+
 
 				List<Event> mappedEvents = _mapper->mapEvent(event);
 

common/events.h

@@ -75,11 +75,12 @@ enum EventType {
 	EVENT_PREDICTIVE_DIALOG = 12,
 
 	EVENT_CUSTOM_BACKEND_ACTION_START = 18,
-	EVENT_CUSTOM_BACKEND_ACTION_END = 19,
-	EVENT_CUSTOM_BACKEND_HARDWARE = 21,
+	EVENT_CUSTOM_BACKEND_ACTION_END   = 19,
+	EVENT_CUSTOM_ENGINE_ACTION_START  = 20,
+	EVENT_CUSTOM_ENGINE_ACTION_END    = 21,
 
 #ifdef ENABLE_VKEYBD
-	EVENT_VIRTUAL_KEYBOARD = 20,
+	EVENT_VIRTUAL_KEYBOARD = 22,
 #endif
 
 	EVENT_DROP_FILE = 23,
@@ -88,7 +89,9 @@ enum EventType {
 	EVENT_JOYBUTTON_DOWN = 25,
 	EVENT_JOYBUTTON_UP = 26,
 
-	EVENT_CLIPBOARD_UPDATE = 27
+	EVENT_CLIPBOARD_UPDATE = 27,
+
+	EVENT_CUSTOM_BACKEND_HARDWARE = 28
 };
 
 const int16 JOYAXIS_MIN = -32768;