GtkDatabox

GtkDatabox — A GTK+ widget to display large amounts of numerical data quickly and easily.

Synopsis


#include <gtkdatabox.h>

                    GtkDataboxPrivate;
                    GtkDatabox;
GtkWidget*          gtk_databox_new                     (void);
gint                gtk_databox_graph_add               (GtkDatabox *box,
                                                         GtkDataboxGraph *graph);
gint                gtk_databox_graph_remove            (GtkDatabox *box,
                                                         GtkDataboxGraph *graph);
gint                gtk_databox_graph_remove_all        (GtkDatabox *box);
gint                gtk_databox_auto_rescale            (GtkDatabox *box,
                                                         gfloat border);
gint                gtk_databox_calculate_extrema       (GtkDatabox *box,
                                                         gfloat *min_x,
                                                         gfloat *max_x,
                                                         gfloat *min_y,
                                                         gfloat *max_y);
void                gtk_databox_set_total_limits        (GtkDatabox *box,
                                                         gfloat left,
                                                         gfloat right,
                                                         gfloat top,
                                                         gfloat bottom);
void                gtk_databox_set_visible_limits      (GtkDatabox *box,
                                                         gfloat left,
                                                         gfloat right,
                                                         gfloat top,
                                                         gfloat bottom);
void                gtk_databox_get_total_limits        (GtkDatabox *box,
                                                         gfloat *left,
                                                         gfloat *right,
                                                         gfloat *top,
                                                         gfloat *bottom);
void                gtk_databox_get_visible_limits      (GtkDatabox *box,
                                                         gfloat *left,
                                                         gfloat *right,
                                                         gfloat *top,
                                                         gfloat *bottom);
void                gtk_databox_set_adjustment_x        (GtkDatabox *box,
                                                         GtkAdjustment *adj);
void                gtk_databox_set_adjustment_y        (GtkDatabox *box,
                                                         GtkAdjustment *adj);
GtkAdjustment*      gtk_databox_get_adjustment_x        (GtkDatabox *box);
GtkAdjustment*      gtk_databox_get_adjustment_y        (GtkDatabox *box);
void                gtk_databox_set_ruler_x             (GtkDatabox *box,
                                                         GtkDataboxRuler *ruler);
void                gtk_databox_set_ruler_y             (GtkDatabox *box,
                                                         GtkDataboxRuler *ruler);
GtkDataboxRuler*    gtk_databox_get_ruler_x             (GtkDatabox *box);
GtkDataboxRuler*    gtk_databox_get_ruler_y             (GtkDatabox *box);
void                gtk_databox_set_scale_type_x        (GtkDatabox *box,
                                                         GtkDataboxScaleType scale_type);
void                gtk_databox_set_scale_type_y        (GtkDatabox *box,
                                                         GtkDataboxScaleType scale_type);
GtkDataboxScaleType gtk_databox_get_scale_type_x        (GtkDatabox *box);
GtkDataboxScaleType gtk_databox_get_scale_type_y        (GtkDatabox *box);
void                gtk_databox_set_enable_selection    (GtkDatabox *box,
                                                         gboolean enable);
void                gtk_databox_set_enable_zoom         (GtkDatabox *box,
                                                         gboolean enable);
gboolean            gtk_databox_get_enable_selection    (GtkDatabox *box);
gboolean            gtk_databox_get_enable_zoom         (GtkDatabox *box);
void                gtk_databox_zoom_to_selection       (GtkDatabox *box);
void                gtk_databox_zoom_out                (GtkDatabox *box);
void                gtk_databox_zoom_home               (GtkDatabox *box);
gint16              gtk_databox_value_to_pixel_x        (GtkDatabox *box,
                                                         gfloat value);
gint16              gtk_databox_value_to_pixel_y        (GtkDatabox *box,
                                                         gfloat value);
gfloat              gtk_databox_pixel_to_value_x        (GtkDatabox *box,
                                                         gint16 pixel);
gfloat              gtk_databox_pixel_to_value_y        (GtkDatabox *box,
                                                         gint16 pixel);
void                gtk_databox_values_to_pixels        (GtkDatabox *box,
                                                         guint len,
                                                         const gfloat *values_x,
                                                         const gfloat *values_y,
                                                         GdkPoint *pixels);
