musca(1) Users Manual musca(1)NAMEmusca - A simple dynamic window manager
SYNOPSISmusca [OPTIONS]
DESCRIPTION
Musca is a simple dynamic window manager for X, with features nicked
from ratpoison and dwm.
Musca operates as a tiling window manager by default. It uses "manual
tiling", which means the user determines how the screen is divided into
non-overlapping frames, with no restrictions on layout.
Application windows always fill their assigned frame, with the excep‐
tion of transient windows and popup dialog boxes which float above
their parent application at the appropriate size. Once visible, appli‐
cations do not change frames unless so instructed.
Since not all applications suit tiling, a more traditional stacking
window manager mode is also available, allowing windows to float at any
screen location and overlap.
There are no built in status bars, panels, tabs or window decorations
to take up screen real estate. If the user wants any of these things,
there are plenty of external applications available to do the job. Win‐
dow decoration is limited to a slender border, which is coloured to
indicate keyboard focus.
Windows are placed in named "groups" which can be used in a similar
fashion to virtual desktops. Groups can be added and removed on the
fly, and each group has its own frame layout.
The excellent "dmenu" utility is being used to execute commands and
launch applications, and it can also act as a window and group
switcher. Basic EWMH support allows use of common panels, pagers and
the wmctrl utility.
Windows and frames are navigated and focused on any mouse button click,
including rolling the wheel, or alternatively driven entirely by the
keyboard. Simple key combinations exist for window switching, group
switching, frame control and screen switching.
For more information about Musca visit http://aerosuidae.net/musca.html
OPTIONS
These command line options are recognized by Musca:
-c [command]
Connect to a running instance of Musca and execute a single Musca command
supplied on the command line.
-i
Connect to a running instance of Musca and execute one or more EOL delimited
Musca commands supplied on stdin.
-s [path]
Override the "startup" setting by specifying a custom path to a configuration
file holding Musca commands to execute at startup.
-v
Report version number.
INITIALIZATION
During initialization, Musca will read the ~/.musca_start configuration
file or any other text file which was specified by the 'startup' set‐
ting in config.h during compilation.
The startup file should contain Musca commands one per line. Any com‐
ments must be on separate lines starting with hash (#). Blank lines are
acceptable.
For example:
manage off trayer
manage off Conky
screen 1
name bling
pad 0 0 0 32
exec trayer
exec conky
screen 0
add mail
add net
add work
use mail
exec firefox gmail.com
exec evolution
hsplit 1/2
set notify notify-send -t 3000 Musca "$(cat)"
Note that launching applications from the startup file is acceptable,
but can be of limited use if they have to start in more than one group.
The 'exec' command runs asynchronously, and if applications are slow to
create their windows, they may not necessarily appear in the expected
group. In this case, a better option is launching applications from
~/.xinitrc.
MUSCA COMMANDS
add <name>
create a new group called `name`, and switch to it.
alias <name> <command>
create a new Musca command.
bind <on|off> <Modifier>+<Key> <command>
bind a Musca command to a key combination with `on`, and remove it
again with `off`. If the argument to `off` is `all`, it clears the
bound key list. The `command` argument is only need for `on`.
border <on|off|flip>
(toggle) turn the current frame border on and off.
catchall <on|off|flip>
(toggle) set the current frame as a `catch-all`, where all new windows
will open.
client hints <on|off>
(toggle) whether to respect X size hints for the current application window,
such as PMinSize, PMaxSize, PResizeInc, PBaseSize, PAspect.
command
launch the dmenu Musca command input.
cycle <local> <next|prev>
cycle a hidden window into the current frame. `local` means
cycle over windows previously displayed in the current frame.
`next` or `prev` specify the direction, defaulting to next.
Both arguments are optional.
dedicate <on|off|flip>
(toggle) dedicate the current frame to the current application.
drop <name|nr>
delete a group by `name` or by `nr`.
dump <file>
export a description (group name and frame layout) of the current group to `file`.
exec <command>
execute as shell command.
focus <left|right|up|down> or <lfocus|rfocus|ufocus|dfocus>
change focus to a frame in the specified direction.
height <relative|pixel>
resize frame vertically.
hook <on|off> <name> <command>
bind a Musca command to a named hook.
hsplit <relative|pixel>
split frame horizontally.
kill <number|name>
politely close the client window via a close event. When the optional
argument `number` or `name` is given, kill the associated window,
otherwise kill the current frame. Press again to forcibly kill it.
load <file>
import a description from `file` into the current group.
manage <on|off> <name>
(toggle) set whether the window class called `name` is managed or ignored.
move <name|nr>
move the current window to the group called `name` or to the group `nr`.
If it's an unknown group, automatically creates the group `name` and then
moves the current window to that group.
name <name>
rename the current group.
only
remove all other frames except the current one, resizing it to full screen.
pad <left> <right> <top> <bottom>
set the current group screen padding in pixels.
quit
exit Musca.
raise <number|title>
raise and focus a window in the current group by number (order opened) or
title.
remove
remove the current frame and resize others to fill the gap.
resize <left|right|up|down>
resize the current frame in the specified direction.
run <file>
execute a file consisting of Musca commands. The file must contain
one command per line. Lines starting with hash *#* are comments and
blank lines are acceptable.
say <text>
display text via the method in the 'notify' setting.
screen <number>
switch to screen `number`. This is zero based, and should match the order
in which screens are defined in "xorg.conf".
set <setting> <value>
set a Musca variable. See SETTINGS for a list of variable names.
shell
launch the dmenu shell command input.
show <settings|bindings|unmanaged|hooks|groups|frames|windows|aliases>
output a system table for diagnostic purposes.
shrink <number|title>
Minimize/Iconify (same thing in Musca) a window.
slide <left|right|up|down> or <lslide|rslide|uslide|dslide>
move current window into the frame to the left, right, up and down respectively.
stack <on|off|flip>
(toggle) switch the current group between `tiling` and `stacking` window modes.
swap <left|right|up|down> or <lswap|rswap|uswap|dswap>
swap current window with the contents of the frame to the left, right, up
and down respectively.
switch <window|group>
launch the dmenu window or group switcher.
undo
revert the last frame layout change.
use <name|number|(other)|(prev)|(next)>
switch to a group called by its `name` or to a group by its `number`.
`name` has precedence over `number`. If it's an unknown group, automatically
creates the group `name` and then switch to that group.
When `(other)`, `(prev)` or `(next)`, switch to the previously focused, previous
or next group respectively.
vsplit <relative|pixel>
split frame vertically.
width <relative|pixel>
resize frame horizontally.
Notes:
Any Musca command may be prefixed with "silent" to prevent any messages
being sent to the notify setting. This is useful for scripting, to pre‐
vent popup window noise.
Example:
musca-c "silent show groups"
Relative values can be specified as a percentage or a fraction:
Examples:
hsplit 2/3
hsplit 33%
SETTINGS
border_catchall_focus
Type: string
Default: Green
Border colour for focused `catchall` frames in tiling mode.
border_catchall_unfocus
Type: string
Default: Dark Green
Border colour for unfocused `catchall` frames in tiling mode.
border_dedicate_focus
Type: string
Default: Red
Border colour for focused `dedicated` frames in tiling mode.
border_dedicate_unfocus
Type: string
Default: Dark Red
Border colour for unfocused `dedicated` frames in tiling mode.
border_focus
Type: string
Default: Blue
Border colour for focused frames in tiling mode, and focused
windows in stacking mode.
border_unfocus
Type: string
Default: Dim Gray
Border colour for unfocused frames in tiling mode, and unfocused
windows in stacking mode.
border_width
Type: integer
Default: 1
Width in pixels of frame borders in tiling mode, and window bor‐
ders in stacking mode. The minimum value is 0, which makes frame
borders invisible.
command_buffer_size
Type: integer
Default: 4096
Size in bytes of the allocated buffer for passing commands and
results to and from "musca -c" and "musca -i".
dmenu
Type: string
Default: "dmenu -i -b"
Command to run to launch 'dmenu' along with any customize
appearance arguments. This can be replaced by another launcher
so long as it accepts a list of \n terminated items on stdin and
returns a single line on stdout.
focus_follow_mouse
Type: boolean
Default: 0
(toggle) Set to 1 to enable.
frame_display_hidden
Type: integer
Default: 1
When set to "0", empty frames will stay empty until a window is
manually selected. When set to "1", empty frames will automati‐
cally display the first available hidden window. When set to
"2", empty frames will automatically display only windows previ‐
ously displayed in this frame.
frame_min_wh
Type: integer
Default: 100
Minimum width and height in pixels of frames and managed win‐
dows.
frame_resize
Type: integer
Default: 20
Size in pixels of a frame resize step. Setting this smaller will
make resizing operations smoother, but also slower and increase
load.
frame_split_focus
Type: string
Default: current
Where focus should go when splitting a frame. When set to "cur‐
rent", focus remains to the current frame. When set to "new",
the new frame receives the focus.
group_close_empty
Type: boolean
Default: 0
When set to "1" and navigating away from an empty group, auto‐
matically drop this group.
notify
Type: string
Default: "echo `cat`"
The command to run to send the user a message. By default Musca
just writes to stdout.
notify_buffer_size
Type: integer
Default: 4096
Size in bytes of the allocated buffer for passing messages to
the command defined in the 'notify' setting.
run_musca_command
Type: string
Default: "$MUSCA -i"
The command to run when the user has entered a Musca command via
'dmenu'.
run_shell_command
Type: string
Default: "sed 's/^/exec /' | $MUSCA -i"
The command to run when the user has entered a shell command via
'dmenu'.
stack_mouse_modifier
Type: string
Default: Mod4
The modifier key to use in `stacking` mode, along with mouse
buttons 1 and 3, to move and resize windows respectively.
startup
Type: string
Default: ~/.musca_start
(optional) Path to a file containing Musca commands to run at
start up. The default setting is relative to the working direc‐
tory, i.e., Musca will use "$HOME/.musca_start" only if Musca is
started from $HOME, which is the usual method for login man‐
agers. The file must contain one command per line. Lines start‐
ing with hash *#* are comments and blank lines are acceptable.
switch_group
Type: string
Default: "sed 's/^/use /' | $MUSCA -i"
The command to run once the user has selected a group name from
'dmenu'.
switch_window
Type: string
Default: "sed 's/^/raise /' | $MUSCA -i"
The command to run once the user has selected a window number
and name from 'dmenu'.
window_open_focus
Type: boolean
Default: 1
(toggle) Set to 0 to prevent new windows from taking the input
focus.
window_open_frame
Type: string
Default: current
When set to "current", new windows always open in the currently
focused frame. When set to "empty", new windows will try to find
an empty frame to use.
window_size_hints
Type: boolean
Default: 1
(toggle) Set to 0 to disable size hints checks for new windows.
This can still be overridden on a per client basis using the
client command.
USAGE
Default Keyboard commands
Mod4+h hsplit 1/2
Mod4+v vsplit 1/2
Mod4+r remove
Mod4+o only
Mod4+k kill
Mod4+c cycle
Mod4+w switch window
Mod4+g switch group
Mod4+x shell
Mod4+m command
Mod4+d dedicate flip
Mod4+a catchall flip
Mod4+u undo
Mod4+s stack flip
Mod4+Left
focus left
Mod4+Right
focus right
Mod4+Up
focus up
Mod4+Down
focus down
Mod4+Next
use (next)
Mod4+Prior
use (prev)
Mod4+Tab
screen (next)
Mod4+Control+Left
resize left
Mod4+Control+Right
resize right
Mod4+Control+Up
resize up
Mod4+Control+Down
resize down
Mod4+Shift+Left
swap left
Mod4+Shift+Right
swap right
Mod4+Shift+Up
swap up
Mod4+Shift+Down
swap down
Mouse commands
Mod4+Button1
Moves a window in stacking mode.
Mod4+Button3
Resizes a window in stacking mode.
HOOKS
Executing Musca commands can optionally trigger a hook command. This
can be useful for chaining Musca commands together or firing off
scripts on certain events. For example, set default new group padding
by hooking into the add command:
hook on ^add pad 0 0 0 26
Or, attach to multiple commands:
hook on ^(add|use) pad 0 0 0 26
For now, only Musca commands trigger hooks. In the future this may be
extended to add hooks to X events.
STACKING MODE
Stacking window management mode is available at the window group level,
on a group by group basis. Select the group you wish to make stacking,
and press 'Modifier+s' or run the command 'stack on'. Any frames in the
group will disappear. Other groups will not be affected.
Floating windows can be moved using 'Modifier+Mouse1', i.e., hold down
the modifier key and click the left mouse button on the window and
dragging the mouse. Floating windows can be resized using 'Modi‐
fier+Mouse3' in the same fashion. Click-to-focus still works.
Most of the frame manipulation related key combinations and commands
are disabled in stacking mode. Note: there is no way to float specific
windows while in tiling mode.
To switch the group back to tiling mode, press 'Modifier+s' again or
run the command 'stack off'. The group frames will be recreated as they
were before the mode change.
Make Musca ignore windows
In config.h there is an unmanaged_windows[] list of WM_CLASS names:
char *unmanaged_windows[] = { "trayer", "Xmessage", "Conky" };
Check out the xprop utility to find class names. Either change unman‐
aged_windows[] and recompile, or do on the fly in .musca_start with the
'manage' command. Note that any manage setting only takes effect for
subsequently opened windows.
SEE ALSOdmenu(1), wmctrl(1)AUTHORS
Sean Pringle
Musca April 10, 2009 musca(1)
