31 mouse buttons via kde's 'qt-copy'

Proposed for Deletion

This page has been proposed for deletion for the following reason:

this page is no longer required

Please use the discussion section of this page to voice your opinion on this.

This page provides a template for Project Elegance proposals.

Parts marked with * are mandatory!

Summary/Abstract*

Provide an extended version of the Qt 'MouseEvent' class, supporting buttons through #31 (for X11 only). Extended Class would add a method to get the full-width Mouse Button State mask (a 32-bit mask field), and a method to obtain the Button Number which was responsible for the most recent event.

Would resolve bugs 34362, 48062, and their duplicates. (These are both top-20 bugs, with THOUSANDS of Votes.)

Creation Date	03-Nov-2011
Status	Not yet written, but conceptual design exists in the corresponding Qt bug (QTBUG-19238). The Qt bug died when 4.x series was declared 'dead'. With some assistance and aggressive work, and limiting the scope to just a few of Qt's numerous input plugins, this could be completed in time for 4.8 KDE code freeze. Several files and classes would need to be be re-coded, but their changes would be transparent to the programmer of a KDE Application. Users would need to have the correct versions of these libraries. (The 'new' versions of the other files are binary-compatible with old programs, but also capable of setting the new bit and integer which indicate the a high-numbered Button created the Event.) Once written, this scheme could be applied to Qt-5 as well. (Qt-5 code, pulled from Gitorious a few weeks ago, supports no more mouse Buttons than Qt-4. It doesn't yet improve upon the bad implementation of earlier Qt Versions.) And yes, all of this should have been done within the Qt project itself.
Maintainers	Primary Lead and Contact Person: Rick Stockton (community ID 'Rickst29', email address '[email protected]'. Also reachable via the mailing list, '[email protected]'

Description*

This is a detailed description of your proposal. Include as much detail as possible. The following questions should be answerable by anyone who reads this:

• What is the problem this project tries to solve?

This project would solve KDE's long-standing problem, inherited from the Qt Toolkit, of supporting only 5 mouse buttons. (And before Qt 4.5, Qt supported only 3 buttons.) Although KDE Bugzilla shows huge numbers of votes and large numbers of duplicates complaining about this deficiency, Nokia/Qt refuses to provide any worthwhile assistance in enhancing their code.

Key references: https://bugs.kde.org/show_bug.cgi?id=34362 The basic "more mouse buttons" Bug (1421 votes, several Duplicates)

https://bugs.kde.org/show_bug.cgi?id=48062 The "mouse modifiers/shortcuts" Bug (1908 votes, few Duplicates)

https://bugreports.qt.nokia.com/browse/QTBUG-19238 My abandoned work at Qt (Which is assigned to a non-employee; never received needed feedback, and was abandoned by me following the decision to make 4.8 the last Release of the Qt-4 series.)

The 'modifier buttons' shortcut system is described in 'Related Work', below. Receiving the ButtonPress and ButtonRelease actions, and preventing Qt from destroying them, is this project (IMO, prerequisite for the second).

• What is the scope of this project (how big or small is the effect?)

The effects would be pervasive and favorable for the KDE Desktop. Obviously, KDE users and programmers who wish to utilize mice with 'extra' buttons would have a viable method for doing so. But, as a follow-up to this project, KDE's shortcut system can provide a translation of these now-unsupported Buttons into keystroke sequences; and it can allow use of low-numbered buttons as 'modifier buttons', creating even more mouse functionality. See the discussion below, under "Related Work".

• Who are the primary users and how will they benefit?

Anyone who uses a mouse would be able to 'drive' KDE Applications more easily, just from the mouse -- without switching to the keyboard as frequently as they must do now. And with just a few "extra" buttons, the follow-up shortcut scheme nearly doubles the number of 'virtual buttons' which a user can easily click. The better the mouse device, the greater the benefits for the KDE user.

• How is this solution better than other solutions (what we have now and how other projects solve the problem)

What we have now, with the mouse, is defective by design, and not any kind of "solution" at all. (This has provoked numerous angry comments in Bugzilla, along the lines of "... it's unbelievable that you've known about this fundamental problem for so many years, and haven't FIXED IT already!"). It was implemented by a persons, or persons, who didn't understand the XI Version 1.x API which we use. The buttons are all available in XI Version 1. And Windows mouse drivers, of course, allow users to work with *all* the Buttons on their expensive "Gamer Mouse" devices. We are at a severe UI disadvantage.

This design scheme is unique in preserving Binary Compatibility. The cost of doing so is the requirement that the KApplication programmer add an additional statement to get the actual Button Number which was responsible for the event, if they desire to take action upon a higher-numbered MouseButton Event. (After testing the Qt:MouseButton value and finding it to be HIGHER than the maximum value in Qt, "Qt::XButton2", the programmer must make a function call which returns the actual button number.)

Costs also occur in application memory usage, and the ongoing issue of code forked from Qt in the kde-copy Version.

I (Rick Stockton) am uncertain how to add a new value into this Qt Namespace enum (that is, without creating a new version of their entire namespace. It would be BC, but an ugly thing.)

With total non-cooperation from Qt, we would likely have to work with the 'full' Qt::MouseButtons byte in order to test for the currently undefined value, coding a full byte-wide masked comparison. High-order bits x00000020, x00000040, and x00000080 are unused. x00000080 should be probably be avoided, because it could (perhaps) lead to signage problems. I thus choose the x00000040 bit as the flag for 'Higher Button Number Caused the Event'.

Related Work

After this Button enhancement exists, it could be very easy for the User to further extend the mouse by designating easily-pressed button combinations as 'Modifier' + 'Click/DoubleClick' mouse command sequences. These would be defined in our shortcut system, with a UI TBD. Here are simple examples:

Suppose that a KDE User has only a basic mouse (3 buttons, one vertical wheel). By defining ButtonLeft and ButtonRight as 'Modifier Buttons' for the wheel, the user could perhaps drive horizontal scroll actions by holding ButtonLeft down while spinning the Wheel up for Tilt-Right, or Down for Tilt-left. At the same time, the user could also define the wheel to perform Zoom in/Zoom out when s/he is holding down RightButton while spinning the wheel.

Within KDE, the shortcut system would be translating these combinations into the corresponding keyboard combinations -- which have some common default values already. And of course, the user is free to define any other keycode sequence for any other set of held down 'modifier button' with click or doubleclick action on a different key.

Design

I imagine an implementation in which the currently-unused x00000040 bit, within Qt::MouseButtons, constitutes a flag that the Button number (from X11, or evdev/Wayland, or other supported input interface) is HIGHER than 9. (9 is the low-level integer value of XButton2.)

In this situation, it will be MANDATORY for the KApplication programmer to use the Getter function (int) MouseButtonNumber() to obtain the actual number of the Button which was responsible for the Event.

The other API feature will be another Getter function, returning a 32-bit mask field: The State of each Button, with Button1 in the right-most bit, will be indicated with '1' for State=Pressed, '0' for State=Unpressed. Mask Field bits on the left, higher than the highest possible Button number on the mouse being used, will always contain the value zero. Note that Buttons 4-7 (the wheel Button States) are included in the mask field, even though they may rapidly transition between 'Pressed' and 'Unpressed' State. Thus, the mask should not be considered as a reliable indicator for these particular buttons.

A Global, integer "shadow" value must also be added - so that the class can properly distinguish between Click and DoubleClick events. (In current Qt, this is done with values of Qt::MouseButton, but that is not sufficient to keep track of higher-numbered Buttons.)

It is uncertain, and CRITICAL, to determine which 'plugin' interfaces to low-level event library code will be modified. (glibc, xcb, etc.) Qt4 seems to have many such interfaces, and there is not sufficient time to change them all.

Affected Modules*

Which parts of KDE's software are affected? Which should definitely be part of the implementation process?

kwin, shortcuts (GUI and execution), qt-copy

Primary Modules

qt-copy: Change #1, enhanced QMouseEvent class. Change #2: enhanced low-level input classes and plugins. kwin and workspace: Execute WM actions. Can be done independently of Qt changes, since kwin receives un-grabbed events directly from X11.

Secondary Modules

The shortcut system - modules TBD. And corresponding GUI within 'System Settings'.

Project Timeline*

This section is the project plan for the proposal.

TODO

Milestone name	Milestone description	Assigned to	Status
Prerequisite Button numbering fixes in kwin	Rick Stockton	In progress
Implement proof-of-concept in Kwin	Rick Stockton	Not Started
Go/No-Go Decision (consensus from KDE-Core ML)	KDE strategic leaders	Not Started
Selection of low-level plugins to support	Consensus from KDE-Core	Not Started
Module coding and testing	Rick Stockton, with any volunteers	Not Started

Completed

NONE.

Milestone name	Milestone description	Assigned to	Status

Note

Please use the talk page to discuss this proposal.