Release version 0.2.0

Author: thkala

ChangeLog

@@ -1,3 +1,18 @@
+Tue Mar  7 02:32:15 EET 2006 - Theodoros V. Kalamatianos <[email protected]>
+	* Release 0.2.0
+	* Added the `grab'/`ungrab' attributes that allow keyboard grabbbing
+	* Added the `grabbed'/`ungrabbed' attributes to fine tune the key
+	  shortcut configuration
+	* Added the `exec'/`noexec' attributes to control the execution of
+	  external commands
+	* Added the `ignrel'/`rcvrel'/`allrel' attributes to allow for key
+	  combinations where the keys are pressed sequentially rather than
+	  simultaneously.
+	* Fixed the -v/--verbose help message line
+	* Updated documentation
+	* Some minor Makefile fixes
+	* Minor fixes and clean-ups here and there
+
 Tue Nov 22 23:53:12 EEST 2005 - Theodoros V. Kalamatianos <[email protected]>
 	* Release 0.1.2
 	* Improve automatic keyboard detection

FAQ

@@ -45,8 +45,9 @@ KeyBoard Daemon. Or...
 
 * Does it work ?
 
-I have performed some minimal testing and it seems to work fine. I will have to 
-receive quite a lot of feedback before I mark it as stable, though.
+It is now launched at boot time on my system and it seems to work without any
+problems. I will still have to receive quite a bit of feedback before I mark it
+as stable, though.
 
 
 * How does it work ?

Makefile

@@ -24,7 +24,7 @@ actkbd: actkbd.o mask.o config.o linux.o
 actkbd.o : actkbd.h
 mask.o : actkbd.h
 
-config.o : actkbd.h
+config.o : actkbd.h config.c
 	$(CC) $(CFLAGS)	-c -o config.o config.c -DCONFIG=\"$(sysconfdir)/actkbd.conf\"
 
 linux.o : actkbd.h

NEWS

@@ -1,2 +1,13 @@
-0.1.2:
-	* Improve automatic keyboard detection
+0.2.0:
+	* Added the `grab'/`ungrab' attributes that allow keyboard grabbbing
+	* Added the `grabbed'/`ungrabbed' attributes to fine tune the key
+	  shortcut configuration
+	* Added the `exec'/`noexec' attributes to control the execution of
+	  external commands
+	* Added the `ignrel'/`rcvrel'/`allrel' attributes to allow for key
+	  combinations where the keys are pressed sequentially rather than
+	  simultaneously.
+	* Fixed the -v/--verbose help message line
+	* Updated documentation
+	* Some minor Makefile fixes
+	* Minor fixes and clean-ups here and there

README

@@ -11,6 +11,7 @@ Contents:
 	3.1. Compilation
 	3.2. Installation
 	3.3. Configuration
+	3.3.1. Supported command attributes
 	3.4. Running
     4. Internals
     5. License
@@ -26,10 +27,10 @@ well-contained, so that support for additional platforms can be added with no or
 minimal changes to the rest of the code.
 
 It uses a plain-text configuration file which contains all the bindings. Its 
-file format has some prediction for command modules, which would allow the user 
-to perform some common actions (e.g. eject the CD-ROM or change the volume) 
-without having to call external commands. Currently, though, actkbd can only 
-execute external commands.
+file format has some prediction for command attributes, which allow the user to
+perform some common actions (e.g. eject the CD-ROM or change the volume) without
+having to call external commands. Currently, though, actkbd can only execute
+external commands, as the supported attributes only serve configuration purposes.
 
 
 
@@ -93,7 +94,7 @@ The default configuration file resides in $(sysconfdir)/actkbd.conf. It is a
 plain-text file with each line being an entry. A proper entry has the following 
 format:
 
-<keys>:<event type>:<command module>:<command>
+<keys>:<event type>:<attributes>:<command>
 
 The <keys> field is a series of numeric keycodes, separated by the `+' 
 character. `actkbd -n -s' can be used to find out any keycodes you need, as it 
@@ -102,18 +103,86 @@ will report all key presses without executing any commands.
 The <event type> string field is one of `key' (key press event), `rep' (key 
 repeat event) or `rel' (key release event). If empty, it defaults to `key'.
 
-The <command module> field is currently ignored.
+The <attributes> field contains a comma separated list of attributes. The listed
+attributes can modify the execution of the supplied command or change the state
+of actkbd in order to perform complex actions. The attribute actions are executed
+in the listed order.
 
