GlgLineGraph: GTK/Cairo Line Graph Widget Reference Manual

GlgLineGraph

GlgLineGraph — A simple xy line graph widget written using only GTK and cairo.

Stability Level

Stable, unless otherwise indicated

Functions

GlgLineGraph *	glg_line_graph_new ()
void	glg_line_graph_redraw ()
GLGElementID	glg_line_graph_chart_get_elements ()
void	glg_line_graph_chart_set_elements ()
gboolean	glg_line_graph_chart_set_text ()
gboolean	glg_line_graph_chart_set_color ()
void	glg_line_graph_chart_set_ranges ()
void	glg_line_graph_chart_set_x_ranges ()
void	glg_line_graph_chart_set_y_ranges ()
gint	glg_line_graph_data_series_add ()
gboolean	glg_line_graph_data_series_add_value ()

Properties

gint	chart-set-elements	Write
gchar *	graph-chart-background	Write
gchar *	graph-scale-foreground	Write
gchar *	graph-title-foreground	Write
gchar *	graph-window-background	Write
gint	range-scale-major-x	Write
gint	range-scale-major-y	Write
gint	range-scale-minor-x	Write
gint	range-scale-minor-y	Write
gint	range-tick-major-x	Write
gint	range-tick-major-y	Write
gint	range-tick-minor-x	Write
gint	range-tick-minor-y	Write
gint	series-line-width	Read / Write
gchar *	text-title-main	Write
gchar *	text-title-xaxis	Write
gchar *	text-title-yaxis	Write

Signals

void

point-selected

Run First

Types and Values

struct	GlgLineGraph
enum	GLGElementID

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GlgLineGraph

Implemented Interfaces

GlgLineGraph implements AtkImplementorIface and GtkBuildable.

Includes

#include <glg_cairo.h>

Description

A Gtk+3/GLib2/Cairo GUI application which demonstrates the use of GTK+ and cairo for producing xy line graphs. This widget once created allows you to add one or more data series, then add values to those series for plotting. The X point is assumed based on arrival order. However, the Y value or position is based on the current scale and the y value itself. If the charts x scale maximum is 40, or 40 points, the 41+ value is appended to the 40th position after pos 0 is dropped - effectively rolling the x points from right to left in the chart view.

FEATURES

Unlimited data series support.
Accurate scaling across a wide range of X & Y scales.
Using values ranges above or below 1.
Rolling data points, if number of x points exceed x-scale. (left shift)
Ability to change chart background color, window backgrounds colors, etc.
Popup Tooltip, via mouse-button-1 click to enable/toggle. Tooltip overlays top graph title, when present.
Data points are time stamped with current time when added.
Auto Size to current window size; i.e. no-scrolling.

Packaged as a gtk widget for ease of use and easy inclusion into new or existing programs.

The GlgLinegraph widget has a gobject property for every control option except creating a new data series glg_line_graph_series_add(), and adding a value to that series with glg_line_graph_series_add_value().

One signal is available 'point-selected' which outputs the Y value most likely under the mouse ptr. For correlation purposes the position of the mouse and the position of the Y point is given in case two or more points are returned.

The scale or range of the chart is dependant on the Y-values. For value greater than 1, the range/scale should be set to whole numbers say 0 to 100. For values less than 1, use a range/scale of 0 to 1 .

The following api's will create a version of this line graph:

Example 1. Using a GlgLineGraph with gobject methods.

#include <gtk/gtk.h>
#include <glg_cairo.h>
...
GlgLineGraph *glg = NULL;
gint  i_series_0 = 0, i_series_1 = 0;
...
glg = glg_line_graph_new(
            "range-tick-minor-x", 1,
                                        "range-tick-major-x", 2,
                                        "range-scale-minor-x", 0,
                                        "range-scale-major-x", 40,
                                        "range-tick-minor-y", 5,
                                        "range-tick-major-y", 10,
                                        "range-scale-minor-y", 0,
                                        "range-scale-major-y", 100,
                                        "chart-set-elements", GLG_TOOLTIP |
                                        GLG_GRID_LABELS_X | GLG_GRID_LABELS_Y |
                        GLG_TITLE_T | GLG_TITLE_X | GLG_TITLE_Y |
                        GLG_GRID_LINES | GLG_GRID_MINOR_X | GLG_GRID_MAJOR_X |
                        GLG_GRID_MINOR_Y | GLG_GRID_MAJOR_Y,
                        "series-line-width", 3,
                    "graph-title-foreground",  "blue",
                                        "graph-scale-foreground",  "red",
                                        "graph-chart-background",  "light blue",
                                        "graph-window-background", "white",
                                        "text-title-main", "This Top Title Line ",
                    "text-title-yaxis", "This is the Y axis title line.",
                                "text-title-xaxis", "This is the X axis title line.",
                                NULL);

