Content

• Preamble (original)
• A foreword to xhkeys-2.
• Terms explained (the way I understand it, which might be not 100% correct).
• ScanCode vs  KeySym
• Modifier and shift state
• Support

• From source tarball
• From RPM binary
• From RPM source

• Configuration
• Activation
• Command line arguments

• Parameters
• Modes

• General resources
• Plugin declaration
• Code lines
• Obsolete resources

• Supported operations
• Obsolete operations

• About plugins
• Default Plugins
• CD Audio control (xhkeys_cdaudio)
• Initialisation string
• Operations
• Audio Mixer (volume and balance) control (xhkeys_mixer).
• Initialisation string
• Operations
• Plugin interface
• How to build a plugin ?
• How the main application operates a plugin ?
• Plugin functions
• Initialisation
• Query operations
• Operation processing
• Property exchange
• Termination

Introduction

Preamble (original)

xhkeys is designed to suit any keyboard  that has some extra keys that otherwise make no use with X:   "Menu" key  on a  105 key keyboard,  extra keys on some keyboard models, or laptops.

The application allows to assign a particular action to any key or key combination (key and modifiers ).  An action can be of one of the following types:

• a  built-in operation (internal command)
• calling an external application
• sending a key event (simulating key press/release)
• sending a mouse button event (simulating button press/release)

xhkeys   - the main application which processes key presses and implements actions
xhkconf - configuration for xhkeys

A foreword to xhkeys-2.

• Plugins. Having CD Audio and mixer control as built-in functions looked very awkward to me. Now they are implemented as separate modules, and of course not the only plugins that can work with xhkeys. This manual contains the description of Plugin Interface, in case someone wishes to create a new plugin or modify the standard ones.
  

• On-screen display (OSD). Now the application can provide a feedback by showing some messages, like application name or alias (custom title), current CD Audio position, sound volume. Of course, you can select OSD position, text font, colour etc. I've even built a plugin framework that allows future use of graphics with OSD (e.g. volume bar), however current plugins don't use it, and to be honest, OSD graphics hasn't been tested at all. Starting with v 2.2 OSD is always on top, and you can specify background style and transparency with osdFrameWidth, osdBkgrMask  and other general resources discussed in Appendix A
  

• Continuous plugin call. No xhkeys_cdaudio plugin can work as a real CD player, so that it not only starts playback, but can regularly update OSD with current position. For that reason the application should call the plugin continuously. Hopefully this is not the only case when continuous plugin call might be useful.

• New xhkconf features. New features required changes in configuration utility xhkconf  which is not only  brought  up to date, but has become more logical.  Thus no longer it will  not annoy  you by asking arguments for a function like Quit, that doesn't take any arguments.

Terms explained (the way I understand it, which might be not 100% correct).

ScanCode vs  KeySym

Scan code is a unique code generated  by the keyboard for a particular key.  As opposed to that,  Key Symbol (KeySym for short) is assigned by the X-server⁽¹⁾ ,  depending on the selected layout. KeySyms have  mnemonics starting with XK_,  e.g.  XK_A for capital A,  XK_percent for  %  sign. All KeySyms are listed in  /usr/X11R6/include/X11/keysymdef.h .

While using KeySyms is preferred for portability, this application identifies a key by its scan code,  because:

• an extra key usually don't have an associated KeySym
• xhkeys is configured for a particular keyboard and doesn't need to be portable

----
⁽¹⁾  More exactly by KEYBOARD extension, unless disabled.
⁽²⁾  In reality all scan codes are below 128, what X reports as  a  key code over 128  is really an e0-sequence, e.g.  '0xc2' corresponds to  '0xe0 0x42'

Modifier and shift state

A modifier is a key  that can be pressed simultaneously with a function key to affect its interpretation. At least 6 modifiers are supported by X on PC:  Shift (1), Caps Lock (2),  Ctrl(4), Alt(8),  Win(0x40), ScrollLock(0x80).

Shift state is a bit mask  corresponding  to all pressed modifiers.  With  6 modifiers you have 64 possible shift states, therefore the  amount of possible key combinations (ExtraKey1,  Shift + ExtraKey1 ,  Ctrl+Shift+ExtraKey1, etc.) is 64 times more than a number of extra keys.

Support

The author can be contacted by email:  "Michael Glickman" <wmalms@yahoo.com>
 

