1BBKEYSRC(5)                        bbkeysrc                        BBKEYSRC(5)
2
3
4

NAME

6       bbkeysrc - bbkeys configuration file
7
8

SYNOPSIS

10       $HOME/.bbkeysrc
11
12

DESCRIPTION

14       bbkeys  picks up its configuration settings from $HOME/.bbkeysrc unless
15       overridden on the command line.  There are several avenues open to  the
16       user to set any key-grabs that the user wishes:
17
18
19   Using bbconf:
20       This  is  a  Qt-based  application  available  at http://bbconf.source
21       forge.net/.
22
23
24   Manually editing $HOME/.bbkeysrc:
25       The format is very easy, and it follows the same format  as  blackbox's
26       menu  files.   It  must  begin  with a "[begin]" tag.  It may contain a
27       "[config]" tag, containing  a  configuration  section,  ending  with  a
28       "[end]"  tag.   In  fact,  all  opening  section  tags must end with an
29       "[end]" tag.  It should also contain a "[keybindings]" section.
30       For more information, see the man page for blackbox's menu.
31
32

LIST OF CONFIG OPTIONS

34       stylefile:
35              filename of blackbox style to use (string)
36
37
38       honorModifiers:
39              whether or not to break if NumLock  or  ScrollLock  is  pressed.
40              (hint:  for  bbkeys  to  ignore  your  keybindings if NumLock or
41              ScrollLock are pressed, set this to true) (true or false)
42
43
44       raiseWhileCycling:
45              should bbkeys raise the windows  you're  cycling  through  while
46              cycling through them? (true or false)
47
48
49       showCycleMenu
50              show  the  window-cycling  menu  or  cycle  without it? (true or
51              false)
52
53
54       cycleMenuTitle
55              show the given string as the title of the  window-cycling  menu.
56              if  an  empty  string  is passed as the parameter to this config
57              option("{}"), then the title will not be drawn. (string value)
58
59
60       menuTextJustify
61              how should the window-cycling menu be justified? (left,  center,
62              right)
63
64
65       menuTitleJustify
66              how should the window-cycling title be justified? (left, center,
67              right)
68
69
70       autoConfig
71              should bbkeys watch for changes to its config  file?   (true  or
72              false)  Note:  if you decide to not do this (though it should be
73              VERY light on system resources), you can always force bbkeys  to
74              reconfigure itself by sending it a SIGHUP (killall -HUP bbkeys).
75
76
77       autoConfigCheckTimeout
78              how  often  should  bbkeys  check for changes made to its config
79              file?  (numeric number of seconds)
80
81
82       workspaceColumns
83              number of columns that you have your workspaces laid out in your
84              pager (numeric)
85
86
87       workspaceRows
88              number  of  rows that you have your workspaces/desktops laid out
89              in (numeric).  As way of an example, if you have your pager laid
90              out  in  a  4x2  grid  (4  wide,  2  high),  then  you would set
91              workspaceColumns to 4 and workspaceRows to 2.
92
93
94       cycleMenuX
95              horizontal position that you want the  window  cycling  menu  to
96              show up at. (numeric)
97
98
99       cycleMenuY
100              vertical  position that you want the window cycling menu to show
101              up at. (numeric)  NOTE.  The cycleMenuX  and  cycleMenuY  config
102              options  allow  you  to place your window-cycling window exactly
103              where you want to put it on screen.  We at the Bbkeys Foundation
104              For  Better Software (TM) call this a feature, though some crazy
105              nuts might call it a bug caused by the fact that blackbox's Menu
106              class  doesn't  have anything in it to center it on-screen, etc.
107              It also doesn't have any methods available to figure out how big
108              the  menu  will  be  on-screen.   This  can  be worked around by
109              bbkeys, but I've not the time to do it now.  Patch anyone?   Or,
110              you  can  just  consider  it  a really neat feature that you can
111              place the popup window-cycling window anywhere you want.  =:D
112

KEYBINDINGS