gtk_container_add (GTK_CONTAINER (window), GTK_WIDGET(glg));
gtk_widget_show_all (window);

i_series_0 = glg_line_graph_data_series_add (glg, "Volts", "red");
i_series_1 = glg_line_graph_data_series_add (glg, "Battery", "blue");

glg_line_graph_data_series_add_value (glg, i_series_0, 66.0);
glg_line_graph_data_series_add_value (glg, i_series_0, 73.0);

glg_line_graph_data_series_add_value (glg, i_series_1, 56.8);
glg_line_graph_data_series_add_value (glg, i_series_1, 83.6);


glg_line_graph_redraw ( graph );

Or the following standard api method will also work.

Example 2. Using a GlgLineGraph with standard APIs.

#include <gtk/gtk.h>
#include <glg_cairo.h>
...
GlgLineGraph *glg = NULL;
gint  i_series_0 = 0, i_series_1 = 0;
...
glg = glg_line_graph_new(NULL);

glg_line_graph_chart_set_x_ranges (glg, 1, 2,0, 40);
glg_line_graph_chart_set_y_ranges (glg, 5,10,0,100);

glg_line_graph_chart_set_elements (glg, GLG_TOOLTIP |
                                GLG_GRID_LABELS_X | GLG_GRID_LABELS_Y |
                        GLG_TITLE_T | GLG_TITLE_X | GLG_TITLE_Y |
                        GLG_GRID_LINES | GLG_GRID_MINOR_X | GLG_GRID_MAJOR_X |
                        GLG_GRID_MINOR_Y | GLG_GRID_MAJOR_Y
                                             );

glg_line_graph_chart_set_text (glg, GLG_TITLE_T, "This Top Title Line " );

glg_line_graph_chart_set_text (glg, GLG_TITLE_Y, "This is the y label." );

glg_line_graph_chart_set_text (glg, GLG_TITLE_X, "This is the x label" );

glg_line_graph_chart_set_color (glg, GLG_TITLE,  "blue");
glg_line_graph_chart_set_color (glg, GLG_SCALE,  "read");
glg_line_graph_chart_set_color (glg, GLG_CHART,  "light blue");
glg_line_graph_chart_set_color (glg, GLG_WINDOW, "white");

gtk_container_add (GTK_CONTAINER (window), GTK_WIDGET(glg));
gtk_widget_show_all (window);

i_series_0 = glg_line_graph_data_series_add (glg, "Volts", "red");
i_series_1 = glg_line_graph_data_series_add (glg, "Battery", "blue");

glg_line_graph_data_series_add_value (glg, i_series_0, 66.0);
glg_line_graph_data_series_add_value (glg, i_series_0, 73.0);

glg_line_graph_data_series_add_value (glg, i_series_1, 56.8);
glg_line_graph_data_series_add_value (glg, i_series_1, 83.6);

glg_line_graph_redraw ( glg );

A 'lgcairo.c' demonstration proram is included to illustrate how to quickly use the widget.

lgcairo.c demonstration program

C example program

Functions

glg_line_graph_new ()

GlgLineGraph *
glg_line_graph_new (const gchar *first_property_name,
                    ...);

Creates a new line graph widget

optionally accepts 'property-name, property-values',...,NULL pairs

Parameters

first_property_name	NULL or gchar pointer to first property name to set, next param must be its value
...	va_list null terminated list of additional property-name/property-value pairs

Returns

GlgLineGraph widget

