--- name: "event" section: "3g" platform: "linux" package: "libxg-dev" version: "4.3-14" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/event/3g" --- # event(3g) graphics events ## NAME event, einit, estart, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereshaped, getrect, menuhit, Event, Mouse, Menu - graphics events ## SYNOPSIS ``` #include #include ``` **void einit(ulong keys)** **unsigned long event(Event \*e)** **Mouse emouse(void)** **int ekbd(void)** **int ecanmouse(void)** **int ecankbd(void)** **unsigned long estart(ulong key, int fd, int n)** **unsigned long etimer(ulong key, int n)** **unsigned long eread(ulong keys, Event \*e)** **int ecanread(ulong keys)** **void ereshaped(Rectangle r)** **Rectangle getrect(int but, Mouse \*m)** **int menuhit(int but, Mouse \*m, Menu \*menu)** enum{\ Emouse = 1,\ Ekeyboard = 2, } ## DESCRIPTION These routines provide an interface to multiple sources of input. To use them, *einit* must be called. If the argument to *enit* has the **Emouse** and **Ekeyboard** bits set, the mouse and keyboard events will be enabled; in this case, *xtbinit* (see [*graphics*(3g)](/graphics/3g.md)) must have already been called. The user must provide a function called *ereshaped*, which will be called whenever the window in which the process is running has been reshaped; the argument will be the Rectangle for the new window shape, including the border. As characters are typed on the keyboard, they are read by the event mechanism and put in a queue. *Ekbd* returns the next character from the queue, blocking until the queue is non-empty. The characters are read by the event mechanism from the keyboard so they are available as soon as they are typed. When the mouse moves or a mouse button is depressed 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; unsigned long msec; }; ``` **Buttons** is a bit field; **buttons&1** is set when the left mouse button is depressed, **buttons&2** when the middle button is depressed, and **buttons&4** when the right button is depressed. The current mouse position is always returned in **xy**. **Msec** is the time stamp of the mouse event in units of milliseconds. *Ecankbd* and *ecanmouse* return non-zero when there are keyboard or mouse events to available to be read. *Estart* can be used to register additional file descriptors. It takes as arguments the file descriptor 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 confilict with any previous keys. If a zero key is given, one which is not used will be chosen and returned. **Ekeyboard** and **Emouse** are the mouse and keyboard event keys. *Etimer* starts a repeating timer with a period of n milliseconds (default 1 second). 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; uchar data[EMAXMSG]; } ``` **Data** is an array which is large enough to hold a plan 9 protocol 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*(3g)](/graphics/3g.md), the graphics functions are buffered. *Event*, *eread*, *emouse*, and *ekbd* all cause a buffer flush unless there is an event of the appropriate type ready to return. *Getrect* is used to prompt the user to sweep a rectangle. It should be called with *m* holding the mouse event that triggered the *getrect* (or, if none, a **Mouse** with **buttons** set to 7). It changes to the sweep cursor, waits for the buttons to all go up, and then waits for button number *but* to be depressed, marking the initial corner. If another button is depressed instead, *getrect* returns a rectangle with zero for both x-coordinates, after waiting for all the buttons to be released. Otherwise, *getrect* 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. *Menuhit* displays a menu and returns a seleced menu item number. It should be called with *m* holding the mouse event that triggered the *menuhit .* 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. 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. ## SEE ALSO [*graphics*(3g)](/graphics/3g.md).