getkey: add a "feature function" to create application-wide shortcuts

This change introduces the global "feature function" that can be
enabled in getkey() to receive events, and use them for
application-wide features. This would be useful, for instance, to
toggle screen backlight with a different key combination that the
default, to capture screenshots, or to implement a catalog.

When enabled, the feature function is present with all new events and
can perform actions, then decide whether or not to return them from
getkey().

include/gint/keyboard.h

@@ -212,17 +212,23 @@ enum {
 	GETKEY_REP_ALL     = 0x20,
 	/* Enable custom repeat profiles; see getkey_set_repeat_profile() */
 	GETKEY_REP_PROFILE = 0x40,
+	/* Enable application shortcuts; see getkey_set_feature_function() */
+	GETKEY_FEATURES    = 0x80,
 
 	/* No modifiers */
 	GETKEY_NONE        = 0x00,
 	/* Default settings of getkey() */
-	GETKEY_DEFAULT     = 0x5f,
+	GETKEY_DEFAULT     = 0xdf,
 };
 
 /* getkey_profile_t: Custom repeat profile function
    See getkey_set_repeat_profile() for details. */
 typedef int (*getkey_profile_t)(int key, int duration, int count);
 
+/* getkey_feature_t: Custom feature function
+   See getkey_set_feature_function() for details. */
+typedef bool (*getkey_feature_t)(key_event_t event);
+
 /* getkey_opt(): Enhanced getkey()
 
    This function enhances getkey() with more general features. An
@@ -288,6 +294,27 @@ getkey_profile_t getkey_repeat_profile(void);
    the repeat exactly when needed. */
 void getkey_set_repeat_profile(getkey_profile_t profile);
 
+/* getkey_feature_function(): Get the current feature function */
+getkey_feature_t getkey_feature_function(void);
+
+/* getkey_set_feature_function(): Set the global feature function
+
+   The feature function can be used to extend getkey() with application-wide
+   shortcuts, in a way similar to the CATALOG, CAPTURE or OFF functions of the
+   original getkey(). The feature function can be set globally at the
+   application level, and thus does not require every call site that uses
+   getkey() to support the shortcuts explicitly.
+
+   The feature function receives events when they are generated; if can them
+   process them, and return either true to accept the event (preventing
+   getkey() from returning it) or false to refuse the event (in which case it
+   is returned normally).
+
+   The feature function is enabled by default and be disabled by removing the
+   GETKEY_FEATURES flag in getkey_opt(). Setting function=NULL disables the
+   functionality. */
+void getkey_set_feature_function(getkey_feature_t function);
+
 //---
 //	Key code functions
 //---

src/keysc/getkey.c

@@ -15,6 +15,8 @@
 static int rep_first = 400, rep_next = 40;
 /* Repeat profile function */
 static getkey_profile_t repeat_profile = NULL;
+/* Feature function */
+static getkey_feature_t feature_function = NULL;
 /* Repeater specification */
 static enum { NONE, ALL, ARROWS, FILTER } repeat_mode;
 
@@ -71,7 +73,15 @@ key_event_t getkey_opt(int opt, volatile int *timeout)
 			e.key == KEY_MENU && !e.shift && !e.alpha)
 			gint_osmenu();
 
-		else if(e.type == KEYEV_DOWN || e.type == KEYEV_HOLD) break;
+		else if(e.type == KEYEV_DOWN || e.type == KEYEV_HOLD)
+		{
+			/* Custom global features */
+			bool accepted = false;
+			if((opt & GETKEY_FEATURES) && feature_function)
+				accepted = feature_function(e);
+			/* Return if the even has not been accepted yet */
+			if(!accepted) break;
+		}
 	}
 
 	keydev_set_transform(d, tr0);
@@ -96,3 +106,17 @@ void getkey_set_repeat_profile(getkey_profile_t profile)
 {
 	repeat_profile = profile;
 }
+
+/* getkey_feature_function(): Get the current feature function */
+getkey_feature_t getkey_feature_function(void)
+{
+	return feature_function;
+}
+
+/* getkey_set_feature_function(): Set the global feature function */
+void getkey_set_feature_function(getkey_feature_t function)
+{
+	feature_function = function;
+}
+
+