glg_line_graph_redraw ()

void
glg_line_graph_redraw (GlgLineGraph *graph);

Updates the current graph showing new changes.

Parameters

graph

pointer to a GlgLineGraph widget

glg_line_graph_chart_get_elements ()

GLGElementID
glg_line_graph_chart_get_elements (GlgLineGraph *graph);

Retrieves the current draw setting for the graph. AND it with the desired value to test if what your after is present.

Parameters

graph

pointer to a GlglineGraph widget

Returns

gint containing all current draw flags as defined in GLGElementID

glg_line_graph_chart_set_elements ()

void
glg_line_graph_chart_set_elements (GlgLineGraph *graph,
                                   GLGElementID element);

Parameters

graph	pointer to a GlglineGraph widget
element	An or'ed list of GLGElementID indicating what graph elements should be drawn to the screen.

glg_line_graph_chart_set_text ()

gboolean
glg_line_graph_chart_set_text (GlgLineGraph *graph,
                               GLGElementID element,
                               const gchar *pch_text);

Copy (without freeing) pch_text into place to be used as the graph title. PangoMarkup is also supported.

GLG_TITLE_X - Bottom x axis title GLG_TITLE_Y - Left vertical y axis title GLG_TITLE_T - Top and considered main title on x axis

Parameters

graph	pointer to a GlgLineGraph widget
element	GLGElementID of the Title
pch_text	gchar* string to set in title.

Returns

gboolean TRUE if copied, FALSE if copy failed.

glg_line_graph_chart_set_color ()

gboolean
glg_line_graph_chart_set_color (GlgLineGraph *graph,
                                GLGElementID element,
                                const gchar *pch_color);

Copy (without freeing) pch_color into place to be used as the graph element color. GLG_SCALE - x/y integer legends color {default black} GLG_TITLE - Main graph title. {default light blue} GLG_WINDOW - Graph window background color, and grid foreground. {default white} GLG_CHART - Graph plot area background. {default light blue}

Parameters

graph	pointer to a GlgLineGraph widget
element	GLGElementID of the Window Element
pch_color	gchar* string with name of color.

Returns

gboolean TRUE if copied, FALSE if copy failed.

glg_line_graph_chart_set_ranges ()

void
glg_line_graph_chart_set_ranges (GlgLineGraph *graph,
                                 gint x_tick_minor,
                                 gint x_tick_major,
                                 gint x_scale_min,
                                 gint x_scale_max,
                                 gint y_tick_minor,
                                 gint y_tick_major,
                                 gint y_scale_min,
                                 gint y_scale_max);

Sets the X and Y ticks and scales for the graph grid area.

Parameters

graph	pointer to a GlgLineGraph widget
x_tick_minor	number of minor divisions for x scale
x_tick_major	number of major divisions for x scale
x_scale_min	minimum x scale value or starting point
x_scale_max	maximum x scale value or ending point
y_tick_minor	number of minor divisions for y scale
y_tick_major	number of major divisions for y scale
y_scale_min	minimum y scale value or starting point
y_scale_max	maximum y scale value or ending point

glg_line_graph_chart_set_x_ranges ()

void
glg_line_graph_chart_set_x_ranges (GlgLineGraph *graph,
                                   gint x_tick_minor,
                                   gint x_tick_major,
                                   gint x_scale_min,
                                   gint x_scale_max);

Sets the X ticks and scales for the graph grid area.

Parameters

graph	pointer to a GlgLineGraph widget
x_tick_minor	number of minor divisions for x scale
x_tick_major	number of major divisions for x scale
x_scale_min	minimum x scale value or starting point
x_scale_max	maximum x scale value or ending point

glg_line_graph_chart_set_y_ranges ()

void
glg_line_graph_chart_set_y_ranges (GlgLineGraph *graph,
                                   gint y_tick_minor,
                                   gint y_tick_major,
                                   gint y_scale_min,
                                   gint y_scale_max);

Sets the Y ticks and scales for the graph grid area.

Parameters

graph	pointer to a GlgLineGraph widget
y_tick_minor	number of minor divisions for y scale
y_tick_major	number of major divisions for y scale
y_scale_min	minimum y scale value or starting point
y_scale_max	maximum y scale value or ending point

