cowpager(1)

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.

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 separated by commas (e.g. -m HDMI-A-1,DP-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.

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

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

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.

Supported colour roles:

    style background 0xffffff
    style desk.bg 0xffffff
    style page.bg 0xffffff
    style page.active.bg 0x3366b3
    style label.bg 0xd8d8d8
    style label.active.bg 0x3366b3
    style label.fg 0x000000
    style label.inactive.fg 0x000000
    style window.focused.bg 0xf7c733

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.

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.

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. Windows are coloured by their id. The focused window is drawn in yellowi 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 &

SEE ALSO

cow(1)

AUTHORS

Thomas Adam