graph: return opaque graph_label_t for each label added
[fio.git] / graph.h
1#ifndef GRAPH_H
2#define GRAPH_H
4struct graph;
8dfd6071 5struct graph_label;
af58ef32 6
8dfd6071 7typedef struct graph_label * graph_label_t;
cae08727 8
f3e8440f 9struct graph *graph_new(unsigned int xdim, unsigned int ydim, const char *font);
ba35aa8d 10/* graph_new() Returns a new graph structure of the given dimensions and font */
3ea48b88 11void graph_set_size(struct graph *g, unsigned int xdim, unsigned int ydim);
ba35aa8d 12/* graph_set_size() Changes the size of a graph to the given dimensions. */
13void graph_set_position(struct graph *g, double xoffset, double yoffset);
14/* graph_set_position() sets the x- and y-offset to translate the graph */
af58ef32 15void bar_graph_draw(struct graph *g, cairo_t *cr);
ba35aa8d 16/* bar_graph_draw() draws the given graph as a bar graph */
af58ef32 17void line_graph_draw(struct graph *g, cairo_t *cr);
ba35aa8d 18/* line_graph_draw draws the given graph as a line graph */
af58ef32 19void line_graph_set_data_count_limit(struct graph *g, int per_label_limit);
20/* line_graph_set_data_count_limit() limits the amount of data which can
21 * be added to a line graph. Once the limit is reached, the oldest data
22 * is discarded as new data is added
23 */
af58ef32 24void graph_title(struct graph *g, const char *title);
ba35aa8d 25/* graph_title() sets the main title of the graph to the given string */
af58ef32 26void graph_x_title(struct graph *g, const char *title);
ba35aa8d 27/* graph_x_title() sets the title of the x axis to the given string */
af58ef32 28void graph_y_title(struct graph *g, const char *title);
ba35aa8d 29/* graph_y_title() sets the title of the y axis to the given string */
8dfd6071 30graph_label_t graph_add_label(struct graph *g, const char *label);
31/* graph_add_label() adds a new "stream" of data to be graphed.
32 * For line charts, each label is a separate line on the graph.
33 * For bar charts, each label is a grouping of columns on the x-axis
34 * For example:
35 *
36 * | * | **
37 * | * xxxxxxxx | **
38 * | *** x | ** **
39 * | *x **** | ** ** **
40 * | xxxx* ***** | ** xx ** xx **
41 * | x ** | ** xx ** xx ** xx
42 * | x | ** xx ** xx ** xx
43 * ----------------------- -------------------------
44 * A B C
45 *
46 * For a line graph, the 'x's For a bar graph,
47 * would be on one "label", and 'A', 'B', and 'C'
48 * the '*'s would be on another are the labels.
49 * label.
50 */
8dfd6071 52int graph_add_data(struct graph *g, graph_label_t label, const double value);
ba35aa8d 53/* graph_add_data() is used to add data to the labels of a bar graph */
8dfd6071 54int graph_add_xy_data(struct graph *g, graph_label_t label,
93e2db2b 55 const double x, const double y, const char *tooltip);
56/* graph_add_xy_data is used to add data to the labels of a line graph */
8dfd6071 58void graph_set_color(struct graph *g, graph_label_t label,
af58ef32 59 double red, double green, double blue);
60#define INVISIBLE_COLOR (-1.0)
61/* graph_set_color is used to set the color used to plot the data in
62 * a line graph. INVISIBLE_COLOR can be used to plot the data invisibly.
63 * Invisible data will have the same effect on the scaling of the axes
64 * as visible data.
65 */
af58ef32 67void graph_free(struct graph *bg);
ba35aa8d 68/* free a graph allocated by graph_new() */
af58ef32 69
70typedef void (*graph_axis_unit_change_callback)(struct graph *g, int power_of_ten);
71void graph_x_axis_unit_change_notify(struct graph *g, graph_axis_unit_change_callback f);
72void graph_y_axis_unit_change_notify(struct graph *g, graph_axis_unit_change_callback f);
73/* The labels used on the x and y axes may be shortened. You can register for callbacks
74 * so that you can know how the labels are shorted, typically used to adjust the axis
75 * titles to display the proper units. The power_of_ten parameter indicates what power
76 * of ten the labels have been divided by (9, 6, 3, or 0, corresponding to billions,
77 * millions, thousands and ones.
78 */
af58ef32 79
80void graph_add_extra_space(struct graph *g, double left_percent, double right_percent,
81 double top_percent, double bottom_percent);
82/* graph_add_extra_space() adds extra space to edges of the the graph
83 * so that the data doesn't go to the very edges.
84 */
86extern int graph_has_tooltips(struct graph *g);
87extern const char *graph_find_tooltip(struct graph *g, int x, int y);
88extern int graph_contains_xy(struct graph *p, int x, int y);
d8fbeefb 90extern void graph_set_base_offset(struct graph *g, unsigned int base_offset);
01a947f0 91extern void graph_set_graph_all_zeroes(struct graph *g, unsigned int set);
d8fbeefb 92