From 6ca68635e8cef8407e91bc9542edf196ef708210 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 17 Dec 2021 10:43:11 -0500 Subject: Make button numbers consistent across platforms There's no universal consensus on how buttons are numbered. Left, right, middle as 0, 1, 2 seems to be the most common convention on modern vaguely similar libraries, so I've gone with that. The switch to zero-based indices will obviously break all current client code. Particularly since now is the time to finish any breaking changes before a stable release, I think that is better than only changing the middle and right numbers, which would likely go unnoticed. --- include/pugl/pugl.h | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'include/pugl') diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h index 71578a9..4d26604 100644 --- a/include/pugl/pugl.h +++ b/include/pugl/pugl.h @@ -419,6 +419,21 @@ typedef struct { /** Button press or release event. + + Button numbers start from 0, and are ordered: primary, secondary, middle. + So, on a typical right-handed mouse, the button numbers are: + + Left: 0 + Right: 1 + Middle (often a wheel): 2 + + Higher button numbers are reported in the same order they are represented on + the system. There is no universal standard here, but buttons 3 and 4 are + typically a pair of buttons or a rocker, which are usually bound to "back" + and "forward" operations. + + Note that these numbers may differ from those used on the underlying + platform, since they are manipulated to provide a consistent portable API. */ typedef struct { PuglEventType type; ///< #PUGL_BUTTON_PRESS or #PUGL_BUTTON_RELEASE @@ -429,7 +444,7 @@ typedef struct { double xRoot; ///< Root-relative X coordinate double yRoot; ///< Root-relative Y coordinate PuglMods state; ///< Bitwise OR of #PuglMod flags - uint32_t button; ///< Button number starting from 1 + uint32_t button; ///< Button number starting from 0 } PuglButtonEvent; /** -- cgit v1.2.1