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.

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