DragonFly On-Line Manual Pages

musca(1) Users Manual musca(1)

NAME
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.

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.

shrink <number|title>
Minimize/Iconify (same thing in Musca) a window.

stack <on|off|flip>
(toggle) switch the current group between `tiling` and `stacking` window modes.

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.

DragonFly On-Line Manual Pages

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

INITIALIZATION

MUSCA COMMANDS

SETTINGS

USAGE

HOOKS

STACKING MODE

SEE ALSO

AUTHORS