musca man page

musca — A simple dynamic window manager

Synopsis

musca [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 exception of transient windows and popup dialog boxes which float above their parent application at the appropriate size. Once visible, applications 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. Window 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' setting in config.h during compilation.

The startup file should contain Musca commands one per line. Any comments 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 prevent 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 borders 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 automatically display the first available hidden window. When set to "2", empty frames will automatically display only windows previously displayed in this frame.

frame_min_wh
Type: integer
Default: 100

Minimum width and height in pixels of frames and managed windows.

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 "current", 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, automatically 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 directory, i.e., Musca will use "$HOME/.musca_start" only if Musca is started from $HOME, which is the usual method for login managers. The file must contain one command per line. Lines starting 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 'Modifier+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 unmanaged_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 Also

dmenu(1), wmctrl(1)

Authors

Sean Pringle

Info

April 10, 2009 Musca Users Manual