cow - Man Page

A block contains zero or more statements; whitespace (including newlines) separates them.​

let NAME = EXPR

Bind NAME to the value of EXPR in the current scope.​ Names are visible to subsequent statements in the same block and to nested blocks.​

for NAME in (SOURCE [where EXPR]) { .​.​.​ }

Snapshot SOURCE at loop entry and execute the body once per matching element with NAME bound to the current record.​  SOURCE is one of windows, desks, outputs (or screens), rules.​  An optional where clause filters the snapshot with the supplied expression (evaluated per element with NAME in scope).​  The body sees a fresh sub-scope; let bindings inside the body don'​t leak out.​

if EXPR { .​.​.​ } [else { .​.​.​ } | else if .​.​.​ ]

Branch on the truthiness of EXPR (numbers are false when zero; strings are false when empty; lists are false when empty; records are always true; nil and false are false).​

break

Exit the nearest enclosing for loop.​

continue

Skip to the next iteration of the nearest enclosing for loop.​

COMMAND [ARGS .​.​.​]

Invoke any registered cow command.​  Each argument is either a raw text chunk (passed verbatim) or an interpolation of the form #{EXPR} which is replaced with the stringified result before the command runs.​

The expression language has no arithmetic; it covers what'​s needed to choose work to do.​

For example, match every named cowiconman instance on a particular output:

  if self​.title matches "cowiconman:*" and self​.output == "eDP-1" {
  	# commands
  }

Each iterable source yields records whose fields match the corresponding show -a topic JSON (see show -a window, show -a desk, show -a output, and show -a rule).​ Common window fields include id, app_id, title, desk, output, layer, focused, iconified, circulate_skip, maximized, width, height, page_col, page_row, current_page, current_desk, current_output, sticky_desk, sticky_page, border_width, title_thickness, squeeze, and squeezed_rect.​ Common desk fields include nr, name, output, current, active, collected, window_count, page_col, page_row, page_cols, page_rows, page_vx, and page_vy.​  Common output fields include name, number, geometry, usable geometry, current, current_desk, current_desk_name, and page state.​  Common rule fields include name, type, global, output, desk, match, and body.​

For window records, current_page is relative to that window'​s output.​ Use current_output and current_page when matching windows only on the current output'​s current page.​

Inside a rule body, the identifier self resolves to a record for the event'​s target view; outside a rule body it is unbound.​

Tint titlebars of windows promoted to the top layer:

  decor -d top-tint titlebar​.active_colour 0xC04030
  decor -d normal-tint titlebar​.active_colour 0x303030
  rule -g -n top-tint -T on-layer-change script {
      if self​.layer == 16 {
          decor -a top-tint
      } else {
          decor -a normal-tint
      }
  }

Move every mpv window to the top layer:

  script {
      for w in (windows where w​.app_id == "mpv") {
          winops -t #{w​.id} -L =top
      }
  }

Iconify every window not on the currently-focused desk:

  script {
      for w in (windows where w​.focused != true and w​.iconified != true) {
          winops -t #{w​.id} -i
      }
  }

When cow starts, for the output (screen) HDMI-A-1, set every desk to start on page 1,1:

  rule -g -T on-start -n startup-pages script {
      let output = "HDMI-A-1"
      for d in (desks where d​.output == output) {
          desk -t ​'#{output}​' -d #{d​.nr}
          scroll -t ​'#{output}​' -a 1,1
      }
  }

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

The include command reads additional commands from another file.​  Absolute paths are used as-is, paths beginning with ~/ are resolved relative to $HOME, and other relative paths are resolved relative to $XDG_RUNTIME_DIR.​

Example:

  # This is a comment which cow ignores​.
  decor -d default border​.width 10
  decor -d default border​.style fvwm
  decor -a default

# 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, @N by output number, @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
  bind CONTEXTS:MODIFIERS+keysym command
  bind MODIFIERS+keysym,MODIFIERS+keysym command

Without a context prefix the binding is global.​  A context-qualified binding is enabled only while the pointer is in one of its regions.​  If the same key has both global and matching contextual bindings, the contextual binding wins; the global binding is the fallback.​

For overlapping contextual bindings, the most specific context wins.​

Context characters:

