NAME

cowpager - FvwmPager-style visual pager for the cow window manager

SYNOPSIS

cowpager [-f path] [-r rows] [-c cols] [-m mon[,mon…]] [-1] [-h] [first last]

DESCRIPTION

cowpager is a small graphical pager that displays desks tracked by cow and the windows on them. By default, each desk is drawn as one canvas containing the full visible monitor layout, similar to FvwmPager when it is not tracking a specific monitor.

Without any options, cowpager will show all desks and windows across all outputs.

Containers appear as one window, without their internal pane layout. The container is highlighted when its outer window or any pane inside has focus.

On startup, cowpager reads cowpager.conf from $XDG_CONFIG_HOME/cow/cowpager.conf or ~/.config/cow/cowpager.conf when that file exists. Command-line options override settings loaded from the config file.

OPTIONS

-f PATH

Load configuration from PATH instead of the default location. Unlike a missing default file, a missing explicit file is an error.

-r ROWS

Arrange desks in ROWS rows. If only -r is given, the number of columns is computed from the number of desks.

-c COLS

Arrange desks in COLS columns. If only -c is given, the number of rows is computed from the number of desks. When neither -r nor -c is given, all desks are arranged in a single row.

-m LIST

Restrict the pager to the listed outputs. LIST is one or more output names or selectors separated by commas (e.g. -m HDMI-A-1,@2). Selectors are @N, @current, @next, and @prev, with the same meaning as in cow(1). Monitor labels appear in the order given on the command line.

When -m names a single output, cowpager tracks that output: the page grid is scaled to that monitor rather than to the full monitor layout.

Without -m, all outputs are shown in the way cow manages them. See cow(1) – OUTPUT MANAGEMENT.

-1

Display only the currently active desk.

first last

Display desks first through last, inclusive. For example, cowpager 0 3 shows desks 0, 1, 2, and 3.

-h

Print usage and exit.

CONFIGURATION

The config file uses the same simple, whitespace-separated format as cowbuttons. Double-quoted strings are supported, and # starts a comment outside quoted strings.

Top-level options act as defaults. A config may also contain named pager blocks, selected by top-level show pager lines. Each top-level show pager line creates one cowpager window:

show pager main
show pager compact

pager main {
    columns 4
    desks 0 3
    monitors HDMI-A-1,DP-1
}

pager compact {
    current-only true
    monitors DP-1
}

When no show pager line is present, only top-level options are used. When a pager block is selectd, options inside that block override the top-level defaults. Multiple names may be listed on one show pager line; those matching blocks are combined into that one instance as they are encountered in the file.

The window title identifies both the selected pager definitions and, when exactly one monitor is selected, that monitor. For example, a fvwm instance restricted with -m HDMI-A-1 is titled cowpager:fvwm:HDMI-A-1. This allows cow rules and styles to distinguish per-output instances created from the same pager definition.

Supported layout commands:

rows 2
columns 4
desks 0 3
monitors HDMI-A-1,DP-1
current-only false
desktop-labels true
monitor-labels true
label-highlight true
desktop-scale 32
window-icons true
window-icon-size 16

monitors selects the outputs shown by this pager. Use a single output name or selector to track one monitor, or a comma-separated list to show several outputs in the given order. It accepts the same selectors as -m.

desks selects the desks shown by this pager. The range is inclusive, so desks 0 3 shows desks 0, 1, 2, and 3. It is mutually exclusive with current-only true: setting desks clears current-only mode, and setting current-only true clears the desk range.

window-icons controls whether application icons are drawn in window miniatures (default: true). window-icon-size sets their maximum square size in pixels (default: 16). An icon is centred in its window miniature and automatically reduced further when the miniature is too small for the configured size.

Supported colour roles:

style background 0xffffff
style desk.bg 0xffffff
style desk.active.border 0x4d9ef2
style page.bg 0xffffff
style page.active.bg 0x3366b3
style page.separator 0x000000
style label.bg 0xd8d8d8
style label.active.bg 0x3366b3
style label.fg 0x000000
style label.inactive.fg 0x000000
style window.bg 0x60a0c0
style window.border 0x000000
style window.focused.bg 0xf7c733
style viewport.bg 0x00000000
style viewport.border 0xda70d6

Colours may be opaque 0xRRGGBB values or 0xRRGGBBAA values carrying an alpha component. Each background layer has its own colour. For example, the following makes the pager’s principal backgrounds dark grey at 80 percent opacity:

style background 0x282828CC
style desk.bg 0x282828CC
style page.bg 0x282828CC
style page.active.bg 0x458588CC
style label.bg 0x282828CC
style label.active.bg 0x458588CC

By default, cowpager derives these colours from cow’s current configured theme. The output background becomes the pager background when one is configured; otherwise the inactive titlebar or tab colour is used. Active/inactive titlebar or tab colours are used for highlights and labels. Any style line in cowpager.conf overrides the derived value for that role.

Label fonts inherit the font family from cow’s titlebar.font decoration setting. The pager chooses its own label sizes and weights. No font setting is needed in cowpager.conf.

background is the default colour for the whole pager surface, including desk and page backgrounds. desk.bg, page.bg, and page.active.bg may be set when those areas should differ. desk.active.border controls the frame around the active desk.

Without explicit background or page.bg settings, page cells inherit CoW’s output, desk and page colours, including those set with background. Background images tile at their original size to keep patterns recognisable in small page cells. An explicit page.active.bg overrides the current page background, including its image.

page.separator sets the colour of the dashed lines between pages. Set it to 0x00000000.

window.bg gives every unfocused window miniature the same colour. When it is not set, cowpager retains its default behaviour of deriving a stable colour from each window identifier. window.focused.bg controls the focused window miniature, and window.border controls miniature outlines.

viewport.bg and viewport.border override the monitor-derived fill and outline used to mark the currently visible viewport. A fully transparent viewport.bg, such as 0x00000000, leaves the active page colour unchanged.

DISPLAY

DESKTOP AND MONITOR LABELS

Each desk cell has a desktop label. When more than one output is shown, a second monitor-label row is drawn below it. Hence:

the desktop label identifies the desk;
each monitor label identifies an output;
a monitor label is highlighted on the desk that output currently views;
when only one output is shown, the desktop label itself is highlighted for the active desk.

The monitor label is the output’s name when it fits, falling back to its cow-assigned number when the name would overflow the slot.

PAGE GRID AND VIEWPORTS

Window miniatures are placed on the grid and coloured by their id. When CoW has resolved an application icon, cowpager centres it inside the corresponding miniature. The same effective icon.image is used for desktop icons and the pager, so decoration profiles and rules can override or disable the image for particular windows. The focused window is drawn in yellow by default.

Without -m, the page grid is scaled to the bounding box of all shown outputs. Window miniatures and viewport rectangles are placed using the physical monitor layout, so adjacent monitors appear adjacent in the pager instead of overlapping.

For every output currently viewing a desk, a translucent rectangle marks that output’s viewport position within that desk’s page grid.

EXAMPLES

Show every output and every desk (the default):

cowpager &

Limit the pager to two specific outputs, arranged in two rows:

cowpager -r 2 -m HDMI-A-1,DP-1 &

Use a custom config file:

cowpager -f ./cowpager.conf &

Single-output pager pinned to DP-1, showing only the active desk:

cowpager -1 -m DP-1 &

Show desks 0 through 3:

cowpager 0 3 &

AUTHORS

Thomas Adam