Input API, as of v4

Where do I find the source?

Most of the stuff can be found in grab.c and grab.h, after the patch has been
applied.

New Types

/* GrabHandler:
   if your GrabHandler returns TRUE, your grab will be removed, otherwise it's
   kept active and you get more grabbed events passed to your handler.

   the default_keyboard_handler now simplifies access to subsequent keypresses
   when you establish a grab using grab_establish().
 */
typedef bool GrabHandler(WThing *thing, XEvent *ev);


typedef void InputEventHandler(XEvent *ev);
typedef struct input_event_handler{
    InputEventHandler *keyboard;
    InputEventHandler *pointer;
}InputHandler;


/* InputHandlerContext:
   current context. the fields prev and next are currently unused, but might
   eventually be used to allow InputHandler stacking or something like this.
   This structure is filled when passed to set_input_handler() and needs to be
   passed to restore_input_handler(), which will use ->oldhandler to fall back
   to to handlers we started off with.
 */
typedef struct input_handler_context{
    struct input_handler_context *prev, *next;
    InputHandler *oldhandler;
}InputHandlerContext;

Functions

/*
  grab_establish() is your new interface to XGrabKeyboard().

  Arguments:
  thing the thing you want to use as the context of the grab
  func: your GrabHandler callback responsible for handling keyboard events
  eventmask: a mask of events that should be blocked(!) while the grab is held
 */
void grab_establish(WThing *thing, GrabHandler *func, long eventmask);

/*
  grab_remove()

  usually you won't need to call grab_remove() yourself, as the caller of your GrabHandler
  does this for you based on the return value of your GrabHandler.
  i.e. if you are not interested in modifier-only key events and still want to receive
  the next keypress, return FALSE. if you're satisfied and want your GrabHandler to be removed,
  make your GrabHandler return TRUE.

  Arguments:
  func: the GrabHandler of the grab you want to remove.
     this argument is necessary to support stacked grabs that must not disturb each other.
     if you call grab_remove() with your GrabHandler, but you are not the current grab in control
     the removal will be deferred until all handlers above yours in the stack are also removed.
     but as soon as you call grab_remove() you can be sure, that your handler
     won't receive another keystroke until the next grab_establish()!
 */
void grab_remove(GrabHandler *func);


/* grab_held() returns true if there is currently any grab held through this grab_*() interface.
   if you established a grab in another way (manual call to XGrab[Keyboard|Pointer] or do_grab_kb_ptr()
   then you're on your own...
 */
bool grab_held();


/* grab_get_holder() returns the WThing you passed to grab_establish().
  func: the GrabHandler of the grab you want to get the holder of
  returns NULL if no such grab is found
 */
WThing grab_get_holder(GrabHandler *func);


/*
   grab_suspend() is currently not used, and might be thrown away. documentation pending
 */
void grab_suspend();

/*
   grab_resume() is currently not used, and might be thrown away. documentation pending
 */
void grab_resume();