Installation

From source tarball

To install for common use (binaries and documentation), log in as root and enter
        make install
        make install_doc

This will install the binaries in ${prefix}/bin and the manual in ${prefix}/share/doc/xhkeys-1.0.0

Useful configuration options (with ./configure):
 

Among most commonly used environment variables are:

From RPM binary

Log in as root and say

rpm -Uv xhkeys-2.0.0-1.i386.rpm

From RPM source

Using xhkeys

Configuration

 By default xhkeys looks for configuration file in the following  paths:

Global configuration:   /usr/lib/X11/app-defaults/XHkeys
User configuration:      ~/.XHkeys

User settings overwrite the global ones. The location of user configuration file can be changed with --file command line argument.

The package comes with a configuration utility xhkconf ,  that can help you to create and maintain the configuration file. Sorry, I still don't have time (and patience) to implement a nice GUI interface (you will do me a favor by building it), but I will always find time to help you in case you have problems.  xhkconf can configure key bindings,  but not other parameters like device names, time-outs, etc. What really frustrates me about 'xhkconf --edit ' is that it uses a standard Xrm (X Resource Manager) engine, ended up with XrmPutFileDatabase, which doesn't keep the comments, and completely reshuffles the lines, which makes a resource file hardly readable.

Activation

As an alternative, some Window Managers provide their own way for application autostart, like ~/GNUstep/Library/WindowMaker/autostart for Window Maker, or Autostart directory for kwm .

FYI:  xhkeys fails if X server is inactive, therefore you can't activate it before calling X.
 

Command line arguments

The  following command line arguments are accepted:

-c
--console
Always log to stdout (suppresses resource settings). Use it if you want to see the feedback but are denied  access to syslog.

-d
--debug
Debug mode: don't fork and,  by default (unless -s is specified) use stdout instead of syslog .

-f name
--file=name
Location of user configuration file, if different from default ~/.XHkeys

-h
--help
Print help and exit

-l level
--log=level
The level of logging
    n- don't  log  messages
    e - log only error messages (default)
    a - log all messages:  start, stop/termination and errors

-o
--noosd
Disable OSD (suppresses resource settings)

-O[display name]
--osd[=display name]
Enable OSD (even if disabled in resource settings). Optionally you can specify display name as Server:ScreenNo (same as DISPLAY environment variable). If display name is used with the short form, it must immediately follow -O, eg   -OotherServer:0, while with the long form =  is used before  display name:  --osd=otherServer:0

Enable using syslog (suppresses resource settings).

Using xhkconf

Parameters

-f  name
--file  name
Location of user configuration file, if different from default ~/.XHkeys.  Used with  --edit,  --delete, and  --list.

-c  value
--count  value
Number of iterations for --keys, --mouse, --delete and --list

-s  code[.shift]
--scan  code[.shift]
Scan code and optionally shift state separated from the scan code by a dot. The scan code can be specified as a decimal, or hexadecimal number. Shift state 0 is assumed if omitted. Used with  --list, --edit and --delete.

-g
--global
Lookup also global configuration file. Used with --list only.

-a
--all
List all assignments. Used with --list only.
 

N.B.  --count, --scan  and  --all are mutually exclusive.

For details refer to the description of a particular mode
 

Modes

One and only one of the following modes may appear in the command line

-k
--keys

This mode displays key information. After 'xhkconf -k' starts it waits for 10 seconds (the time-out can be changed using  keytimeout parameter  in configuration file).  After you type a key combination, you can see its scan code, shift state and KeySym, if applicable.

If you need to query several key combinations, use --count with a maximum  number of keys. With  0 (zero) as the counter, the number of key combinations is unlimited, so that quit by time-out is the only way to terminate the application.

Examples:
    xhkconf -k -c0               # short keywords
    xhkconf --keys --count=10    # long keywords
 

-m
--mouse

This mode displays information needed for mouse event configuration. Before calling ' xhkconf -m ', you have to start the applications, that will receive mouse events (target applications).

After start, the application waits 8 seconds for a button click  (the time-out can be changed using  clicktimeout resource  in configuration file). After you click a window (of the target application), you get

-l
--list

Display a command assigned to a particular key combination.

You can specify scan code and shift state with --scan argument, or use --all to show all scan codes.

