Events

Handling input events is CLUE's main job, and it's an area where CLUE does a lot of the work for programmers automatically. Application programmers don't have to worry about much more than setting up an event loop, as shown in Section

. Contact programmers need to know how to use CLUE's event translation mechanism in order to implement the details of a contact's input behavior.

What exactly are these events we're talking about? Fundamentally, an event is a message to the program from the X server, a packet of data describing some occurrence that the program ought to be interested in. Most events represent an action performed by the user with the X server's keyboard or pointing device (i.e. mouse, tablet, etc.). Keyboard actions, for example, can generate :key-press and :key-release events. The pointer may be used to generate :button-press and :button-release (when the user presses one of the mouse buttons) and :motion-notify events (when the user changes the pointer position). These kind of user events contain data for the button or key involved, the coordinates of the pointer position, and other useful things, such as the up/down state of :shift, :control, and the other modifier keys. In addition to user events, there is another important group of side-effect events, events which occur as an indirect result of other user actions. For example, when the user causes part of an obscured window to become visible, an :exposure event may be sent. Other side-effect events include :enter-notify, which signifies that the user has moved the pointer cursor inside a particular window, and :focus-in, which happens when the user has identified a particular window as the focus for keyboard events. This is just the beginning, but the definition and meaning for all of the events received by CLUE contacts can be found by reading the X Protocol Specification.

To understand CLUE event processing, let's start with the basic program event loop and follow its operation, step by step. A call to process-next-event gets the ball rolling. process-next-event causes CLUE to read the next event from the given contact-display connection. By default, process-next-event does not return until the next event has been completely processed. This means that if no event is yet available, then process-next-event will generally wait until one finally comes along. However, an optional timeout argument may be given, which says how long process-next-event will wait before giving up. Set the timeout to 0 if you don't want process-next-event to wait at all. process-next-event returns nil if a timeout occurred; otherwise, it returns t.

(catch :event-loop
  (loop
    (unless 
      (process-next-event display 5)  ; Timeout after waiting 5 sec.

      ;; No events yet -- do something useful
      (do-background-task))))

$\framebox[5.5in]{ \hspace*{\fill} {\bf Note} \hspace*{\fill} \parbox[t]{4.5in}{ ... ...pe the event loop by {\tt throw}'ing to some well-defined tag.} \hspace*{\fill}}$

Inside process-next-event, the next thing that happens is that the event is dispatched. In other words, CLUE figures out which contact is supposed to handle the event. This is fairly easy because almost every event message contains an identifier for the window object which is the ``addressee'' of the event. CLUE knows how to convert this identifier into the corresponding contact object. At this point, the event is handled by calling the handle-event function with the receiving contact and the event as its arguments. handle-event then implements the process of event translation, i.e. figuring out which methods of the receiving contact to call in response to the event⁴. What happens next is of interest only to contact programmers.

Subsections