• A: any context (equivalent to omitting the prefix).​
• R: output background (root).​
• W: application window content.​
• I: an iconified-window icon.​
• 0 to 9: the corresponding titlebar button.​

Multiple characters combine regions.​  The context window becomes the command'​s default target, making window commands act on the window under that region rather than whichever window was previously focused.​

-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).​

-d pattern

Remove configured keyboard bindings whose complete key specification matches the shell-style pattern.​  Quote patterns in configuration files, for example bind -d "L+[0-9]".​  This is useful before regenerating a group of bindings from a script.​

-x action

Perform this action after the key and every modifier named by the binding have been released.​ The definition still requires a key-press action (even if nop).​ This allows a menu opened by A+Tab, for example, to remain open through repeated Tab presses and be destroyed when Alt is released:

  bind -x "menu-destroy AllWindows" A+Tab menu-show AllWindows

All bind options must appear before the key specification.​ On versions of the River XKB bindings protocol before version 3, modifier release cannot be observed, so the action instead runs when the main key is released.​

Modifier characters:

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

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

Separate keys with commas to define a chorded binding.​  Every key except the last is a prefix: pressing it temporarily replaces the normal key bindings with the bindings below that prefix.​  A matching key continues the sequence; the final key executes the command and restores the normal bindings.​  An unmatched non-modifier key, including Escape unless explicitly bound, is consumed and cancels the sequence.​

Prefixes are shared, so several bindings may begin with the same keys:

  bind C+c,C+a window-move -x 0 -y 0
  bind C+c,C+i winops -i
  bind C+c,C+c winops -c
  bind C+x,0+4,C+f window-maximize

Only the first key may have a binding context.​  Its context window remains the default command target throughout the sequence.​  A key cannot be both a complete binding and a prefix.​  The -r and -x options apply to the final key.​  Chorded bindings require version 2 or newer of River'​s XKB bindings protocol.​

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
  bind R:L+Return   exec xterm          # only over the background
  bind I:0+Return   winops -i           # restore the icon under the pointer
  bind 0:L+Return   window-maximize     # over titlebar button 0

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

  mouse MODIFIERS+button command
  mouse CONTEXTS: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).​ The optional contexts and their precedence are the same as for bind.​ Contextual commands target the window under the pointer.​ A matching contextual mouse binding consumes the click before normal pointer interaction, so it overrides a bind-decoration action or titlebar-button action in that region.​  Without a matching binding, the normal decoration or client click behaviour is unchanged.​

In addition to the contexts accepted by bind, mouse bindings accept these non-button SSD decoration contexts:

• T: window titlebar, excluding its buttons.​
• [, ], -, : left, right, top, or bottom frame border.​
• S: any frame side; equivalent to []-.​
• <, ^, >, v: northwest, northeast, southeast, or southwest frame corner.​
• F: any frame corner; equivalent to <^>v.​
• R: "root window" (output background)

Multiple characters combine regions, so TF: applies to the titlebar or any frame corner.​

Example:

  mouse L+left   window-move
  mouse L+right  resize
  mouse L+middle window-move -C
  mouse T:0+left window-move
  mouse <:0+left window-resize -e nw
  mouse ]:0+left window-resize -e e
  mouse I:0+left winops -i
  mouse R:0+left menu-show RootMenu

The R context applies to cow'​s output background surface and does not capture clicks on client windows.​  It supports the same buttons and modifiers as other mouse contexts and is useful for root-window style menus.​  See the MENU section for more information.​

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 default bindings are:

Double-clicks on edges and corners have no defaults.​

If a button has both single- and double-click bindings, CoW waits until the double-click interval has elapsed before running the single-click action.​  A second click on the same button runs only the double-click action.​  Other decoration regions retain immediate press-and-hold handling for interactive move and resize actions.​

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 titlebar

# 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

# Button 0 toggles vertical maximisation on one click and full
# maximisation on two clicks​.
bind-decoration 0       window-maximize -T
bind-decoration -2 0    window-maximize -m

# 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 will be rejected.​ 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
decor -d desk2 titlebar​.active_colour 0xFF8C00
decor -d desk2 titlebar​.inactive_colour 0xB28E4C
decor -d desk2 border​.inactive 0xB28E4C
rule -t :2 -Ton-map -ndesk2 decor -a desk2

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