glg_line_graph_data_series_add ()

gint
glg_line_graph_data_series_add (GlgLineGraph *graph,
                                const gchar *pch_legend_text,
                                const gchar *pch_color_text);

Allocates space for another data series of y-values and returns the series number of this dataset added which you must keep track of to add values.

Parameters

graph	pointer to a GlglineGraph widget
pch_legend_text	The name of the data series
pch_color_text	A string containing the line color to be used.

Returns

gint The series number of this dataset added ( range 0 thru n )

glg_line_graph_data_series_add_value ()

gboolean
glg_line_graph_data_series_add_value (GlgLineGraph *graph,
                                      gint i_series_number,
                                      gdouble y_value);

Add a single y value to the requested data series. auto indexes the value if x-scale max is reached (appends to the end) The X value is implied to be the current count of Y-values added.

Parameters

graph	pointer to a GlgLineGraph widget
i_series_number	The data series to add value to.
y_value	The value to add. Current range is 0.0 to y-max-scale

Returns

gboolean TRUE if value was added, FALSE if add failed.

Types and Values

struct GlgLineGraph

struct GlgLineGraph;

Main widget structure

enum GLGElementID

Communication params for interface APIs

Members

GLG_ELEMENT_NONE
GLG_TITLE_X	Enables display of the bottom chart title
GLG_NO_TITLE_X	Disables display of the bottom chart title
GLG_TITLE_Y	Enables display of the left/vertical chart title
GLG_NO_TITLE_Y	Disables display of the left/vertical chart title
GLG_TITLE_T	Enables display of the top chart title
GLG_NO_TITLE_T	Disables display of the top chart title
GLG_GRID_LABELS_X
GLG_NO_GRID_LABELS_X
GLG_GRID_LABELS_Y
GLG_NO_GRID_LABELS_Y
GLG_TOOLTIP
GLG_NO_TOOLTIP
GLG_GRID_LINES
GLG_NO_GRID_LINES
GLG_GRID_MINOR_X
GLG_NO_GRID_MINOR_X
GLG_GRID_MAJOR_X
GLG_NO_GRID_MAJOR_X
GLG_GRID_MINOR_Y
GLG_NO_GRID_MINOR_Y
GLG_GRID_MAJOR_Y
GLG_NO_GRID_MAJOR_Y
GLG_SCALE	chart color key -- used to change chart scale/labels color
GLG_TITLE	chart color key -- used to change top title color
GLG_WINDOW	chart color key -- used to change window color
GLG_CHART	chart color key -- used to change chart color
GLG_RESERVED_OFF
GLG_RESERVED_ON

Property Details

The `“chart-set-elements”` property

  “chart-set-elements”       gint

Enable showing these elements of the chart body.

Flags: Write

Allowed values: [0,65536]

Default value: 128

The `“graph-chart-background”` property

  “graph-chart-background”   gchar *

Chart inside fill color.

Flags: Write

Default value: "light blue"

The `“graph-scale-foreground”` property

  “graph-scale-foreground”   gchar *

X and Y chart scale foreground font color.

Flags: Write

Default value: "black"

The `“graph-title-foreground”` property

  “graph-title-foreground”   gchar *

Main title foreground color.

Flags: Write

Default value: "blue"

The `“graph-window-background”` property

  “graph-window-background”  gchar *

Window background fill color.

Flags: Write

Default value: "white"

The `“range-scale-major-x”` property

  “range-scale-major-x”      gint

x major scale range.

Flags: Write

Allowed values: [1,1000]

Default value: 100

The `“range-scale-major-y”` property

  “range-scale-major-y”      gint

Y major scale range.

Flags: Write

Allowed values: [1,1000]

Default value: 100

The `“range-scale-minor-x”` property

  “range-scale-minor-x”      gint

x minor scale range.

Flags: Write

Allowed values: [0,100]

Default value: 0

The `“range-scale-minor-y”` property

  “range-scale-minor-y”      gint

Y minor scale range.

Flags: Write

Allowed values: [0,100]

Default value: 0

