[Qt5-feedback] Thanks for your (FIRST round of... ) Mouse Button comments!

[Rick Stockton]

Wow, you guys are fast! And smart, too. :))
Samuel gave me an especially detailed set of comments, some complex, 
which I'll talk about in another post (to be written in a few hours). 
This one covers a few SIMPLE items quickly, so that we can take them off 
the table.

--- 1. The maximum number of buttons *WILL NEVER* exceed 32. ---
First, let me give some detail about the 'maximum possible number of 
buttons'. It DEFINITELY can't be more than 32, and might possibly be 
limited to 31. Many protocol elements and functions use fields of one 
byte or two bytes, or four bytes, or allow the possibility of _more_ 
than one 32-bit value for the button mask, so you might guess that we 
could do more. But we can't. Deep inside the code, and also within a ton 
of header files, the set of values reserved for JOYSTICK BUTTONS begins 
32 "Buttons" later than Button #1 of the "MOUSE BUTTONS" set. 32 buttons 
is considered adequate by everybody involved at a low level (Daniel 
Stone, Peter Hutterer, etc.); but far more important -- everyone agrees 
that it would be an absolute nightmare to increase the number.

Finally, in the _very_ long term, I feel that future devices with "more 
buttons" will not be 2-dimensional mice. They will be more like pens, 
waved in 3-dimensional space.

But I loved the joke about 640 Kbytes. I bet one of us could find a 
similar quote from Steve Jobs, along the lines of "no one will ever need 
more than two buttons" - if we had time to waste on that ;)

--- 2. The Highest number of Buttons ever implemented under x11, so far, 
is 27. ---
Daniel Stone remembers fixing x11 so that it could support that device, 
although he doesn't remember the manufacturer (and I don't see one for 
Sale in the current "PC" marketplace. In addition to the 18-button Mouse 
which Samuel found, I'll point at the Razer 'Naga' models: They each 
have twelve button "thumb" area, and they claim a total of 17 
"programmable" buttons. (I don't know if they are including the wheel 
counting the wheel button numbers 4/5 and 6/7 in this count- but I think 
that they are including the 4 scroll directions as "programmable"). This 
is a *very* popular mouse for Internet multi-player gaming addicts, 
although it is uncomfortably small for my own hand. (And thanks for that 
link to the 18-button device). My own Logitech L700 has 3 taller 
mini-buttons at the edge of BUTTON_LEFT, and a four-button "thumb" 
pattern. I may also have one more "genuine button" placed below the 
scroll wheel, but I don't remember if it's a genuine button, per a 
response from xev.

I've been using evdev with my own mice for 3 years. My driver is 
compatible with Wayland already, and I can test anything we write to 
solve this long-standing issue with (qt4) .... AND Wayland as well. 
Samuel and Theo, I think that we should be considering the the following 
Thread from the Wayland-Devel mailing list from a few months ago: 
http://lists.freedesktop.org/archives/wayland-devel/2011-January/000502.html 
. That initial posting pleads for input to be comprehensive, and 
backward compatible with XI 2.1 -- but the follow-ups indicate a 
strategy of a more basic input scheme for "Wayland 1.0", with 
"Wayland-Input-2.x" to follow later. The big advantage over the x11 
scheme is, they know already (before even starting) that they will need 
to support the 2.x API and the 1.x API concurrently: 2.x ** MUST! ** be 
backward compatible with "Wayland-Input-1.x".

--- 3. The Button Names, if put into an enumeration, are an 
insignificant issue. ---
In the code I've looked at, there's only one reference to a enum name 
for a higher button: In that case, the button following #9 ("FORWARD", 
our "XButton2") was called "TASK". But we can choose whatever we like, 
and we can put in duplicates... in the same way I showed as a "while I'm 
in here, do a quick and dirty fix" on XButton1 and XButton2.

