--- awesome keygrabber API
-- @author Julien Danjou <julien@danjou.info>
-- @copyright 2008-2009 Julien Danjou
-- @release @AWESOME_VERSION@
-- @module keygrabber

---
-- Grab keyboard input and read pressed keys, calling a callback function at
-- each keypress, until `keygrabber.stop` is called.
-- The callback function receives three arguments:
--
-- * a table containing modifiers keys
-- * a string with the pressed key
-- * a string with either "press" or "release" to indicate the event type.
--
-- @param callback A callback function as described above.
-- @function run
-- @usage The following function can be bound to a key, and will be used to
--        resize a client using keyboard.
--
--     function resize(c)
--       keygrabber.run(function(mod, key, event)
--         if event == "release" then return end
--
--         if     key == 'Up'   then awful.client.moveresize(0, 0, 0, 5, c)
--         elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c)
--         elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c)
--         elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c)
--         else   keygrabber.stop()
--         end
--       end)
--     end

--- Stop grabbing the keyboard.
-- @function stop

--- Check if the keygrabber is running.
-- @return A boolean value, true if running, false otherwise.
-- @function isrunning