NAME

cowbuttons - Button panel for the cow window manager

SYNOPSIS

cowbuttons [-c config] [-p panel]… [-h]

DESCRIPTION

cowbuttons displays a small configurable grid of cells. Cells can run cow(1) commands, periodically display the output of scripts, show selected state from cow’s status socket, or act as empty spacers.

External applications can occupy cells or open beside a panel handle. CoW attaches their windows to cowbuttons, keeping them together when moved, raised, or iconified. This uses CoW’s container machinery.

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. Labels and commands containing whitespace must be quoted.

End a line with a single backslash to continue it on the next line. The backslash and newline become a space. A backslash in a comment does not continue that comment; a doubled trailing backslash stays literal.

button "Terminal" "exec foot" \
    image terminal.svg width 64 height 64 \
    rightclick "menu-show Applications"

Self-contained panels

Use -p panel to select a named panel instead of the file’s show lines. Repeat -p to combine panels in one window. This does not start other instances and can be used to launch a drawer from the same file.

A cowbuttons setup may keep its embedded modules’ configuration in the same file. Wrap each program’s settings in module program { … }. Each program reads only its own section using its normal configuration syntax. Existing standalone files do not need a wrapper.

An optional cow { … } block contains CoW commands. Cowbuttons submits them before creating its window, for example to install its placement and decoration style. Startup stops if CoW rejects these commands. Other modules ignore this block. These commands run when cowbuttons starts; restart cowbuttons to reapply them after restarting CoW. Use style -r for named styles in this block so relaunching the panel replaces its previous definition.

Cowbuttons supplies COWBUTTONS_CONFIG to external applications. It is the absolute path to its configuration file; quote it in shell commands:

module cowbuttons {
    show panel bar
    panel bar {
        row {
            external "cowpager -f \"$COWBUTTONS_CONFIG\"" app_id cowpager
        }
    }
}
module cowpager {
    show pager embedded
    pager embedded {
        current-only true
    }
}

Keep section braces on separate lines as above, and put shared-file settings inside their program’s section. The programs remain independent clients; they do not exchange configuration or communicate with one another.

See examples/cowbuttons/application-row.conf for a complete panel in one file, including its CoW style, pager, and icon manager. examples/cowbuttons/cde-panel.conf demonstrates a bottom-centred front panel with a clock, desk switcher, and independent upward launcher drawers.

Colours may be opaque 0xRRGGBB values or 0xRRGGBBAA values carrying an alpha component. In the latter form, 00 is fully transparent and FF is fully opaque. For example, style button.bg 0x282828CC uses an 80-percent opaque dark grey.

cell W H

Set the default cell size in pixels. The default is 96 by 32.

grid rows cols

Set the grid size.

col col width N

Set one column’s width in pixels.

fill.width true|false

A cell property which gives its columns the panel’s remaining width. For example, add fill.width true to an external cowiconman cell to let it grow while neighbouring buttons retain their configured widths. If several cells request it, they share the extra space proportionally. Without any fill cells, all non-handle columns grow as before.

show panel name […]

Show one or more named panel definitions from the configuration file. Multiple names on the same show panel line are combined into one cowbuttons window. Multiple top-level show panel lines create separate cowbuttons windows from the same configuration file. Settings outside panel blocks can be used as shared defaults.