Define states for windows.​  Styles reuse the same names, scopes, and selectors as rules, but describe window state rather than executing commands in response to an event.​  Styles can override one another, the last match wins, with theat style overriding any previous properties within it/

The selector forms are the same as for rule: %app-id, /title/, and #identifier.​  A global style uses -g.​  With -t output[:desk], either part may be omitted to match any output or desk.​

The following properties are reapplied when a window'​s title or scope changes and when the configuration is reloaded:

These placement and state properties apply only when the window is first managed.​  They are not replayed by a configuration reload or title change:

Styles are resolved before an event rule is executed.​  If a rule or later targeted command changes a live style field, that field becomes an explicit per-window override and is not subsequently replaced by style recomputation.​

For example, give terminals a reusable base theme with a local border change, keep them in the normal layer, and initially place them on the left half of the work desk:

  style -g -n terminal -s %foot {
      decor motif
      decor {
          border​.width 4
          titlebar​.active_colour 0x303030
      }
      layer 4
      circulate​.skip false
      placement​.desk work
      placement​.x 0vw
      placement​.y 0vh
      placement​.width 50vw
      placement​.height 100vh
  }

An event rule can then make a particular terminal an explicit exception:

  rule -g -T on-map -n build-log -s ​'/build log/​' script {
      winops -L =top
      decor -a alert
  }

Delete a style with style -d -n name.​

Styles can be inspected with the show style name and show -a style commands.​

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

Start an interactive pointer drag.​  On button release, run command and apply the drawn frame to the first newly mapped window which matches expr.​  Without -F, the first newly mapped window consumes the frame.​

The command is parsed as a CoW command, so launching an application usually uses exec:

  mouse M+left draw-exec exec foot
  mouse M+middle draw-exec -F ​'self​.app_id == "foot"​' exec foot

If the command is a brace-delimited script block, the surrounding braces are removed before the block is evaluated.​

Query window manager state and configured objects.​ Without -a, a topic returns one current or named record.​ With -a, it returns an array containing all records for that topic.​ When used via moocow(1), JSON is printed to standard output.​

-a

Return all records for the topic.​ This is supported by window, output, desk, rule, style, decor, menu, binding, and command.​ It cannot be combined with -t or a resource name.​

-f format

Select the output format.​ json is the default.​ config emits commands accepted by cow.​conf and is available for config, rule, style, decor, menu, and binding.​ With -a, filters are applied before the collection is serialized.​

-t target

Select the resource returned by show window, show output, or show desk.​ It uses the normal command context syntax described in Command Referencing.​ Without -t, the focused window, current output, or current desk is used respectively.​

-F expr

Filter a topic selected with -a using a DSL expression.​ self is bound to each candidate record.​ A query with no matches returns an empty array.​ -F requires -a.​

Topics:

show window, show -a window

Return the target managed window or all managed windows.​ Window records include identity, content and frame geometry, icon geometry, placement, page state, stacking state, window flags, decorations, size hints, and per-window style fields.​

Examples: show window show -t '​#0123abcd'​ window show -a -F '​self.​current_page and not self.​iconified'​ window

show output, show -a output

Return the target output or all outputs.​ Output records contain name, number, geometry, usable geometry, current desk, and page state.​

Examples: show -t @2 output show -a -F '​self.​current'​ output

show desk, show -a desk

Return the target desk or all desks on every output.​ Desk records contain their number, name, output, page state, collection state, and window count.​

Examples: show -t HDMI-A-1:2 desk show -a -F '​self.​output == "HDMI-A-1"'​ desk

show rule name, show -a rule

Return one exactly named rule or all rules.​ Rules can be filtered by fields such as name, type, global, output, desk, and match.​

Example: show -a -F '​self.​type == "on-map"'​ rule

show style name, show -a style

Return one exactly named style or all styles.​  Records contain the shared rule-style scope and selector fields plus the style body.​

Examples: show style terminal show -a -F '​self.​global'​ style show -a -f config style

show decor name, show -a decor

Return one exactly named decoration profile or every profile.​ Each profile contains its name, whether it is globally active, and its sparse settings object.​ The collection may be filtered with -F.​

