xosdd — an XOSD daemon

xosdd is a yet another daemon^†, or front-end, for displaying information “on-screen” with XOSD. XOSD is a thin library for displaying strings, sliders, and bars on your X11 screen with shaped windows to achieve a floating effect. It is very useful for displaying things like volume or battery levels, notifications, and window manager events. This program makes XOSD facilities available via a named pipe, so that you can hook into it using simple file I/O (from your window manager, for example).

There are many other implementations for more or less the same thing (OSDsh, osdd, onscreend, …). Some are feature-rich, while some are archaic. xosdd tries to fit in between by exposing all XOSD functionality without any significant extra goodies.

The interface is about as simple as it can be. Start xosdd giving initial XOSD properties and a pipe file name on the command line (see Usage). Then, write a string to the pipe to display information or modify the properties of the OSD object managed by the running xosdd (see Commands).

(^† Calling xosdd a “daemon” is technically wrong, as xosdd does not support forking and detaching itself from its parent process. Earlier versions of xosdd could do that, but this feature was removed in version 0.1, as running xosdd is meaningful only within a single X session. Nonetheless, the name stuck.)

Installation

Download and extract the source code: xosdd-0.1.tar.gz

You need a C compiler, X11, and XOSD, of course. If you’re running GNU, your distribution might have separate development packages like libx11-dev and libxosd-dev. You need to install them first. I have used XOSD version 2.2.14, but other versions may be OK as well.

A primitive Makefile is included in the source package, though simple

cc -o xosdd *.c -lxosd

should be enough. xosdd is a very small program. The makefile does not have separate installation targets, just copy the resulting binary to some appropriate location like /usr/local/bin.

Usage synopsis

xosdd -abCcfHhlopstVv fifo

The only required argument is fifo, which is the file name of the FIFO which xosdd reads. For help on options, type xosdd -h. Most of the options set OSD parameters, which can be changed later as well (see Commands). The default number of lines for the OSD is two. This can be changed with option -l.

One xosdd process can handle only one on-screen display. If you need more than one OSD, spawn a separate xosdd process with a unique FIFO name for each OSD.

If you wish to spawn OSD on a specific X11 display, set DISPLAY environment variable to that display before starting xosdd.

Commands

xosdd expects strings of form command param1 param2 … paramN from its pipe, where command is a supported command, and param1 … paramN are parameters for the command (see the table below). Parameters must be separated by single spaces. A parameter with embedded spaces must be surrounded by double quotes. Literal double quotes within parameters must be escaped by doubling them. XOSD expects UTF-8 encoded strings; specifically, xosdd doesn’t do any coding conversions, although such support should be straightforward to add if needed.

Table 1: Commands recognized by `xosdd`
Command	Parameters	Description	Corresponding XOSD function
`align`	`left` \| `center` \| `right`	Set the horizontal alignment.	`xosd_set_align`
`bar`	`line value`	Display percentage bar with value `value` on line `line`. The value is clamped between 0 and 100.	`xosd_display`
`barlen`	`value`	Set the bar/slider length to `value`.	`xosd_set_bar_length`
`color`	`color`	Set the foreground color to `color`.	`xosd_set_colour`
`font`	`font`	Set the font to `font`.	`xosd_set_font`
`horizoff`	`offset`	Set the horizontal offset to `offset`.	`xosd_set_horizontal_offset`
`hide`	N/A	Hide the OSD.	`xosd_hide`
`outcolor`	`color`	Set the outline color to `color`.	`xosd_set_outline_colour`
`outoff`	`offset`	Set the outline offset to `offset`.	`xosd_set_outline_offset`
`pos`	`top` \| `bottom`	Set the vertical position.	`xosd_set_pos`
`scroll`	`nlines`	Scroll the OSD by `nlines` lines.	`xosd_scroll`
`shadowoff`	`offset`	Set the shadow offset to `offset`.	`xosd_set_shadow_offset`
`show`	N/A	Show the OSD.	`xosd_show`
`slider`	`line value`	Display percentage slider with value `value` on line `line`. The value is clamped between 0 and 100.	`xosd_display`
`strbar`	`value str [str…]`	Display percentage bar with value `value` on line zero, and strings `str` below it. Line zero is the topmost line if the OSD is located at the top of the screen. Otherwise, line zero is the bottom line, and the strings are displayed in reverse order.	N/A
`string`	`line str`	Display string `str` on line `line`.	`xosd_display`
`strings`	`str [str…]`	Display strings `str`, starting from line zero. Line zero is the topmost line if the OSD is located at the top of the screen. Otherwise, line zero is the bottom line, and the strings are displayed in reverse order.	N/A
`strslider`	`value str [str…]`	Display percentage slider with value `value` on line zero, and strings `str` below it. Line zero is the topmost line if the OSD is located at the top of the screen. Otherwise, line zero is the bottom line, and the strings are displayed in reverse order.	N/A
`term`	N/A	Terminate `xosdd`.	N/A
`timeout`	`nsec`	Set the OSD timeout to `nsec` seconds.	`xosd_set_timeout`
`vertoff`	`offset`	Set the vertical offset to `offset`.	`xosd_set_vertical_offset`

strbar, strings, and strslider are convenience functions.

Copyrights

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Home

Last updated on 5 November 2023.