void                gtk_databox_create_box_with_scrollbars_and_rulers
                                                        (GtkWidget **p_box,
                                                         GtkWidget **p_table,
                                                         gboolean scrollbar_x,
                                                         gboolean scrollbar_y,
                                                         gboolean ruler_x,
                                                         gboolean ruler_y);
GdkPixmap*          gtk_databox_get_backing_pixmap      (GtkDatabox *box);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkDatabox

Implemented Interfaces

GtkDatabox implements AtkImplementorIface and GtkBuildable.

Properties

  "adjustment-x"             GtkAdjustment*        : Read / Write / Construct
  "adjustment-y"             GtkAdjustment*        : Read / Write / Construct
  "enable-selection"         gboolean              : Read / Write / Construct
  "enable-zoom"              gboolean              : Read / Write / Construct
  "ruler-x"                  GtkDataboxRuler*      : Read / Write / Construct
  "ruler-y"                  GtkDataboxRuler*      : Read / Write / Construct
  "scale-type-x"             GtkDataboxScaleType   : Read / Write / Construct
  "scale-type-y"             GtkDataboxScaleType   : Read / Write / Construct

Signals

  "selection-canceled"                             : Run First
  "selection-changed"                              : Run First
  "selection-finalized"                            : Run First
  "selection-started"                              : Run First
  "zoomed"                                         : Run First

Description

GtkDatabox is a widget for the GTK+ library designed to display large amounts of numerical data quickly and easily. It allows for one or more data sets of thousands of data points (X and Y coordinates) to be displayed and updated in split seconds.

It offers the ability to zoom into and out of the data, and to navigate through your data by scrolling.

In addition to rulers and a simple coordinate cross, it allows you to add one (or even more) configurable grids like on an oscilloscope.

Data may be presented as dots, lines connecting the data, or vertical bars. The widget allows you to easily transform pixel coordinates into data coordinates, thus allowing you to easily create powerful applications for data analysis.

Details

GtkDataboxPrivate

typedef struct _GtkDataboxPrivate GtkDataboxPrivate;

A private data structure used by the GtkDatabox. It shields all internal things from developers who are just using the widget.


GtkDatabox

typedef struct _GtkDatabox GtkDatabox;

A GTK+ widget to display large amounts of numerical data quickly and easily. The numerical data is represented/displayed by GtkDataboxGraph objects, e.g. GtkDataboxPoints.

Implemented by _GtkDatabox;


gtk_databox_new ()

GtkWidget*          gtk_databox_new                     (void);

Creates a new GtkDatabox widget.

Returns :

The new GtkDatabox widget.

gtk_databox_graph_add ()

gint                gtk_databox_graph_add               (GtkDatabox *box,
                                                         GtkDataboxGraph *graph);

Adds the graph to the box. The next time the box is re-drawn, the graph will be shown.

It might be becessary to modify the total_limits in order for the graph to be displayed properly (see gtk_databox_set_total_limits()).

box :

A GtkDatabox widget

graph :

A graph, e.g. a GtkDataboxPoints or a GtkDataboxGrid object

Returns :

0 on success, -1 otherwise

gtk_databox_graph_remove ()

gint                gtk_databox_graph_remove            (GtkDatabox *box,
                                                         GtkDataboxGraph *graph);

Removes the graph from the box once. The next time the box is re-drawn, the graph will not be shown (unless it was added more than once).

box :

A GtkDatabox widget

graph :

A graph, e.g. a GtkDataboxPoints or a GtkDataboxGrid object

Returns :

0 on success, -1 otherwise

gtk_databox_graph_remove_all ()

gint                gtk_databox_graph_remove_all        (GtkDatabox *box);

Removes all graphs from the box. The next time the box is re-drawn, no graphs will be shown.

box :

A GtkDatabox widget

Returns :

0 on success, -1 otherwise

gtk_databox_auto_rescale ()

gint                gtk_databox_auto_rescale            (GtkDatabox *box,
                                                         gfloat border);

This function is similar to gtk_databox_set_total_limits(). It sets the total limits to match the data extrema (see gtk_databox_calculate_extrema()). If you do not like data pixels exactly at the widget's border, you can add modify the limits using the border parameter: The limits are extended by border*(max-min) if max!=min. If max==min, they are extended by border*max (otherwise the data could not be scaled to the pixel realm).

