glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/event
term% cat index.txt
EVENT(2)                      System Calls Manual                     EVENT(2)



NAME
       event,  einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread,
       ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawge‐
       trect,  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)

       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 keyboard 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 argu‐
       ment new is a flag specifying whether the program must  call  getwindow
       (see  graphics(2))  to  re-establish a connection 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 mechanism.  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 position is always returned in xy.  Msec is
       a time stamp in units of milliseconds.

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

       Ereadmouse reads the next mouse event from  the  file  descriptor  con‐
       nected  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 descriptor to register, the max‐
       imum  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 returning 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 variable 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 milliseconds; it re‐
       turns  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 re‐
       turns 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  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 but‐
       ton 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  re‐
       leased  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 rec‐
       tangle  showing  the  sweep-in-progress.   The rectangle 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 charac‐
       ter strings to be displayed as menu items.  Otherwise, 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 to the default  ar‐
       row.

       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  be‐
       fore  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)



                                                                      EVENT(2)