events between the backend and the widget system 

/* Events are mostly user input related. Normally they are processed by
   a handler installed on a widget. The application code rarely needs to
   deal with events, the handler would convert them to higher level
   per-widget function callbacks. */


typedef enum mbtk_event_type_e {
  MBTK_EV_KEY_PRESS,      /* data.key */
  MBTK_EV_KEY_RELEASE,    /* data.key */
  MBTK_EV_MOUSE_PRESS,    /* data.mouse */
  MBTK_EV_MOUSE_RELEASE,  /* data.mouse */
  MBTK_EV_MOUSE_MOTION,   /* data.mouse */
  MBTK_EV_MOUSE_SCROLL,   /* data.mouse (mouse wheel motion, using .x); positive is up and to the right */
  MBTK_EV_WIN_EXPOSE,     /* data.win (called when window needs to be redrawn) */
  MBTK_EV_WIN_MOVE,       /* data.win (x;y) */
  MBTK_EV_WIN_RESIZE,     /* data.win (w;h) */
  MBTK_EV_WIN_CLOSE,      /* data.win */
  MBTK_EV_WIN_ENTER,      /* data.win; mouse has entered window (mouse focus on window) */
  MBTK_EV_WIN_LEAVE,      /* data.win; mouse has left window (no mouse focus on window)*/
  MBTK_EV_RSTDIN,         /* data.rstdin */
  MBTK_EV_FDWATCH,        /* data.fdwatch */

} mbtk_event_type_t;

typedef enum mbtk_mouse_button_e {
  MBTK_MB_LEFT   = 1,
  MBTK_MB_MIDDLE = 2, /* not guaranteed to exist */
  MBTK_MB_RIGHT  = 3,

  /* these are not guaranteed to exist on the actual hardware and their mapping
     is rather random. Scroll up/down/left/right _not_ included in these. It's
     generally unsafe to use these and assume a specific button. It may be safe
     to use these with dynamic (user configurable) assignment. */
  MBTK_MB_EXTRA1 = 4,
  MBTK_MB_EXTRA2 = 5,
  MBTK_MB_EXTRA3 = 6,
  MBTK_MB_EXTRA4 = 7,
  MBTK_MB_EXTRA5 = 8,

  /* anything not covered above */
  MBTK_MB_UNKNOWN = 9
} mbtk_mouse_button_t;


struct mbtk_event_s {
  mbtk_event_type_t type;
  mbtk_window_t *win;
  union {
    struct {                 /* either combined raw+edit, raw only or edit only */
      int scancode;          /* raw: hw-specific (for debug purposes only) */
      mbtk_keysym_t sym;     /* raw: base key (ASCII) */
      mbtk_keymod_t mods;    /* raw: modifiers */
      unsigned long edit;    /* 0 or translated key (unicode codepoint, UTF-32); something that can be put into a text input edit; happens on KEY_RELEASE */
    } key;
    struct {
      long x, y;
      char button; /* one of mbtk_mouse_button_t */
    } mouse;
    struct {
      long x, y, w, h;
    } win;
    struct {
      char *data;  /* valid until the next event received */
      size_t len;
    } rstdin; /* read on stdin */
    struct {
      int fd;
      unsigned readable:1;
      unsigned writable:1;
      unsigned closed:1;     /* hup, error and anything alike */
    } fdwatch;
  } data;
};


/* Convert event type to human readable event name; returns "unknown" for
   invalid types */
const char *mbtk_event_type_name(mbtk_event_type_t t);

/*** non-gui event control ***/

/* Enable or disable reading stdin and reporting the bytes in events for disp;
   shall be enabled only for one disp at a time. May enable emitting
   MBTK_EV_RSTDIN events. */
void mbtk_watch_stdin_read(mbtk_display_t *disp, int enable);


/* Enable or disable watching fd in a disp. If for_read and/or for_write is
   true, the watch is enabled; if both are false, fd is not watched any more.
   If an fd is closed by the system or peer, it is automatically removed from
   watch before the event is emitted with the close bit set.
   May enable emitting MBTK_EV_FDWATCH events. Does NOT work on stdio
   (because of windows)!*/
void mbtk_watch_fd(mbtk_display_t *disp, int fd, int for_read, int for_write);


/*** High level ***/

/* Keep iterating the whole GUI until win is closed. When this call returns,
   win is not valid anymore as it has been closed. */
void mbtk_run_window(mbtk_window_t *win);

/* The _for variant returns (breaks blocking) if win is closed. */
int mbtk_iterate(mbtk_display_t *disp, mbtk_event_t *dst, int block);
int mbtk_iterate_for(mbtk_display_t *disp, mbtk_event_t *ev, int block, mbtk_window_t *win);