Redirects key events to different module(s).
Normally, key events are interpreted by the engine, affected by the key bindings. This trap allows you redirect key events to other components.
Valid catchers are:
- KEYCATCH_CONSOLE: the console
- KEYCATCH_UI: the ui module
- KEYCATCH_MESSAGE: the little message editor thingy
- KEYCATCH_CGAME: the cgame module
These are bitmasked values, meaning you can combine them with the OR operator (|), as in (KEYCATCH_UI|KEYCATCH_CGAME), but I recommend against trying multiple catchers (it may get confusing).
As a mods programmer, you may be most interested in KEYCATCH_CGAME, and on this I will concentrate this entry.
The Keyboard
When key-catching is enabled (trap_Key_SetCatcher(KEYCATCH_CGAME);), upon a change in key state (gets pressed or gets released), the engine calls the vmMain() function in cg_main.c with the following parameters:
- command = CG_KEY_EVENT
- arg0 = keynum
- arg1 = 1 if pressed, 0 if released.
In baseq3 game source, this event is already handled and delegated to CG_KeyEvent(), which is empty.
The values for keynum are the same as for trap_Key_IsDown().
Key catching is disabled by calling with a parameter of 0 (as in, no catchers). Key catching is also terminated if the user presses the ESC key, which means you won't receive events on the ESC key.
The Mouse
When key-catching is enabled, mouse movement is also redirected to the specified module. When the engine detects mouse movement, it calls vmMain() with the following parameters:
- command = CG_MOUSE_EVENT
- arg0 = relative X position
- arg1 = relative Y position
The game source for baseq3 delegates this event to CG_MouseEvent().
Pointer Device Movement - Reported Value:
- Left - Negative X
- Right - Positive X
- Up - Negative Y
- Down - Positive Y
The engine only reports mouse movement -- if the mouse doesn't move, there is no mouse event. The engine reports mouse buttons and wheels (if any) as key events, for binding purposes.
Cvars do not influence the reported values.