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:
xhkeys - the main application which processes key presses and implements actions
xhkconf - configuration for xhkeys
WARNING. If you care about readability of your resource database file ~/.XHkeys is is strongly recommended to add the declaration of standard plugins manually before running xhkeys 2.0.0. See Plugin Declarations for the details. |
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(1) , 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:
----
(1) More
exactly
by KEYBOARD extension, unless disabled.
(2) 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'
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.
The author can be contacted by email: "Michael
Glickman" <wmalms@yahoo.com>
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):
--prefix=path | installation prefix, default /usr/local |
--disable-plugins | disable support of plugins in
xhkeys code |
--disable-cdaudio | even if plugins are enabled, exclude compilation and
installation of CD audio plugin xhkeys_cdaudio |
--disable-mixer | even if plugins are enabled, exclude compilation and
installation of audio mixer plugin xhkeys_mixer |
--disable-osd | disable support of on-screen display (OSD) in xhkeys code |
--disable-shape | disable using SHAPE extension
with OSD, so that the background can be always 100% opaque |
--disable-syslog | exclude syslog support: all messages addressed to syslog will be printed on stout instead |
Among most commonly used environment variables are:
CC | name of C compiler |
CFLAGS | compilation flags |
Log in as root and say
rpm -Uv xhkeys-2.0.0-1.i386.rpm
rpm --rebuild --clean xhkeys-2.0.0-1.src.rpmThis creates the binary xhkeys-2.0.0-1.i386.rpm usually in /usr/src/redhat/SRPMS. Cchange to this directory and follow the instructions for installation from RPM binary .
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.
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.
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).
-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
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
target window idIf you need to perform several queries, use --count with a maximum number of button clicks , or 0 for unlimited number of clicks.
class hints (application and class names) if applicable
title if applicable,
mouse button number and shift state,
coordinates (x,y) relative to the target window
-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:
xhkconf -ls 176.1 -f ~/.XHkeys.1 | # Display binding for scan code 176,
shift state 1 # Configuration file is explicitly specified |
xhkconf --list --scan=176.1 --file=~/.XHkeys.1 | # Same with long keywords |
xhkconf --list --scan=0xb0 | # Scan code is specified in hexadecimal
format, # shift state is not specified, 0 is assumed |
xhkconf -la | # List all assignments from user configuration |
xhkconf -lag | # List all effective assignments (from user, # or global configuration) |
-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:
xhkconf -es 0xb0.1 | # Add/edit binding for scan code 176, shift state 1 |
xhkconf --scan=176.1 | # Same result with using a long keyword, and decimal scan
mode # edit mode is assumed by default |
xhkconf -c0 | # Count=0 - edit repeatedly until quit on time-out |
xhkconf | # No arguments: edit a single (prompted) key combination. |
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:
Internal Function | See Appendix B |
Application | any external application with command arguments if
needed, (e.g. mozilla -edit to start mozilla composer) |
Key Event | KeyPress and/or KeyRelease events are sent to a designated window |
Mouse Event | Button Press and/or ButtonRelease events are sent to a designated window |
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.
The resources are listed below
maxcodes | Minimum number of codes: a code line number must not exceed this value (see Code Lines). | ||||
maxplugins |
Maximum number of plugins: a
plugin line number must not exceed this value (see Plugin Declaration) |
||||
logmode | xhkeys log mode, if not specified in the command line: none, errors (default) or all | ||||
logconsole |
true:
log to stdout, don't use syslog false (default): use syslog for messages (errors are also sent to stdout) Resource is ignored, if logging target is specified in command line |
||||
osd | true
(default): osd is enabled false: osd is disabled Resource is ignored, if osd mode is specified in the command line |
||||
osdFont |
Name of font to be used for OSD
text. By default the application will look for the following fonts (in
given order): 9x15bold,
variable, fixed |
||||
osdColour
or osdColor |
Colour to be used for OSD text.
While screen colour is taken by default. |
||||
osdBkgrColour
or osdBkgrColor |
Colour to be used for OSD
background, Black screen colour is taken for default |
||||
osdBkgrMask |
In case osdFrameWidth
is zero, this resource defines OSD background transparency as a 4 or
8-digit hexadecimal number (prefixed with 0x).
Specified mask value results in a (monochrome) bimap of size 8x4
or 8x2 resp., where ones stand for mapped pixels, while zeroes refer to
transparent pixels.
For example
osdBkgrMask 0xAA55 produces a 8x2
bitmap, where first line is 0x55 (binary 01010101), and
second line is 0xAA (binary 10101010), or in rasterized view:
* * * *
which corresponds to 50% X - hatch* * * * As another example, osdBkgrMask 0x3366CC99 produces a 8x4 bitmap with lines 0x99, 0xCC, 0x66, 0x33 or in rasterized view: * ** *
which is a 50% diagonal hatch** ** ** ** ** ** Other bkgrMask examples: 0xFFFF
- solid (100% opaque) background
0 - transparent background (only text is seen) 0x5555 - 50% vertical hatch 0xFF55 - 75% opacity 0x0055 - 25% opacity Default value 0x3366CC99. If SHAPE extension is unavailable, osdBkgrMask is ignored so that the background is solid. |
||||
osdFrameWidth | A number
from 0 up to 4, that specifies frame thickness. For a non-zero osdFrameWidth
the background is assumed to be solid, and osdBkgrMask
value is ignored. By default osdFrameWidth
is assumed to be 0. |
||||
osdFrameColour
or osdFrameColor |
Colour of OSD frame (in case osdFrameWidth
is non-zero). By default osdColour
is taken to be
osdFrameColour. |
||||
osdGeometry |
Location of osd window as widthxheight+x+y.
Positive x specifies the
distance of left OSD border from left of the screen, while negative x specifies the distance of right
OSD border from right of the screen. Similarly positive/negative y values specify distance of
top/bottom OSD border from top/bottom of the screen. If a
parameter is omitted, the default value is used. Default: width 300, height 20, x=(ScreenWidth-OSDWidth)/2, y =4 Examples:
|
||||
osdHAlignment |
Horizontal alignment of text in
OSD window: left, right or centre (default) |
||||
osdTextTop | Position of top text line in OSD
window. if omitted, OSD text is vertically aligned to the middle
of OSD window. |
||||
osdTimeout |
OSD message is cleared after
specified number of milliseconds. If osdTimeout is 0, the message is
not cleared until next message appears, otherwise it must be number
from 300 up to 5000. Default: 1000. |
||||
pluginTimeout
|
A period in milliseconds between consecutive plugin calls
(see Running Plugin Continuously). In order OSD to be seen
continuously,
pluginTimeout value should not exceed osdTimeout |
||||
keylattency | A period in microseconds between generated KeyPress and KeyRelease (see Key Event below), default 0 | ||||
keypause | A period in microseconds between consecutively generated key event sequences, default 50000 | ||||
clicklattency | A period in microseconds between generated ButtonPress and ButtonRelease (see Mouse Button Event below), default 0 | ||||
clickpause | A period in microseconds between consecutively generated mouse button event sequences, default 50000 | ||||
keytimeout | A period in seconds for xhkconf to wait for a key
combination
(see Using xhkconf ), default 10 |
||||
clicktimeout | A period in seconds for xhkconf to wait for a mouse button click (see Using xhkconf ), default 15 |
A code line has he following structure:
scanCode;shiftState;cmdType;parameterswhere:
either scanCode or shiftState is a decimal (e.g. 176) or hexadecimal (e.g. 0xb0) number.
cmdType is one of the following:
Hint: target identification by WM class hints appears to be the safest one, because window title often includes variables (file name, tip of the day, etc.). A problem with WM class hints is that an application might have several active windows with same WM class hints, where specification by title may become useful. Use window id only for permanent windows (e.g. weaker clip), because window id is allocated dynamically and can't be therefore a reliable identifier.
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:For an external application (A):
Title;Command Arguments
otherwise
CommandArguments
In case of custom OSD message:For a plugin call (P):
Title;ShellCommandLine
otherwise
ShellCommandLine
TargetWindow;SentKey;SentShiftState;PressRelease;Count
PressRelease and Count can be omitted with separating semicolonsTargetWindow (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 semicolonsTargetWindow (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:
xhkeys.codeline4: 119;0;MI;0x6000e7;57;6;1;0;3 # Next workspaceThe 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.
cddevice | save as devname with xhkeys_cdaudio (see CDAudio control
(xhkeys_cdaudio), but no delimiters or brackets accepted. |
cdhold | yes or no - same as devgrab with xhkeys_cdaudio |
mixerdevice | same as devname with xhkeys_mixer (see Mixer control (xhkeys_mixer), but no
delimiters or bracket accepted. |
mixerhold | yes or no - same as devgrab with xhkeys_mixer |
mixerchannel | same as channel with xhkeys_mixer |
Quit - terminate xhkeys (no arguments)
WNDCLOSE F or no arguments |
Close a window having an input
focus. |
WNDCLOSE S | Close selected window. After command is entered, three beeps are sound and an OSD message Click a window to close appears. You need to click the window to be closed within 10 seconds (unless otherwise specified as clicktimeout resource - see General Resources). |
ROTATE + | Circulate windows by raising the lowest window |
WNDROTATE - | Circulate windows by lowering the highest window |
Obsolete operation |
Plugin |
Plugin operation |
CDPLAY |
xhkeys_cdaudio |
PLAY |
CDPLAYPAUSE | same |
PLAYPAUSE |
CDPAUSE | same |
PAUSE |
CDSTOP | same | STOP |
CDLOADEJECT | same | LOADEJECT |
CDLOAD | same | LOAD |
CDEJECT | same | EJECT |
CDSLOT | same | SLOT |
SNDVOLUME | xhkeys_mixer |
VOLUME |
SNDBALANCE | same |
BALANCE |
devname | CD device name to use for built
in CD functions, default /dev/cdrom In (a rather imaginary) case of device name containing special characters, or just for readability, you can use custom delimiters or brackets, e,g, devname='dev/hdc', devname=[/dev/hdc], etc. |
devgrab |
yes
or no If yes, the CD device is opened with the first internal command accessing CD, and closes before xhkeys quits. If no, the CD device is opened and closed for each individual operations. For a better readability you can code just devgrab (same as devgrab=yes), or nodevgrab (i.e. devgrab=no) If devgrab is omitted, devgrab=no is assumed. Set devgrab=yes, if you use cdrom auto eject (e.g. dev.cdrom.autoeject=1 in /etc/sysctl.conf). |
osd |
yes
or no Enable/disable on-screen display(OSD). osd value does not affect operations like Status, or continuously called Play and PlayPause, merely because calling those without OSD wouldn't make sense. However noosd will suppress OSD for called once Play, PlayPause and other operations. Note that disabling osd for xhkeys will suppress any plugin osd. |
Examples:
Play | Start from current position |
Play * | Same |
Play D | Play from disc start |
Play -1T | Play previous track |
Play +4T | Go 4 tracks forward |
Play 4T | Play track 4 |
Play +0T | Restart current track |
Play +1M3S2F | Go 1 minute 3 sec and 1 frame forward (frame = 1/75 sec) |
Play -10S | Go 10 seconds back |
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:
Slot +1 | Select to next slot |
Slot -1 | Select previous slot |
Slot 0 | Select starting slot (slot number 0) |
devname | Mixer device name to use for
built
in CD functions, default /dev/mixer As for CD devname, you can use custom delimiters or brackets, e,g, devname='dev/mixer2', devname=[/dev/mixer2], etc. |
||||||||||||||||||||
devgrab |
yes
or no If yes, the device is opened with the first internal command accessing mixer, and closes before xhkeys quits. If no, the mixer device is opened and closed for each individual operations. For a better readability you can code just devgrab (same as devgrab=yes), or nodevgrab (i.e. devgrab=no) devgrab=yes seems to be rather safe and probably more efficient choice, however devgrab=no is assumed if parameter is omitted |
||||||||||||||||||||
channel |
default mixer channel used for
volume/balance control. The most commonly used mixer devices are:
The full list of mixer devices is given in /usr/include/linux/soundcard.h If channel is omitted, or set to (-1), the plugin takes the first available of the following devices: Master Volume, PCM-1, PCM-2. |
||||||||||||||||||||
osd |
yes
or no Enable/disable on-screen display(OSD). osd value does not affect operations like Status, or continuously called Play and PlayPause, merely because calling those without OSD wouldn't make sense. However noosd will suppress OSD for called once Play, PlayPause and other operations. Note that disabling osd for xhkeys will suppress any plugin osd. |
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.
Volume +2 | Increase volume by 2 on default device |
Volume 0 | Mute |
Volume -1 | Reduce volume by 1 on default device |
Volume +1;8 | Increase CD volume (device 8) by 1 |
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:
Balance +2 | Increase balance by 2 on default device |
Balance -1;6 | Reduce balance by 1 for Line (device 6) |
Balance =-10 | Set balance to -10 on default device (= is required to avoid confusion) |
Balance =30;8 | Set balance to 30 for CD (device 8) (= is not necessary, but used fore readability) |
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
Name |
Type |
Description |
init |
Optional |
Called
once after opening the plugin. The function processes init
string, and (if necessary) allocates and initialises data buffer. If
the function is missing, init string is discarded and no data buffer is
assumed. |
getopcount |
Required |
Returns number of operations
supported by the plugin. |
getopdata |
Required |
Returns properties of requested
operation. |
process |
Required |
Process operation. |
property |
Optional |
Get or set
a global plugin property (e.g. get plugin version and description, pass
xhkeys settings to the plugin). Currently this function is not really
crucial, but it is a good idea to have it. |
term |
Optional |
A
deinitialisation routine (e.g. close files, free arrays) called before
closing the plugin. As opposed to standard plugin destructor, term
provides you an access to data buffer. |
bufferReturn | a pointer to allocated buffer or NULL (passed by reference) |
initString | initialisation string |
message | a pointer to error message |
msgLen | maximum length of error message (to be used with strncpy, or snprintf) |
opCode |
code of requested operation |
opName |
If not NULL, a string of size is at least XHKEYS_PLUGIN_OPNAME_LENGTHto be filled with a zero-terminated operation name. |
opFlags |
If not NULL, a pointer int
variable to get operation flags |
XHKEYS_PLUGOPTYPE_PARMNONE | operation doesn't take arguments (default) |
XHKEYS_PLUGOPTYPE_PARMOPTIONAL | operation takes an optional argument |
XHKEYS_PLUGOPTYPE_PARMREQUIRED | operation requires an argument |
XHKEYS_PLUGOPTYPE_PARMSPECCHARS | Operation argument may contain Space, Tab or #. Normally these characters are used for starting comments in the code line for plugin call (see Code Lines), so that xhkeys main application removes comments and delimiters before passing an argument to the plugin. If XHKEYS_PLUGOPTYPE_PARMSPECCHARS is specified for the operation, the tail of the code line is passed to the plugin "as is" without pre-processing. |
XHKEYS_PLUGOPTYPE_CANCONTINUE | The operation may be called
continuously (see About Plugins) |
XHKEYS_PLUGOPTYPE_PERSISTENT | A continuously running operation
does not stop but restarted, when a key combination is re-entered. In
this case KillPlugin
(see Built-in Operations) is the
only way to stop the plugin. See Operation Processing for more
information about continuous run. XHKEYS_PLUGOPTYPE_PERSISTENT assumes XHKEYS_PLUGOPTYPE_CANCONTINUE, so that there is no need for OR-ing: just XHKEYS_PLUGOPTYPE_PERSISTENT will do. |
buffer |
Pointer to data buffer created
by init,
or NULL |
opcode |
Operation code (see Query Operations) |
argument |
Operation argument |
behaviour |
One of behaviour constants discussed below |
message |
This string gets error message
on error, or OSD text message on success |
msgLen |
Length of message
string |
True |
Processed successfully, message
contains OSD text. Set message to zero-length string if no OSD is needed. |
False |
Processed with errors, message contains error description |
XHK_BEHAVIOUR_ONCE |
The operation is called for
a single run |
XHK_BEHAVIOUR_CONTINUOUS |
First call in continuous run |
XHK_BEHAVIOUR_REPEATED |
Repeated call in continuous run |
XHK_BEHAVIOUR_DISCONTINUE |
Last call in continuous run, the
operation is about to stop. |
buffer |
Pointer to data buffer created by init, or NULL |
code |
One of XHKEYS_PLUGIN_PROPERTY
constants listed below (declared in xhkeys_plugin.h).
|
The remaining arguments depend on the property (as specified below). |