Examples: show -a decor show decor fvwm show -a -F '​self.​active'​ decor

show menu name, show -a menu

Return one named menu or every menu definition.​ Records contain the selection modes, resolved style, and ordered item definitions.​

Examples: show menu RootMenu show -a menu

show -a binding

Return every keyboard, mouse, and decoration binding.​ Bindings have no singular selector.​ The type field is keyboard, mouse, or decoration; -F can select one kind.​

Example: show -a -F '​self.​type == "keyboard"'​ binding

show command name, show -a command

Return one named command or every registered command with its name and usage.​ This replaces the former list-commands command and supports filtering with -a -F.​

show keyboard-layout

Return the active keyboard layout'​s name, caps_lock, num_lock, and scroll_lock states, or null if no layout is set.​ A lock state is null until River has reported it.​

show config [key]

With no key, return all serializable configuration grouped into commands, settings, decor, menu_style, menus, bindings, rules, and styles.​ The commands array is the ordered, directly reusable configuration record.​ With a key, return only that setting.​ Supported setting keys: border.​width, step, border.​corner_length, border.​style, focus, geometry_window, clamp_mode, placement, page and edge-scroll settings, titlebar.​font, title_format, cursor and repeat settings, default_layer, max_layer, preserve_desk_on_output_loss, and desks.​count.​ With desks.​count, -t may select the output to inspect.​

Examples: show config show config border.​width show -t @2 config desks.​count show -f config config show -a -f config binding

The config form of show config is built from the successful persistent commands seen while loading the configuration and from later configuration changes made through moocow(1).​ This includes settings, decorations, bindings, menus, rules, icon placement and startup exec commands without relying on a separate list of setting names.​ Per-window commands fired by rules are session state and are not included.​

moocow(1) prints this form without a JSON envelope, so it can be written directly:

  moocow show -f config config > cow​.generated​.conf

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

Read and execute commands from file.​  Absolute paths are used as-is, ~/ is resolved relative to $HOME, and other relative paths are resolved relative to $XDG_RUNTIME_DIR.​

Set the active XKB layout on every keyboard.​ NAME must match a descriptive layout name in the keyboard'​s current keymap.​ River ignores a name which does not exist.​

  keyboard-layout ​'English (UK)​'

Do nothing.​

Define or replace one key in a named, sparse decoration profile.​  The key is a decoration key without the set prefix.​

  decor -d alert border​.width 8
  decor -d alert titlebar​.active_colour 0xC04030
  decor -d alert border​.inactive 0x303030

Theme packs can be split into files and loaded with include, for example:

  include themes/fvwm
  decor -a fvwm

Titlebar buttons may set their face and vector foreground colours separately for focused and unfocused windows:

  decor -d motif titlebar​.button​.0​.active_colour 0xC0C0C0
  decor -d motif titlebar​.button​.0​.inactive_colour 0xC0C0C0
  decor -d motif titlebar​.button​.0​.active_fg 0x000000
  decor -d motif titlebar​.button​.0​.inactive_fg 0xFFFFFF

The foreground properties affect native vector buttons.​ Image buttons render the colours contained in the image itself.​

Image values in a profile may name PNG, SVG, or XPM files.​  Relative image paths are resolved against the file containing the decor -d command, so a theme directory can keep its config and image assets together.​

XPM support covers the XPM3 format, including transparent None pixels, hexadecimal colours, the basic named colours, and gray0 through gray100 (also spelled grey).​

Apply a named decoration profile.​  Switching to a different global profile, or applying a profile to an explicit target, resets the target decoration to the base defaults before applying the profile entries.​  Reapplying the active global profile patches the current decoration in place.​  Profiles containing only icon.​* keys also patch in place.​  Profiles applied by rules are overlays, so layered rules can compose sparse profiles.​

With -t, the target is that window.​  Without -t, the target is the global decoration defaults and existing windows.​  Rule bodies use the rule'​s default window target.​

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

However, there are global settings which don'​t fit into other command settings.​ These are listed below:

Operate on a window.​

-t target

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

-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.​ When enabled for a window on another page, the window is first moved to the current page while retaining its within-page position.​ Combine -s and -S for fully sticky (all desks and pages).​

-i

