src/SUIT/SUIT_ShortcutMgr. ReadMe.md

   1  # ShortcutMgr ReadMe
   2
   3 Hot keys must be considered as resources, being shared between all components of an application. E.g. it is unacceptable to have 'Close file' and 'Redo' actions being assigned to the same key sequence. When the SHAPER module is active, the application desktop is active too. The desktop has own hot keys, and they must not interfere with ones of SHAPER. Since the task implies granting users a right to assign shortcuts on their will, the application must track all assigned shortcuts of all modules, prevent intolerable user shortcut modifications and govern actual binding of QActions with key sequences.
   4
   5 `SUIT_ShortcutMgr` handles shortcuts of SALOME desktop and all modules. It is solely responsible and capable to dynamically bind actions with key sequences and (de)serialize shortcut preferences using `SUIT_ResourceMgr`. `SUIT_ShortcutContainer` encapsulates logics of conflict detecting and resolving. `SUIT_ShortcutTree` widget provides GUI to change shortcut preferences conveniently: it allows to remap plenty of shortcuts without applying, displays conflict-resolving dialog, highlights modifications until they are applied (saved into preference files).
   6
   7 To (de)serialize shortcut preferences without dependence on language environment, shortcuts must be stored as pairs {action ID, key sequence}, where action IDs must be application-unique.
   8
   9 Since desktop shortcuts may also be changed and interfere with shortcuts of modules, `SUIT_ShortcutTree` should always display desktop shortcuts and shortcuts of all modules altogether, even if some modules are inactive. It means, that `SUIT_ShortcutTree` must be fed not only with shortcut data {action ID, key sequence}[], but also with dictionaries {action ID, action name}[]. `SUIT_ShortcutTree` also requires other action assets - tool tip and icon path.
  10
  11 Assets of actions may be retrieved from instances of actions, but there is a pitfall: if a module has not been activated yet, its actions have not been initialized either.
  12 Qt Linguist is no help in this case too. To retrieve an action name using `QObject::tr(actionID)`, the `tr(const char*)` method must be called with instance of the class, which is designated as a context for the actionID in *.ts files. And contexts are usually descendants of SUIT_Application and CAM_Module. Again, until a module instance is created, there is no way for `SUIT_ShortcutMgr` to get even a name of a context-class, which an action with an ID belongs to, without any additional data. Straightforward mechanism for loading of action assets in advance has been devised: for all actions, which are bound by default or may be bound by user to hotkeys, assets must be placed into asset files. People who do/refine localizations should keep this in mind and also process JSON files, which are referred in resource files in sections `<section name="action_assets">`.
  13
  14 To alleviate process of composing resource and asset files, a development tool `DevTools` has been made. It grabs all shortcuts and assets (except icon path) of intercepted at runtime actions with valid IDs and dumps shortcuts into XML files with identical to project-conventional resource files structure and assets into properly-formatted JSON files. Run modules/features of interest, switch application language, and if IDs or names in the selected language of some actions of the module are not added yet to preference files, these dump files will be appended with new data – shortcuts and assets, if the last ones are provided in *.ts files.
  15 The tool also logs assets of intercepted actions with invalid IDs. The intent is as follows: run modules/features of interest at several languages in exactly the same sequence of actions, paste content of resulting language-dedicated *.csv files to corresponding sheet of  [“ShortcutMgr. Resource generator.xlsx”](../../tools/DevTools/ShortcutMgr/ShortcutMgr. Resource generator.xlsx). Then come up with proper IDs for the actions, type the action IDs and their module IDs into corresponding columns and take away ready resource and asset items.
  16
  17 Shortcuts and assets for all actions of SHAPER and GEOM and those actions of desktop, which were bound (hardcoded) to non-empty key sequences, have been added to resource files. Now they are available for hot key remapping via GUI, no conflicts guaranteed. Any hardcoded shortcut is disabled, unless the same shortcut persists in resource files.
  18
  19 ## Possible conflicts between shortcuts of desktop and modules, except SHAPER and GEOM
  20
  21 Most of remaining actions can not be made available for shortcut customization without further meticulous inspection of all other modules' code, devising and typing proper action IDs for all such occurrences.
  22
  23 Since desktop shortcuts are allowed for remapping, user can end up with conflicting shortcuts of desktop actions and those actions of unprocessed modules (all, except SHAPER and GEOM), which are hardcoded to non-empty key sequences.
  24
  25 Now actions with invalid IDs are disabled by `SUIT_ShortcutMgr` at runtime and not available for binding neither using UI, neither by editing of preference file. There are four approaches how to handle this:
  26
  27 1. Keep as is: user can remap shortcuts of desktop, SHAPER and GEOM - no conflicts guaranteed, hardcoded (now means all) shortcuts of other modules are disabled.
  28
  29 2. Go through unprocessed repositories and add valid ID in every occurrence of action creation. Or at least only for those invalid-ID actions, which are currently assigned non-empty key sequences. It should not be just dumb slapping of unique IDs: some actions comprise meta-action (see `SUIT_ShortcutMgr` class documentation) and must get the same ID, e.g. “Undo”, and some actions with similar names do absolutely unrelated things and must be given with different IDs.
  30
  31 3. Comment the line in `SUIT_ShortcutMgr` code, which disables shortcuts of inavlid-ID actions. At that rate, users will get back all the shortcuts of unprocessed modules they have accustomed to, but since these actions can not be taken into account during conflict detection,
  32 users may face with shortcut interference, if a desktop action is bound to the same key sequence as a hardcoded shortcut from unprocessed module.
  33
  34 4. Forbid user to edit shortcuts of desktop and shortcuts of unprocessed modules. When another module will be processed, allow to modify its shortcuts. When all modules will be processed, make desktop shortcuts available for customization.
  35
  36 ## Issue with ampersand-shortcuts
  37
  38 `QPushButton::QPushButton(const QString&)`, being fed with an action name with an ampersand preceding a char, automatically creates a shortcut, bound to *Alt+\<char>* key sequence.
  39
  40 E.g. `auto button = QPushButton(tr("&Help")` may create language-depdendent shortcuts. Suppose that \*_fr.ts file contains this:
  41 ```
  42 <message>
  43         <source>&amp;Help</source>
  44         <translation>A&amp;ide</translation>
  45 <message>
  46
  47 ```
  48
  49 Then help menu has different shortcuts if the application is run in EN or FR.
  50
  51 **A part of the issue** is that some ampersand-shortcuts interfere between each other. You can witness this in master-native application. Switch language to FR, run the app, click on the area, where viewers appear, and stroke *Alt+A*. You will get a Qt-generated notification *"Ambiguous shortcut detected"*, because *Alt+A* is bound to *"New ParaView window"* and to *"Affichage"* simultaneously. If you stroke the sequence again, *"Affichage"* menu expands, since the button tray, where the menu-button resides, has gained focus.
  52
  53 **Another part of the issue** is that ampersand-shortcuts are not always intercepted by `SUIT_ShortcutMgr::eventFilter(_)`. Normally, if the manager catches an unregistered `QAction`, it disables the action' shortcut. But, non-intercepted ampersand-shortcut remains enabled, and, if user binds some action to the same key sequence in the shortcut editor, the editor is not able to detect conflict and prevent interfering binding. Then user faces with the *"Ambiguous shortcut detected"* notification or button-menu is opened instead of executing the action, mapped to the key sequence in shortcut editor.
  54
  55 **The question is how to handle ampersand-shortcuts?**
  56 1. Resolve conflicts between ampersand-shortcuts for all localizations. Prohibit binding actions to *Alt+\<char>* key sequences in shortcut editor.
  57 2. After every occurrence of `QPushButton` creation type something like this:
  58 ```
  59 // Occurrence
  60 const auto helpButton = new QPushButton(tr("&Help");
  61 SUIT_ShortcutMgr::get()->registerButtonActions("/#AltHelp", *helpButton);
  62
  63 ----------------------------------------------------
  64 // SUIT_ShortcutMgr.cpp
  65 void SUIT_ShortcutMgr::registerButtonActions(const QString& theActionID, const QPushButton& theButton) const {
  66         for (QAction* const action : theButton.actions()) {
  67                 registerAction(theActionID, action);
  68         }
  69 }
  70 ----------------------------------------------------
  71 // Resource file
  72         <section name="shortcuts:">
  73                 <parameter name="#AltHelp" value="Alt+H"/>
  74         </section>
  75 ```
  76 Thus, ampersand-shortcuts will appear and be treated in shortcut editor as regular shortcuts.
  77 If the second option is preferable, should different ampersand-shortcuts for every target language be placed in resource files?
  78
  79 ## Minor issues
  80 1. `SUIT_ShortcutTree` widget does not take the whole available height of preference window, it only takes as mush as its items require.
  81 2. Selection of `SUIT_ShortcutTree`' item shadows "modified" highlighter. Can be fixed by replacing base `QTreeWidget` of `SUIT_ShortcutTree` with `QTreeView`, or may be by applying some style sheet.
  82 3. `SUIT_ShortcutMgr` introduces concept of module, but the first module class is `CAM_Module` is introduced along with `CAM_Application`, which is descendant of `SUIT_Application`.