After calling this function, x values grow from left to right, y values grow from bottom to top.

box :

A GtkDatabox widget

border :

Relative border width (e.g. 0.1 means that the border on each side is 10% of the data area).

Returns :

0 on success, -1 if box is no GtkDatabox widget, -2 if no datasets are available

gtk_databox_calculate_extrema ()

gint                gtk_databox_calculate_extrema       (GtkDatabox *box,
                                                         gfloat *min_x,
                                                         gfloat *max_x,
                                                         gfloat *min_y,
                                                         gfloat *max_y);

Determines the minimum and maximum x and y values of all GtkDataboxGraph objects which have been added to the GtkDatabox widget via gtk_databox_graph_add().

box :

A GtkDatabox widget

min_x :

Will be filled with the lowest x value of all datasets

max_x :

Will be filled with the highest x value of all datasets

min_y :

Will be filled with the lowest y value of all datasets

max_y :

Will be filled with the highest y value of all datasets

Returns :

0 on success, -1 if box is no GtkDatabox widget, -2 if no datasets are available

gtk_databox_set_total_limits ()

void                gtk_databox_set_total_limits        (GtkDatabox *box,
                                                         gfloat left,
                                                         gfloat right,
                                                         gfloat top,
                                                         gfloat bottom);

This function is used to set the limits of the total display area of box. This function can be used to invert the orientation of the displayed graphs, e.g. top=-1000 and bottom=0.

Side effect: The box also internally calls gtk_databox_set_visible_limits() with the same values.

box :

A GtkDatabox widget

left :

Left total limit

right :

Right total limit

top :

Top total limit

bottom :

Bottom total limit

gtk_databox_set_visible_limits ()

void                gtk_databox_set_visible_limits      (GtkDatabox *box,
                                                         gfloat left,
                                                         gfloat right,
                                                         gfloat top,
                                                         gfloat bottom);

This function is used to set the limits of the visible display area of box. The visible display area can be section of the total area, i.e. the box zooms in, showing only a part of the complete picture.

The orientation of the values have to be the same as in gtk_databox_set_total_limits() and the visible limits have to be within the total limits. The values will not be used otherwise.

Side effect: The box emits "zoomed".

box :

A GtkDatabox widget

left :

Left visible limit

right :

Right visible limit

top :

Top visible limit

bottom :

Bottom visible limit

gtk_databox_get_total_limits ()

void                gtk_databox_get_total_limits        (GtkDatabox *box,
                                                         gfloat *left,
                                                         gfloat *right,
                                                         gfloat *top,
                                                         gfloat *bottom);

Gives the total limits (as set by gtk_databox_auto_rescale() or gtk_databox_set_total_limits()).

box :

A GtkDatabox widget

left :

Space for total left value or NULL

right :

Space for total right value or NULL

top :

Space for total top value or NULL

bottom :

Space for total bottom value or NULL

gtk_databox_get_visible_limits ()

void                gtk_databox_get_visible_limits      (GtkDatabox *box,
                                                         gfloat *left,
                                                         gfloat *right,
                                                         gfloat *top,
                                                         gfloat *bottom);

Gives the current visible limits. These differ from those given by gtk_databox_get_total_limits() if you zoomed into the data for instance by gtk_databox_zoom_to_selection() or gtk_databox_set_visible_limits() (these values can be changed by scrolling, of course).

box :

A GtkDatabox widget

left :

Space for visible left value or NULL

right :

Space for visible right value or NULL

top :

Space for visible top value or NULL

bottom :

Space for visible bottom value or NULL

gtk_databox_set_adjustment_x ()

void                gtk_databox_set_adjustment_x        (GtkDatabox *box,
                                                         GtkAdjustment *adj);

Setter function for the "adjustment-x" property. Normally, it should not be required to use this function, see property documentation.

box :

A GtkDatabox widget

adj :

A GtkAdjustment object

gtk_databox_set_adjustment_y ()

void                gtk_databox_set_adjustment_y        (GtkDatabox *box,
                                                         GtkAdjustment *adj);

