From aecea5c3505051b71fbeffb6c80ca617299a5d67 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Mon, 4 Jan 2016 16:11:15 +0900 Subject: [PATCH] Document most of they key binding system. --- include/QF/keys.h | 133 ++++++++++++++++++++++++++++++++++---- libs/video/targets/keys.c | 19 ------ 2 files changed, 120 insertions(+), 32 deletions(-) diff --git a/include/QF/keys.h b/include/QF/keys.h index b862a4bb7..cfd20d258 100644 --- a/include/QF/keys.h +++ b/include/QF/keys.h @@ -482,14 +482,14 @@ typedef enum { } knum_t; typedef enum { - key_unfocused, // engine has lost input focus - key_game, - key_demo, - key_console, - key_message, - key_menu, + key_unfocused, ///< engine has lost input focus + key_game, ///< Normal in-game key bindings + key_demo, ///< Demo playback key bindings + key_console, ///< Command console key bindings + key_message, ///< Message input line key bindings + key_menu, ///< Menu key bindings. - key_last // enum size + key_last ///< enum size } keydest_t; #ifndef __QFCC__ @@ -515,34 +515,141 @@ typedef struct imt_s { int written; ///< avoid duplicate config file writes } imt_t; +/** Chain of input mapping tables ascociated with a keydest sub-system (game, + menu, etc). +*/ typedef struct keytarget_s { - imt_t *imts; - imt_t *active; + imt_t *imts; ///< list of tables attached to this target + imt_t *active; ///< currently active table in this target } keytarget_t; extern int keydown[QFK_LAST]; +struct cbuf_s; + +void Key_Init (struct cbuf_s *cb); +void Key_Init_Cvars (void); + +/** Find an Input Mapping Table by name. + + Searches through all keydest targets for the named imt. The search is case + insensitive. + + \param imt_name The name of the imt to find. Case insensitive. + \return The named imt, or null if not found. +*/ imt_t *Key_FindIMT (const char *imt_name); + +/** Create a new imt and attach it to the specified keydest target. + + The name of the new imt must be unique (case insensitive) across all + keydest targets. This is to simplify the in_bind command. + + If \a chain_imt_name is not null, then it species the fallback imt for when + the key is not bound in the new imt. It must be an already existing imt in + the specified keydest target. This is to prevent loops and other weird + behavior. + + \param kd The keydest target to which the new imt will be attached. + \param imt_name The name for the new imt. Must be unique (case + insensitive). + \param chain_imt_name The name of the fallback imt if not null. Must + already exist on the specified keydest target. +*/ void Key_CreateIMT (keydest_t kd, const char *imt_name, const char *chain_imt_name); -struct cbuf_s; +/** Handle a key press/release event. + + \param key The key that was pressed or released for this event. + \param unicode The unicode value of the key. + \param down True if a press event, false if a release event. +*/ void Key_Event (knum_t key, short unicode, qboolean down); + +/** Handle loss or gain of input focus (usually in windowed enviroments). + + Sets the keydest target to key_unfocuses when input focus is lost. + + Triggers keydest callbacks. + + \bug Always sets the target to key_game when focus is gained. + + \param gain True if focus is gained, false if focus is lost. +*/ void Key_FocusEvent (int gain); -void Key_Init (struct cbuf_s *cb); -void Key_Init_Cvars (void); + void Key_WriteBindings (QFile *f); + +/** Force all key states to unpressed. + + Sends a key release event for any keys that are seen as down. +*/ void Key_ClearStates (void); + +/** Return a key binding in the specified input mapping table. + + \param imt The input mapping table from which to get the binding. + \param key The key for which to get the binding. + \return The command string bound to the key, or null if unbound. +*/ const char *Key_GetBinding (imt_t *imt, knum_t key); + +/** Bind a command string to a key in the specified input mapping table. + + Only one command string can be bound to a key, but the command string may + contain multiple commands. + + \param int The input mapping table in which the key will be bound. + \param keynum The key to which the command string will be bound. + \param binding The command string that will be bound. +*/ void Key_SetBinding (imt_t *imt, knum_t keynum, const char *binding); + +/** Set the current keydest target. + + Triggers keydest callbacks. + + \param kd The keydest target to make current. +*/ void Key_SetKeyDest(keydest_t kd); -typedef void keydest_callback_t (keydest_t); + +/** keydest callback signature. + + \param kd The new current keydest target. +*/ +typedef void keydest_callback_t (keydest_t kd); + +/** Add a callback for when the keydest target changes. + + \param callback The callback to be added. +*/ void Key_KeydestCallback (keydest_callback_t *callback); +/** Get the string representation of a key. + Returns a string (a QFK_* name) for the given keynum. + + \param keynum The key for which to get the string. + \return The string representation of the key. +*/ const char *Key_KeynumToString (knum_t keynum); + +/** Get the keynum for the named key. + + Returns a key number to be used to index keybindings[] by looking at + the given string. Single ascii characters return themselves, while + the QFK_* names are matched up. + + \param str The name of the key. + \return The named key if valid, otherwise -1 +*/ int Key_StringToKeynum (const char *str); + struct progs_s; + +/** Add the Key builtins to the specified progs instance. +*/ void Key_Progs_Init (struct progs_s *pr); #endif diff --git a/libs/video/targets/keys.c b/libs/video/targets/keys.c index 1170dee24..b1d22f121 100644 --- a/libs/video/targets/keys.c +++ b/libs/video/targets/keys.c @@ -634,10 +634,6 @@ Key_Game (knum_t key, short unicode) imt = imt->chain; } return false; -/* - Sys_DPrintf("kb %p, key_target %d, key_dest %d, key %d\n", kb, - key_target, key_dest, key); -*/ } /* @@ -655,15 +651,6 @@ Key_Console (knum_t key, short unicode) Con_KeyEvent (key, unicode, keydown[key]); } -//============================================================================ - -/* - Key_StringToKeynum - - Returns a key number to be used to index keybindings[] by looking at - the given string. Single ascii characters return themselves, while - the QFK_* names are matched up. -*/ VISIBLE int Key_StringToKeynum (const char *str) { @@ -679,12 +666,6 @@ Key_StringToKeynum (const char *str) return -1; } -/* - Key_KeynumToString - - Returns a string (a QFK_* name) for the given keynum. - FIXME: handle quote special (general escape sequence?) -*/ VISIBLE const char * Key_KeynumToString (knum_t keynum) {