![]() |
![]() |
![]() |
GtkDatabox Reference Manual | ![]() |
---|---|---|---|---|
GtkDataboxGtkDatabox — A GTK+ widget to display large amounts of numerical data quickly and easily. |
#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);
"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
"selection-canceled" : Run First "selection-changed" : Run First "selection-finalized" : Run First "selection-started" : Run First "zoomed" : Run First
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.
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.
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;
GtkWidget* gtk_databox_new (void);
Creates a new GtkDatabox widget.
Returns : |
The new GtkDatabox widget. |
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()
).
|
A GtkDatabox widget |
|
A graph, e.g. a GtkDataboxPoints or a GtkDataboxGrid object |
Returns : |
0 on success, -1 otherwise |
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).
|
A GtkDatabox widget |
|
A graph, e.g. a GtkDataboxPoints or a GtkDataboxGrid object |
Returns : |
0 on success, -1 otherwise |
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.
|
A GtkDatabox widget |
Returns : |
0 on success, -1 otherwise |
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.
|
A GtkDatabox widget |
|
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
|
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()
.
|
A GtkDatabox widget |
|
Will be filled with the lowest x value of all datasets |
|
Will be filled with the highest x value of all datasets |
|
Will be filled with the lowest y value of all datasets |
|
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
|
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.
|
A GtkDatabox widget |
|
Left total limit |
|
Right total limit |
|
Top total limit |
|
Bottom total limit |
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".
|
A GtkDatabox widget |
|
Left visible limit |
|
Right visible limit |
|
Top visible limit |
|
Bottom visible limit |
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()
).
|
A GtkDatabox widget |
|
Space for total left value or NULL |
|
Space for total right value or NULL |
|
Space for total top value or NULL |
|
Space for total bottom value or NULL |
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).
|
A GtkDatabox widget |
|
Space for visible left value or NULL |
|
Space for visible right value or NULL |
|
Space for visible top value or NULL |
|
Space for visible bottom value or NULL |
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.
|
A GtkDatabox widget |
|
A GtkAdjustment object |
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.
|
A GtkDatabox widget |
|
A GtkAdjustment object |
GtkAdjustment* gtk_databox_get_adjustment_x (GtkDatabox *box);
Getter function for the "adjustment-x" property.
|
A GtkDatabox widget. |
Returns : |
The "adjustment-x" property value. |
GtkAdjustment* gtk_databox_get_adjustment_y (GtkDatabox *box);
Getter function for the "adjustment-y" property.
|
A GtkDatabox widget. |
Returns : |
The "adjustment-y" property value. |
void gtk_databox_set_ruler_x (GtkDatabox *box, GtkDataboxRuler *ruler);
Setter function for the "ruler-x" property.
|
A GtkDatabox widget |
|
A GtkDataboxRuler object |
void gtk_databox_set_ruler_y (GtkDatabox *box, GtkDataboxRuler *ruler);
Setter function for the "ruler-y" property.
|
A GtkDatabox widget |
|
An GtkDataboxRuler object |
GtkDataboxRuler* gtk_databox_get_ruler_x (GtkDatabox *box);
Getter function for the "ruler-x" property.
|
A GtkDatabox widget. |
Returns : |
The "ruler-x" property value. |
GtkDataboxRuler* gtk_databox_get_ruler_y (GtkDatabox *box);
Getter function for the "ruler-y" property.
|
A GtkDatabox widget. |
Returns : |
The "ruler-y" property value. |
void gtk_databox_set_scale_type_x (GtkDatabox *box, GtkDataboxScaleType scale_type);
Setter function for the "scale-type-x" property.
|
A GtkDatabox widget |
|
An GtkDataboxScaleType (linear or logarithmic) |
void gtk_databox_set_scale_type_y (GtkDatabox *box, GtkDataboxScaleType scale_type);
Setter function for the "scale-type-y" property.
|
A GtkDatabox widget |
|
An GtkDataboxScaleType (linear or logarithmic) |
GtkDataboxScaleType gtk_databox_get_scale_type_x (GtkDatabox *box);
Getter function for the "scale-type-x" property.
|
A GtkDatabox widget. |
Returns : |
The "scale-type-x" property value. |
GtkDataboxScaleType gtk_databox_get_scale_type_y (GtkDatabox *box);
Getter function for the "scale-type-y" property.
|
A GtkDatabox widget. |
Returns : |
The "scale-type-y" property value. |
void gtk_databox_set_enable_selection (GtkDatabox *box, gboolean enable);
Setter function for the "enable-selection" property.
|
A GtkDatabox widget |
|
Whether selection via mouse is enabled or not. |
void gtk_databox_set_enable_zoom (GtkDatabox *box, gboolean enable);
Setter function for the "enable-zoom" property.
|
A GtkDatabox widget |
|
Whether zoom via mouse is enabled or not. |
gboolean gtk_databox_get_enable_selection (GtkDatabox *box);
Getter function for the "enable-selection" property.
|
A GtkDatabox widget. |
Returns : |
The "enable-selection" property value. |
gboolean gtk_databox_get_enable_zoom (GtkDatabox *box);
Getter function for the "enable-zoom" property.
|
A GtkDatabox widget. |
Returns : |
The "enable-zoom" property value. |
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".
|
A GtkDatabox widget |
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".
|
A GtkDatabox widget |
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.
|
A GtkDatabox widget |
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).
|
A GtkDatabox widget |
|
An x value |
Returns : |
Pixel coordinate |
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).
|
A GtkDatabox widget |
|
A y value |
Returns : |
Pixel coordinate |
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).
|
A GtkDatabox widget |
|
A horizontal pixel coordinate |
Returns : |
x value |
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).
|
A GtkDatabox widget |
|
A vertical pixel coordinate |
Returns : |
y value |
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.
|
A GtkDatabox widget |
|
Number of values/pixels |
|
Array of X values (length >= len) |
|
Array of Y values (length >= len) |
|
Array of pixel coordinates (length >= len) |
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()
|
Will contain a pointer to a GtkDatabox widget |
|
Will contain a pointer to a GtkTable widget |
|
Whether to attach a horizontal scrollbar |
|
Whether to attach a vertical scrollbar |
|
Whether to attach a horizontal ruler |
|
Whether to attach a vertical ruler |
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.
|
A GtkDatabox widget |
Returns : |
Backing pixmap |
"adjustment-x"
property"adjustment-x" GtkAdjustment* : Read / Write / Construct
GtkAdjustment for horizontal scrolling.
"adjustment-y"
property"adjustment-y" GtkAdjustment* : Read / Write / Construct
GtkAdjustment for vertical scrolling.
"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
"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
"ruler-x"
property"ruler-x" GtkDataboxRuler* : Read / Write / Construct
A horizontal GtkDataboxRuler or NULL.
"ruler-y"
property"ruler-y" GtkDataboxRuler* : Read / Write / Construct
A vertical GtkDataboxRuler or NULL.
"scale-type-x"
property"scale-type-x" GtkDataboxScaleType : Read / Write / Construct
Horizontal scale type (linear or logarithmic).
Default value: GTK_DATABOX_SCALE_LINEAR
"scale-type-y"
property"scale-type-y" GtkDataboxScaleType : Read / Write / Construct
Vertical scale type (linear or logarithmic).
Default value: GTK_DATABOX_SCALE_LINEAR
"selection-canceled"
signalvoid user_function (GtkDatabox *box, gpointer user_data) : Run First
This signal is emitted after a right click outside a selection rectangle.
@:
|
The GtkDatabox widget which zoomed in or out. |
|
user data set when the signal handler was connected. |
"selection-changed"
signalvoid 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
.
@: @:
|
The GtkDatabox widget in which the selection was changed. |
|
The corners of the selection rectangle. |
|
user data set when the signal handler was connected. |
"selection-finalized"
signalvoid 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"
@: @:
|
The GtkDatabox widget in which the selection has been stopped. |
|
The corners of the selection rectangle. |
|
user data set when the signal handler was connected. |
"selection-started"
signalvoid 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"
@: @:
|
The GtkDatabox widget in which the selection has been started. |
|
The corners of the selection rectangle. |
|
user data set when the signal handler was connected. |
"zoomed"
signalvoid 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()
.
@:
|
The GtkDatabox widget which zoomed in or out. |
|
user data set when the signal handler was connected. |