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.