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.

binds are only triggered if the keyboard event is not consumed by the guy system, especially by edittext fields (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

mouse events

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
 gKeyPressed[key_mouse1] -- true if left mouse button is down, right=2, middle=3

and maybe these global vars :

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

while the mousebuttons are also considered as keys (key_mouse1,...) and can have binds like described above, there are also some helpful mouse 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

double click

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)

mouse drag

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)