Toggle the window'​s iconified (minimised) state.​ Click an iconified window to restore it; drag it to remember a manual icon position for later iconify operations.​

-C on|off|toggle

Set, clear, or toggle CirculateSkip.​  Skipped windows are ignored by focus -n, focus -p, @next, and @prev; explicit focus and mouse focus still work.​

CirculateSkip is window state.​  Once set, it applies to ordinary next/previous circulation regardless of which key binding or command started the focus change.​  This is useful for panels, pagers, docks, and other utility windows which should generally remain reachable by direct focus, but not appear in normal circulation.​

-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 a rule command.​

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.​ It may be combined with -w as -nw.​

-w

Warp the pointer to the centre of the moved window after a non-interactive move.​ This is independent of -n: -w follows a stepped move, while -nw follows a snapped move.​ No warp is performed when the moved window is not visible on its destination.​

-o output

Move the window to the named output or output number (@N).​ May be combined with -k to land the window on a specific desk of that output; other flags (-d, -c, -x, -y, -P) are rejected when given with -o.​

-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.​ Negative indices count from the end of the corresponding axis.​ A signed value suffixed with p is relative to the window'​s current page, for example -P +1p,+0p moves it one page to the right.​ row defaults to 0.​

Only meaningful when desktop_size is larger than 1x1.​

-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.​ A value suffixed with vw is a percentage of the current output'​s usable width; an absolute vw position places the outer frame relative to the usable area'​s left edge.​

-y Y

Set the window'​s Y position.​ A leading + or - makes the value relative to the current position.​ A value suffixed with vh is a percentage of the current output'​s usable height; an absolute vh position places the outer frame relative to the usable area'​s top edge.​

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|automatic

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.​  With automatic, the pointer position in the target window'​s 3x3 grid selects the corresponding edge or corner.​  No resize starts from the centre cell or when the pointer is outside the target window.​  If border.​resize is configured, the selected borders use that colour until the operation ends.​  This visual feedback applies only when -e is present.​

-W

Warp the pointer to the selected border before starting an interactive resize.​  On a single edge, its position along that edge is retained; at a corner, it is warped to the corner.​  This can be combined with either an explicit -e direction or -e automatic.​

-w width

Set the client width in pixels.​ A value suffixed with vw sets the outer frame width to that percentage of the current output'​s usable width, accounting for borders and titlebar.​

-h height

Set the client height in pixels.​ A value suffixed with vh sets the outer frame height to that percentage of the current output'​s usable height, accounting for borders and titlebar.​

Viewport units may contain decimals.​ For example, these bindings place the focused window in the left half and bottom-right quarter respectively:

  bind L+Left  window-move -x 0vw -y 0vh ; window-resize -w 50vw -h 100vh
  bind L+3     window-move -x 50vw -y 50vh ; window-resize -w 50vw -h 50vh

Automatic resize direction works identically with keyboard and mouse bindings.​  The first example also warps the pointer to the chosen border:

  bind L+r       window-resize -e automatic -W
  mouse L+right  window-resize -e automatic

Move keyboard focus.​

-n

Focus the next window in stacking order.​

-p

Focus the previous window in stacking order.​

-F expr

Restrict -n and -p circulation with a DSL expression.​  self is bound to each candidate window.​  CirculateSkip still applies, so utility windows marked with winops -C on are skipped independently from the expression.​

The filter is local to this focus invocation.​  Use it for predicates which are part of a particular focus action, such as limiting circulation to the current output and page.​  Use winops -C instead when a window should be skipped by normal circulation in general.​

Examples:

• focus -nw -F '​self.​current_output and self.​current_page'​
• focus -nw -F '​self.​current_desk'​
• focus -nw -F '​self.​current_output'​
• focus -nw -F '​self.​current_output and self.​current_page and self.​app_id not in ["cowpager"]'​
• focus -nw -F '​self.​current_output and self.​current_page and self.​app_id not in ["cowpager", "appA", "appB"]'​

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

Open a transient list of managed windows, centred on the target output unless -p is used.​  Press 1 through 9, or 0 for the tenth entry, to select immediately.​  For longer lists use the arrow keys and Enter.​  Typing letters performs an incremental, case-insensitive filter over the displayed labels; only matching windows remain visible and the first match is selected.​ Backspace removes the last search character and expands the list again.​