Setter function for the "adjustment-y" property. Normally, it should not be required to use this function, see property documentation.

box :

A GtkDatabox widget

adj :

A GtkAdjustment object

gtk_databox_get_adjustment_x ()

GtkAdjustment*      gtk_databox_get_adjustment_x        (GtkDatabox *box);

Getter function for the "adjustment-x" property.

box :

A GtkDatabox widget.

Returns :

The "adjustment-x" property value.

gtk_databox_get_adjustment_y ()

GtkAdjustment*      gtk_databox_get_adjustment_y        (GtkDatabox *box);

Getter function for the "adjustment-y" property.

box :

A GtkDatabox widget.

Returns :

The "adjustment-y" property value.

gtk_databox_set_ruler_x ()

void                gtk_databox_set_ruler_x             (GtkDatabox *box,
                                                         GtkDataboxRuler *ruler);

Setter function for the "ruler-x" property.

box :

A GtkDatabox widget

ruler :

A GtkDataboxRuler object

gtk_databox_set_ruler_y ()

void                gtk_databox_set_ruler_y             (GtkDatabox *box,
                                                         GtkDataboxRuler *ruler);

Setter function for the "ruler-y" property.

box :

A GtkDatabox widget

ruler :

An GtkDataboxRuler object

gtk_databox_get_ruler_x ()

GtkDataboxRuler*    gtk_databox_get_ruler_x             (GtkDatabox *box);

Getter function for the "ruler-x" property.

box :

A GtkDatabox widget.

Returns :

The "ruler-x" property value.

gtk_databox_get_ruler_y ()

GtkDataboxRuler*    gtk_databox_get_ruler_y             (GtkDatabox *box);

Getter function for the "ruler-y" property.

box :

A GtkDatabox widget.

Returns :

The "ruler-y" property value.

gtk_databox_set_scale_type_x ()

void                gtk_databox_set_scale_type_x        (GtkDatabox *box,
                                                         GtkDataboxScaleType scale_type);

Setter function for the "scale-type-x" property.

box :

A GtkDatabox widget

scale_type :

An GtkDataboxScaleType (linear or logarithmic)

gtk_databox_set_scale_type_y ()

void                gtk_databox_set_scale_type_y        (GtkDatabox *box,
                                                         GtkDataboxScaleType scale_type);

Setter function for the "scale-type-y" property.

box :

A GtkDatabox widget

scale_type :

An GtkDataboxScaleType (linear or logarithmic)

gtk_databox_get_scale_type_x ()

GtkDataboxScaleType gtk_databox_get_scale_type_x        (GtkDatabox *box);

Getter function for the "scale-type-x" property.

box :

A GtkDatabox widget.

Returns :

The "scale-type-x" property value.

gtk_databox_get_scale_type_y ()

GtkDataboxScaleType gtk_databox_get_scale_type_y        (GtkDatabox *box);

Getter function for the "scale-type-y" property.

box :

A GtkDatabox widget.

Returns :

The "scale-type-y" property value.

gtk_databox_set_enable_selection ()

void                gtk_databox_set_enable_selection    (GtkDatabox *box,
                                                         gboolean enable);

Setter function for the "enable-selection" property.

box :

A GtkDatabox widget

enable :

Whether selection via mouse is enabled or not.

gtk_databox_set_enable_zoom ()

void                gtk_databox_set_enable_zoom         (GtkDatabox *box,
                                                         gboolean enable);

Setter function for the "enable-zoom" property.

box :

A GtkDatabox widget

enable :

Whether zoom via mouse is enabled or not.

gtk_databox_get_enable_selection ()

gboolean            gtk_databox_get_enable_selection    (GtkDatabox *box);

Getter function for the "enable-selection" property.

box :

A GtkDatabox widget.

Returns :

The "enable-selection" property value.

gtk_databox_get_enable_zoom ()

gboolean            gtk_databox_get_enable_zoom         (GtkDatabox *box);

Getter function for the "enable-zoom" property.

box :

A GtkDatabox widget.

Returns :

The "enable-zoom" property value.

gtk_databox_zoom_to_selection ()

void                gtk_databox_zoom_to_selection       (GtkDatabox *box);

This is equivalent to left-clicking into the selected area.