If neither scan code, nor -all  is  specified, ' xhkeys -l' waits keytimeout seconds for a key combination, and displays the action associated.  To query several key combinations in same run, use --count with a maximum  number of keys (count 0 - unlimited)

Normally --list processes only user configuration file., however if --global argument is specified,  the key assignment will be displayed from the global configuration in case is not found in the user configuration.

Examples:
 

-e
--edit

Edit a command assigned to a particular key in user configuration (global configuration file cannot be accessed).

This is the default mode.

Accepted parameters:  --scan, --count, --file .  The interpretation is similar to --list  mode

Examples:
 

If key and/or mouse event are going to be assigned, you have to activate the application(-s), that will receive the events (target application).

xhkeys will look for a command, assigned to the key combination. If there is an assigned command, you will asked a permission to overwrite it.

To enter a,  you will be asked  to select command type:
 

Following prompts depend on the command type.

At last the new command is displayed, and if accepted, the key binding is added or replaced.

The changes are written to the user configuration file,  specified with  --file command line argument, or ~/.XHkeys by default.
 

-d
--delete

Delete user assignment for a  particular key. This will activate the global assignment if any.

Accepts same parameters as --edit.

-p
--plugins

View, edit and modify the list of plugins. All other command line arguments are ignored.

-p name
--plugin=name

Edit an information for a particular plugin specified by its name or alias.

All other command line arguments are ignored.

-h
--help

Print help page and quit. All other command line arguments are ignored.
 

Appendix A.  Configuration file format

The resources are listed below

General resources

Plugin declaration

Code lines

A code line has he following structure:

scanCode ;shiftState ;cmdType ;parameters

either scanCode or shiftState is a decimal (e.g. 176) or hexadecimal (e.g. 0xb0) number.

cmdType is one of the  following:

 

Ix	Built-in (internal) command. The following optional character specifies type of OSD message (title): *   use custom title #   suppress OSD message If neither is specified, OSD title is command name.
Ax	Application call. The optional character specifies type of OSD message in the same way as for a built-in command. By default command line itself is used as OSD title.
Pxx	Plugin call. Two optional characters specify Plugin selection: N - by name (default) L - by plugin number Plugin call style O - call once (default) C - call continuously Example: PC - plugin is specified by name (taken by default), and is called continuously
Kxx	Key event . Two following characters specify Target window selection:  C - Target window is identified by WM. class hints (application name, and class name),  T - Target window is identified by its title (caption)  I - Target window is given by the window id  O - Target window is given by its stacking order, or input focus Sent key selection:  Y - Sent key is specified by KeySym as symbolic value,  U - Sent key is specified by KeySym in numeric (decimal, or hex) form, S - Sent key is specified by scan code Example:  KCY  - target window is given by WM. class hints,  key to send is given as KeySym (symbolic)
Mx	Mouse button event.  The next character specifies target window selection ( C, T, I , or O) in the same way as for a key event

The parameters depend of command type:

For  a built-in command (I):

In case of custom OSD title:
    Title ;Command Arguments

otherwise
    CommandArguments

In case of custom OSD message:
    Title ;ShellCommandLine

otherwise
    ShellCommandLine

T argetWindow ;SentKey ;SentShiftState ; PressRelease ;Count

PressRelease and Count can be omitted with separating semicolons

TargetWindow  (a window receiving the event) format depends on target window selection:
C - AppName-ClassName (hyphen - separated)
T - Window Title
I - Window id (a decimal or hexadecimal number)
O - One of the following characters:
       F - window having the input focus,
       T - topmost window,
       B - bottom window,
       R - root window.

SentKey (key to be sent)  depends on sent key selection
Y - KeySym as a text string without XK_ prefix
U - KeySym as a decimal or hexadecimal number
S - Scan code as a decimal or hexadecimal number

SentShiftState (shift state to send) is a decimal or hexadecimal mask

PressRelease  is:
0 - don't send an event, just bring window to focus and top of the stack
1 - send KeyPress event only
2 - send Key Release event only
3 - send KeyPress and Key Release (default)

For a non-zero PressRelease,  target window gets input focus only temporary for sending events, and the window isn't brought upfront.

An interval  between KeyPress and KeyRelease is given as keylattency

Count:   how many times the event has to be sent,  default 1
A pause between events is specified as keypause

Example: The following code line assigns scan code 254 to Ctlr+Ins , which many editors  process as Copy command:

TargetWindow;SentX,SentY;SentButtonNumber,SentShiftState;PressRelease;Count

PressRelease and Count can be omitted with separating semicolons

TargetWindow  (a window receiving the event) format depends on target window selection:
C - AppName-ClassName (hyphen - separated)
T - Window Title
I - Window id (a decimal or hexadecimal number)
O - One of the following characters:
       F - window having the input focus,
       T - topmost window,
       B - bottom window,
       R - root window.

SentX and SentY are coordinates relative to target window

SentButtonNumber (a button number to sent) is an X button number (1- left button, middle, etc.)

SentShiftState (shift state to send) is a decimal or hexadecimal mask

PressRelease is
0 - don't send an event,  just bring window to focus and top of the stack
1 - send ButtonPress event only
2 - send Button Release event only
3 - send Button Press and Button Release (default)

For a non-zero PressRelease,  target window gets input focus only temporary for sending events, and the window isn't brought upfront.

An interval  between ButtonPress and ButtonRelease is given as clicklattency

Count: how many times the event has to be sent,  default 1
A pause between events is specified as clickpause

Example: The following code assigns scan code 119 to seinding mouse events to Window Maker Clip causing switch to next workspace:

Obsolete resources

The following resources have become obsolete since CD audio and mixer operations are now implemented  with plugins. For backward compatibility the following resource are used to generate initialisation string for default plugins in case they are not declared, but available.

See Plugin Declarations  and Default Plugins sections for details.

Appendix B.  Built in operations

Supported operations

Obsolete operations

Appendix C. Plugins

About plugins

Default Plugins

CD Audio control (xhkeys_cdaudio)

Initialisation string

Operations

Examples: 

PLAYPAUSE - a paused/stopped CD start playing, a playing CD pauses. No arguments

When PlayPause is called continuously, the first call performs actual CD operation and draws status, whereas following calls merely update OSD. Use KillPlugin to stop.

PAUSE - pause a playing CD.  No arguments, run once only

STOP - stop a playing CD.  No arguments, run once only

STATUS - show CD status and position. No arguments Works even with osd=no in init string. Can be called continuously. Press key combination again, or use KillPlugin to stop.

LOADEJECT - load a disk if no medium currently, eject otherwise.   No arguments, run once only

LOAD - attempt load a disk.   No arguments, run once only

EJECT - attempt to eject a disc.   No arguments, run once only

SLOT - change current slot on a multi-changer device. Run once only.
Argument - slot number,  with a sign if relative to current:

Audio Mixer (volume and balance) control (xhkeys_mixer).

Initialisation string

Operations

All mixer operations apart from STATUS can't  be called continuously.

VOLUME

Change volume. The argument is coded as volume;channel

Volume can be relative to current (+value, -value) or absolute (without a sign).
The maximum volume value is 100.

The optional channel parameter allows overwriting the default mixer channel selected during plugin initialisation (see Audio Mixer initialisation string), this value is effective only for the current operation.

BALANCE

Change balance. The argument is coded as balance;channel

Balance value can be from -50 up to +50.
You need to use prefix = with an absolute negative balance.

Examples:

Save current volume and set volume to zero. Calling Mute again restores saved volume.

Argument: channel,  or omitted

STATUS

Show volume and balance fore selected (or default) device. The information is shown even if osd is disabled for the plugin. SndStatus may be called continuously.o. Press key combination again, or use built in operation KillPlugin (see Appendix B) to stop.

Argument: channel,  or omitted

Plugin interface

How to build a plugin ?

How the main application operates a plugin ?

Plugin functions

Initialisation

1. Allocate the data buffer to hold arguments and variables. In fails, copy string "<plugin name> init memory allocation error" to message;
2. If no errors so far, process init string and fill buffer with arguments. In case of an error copy error message to message;
3. If no errors so far, initialise variables and generate error message in case of failure
4. If no errors,  assign *bufferReturn to the data buffer pointer, set message to an empty string and return True.  In case of an error, free data buffer if necessary, set *bufferReturn to NULL and return False,

Query operations

• operation code: a number from 0 to OPCOUNT-1
• operation name: a string of length no more than XHKEYS_PLUGIN_OPNAME_LENGTH (the constant is declared in xhkeys_plugin.h)
• operation flags, discussed below

Operation processing

Property exchange

Termination