Difference between revisions of "31 mouse buttons via kde's 'qt-copy'"

Jump to: navigation, search
(Few updates to layout, some changes to content)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{Proposed_deletion|reason=this page is no longer required}}
 +
 
This page provides a template for Project [[Elegance]] proposals.
 
This page provides a template for Project [[Elegance]] proposals.
  
Line 4: Line 6:
  
 
= Summary/Abstract* =
 
= Summary/Abstract* =
Give a short intro to the problem/idea - 2 or 3 sentences. People should be able to have an idea of what you are trying to do and recognize your project by reading this.
+
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  
 
! Creation Date  
| Creation date of the proposal
+
| 03-Nov-2011
 
|-
 
|-
 
! Status
 
! Status
| Current status of the proposal
+
| 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
 
! Maintainers
| The project maintainers and their contact information. Indicate Primary Lead/Contact person
+
| Primary Lead and Contact Person: Rick Stockton (community ID 'Rickst29', email address '[email protected]'. Also reachable via the mailing list, '[email protected]'
 
|-
 
|-
 
|}
 
|}
Line 23: Line 32:
  
 
* What is the problem this project tries to solve?
 
* 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?)
 
* 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?
 
* 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)
 
* How is this solution better than other solutions (what we have now and how other projects solve the problem)
* How will it effect other parts of KDE?
+
 
 +
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 ==
 
== Related Work ==
References to related research or other projects that will back up your proposal.
+
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:
* If this is a list of links to publications, they should be referenced in the detailed description
+
 
* Alternatively, this can be an annotated citation list (short 2-3 word summary of relevant conclusion of each paper), or a literature review summary itself (with relevant citations listed at the end)
+
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 ==
 
== Design ==
Discussion and details of the design of the proposal. This includes workflows, UI mockups, graphics, interface guidelines, interface proposals, usability testing and results, etc.
 
  
Detailed description of user requirements and needs will also go here, including any workflow or UI details specific to user groups.
+
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.)
  
== Implementation ==
+
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.
Discussion and details on implementation details.
 
  
 
= Affected Modules* =
 
= Affected Modules* =
Which parts of KDE's software are affected? Which should definitely be part of the implementation process? Provide a short description here and then list out the primary and secondary modules in detail. This may be related to scope: if so, be sure to explain.
+
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===
 
===Primary Modules===
 
{|
 
{|
 
|-  
 
|-  
! Name of module
+
qt-copy: Change #1, enhanced QMouseEvent class. Change #2: enhanced low-level input classes and plugins.
! Description of changes
+
 
|-
+
kwin and workspace: Execute WM actions. Can be done independently of Qt changes, since kwin receives un-grabbed events directly from X11.
| KHotNewStuff
 
| Default icon changed from favicon to khns
 
|}
 
  
 
===Secondary Modules===
 
===Secondary Modules===
 
{|
 
{|
 
|-  
 
|-  
! Name of module
+
The shortcut system - modules TBD. And corresponding GUI within 'System Settings'.
! Description of changes
 
|-
 
| KHangMan
 
| Icon on Get New Puzzles button should be updated to use khns icon
 
 
|}
 
|}
  
 
= Project Timeline* =
 
= Project Timeline* =
This section is the project plan for the proposal. It includes a project timeline (a record of when certain milestones are met, or expected to be met), information on who is working on what, changes in status including an indication of final implementation and release.
+
This section is the project plan for the proposal.
 
 
These items may be low-level implementation details or high-level project goals (such as "Complete User Survey of KHNS Use").
 
  
 
== TODO ==
 
== TODO ==
Line 77: Line 112:
 
! Status
 
! Status
 
|-
 
|-
| Update KHNS Class
+
| Prerequisite Button numbering fixes in kwin
| Update KHNS class to call khns icon
+
| Rick Stockton
| Jeremy Whiting
+
| In progress
| 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 ==
 
== Completed ==
 
{|
 
{|
Line 91: Line 141:
 
| Status
 
| Status
 
|-
 
|-
| Create KHNS Icon
+
 
| Need a dedicated icon for KHNS
+
NONE.
| Nuno Pinhero
 
| Completed (12-Nov-2009)
 
 
|}
 
|}
  
  
 
{{Note|Please use the talk page to discuss this proposal.}}
 
{{Note|Please use the talk page to discuss this proposal.}}

Latest revision as of 09:17, 9 March 2016

Flag-red.png
 
Proposed for Deletion
This page has been proposed for deletion for the following reason:

this page is no longer required

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-box-icon.png
Note
Please use the talk page to discuss this proposal.

This page was last edited on 9 March 2016, at 09:17. Content is available under Creative Commons License SA 4.0 unless otherwise noted.