Chapter 3. Using libxosd

The XOSD library is modelled on the GTK+ libraries, in that it is an object-oriented library written in C. There are constructor functions, getter and setter functions, and destructor functions, just as you would find in a Java™ or Python module. In this chapter we will introduce XOSD by creating a small application that uses XOSD to write a message on the display.

Like all C programs, ours will begin with the basic boiler-plate code.

In the above code there are two XOSD specific lines: the inclusion of the xosd.h header, and the declaration of the osd variable. The header file is needed so we can access all the functions and type definitions associated with XOSD, and osd will be used to store all information relating to the XOSD window.

Now lets create a XOSD window (or instance). The function xosd_create will create a new window, but we must know how big the window should be. Our new window will have two lines in its display, so we pass in 2 as the argument to xosd_create. After creating the window we check to see if it was created correctly.

  osd = xosd_create (2);
  if (osd == NULL)
    {
      perror ("Could not create \"osd\"");
      exit (1);
    }
	  

Now we have to display something. The xosd_display function is the most complex of all the functions in the XOSD library. To display some data we have to say:

  • The line to modify,

  • The type of data to display, and

  • The data.

We will display the string You have been R00ted on the first line of the display, so our code will look like the following.

  xosd_display (osd, 0, XOSD_string, "You have been R00ted");
	  

Notice that osd was passed in as the first argument. All functions in the XOSD library (except for xosd_create) take a XOSD window as the first argument.

After displaying the string, all that is left to do is to wait for a few seconds before destroying the window (by calling the xosd_destroy function) and exiting the program.

  sleep (8);
  xosd_destroy (osd);
  exit (0);
}

Compiling the newly created program is a strait-forward process thanks to the xosd-config command that generates the correct arguments to GCC. Using xosd-config is similar to using pkg-config, which is used to compile programs that use the GNOME libaries: the command is placed on the GCC command-line, as shown below.

bash$ gcc `xosd-config --cflags --libs` xosd_eg1.c -o xosd_eg1

In the above code the C-file xosd_eg1.c is compiled into the executable xosd_eg1 that can be run from the command line.

bash$ ./xosd_eg1

Did you see the on-screen display? Try looking at the top-left of the display, where the words You have been R00ted will be written in small, green letters for eight seconds before the program finishes. We should make the text larger, which brings us to our next section!