NAME

osd_create, osd_destroy - create and destroy osd objects
osd_show, osd_hide, osd_display - display content
osd_parse_geometry osd_set_geometry - set size, position and offsets
osd_set_font - set font
osd_set_color, osd_set_bgcolor, osd_set_shadowcolor, osd_set_shadowoffset - color handling
osd_set_padding, osd_set_number_of_lines - padding and display lines for content
osd_set_monitor, osd_set_xinerama osd_set_xrandr - settings for multihead

SYNOPSIS

#include <xosd-xft.h>

extern char* osd_error;

xosd_xft *osd_create();
int osd_destroy(xosd_xft *osd);
int osd_show(xosd_xft *osda);
int osd_hide(xosd_xft *osda);
int osd_display(xosd_xft *osd, char *message, int len);
osd_geometry* osd_parse_geometry(const char *geometry, const char* textalign, osd_geometry *g);
void osd_set_geometry(xosd_xft *osd, const osd_geometry *geometry);
void osd_set_font(xosd_xft *osd, const char *font);
void osd_set_color(xosd_xft *osd, const char *color);
void osd_set_bgcolor(xosd_xft *osd, const char *bgcolor, unsigned int alpha);
void osd_set_shadowcolor(xosd_xft *osd, const char *shadowcolor);
void osd_set_shadowoffset(xosd_xft *osd, int offset);
void osd_set_padding(xosd_xft *osd, const char *padding);
void osd_set_number_of_lines(xosd_xft *osd, int nlines);
void osd_set_monitor(xosd_xft *osd, int monitor);
void osd_set_xinerama(xosd_xft *osd, int xinerama);
void osd_set_xrandr(xosd_xft *osd, int xrandr);

DESCRIPTION

The osd_create() function creates a xosd_xft object that is used in subsequent calls. osd_create() does not allocate any X resources till a subsequent call to osd_display is made. osd_destroy frees the resources used during the course of operation.

The osd_show() and osd_hide() methods are used to display and hide the OSD window after it is shown. These can be used only after osd_display() is used to display the window.

The osd_display() methods adds the given line to the content. If the window is not yet displayed, osd_display() initializes the required resources and displays the window. The settings are validated during this method call and display_window() returns -1 on error and the osd_error variable contains the error message.

The osd_parse_geometry() is a convenience method to initialize a osd_geometry object from a string representation. The osd_parse_geometry() returns NULL if the string is not in proper format.

Geometry String Format:

      geometry: <size><offset>*<alignment>
      size: <width>x<height>
        The `width` is specified as an integer. It can optionally succeed
        by either `%` or `c`. `%` is used to specify the width as a percentage
        of the screen width. `c` is used to specify the width as number of
        characters

      offset: [+-]<xoffset>[+-]<yoffset>
        The `xoffset` and `yoffset` follows the standard X geometry definition
        when alignment is not provided. When alignment is provided the offsets
        are used to adjust the alignmennt positions 

      alignment: <valign>/<halign>
        The `valign` can be any one of `top`, `middle`, or `bottom`. The `halign` can
        be one of `left`, `center` or `right`.

The osd_geometry structure holds the parsed geometry information and can be used with a subsequent osd_set_geometry() call.

osd_geometry:

/* Parsed Geometry and Text Alignment */
typedef struct _geometry
{
  /* Size - width_per and height_per set to true if % are used
            width_chars and height_lines set to true if char sizes are used */
  unsigned int          width;            /* Width */
  int                   width_per;        /* Is Width Unit as percentage of screen size */
  int                   width_chars;      /* Is Width Unit as number of characters */
  unsigned int          height;           /* Height */
  int                   height_per;       /* Is Height Unit as pecentage of screen size */
  int                   height_lines;     /* Is Height Unit as number of lines */

  /* Position - offsets are abs values, neg set to true when negative */
  unsigned int          xoffset;          /* X Offset - Absolute value */
  int                   xneg;             /* Is X Offset Negative */
  unsigned int          yoffset;          /* Y Offset - Absolute value */
  int                   yneg;             /* Is Y Offset Negative */

  /* Alignment - Horizontal and Vertical Alignment of OSD Window */
  osd_valign          valign;             /* Vertical Alignment */
  osd_halign          halign;             /* Horizontal Alignment */

  /* Alignment - for Text */
  osd_valign          text_valign;        /* Text Vertical Alignment */
  osd_halign          text_halign;        /* Text Horizontal Alignment */
} osd_geometry;

Horizontal and Vertical Alignment Constants

/* Vertical Alignment */
typedef enum
{
  XOSD_XFT_top = 0,       /* Align to Top */
  XOSD_XFT_bottom,        /* Align to Bottom */
  XOSD_XFT_middle,        /* Align to Middle */
  XOSD_XFT_valign_none    /* Unspecified - defaults to Top */
} osd_valign;

/* Horizontal Alignment */
typedef enum
{
  XOSD_XFT_left = 0,      /* Align to Left */
  XOSD_XFT_center,        /* Align to Center */
  XOSD_XFT_right,         /* Align to Righht */
  XOSD_XFT_halign_none    /* Unspecified - defaults to Left */
} osd_halign;

osd_set_geometry() can be used to modify the geometry. If the window is already displayed, osd_set_geometry() sets the modifies the displayed window.

The osd_set_font() method is used to specify the font used for displaying the content. Setting font after the window is displayed doesn't have any effect. The font parameter is the name of the font in Xft format.

The osd_set_color(), osd_set_bgcolor() and osd_set_shadowcolor() methods are used to set the corresponding color values. Either X11 color names or values can be used for the color parameters. The alpha parameter is an integer between 0-100 and sets the transparency (0 being fully transparent, 100 opaque).

osd_set_padding is used to set the padding for the content. The padding parameter is a string and uses the CSS convention. The osd_set_number_of_lines method can be used to set the number of lines to display.

The library supports multihead displays using Xrandr or Xinerama extensions. osd_set_monitor() allows you to select a monitor to display the content. You can set monitor to ACTIVE or PRIMARY to select either active or primary monitor. Active monitor is the default. osd_set_xinerama or osd_set_xrandr are used to disable calls to either library.

EXAMPLES

The following program displays the message on the active monitor.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <xosd-xft.h>

xosd_xft *osd;

int main(int argc, char *argv[])
{
  osd_geometry g;

  xosd_xft *osd = osd_create();
  if(osd_parse_geometry("300x300+0+0*middle/center", "center/middle", &g) == NULL) {
    fprintf(stderr, "%s\n", osd_error);
    return EXIT_FAILURE;
  }
  osd_set_geometry(osd, &g);
  osd_set_font(osd, "mono:size=16");
  osd_set_color(osd, "lightblue");
  osd_set_bgcolor(osd, "black", 100);

  char* message = "HELLO XOSD-XFT" ;
  osd_display(osd, message, strlen(message));

  usleep(1000000);
  osd_destroy(osd);
  return EXIT_SUCCESS;
}

7.4 KiB Raw Blame History

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

7.4 KiB

Raw Blame History