-The <command> field is the executed command that will be passed to system(). 
+The <command> field is the executed command that will be passed to system().
 Note that in order to have non-blocking behaviour, you have to append the `&' 
 character to the command, so that /bin/sh will execute it in the background.
+Also keep in mind that the listed command attributes can affect the way the
+command is executed, if at all. Currently system() is the only interpretter
+for commands, but in the future there may be command attributes that use the
+contents of this field differently, e.g. to set a sound mixer.
 
 Lines starting with '#' are considered comments. Invalid lines are silently 
 ignored, unless a high enough verbosity level has been specified.
 
 A sample actkbd.conf is included in the actkbd distribution.
 
 
+3.3.1. Supported command attributes
+
+The supported attributes are:
+
+* `grab': This grabs the keyboard device to block other applications from
+	receiving the subsequent events. This allows the user to bind commands
+	to keys that are not normally usable because they produce symbols that
+	mess with regular keyboard operation (letters, numbers e.t.c.).
+
+* `ungrab': This releases a grabbed device, so that other programs may get the
+	key events. Please note that at least some versions of the X keyboard
+	driver (and possibly other programs) will interpret a key release event
+	as a full key press/release sequence even if the press event was never
+	received (why?). Therefore you may prefer to use the `ungrab' attribute
+	in release event bindings, rather than keypress ones, to ensure correct
+	operation.
+
+WARNING: Using the `grab' attribute without a well thought way to invoke the
+	`ungrab' command can easily leave your keyboard unusable for all other
+	applications with no way out. You may want to invoke something like the
+	following:
+
+	# sleep 120; killall -9 actkbd
+
+	in a different console, while testing you configuration, to be able to
+	reclaim your keyboard even if the configuration file is not correct.
+
+* `grabbed': This instructs actkbd to execute the specified command only if the
+	keyboard has been grabbed. This can be used to allow a key to act as an
+	extra Function key that adds extra functionality to the other keys.
+
+* `ungrabbed': This instructs actkbd to execute the specified command only if
+	the keyboard has not been grabbed.
+
+NOTE: If none of the `grabbed'/`ungrabbed' attributes has been used, the command
+	is always executed if the key mask matches. If both are specified then
+	the command is never executed - obviously the keyboard cannot be grabbed
+	and ungrabbed at the same time.
+
+* `noexec': Do not call system() to run an external command. Useful for entries
+	that only serve configuration purposes.
+
+* `exec': Use system() to run an external command here and now. Allows specific
+	ordering of the attribute actions with regard to the system() call.
+
+NOTE: If none of the `noexec'/`exec' attributes has been specified, or if the
+	attribute list is empty, an `exec' call is implied at the end of the
+	list. Always use `noexec' for entries with empty/invalid commands.
+
+* `ignrel': Ignore release events for the keys that are currently pressed. This
+	allows complex key combinations where the keys are pressed sequentially,
+	rather than simultaneously. When the key combination is completed, the
+	`allrel' and `rcvrel' attributes should be used to clear the key mask
+	and to resume the proper reception of release events.
+
+* `allrel': Clear the pressed key mask. It is the equivalent of releasing all
+	pressed keys, but is not affected by the `ignrel' attribute.
+
+* `rcvrel': Restore proper reception of key release events.
+
+
 3.4. Running
 
 Run `actkbd --help' to see the various command line options. actkbd is normally 

TODO

@@ -10,6 +10,8 @@
 
 * Implement the module subsystem. Modules to control sound mixers e.t.c. could
   be built.
+  UPDATE: The attribute infrastructure introduced in actkbd-0.2.0 is the core
+	of the module subsystem. Now we are just missing the modules...
 
 * Use select() to handle multiple keyboards, instead of just the first one,
   and get a USB keyboard to test it.
@@ -34,3 +36,5 @@
   huge fixed keymaps ?
 
 * Create manual pages: actkbd.1, actkbd.conf.5
+
+* Autotools ?

actkbd.c

@@ -26,6 +26,12 @@ int uselog = 0;
 /* Maximum number of keys */
 int maxkey = 0;
 
+/* Device grab state */
+int grabbed = 0;
+
+/* Ignore release events */
+int ignrel = 0;
+
 /* Keyboard device name */
 char *device = NULL;
 