114       The format of this section is similar to the config section, and black‐
115       box's menu structure.  Each line will look like this:
116
117              [command] (keys) {parameters}
118
119
120       Parameters:
121       Not  all  directives  need  to have parameters provided, and within the
122       [keybindings] section, the only sub-group allowed (a  group  that  will
123       have  an  [end]  tag) is the [chain] tag.  The chain tag is special and
124       allows the user to give emacs-style keybindings, where a  certain  key‐
125       stroke  is given, released, and then another keystroke is given to com‐
126       plete the action.  A good example would be the following:
127
128
129                  [chain] (Control-Mod1-W)
130                    [sendToWorkspace] (1) {1}
131                    [sendToWorkspace] (2) {2}
132                    [sendToWorkspace] (3) {3}
133                    [sendToWorkspace] (4) {4}
134                  [end]
135
136
137       Note that both the beginning [chain] and the ending [end] tags must  be
138       provided.   In  this  example,  the chain is begun by the user pressing
139       (and holding) the Control modifier, the Mod1 (Alt)  modifier,  and  the
140       "W"  key on his keyboard.  The user then releases these keys and bbkeys
141       enters the chain.  Bbkeys will then wait for the user to press  one  of
142       the  keybindings from within that chain to execute the next action.  In
143       this case, if bbkeys sees either the 1, 2, 3 or 4 key  pressed  on  the
144       keyboard,  it  will  execute  the given action for that key.  Again, in
145       this case,  bbkeys  will  send  the  currently-focused  window  to  the
146       workspace specified in the {}-enclosed parameter (workspace 1, 2, 3, or
147       4 as the case may be here.
148
149
150       So, the parameters provided in a keybinding directive can  be  seen  as
151       additional  information to provide to the "command".  In some cases, it
152       will be a number (what workspace to send a window to, how  many  pixels
153       to  move  the  window,  how  many pixels to resize a window, etc.).  In
154       other cases, it will be a string ("xterm -fn nexus", for example, as an
155       argument  to  the  Execute command.  And for many directives, it is not
156       needed at all.
157
158
159
160       Keys:
161       The format for the keybindings are using 0 or more modifiers, separated
162       with the "-" character, finally followed by the key name as known to X.
163       The "left" key, for example, is known to X as "Left".  The "j"  key  is
164       known as "J".  You get the idea.  The modifiers are typically, "Shift",
165       "Control", and "Mod1".  An example would be Mod1-Control-K.  This would
166       be listed as the second element in a keybinding directive.
167
168
169       Commands:
170       The  following  commands  are  understood  by  bbkeys.   Bbkeys  is not
171       case-sensitive with regards to its commands, so the case may  be  mixed
172       accidentally or on purpose.  =:)
173
174
175
176       execute
177              Executes  a  command.   An string argument/parameter is expected
178              for this directive that lists the command to be executed.
179
180
181       iconify
182
183
184       raise
185
186
187       lower
188
189
190       close
191
192
193       toggleShade
194
195
196       toggleOmnipresent
197              Sets a window to be "sticky"--on all workspaces.
198
199
200       toggleDecorations
201              Either strips a window of all decorations or  causes  it  to  be
202              decorated regularly.
203
204
205       moveWindowUp
206              A  numeric parameter may be provided which tells bbkeys how many
207              pixels in the given direction  to  move  the  currently-selected
208              window.
209
210
211       moveWindowDown
212              A  numeric parameter may be provided which tells bbkeys how many
213              pixels in the given direction  to  move  the  currently-selected
214              window.
215
216
217       moveWindowLeft
218              A  numeric parameter may be provided which tells bbkeys how many
219              pixels in the given direction  to  move  the  currently-selected
220              window.
221
222
223       moveWindowRight
224              A  numeric parameter may be provided which tells bbkeys how many
225              pixels in the given direction  to  move  the  currently-selected
226              window.
227
228
229       resizeWindowWidth
230              A  numeric parameter may be provided which tells bbkeys how many
231              pixels in the given direction to resize  the  currently-selected
232              window.   This  may  be  a positive or negative number, allowing
233              bbkeys to grow or shrink the window.
234
235
236       resizeWindowHeight
237              A numeric parameter may be provided which tells bbkeys how  many
238              pixels  in  the given direction to resize the currently-selected
239              window.  This may be a positive  or  negative  number,  allowing
240              bbkeys to grow or shrink the window.
241
242
243       toggleMaximizeFull
244
245
246       toggleMaximizeVertical
247
248
249       toggleMaximizeHorizontal
250
251
252       sendToWorkspace
253              A  numeric  parameter  must be provided which tells bbkeys which
254              workspace (1-based index) to send the current window to.
255
256
257       nextWindow
258              Used for window cycling (alt-tabbing, most often).  Selects  the
259              next window according to the window stack.
260
261
262       prevWindow
263              Used  for window cycling (alt-tabbing, most often).  Selects the
264              previous window according to the window stack.
265
266
267       nextWindowOnAllWorkspaces
268
269
270       prevWindowOnAllWorkspaces
271
272
273       nextWindowOnAllScreens
274
275
276       prevWindowOnAllScreens
277
278
279       nextWindowOfClass
280
281
282       prevWindowOfClass
283
284
285       nextWindowOfClassOnAllWorkspaces
286
287
288       prevWindowOfClassOnAllWorkspaces
289
290
291       changeWorkspace
292              A numeric parameter must be given to tell bbkeys  which  1-based
293              workspace to switch to.
294
295
296       nextWorkspace
297
298
299       prevWorkspace
300
301
302       upWorkspace
303
304
305       downWorkspace
306
307
308       leftWorkspace
309
310
311       rightWorkspace
312
313
314       nextScreen
315
316
317       prevScreen
318
319
320       chain  No parameter is needed for this directive.
321
322

EXAMPLE

324       Example config file below...
325
326       [begin] (bbkeys configuration file)
327
328         [config]
329           [option]       (stylefile)       {~/local/blackbox-CVS/share/black‐
330       box/styles/Cthulhain}
331           [option] (honorModifiers) {false}
332           [option] (raiseWhileCycling) {false}
333           [option] (showCycleMenu)  {true}
334           [option] (menuTextJustify) {right}
335           [option] (autoConfig)   {true}
336           [option] (autoConfigCheckTimeout) {2}
337           [option] (workspaceColumns) {4}
338           [option] (workspaceRows) {2}
339           [option] (cycleMenuX) {20}
340           [option] (cycleMenuY) {20}
341         [end]
342
343         [keybindings] (begin keybindings)
344           [chain] (Control-Mod1-W)
345             [sendToWorkspace] (1) {1}
346             [sendToWorkspace] (2) {2}
347             [sendToWorkspace] (3) {3}
348             [sendToWorkspace] (4) {4}
349             [sendToWorkspace] (5) {5}
350             [sendToWorkspace] (6) {6}
351             [sendToWorkspace] (7) {7}
352             [sendToWorkspace] (8) {8}
353           [end]
354           [chain] (Mod1-Y)
355             [execute] (1) {xmms}
356             [execute] (2) {aumix -v +5}
357             [execute] (3) {aumix -v -5}
358           [end]
359           [Lower]  (Mod1-Down)
360           [Raise]  (Mod1-Up)
361           [toggleShade]  (Mod1-F9)
362           [Close]  (Mod1-F4)
363           [Iconify]  (Mod1-m)
364           [toggleMaximizeFull]  (Mod1-F12)
365           [toggleMaximizeHorizontal]  (Mod1-F11)
366           [toggleMaximizeVertical]  (Mod1-F10)
367           [toggleOmnipresent]  (Mod1-Control-S)
368           [resizeWindowWidth]  (Mod1-Control-Shift-Left) {-5}
369           [resizeWindowWidth]  (Mod1-Control-Shift-Right) {5}
370           [resizeWindowHeight]  (Mod1-Control-Shift-Up) {-5}
371           [resizeWindowHeight]  (Mod1-Control-Shift-Down) {5}
372           [moveWindowUp]  (Mod1-Control-Up) {1}
373           [moveWindowDown]  (Mod1-Control-Down) {1}
374           [moveWindowLeft]  (Mod1-Control-Left) {1}
375           [moveWindowRight]  (Mod1-Control-Right) {1}
376           [NextWindow]  (Mod1-Tab)
377           [NextWindowOnAllWorkspaces]  (Mod1-Control-Tab)
378           [PrevWindow]  (Mod1-Shift-Tab)
379           [changeWorkspace]  (Mod1-1) {1}
380           [changeWorkspace]  (Mod1-2) {2}
381           [changeWorkspace]  (Mod1-3) {3}
382           [changeWorkspace]  (Mod1-4) {4}
383           [changeWorkspace]  (Mod1-5) {5}
384           [changeWorkspace]  (Mod1-6) {6}
385           [changeWorkspace]  (Mod1-7) {7}
386           [changeWorkspace]  (Mod1-8) {8}
387
388           [upWorkspace] (Mod1-Control-K)
389           [downWorkspace] (Mod1-Control-J)
390           [leftWorkspace] (Mod1-Control-H)
391           [rightWorkspace] (Mod1-Control-L)
392
393           [showRootMenu] (Mod1-Control-Escape)
394
395           [Execute]  (Mod1-F5) {xrefresh}
396           [Execute]  (Mod1-F1) {gnome-terminal}
397           #[Execute]  (Mod4-E) {kfmclient openProfile filemanagement}
398           #[Execute]  (F20) {kfmclient openProfile filemanagement}
399           [Execute]  (Mod4-E) {nautilus /home/gideon}
400           [Execute]  (F20) {nautilus /home/gideon}
401         [end] (end keybindings) [end] (end bbkeys configuration)
402

SEE ALSO

404       bbkeys(1), blackbox(1)
405
406

AUTHOR

408       Jason 'vanRijn' Kasper <vR@movingparts.net> - bbkeys
409       Jan Schaumann <jschauma@netmeister.org> - this man page
410
411
412
413vanRijn                         August 27, 2004                    BBKEYSRC(5)
Impressum