Selecting an entry closes the list, switches to its output, desk, and page, restores it if iconified, activates its container tab if necessary, and focuses it.​

-I

Show each window'​s resolved application icon beside its label.​

-n

Disable type-ahead searching.​  Number keys continue to select the first ten entries, and the arrow keys and Enter continue to navigate and select.​

-p

Open the menu at the pointer instead of centring it on the target output.​

-F expr

Only include windows matching the DSL expression.​  self is bound to each candidate window, as with show -a -F and focus -F.​

-f format

Format each window label.​  The following conversions are supported:

• %n: entry number (0 is the shortcut for the tenth entry)
• %t: displayed title, including any title.​format expansion
• %T: raw client title
• %a: application ID
• %i / %I: full / first eight characters of the window identifier
• %o / %O: output name / number
• %d / %D: desk number / name
• %x, %y, %w, %h: window position and content size
• %l: window layer
• %%: a literal percent sign

Without -f, the default is %o:%d %a - %T (output, desk, application ID, and raw window title).​  Type-ahead searches the resulting formatted label, so omitted fields are not included in searches.​  Filtered results retain the configured sort order.​

-S sort

Sort windows by title, app, id, output, or desk.​  location sorts by output, desk, application ID, then title.​  none preserves CoW'​s window order and is the default.​  Sorting is case-insensitive and stable.​

-w

Warp the pointer to the selected window.​

Examples:

  bind L+w window-list
  bind LS+w "window-list -F ​'self​.current_output and self​.current_desk​'"
  bind L+a "window-list -f ​'%n  [%a] %t​'"
  bind L+o "window-list -f ​'%n  %o:%d  %t​'"
  bind L+s "window-list -S location"
  bind L+n "window-list -n"
  bind L+i "window-list -I -p"

The popup takes keyboard focus while it is open, so no additional bindings are needed for these keys and normal keyboard input resumes when it closes.​

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

Use window-maximize -k after expanding to retain the original window position so that it can be unmaximized.​

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

-k

Keep the current geometry while marking the window as maximized.​ Combined with -T, restore if the requested axis is already maximized; otherwise mark it maximized without changing size.​

-R

Ignore reserved areas and maximize to the full output dimensions.​ This includes both areas configured with reserved.​EDGE and areas reported automatically by River for layer-shell surfaces.​ Combined with -h or -v, it applies only to the requested axis.​

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
  window-maximize -k     # mark maximised without changing size
  window-maximize -R     # maximise over panels and other reserved areas

Pick a window with the mouse and run command targeting that window.​ The cursor changes to a crosshair icon, indicating a target window should be selected.​ Right-click or Escape cancels.​

The picked window is passed to command as the default target, so a command without an explicit -t operates on the picked view.​  Any explicit -t in command takes precedence.​

-F expr

Only allow matching windows to be picked.​  self is bound to each candidate window.​

Examples:

  bind Super+p pick-window winops -c
  bind Super+P pick-window { winops -c ; focus -L }
  bind Super+o pick-window -F ​'self​.current_output​' focus

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 inside decor -d profile blocks to style container tabs:

Configure automatic icon placement.​  Without -o, the setting applies to all outputs.​  With -o, OUTPUT may be an output name or ordinal such as @2; only properties explicitly set for that output override the global policy.​

box GEOMETRY

Constrain automatic placement to a rectangle within the output'​s usable area.​  full uses the complete usable area.​  An X-style geometry uses pixel dimensions and offsets, for example 300x800-0+0.​  A negative X or Y offset measures from the right or bottom edge.​  Geometry outside the usable area is clipped.​

fill PRIMARY SECONDARY

Set the movement direction within a row or column and the direction used when wrapping.​  Directions are left, right, up, and down.​  One must be horizontal and the other vertical.​  For example, right up fills a bottom row from left to right before wrapping upward; down left starts at the top-right, fills downward, then wraps leftward.​

grid X Y

Set the positive pixel increments used while looking for a free position.​ The built-in automatic grid uses the icon dimensions plus the traditional 8-pixel gap.​  Explicit smaller increments allow tighter searching; occupied positions are skipped.​

compact BOOLEAN

