1musca(1) Users Manual musca(1)
2
6 musca - A simple dynamic window manager
7
9 musca [OPTIONS]
10
12 Musca is a simple dynamic window manager for X, with features nicked
13 from ratpoison and dwm.
14 Musca operates as a tiling window manager by default. It uses "manual
16 tiling", which means the user determines how the screen is divided into
17 non-overlapping frames, with no restrictions on layout.
18 Application windows always fill their assigned frame, with the excep‐
20 tion of transient windows and popup dialog boxes which float above
21 their parent application at the appropriate size. Once visible, appli‐
22 cations do not change frames unless so instructed.
23 Since not all applications suit tiling, a more traditional stacking
25 window manager mode is also available, allowing windows to float at any
26 screen location and overlap.
27 There are no built in status bars, panels, tabs or window decorations
29 to take up screen real estate. If the user wants any of these things,
30 there are plenty of external applications available to do the job. Win‐
31 dow decoration is limited to a slender border, which is coloured to
32 indicate keyboard focus.
33 Windows are placed in named "groups" which can be used in a similar
35 fashion to virtual desktops. Groups can be added and removed on the
36 fly, and each group has its own frame layout.
37 The excellent "dmenu" utility is being used to execute commands and
39 launch applications, and it can also act as a window and group
40 switcher. Basic EWMH support allows use of common panels, pagers and
41 the wmctrl utility.
42 Windows and frames are navigated and focused on any mouse button click,
44 including rolling the wheel, or alternatively driven entirely by the
45 keyboard. Simple key combinations exist for window switching, group
46 switching, frame control and screen switching.
47 For more information about Musca visit http://aerosuidae.net/musca.html
49
51 These command line options are recognized by Musca:
52 -c [command]
54 Connect to a running instance of Musca and execute a single Musca command
55 supplied on the command line.
56 -i
58 Connect to a running instance of Musca and execute one or more EOL delimited
59 Musca commands supplied on stdin.
60 -s [path]
62 Override the "startup" setting by specifying a custom path to a configuration
63 file holding Musca commands to execute at startup.
64 -v
66 Report version number.
67
69 During initialization, Musca will read the ~/.musca_start configuration
70 file or any other text file which was specified by the 'startup' set‐
71 ting in config.h during compilation.
72 The startup file should contain Musca commands one per line. Any com‐
74 ments must be on separate lines starting with hash (#). Blank lines are
75 acceptable.
76 For example:
78 manage off trayer
80 manage off Conky
81 screen 1
83 name bling
84 pad 0 0 0 32
85 exec trayer
86 exec conky
87 screen 0
89 add mail
90 add net
91 add work
92 use mail
93 exec firefox gmail.com
94 exec evolution
95 hsplit 1/2
96 set notify notify-send -t 3000 Musca "$(cat)"
98 Note that launching applications from the startup file is acceptable,
100 but can be of limited use if they have to start in more than one group.
101 The 'exec' command runs asynchronously, and if applications are slow to
102 create their windows, they may not necessarily appear in the expected
103 group. In this case, a better option is launching applications from
104 ~/.xinitrc.
105
108 add <name>
109 create a new group called `name`, and switch to it.
110 alias <name> <command>
112 create a new Musca command.
113 bind <on|off> <Modifier>+<Key> <command>
115 bind a Musca command to a key combination with `on`, and remove it
116 again with `off`. If the argument to `off` is `all`, it clears the
117 bound key list. The `command` argument is only need for `on`.
118 border <on|off|flip>
120 (toggle) turn the current frame border on and off.
121 catchall <on|off|flip>
123 (toggle) set the current frame as a `catch-all`, where all new windows
124 will open.
125 client hints <on|off>
127 (toggle) whether to respect X size hints for the current application window,
128 such as PMinSize, PMaxSize, PResizeInc, PBaseSize, PAspect.
129 command
131 launch the dmenu Musca command input.
132 cycle <local> <next|prev>
134 cycle a hidden window into the current frame. `local` means
135 cycle over windows previously displayed in the current frame.
136 `next` or `prev` specify the direction, defaulting to next.
137 Both arguments are optional.
138 dedicate <on|off|flip>
140 (toggle) dedicate the current frame to the current application.
141 drop <name|nr>
143 delete a group by `name` or by `nr`.
144 dump <file>
146 export a description (group name and frame layout) of the current group to `file`.
147 exec <command>
149 execute as shell command.
150 focus <left|right|up|down> or <lfocus|rfocus|ufocus|dfocus>
152 change focus to a frame in the specified direction.
153 height <relative|pixel>
155 resize frame vertically.
156 hook <on|off> <name> <command>
158 bind a Musca command to a named hook.
159 hsplit <relative|pixel>
161 split frame horizontally.
162 kill <number|name>
164 politely close the client window via a close event. When the optional
165 argument `number` or `name` is given, kill the associated window,
166 otherwise kill the current frame. Press again to forcibly kill it.
167 load <file>
169 import a description from `file` into the current group.
170 manage <on|off> <name>
172 (toggle) set whether the window class called `name` is managed or ignored.
173 move <name|nr>
175 move the current window to the group called `name` or to the group `nr`.
176 If it's an unknown group, automatically creates the group `name` and then
177 moves the current window to that group.
178 name <name>
180 rename the current group.
181 only
183 remove all other frames except the current one, resizing it to full screen.
184 pad <left> <right> <top> <bottom>
186 set the current group screen padding in pixels.
187 quit
189 exit Musca.
190 raise <number|title>
192 raise and focus a window in the current group by number (order opened) or
193 title.
194 remove
196 remove the current frame and resize others to fill the gap.
197 resize <left|right|up|down>
199 resize the current frame in the specified direction.
200 run <file>
202 execute a file consisting of Musca commands. The file must contain
203 one command per line. Lines starting with hash *#* are comments and
204 blank lines are acceptable.
205 say <text>
207 display text via the method in the 'notify' setting.
208 screen <number>
210 switch to screen `number`. This is zero based, and should match the order
211 in which screens are defined in "xorg.conf".
212 set <setting> <value>
214 set a Musca variable. See SETTINGS for a list of variable names.
215 shell
217 launch the dmenu shell command input.
218 show <settings|bindings|unmanaged|hooks|groups|frames|windows|aliases>
220 output a system table for diagnostic purposes.
221 shrink <number|title>
223 Minimize/Iconify (same thing in Musca) a window.
224 slide <left|right|up|down> or <lslide|rslide|uslide|dslide>
226 move current window into the frame to the left, right, up and down respectively.
227 stack <on|off|flip>
229 (toggle) switch the current group between `tiling` and `stacking` window modes.
230 swap <left|right|up|down> or <lswap|rswap|uswap|dswap>
232 swap current window with the contents of the frame to the left, right, up
233 and down respectively.
234 switch <window|group>
236 launch the dmenu window or group switcher.
237 undo
239 revert the last frame layout change.
240 use <name|number|(other)|(prev)|(next)>
242 switch to a group called by its `name` or to a group by its `number`.
243 `name` has precedence over `number`. If it's an unknown group, automatically
244 creates the group `name` and then switch to that group.
245 When `(other)`, `(prev)` or `(next)`, switch to the previously focused, previous
246 or next group respectively.
247 vsplit <relative|pixel>
249 split frame vertically.
250 width <relative|pixel>
252 resize frame horizontally.
253 Notes:
255 Any Musca command may be prefixed with "silent" to prevent any messages
257 being sent to the notify setting. This is useful for scripting, to pre‐
258 vent popup window noise.
259 Example:
261 musca -c "silent show groups"
262 Relative values can be specified as a percentage or a fraction:
264 Examples:
266 hsplit 2/3
267 hsplit 33%
268
271 border_catchall_focus
272 Type: string
273 Default: Green
274 Border colour for focused `catchall` frames in tiling mode.
276 border_catchall_unfocus
278 Type: string
279 Default: Dark Green
280 Border colour for unfocused `catchall` frames in tiling mode.
282 border_dedicate_focus
284 Type: string
285 Default: Red
286 Border colour for focused `dedicated` frames in tiling mode.
288 border_dedicate_unfocus
290 Type: string
291 Default: Dark Red
292 Border colour for unfocused `dedicated` frames in tiling mode.
294 border_focus
296 Type: string
297 Default: Blue
298 Border colour for focused frames in tiling mode, and focused
300 windows in stacking mode.
301 border_unfocus
303 Type: string
304 Default: Dim Gray
305 Border colour for unfocused frames in tiling mode, and unfocused
307 windows in stacking mode.
308 border_width
310 Type: integer
311 Default: 1
312 Width in pixels of frame borders in tiling mode, and window bor‐
314 ders in stacking mode. The minimum value is 0, which makes frame
315 borders invisible.
316 command_buffer_size
318 Type: integer
319 Default: 4096
320 Size in bytes of the allocated buffer for passing commands and
322 results to and from "musca -c" and "musca -i".
323 dmenu
325 Type: string
326 Default: "dmenu -i -b"
327 Command to run to launch 'dmenu' along with any customize
329 appearance arguments. This can be replaced by another launcher
330 so long as it accepts a list of \n terminated items on stdin and
331 returns a single line on stdout.
332 focus_follow_mouse
334 Type: boolean
335 Default: 0
336 (toggle) Set to 1 to enable.
338 frame_display_hidden
340 Type: integer
341 Default: 1
342 When set to "0", empty frames will stay empty until a window is
344 manually selected. When set to "1", empty frames will automati‐
345 cally display the first available hidden window. When set to
346 "2", empty frames will automatically display only windows previ‐
347 ously displayed in this frame.
348 frame_min_wh
350 Type: integer
351 Default: 100
352 Minimum width and height in pixels of frames and managed win‐
354 dows.
355 frame_resize
357 Type: integer
358 Default: 20
359 Size in pixels of a frame resize step. Setting this smaller will
361 make resizing operations smoother, but also slower and increase
362 load.
363 frame_split_focus
365 Type: string
366 Default: current
367 Where focus should go when splitting a frame. When set to "cur‐
369 rent", focus remains to the current frame. When set to "new",
370 the new frame receives the focus.
371 group_close_empty
373 Type: boolean
374 Default: 0
375 When set to "1" and navigating away from an empty group, auto‐
377 matically drop this group.
378 notify
380 Type: string
381 Default: "echo `cat`"
382 The command to run to send the user a message. By default Musca
384 just writes to stdout.
385 notify_buffer_size
387 Type: integer
388 Default: 4096
389 Size in bytes of the allocated buffer for passing messages to
391 the command defined in the 'notify' setting.
392 run_musca_command
394 Type: string
395 Default: "$MUSCA -i"
396 The command to run when the user has entered a Musca command via
398 'dmenu'.
399 run_shell_command
401 Type: string
402 Default: "sed 's/^/exec /' | $MUSCA -i"
403 The command to run when the user has entered a shell command via
405 'dmenu'.
406 stack_mouse_modifier
408 Type: string
409 Default: Mod4
410 The modifier key to use in `stacking` mode, along with mouse
412 buttons 1 and 3, to move and resize windows respectively.
413 startup
415 Type: string
416 Default: ~/.musca_start
417 (optional) Path to a file containing Musca commands to run at
419 start up. The default setting is relative to the working direc‐
420 tory, i.e., Musca will use "$HOME/.musca_start" only if Musca is
421 started from $HOME, which is the usual method for login man‐
422 agers. The file must contain one command per line. Lines start‐
423 ing with hash *#* are comments and blank lines are acceptable.
424 switch_group
426 Type: string
427 Default: "sed 's/^/use /' | $MUSCA -i"
428 The command to run once the user has selected a group name from
430 'dmenu'.
431 switch_window
433 Type: string
434 Default: "sed 's/^/raise /' | $MUSCA -i"
435 The command to run once the user has selected a window number
437 and name from 'dmenu'.
438 window_open_focus
440 Type: boolean
441 Default: 1
442 (toggle) Set to 0 to prevent new windows from taking the input
444 focus.
445 window_open_frame
447 Type: string
448 Default: current
449 When set to "current", new windows always open in the currently
451 focused frame. When set to "empty", new windows will try to find
452 an empty frame to use.
453 window_size_hints
455 Type: boolean
456 Default: 1
457 (toggle) Set to 0 to disable size hints checks for new windows.
459 This can still be overridden on a per client basis using the
460 client command.
461
464 Default Keyboard commands
465 Mod4+h hsplit 1/2
467 Mod4+v vsplit 1/2
469 Mod4+r remove
471 Mod4+o only
473 Mod4+k kill
475 Mod4+c cycle
477 Mod4+w switch window
479 Mod4+g switch group
481 Mod4+x shell
483 Mod4+m command
485 Mod4+d dedicate flip
487 Mod4+a catchall flip
489 Mod4+u undo
491 Mod4+s stack flip
493 Mod4+Left
495 focus left
496 Mod4+Right
498 focus right
499 Mod4+Up
501 focus up
502 Mod4+Down
504 focus down
505 Mod4+Next
507 use (next)
508 Mod4+Prior
510 use (prev)
511 Mod4+Tab
513 screen (next)
514 Mod4+Control+Left
516 resize left
517 Mod4+Control+Right
519 resize right
520 Mod4+Control+Up
522 resize up
523 Mod4+Control+Down
525 resize down
526 Mod4+Shift+Left
528 swap left
529 Mod4+Shift+Right
531 swap right
532 Mod4+Shift+Up
534 swap up
535 Mod4+Shift+Down
537 swap down
538 Mouse commands
540 Mod4+Button1
541 Moves a window in stacking mode.
542 Mod4+Button3
544 Resizes a window in stacking mode.
545
548 Executing Musca commands can optionally trigger a hook command. This
549 can be useful for chaining Musca commands together or firing off
550 scripts on certain events. For example, set default new group padding
551 by hooking into the add command:
552 hook on ^add pad 0 0 0 26
554 Or, attach to multiple commands:
556 hook on ^(add|use) pad 0 0 0 26
558 For now, only Musca commands trigger hooks. In the future this may be
560 extended to add hooks to X events.
561
564 Stacking window management mode is available at the window group level,
565 on a group by group basis. Select the group you wish to make stacking,
566 and press 'Modifier+s' or run the command 'stack on'. Any frames in the
567 group will disappear. Other groups will not be affected.
568 Floating windows can be moved using 'Modifier+Mouse1', i.e., hold down
570 the modifier key and click the left mouse button on the window and
571 dragging the mouse. Floating windows can be resized using 'Modi‐
572 fier+Mouse3' in the same fashion. Click-to-focus still works.
573 Most of the frame manipulation related key combinations and commands
575 are disabled in stacking mode. Note: there is no way to float specific
576 windows while in tiling mode.
577 To switch the group back to tiling mode, press 'Modifier+s' again or
579 run the command 'stack off'. The group frames will be recreated as they
580 were before the mode change.
581
584 In config.h there is an unmanaged_windows[] list of WM_CLASS names:
585 char *unmanaged_windows[] = { "trayer", "Xmessage", "Conky" };
587 Check out the xprop utility to find class names. Either change unman‐
589 aged_windows[] and recompile, or do on the fly in .musca_start with the
590 'manage' command. Note that any manage setting only takes effect for
591 subsequently opened windows.
592
595 dmenu(1), wmctrl(1)
596
598 Sean Pringle
599Musca April 10, 2009 musca(1)