cowiconman(1)

NAME

cowiconman - CoW Icon Manager

SYNOPSIS

cowiconman [-c config] [-h]

DESCRIPTION

cowiconman displays a clickable list of windows known to cow(1).

Without a configuration file, one icon manager is created using built-in defaults. It shows every window in a single column, sorted by title.

Its configuration can define several named icon managers. Each top-level show iconman line creates a separate cowiconman window.

The window size follows the visible button grid, growing or shrinking as windows enter or leave the list. It is capped to the selected output's usable area.

OPTIONS

-c config
    Load config instead of the default configuration file.

-h
    Show usage.

CONFIGURATION

The format is line-oriented. Blank lines and lines starting with # are ignored. Values containing whitespace must be double quoted.

By default, cowiconman reads cowiconman.conf from $XDG_CONFIG_HOME/cow/cowiconman.conf or ~/.config/cow/cowiconman.conf.

Top-level settings are shared defaults. Named iconman blocks override those defaults for the instances which select them. For example:

    show iconman current
    show iconman applications
    sort title
    button-width 240
    iconman current {
    	output current
    	desk current
    	page current
    }
    iconman applications {
    	group-by app
    	icons true
    }

Each show iconman line creates one window. Multiple names on the same line combine those blocks into one instance, in the order in which their definitions occur:

    show iconman common current-output

Supported commands are described below.

output VALUE
    Limit the list to an output. VALUE may be an output name, @N for cow's output number, current for cow's current output, or self for the output containing the cowiconman window. Use all to clear an inherited output filter. The default is to show all outputs.

desk VALUE
    Limit the list to a desk. VALUE may be a desk number or current. Use all to clear an inherited desk filter. The default is to show all desks.

page VALUE
    Limit the list to a page. VALUE may be X,Y or current. Use all to clear an inherited page filter. The default is to show all pages.

sort MODE
    Sort rows by title, app, id, or leave them in cow's order with none. The default is title.

group-by MODE
    Group matching windows into one row. MODE may be none, app, title, output, or desk. The default is none.

match FIELD=TEXT
    Only show windows whose FIELD contains TEXT. FIELD may be title, app, or id. Matching is case-insensitive. Repeat the command to add filters. Prefix TEXT with ! to exclude matching windows.

format FMT
    Set the row label format. Supported escapes are %t title, %a app_id, %i short window id, %o output, %d desk, and %%. The default is %t.

rows N
    Arrange buttons into at most N rows before starting a new column.

columns N
    Arrange buttons into N columns. The number of rows is computed from the visible window count.

anchor none|top|bottom
    Move the cowiconman window to the selected output's top or bottom usable edge. The default is none.

button-width N
    Set the preferred button width in pixels. The default is 300.

button-height N
    Override the row height derived from cow's current titlebar theme.

min-button-width N
    Set the minimum button width used when the preferred grid would exceed the output's usable width. The default is 80.

icons true|false
    Show each window's application icon before its label. cowiconman uses the icon resolved by cow. The default is false.

icon-size N
    Set the application icon size in pixels. The default is 16 and the maximum is 20.

iconified-marker true|false
    Reserve space before each label and draw a small square there for iconified windows. The default is false.

show-self true|false
    Include cowiconman windows in the list. Hidden by default.

APPEARANCE

Focused and unfocused rows use the active and inactive titlebar colours.

USAGE

Left-click a row to focus the window. If the window is iconified, it is restored and focused.

Left-click a grouped row to open a selector for the windows in that group. The selector is a native cow menu using the current menu style. Its rows include the short window id, output, and desk. Selecting a window switches to its output, desk, and page, activates its container member when necessary, restores it when iconified, and focuses it. Type-ahead is disabled for these selectors; number keys, arrows, Enter, and Escape remain available.

Middle-click a row to toggle the window's iconified state.

Use the pointer wheel to scroll when a fixed row layout has more entries than fit on screen.

An anchored rows 1 layout behaves like a bar: it spans the selected output's usable width and divides that space evenly between entries.

EXAMPLES

Show windows on the current output, desk, and page in a top task bar:

    show iconman taskbar
    iconman taskbar {
    	output current
    	desk current
    	page current
    	rows 1
    	anchor top
    	icons true
    }

Create a separate grouped list for each of two outputs:

    show iconman left
    show iconman right
    group-by app
    format "%a (%t)"
    iconman left {
    	output HDMI-A-1
    }
    iconman right {
    	output eDP-1
    }

Show xterm windows but exclude titles containing "logs":

    show iconman terminals
    iconman terminals {
    	match app=xterm
    	match title=!logs
    }

Remove cowiconman's own window decors while preserving the active decor theme:

    decor -d cowiconman-nodecor border.width 0
    decor -d cowiconman-nodecor border.handles false
    decor -d cowiconman-nodecor titlebar.enabled false
    rule -g -Ton-map -ncowiconman-nodecor -s %cowiconman decor -a cowiconman-nodecor

FILES

$XDG_CONFIG_HOME/cow/cowiconman.conf ~/.config/cow/cowiconman.conf

SEE ALSO

cow(1), moocow(1), cowbuttons(1), cowpager(1)

AUTHORS

Thomas Adam <thomas@xteddy.org>