The API is (by necessity and by design) extremely simple. It only offers access to a relatively small subset of Guppi's functionality: most of the complexity has been abstracted away in the name of stability and guaranteed future compatibility.
The automake macro AM_PATH_LIBGUPPI(min-version) will check for the presence of the appropriate Guppi libraries and will set the variables LIBGUPPI_CFLAGS and LIBGUPPI_LIBS.
To use the library, include
#include <libguppitank/guppi-tank.h>
This should be the only Guppi-related header file that you include. As long as you follow this rule, you should be able to avoid using any "non-safe" parts of Guppi.
At the beginning of your program, after calling gnome_init(), GuppiTank needs to be initialized by calling the function:
This will initialize all of the component libraries and pre-load all plug-ins; the scripting interfaces (Guile and Python) are not initialized, and are not available in GuppiTank.You can test if guppi_tank_init has been called with the function:
It is safe to call guppi_tank_init multiple times. Only the first call will actually do anything; all subsequent calls will just return harmlessly.GuppiTank had a model/view design in which the state information about plots is stored in totally opaque objects of type GuppiObject, which are derived from GtkObject.
New GuppiObjects are constructed using either the
GuppiObject *guppi_object_new
(const gchar *plot_type, double horizontal_size, double vertical_size, const gchar *arg_key, arg_value, ...);
GuppiObject *guppi_object_newv
(const gchar *plot_type, double horizontal_size, double vertical_size, guint number_of_args, GtkArg *args);
The horizontal and vertical size are measured in points: 72 points are equal to 1 inch, and approximately 28.35 points are equal to 1 cm. The argument key/value format is similar to, and is subject to all of the same caveats as, the gnome_canvas_item_new function. The list of arguments needs to be NULL-terminated, or horrible segfaults will ensue.
The currently-supported plot types are:
A description of each follows.Once you've constructed a GuppiObject, the function:
returns a standard Gtk Widget containing a graphical version of the plot. Multiple widgets can be made from the same object.A GuppiObject's plot can be printed, via gnome-print, with the function:
The printed plot will have the size specified when the object was initially constructed, and will have the lower-left corner positioned at (0,0) in the print context's current coordinate system. To reposition or rescale the plot, the print context's coordinate system should be adjusted accordingly.A very small, stand-alone example of using GuppiTank (complete with its own autoconf/automake-based build) can be found in guppi3/test-embedding on the Gnome CVS server.