From 354d530231cb06fb8aa046b1a6442586aec8847f Mon Sep 17 00:00:00 2001
From: keis <keijser@gmail.com>
Date: Mon, 14 Mar 2011 20:53:31 +0100
Subject: keycmd comments and docs

---
 README                          | 12 ++++++------
 docs/README.uzbl-event-manager  | 27 ++++++++++++++++++++++++---
 examples/data/plugins/keycmd.py | 13 +++++--------
 3 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/README b/README
index c5d353b..08c6356 100644
--- a/README
+++ b/README
@@ -677,10 +677,14 @@ Events have this format:
   `uri`.
 * `EVENT [uzbl_instance_name] LINK_UNHOVER uri`: The mouse leaves the link
   `uri`.
-* `EVENT [uzbl_instance_name] KEY_PRESS key_name`: The key (or mouse button)
+* `EVENT [uzbl_instance_name] KEY_PRESS 'mod_state' key_name`: The key (or mouse button)
   `key_name` is pressed.
-* `EVENT [uzbl_instance_name] KEY_RELEASE key_name`: The key (or mouse button)
+* `EVENT [uzbl_instance_name] KEY_RELEASE 'mod_state' key_name`: The key (or mouse button)
   `key_name` is released.
+* `EVENT [uzbl_instance_name] MOD_PRESS 'mod_state' mod_name`: A key mapped to
+  `mod_name` is pressed.
+* `EVENT [uzbl_instance_name] MOD_RELEASE 'mod_state' mod_name`: A key mapped to
+  `mod_name` is released.
 * `EVENT [uzbl_instance_name] SELECTION_CHANGED selected_text`: When text is
   selected in the `uzbl` window.
 * `EVENT [uzbl_instance_name] NEW_WINDOW uri`: Request to creation of new `uzbl` window,
@@ -758,10 +762,6 @@ Events/requests which the EM and its plugins listens for
     when the `<from>` key or button is pressed.
 * `IGNORE_KEY`: Ignore a key pattern, specified by `<glob>`.
   - `request IGNORE_KEY <glob>`
-* `MODKEY_ADDITION`: Create a compound modkey from multiple individual keys.
-  - `request MODKEY_ADDITION <key1> <key2> <keyn> <result>`: The modkey
-    `<result>` is considered pressed when all of `<key1>`, `<key2>`, and
-    `<keyn>` are pressed.
 * `TOGGLE_MODES`
   - `request TOGGLE_MODES <mode1> <mode2> ... <moden>`
 * `APPEND_KEYCMD`: Append a string to the current keycmd.
diff --git a/docs/README.uzbl-event-manager b/docs/README.uzbl-event-manager
index 23e185c..da26847 100644
--- a/docs/README.uzbl-event-manager
+++ b/docs/README.uzbl-event-manager
@@ -26,15 +26,36 @@ MODE_CHANGE <mode>
 
 ### keycmd.py ###
 - Tracks the currently entered command
-- Connects To: FOCUS_GAINED, FOCUS_LOST, KEY_PRESS, KEY_RELEASE, (APPEND_KEYCMD,
+- Connects To: KEY_PRESS, KEY_RELEASE, MOD_PRESS, MOD_RELEASE, (APPEND_KEYCMD,
   IGNORE_KEY, INJECT_KEYCMD, KEYCMD_BACKSPACE, KEYCMD_DELETE,
-  KEYCMD_EXEC_CURRENT, KEYCMD_STRIP_WORD, MODKEY_ADDITION, MODMAP,
+  KEYCMD_EXEC_CURRENT, KEYCMD_STRIP_WORD, KEYCMD_CLEAR, MODMAP,
   SET_CURSOR_POS, SET_KEYCMD)
-- Emits: KEYCMD_UPDATE, KEYCMD_EXEC, MODCMD_UPDATE, MODCMD_EXEC
+- Emits: KEYCMD_UPDATE, KEYCMD_EXEC, MODCMD_UPDATE, MODCMD_EXEC, KEYCMD_CLEARED
+  MODCMD_CLEARED
 
 Maintains a command line that is manipulated by simple keypresses and a number
 of events.
 
+APPEND_KEYCMD <str>
+    Appends `str` to the end of the keycmd
+
+INJECT_KEYCMD <str>
+    Inserts `str` at the cursor position
+
+KEYCMD_BACKSPACE
+    Removes the character at the cursor position in the keycmd
+
+KEYCMD_DELETE
+    Removes the character after the cursor position in the keycmd
+
+KEYCMD_EXEC_CURRENT
+    Raise a KEYCMD_EXEC with the current keylet and then clear the keycmd
+
+KEYCMD_STRIP_WORD [<separator>]
+    Removes the last word from the keycmd, similar to readline ^W
+
+KEYCMD_CLEAR
+    Clears the keycmd and raises KEYCMD_CLEARED
 
 ### bind.py ###
 - Provides support for key bindings
diff --git a/examples/data/plugins/keycmd.py b/examples/data/plugins/keycmd.py
index 952fbac..99f92af 100644
--- a/examples/data/plugins/keycmd.py
+++ b/examples/data/plugins/keycmd.py
@@ -228,11 +228,10 @@ def key_press(uzbl, key):
     '''Handle KEY_PRESS events. Things done by this function include:
 
     1. Ignore all shift key presses (shift can be detected by capital chars)
-    3. In non-modcmd mode:
+    2. In non-modcmd mode:
          a. append char to keycmd
-    4. If not in modcmd mode and a modkey was pressed set modcmd mode.
-    5. If in modcmd mode the pressed key is added to the held keys list.
-    6. Keycmd is updated and events raised if anything is changed.'''
+    3. If not in modcmd mode and a modkey was pressed set modcmd mode.
+    4. Keycmd is updated and events raised if anything is changed.'''
 
     k = uzbl.keylet
     modstate, key = parse_key_event(uzbl, key)
@@ -270,10 +269,8 @@ def key_press(uzbl, key):
 def key_release(uzbl, key):
     '''Respond to KEY_RELEASE event. Things done by this function include:
 
-    1. Remove the key from the keylet held list.
-    2. If in a mod-command then raise a MODCMD_EXEC.
-    3. Check if any modkey is held, if so set modcmd mode.
-    4. Update the keycmd uzbl variable if anything changed.'''
+    1. If in a mod-command then raise a MODCMD_EXEC.
+    2. Update the keycmd uzbl variable if anything changed.'''
     k = uzbl.keylet
     modstate, key = parse_key_event(uzbl, key)
     modstate = set([m for m in modstate if not k.key_ignored(m)])
-- 
cgit v1.2.3