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.

resizable true|false

Honour the window size requested by CoW, for example when embedded in a cowbuttons panel. Buttons fill the available grid; use the mouse wheel to reach entries which do not fit. rows and columns limit the grid, while button-height and min-button-width determine how many buttons fit. The default, false, sizes the window to its contents.

fit-all true|false

Fit every entry into the configured window size without scrolling. The grid adapts to the available width and height, overriding rows, columns and min-button-width. Button dimensions are preferences; text and icons shrink when necessary. This also enables resizing. Very small windows may make entries unreadable. Default: false.

output VALUE

Limit the list to an output. VALUE may be an output name, @N, @current, @next, or @prev. The existing current alias selects cow’s current output, while self selects 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.

group-typeahead BOOLEAN

Enable typeahead filtering in the native menu used to select a window from a grouped row. The default is false.

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.

button-relief auto|raised|sunken|flat

Set the relief drawn around each row. auto raises normal rows and sinks focused or iconified rows, and is the default. flat disables the relief; combine it with style border for a solid outline.

style element colour

Override a palette colour. element is one of background, active.bg, active.fg, inactive.bg, inactive.fg, or iconified.bg, or border. The optional border is drawn around every row. Colours use CoW’s RGB or RGBA syntax. Styles may be shared at top level or set separately inside an iconman block.

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.

frame-padding N

Add a border of N pixels around the window list. The default is 4.

APPEARANCE

Without explicit style settings, focused and unfocused rows use CoW’s active and inactive titlebar colours. The empty background follows the selected output, and an iconified row uses a darkened inactive background. Explicit styles override these inherited colours; an unset iconified.bg is derived from the effective inactive.bg colour.

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 by default; number keys, arrows, Enter, and Escape remain available. Set group-typeahead true to filter the selector by typing instead.

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
    style active.bg 0x458588
    style active.fg 0xffffff
    style inactive.bg 0x83a598
    style inactive.fg 0x000000
}

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>