NAME
bbkeysrc - bbkeys configuration file
SYNOPSIS
$HOME/.bbkeysrc
DESCRIPTION
bbkeys picks up its configuration settings from $HOME/.bbkeysrc unless
overridden on the command line. There are several avenues open to the
user to set any key-grabs that the user wishes:
Using bbconf:
This is a Qt-based application available at
http://bbconf.sourceforge.net/.
Manually editing $HOME/.bbkeysrc:
The format is very easy, and it follows the same format as blackbox’s
menu files. It must begin with a "[begin]" tag. It may contain a
"[config]" tag, containing a configuration section, ending with a
"[end]" tag. In fact, all opening section tags must end with an
"[end]" tag. It should also contain a "[keybindings]" section.
For more information, see the man page for blackbox’s menu.
LIST OF CONFIG OPTIONS
stylefile:
filename of blackbox style to use (string)
honorModifiers:
whether or not to break if NumLock or ScrollLock is pressed.
(hint: for bbkeys to ignore your keybindings if NumLock or
ScrollLock are pressed, set this to true) (true or false)
raiseWhileCycling:
should bbkeys raise the windows you’re cycling through while
cycling through them? (true or false)
showCycleMenu
show the window-cycling menu or cycle without it? (true or
false)
cycleMenuTitle
show the given string as the title of the window-cycling menu.
if an empty string is passed as the parameter to this config
option("{}"), then the title will not be drawn. (string value)
menuTextJustify
how should the window-cycling menu be justified? (left, center,
right)
menuTitleJustify
how should the window-cycling title be justified? (left, center,
right)
autoConfig
should bbkeys watch for changes to its config file? (true or
false) Note: if you decide to not do this (though it should be
VERY light on system resources), you can always force bbkeys to
reconfigure itself by sending it a SIGHUP (killall -HUP bbkeys).
autoConfigCheckTimeout
how often should bbkeys check for changes made to its config
file? (numeric number of seconds)
workspaceColumns
number of columns that you have your workspaces laid out in your
pager (numeric)
workspaceRows
number of rows that you have your workspaces/desktops laid out
in (numeric). As way of an example, if you have your pager laid
out in a 4x2 grid (4 wide, 2 high), then you would set
workspaceColumns to 4 and workspaceRows to 2.
cycleMenuX
horizontal position that you want the window cycling menu to
show up at. (numeric)
cycleMenuY
vertical position that you want the window cycling menu to show
up at. (numeric) NOTE. The cycleMenuX and cycleMenuY config
options allow you to place your window-cycling window exactly
where you want to put it on screen. We at the Bbkeys Foundation
For Better Software (TM) call this a feature, though some crazy
nuts might call it a bug caused by the fact that blackbox’s Menu
class doesn’t have anything in it to center it on-screen, etc.
It also doesn’t have any methods available to figure out how big
the menu will be on-screen. This can be worked around by
bbkeys, but I’ve not the time to do it now. Patch anyone? Or,
you can just consider it a really neat feature that you can
place the popup window-cycling window anywhere you want. =:D
KEYBINDINGS
The format of this section is similar to the config section, and
blackbox’s menu structure. Each line will look like this:
[command] (keys) {parameters}
Parameters:
Not all directives need to have parameters provided, and within the
[keybindings] section, the only sub-group allowed (a group that will
have an [end] tag) is the [chain] tag. The chain tag is special and
allows the user to give emacs-style keybindings, where a certain
keystroke is given, released, and then another keystroke is given to
complete the action. A good example would be the following:
[chain] (Control-Mod1-W)
[sendToWorkspace] (1) {1}
[sendToWorkspace] (2) {2}
[sendToWorkspace] (3) {3}
[sendToWorkspace] (4) {4}
[end]
Note that both the beginning [chain] and the ending [end] tags must be
provided. In this example, the chain is begun by the user pressing
(and holding) the Control modifier, the Mod1 (Alt) modifier, and the
"W" key on his keyboard. The user then releases these keys and bbkeys
enters the chain. Bbkeys will then wait for the user to press one of
the keybindings from within that chain to execute the next action. In
this case, if bbkeys sees either the 1, 2, 3 or 4 key pressed on the
keyboard, it will execute the given action for that key. Again, in
this case, bbkeys will send the currently-focused window to the
workspace specified in the {}-enclosed parameter (workspace 1, 2, 3, or
4 as the case may be here.
So, the parameters provided in a keybinding directive can be seen as
additional information to provide to the "command". In some cases, it
will be a number (what workspace to send a window to, how many pixels
to move the window, how many pixels to resize a window, etc.). In
other cases, it will be a string ("xterm -fn nexus", for example, as an
argument to the Execute command. And for many directives, it is not
needed at all.
Keys:
The format for the keybindings are using 0 or more modifiers, separated
with the "-" character, finally followed by the key name as known to X.
The "left" key, for example, is known to X as "Left". The "j" key is
known as "J". You get the idea. The modifiers are typically, "Shift",
"Control", and "Mod1". An example would be Mod1-Control-K. This would
be listed as the second element in a keybinding directive.
Commands:
The following commands are understood by bbkeys. Bbkeys is not
case-sensitive with regards to its commands, so the case may be mixed
accidentally or on purpose. =:)
execute
Executes a command. An string argument/parameter is expected
for this directive that lists the command to be executed.
iconify
raise
lower
close
toggleShade
toggleOmnipresent
Sets a window to be "sticky"--on all workspaces.
toggleDecorations
Either strips a window of all decorations or causes it to be
decorated regularly.
moveWindowUp
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to move the currently-selected
window.
moveWindowDown
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to move the currently-selected
window.
moveWindowLeft
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to move the currently-selected
window.
moveWindowRight
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to move the currently-selected
window.
resizeWindowWidth
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to resize the currently-selected
window. This may be a positive or negative number, allowing
bbkeys to grow or shrink the window.
resizeWindowHeight
A numeric parameter may be provided which tells bbkeys how many
pixels in the given direction to resize the currently-selected
window. This may be a positive or negative number, allowing
bbkeys to grow or shrink the window.
toggleMaximizeFull
toggleMaximizeVertical
toggleMaximizeHorizontal
sendToWorkspace
A numeric parameter must be provided which tells bbkeys which
workspace (1-based index) to send the current window to.
nextWindow
Used for window cycling (alt-tabbing, most often). Selects the
next window according to the window stack.
prevWindow
Used for window cycling (alt-tabbing, most often). Selects the
previous window according to the window stack.
nextWindowOnAllWorkspaces
prevWindowOnAllWorkspaces
nextWindowOnAllScreens
prevWindowOnAllScreens
nextWindowOfClass
prevWindowOfClass
nextWindowOfClassOnAllWorkspaces
prevWindowOfClassOnAllWorkspaces
changeWorkspace
A numeric parameter must be given to tell bbkeys which 1-based
workspace to switch to.
nextWorkspace
prevWorkspace
upWorkspace
downWorkspace
leftWorkspace
rightWorkspace
nextScreen
prevScreen
chain No parameter is needed for this directive.
EXAMPLE
Example config file below...
[begin] (bbkeys configuration file)
[config]
[option] (stylefile)
{~/local/blackbox-CVS/share/blackbox/styles/Cthulhain}
[option] (honorModifiers) {false}
[option] (raiseWhileCycling) {false}
[option] (showCycleMenu) {true}
[option] (menuTextJustify) {right}
[option] (autoConfig) {true}
[option] (autoConfigCheckTimeout) {2}
[option] (workspaceColumns) {4}
[option] (workspaceRows) {2}
[option] (cycleMenuX) {20}
[option] (cycleMenuY) {20}
[end]
[keybindings] (begin keybindings)
[chain] (Control-Mod1-W)
[sendToWorkspace] (1) {1}
[sendToWorkspace] (2) {2}
[sendToWorkspace] (3) {3}
[sendToWorkspace] (4) {4}
[sendToWorkspace] (5) {5}
[sendToWorkspace] (6) {6}
[sendToWorkspace] (7) {7}
[sendToWorkspace] (8) {8}
[end]
[chain] (Mod1-Y)
[execute] (1) {xmms}
[execute] (2) {aumix -v +5}
[execute] (3) {aumix -v -5}
[end]
[Lower] (Mod1-Down)
[Raise] (Mod1-Up)
[toggleShade] (Mod1-F9)
[Close] (Mod1-F4)
[Iconify] (Mod1-m)
[toggleMaximizeFull] (Mod1-F12)
[toggleMaximizeHorizontal] (Mod1-F11)
[toggleMaximizeVertical] (Mod1-F10)
[toggleOmnipresent] (Mod1-Control-S)
[resizeWindowWidth] (Mod1-Control-Shift-Left) {-5}
[resizeWindowWidth] (Mod1-Control-Shift-Right) {5}
[resizeWindowHeight] (Mod1-Control-Shift-Up) {-5}
[resizeWindowHeight] (Mod1-Control-Shift-Down) {5}
[moveWindowUp] (Mod1-Control-Up) {1}
[moveWindowDown] (Mod1-Control-Down) {1}
[moveWindowLeft] (Mod1-Control-Left) {1}
[moveWindowRight] (Mod1-Control-Right) {1}
[NextWindow] (Mod1-Tab)
[NextWindowOnAllWorkspaces] (Mod1-Control-Tab)
[PrevWindow] (Mod1-Shift-Tab)
[changeWorkspace] (Mod1-1) {1}
[changeWorkspace] (Mod1-2) {2}
[changeWorkspace] (Mod1-3) {3}
[changeWorkspace] (Mod1-4) {4}
[changeWorkspace] (Mod1-5) {5}
[changeWorkspace] (Mod1-6) {6}
[changeWorkspace] (Mod1-7) {7}
[changeWorkspace] (Mod1-8) {8}
[upWorkspace] (Mod1-Control-K)
[downWorkspace] (Mod1-Control-J)
[leftWorkspace] (Mod1-Control-H)
[rightWorkspace] (Mod1-Control-L)
[showRootMenu] (Mod1-Control-Escape)
[Execute] (Mod1-F5) {xrefresh}
[Execute] (Mod1-F1) {gnome-terminal}
#[Execute] (Mod4-E) {kfmclient openProfile filemanagement}
#[Execute] (F20) {kfmclient openProfile filemanagement}
[Execute] (Mod4-E) {nautilus /home/gideon}
[Execute] (F20) {nautilus /home/gideon}
[end] (end keybindings) [end] (end bbkeys configuration)
SEE ALSO
bbkeys(1), blackbox(1)
AUTHOR
Jason ’vanRijn’ Kasper <vR@movingparts.net> - bbkeys
Jan Schaumann <jschauma@netmeister.org> - this man page