The `“range-tick-major-x”` property

  “range-tick-major-x”       gint

x major ticks on scale.

Flags: Write

Allowed values: [1,1000]

Default value: 10

The `“range-tick-major-y”` property

  “range-tick-major-y”       gint

Y major ticks on scale.

Flags: Write

Allowed values: [1,1000]

Default value: 10

The `“range-tick-minor-x”` property

  “range-tick-minor-x”       gint

x minor ticks on scale.

Flags: Write

Allowed values: [1,100]

Default value: 5

The `“range-tick-minor-y”` property

  “range-tick-minor-y”       gint

Y minor ticks on scale.

Flags: Write

Allowed values: [1,100]

Default value: 5

The `“series-line-width”` property

  “series-line-width”        gint

Width of line drawn for data series.

Flags: Read / Write

Allowed values: [1,10]

Default value: 2

The `“text-title-main”` property

  “text-title-main”          gchar *

Title at top of graph on the X axis.

Flags: Write

Default value: "<big><b>Top Title</b></big>"

The `“text-title-xaxis”` property

  “text-title-xaxis”         gchar *

Title at bottom of graph on the X axis.

Flags: Write

Default value: "<i>X Axis Title</i>"

The `“text-title-yaxis”` property

  “text-title-yaxis”         gchar *

Title on left of graph on the Y axis.

Flags: Write

Default value: "Y Axis Title"

Signal Details

The `“point-selected”` signal

void
user_function (GlgLineGraph *widget,
               gdouble       x_value,
               gdouble       y_value,
               gdouble       point_y_pos,
               gdouble       mouse_y_pos,
               gpointer      user_data)

The ::point-selected signal is emitted after the toggle-on mouse1 click, and sends values closest to the mouse pointer.

Parameters

widget	the line graph widget that received the signal
x_value	x value on the chart
y_value	y value on the chart
point_y_pos	pixel position of y value on chart
mouse_y_pos	pixel position of the mouse ptr on chart
user_data	user data set when the signal handler was connected.

Flags: Run First

GlgLineGraph

Stability Level

Functions

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

lgcairo.c demonstration program

Functions

glg_line_graph_new ()

Parameters

Returns

glg_line_graph_redraw ()

Parameters

glg_line_graph_chart_get_elements ()

Parameters

Returns

glg_line_graph_chart_set_elements ()

Parameters

glg_line_graph_chart_set_text ()

Parameters

Returns

glg_line_graph_chart_set_color ()

Parameters

Returns

glg_line_graph_chart_set_ranges ()

Parameters

glg_line_graph_chart_set_x_ranges ()

Parameters

glg_line_graph_chart_set_y_ranges ()

Parameters

glg_line_graph_data_series_add ()

Parameters

Returns

glg_line_graph_data_series_add_value ()

Parameters

Returns

Types and Values

struct GlgLineGraph

enum GLGElementID

Members

Property Details

The “chart-set-elements” property

The “graph-chart-background” property

The “graph-scale-foreground” property

The “graph-title-foreground” property

The “graph-window-background” property

The “range-scale-major-x” property

The “range-scale-major-y” property

The “range-scale-minor-x” property

The “range-scale-minor-y” property

The “range-tick-major-x” property

The “range-tick-major-y” property

The “range-tick-minor-x” property

The “range-tick-minor-y” property

The “series-line-width” property

The “text-title-main” property

The “text-title-xaxis” property

The “text-title-yaxis” property

Signal Details

The “point-selected” signal

Parameters

See Also

The `“chart-set-elements”` property

The `“graph-chart-background”` property

The `“graph-scale-foreground”` property

The `“graph-title-foreground”` property

The `“graph-window-background”` property

The `“range-scale-major-x”` property

The `“range-scale-major-y”` property

The `“range-scale-minor-x”` property

The `“range-scale-minor-y”` property

The `“range-tick-major-x”` property

The `“range-tick-major-y”` property

The `“range-tick-minor-x”` property

The `“range-tick-minor-y”` property

The `“series-line-width”` property

The `“text-title-main”` property

The `“text-title-xaxis”` property

The `“text-title-yaxis”` property

The `“point-selected”` signal