doc/bbkeysrc.5

   1 .\"
   2 .\" $Id$
   3 .\"
   4 .TH "BBKEYSRC" "5" "August 27, 2004" "vanRijn" "bbkeysrc"
   5 .SH "NAME"
   6 bbkeysrc \- bbkeys configuration file
   7
   8 .SH "SYNOPSIS"
   9 .B $HOME/.bbkeysrc
  10
  11 .SH "DESCRIPTION"
  12 \fBbbkeys\fR picks up its configuration settings from $HOME/.bbkeysrc unless overridden on the command line.
  13 There are several avenues open to the user to set any key\-grabs that the user wishes:
  14
  15 .SS "Using \fIbbconf\fR:"
  16 This is a Qt\-based application available at http://bbconf.sourceforge.net/.
  17
  18 .SS "Manually editing \fI$HOME/.bbkeysrc\fR:"
  19 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.
  20 .br
  21 .br
  22 For more information, see the man page for blackbox's menu.
  23
  24 .SH "LIST OF CONFIG OPTIONS"
  25 .TP
  26 \fIstylefile\fR:
  27 filename of blackbox style to use (string)
  28
  29 .TP
  30 \fIhonorModifiers\fR:
  31 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)
  32
  33 .TP
  34 \fIraiseWhileCycling\fR:
  35 should bbkeys raise the windows you're cycling through while cycling through them? (true or false)
  36
  37 .TP
  38 \fIfollowWindowOnSend\fR:
  39 should bbkeys follow the window that you send to another workspace?  this will apply to all send\-to operations such that if this is set to true, bbkeys will change workspaces to the workspace that you send the window to. (true or false)
  40
  41 .TP
  42 \fIincludeIconifiedWindowsInCycle\fR:
  43 should bbkeys include iconified windows in its window-cycling list? (true or false)
  44
  45 .TP
  46 \fIshowCycleMenu\fR
  47 show the window\-cycling menu or cycle without it? (true or false)
  48
  49 .TP
  50 \fIcycleMenuTitle\fR
  51 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)
  52
  53 .TP
  54 \fImenuTextJustify\fR
  55 how should the window\-cycling menu be justified? (left, center, right)
  56
  57 .TP
  58 \fImenuTitleJustify\fR
  59 how should the window\-cycling title be justified? (left, center, right)
  60
  61 .TP
  62 \fIautoConfig\fR
  63 should bbkeys watch for changes to its config file?
  64 (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).
  65
  66 .TP
  67 \fIautoConfigCheckTimeout\fR
  68 how often should bbkeys check for changes made to its
  69 config file?  (numeric number of seconds)
  70
  71 .TP
  72 \fIworkspaceColumns\fR
  73 number of columns that you have your workspaces laid
  74 out in your pager (numeric)
  75
  76 .TP
  77 \fIworkspaceRows\fR
  78 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.
  79
  80 .TP
  81 \fIcycleMenuX\fR
  82 horizontal position that you want the window cycling menu to show up at. (numeric)
  83
  84 .TP
  85 \fIcycleMenuY\fR
  86 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
  87 .SH "KEYBINDINGS"
  88 .LP
  89 The format of this section is similar to the config section, and blackbox's menu structure.  Each line will look like this:
  90 .IP
  91 [command] (keys) {parameters}
  92
  93 .LP
  94 \fBParameters:\fR
  95 .br
  96 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:
  97
  98 .LP
  99 .IP
 100     [chain] (Control\-Mod1\-W)
 101       [sendToWorkspace] (1) {1}
 102       [sendToWorkspace] (2) {2}
 103       [sendToWorkspace] (3) {3}
 104       [sendToWorkspace] (4) {4}
 105     [end]
 106
 107 .LP
 108 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.
 109
 110 .LP
 111 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.
 112
 113
 114 .LP
 115 \fBKeys:\fR
 116 .br
 117 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.
 118
 119 .LP
 120 \fBCommands:\fR
 121 .br
 122 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.  =:)
 123
 124
 125 .TP
 126 \fIexecute\fR
 127 Executes a command.  An string argument/parameter is expected for this directive that lists the command to be executed.
 128
 129 .TP
 130 \fIiconify\fR
 131
 132 .TP
 133 \fIraise\fR
 134
 135 .TP
 136 \fIlower\fR
 137
 138 .TP
 139 \fIclose\fR
 140
 141 .TP
 142 \fItoggleShade\fR
 143
 144 .TP
 145 \fItoggleOmnipresent\fR
 146 Sets a window to be "sticky"\-\-on all workspaces.
 147
 148 .TP
 149 \fItoggleDecorations\fR
 150 Either strips a window of all decorations or causes it to be decorated regularly.
 151
 152 .TP
 153 \fImoveWindowUp\fR
 154 A numeric parameter may be provided which tells bbkeys how many pixels in the given direction to move the currently\-selected window.
 155
 156 .TP
 157 \fImoveWindowDown\fR
 158 A numeric parameter may be provided which tells bbkeys how many pixels in the given direction to move the currently\-selected window.
 159
 160 .TP
 161 \fImoveWindowLeft\fR
 162 A numeric parameter may be provided which tells bbkeys how many pixels in the given direction to move the currently\-selected window.
 163
 164 .TP
 165 \fImoveWindowRight\fR
 166 A numeric parameter may be provided which tells bbkeys how many pixels in the given direction to move the currently\-selected window.
 167
 168 .TP
 169 \fIresizeWindowWidth\fR
 170 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.
 171
 172 .TP
 173 \fIresizeWindowHeight\fR
 174 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.
 175
 176 .TP
 177 \fItoggleMaximizeFull\fR
 178
 179 .TP
 180 \fItoggleMaximizeVertical\fR
 181
 182 .TP
 183 \fItoggleMaximizeHorizontal\fR
 184
 185 .TP
 186 \fIsendToWorkspace\fR
 187 A numeric parameter must be provided which tells bbkeys which workspace (1\-based index) to send the current window to.
 188
 189 .TP
 190 \fIsendToNextWorkspace\fR
 191
 192 .TP
 193 \fIsendToPrevWorkspace\fR
 194
 195 .TP
 196 \fInextWindow\fR
 197 Used for window cycling (alt\-tabbing, most often).  Selects the next window according to the window stack.
 198
 199 .TP
 200 \fIprevWindow\fR
 201 Used for window cycling (alt\-tabbing, most often).  Selects the previous window according to the window stack.
 202
 203 .TP
 204 \fInextWindowOnAllWorkspaces\fR
 205
 206 .TP
 207 \fIprevWindowOnAllWorkspaces\fR
 208
 209 .TP
 210 \fInextWindowOnAllScreens\fR
 211
 212 .TP
 213 \fIprevWindowOnAllScreens\fR
 214
 215 .TP
 216 \fInextWindowOfClass\fR
 217
 218 .TP
 219 \fIprevWindowOfClass\fR
 220
 221 .TP
 222 \fInextWindowOfClassOnAllWorkspaces\fR
 223
 224 .TP
 225 \fIprevWindowOfClassOnAllWorkspaces\fR
 226
 227 .TP
 228 \fIchangeWorkspace\fR
 229 A numeric parameter must be given to tell bbkeys which 1\-based workspace to switch to.
 230
 231 .TP
 232 \fInextWorkspace\fR
 233
 234 .TP
 235 \fIprevWorkspace\fR
 236
 237 .TP
 238 \fIupWorkspace\fR
 239
 240 .TP
 241 \fIdownWorkspace\fR
 242
 243 .TP
 244 \fIleftWorkspace\fR
 245
 246 .TP
 247 \fIrightWorkspace\fR
 248
 249 .TP
 250 \fInextScreen\fR
 251
 252 .TP
 253 \fIprevScreen\fR
 254
 255 .TP
 256 \fIchain\fR
 257 No parameter is needed for this directive.
 258
 259 .LP
 260
 261 .SH "EXAMPLE"
 262 Example config file below...
 263 .br
 264
 265 [begin] (bbkeys configuration file)
 266
 267   [config]
 268     [option] (stylefile) {~/local/blackbox\-CVS/share/blackbox/styles/Cthulhain}
 269     [option] (honorModifiers) {false}
 270     [option] (raiseWhileCycling) {false}
 271     [option] (showCycleMenu)  {true}
 272     [option] (menuTextJustify) {right}
 273     [option] (autoConfig)   {true}
 274     [option] (autoConfigCheckTimeout) {2}
 275     [option] (workspaceColumns) {4}
 276     [option] (workspaceRows) {2}
 277     [option] (cycleMenuX) {20}
 278     [option] (cycleMenuY) {20}
 279   [end]
 280
 281   [keybindings] (begin keybindings)
 282     [chain] (Control\-Mod1\-W)
 283       [sendToWorkspace] (1) {1}
 284       [sendToWorkspace] (2) {2}
 285       [sendToWorkspace] (3) {3}
 286       [sendToWorkspace] (4) {4}
 287       [sendToWorkspace] (5) {5}
 288       [sendToWorkspace] (6) {6}
 289       [sendToWorkspace] (7) {7}
 290       [sendToWorkspace] (8) {8}
 291     [end]
 292     [chain] (Mod1\-Y)
 293       [execute] (1) {xmms}
 294       [execute] (2) {aumix \-v +5}
 295       [execute] (3) {aumix \-v \-5}
 296     [end]
 297     [Lower]  (Mod1\-Down)
 298     [Raise]  (Mod1\-Up)
 299     [toggleShade]  (Mod1\-F9)
 300     [Close]  (Mod1\-F4)
 301     [Iconify]  (Mod1\-m)
 302     [toggleMaximizeFull]  (Mod1\-F12)
 303     [toggleMaximizeHorizontal]  (Mod1\-F11)
 304     [toggleMaximizeVertical]  (Mod1\-F10)
 305     [toggleOmnipresent]  (Mod1\-Control\-S)
 306     [resizeWindowWidth]  (Mod1\-Control\-Shift\-Left) {\-5}
 307     [resizeWindowWidth]  (Mod1\-Control\-Shift\-Right) {5}
 308     [resizeWindowHeight]  (Mod1\-Control\-Shift\-Up) {\-5}
 309     [resizeWindowHeight]  (Mod1\-Control\-Shift\-Down) {5}
 310     [moveWindowUp]  (Mod1\-Control\-Up) {1}
 311     [moveWindowDown]  (Mod1\-Control\-Down) {1}
 312     [moveWindowLeft]  (Mod1\-Control\-Left) {1}
 313     [moveWindowRight]  (Mod1\-Control\-Right) {1}
 314     [NextWindow]  (Mod1\-Tab)
 315     [NextWindowOnAllWorkspaces]  (Mod1\-Control\-Tab)
 316     [PrevWindow]  (Mod1\-Shift\-Tab)
 317     [changeWorkspace]  (Mod1\-1) {1}
 318     [changeWorkspace]  (Mod1\-2) {2}
 319     [changeWorkspace]  (Mod1\-3) {3}
 320     [changeWorkspace]  (Mod1\-4) {4}
 321     [changeWorkspace]  (Mod1\-5) {5}
 322     [changeWorkspace]  (Mod1\-6) {6}
 323     [changeWorkspace]  (Mod1\-7) {7}
 324     [changeWorkspace]  (Mod1\-8) {8}
 325
 326     [upWorkspace] (Mod1\-Control\-K)
 327     [downWorkspace] (Mod1\-Control\-J)
 328     [leftWorkspace] (Mod1\-Control\-H)
 329     [rightWorkspace] (Mod1\-Control\-L)
 330
 331     [showRootMenu] (Mod1\-Control\-Escape)
 332
 333     [Execute]  (Mod1\-F5) {xrefresh}
 334     [Execute]  (Mod1\-F1) {gnome\-terminal}
 335     #[Execute]  (Mod4\-E) {kfmclient openProfile filemanagement}
 336     #[Execute]  (F20) {kfmclient openProfile filemanagement}
 337     [Execute]  (Mod4\-E) {nautilus /home/gideon}
 338     [Execute]  (F20) {nautilus /home/gideon}
 339   [end] (end keybindings)
 340 [end] (end bbkeys configuration)
 341 .SH "SEE ALSO"
 342 .BR bbkeys(1),
 343 .BR blackbox(1)
 344
 345 .SH "AUTHOR"
 346 .nr
 347 Jason 'vanRijn' Kasper <vR@movingparts.net> \- bbkeys
 348 .br
 349 Jan Schaumann <jschauma@netmeister.org> \- this man page