When true (the default), close gaps by arranging every automatic icon again whenever the set of icons changes.​  When false, keep surviving icons in place when another window is deiconified and use the first free position for the next icon.​

reset

Restore the built-in global policy.​  With -o, remove all placement overrides for that output so it inherits the global policy again.​

Manually dragged icons retain their positions and reserve their rectangles so automatic icons do not overlap them.​  Placement changes immediately reflow only automatic icons.​  If a configured box is full, cow searches the full usable area; if that too is full, it uses a deterministic overlapping fallback and logs a warning.​

Examples:

The numbered boxes in these diagrams show the order in which free icon positions are considered.​

The traditional policy starts at the bottom-left.​  right is the primary direction and up is the wrapping direction:

  icon-placement fill right up

+---------------------------------------+
|                                       |
| [7] [8] [9]                           |
| [4] [5] [6]                 wrap: up  |
| [1] [2] [3]  primary: right           |
+---------------------------------------+

To start at the top-right, fill from top to bottom, and then add columns towards the left:

  icon-placement box full
  icon-placement fill down left
  icon-placement compact false

+---------------------------------------+
|                           [7] [4] [1] |
|                  down: v  [8] [5] [2] |
|       <-- wrap left       [9] [6] [3] |
+---------------------------------------+

The same fill policy can be constrained to a box.​  In this example, 96x900-0+0 makes a 96 by 900 pixel strip at the top-right of the usable area; -0 anchors its right edge and +0 anchors its top edge:

  icon-placement box 96x900-0+0
  icon-placement fill down left

+-----------------------------------+-----+
|                                   | [1] |
|                                   | [2] |
|          rest of usable area      | [3] |
|                                   | [4] |
|                                   |  v  |
+-----------------------------------+-----+
                              placement box

Output-specific settings override only the named properties and inherit the remaining global policy:

  icon-placement -o @2 box full
  icon-placement -o @2 fill right down

# Remove all overrides for the second output​.
icon-placement -o @2 reset

Reset manual icon positions.​  Without -t, all saved icon positions are cleared and iconified windows are returned to automatic placement.​  With -t, the target may be a window, output, or desk; for example -t #id, -t @1, or -t :2.​

-F expr

Only reset matching windows.​  self is bound to each candidate window.​  With a single target window, the expression is a guard.​

Example:

icon-reset -F '​self.​current_desk and self.​iconified'​

The following table shows which settings can be applied to a given (named) decor to change aspects of how icons are controlled:

menu-add [-i ICON] NAME LABEL ACTION

menu-clear NAME

menu-destroy NAME

menu-show NAME [-x N] [-y N]

Menus take keyboard focus while open.​  Arrow keys navigate, Enter selects, Escape closes, and a menu item'​s alphanumeric hotkey activates it.​  Keys listed in menu.​repeat_keys repeat while held, using repeat_delay_ms and repeat_interval_ms.​  Backspace edits the search text in menus such as window-list which support type-ahead.​ The first visible actionable item is initially highlighted.​  Pointer hover does not replace that selection until the pointer moves after the menu opens.​ Selecting a submenu item with Up or Down opens it after the same short delay used for pointer hover; Right continues to open it immediately.​

The mouse command can bind a menu to cow'​s output background with the R context:

  mouse R:0+left "menu-show RootMenu"

menu-style KEY VALUE
menu-style -m NAME KEY VALUE
menu-style -m NAME -r KEY

Without -m, sets the global menu style.​  With -m, sets an override for the named menu; the menu is created if it does not exist yet, so style declarations may precede menu-add.​  Properties not overridden by a named menu use the current global value.​

-r KEY

Remove the named menu'​s override for KEY, returning that property to the global menu style.​  This requires -m.​

All style properties may be overridden per menu.​  Submenus resolve their own named overrides directly against the global style rather than inheriting their parent menu'​s overrides.​  menu-clear preserves overrides; menu-destroy removes them with the menu.​

The table below shows the possible values:

The default raised selection retains the menu background and derives a lighter top/left edge and darker bottom/right edge from the resolved bg colour.​  This also applies to per-menu background overrides, including very light and very dark colours; no selection.​relief setting is required to enable it.​  The sunken selection applies the darker colour for top/left and the lighter one for bottom/right.​