This function works, if the attribute enable-zoom is set to TRUE. Calling the function then zooms to the area selected with the mouse.

Side effect: The box emits "zoomed".

box :

A GtkDatabox widget

gtk_databox_zoom_out ()

void                gtk_databox_zoom_out                (GtkDatabox *box);

This is equivalent to right-clicking into the box.

This function works, if the attribute enable-zoom is set to TRUE. Calling the function then zooms out by a factor of 2 in both dimensions (the maximum is defined by the total limits, see gtk_databox_set_total_limits()).

Side effect: The box emits "zoomed".

box :

A GtkDatabox widget

gtk_databox_zoom_home ()

void                gtk_databox_zoom_home               (GtkDatabox *box);

This is equivalent to shift right-clicking into the box.

This function works, if the attribute enable-zoom is set to TRUE. It is equivalent to calling the gtk_databox_set_visible_limits() with the total limits.

box :

A GtkDatabox widget

gtk_databox_value_to_pixel_x ()

gint16              gtk_databox_value_to_pixel_x        (GtkDatabox *box,
                                                         gfloat value);

Calculates the horizontal pixel coordinate which represents the x value. Pixel coordinates are relative to the top-left corner of the box which is equivalent to (0,0).

box :

A GtkDatabox widget

value :

An x value

Returns :

Pixel coordinate

gtk_databox_value_to_pixel_y ()

gint16              gtk_databox_value_to_pixel_y        (GtkDatabox *box,
                                                         gfloat value);

Calculates the vertical pixel coordinate which represents the y value. Pixel coordinates are relative to the top-left corner of the box which is equivalent to (0,0).

box :

A GtkDatabox widget

value :

A y value

Returns :

Pixel coordinate

gtk_databox_pixel_to_value_x ()

gfloat              gtk_databox_pixel_to_value_x        (GtkDatabox *box,
                                                         gint16 pixel);

Calculates the x value which is represented by the horizontal pixel coordinate. Pixel coordinates are relative to the top-left corner of the box which is equivalent to (0,0).

box :

A GtkDatabox widget

pixel :

A horizontal pixel coordinate

Returns :

x value

gtk_databox_pixel_to_value_y ()

gfloat              gtk_databox_pixel_to_value_y        (GtkDatabox *box,
                                                         gint16 pixel);

Calculates the y value which is represented by the vertical pixel coordinate. Pixel coordinates are relative to the top-left corner of the box which is equivalent to (0,0).

box :

A GtkDatabox widget

pixel :

A vertical pixel coordinate

Returns :

y value

gtk_databox_values_to_pixels ()

void                gtk_databox_values_to_pixels        (GtkDatabox *box,
                                                         guint len,
                                                         const gfloat *values_x,
                                                         const gfloat *values_y,
                                                         GdkPoint *pixels);

Calculates the pixel equivalents of the given X/Y values and stores them in the pixels array.

box :

A GtkDatabox widget

len :

Number of values/pixels

values_x :

Array of X values (length >= len)

values_y :

Array of Y values (length >= len)

pixels :

Array of pixel coordinates (length >= len)

gtk_databox_create_box_with_scrollbars_and_rulers ()

void                gtk_databox_create_box_with_scrollbars_and_rulers
                                                        (GtkWidget **p_box,
                                                         GtkWidget **p_table,
                                                         gboolean scrollbar_x,
                                                         gboolean scrollbar_y,
                                                         gboolean ruler_x,
                                                         gboolean ruler_y);

This is a convenience function which creates a GtkDatabox widget in a GtkTable widget optionally accompanied by scrollbars and rulers. You only have to fill in the data (gtk_databox_graph_add()) and adjust the limits (gtk_databox_set_total_limits() or gtk_databox_auto_rescale()).

see_also: gtk_databox_new(), gtk_databox_set_adjustment_x(), gtk_databox_set_adjustment_y(), gtk_databox_set_ruler_x(), gtk_databox_set_ruler_y()

p_box :

Will contain a pointer to a GtkDatabox widget

p_table :

Will contain a pointer to a GtkTable widget

scrollbar_x :

Whether to attach a horizontal scrollbar

scrollbar_y :

Whether to attach a vertical scrollbar

ruler_x :

