Using Guppitank

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.

Automake Macros

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.

Include Files

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.

Initializing the GuppiTank Library

At the beginning of your program, after calling gnome_init(), GuppiTank needs to be initialized by calling the function:

void guppi_tank_init(void);

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:

gboolean guppi_tank_is_initialized(void);

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.

Creating Plot Objects

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, ...);

or

GuppiObject *guppi_object_newv(const gchar *plot_type, double horizontal_size, double vertical_size, guint number_of_args, GtkArg *args);

functions. If guppi_object_new or guppi_object_newv are passed any invalid inputs, they will return NULL.

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:

NameDescription
"pie"Pie Chart
"barchart"Bar Chart
"scatter"Scatter Plot

A description of each follows.

Putting Plots on the Screen

Once you've constructed a GuppiObject, the function:

GtkWidget *guppi_object_build_widget(GuppiObject *obj);

returns a standard Gtk Widget containing a graphical version of the plot. Multiple widgets can be made from the same object.

Printing Plots

A GuppiObject's plot can be printed, via gnome-print, with the function:

void guppi_object_print(GuppiObject *obj, GnomePrintContext *ctxt);

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.

Sample Code

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.