GNOME.org
 

[sawfish] Docs on keys.

commit 2c804e9f86583c29393798b7b68476d15aa6489d
Author: Teika kazura <teika lavabit com>
Date:   Tue May 11 14:29:36 2010 +0900

    Docs on keys.

 KEYBINDINGS      |   53 ++++++++++++++++++++++++++++-------------------------
 man/sawfish.texi |   10 ++++++++--
 src/keys.c       |   28 ++++++++++++++++++++++------
 3 files changed, 58 insertions(+), 33 deletions(-)
---
diff --git a/KEYBINDINGS b/KEYBINDINGS
index e5becd1..3637188 100644
--- a/KEYBINDINGS
+++ b/KEYBINDINGS
@@ -1,25 +1,24 @@
 This is the complete list of default sawfish keybindings.
 You can use xmodmap (among other tools) to change your keyboard layout,
-and xev to check what key and button presses generate.
+and xev to check what key and button presses are generated.
+
+Keyboard features in Sawfish are explained in this file, too.
 
 Key Descriptions
 ================
 
-Toggle = Switch Status (Maximized -> Unmaximized ...)
-
+Modifiers:
 W = Default Modifier Key
 H = Hyper
 M = Meta
 C = Control
 S = Shift
 A = Alt
-Super = Super
+Super
 
-Mod(5...) = Additional Modifiers, eg: Alt Gr or Compose
+W, the "default modifier"
 
-ESC = Escape
-
-F(1...12) = F(1...12)
+Mod(5...) = Additional Modifiers, eg: Alt Gr or Compose
 
 dead_circumflex = ^
 degree = °
@@ -29,10 +28,10 @@ Right = Right Arrow Key
 Up = Up Arrow Key
 Down = Down Arrow Key
 
-! Currently sawfish does not differ between
-! Num_Lock beeing activated or not, so always
-! use the keysyms like it would be deactived
+! Currently sawfish ignores caps lock, num lock, and screen lock.
+! Even if they're on, Sawfish reports as if they're not.
 
+! The following table is not universal. It depends on each keyboard.
 When Num_Lock is off:
 
 KP_Insert = Keypad Insert (0)
@@ -80,6 +79,7 @@ Insert = Insert
 Print = Print
 Home = Pos1
 
+ESC = Escape
 Tab = Tabulator Key
 
 ISO_Left_Tab = Same as Shift + TAB
@@ -109,8 +109,10 @@ X86Search = Search  Key
 XF86Favorites = Favorites Key
 XF86Standby = Sleep Key
 
+! Button mapping depends. For example, left handed people may set
+! the right button as "button 1".
 Button1 = Left Mouse Button
-Button2 = Middle Mouse Button/Scroll Wheel (Button 1 and 3 together should emulate this)
+Button2 = Middle Mouse Button/Scroll Wheel (Often emulated by button presses 1 and 3 at once.)
 Button3 = Right Mouse Button
 Button4 = Scroll Wheel Up
 Button5 = Scroll Wheel Down
@@ -126,9 +128,9 @@ Move = When Button Is Clicked and Pointer Moved
 Setting Keybindings
 ===================
 
-how to set keybindings manually:
+To set keybinding from lisp:
 
