[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    KDE/kdelibs/kdeui/shortcuts
From:       David Faure <faure () kde ! org>
Date:       2008-02-05 11:41:56
Message-ID: 1202211716.499895.15599.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 771160 by dfaure:

Paste some explanations from an old mail of Andreas, which introduces the concepts better.
Explained what KGlobalAccel::updateGlobalShortcutsAllowed is for.


 M  +36 -9     README  


--- trunk/KDE/kdelibs/kdeui/shortcuts/README #771159:771160
@@ -1,14 +1,37 @@
 # Overall summary of global shortcut implementation
 
-Disclaimer: I gathered this knowledge while fixing a few bugs in KDE 4.0.0
-code. I am not the original author.
-
 ## KAction, KGlobalAccel and KdedGlobalAccel
 
+[Basic functionality]
+- You call KAction::setGlobalShortcut() to set a shortcut for an action. 
+KAction then calls KGlobalAccel which is, among other things, the interface 
+to KdedGlobalAccel (communication via DBus). KdedGlobalAccel is a KDED module 
+as you might have guessed.
+- KdedGlobalAccel then grabs the shortcut key in a platform-specific way and 
+makes an entry of the mapping key<->action where actions are identified by 
+their main component name and their own name.
+- When a key grab triggers, KdedGlobalAccel calls (via DBus) KGlobalAccel 
+which tells the action to trigger.
+
+The KdedGlobalAccel is responsible for actually handling the shortcuts,
+loading and saving the shortcut keys to kglobalshortcutrc. It doesn't
+really know the actions, it just know what KGlobalAccel gave it.
+
+[Conflict resolution]
+KdedGlobalAccel has a list of all global shortcuts. If you try to assign a key 
+twice, it will tell the appropriate KdedGlobalAccel/KGlobalAccel that the 
+corresponding shortcut was changed to an empty one, which goes back to the 
+KAction.
+When manually assigning shortcuts, the config widget asks 
+KGlobalAccel/KdedGlobalAccel for conflicts and presents options to the user 
+to fix them.
+To prevent all clashes as good as possible, KdedGlobalAccel remembers key<-> 
+action mappings even after the corresponding application shuts down.
+
+[More details]
 KAction instances talk to the KGlobalAccel singleton to make it aware of global
-shortcuts changes via KGlobalAccel::updateGlobalShortcuts() and
-KGlobalAccel::updateGlobalShortcutsAllowed() (I am still not sure why there are
-two methods).
+shortcuts changes via KGlobalAccel::updateGlobalShortcuts() (to define the shortcut)
+KGlobalAccel::updateGlobalShortcutsAllowed() (to enable/disable the shortcut)
 
 These two methods do the following:
 - Create an action "id" which is a QStringList of two items: the application
@@ -19,9 +42,11 @@
 - Pass all this via DBus to the KdedGlobalAccel instance, which lives in the
 kded4 process.
 
-The KdedGlobalAccel is responsible for actually handling the shortcuts,
-loading and saving the shortcut keys to kglobalshortcutrc. It doesn't
-really know the actions, it just know what KGlobalAccel gave it.
+KGlobalAccel::updateGlobalShortcutsAllowed(true) sets the "SetPresent" flag when calling
+kdedglobalaccel, which makes kdedglobalaccel actually grab the key shortcut
+(so that the grab is done after the action has been defined, and only if it is enabled).
+kdedglobalaccel must know about inactive global shortcuts too (e.g. those defined in
+appliations not running at the moment), for conflict resolution.
 
 ## kdebase side: keyboard shortcuts KCM
 
@@ -35,3 +60,5 @@
 
 Aurélien Gâteau, 2008.02.01
 aurelien.gateau@free.fr
+David Faure, 2008.02.05
+faure@kde.org
[prev in list] [next in list] [prev in thread] [next in thread]