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(3),  is
       reached,    but    xosd_display    returns    immediately.   If   blocking   is   required
       xosd_wait_until_no_display(3) should be  called  after  xosd_display.  A  window  that  is
       displaying data can be hidden by calling xosd_hide(3).

       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(3).

       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(3),    xosd_set_timeout(3),    xosd_wait_until_no_display(3),   xosd_hide(3),
       printf(3).

                                                                                  XOSD_DISPLAY(3)