## Responding to Mouse Events

### OBJECTS

      typedef void (*MouseFunc)(Control *c, int buttons, Point xy);

### FUNCTIONS

      void  on_control_mouse_down(Control *c, MouseFunc mouse_down);
      void  on_control_mouse_up  (Control *c, MouseFunc mouse_up);
      void  on_control_mouse_drag(Control *c, MouseFunc mouse_drag);
      void  on_control_mouse_move(Control *c, MouseFunc mouse_move);

### CONSTANTS

      enum {
        NO_BUTTON     = 0,
        LEFT_BUTTON   = 1,
        MIDDLE_BUTTON = 2,
        RIGHT_BUTTON  = 4
      };

### NOTES

The functions on_control_mouse_down, on_control_mouse_up, on_control_mouse_drag, on_control_mouse_move allow controls to respond to mouse events. They associate call-back functions with a control, so that when a certain kind of mouse events occurs, the relevant call-back function is called.

Each of the functions handles a different kind of mouse event:

- A mouse_down occurs when a mouse button is clicked while the mouse pointer is inside a control.
- A mouse_move occurs when the mouse is moved within a control, but no mouse buttons are held down at the time.
- A mouse_drag occurs when the mouse is moved while one or more mouse buttons are held down at the same time.
- A mouse_up occurs when any mouse button is released (some mouse buttons may still be held down).

Each of the call-backs are defined as MouseFunc. A MouseFunc has an integer parameter `buttons` and a point `xy` expressed in the control's own co-ordinate system. These refer to the mouse state at the time the event happened.

If any of the mouse buttons are held down when the call-back is activated, the `buttons` parameter will be set to reflect the fact. It is a bit-field which is organised so that `buttons & LEFT_BUTTON` is set when the left mouse button is down, `buttons & MIDDLE_BUTTON` corresponds to the middle mouse button and `buttons & RIGHT_BUTTON` corresponds to the right mouse button. It will be zero if no buttons are held down.

For systems which have a mouse with fewer than three buttons, extra buttons can be simulated by holding down modifier keys and clicking with the left button. Holding down Shift simulates a right mouse button click, while holding down Ctrl simulates a middle button click. Holding down Alt simulates a left mouse button click, which is useful for situations where the user wants several buttons clicked at the same time on a two or one button mouse.