API Advice needed: Mouse Shortcuts Database

[Rick Stockton]

Before I begin- I am extremely interested in any upcoming re-factor 
scheme, which could 'share' as much code as possible (between QtGui and 
Widget-based shortcuts) at a 'higher" level.

With that said, however, my "little" project won't be sharing very much 
of the current code, because nearly all existing code is INTIMATELY tied 
into the fact that KeySequences (and their overrides, when necessary) 
are tied to the keyboard. I'll 'friend' those classes, when necessary, 
to get at things which can be shared immediately. The header file 
'qkeysequence.h', will be included frequently to define 'standard keys' 
-- or should I split out that enumeration into another file, without all 
of the Method definitions ???

Anyway, her is my tentative DB design.
Mouse Shortcuts will be organized into an 2D array of 
MouseShortcutButtonSets. The first index is for the type of mouse event:
    0 == single-click
    1 == double-click

The second index of the Table is the shift index of the responsible 
'Button Number'. (i.e., the amount by which the Qt::MouseButton value 
which was responsible for the event gets shifted to the right, in order 
to result in value 'x1'== 0x00000001. This is, basically, the original 
(int) value of the 'raw button number' which we received, and translated 
_into_ a Qt::MouseButton value, within one of our platform plugins. In 
Qt 5.0, the size in this Dimension includes integers from 0 
(Qt::LeftButton) to 27 (Qt::MaxMouseButton).

Each Array Cell shall be the entry point of a QMultiHash() hashmap, or 
maybe just a list. The thing which we need to find quickly in the set of 
shortcuts for a given mouse click/doubleclick is the entries which 
correspond to a particular shortcut 'owner' -- and this is PROBABLY best 
done by using a QMultiHash().

*** question *** : Or, is the number of alternative 'owners' for a given 
mouse click, or double-click, likely to be so small that I should simply 
make it a linked list, inspected from start-to-finish?

Anyway, once we have the owner, we have a byte of bit flags (mostly unused):
   value in the lowest bit: whether the shortcut is currently Disabled 
(0 == Enabled, 1 == Disabled)
   value next bit: whether Qt::LeftButton is being held down, concurrent 
with the click (or double-click) of another button. 0 == No, 1 == Yes)
   bit 2: whether Qt::RightButton is beng held down concurrently (0 == 
No, 1 == Yes)
   Upper bits 3-7 are available for future use.

This ability to use Qt::LeftButton, Qt::RightButton as 'Modifier 
BUTTONS' _for other buttons_ increases the number of possible mouse 
shortcuts by quite a lot. For example, using just Qt::BackButton, you 
can have:
   Shortcut A == single-click of Qt::BackButton; (And THIS ONE will 
often already be in use, as a default 'Back'  action which you want to 
keep unchanged.)
But all these others are new, and they're not difficult for people with 
fully-functional hands to Press:
   Shortcut B == double-click of Qt::BackButton;
   Shortcut C == single-click of Qt::BackButton with Qt::LeftButton held 
down;
   Shortcut D == double-click of Qt::BackButton with Qt::RightButton 
held down;
   Shortcut E == single-click of Qt::BackButton with Qt::LeftButton held 
down;
   Shortcut F == double-click of Qt::BackButton with Qt::MouseButton2 
held down;
   Shortcut G == single-click of Qt::BackButton with BOTH Qt::LeftButton 
and Qt::RightButton held down;
   Shortcut H == double-click of Qt::BackButton with BOTH Qt::LeftButton 
and Qt::RightButton held down.





I DO NOT see any need for shortcut 'invocation sequences' with keyboard 
and mouse combined. The requests are for one-handed Shortcuts, done ONLY 
with the mouse. (Not needing a second hand). There will be, however, the 
need for a Mouse Shortcut 'OverRideKey'. I will make this user-settable, 
but I plan to insist that the permissible values be ONLY one of the 
modifier keys. That's because modifier key status is given to us with 
the button Event, right in the plugin.

I will probably have to duplicate the 'owner' value in each shortcut 
entry. I might also need to keep track of the current Window on which 
I'm trying to execute the shortcut, if they're supposed to 'escalate' 
into parent widdgets and parent GUI elements auto-magically. This leads 
to *** questions ***

I really don't understand the concept of 'shortcut owner', especially 
with regard to Application-Wide shortcuts. If a shortcut is NOT 
'Application-Wide', will it try to run it's action on each of a Widget's 
parents? Or does the shortcut need to have a duplicate created into each 
viable parent, differing only in the 'Widget'? And how SHOULD I handle 
escalation from a GUI MouseArea?

My last question: I'm also unclear whether each shortcut in the 'map' 
should be associated ONLY with the result of sending a Signal or whether 
they should also have the option of linking to an Action directly.
- - - -

Thanks in advance. Yes, I can 'learn' by reading code, but my results 
will be faster, BETTER with help to go from Concept to Design to Code 
... rather than reading the code, trying to extract a Design, and 
GUESSING at the concepts behind it. So, please tell me how shortcuts 
'want' to work, in a few sentences.