-( bind-keys keymap "keybinding" 'action )
+( bind-keys keymap "key" 'action )
 
 for example:
 
@@ -145,10 +147,10 @@ for example:
 Keymap for specific application
 ===============================
 
-it's possible to have a keymap for a specific application only,
-for example, we use `nautilus-keymap' for Nautilus, all other keymaps
-are nil inside Nautilus then, so only what's inside of nautilus-keymap
-is actually existing, as long as Nautilus is focused:
+It's possible to have a keymap for a specific application only.  For
+example, you can use `nautilus-keymap' which is active when Nautilus
+is focused. All other key events are ignored, that is, events not in
+`nautilus-keymap' are not captured by Sawfish, but sent to Nautilus.
 
 ( define nautilus-keymap ( make-keymap ) )
 ( bind-keys nautilus-keymap
@@ -159,21 +161,21 @@ is actually existing, as long as Nautilus is focused:
 ( add-window-matcher '( ( WM_CLASS . "^Nautilus/nautilus$" ) )
        '( ( keymap . ,nautilus-keymap ) ) )
 
-So now Sawfish only nows 3 keybindings for Nautilus.
+So now Sawfish only has 3 keybindings for Nautilus.
 
 Keymap Transistion
 ==================
 
-Sawfish is able to `translate' keystrokes to different ones, for example
-say we want to create a new tab in Guake (a dropdown terminal emulator) by
-pressing C-n instead of C-S-t, when we do:
+Sawfish is also able to `translate' a keypress to different one. For
+example, assume you want to create a new tab in Guake (a dropdown
+terminal emulator) by pressing C-n instead of C-S-t (the Guake
+default). Then put:
 
 ( add-window-matcher '( ( WM_CLASS . "^Guake.py/guake.py$" ) )
        '( ( keymap-trans . ( ( "C-n" "C-S-t" ) ) ) ) )
 
-so we do now press C-n inside Guake, but Guake receives C-S-t instead, or in
-other words: no more unconfigurable keybindings. This may also be usefull in
-conjunction with an application specific keymap, to prevent colliding bindings.
+This is also useful in conjunction with an application specific
+keymap, to prevent colliding bindings.
 
 Nested Keybindings (Macros)
 ===========================
@@ -196,6 +198,7 @@ now first press "W-e" (as I said no need to keep it pressed) and press b, now bl
 
 Default Keymaps and Keybindings
 ===============================
+"Toggle" in the command name means switching between "on" and "off".
 
 Explanation of Keymaps (+ default bindings)
 
diff --git a/man/sawfish.texi b/man/sawfish.texi
index dd964bd..94da14b 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -5312,6 +5312,9 @@ A special modifier that matches key release events, not the default
 key press events.  Mouse events never have @key{Release} modifiers;
 they have separate actions instead.  @xref{Event Actions}.
 
+You have to set the variable @code{eval-key-release-events} to
+ code{non-nil} to use this modifier.
+
 @item Button var{k}
 The @var{k}'th mouse button is currently pressed.
 
@@ -5741,8 +5744,8 @@ Installs zero or more key bindings into the keymap @var{keymap}, then
 returns @var{keymap}.
 
 Each binding is defined by two elements in the list of @var{bindings},
-the first defines the name of the input event (or the event itself) and
-the second defines the command to be associated with the event.
+the first defines the name of an event (or the event itself) and the
+second defines the command to be associated with the event.
 
 For example to bind two keys in the keymap @var{keymap}; the event
 @kbd{C-f} to the command @code{foo} and the event @kbd{C-b} to the
@@ -5753,6 +5756,9 @@ command @code{bar} the following form would be used,
  "C-f" 'foo
  "C-b" 'bar)
 @end lisp
+
+Currently, multiple keystrokes can't be bound with a single
+ code{bind-keys} call. Instead, bind an event to another keymap.
 @end defun
 
 @defun unbind-keys @var{keymap} &rest @var{keys}
diff --git a/src/keys.c b/src/keys.c
index 981729b..f7a859d 100644
--- a/src/keys.c
+++ b/src/keys.c
@@ -79,7 +79,8 @@ static repv next_keymap_path;
 
 DEFSYM(multi_click_delay, "multi-click-delay");
 
-/* The X modifiers being used for Meta, Alt, Hyper, Super */
+/* The X modifiers being used for Meta, Alt, Hyper, Super.
+   Values are bits in key/button event -> state field. */
 static unsigned long meta_mod, alt_mod, hyper_mod, super_mod;
 
 /* The user-customizable modifier; used for default key bindings. This
@@ -103,12 +104,16 @@ static int all_buttons[9] = { Button1, Button2, Button3, Button4, Button5, Butto
 static int all_buttons[5] = { Button1, Button2, Button3, Button4, Button5 };
 #endif
 
-/* locks: currently LockMask, num_lock, and scroll_lock */
+/*
+  locks: currently LockMask, num_lock, and scroll_lock.
+  These are used in grabbing. All combinations of lock masks is stored.
+*/
 static int total_lock_combs, all_lock_mask;
 static int all_lock_combs[2*2*2];
 
-/* Translate from X events to Lisp events */
-
+/*
+  Translate modifiers back to raw X 'state' from names like "super".
+ */
 static unsigned long
 direct_modifiers (unsigned long mods)
 {
@@ -128,6 +133,7 @@ direct_modifiers (unsigned long mods)
     return mods;
 }
 
+/* Translate from X 'state' to names like "super". */
 static unsigned long
 indirect_modifiers (unsigned long mods)
 {
@@ -299,7 +305,9 @@ translate_event(unsigned long *code, unsigned long *mods, XEvent *xev)
 }
 
 /* Translate the Lisp key event EV to X keycode *KEYCODE and modifier
-   mask *STATE, returning true if successful. */
+   mask *STATE, returning true if successful.
+   Used by grab and sythesize-event.
+*/
 static bool
 translate_event_to_x_key (repv ev, unsigned int *keycode, unsigned int *state)
 {
@@ -338,7 +346,10 @@ translate_event_to_x_key (repv ev, unsigned int *keycode, unsigned int *state)
 }
 
 /* Translate the Lisp button event EV to X button identifier *BUTTON and
-   modifier mask *STATE, returning true if successful. */
+   modifier mask *STATE, returning true if successful.
+   It doesn't distinguish Click and Button-off, by its nature.
+   Used by synthesize-event and grab.
+*/
 static unsigned int
 translate_event_to_x_button (repv ev, unsigned int *button, unsigned int *state)
 {
@@ -392,6 +403,9 @@ translate_event_to_x_button (repv ev, unsigned int *button, unsigned int *state)
 
 /* Keymap searching */
 
+/* Used by search_keymap() and `event-match'.
+   Notice the asymmetry between 1 and 2.
+ */
 static inline bool
 compare_events (unsigned long code1, unsigned long mods1, unsigned long code2, unsigned long mods2)
 {
@@ -1804,6 +1818,8 @@ grab_keymap_event (repv km, long code, long mods, bool grab)
     }
 }
 
+/* Implements `grab-keymap' and `ungrab-keymap', i.e.,
+   grab all keys registered in keymap `map'. */
 static void
 grab_all_keylist_events (repv map, bool grab)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]