The flat outer menu border is a solid border.​colour.​ Raised and sunken borders derive light and dark edges from border.​colour.​

Gradient values use the same syntax as decoration gradients: none, HGradient COLOUR COLOUR, or VGradient COLOUR COLOUR.​

For hotkeys, a literal & before a label character marks that character as the item hotkey and underlines it.​  Use && for a literal ampersand.​

When automatic.​hotkeys is enabled, cow assigns unique alphanumeric hotkeys to selectable items that do not have an explicit & marker.​

When font is not set, menus use the global font.​

The menu font can be set globally or per menu.​  For example:

  menu-style font ​'Bitstream Vera Sans 17​'
  menu-style -m WindowOpsMenu font ​'monospace 10​'

This allows menu and titlebar fonts to be selected independently:

  decor -d default titlebar​.font ​'Bitstream Vera Sans 10​'
  menu-style font ​'Bitstream Vera Sans 17​'

For example, these menus share the global geometry and default raised selection relief, but use different colour palettes:

  menu-style bg 0xbebebe
  menu-style fg 0x000000
  menu-style icon​.size 16
  menu-style icon​.gap 4
  menu-style icon​.path ~/​.config/cow/icons

menu-style -m Applications bg        0xd8e0ef
menu-style -m Applications fg        0x182238
menu-style -m Applications title​.bg  0x435a82
menu-style -m Applications title​.fg  0xffffff
menu-style -m Applications separator 0x8798b8
menu-style -m Applications border​.colour 0x293852

menu-style -m WindowOps bg        0xe7d8d2
menu-style -m WindowOps fg        0x321915
menu-style -m WindowOps title​.bg  0x8b3a2f
menu-style -m WindowOps title​.fg  0xffffff
menu-style -m WindowOps separator 0xb78378
menu-style -m WindowOps border​.colour 0x57231d

menu-style -m RootMenu bg        0xd7e4e2
menu-style -m RootMenu fg        0x102b29
menu-style -m RootMenu title​.bg  0x0d988c
menu-style -m RootMenu title​.fg  0xffffff
menu-style -m RootMenu separator 0x72aaa5
menu-style -m RootMenu border​.colour 0x084b46

# Remove only RootMenu​'s foreground override​.
menu-style -m RootMenu -r fg

  # Relative icon names are searched below this directory​.  This is already
  # the default and is shown here to make the lookup explicit​.
  menu-style icon​.path ~/​.config/cow/icons

# A "send to desk" sub-menu and a window-ops menu that uses it​.
menu-add SendToDesk "Send to Desk" title
menu-add SendToDesk "Desk 1"       "desk 1"
menu-add SendToDesk "Desk 2"       "desk 2"

menu-add WindowOps  "Window"        title
menu-add -i move​.svg WindowOps "Move" "window-move"
menu-add WindowOps  "Maximise"      "window-maximize"
menu-add WindowOps  -               -
menu-add WindowOps  "Send To Desk"  "popup SendToDesk"
menu-add WindowOps  "Close"         "winops -c"

menu-add -i windows​.svg RootMenu "Window Ops" "popup-pick WindowOps"
menu-add -i terminal​.svg RootMenu "Terminal" "exec xterm"
mouse R:0+left "menu-show RootMenu"

# Arrow keys, Enter, Escape, and item hotkeys work while the menu is open​.

Pan the virtual page viewport for the current desk.​

Each page has the logical width and height of its output.​  Reserved and layer-shell areas affect window placement and maximization, but do not change page dimensions or scroll distances.​

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

Page jump: land the viewport at page col,row.​  The pair are a single comma-separated token.​  Each axis accepts an absolute page index (0-indexed), a negative absolute index from the end (-1 is the last page in that axis), or a signed relative page offset with a p suffix (+0p means the current page in that axis).​  The -a flag may be omitted when the command has a single comma-separated argument.​

-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

# Jump to the last column in the current row​.
scroll -a -1,+0p

# 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:

For example, require Alt while dwelling at an edge:

  set edge_scroll true
  set edge_scroll_modifiers A

The modifier applies both while moving a window and during ordinary pointer movement.​  Pressing it while the pointer is already at an edge starts the dwell, while releasing it cancels a pending page switch immediately.​

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 repeatable keyboard input:

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