242 lines
8 KiB
Groff
242 lines
8 KiB
Groff
.\" Automatically generated by Pandoc 2.14.0.2
|
|
.\"
|
|
.TH "XOSD-XFT" "3" "Jun 28 2021" "" "XOSD-XFT Programmers Manual"
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
osd_create, osd_destroy - create and destroy osd objects
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_show, osd_hide, osd_display - display content
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_parse_geometry osd_set_geometry - set size, position and offsets
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_set_font - set font
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_set_color, osd_set_bgcolor, osd_set_shadowcolor,
|
|
osd_set_shadowoffset - color handling
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_set_padding, osd_set_number_of_lines - padding and display lines for
|
|
content
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
osd_set_monitor, osd_set_xinerama osd_set_xrandr - settings for
|
|
multihead
|
|
.SH SYNOPSIS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#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);
|
|
\f[R]
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \f[B]osd_create()\f[R] function creates a \f[C]xosd_xft\f[R] object
|
|
that is used in subsequent calls.
|
|
\f[B]osd_create()\f[R] does not allocate any X resources till a
|
|
subsequent call to \f[B]osd_display\f[R] is made.
|
|
\f[B]osd_destroy\f[R] frees the resources used during the course of
|
|
operation.
|
|
.PP
|
|
The \f[B]osd_show()\f[R] and \f[B]osd_hide()\f[R] methods are used to
|
|
display and hide the OSD window after it is shown.
|
|
These can be used only after \f[B]osd_display()\f[R] is used to display
|
|
the window.
|
|
.PP
|
|
The \f[B]osd_display()\f[R] methods adds the given line to the content.
|
|
If the window is not yet displayed, \f[B]osd_display()\f[R] initializes
|
|
the required resources and displays the window.
|
|
The settings are validated during this method call and
|
|
\f[B]display_window()\f[R] returns \f[C]-1\f[R] on error and the
|
|
\f[B]osd_error\f[R] variable contains the error message.
|
|
.PP
|
|
The \f[B]osd_parse_geometry()\f[R] is a convenience method to initialize
|
|
a \f[B]osd_geometry\f[R] object from a string representation.
|
|
The \f[B]osd_parse_geometry()\f[R] returns NULL if the string is not in
|
|
proper format.
|
|
.PP
|
|
\f[B]Geometry String Format\f[R]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
geometry: <size><offset>*<alignment>
|
|
size: <width>x<height>
|
|
The \[ga]width\[ga] is specified as an integer. It can optionally succeed
|
|
by either \[ga]%\[ga] or \[ga]c\[ga]. \[ga]%\[ga] is used to specify the width as a percentage
|
|
of the screen width. \[ga]c\[ga] is used to specify the width as number of
|
|
characters
|
|
|
|
offset: [+-]<xoffset>[+-]<yoffset>
|
|
The \[ga]xoffset\[ga] and \[ga]yoffset\[ga] 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 \[ga]valign\[ga] can be any one of \[ga]top\[ga], \[ga]middle\[ga], or \[ga]bottom\[ga]. The \[ga]halign\[ga] can
|
|
be one of \[ga]left\[ga], \[ga]center\[ga] or \[ga]right\[ga].
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
The \f[B]osd_geometry\f[R] structure holds the parsed geometry
|
|
information and can be used with a subsequent
|
|
\f[B]osd_set_geometry()\f[R] call.
|
|
.PP
|
|
\f[B]osd_geometry\f[R]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/* 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;
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
\f[B]Horizontal and Vertical Alignment Constants\f[R]
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/* 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;
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
\f[B]osd_set_geometry()\f[R] can be used to modify the geometry.
|
|
If the window is already displayed, \f[B]osd_set_geometry()\f[R] sets
|
|
the modifies the displayed window.
|
|
.PP
|
|
The \f[B]osd_set_font()\f[R] method is used to specify the font used for
|
|
displaying the content.
|
|
Setting font after the window is displayed doesn\[cq]t have any effect.
|
|
The \f[B]font\f[R] parameter is the name of the font in \f[I]Xft\f[R]
|
|
format.
|
|
.PP
|
|
The \f[B]osd_set_color()\f[R], \f[B]osd_set_bgcolor()\f[R] and
|
|
\f[B]osd_set_shadowcolor()\f[R] methods are used to set the
|
|
corresponding color values.
|
|
Either X11 color names or values can be used for the color parameters.
|
|
The \f[B]alpha\f[R] parameter is an integer between 0-100 and sets the
|
|
transparency (0 being fully transparent, 100 opaque).
|
|
.PP
|
|
\f[B]osd_set_padding\f[R] is used to set the padding for the content.
|
|
The \f[B]padding\f[R] parameter is a string and uses the CSS convention.
|
|
The \f[B]osd_set_number_of_lines\f[R] method can be used to set the
|
|
number of lines to display.
|
|
.PP
|
|
The library supports multihead displays using \f[I]Xrandr\f[R] or
|
|
\f[I]Xinerama\f[R] extensions.
|
|
\f[B]osd_set_monitor()\f[R] allows you to select a monitor to display
|
|
the content.
|
|
You can set \f[B]monitor\f[R] to \f[I]ACTIVE\f[R] or \f[I]PRIMARY\f[R]
|
|
to select either active or primary monitor.
|
|
Active monitor is the default.
|
|
\f[B]osd_set_xinerama\f[R] or \f[B]osd_set_xrandr\f[R] are used to
|
|
disable calls to either library.
|
|
.SH EXAMPLES
|
|
.PP
|
|
The following program displays the message on the active monitor.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#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(\[dq]300x300+0+0*middle/center\[dq], \[dq]center/middle\[dq], &g) == NULL) {
|
|
fprintf(stderr, \[dq]%s\[rs]n\[dq], osd_error);
|
|
return EXIT_FAILURE;
|
|
}
|
|
osd_set_geometry(osd, &g);
|
|
osd_set_font(osd, \[dq]mono:size=16\[dq]);
|
|
osd_set_color(osd, \[dq]lightblue\[dq]);
|
|
osd_set_bgcolor(osd, \[dq]black\[dq], 100);
|
|
|
|
char* message = \[dq]HELLO XOSD-XFT\[dq] ;
|
|
osd_display(osd, message, strlen(message));
|
|
|
|
usleep(1000000);
|
|
osd_destroy(osd);
|
|
return EXIT_SUCCESS;
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.SH AUTHORS
|
|
Dakshinamurthy Karra.
|