Go to the first, previous, next, last section, table of contents.

keys Extension Module

keys provides two classes for handling key events: KeyHandler and its subclass KeyGrabKeyboard.

Class: KeyHandler ( obj )

Represents a key handler, and should only be used as a base class, never instantiated directly. Instantiate a class derived from KeyHandler to install its key handler. When instantiating, obj should be a WindowManager, Screen, or Client object.

If obj is a WindowManager object the key bindings defined will be active on all screens. If obj is a Screen object the key bindings will only be active when that screen is the current one. If obj is a Client object the key bindings will only be active when that client is focused.

Instance Variable: KeyHandler propagate_keys

This attribute controls whether this key handler will allow other key handlers to recieve events. If it is true, which is the default, key events will be passed to all currently installed key handlers. If it is false key events will only reach this key handler and other installed handlers will never see them.

Instance Variable: KeyHandler timeout

If this is set to a number, the key handler method _timeout will be called if no key has been pressed for timeout number of seconds. This is None by defalt, meaning that there are no timeout for this keyhandler.

Method: KeyHandler _timeout ( event )

Called when the timeout is reached, if any. event is the TimerEvent causing the timeout. Key handlers using a timeout should override this method.

Method: KeyHandler _cleanup ( )

Uninstall the key handler. This will remove all grabs held by the keyhandler, and remove its event handlers from the event dispatcher. Typically this is called from an overridden _timeout.

Class: KeyGrabKeyboard ( obj, time )

This KeyHandler subclass should be used when the application whishes to grab all key events, not only those corresponding to methods.

The obj argument is the same as for KeyHandler. time is the X time of the event which caused this key handler to be installed, typically the time attribute of the event object. It can also be the constant X.CurrentTime.

This class also changes the defaults for propagate_keys to false and timeout to 10 seconds, and provides a _timeout method which uninstalles the key handler.

A key handler is created by subclassing KeyHandler or KeyGrabKeyboard. All methods defined in the new key handler class represents represents key bindings. When a key event occures that match one of the methods, that method will be called with the event object as the only argument.

The name of the method encodes the key event the method is bound to. The syntax looks like this:

name :== keysym | modifiers '_' keysym

keysym :== <any keysym in Xlib.XK, without the XK_ prefix>

modifiers :== modifiers '_' modifier | modifier

modifier :== 'S' | 'C' | 'M' | 'M1' | 'M2' | 'M3' | 'M4' | 'M5' |
             'Any' | 'None' | 'R'

In other words, the method name should be a list of modifiers followed by the name of a keysym, all separated by underscores. The keysyms are found in the Python Xlib module Xlib.XK.

The modifiers have the following intepretation: modifiers other keysyms which are not valid method names by themselves event
S Shift
C Control
M Meta or Alt (interpreted as Mod1)
M1 Mod1
... ...
M5 Mod5
Any Any modifier state, should not be combined with other
None No modifiers, useful for binding to the key 9, or
R Bind to the key release event instead of the key press

Go to the first, previous, next, last section, table of contents.