--- 4. IMO, we can and MUST keep BC while doing this. ---
The 'broken compatibility' elements in qt5 should be minimized (each 
becomes a quagmire of creating, and then supporting, the "qt4 
compatability" library API as separate code.) We CAN do this without 
breaking BC, and my strategy provides for that goal. Most important of 
all: if we avoid BC breakage, we can implement it in qt4.... which, for 
many reasons, could be around for quite a while.

Here are the key issues surrounding the BC requirement:
*A* We cannot "stretch" the enumerated names past the one-byte boundary. 
(That would break on big-endian versus little-endian machines, because 
the 2nd byte "stretches" the enum byte field in opposite directions.)

*B* We cannot add the button number as an integer in the Event API (The 
change in Event signature would break BC, right? The event comes from 
below, so we can't use a caller's parameter Types to select an 
appropriate set of Event return values.)

*C* We cannot increase the size of the mask byte within the event API 
(also breaks BC of the signature).
With this design, we stay within one byte-- and the last bit value tells 
the programmer that he needs to call a function to obtain his button 
number. (That's a Task-State call into X11/Wayland/Whatever, but 
non-wheel button events are very stable in terms of Task versus Event 
State code priority. They don't happen "too quickly".)

I neglected to say, yesterday, that the full-width button mask (32 bits 
wide) must also be obtainable via a function call. That's the solution 
to issue (C). It would be probably be very valuable for KWin programmers 
to be able to SET the values for both functions as well (i.e. the button 
number, and the mask).

But such things depend on having the buttons, first. Kwin gets the 
events from x11 before passing them to a Window, and a lot of very 
desirable UI code for Desktop Effects could be done without involving 
qt- but I HATE the idea of leaving all this unavailable to Qt library 
users. Kwin currently sets the qt enumerated button values upon 
receiving the x11 events, and this allows the qt toolkit to be used 
internal to KWin and it's friends.

My objectives for KWin are: #1 to allow these high numbered buttons to 
do clever things, such as "show all desktops" without resorting to the 
keyboard at all; And (drum roll for #2 occurs here) shortcuts based on 
multiple mouse buttons. For example, it's extremely comfortable to hold 
"BUTTON_RIGHT", while pressing a thumb button, and the combination could 
be used as yet another unique shortcut action.

With a tilt wheel+7 button device (i.e., a 4 thumb-button pattern), this 
would allow KDE users to drive virtually ALL existing desktop effects 
with one hand- never reaching for the keyboard at all. And BTW, I'd want 
to advise the GTK+ and Wayland people that it might be REALLY NICE to 
define one such combination as the Z-order wheel (Zoom In/Zoom Out) "by 
convention". I would vote for "BUTTON_RIGHT" while scrolling the 
standard wheel Up/Down scroll wheel. (I.e., raw Button4/Button5).
-----

All this becomes possible, if only we clean up the prehistoric design 
defect. And we can do it in qt4 as well! Long ago, someone looked at the 
5-button mask, and the 5 button names, and didn't pay any attention to 
the fact that the button NUMBER is given as an integer, and always was. 
It was a really bad mistake, and this has provoked THOUSANDS of 
complaints and votes in KDE Bugzilla. (It's one of the all time "top-20" 
most hated "bugs", and it's also directly responsible for a second in 
that list.)
- - - - -

This design is extremely low risk, IMO. I feel it to be comparable to 
the adding of "BUTTON_BACK" and "BUTTON_FORWARD" in qt 4.7.  (We called 
them "XButton1" and "XButton2"; but, if we making the actual integer 
numbers available, badly-chosen names will not matter so much. And we 
can add extra names for the same enum bit field, as currently exists for 
"MiddleButton" and "MidButton". (I've already done that in my draft, 
adding names "BackButton" and "ForwardButton" as synonyms for these two 
"XButtons").

Thanks for reading. I'm too talkative, probably, but I've got a lot of 
background info on these issues, and wanted to share it ASAP. I'm 
looking forward to a second round of comments!