DevDoc:Input

WARNING ! preliminary documentation

The Input System handles mouse and keyboard events, the central file is lib.input.lua,
and utilities and keyname-list can be found in input.h input.cpp, and the whole thing is bound to OIS in ogrewrapper.cpp.

Input Events are not generated at arbitrary times, but only at the end of Client_RenderOneFrame() (after the frame has been rendered) called in main.lua:MainStep()

keybindings for ingame controls can be realised by code like this :

 BindDown("v", function () Client_TakeScreenshot() end)

there can only be one bind per key.

while an edit-text is active, binds are only triggered if the keyboard event is not consumed by the edittext (see lib.edittext.lua : EditTextKeyDown)

you can determine if a key is currently pressed by

 if (gKeyPressed[key_a]) then ... end

there are constants for variouse keys, key_f1, key_home,etc
a full list of keynames can be found in src/input.cpp or by dumping the global var gKeyNames

also these utils might be useful :

 local mx,my = PollInput() -- gets current mouse position
 local curtime = Client_GetTicks() -- gets current time, as milli-second-timestamp since application start

and maybe these global vars :

 gLastMouseDownX,gLastMouseDownY -- mousepos at last mouse_down
 gLastMouseDownTime -- time at last mouse_down

while the mousebuttons are also considered as keys (key_mouse1,...), there are also some helpful mosue events.

 mouse_down, mouse_up, 
 mouse_drag_start/step/end : gMouseDragMinDist (prevents mouseclick)
 mouse_click (immediately at mouseup, no double wait, triggered two times during doubleclick, not triggered during drag) : 
 mouse_single_click (avoid this!, only after doubleclick isn't possible anymore : not triggered at all during doubleclick)
 mouse_double_click 
 mouse_right_down,mouse_right_up

you can adjust gDoubleClickIntervall to finetune what is considered as doubleclick

you can listen to these events (and to keydown + keyup) using the listener system from lib.listener.lua

 RegisterListener("mouse_rightclick",function () print("right mouse was pressed") end)
 RegisterListener("keydown",function (keycode,char) print("keydown, keycode,char=",keycode,char) end) -- char is for text input
 RegisterListener("keyup",function (keycode) print("keyup, keycode=",keycode) end)

there is some support for detecting mouse drags, started when the mouse moves more than gMouseDragMinDist pixels (default 5) after mousedown drag prevents mouse_click* events, gbMouseDragging is true if a drag is in progress

IN PLANNING : the mouse events trigger gui/widget commands BEFORE the generic listeners (used for rightclick menus, etc)