docs(evdev): add grabbing-and-repeat.md

Author: haithium

docs/src/evdev/tutorials/grabbing-and-repeat.md

@@ -1,3 +1,10 @@
+---
+order: 2
+title: Grabbing and Repeat
+description:
+  Grab input devices exclusively and configure keyboard repeat behavior.
+---
+
 # Grabbing Devices and Configuring Repeat
 
 This tutorial covers exclusive device access and auto-repeat settings.
@@ -10,95 +17,38 @@ compositors).
 
 ```lua
 local evdev = require "evdev"
-local dev = assert(evdev.device("/dev/input/event3"))
-
-local ok, err = dev:grab()
-if not ok then
-  error("grab failed: " .. err)
-end
-
--- Now only we receive events from this device
-for event in dev:events() do
-  if event.type == evdev.ecodes.EV_KEY and event.value == 1 then
-    print("key pressed:", event.code)
-  end
-end
+local Device = evdev.device.open
 
-dev:ungrab()   -- release the grab
-```
+local path = "/dev/input/event3"
+local dev = assert(Device(path))
 
-## Checking if a device is open
+assert(dev:grab())
 
-```lua
-if dev:is_open() then
-  print("device is still connected")
+-- After grab, events are delivered here and blocked from other programs
+for e in dev:events() do
+  print("key pressed:", e.code)
 end
 ```
 
-If the device gets unplugged and you try to read it, `read()` returns
-`nil, err`.
-
-## Device info after opening
-
-```lua
-print(dev.name)
-```
+> [!TIP]
+>
+> Call `dev:flush()` before grabbing to discard stale buffered events.
 
 ## Auto-repeat settings
 
-Linux input devices have built-in key repeat (initial delay and repeat rate).
-You can read and write these:
+Linux input devices have built-in key repeat with two parameters: **delay** (ms)
+and the repeat **period** (ms between repeats).
 
 ```lua
--- Read current settings
+-- Read current kernel repeat settings
 local delay, period = assert(dev:get_repeat())
-print("repeat delay:",  delay)   -- milliseconds before repeat starts
-print("repeat period:", period)  -- milliseconds between repeats
-
--- Set both at once
-assert(dev:set_repeat(300, 40))
-
--- Verify
-print(assert(dev:get_repeat()))
-```
+print("repeat delay:",  delay)  -- ms before repeat starts
+print("repeat period:", period) -- ms between repeats
 
-These are backed by the `EVIOCGREP` / `EVIOCSREP` ioctls and are live changes to
-the kernel's repeat parameters for that device.
+-- Set both at once (200 ms delay, 20 ms between repeats)
+assert(dev:set_repeat(200, 20))
 
-## Flushing buffered events
-
-Clear any pending events from the kernel buffer:
-
-```lua
-dev:flush()
+delay, period = assert(dev:get_repeat())
+print("new delay:", delay)
+print("new period:", period)
 ```
-
-Useful before starting a grab so stale buffered events don't interfere.
-
-## Complete grab example
-
-```lua
-local evdev = require "evdev"
-local dev = assert(evdev.device("/dev/input/event3"))
-
-assert(dev:grab())
-dev:flush()
-
-local last_key
-local press_count = 0
-
-for event in dev:events() do
-  if event.type == evdev.ecodes.EV_KEY then
-    if event.value == 1 then
-      press_count = press_count + 1
-      last_key = event.code
-      print(string.format("[%d] %s pressed", press_count, last_key))
-    elseif event.value == 2 then
-      print(last_key, "repeat")
-    end
-  end
-end
-```
-
-Remember to `ungrab()` when done, though `close()` also releases the grab
-automatically.