panel name [direction [property value …]] {

Start a named panel definition. A panel is loaded when it is named by show panel. When direction is left, right, up, or down, cowbuttons adds an attached handle and opens the panel in that direction. Pressing the handle collapses or expands the panel. Handle properties use the same styling keys as button. handle.size sets the handle thickness in pixels: its width for left/right panels, or its height for up/down panels. The default is 22. handle.both true adds a second handle at the opposite end. Either handle toggles the same panel, keeping the clicked handle in place. When collapsed, only the clicked handle remains visible. Reopening restores both handles; a panel configured to start closed shows its primary handle. handle.opposite.bg colour overrides the second handle’s background; other styling is shared. parent name hides the panel’s handle and applications while the named panel is collapsed. Reopening the parent restores the child’s previous open/closed state. Both panels must be selected in the same show panel line; parent relationships must not form a cycle. open true|false chooses the initial expanded state. External drawers default to closed; other panels default to open.

position column,row starts a panel at a zero-based grid position. This lets separate drawer handles share a row above their launchers. Leave it unset to place panels consecutively. Panels must not overlap.

Write panel properties on separate lines inside the panel block, before its contents. direction selects the opening direction. These properties affect the panel handle; style still sets button defaults. The inline header form remains supported.

panel applications { direction right handle.size 11 handle.both true handle.opposite.bg 0xcd2626 frame 2 bg 0xffd700 fg 0x202020 row { button “Terminal” “exec foot” } }

row [height N] { … }

Start a new visual row. Cells inside the block are appended left-to-right.

if [not] command name { … }

Process the block only when name exists in PATH and is executable.

if [not] file path { … }

Process the block only when path exists. Relative paths are resolved against the configuration file’s directory.

if [not] env name { … }

Process the block only when the environment variable name is set and non-empty.

font name

Set the font face used for labels.

resizable true|false

Allow the window to be resized. Content columns and rows grow or shrink with the window, while panel handles retain their configured thickness. Closing a panel preserves the resized dimensions for reopening. The default is false.

closeonexit true|false

Set the default for subsequent external cells. The default is false, which releases applications as ordinary windows when cowbuttons exits. With true, CoW requests that they close instead. Each external can override this with its own closeonexit value. This also applies to reused applications and when cowbuttons is killed. It does not forcibly terminate clients: applications may prompt to save work or refuse to close. Collapsing a panel never closes its applications.

style button.bg colour

Set the normal button background colour.

style button.bg_pressed colour

Set the pressed button background colour.

style button.fg colour

Set the normal button text colour.

style button.fg_pressed colour

Set the pressed button text colour.

style button.frame width

Set the relief thickness in pixels (default: 2). Positive values give a raised frame which becomes sunken when pressed. Negative values reverse this; zero draws no frame. Frames are limited to half the cell’s smaller dimension. Override individual buttons or panel handles with frame:

style button.frame 2 button “Terminal” “exec foot” frame -2

style button.image path

Draw a PNG, SVG, or XPM image in command buttons. Relative paths are resolved against the configuration file’s directory.

style button.image_pressed path

Draw a PNG, SVG, or XPM image while a command button is pressed.

style button.image_size N

Set the image size in pixels. The default is 16.

style button.image_position left|center|right|fill

Set where button images are drawn. The default is left.

style button.justify left|center|right

Set the default button text justification. The default is left.

button label command [property value …]

Create a clickable button. command is sent to cow as its left-click action. Supported properties are width, height, span, frame, bg, bg_pressed, fg, fg_pressed, image, image_pressed, image_size, image_position, justify, and the click-action properties described below.

leftclick command click command middleclick command rightclick command

Set the single-click action for the specific button. click is an alias for leftclick.

doubleclick command leftdoubleclick command middledoubleclick command rightdoubleclick command

Set a double-click action. doubleclick is an alias for leftdoubleclick. When both single- and double-click actions exist for the same button, the single-click action is delayed for 300 ms.

leftpress command middlepress command rightpress command

Run on button press, rather than release. This takes precedence over single- and double-click actions for that mouse button and does not run another action on release.

drag true|false

Make a button a drag grip for the cowbuttons window (default false). Holding the left mouse button moves the window until release. This replaces its left-click, double-click and press actions; other mouse buttons keep their configured actions. Use this rather than sending window-move from a press action.

wheelup command wheeldown command wheelleft command wheelright command

Run on scrolling over the cell. Small continuous deltas accumulate before firing an action. Scrolling over an embedded application remains with that application.

Click, press and wheel properties also work inside panel blocks to configure their handles, and on desks cells. A handle without a custom left-click binding still toggles its panel. An explicit binding replaces that default; use nop to disable it.

Desk actions run in a script scope with desk_nr set to the clicked desk number and output_selector to its output selector. For example:

desks rows 2 rightclick "desk -t #{output_selector}" \
    wheelup "desk -t #{output_selector} -p" \
    wheeldown "desk -t #{output_selector} -n"

Without an explicit left-click action, desk buttons switch to the clicked desk. Double-click matching and delayed actions retain the original desk and output context.

script command interval seconds [property value …]

Create a cell whose label is supplied by an external command. The command is run through the shell immediately after startup and then again the configured number of seconds after each run finishes. Runs never overlap.

The first line written to standard output, limited to 255 bytes, replaces the cell’s label when the command exits successfully. Empty output clears the label. If the command fails, the previous successful label is retained and an error is written to standard error.

lines count displays up to count output lines, centred as a block (1–16; default 1). The 255-byte limit applies to the whole label. For example, script "date '+%b%n%d'" interval 60 lines 2 puts the month above the day.

Script cells support the same click actions, styling, and geometry properties as button cells.

external command [property value …]

Create an application slot. In a directional panel, the application starts on first opening and appears beside the handle. Collapsing the panel hides its window without terminating it; reopening shows the same window. Directional external panels start collapsed.

Inside a row, each external occupies its own cell alongside buttons, spacers or other applications. Applications start when the panel is open. Collapsing its handle hides every attached application; reopening restores the same windows. Without a direction the row stays open. A standalone external outside a row retains the directional drawer behaviour described above; only one such drawer is allowed per panel. Upward and downward drawers follow the width of their grid span while retaining their configured height. Use span to extend the handle and application across neighbouring columns. drawer.width pixels overrides an upward or downward drawer’s width without widening its handle; the drawer remains left-aligned with it. Applications are inset inside their slot’s frame, including external drawers. The frame is drawn by cowbuttons, not by a window decoration rule. padding pixels adds space between the frame and application, using the cell’s background colour. It defaults to zero. Set frame 0 and padding 0 on an external cell to use the whole slot. An external cell inside a row may specify handle.size pixels to add a right-edge toggle. This hides only that application; reopening reuses the same window. collapse retain (the default) keeps the cell’s size, background and relief visible without moving neighbouring buttons. collapse shrink reduces its column to the handle width instead. Such cells must occupy one column, but may span several rows. If an embedded application closes or fails to start, click its vacant cell to launch it again. Applications which enforce a minimum size or aspect ratio may leave unused space or be clipped to the cell.

CoW manages the attachment automatically. No container definitions or placement rules are required. Closing cowbuttons releases attached applications as ordinary windows unless closeonexit true is set. Attachments survive a CoW restart while cowbuttons remains running.

Attached applications cannot be moved, resized or dragged out independently. Move the cowbuttons host to move the complete panel.

The application ID defaults to the command’s executable name, matched case-insensitively. Use app_id name when a wrapper or application uses a different ID. title pattern optionally narrows matching using a case-sensitive shell wildcard pattern. By default only newly opened windows are candidates. With use_old true, cowbuttons first looks for an existing matching window and launches the command only if none exists. Existing windows are captured even when the panel starts closed, and remain hidden until it opens. Missing applications are launched only when the panel opens. Windows already in another attachment or container are never captured. If several existing windows match, the cell remains vacant and logs a warning; narrow the match before retrying. With closeonexit false, closing the host releases clients for another instance to reuse.

Newly launched commands must open a unique matching window within ten seconds. Use distinct panel names for separate cowbuttons instances so their host windows can be identified.

Supported properties are width, height, span, bg, bg_pressed, fg, fg_pressed, image, image_pressed, image_size, image_position, justify, app_id, title, use_old (default false), and closeonexit.

respawn true reruns the command when its attached window closes, including a manual close. The default is false. Cowbuttons waits at least one second before relaunching and defers this while the panel is collapsed. The launcher process exiting does not trigger respawn if its window remains open. Exiting cowbuttons never respawns clients.

If a launch fails to produce a matching window, automatic retries stop; click the vacant cell or reopen the panel to try again. This also prevents a broken command from repeatedly launching processes.

For example, a horizontal panel with its handle on the left:

show panel bar panel bar { direction right row { external “cowpager -1” width 160 height 96 button “Windows” “window-list” width 80 height 96 external “foot” width 480 height 96 external “cowiconman” width 300 height 96 } }

To close the pager and icon manager on exit while keeping the terminal:

closeonexit true show panel bar panel bar { direction right row { external “cowpager -1” width 160 height 96 external “foot” closeonexit false width 480 height 96 external “cowiconman” width 300 height 96 } }

status type [property value …]

Create a live status cell. Supported types are: focused-title, focused-app, current-output, current-desk, and desk-list.

spacer [property value …]

Create an empty cell.

desks [property value …]

Show one button per desk on the current output, using its name (or number when unnamed). Left-click switches to that desk. The list updates when desks are added, removed or renamed, or the current output changes. rows sets the maximum number of rows (default 2). Buttons share the cell’s width and height, keeping equal-width columns in a shorter final row. gap insets each button by that many pixels (default 0). Normal button colours, frame, and justify apply; bg_pressed and fg_pressed identify the active desk. Optional colours takes a comma-separated palette, repeated in desk order. This replaces the button background colours; the active desk remains distinguished by its relief.

EXAMPLES

show panel launcher
show panel telephone
show panel pager
show panel statusbar

resizable true

style button.bg 0x39414a
style button.bg_pressed 0x242a30
style button.fg 0x1f2933
style button.fg_pressed 0xffffff
style button.image_size 18

panel launcher {
    cell 118 30
    grid 2 4

    row height 30 {
        button "Terminal" "exec xterm" bg 0xcde7d8 image cowbuttons/svg/terminal.svg
        button "Firefox" "exec firefox" bg 0xffddc8 image cowbuttons/svg/browser.svg
        button "Files" "exec thunar" bg 0xffe4ad image cowbuttons/svg/files.svg
        button "Editor" "exec emacs" bg 0xded7f5 image cowbuttons/svg/editor.svg
    }

    row height 30 {
        button "Next" "focus -n" bg 0xf6e2a6
        button "Prev" "focus -p" bg 0xcfe8db
    }
}

panel telephone {
    direction left
    bg 0xf2d6a6
    cell 42 28
    grid 5 3

    row height 22 {
        button "Telephone" "nop" span fill bg 0xe8d9f2
    }
}

panel pager {
    direction right
    bg 0x3f5b51
    external "cowpager" width 420 height 120 bg 0x242a30
}

panel statusbar {
    cell 140 30
    grid 1 2

    row {
        script "~/.local/bin/clock.sh" interval 1 click "exec gsimplecal" justify center
        script "~/.local/bin/battery.sh" interval 30 justify center
    }
}

Remove cowbuttons’ own window decors using a cow rule:

decor -d cowbuttons-nodecor border.width 0
decor -d cowbuttons-nodecor border.handles false
decor -d cowbuttons-nodecor titlebar.enabled false
rule -g -Ton-map -ncowbuttons-chrome -s %cowbuttons decor -a cowbuttons-nodecor

FILES

$XDG_CONFIG_HOME/cow/cowbuttons.conf

~/.config/cow/cowbuttons.conf

SEE ALSO

cow(1), moocow(1), cowbar(1), cowiconman(1), cowpager(1)

AUTHORS

Thomas Adam <thomas@xteddy.org>