NAME
xosd_display - Display data to an XOSD window
SYNOPSIS
#include <xosd.h>
int xosd_display (xosd *osd, int line, xosd_command command, ...);
DESCRIPTION
xosd_display displays either a string, a percentage bar (like a
progress bar) or a slider on an X display. The data is displayed in a
borderless shaped-window, so it appears to float on top of the other
windows, like the on-screen displays found in many televisions. Users
cannot interact with the display in any way.
The data is displayed until the timeout limit, set by calling
xosd_set_timeout(3xosd), is reached, but xosd_display returns
immediately. If blocking is required xosd_wait_until_no_display(3xosd)
should be called after xosd_display. A window that is displaying data
can be hidden by calling xosd_hide(3xosd).
The type of data displayed is determined by the command argument. There
are two types of data that can be displayed: text or integers.
Displaying Textual Data
Text is normally displayed by passing XOSD_string as the argument to
command, followed by a string in UTF-8 format. If formatted text is
desired, pass XOSD_printf as the argument to command, followed by
string that has the same format as printf(3), and as many additional
arguments as is required by the format string.
Displaying Integer Values
Integer values (which must be within the range 0 to 100) can be
displayed in two ways: a percentage-bar or a slider. A percentage bar
looks like a volume display on a TV, and is created by passing
XOSD_percentage as the argument to command. A slider (see the XOSD
plug-in for xmms(1) for an example) is created by passing XOSD_slider
as the argument to command. An int between 0 and 100 is expected as the
final argument when either XOSD_percentage or XOSD_slider is passed as
the argument to command.
ARGUMENTS
osd The XOSD window to use as the display.
line The line of the display to change. The value of line must be
less than number_lines, set in the call to xosd_create(3xosd).
command
One of XOSD_percentage, XOSD_slider or XOSD_string. If the value
of command is XOSD_string, then the next argument should be a
string in UTF-8 format. If XOSD_percentage or XOSD_slider is
given then an int between 1 and 100 is expected as the next
argument.
RETURN VALUE
If the command is either XOSD_percentage or XOSD_slider then the
integer value of the bar or slider is returned (between 1 and 100). For
XOSD_string and XOSD_printf the number of characters written to the
display is returned.
On error -1 is returned and xosd_error is set to indicate the reason
for the error.
ENVIRONMENT
char *xosd_error
A string describing the error, if one occurred.
enum xosd_command
The type of information that can be displayed, defined as an
enumerated type. There are four values defined: XOSD_percentage,
XOSD_string, XOSD_printf, and XOSD_slider.
AUTHORS
The XOSD library was originally written by André Renaud, and is
currently maintained by Tim Wright. This document was written by
Michael JasonSmith.
BUGS
There are no known bugs with xosd_display. Bug reports can be sent to
<xosd@ignavus.net>.
SEE ALSO
xosd_create(3xosd), xosd_set_timeout(3xosd),
xosd_wait_until_no_display(3xosd), xosd_hide(3xosd), printf(3)
XOSD_DISPLAY(3xosd)