EVENT(2)                                                 EVENT(2)

     NAME
          event, einit, estart, estartfn, etimer, eread, emouse, ekbd,
          ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse,
          eresized, egetrect, edrawgetrect, emenuhit, eenter, emoveto,
          esetcursor, Event, Mouse, Menu - graphics events

     SYNOPSIS
          #include  <u.h>
          #include  <libc.h>
          #include  <draw.h>
          #include  <event.h>
          #include  <cursor.h>

          void      einit(ulong keys)

          ulong     event(Event *e)

          Mouse     emouse(void)

          int       ekbd(void)

          int       ecanmouse(void)

          int       ecankbd(void)

          int       ereadmouse(Mouse *m)

          int       eatomouse(Mouse *m, char *buf, int n)

          ulong     estart(ulong key, int fd, int n)

          ulong     estartfn(ulong key, int fd, int n,
                        int (*fn)(int, Event*, uchar*, int))

          ulong     etimer(ulong key, int n)

          ulong     eread(ulong keys, Event *e)

          int       ecanread(ulong keys)

          void      eresized(int new)

          Rectangle egetrect(int but, Mouse *m)

          void      edrawgetrect(Rectangle r, int up)

          int       emenuhit(int but, Mouse *m, Menu *menu)

          int       emoveto(Point p)

     EVENT(2)                                                 EVENT(2)

          void      esetcursor(Cursor *c)

          int       eenter(char *ask, char *buf, int len, Mouse *m)

          extern Mouse    *mouse

          enum{
                    Emouse = 1,
                    Ekeyboard = 2,
          };

     DESCRIPTION
          These routines provide an interface to multiple sources of
          input for unthreaded programs.  Threaded programs (see
          thread(2)) should instead use the threaded mouse and key-
          board interface described in mouse(2) and keyboard(2).

          Einit must be called first.  If the argument to einit has
          the Emouse and Ekeyboard bits set, the mouse and keyboard
          events will be enabled; in this case, initdraw (see
          graphics(2)) must have already been called.  The user must
          provide a function called eresized to be called whenever the
          window in which the process is running has been resized; the
          argument new is a flag specifying whether the program must
          call getwindow (see graphics(2)) to re-establish a connec-
          tion to its window.  After resizing (and perhaps calling
          getwindow), the global variable screen will be updated to
          point to the new window's Image structure.

          As characters are typed on the keyboard, they are read by
          the event mechanism and put in a queue.  Ekbd returns the
          next rune from the queue, blocking until the queue is non-
          empty.  The characters are read in raw mode (see cons(3)),
          so they are available as soon as a complete rune is typed.

          When the mouse moves or a mouse button is pressed or
          released, a new mouse event is queued by the event mecha-
          nism.  Emouse returns the next mouse event from the queue,
          blocking until the queue is non-empty.  Emouse returns a
          Mouse structure:

               struct Mouse
               {
                     int   buttons;
                     Point xy;
                     ulong msec;
               };

          Buttons&1 is set when the left mouse button is pressed,
          buttons&2 when the middle button is pressed, and buttons&4
          when the right button is pressed.  The current mouse posi-
          tion is always returned in xy.  Msec is a time stamp in

     EVENT(2)                                                 EVENT(2)

          units of milliseconds.

          Ecankbd and ecanmouse return non-zero when there are key-
          board or mouse events available to be read.

          Ereadmouse reads the next mouse event from the file descrip-
          tor connected to the mouse, converts the textual data into a
          Mouse structure by calling eatomouse with the buffer and
          count from the read call, and returns the number of bytes
          read, or -1 for an error.

          Estart can be used to register additional file descriptors
          to scan for input.  It takes as arguments the file descrip-
          tor to register, the maximum length of an event message on
          that descriptor, and a key to be used in accessing the
          event.  The key must be a power of 2 and must not conflict
          with any previous keys.  If a zero key is given, a key will
          be allocated and returned.  Estartfn is similar to estart,
          but processes the data received by calling fn before return-
          ing the event to the user.  The function fn is called with
          the id of the event; it should return id if the event is to
          be passed to the user, 0 if it is to be ignored.  The vari-
          able Event.v can be used by fn to attach an arbitrary data
          item to the returned Event structure.  Ekeyboard and Emouse
          are the keyboard and mouse event keys.

          Etimer starts a repeating timer with a period of n millisec-
          onds; it returns the timer event key, or zero if it fails.
          Only one timer can be started.  Extra timer events are not
          queued and the timer channel has no associated data.

          Eread waits for the next event specified by the mask keys of
          event keys submitted to estart. It fills in the appropriate
          field of the argument Event structure, which looks like:

               struct Event
               {
                     int   kbdc;
                     Mouse mouse;
                     int   n;
                     void  *v;
                     uchar data[EMAXMSG];
               };

          Data is an array which is large enough to hold a 9P message.
          Eread returns the key for the event which was chosen.  For
          example, if a mouse event was read, Emouse will be returned.

          Event waits for the next event of any kind.  The return is
          the same as for eread.

          As described in graphics(2), the graphics functions are

     EVENT(2)                                                 EVENT(2)

          buffered.  Event, eread, emouse, and ekbd all cause a buffer
          flush unless there is an event of the appropriate type
          already queued.

          Ecanread checks whether a call to eread(keys) would block,
          returning 0 if it would, 1 if it would not.

          Getrect prompts the user to sweep a rectangle.  It should be
          called with m holding the mouse event that triggered the
          egetrect (or, if none, a Mouse with buttons set to 7).  It
          changes to the sweep cursor, waits for the buttons all to be
          released, and then waits for button number but to be
          pressed, marking the initial corner.  If another button is
          pressed instead, egetrect returns a rectangle with zero for
          both corners, after waiting for all the buttons to be
          released.  Otherwise, egetrect continually draws the swept
          rectangle until the button is released again, and returns
          the swept rectangle.  The mouse structure pointed to by m
          will contain the final mouse event.

          Egetrect uses successive calls to edrawgetrect to maintain
          the red rectangle showing the sweep-in-progress.  The rect-
          angle to be drawn is specified by rc and the up parameter
          says whether to draw (1) or erase (0) the rectangle.

          Emenuhit displays a menu and returns a selected menu item
          number.  It should be called with m holding the mouse event
          that triggered the emenuhit; it will call emouse to update
          it.  A Menu is a structure:

               struct Menu
               {
                     char  **item;
                     char  *(*gen)(int);
                     int   lasthit;
               };

          If item is nonzero, it should be a null-terminated array of
          the character strings to be displayed as menu items.  Other-
          wise, gen should be a function that, given an item number,
          returns the character string for that item, or zero if the
          number is past the end of the list.  Items are numbered
          starting at zero.  Menuhit waits until but is released, and
          then returns the number of the selection, or -1 for no
          selection.  The m argument is filled in with the final mouse
          event.

          Emoveto moves the mouse cursor to the position p on the
          screen.

          Esetcursor changes the cursor image to that described by the
          Cursor c (see mouse(2)). If c is nil, it restores the image

     EVENT(2)                                                 EVENT(2)

          to the default arrow.

          Eenter provides a simple method of text input in graphical
          programs. It displays a box at the current position of the
          mouse cursor (passed in the Mouse *m argument) in which text
          can be typed and edited.  If the string argument ask is not
          nil, it is displayed as a static label before the input
          string.  The buf parameter contains the null-terminated
          input string to be edited. The len argument specifies the
          length of buf in bytes including the terminating null byte.
          If buf or len is zero, no text can be entered.  On success,
          eenter returns the number of bytes in the edited string buf
          or -1 on error.

     SOURCE
          /sys/src/libdraw

     SEE ALSO
          rio(1), graphics(2), plumb(2), cons(3), draw(3)