.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "XOSD_DISPLAY" 3xosd "" "" ""
.SH NAME
xosd_display \- Display data to an XOSD window
.SH "SYNOPSIS"
.ad l
.hy 0

#include <xosd.h>
.sp
.HP 18
int\ \fBxosd_display\fR\ (xosd\ *\fIosd\fR, int\ \fIline\fR, xosd_command\ \fIcommand\fR, ...);
.ad
.hy

.SH "DESCRIPTION"

.PP
\fBxosd_display\fR 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.

.PP
The data is displayed until the timeout limit, set by calling \fBxosd_set_timeout\fR(3xosd), is reached, but \fBxosd_display\fR returns immediately. If blocking is required \fBxosd_wait_until_no_display\fR(3xosd) should be called after \fBxosd_display\fR. A window that is displaying data can be hidden by calling \fBxosd_hide\fR(3xosd).

.PP
The type of data displayed is determined by the \fIcommand\fR argument. There are two types of data that can be displayed: text or integers.

.SS "Displaying Textual Data"

.PP
Text is normally displayed by passing \fBXOSD_string\fR as the argument to \fIcommand\fR, followed by a string in UTF-8 format. If formatted text is desired, pass \fBXOSD_printf\fR as the argument to \fIcommand\fR, followed by string that has the same format as \fBprintf\fR(3), and as many additional arguments as is required by the format string.

.SS "Displaying Integer Values"

.PP
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 \fBXOSD_percentage\fR as the argument to \fIcommand\fR. A slider (see the XOSD plug-in for \fBxmms\fR(1) for an example) is created by passing \fBXOSD_slider\fR as the argument to \fIcommand\fR. An \fBint\fR between 0 and 100 is expected as the final argument when either \fBXOSD_percentage\fR or \fBXOSD_slider\fR is passed as the argument to \fIcommand\fR.

.SH "ARGUMENTS"

.TP
\fIosd\fR
The XOSD window to use as the display.

.TP
\fIline\fR
The line of the display to change. The value of \fIline\fR must be less than \fInumber_lines\fR, set in the call to \fBxosd_create\fR(3xosd).

.TP
\fIcommand\fR
One of \fBXOSD_percentage\fR, \fBXOSD_slider\fR or \fBXOSD_string\fR. If the value of \fIcommand\fR is \fBXOSD_string\fR, then the next argument should be a string in UTF-8 format. If \fBXOSD_percentage\fR or \fBXOSD_slider\fR is given then an \fBint\fR between 1 and 100 is expected as the next argument.

.SH "RETURN VALUE"

.PP
If the \fIcommand\fR is either \fBXOSD_percentage\fR or \fBXOSD_slider\fR then the integer value of the bar or slider is returned (between 1 and 100). For \fBXOSD_string\fR and \fBXOSD_printf\fR the number of characters written to the display is returned.

.PP
On error -1 is returned and \fIxosd_error\fR is set to indicate the reason for the error.

.SH "ENVIRONMENT"

.TP
\fIchar *xosd_error\fR
A string describing the error, if one occurred.

.TP
\fBenum xosd_command\fR
The type of information that can be displayed, defined as an enumerated type. There are four values defined:
\fBXOSD_percentage\fR,
\fBXOSD_string\fR,
\fBXOSD_printf\fR, and
\fBXOSD_slider\fR.

.SH "AUTHORS"

.PP
The XOSD library was originally written by André Renaud, and was maintained by Tim Wright.
This document was written by Michael JasonSmith.

.SH "BUGS"

.PP
There are no known bugs with \fBxosd_display\fR.
Bug reports can be files on http://sourceforge.net/projects/libxosd/.

.SH "SEE ALSO"

.PP
 \fBxosd_create\fR(3xosd), \fBxosd_set_timeout\fR(3xosd), \fBxosd_wait_until_no_display\fR(3xosd), \fBxosd_hide\fR(3xosd), \fBprintf\fR(3)