git.cworth.org Git - acre/blob - acre.h

   1 /* acre - A cairo-based library for creating plots and charts.
   2  *
   3  * Copyright © 2009 Carl Worth <cworth@cworth.org>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  18  */
  19
  20 #ifndef ACRE_H
  21 #define ACRE_H
  22
  23 #include <pango/pangocairo.h>
  24
  25 typedef struct _acre acre_t;
  26 typedef struct _acre_data acre_data_t;
  27
  28 /* Create a new, empty plot. */
  29 acre_t *
  30 acre_create (void);
  31
  32 /* Destroy a plot. */
  33 void
  34 acre_destroy (acre_t *acre);
  35
  36 void
  37 acre_set_title (acre_t *acre, const char *title);
  38
  39 void
  40 acre_set_x_axis_label (acre_t *acre, const char *label);
  41
  42 void
  43 acre_set_y_axis_label (acre_t *acre, const char *label);
  44
  45 /* Get the range of data values in the X dimension. */
  46 void
  47 acre_get_x_axis_data_range (acre_t *acre, double *x_min, double *x_max);
  48
  49 /* Get the range of the currently viewable X axis. */
  50 void
  51 acre_get_x_axis_range (acre_t *acre, double *x_min, double *x_max);
  52
  53 /* Set the range of the currently viewable X axis. */
  54 void
  55 acre_set_x_axis_range (acre_t *acre, double x_min, double x_max);
  56
  57 /* Set the X axis viewable range to be sized automatically.
  58  *
  59  * If both X and Y axes are sized automatically, then the X range will
  60  * be set to the full range of data in the X dimension.
  61  *
  62  * But if the Y axis has been set to a limited viewable range, (with
  63  * acre_set_y_axis_range), then the X axis will be set to the
  64  * corresponding X range of data that lies within that set Y range. */
  65 void
  66 acre_set_x_axis_range_auto (acre_t *acre);
  67
  68 /* Get the range of data values in the Y dimnension. */
  69 void
  70 acre_get_y_axis_data_range (acre_t *acre, double *y_min, double *y_max);
  71
  72 /* Get the range of the currently viewable Y axis. */
  73 void
  74 acre_get_y_axis_range (acre_t *acre, double *y_min, double *y_max);
  75
  76 /* Set the range of the currently viewable Y axis. */
  77 void
  78 acre_set_y_axis_range (acre_t *acre, double y_min, double y_max);
  79
  80 /* Set the Y axis viewable range to be sized automatically.
  81  *
  82  * If both X and Y axes are sized automatically, then the Y range will
  83  * be set to the full range of data in the Y dimension.
  84  *
  85  * But if the X axis has been set to a limited viewable range, (with
  86  * acre_set_x_axis_range), then the Y axis will be set to the
  87  * corresponding Y range of data that lies within that set X range. */
  88 void
  89 acre_set_y_axis_range_auto (acre_t *acre);
  90
  91 /* Add a dataset to the plot. The plot assumes ownership of the
  92  * dataset so it is not necessary to call acre_data_destroy on it.
  93  */
  94 void
  95 acre_add_data (acre_t *acre, acre_data_t *data);
  96
  97 /* Draw the plot to the given cairo context within a user-space
  98  * rectangle from (0, 0) to (width, height). This size includes all
  99  * space for extra-plot elements (such as the title, the axis labels,
 100  * etc.)
 101  */
 102 void
 103 acre_draw (acre_t *acre, cairo_t *cr, int width, int height);
 104
 105 /* Create a new dataset---a collection of (x, y) datapoints. A single
 106  * plot can contain multiple datasets, (see acre_add_data). */
 107 acre_data_t *
 108 acre_data_create (void);
 109
 110 /* Destroy an acre dataset. Do not call this function if the dataset
 111  * has been added to an acre_t plot with acre_add_data. */
 112 void
 113 acre_data_destroy (acre_data_t *data);
 114
 115 /* The style to be used for rendering data sets. */
 116 typedef enum
 117 {
 118         /* A simple line graph connection each (X,Y) pair in order. */
 119         ACRE_STYLE_LINE,
 120
 121         /* A bar chart. */
 122         ACRE_STYLE_BARS,
 123
 124         /* Bars if there is room for them, a line otherwise. */
 125         ACRE_STYLE_BARS_OR_LINE,
 126
 127         /* A timeline.
 128          *
 129          * Each (X,Y) pair specifies the (start,stop) time of a
 130          * timeline bar.
 131          *
 132          * The acre_data_add_point_2d_named function is particularly
 133          * useful to provide a name for each timeline bar.
 134          */
 135         ACRE_STYLE_TIMELINE
 136 } acre_style_t;
 137
 138 /* Set the rendering style for this dataset. */
 139 void
 140 acre_data_set_style (acre_data_t *data, acre_style_t style);
 141
 142 /* Set the label for this dataset (to appear in the plot's key). */
 143 void
 144 acre_data_set_name (acre_data_t *data, const char *name);
 145
 146 /* Add a datapoint to the given dataset. */
 147 void
 148 acre_data_add_point_2d (acre_data_t *data, double x, double y);
 149
 150 /* Add a datapoint with a name to the given dataset. */
 151 void
 152 acre_data_add_point_2d_named (acre_data_t *data, double x, double y,
 153                               const char *name);
 154
 155 #endif /* ACRE_H */