Whether to attach a horizontal ruler

ruler_y :

Whether to attach a vertical ruler

gtk_databox_get_backing_pixmap ()

GdkPixmap*          gtk_databox_get_backing_pixmap      (GtkDatabox *box);

This function returns the pixmap which is used by box and its GtkDataboxGraph objects for drawing operations before copying the result to the screen.

The function is typically called by the GtkDataboxGraph objects.

box :

A GtkDatabox widget

Returns :

Backing pixmap

Property Details

The "adjustment-x" property

  "adjustment-x"             GtkAdjustment*        : Read / Write / Construct

GtkAdjustment for horizontal scrolling.


The "adjustment-y" property

  "adjustment-y"             GtkAdjustment*        : Read / Write / Construct

GtkAdjustment for vertical scrolling.


The "enable-selection" property

  "enable-selection"         gboolean              : Read / Write / Construct

Defines whether the user can select rectangular areas with the mouse (TRUE) or not (FALSE).

Default value: TRUE


The "enable-zoom" property

  "enable-zoom"              gboolean              : Read / Write / Construct

Defines whether the user can use the mouse to zoom in or out (TRUE) or not (FALSE).

Default value: TRUE


The "ruler-x" property

  "ruler-x"                  GtkDataboxRuler*      : Read / Write / Construct

A horizontal GtkDataboxRuler or NULL.


The "ruler-y" property

  "ruler-y"                  GtkDataboxRuler*      : Read / Write / Construct

A vertical GtkDataboxRuler or NULL.


The "scale-type-x" property

  "scale-type-x"             GtkDataboxScaleType   : Read / Write / Construct

Horizontal scale type (linear or logarithmic).

Default value: GTK_DATABOX_SCALE_LINEAR


The "scale-type-y" property

  "scale-type-y"             GtkDataboxScaleType   : Read / Write / Construct

Vertical scale type (linear or logarithmic).

Default value: GTK_DATABOX_SCALE_LINEAR

Signal Details

The "selection-canceled" signal

void                user_function                      (GtkDatabox *box,
                                                        gpointer    user_data)      : Run First

This signal is emitted after a right click outside a selection rectangle.

@:

box :

The GtkDatabox widget which zoomed in or out.

user_data :

user data set when the signal handler was connected.

The "selection-changed" signal

void                user_function                      (GtkDatabox *box,
                                                        gpointer    selection_values,
                                                        gpointer    user_data)             : Run First

This signal is emitted when the mouse is moved with the left button pressed (and the "enable-selection" property is set). The corners of the selection rectangle are stored in selection_values.

@: @:

box :

The GtkDatabox widget in which the selection was changed.

selection_values :

The corners of the selection rectangle.

user_data :

user data set when the signal handler was connected.

The "selection-finalized" signal

void                user_function                      (GtkDatabox *box,
                                                        gpointer    selection_values,
                                                        gpointer    user_data)             : Run First

This signal is emitted when the left mouse button is released after a selection was started before.

see_also: "selection-changed"

@: @:

box :

The GtkDatabox widget in which the selection has been stopped.

selection_values :

The corners of the selection rectangle.

user_data :

user data set when the signal handler was connected.

The "selection-started" signal

void                user_function                      (GtkDatabox *box,
                                                        gpointer    selection_values,
                                                        gpointer    user_data)             : Run First

This signal is emitted when the mouse is firstmoved with the left button pressed after the mouse-down (and the "enable-selection" property is set). The corners of the selection rectangle are stored in selection_values.

see_also: "selection-changed"

@: @:

box :

The GtkDatabox widget in which the selection has been started.

selection_values :

The corners of the selection rectangle.

user_data :

user data set when the signal handler was connected.

The "zoomed" signal

void                user_function                      (GtkDatabox *box,
                                                        gpointer    user_data)      : Run First

This signal is emitted each time the zoom of the widget is changed, see for example gtk_databox_zoom_to_selection(), gtk_databox_set_visible_limits().

@:

box :

The GtkDatabox widget which zoomed in or out.

user_data :

user data set when the signal handler was connected.

See Also

GtkDataboxGraph, GtkDataboxPoints, GtkDataboxLines, GtkDataboxMarkers, GtkDataboxGrid