@@ -48,7 +54,8 @@ static int usage() {
 	"        -n, --noexec            Do not execute any commands\n"
 	"        -p, --pidfile <file>    Use a file to store the PID\n"
 	"        -q, --quiet             Suppress all console messages\n"
-	"        -v, --verbose [level]   Specify the verbosity level (0-9)\n"
+	"        -v[level]\n"
+	"        --verbose=[level]       Specify the verbosity level (0-9)\n"
 	"        -V, --version           Show version information\n"
 	"        -x, --showexec          Report executed commands\n"
 	"        -s, --showkey           Report key presses\n"
@@ -70,7 +77,8 @@ void on_hup(int signum) {
 	lprintf("Discarding old configuration\n");
 
     close_config();
-    clear_key_mask();
+    free_key_mask();
+    free_ign_mask();
 
     if (verbose > 1)
 	lprintf("Reading new configuration\n");
@@ -79,6 +87,8 @@ void on_hup(int signum) {
 	exit(ret);
     if ((ret = init_key_mask()) != OK)
 	exit(ret);
+    if ((ret = init_ign_mask()) != OK)
+	exit(ret);
 
     if (verbose > 1)
 	lprintf("Reconfiguration complete\n");
@@ -91,7 +101,8 @@ void on_hup(int signum) {
 void on_term(int signum) {
     close_config();
     close_dev();
-    clear_key_mask();
+    free_key_mask();
+    free_ign_mask();
 
     if (detach)
 	lprintf("actkbd %s terminating for %s\n", VERSION, device);
@@ -128,9 +139,20 @@ static int write_pid() {
 }
 
 
+/* External command execution */
+static int ext_exec(char *cmd, int noexec, int showexec) {
+    if ((verbose > 0) || showexec)
+	lprintf("Executing: %s\n", cmd);
+    if (!noexec)
+	return system(cmd);
+
+    return 0;
+}
+
+
 int main(int argc, char **argv) {
     int ret, key, type;
-    char *command;
+    key_cmd *cmd;
 
     /* Options */
     int help = 0, noexec = 0, version = 0, showexec = 0, showkey = 0;
@@ -253,6 +275,9 @@ int main(int argc, char **argv) {
     if ((ret = init_key_mask()) != OK)
 	return ret;
 
+    if ((ret = init_ign_mask()) != OK)
+	return ret;
+
     if ((ret = open_dev()) != OK)
 	return ret;
 
@@ -281,6 +306,8 @@ int main(int argc, char **argv) {
     signal(SIGTERM, on_term);
 
     while (get_key(&key, &type) == OK) {
+	int exec_ok = 0;
+
 	if ((type == KEY) || (type == REP))
 	    set_key_bit(key, 1);
 
@@ -295,15 +322,59 @@ int main(int argc, char **argv) {
 	    lprintf("\n");
 	}
 
-	ret = get_command(get_key_mask(), type, &command);
+	ret = match_key(type, &cmd);
 	if (ret == OK) {
-	    if ((verbose > 0) || showexec)
-		lprintf("Executing: %s\n", command);
-	    if (!noexec)
-		system(command);
+	    attr_t *attr;
+
+	    /* Attribute implementation */
+	    attr = cmd->attrs;
+	    while (attr != NULL) {
+		char *str, *opt = "";
+		switch (attr->type) {
+		    case ATTR_EXEC:
+			str = "exec";
+			ext_exec(cmd->command, noexec, showexec);
+			exec_ok = 1;
+			break;
+		    case ATTR_GRAB:
+			str = "grab";
+			grab_dev();
+			break;
+		    case ATTR_UNGRAB:
+			str = "ungrab";
+			ungrab_dev();
+			break;
+		    case ATTR_IGNREL:
+			str = "ignrel";
+			copy_key_to_ign_mask();
+			ignrel = 1;
+			break;
+		    case ATTR_RCVREL:
+			str = "rcvrel";
+			ignrel = 0;
+			break;
+		    case ATTR_ALLREL:
+			str = "allrel";
+			clear_key_mask();
+			break;
+		    default:
+			str = "unknown";
+			break;
+		}
+		if ((verbose > 0) || showexec)
+		    lprintf("Attribute: %s(%s)\n", str, opt);
+
+		attr = attr->next;
+	    }
+
+	    /* Fall back on command execution */
+	    if ((!exec_ok) && ((cmd->attr_bits & BIT_ATTR_NOEXEC) == 0)) {
+		ext_exec(cmd->command, noexec, showexec);
+		exec_ok = 1;
+	    }
 	}
 
-	if (type == REL)
+	if ((type == REL) && ((!ignrel) || (get_ign_bit(key) == 0)))
 	    set_key_bit(key, 0);
     }
 

actkbd.conf

@@ -10,14 +10,45 @@
 # Mute = 113
 # Volume Down = 114
 # Volume Up = 115
+# Eject = 161
 
-113:key::echo mute
 
-56+113:::echo left.alt+mute
 
+# Some simple examples
 114:::echo volume down
 114:rep::echo volume down rep
+56+114:::echo left.alt+volume.down
 
 115:::echo volume up
 115:rep::echo volume up rep
 115:rel::echo volume up rel
+
+
+
+# Use the mute key as a "Function" key.
+113:key:ungrabbed,grab:echo Grab!
+113:rel:grabbed,ungrab:echo Ungrab!
+
+# This allows the a key to be binded to a command
+# To use: press mute, press a, release in any order
+113+30::grabbed:echo Alpha!
+
+# Same thing with the b key
+113+48::grabbed:echo Beta!
+
+
+
+# When the Eject key is pressed, wait for one of the e/m/u keys
+161::grab,noexec,ignrel:
+
+# Oh! the `e' key
+161+18::grabbed:echo eject
+161+18:rel:grabbed,noexec,ungrab,rcvrel,allrel:
+
+# Oh! the `m' key
+161+50::grabbed:echo mount
+161+50:rel:grabbed,noexec,ungrab,rcvrel,allrel:
+
+# Oh! the `u' key
+161+22::grabbed:echo umount
+161+22:rel:grabbed,noexec,ungrab,rcvrel,allrel: