cow - Man Page

Unless overridden with -c or $COW_CONFIG, the configuration file is located by searching the following paths in order, stopping at the first that exists:

1. $COW_CONFIG
2. ~/cow.conf
3. $XDG_CONFIG_HOME/cow/cow.conf
4. ~/.config/cow/cow.conf
5. /<PREFIX>/etc/cow/cow.conf

The configuration file is plain text. Each line is a cow command, using the Lines beginning with # are comments.  A backslash (\) at the end of a line continues the command on the next line.

Example:

  # This is a comment which cow ignores.
  set border 10
  set border_style fvwm

# This command is split over multiple lines for clarity.
bind \
    L+Return \
    exec foot

Most commands have a target on which the command is going to operate on, and for consistency across those commands, that is the `-t` flag.  The same concept exists for for a source window, via `-s`.

The format for both is the following:

That is to say, there's three components -- the delimiters between the parts are literal and must be specified:

output

Output name, @next, or @prev.

desk

Desk number (0-9), @next, or @prev.

window

One of:

• %app_id - match by app_id
• /substring/ - match by title substring
• #id - match by River identifier
• @focused - the currently focused window (default)
• @next - next window in stacking order
• @prev - previous window in stacking order

In the case of using a substring, this is run through `fnmatch(3)`

Key bindings are specified as a modifier string immediately followed by + and a keysym name, or - and a numeric keycode:

  bind MODIFIERS+keysym  command
  bind MODIFIERS-keycode command

-r

Mark the binding as repeatable.  While the triggering key is held the action re-fires every repeat_interval_ms milliseconds after an initial repeat_delay_ms dwell (see set).

Modifier characters:

Modifiers are combined by concatenation: LS means Logo+Shift, LCA means Logo+Control+Alt. Use 0 to specify no modifier.

Key symbols and codes can be determined with wev(1).

Examples:

  bind L+Return     exec xterm
  bind LS+a         winops -c
  bind LCA+q        quit
  bind 0+F1         action-help
  bind -r L+Right   scroll -n           # hold Super+Right to keep paging

Mouse bindings use the same modifier format as the bind command. The button name replaces the keysym:

  mouse MODIFIERS+button command

Button names: left, right, middle, side, extra, forward, back, task.

Bind a pointer button combination to a command. The key format is the same as for bind, but the key name is a button name (see MOUSE BINDINGS).

Example:

  mouse L+left   window-move
  mouse L+right  resize
  mouse L+middle window-move -C

Bind a primary-button click on a window's decoration to a command.  Each window's frame is divided into regions.  See the ANATOMY_OF_A_WINDOW section.

When a bound region of the window is clicked on, the attached action runs against that window.

-2

Double-click binding (default is single-click).  A region can carry one single-click binding and one double-click binding simultaneously.

The region argument is case-insensitive and accepts both the compass shorthands and the long form:

The defaults bindings are:

Double-clicks on edges and corners have no defaults.

Limitation: River does not expose which button was used when clicking on the window decoration, so currently, only mouse button 1 is usable.

Examples:

  # Maximise a window by clicking anywhere on its titlebar
  # (replaces the default window-move).
  bind-decoration titlebar window-maximize -m

# Re-express the default double-click-shade explicitly.
bind-decoration -2 titlebar window-shade -d north

# Maximise on a click on the north edge.
bind-decoration N window-maximize -m

# Double-click NE corner closes the window (the single-click default
# of starting a corner resize still fires on the first click; bind
# the single-click pair too if you want to suppress it).
bind-decoration -2 NE    winops -c

# Chain: start a resize then focus the next window.
bind-decoration SE       window-resize -e se ; focus -n

Apply rules (groups of commands) to certain conditions (events).

A rule has a name (via `-n`) which must be specified.  Note that rules are globally stored, so any conflicting names will mean that rule is replaced.  It also has a type (via `-T`) which specifies when to run the rule.  Multiple rules can be defined against the same type as long as their names are distinct.

The following table shows which events are available:

Specificity of rules are such that global rules (via `-g`) run before any specific defined rules.  For example:

  # Define a global rule -- this will always run.
  rule -g -Ton-map -ng-on-map exec notify-send "A window has appeared."

# Define a rule to change a window property when windows appears on desk 2
rule -t :2 -Ton-map -ndesk2 
	set titlebar.active_colour 0xFF8C00 ; 
        set titlebar.inactive_colour 0xB28E4C ; 
        set colour.inactive 0xB28E4C

Rules can be deleted with the `-d` option.  Additionally, `-n` is needed to specify the name, example:

  rule -d -ndesk2

Defined rules can be seen with the show command.

Execute a shell command. During configuration loading, exec commands are deferred until cow has fully connected to River.

Query window manager state. The response is a JSON object. When used via moocow(1) the JSON is printed to standard output.

Topics:

show windows

Return an array of all managed windows. Each element contains: id, app_id, title, desk, x, y, width, height, focused, maximized, shaded, iconified.

show desk

Return {"current": N} for the current output's active desk.

show rules

Return an array of all defined rules.

show output

Return an array of output objects, each with name, x, y, width, height, and a usable sub-object reflecting reserved areas.

show config key

Return the current value of a configuration key. Supported keys: border, step, corner_length, border_style, focus. Also accepted as show config.key.

Without any options, cow quits. With -r, reload the configuration from the file cow was started with, instead of quitting.

Keybindings and window decorations are updated immediately on reload.

Return a JSON array of all registered commands, each with name and usage fields.

Set a configuration option at runtime. -v prints the resulting value.

The specific keys/values for this command are detailed under relevant section in this man page.

Operate on a window.

-t target

Target window (see Command Referencing). Defaults to the focused window.

-I

Identify the window; returns a JSON object with geometry and state.

-c

Close the window.

-r

Raise the window to the top of the stacking order within its layer.  See Layers below for the cross-layer invariant.

-l

Lower the window to the bottom of the stacking order within its layer.

-s

Toggle desk-sticky: window appears on all desks.

-S

Toggle page-sticky: window appears on all pages of the current desk. Combine -s and -S for fully sticky (all desks and pages).

-i

Toggle the window's iconified (minimised) state.

-L layer

Set the window's layer (see Layers).  Accepted forms:

• N -- absolute layer (clamped to [0, max_layer]).
• =N -- absolute layer, explicit (never toggles).
• +N / -N -- relative bump, clamped at edges.
• top -- shorthand for max_layer; toggles back to default_layer when the window is already at max_layer.
• bottom -- shorthand for 0; toggles back to default_layer when the window is already at 0.
• =top / =bottom -- non-toggling variants; useful inside rules so a re-map event doesn't accidentally revert the layer.

Container members share a single layer: setting -L on any member updates every member of the container.

Move a window. With no flags, begin an interactive move using the mouse.

-t target

Target window.

-d dir

Move one step in direction dir (up, down, left, right).

-n

With -d, snap to the nearest edge instead of stepping.

-o output

Move the window to the named output.

-C

Enable container-formation on drop. When the interactive move ends with the pointer over another window's titlebar, the two windows are grouped into a container instead of completing a normal move. Releasing over empty space performs a normal move. The target window's titlebar highlights in orange while the pointer is over it.

-P col [row]

Move the window to the page at column col, row row (0-indexed), preserving its within-page position.  row defaults to 0. Only meaningful when desktop_size is larger than 1×1.

-c

Centre the window on its current output.

-k 0-9

Move the window to desk number 0-9.

-x X

Set the window's X position. A leading + or - makes the value relative to the current position.

-y Y

Set the window's Y position. A leading + or - makes the value relative to the current position.

Resize a window. With no flags, begin an interactive resize operation with the mouse, from the bottom-right corner.

-t target

Target window.

-g -d dir

Grow the window in direction dir (up, down, left, right) by one step.

-s -d dir

Shrink the window in direction dir by one step.

-e edges

Begin an interactive resize anchored on the named edges -- a compass spec built from the letters n, s, e, w.  Single letters select an edge (n, s, e, w); two-letter combos select a corner (ne, nw, se, sw).  Used by bind-decoration to express per-edge / per-corner resize defaults as ordinary commands; default if -e is omitted is the historic se (bottom-right) corner.

-w width

Set the window width in pixels.

-h height

Set the window height in pixels.

Move keyboard focus.

-n

Focus the next window in stacking order.

-p

Focus the previous window in stacking order.

-w

Warp the pointer to the centre of the focused window after focus is applied. May be combined with any other focus flag. When used alone, warps to the currently focused window without changing focus.

-d dir

Focus the nearest window in direction dir (up, down, left, right).

-o output

Warp the pointer to the named output. The -w flag is ignored when -o is given, as -o performs its own pointer movement.

-A app_id

Focus the window with the exact app_id app_id.

-T pattern

Focus the window whose title contains pattern.

-i id

Focus the window with River identifier id.

-L

Restrict traversal to the focused window's layer (see Layers). Combine with -n, -p, or -d; standalone -L is an error. When no window is focused, the current layer is taken as default_layer.

-l N

Restrict to layer N.  Without -n or -p, focuses the topmost focusable window in layer N; if the focused window is already in layer N, cycles to the next focusable window in that layer.  Combine with -n/-p to walk only within N.  Mutually exclusive with -L.

Expand a window to fill available space between windows, or the whole monitor if the window is the only window on that monitor.

-t target

Target window.

-d dir

Expand in direction dir (up, down, left, right). Omit to expand in all directions.

-T

Toggle: restore original geometry if the window is already expanded.

Maximize or restore a window.

-t target

Target window.

-T

Toggle between maximized and restored.  Combined with -h / -v, toggles only that axis; toggling an unmaxed axis maximises it.

-m

Maximize the window (default if no flag is given).

-u

Restore (unmaximize) the window.  Combined with -h / -v, restores only that axis; a window can stay maximised on the other axis.

-h

Maximize horizontally only -- the window's width grows to the output's usable area.

-v

Maximize vertically only -- the window's height grows to the output's usable area.

Per-axis maximised state is independent: window-maximize -h followed by window-maximize -v leaves the window maximised on both axes, and each axis can be restored separately with -T -h and -T -v.

Examples:

  window-maximize        # full maximise
  window-maximize -T     # toggle full maximise
  window-maximize -h     # horizontal only
  window-maximize -v     # vertical only
  window-maximize -T -h  # toggle horizontal maximised state only
  window-maximize -u -v  # un-maximise vertical only, keep horizontal

Shade (roll up) a window in a given direction, hiding its content but leaving its border visible.

-t target

Target window.

-d dir

Shade direction: north, south, east, west, nw, ne, sw, se. Required.

window-container -a

Add source to target's container. If neither window is already in a container, a new container is created.

source defaults to the focused window. target defaults to the focused window when -t is given explicitly.

When neither -t nor -s is given, source is the focused window and target is the next focusable window in stacking order. This means container add with no arguments is a self-contained keyboard-only action: it groups the focused window with the one below it in the stack. This is useful in environments where mouse modifier combinations are unavailable (e.g. VNC).

window-container -r [-t target]

Remove target from its container. The detached window reappears offset from the container position. If the container drops to one member, the container is dissolved.

window-container -n [-t target]

Activate the next tab in the container that holds target.

window-container -p [-t target]

Activate the previous tab in the container that holds target.

window-container -N [-t target]

Move the tab containing target one position to the right in the tab strip. The tab remains active. No-op if it is already the last tab.

window-container -P [-t target]

Move the tab containing target one position to the left in the tab strip. The tab remains active. No-op if it is already the first tab.

See also window-move -C, which allows containers to be formed interactively by dragging a window's titlebar onto another. In environments where mouse modifier combinations are unreliable (e.g. VNC), bind container add to a key instead:

  bind L+g   window-container -a
  bind LS+g  window-container -r
  bind L+Tab window-container -n

The following options can be used with the set command to change the behaviour of containers:

Pan the virtual page viewport for the current desk.

Pages can be scrolled in either full pages, or part increments.  Additionally, it's possible to in-effect, "drag" the viewport with the mouse to any position.

In the deltas form (H V), H is the horizontal scroll and V the vertical.  By default each value is a percentage of one page in that axis: 100 is one full page right (or down), -100 one page left (or up), 50 is half a page, and so on.  With -p the values are raw pixels instead.

Options are:

-t output

Target the named output instead of the current one.

-w

Wrap at the desk edges.  Without -w, the viewport is clamped to the desk extent.  The legacy fvwm idiom of multiplying the percentage by 1000 (e.g. scroll 100000 0) is also recognised as an implicit -w.

-p

Treat H and V as pixels rather than percent of a page.

-a col,row

Absolute jump: land the viewport at the page col,row (0-indexed). The pair are a single comma-separated token.

-d dir

Jump one page in direction dir: left, right, up, or down, wrapping at desk edges.

-n

Next page (right, wrapping at the end of a row to the start of the next row).  Shorthand for scroll -w 100 0.

-P

Previous page (left, wrapping).

-r

Start an interactive drag-the-viewport pan.  The viewport follows the pointer until the triggering mouse button is released.  Only valid when invoked from a mouse or key binding. Bind it to a mouse button to "grab and drag" the desk.  The -w and -p flags are ignored with -r since interactive drag works in raw pixels and never wraps.

-R

Paired with -r, makes the viewport follow the pointer in the same direction instead of opposite.

Pages exist only when desktop_size N M is configured with N > 1 or M > 1.

Examples:

  # One full page right (clamps at the last column).
  scroll 100 0

# Half a page right, a quarter page down.
scroll 50 25

# 200 pixels right.
scroll -p 200 0

# One page right, wrapping at the desk edge.
scroll -w 100 0

# Jump straight to page (col=2, row=0).
scroll -a 2,0

# One page right, wrapping; convenient for keybindings.
scroll -d right

# Next / previous page with wrap.
scroll -n
scroll -P

# Bind Ctrl+Meta+Button1 to grab and drag the viewport.
mouse CM+left scroll -r

Switch or manipulate virtual desks.

-t output

Target the named output instead of the current one.

-d N

Switch to desk number N.

-n

Switch to the next desk, wrapping around.

-p

Switch to the previous desk, wrapping around.

-c N

Toggle collection of desk N: overlay its windows on top of the current desk without switching.

Manage the naming of virtual desktops.  By default, cow sets ten desktops, whose names default to '0'..'9'.  With this command it is possible to change that, either by increasing or decreasing the number of desktops, and/or renaming existing desks.

-t output

Target the named output instead of the current one.  In global desktop mode the operation is mirrored across every output.

N NAME

Ensure desk N exists and set its name to NAME.  Gaps below N are auto-filled with default-named desks.  Names must be non-empty, printable, and contain no whitespace or :; duplicates within one set are rejected.

-d N

Delete desk N.  Refused if any window is on it.

-l

List the current desks as JSON, per output.

-r

Reset every desk set to the default set, as if no manipulation had ever occurred.

The following examples show how this command can be used:

  # Three named desks instead of the default ten.
  desk-name 0 main
  desk-name 1 web
  desk-name 2 dev

# Now both forms select the same desk.
focus -t :main
focus -t :0

The minimum number of desks can be set with desks.count.   Note that it is possible with the desk-name command to name desks greater than desks.count number, and that this will effectively create this desk.

The following options can be used with the set command to change the behaviour of desktops and pages:

NOT£: The reserved. settings are akin to X11's concept of a working-area. That is to say, these settings will reserve parts of the screen to be able to put taskbars, etc.

The following options can be used with the set command to tune keybinding behaviour:

A binding registered without -r fires exactly once per press, regardless of either setting.