GwyGraphModel: Gwyddion Widgets Library Reference Manual

GwyGraphModel

GwyGraphModel — Representation of a graph

Functions

GwyGraphModel *	gwy_graph_model_new ()
GwyGraphModel *	gwy_graph_model_new_alike ()
GwyGraphModel *	gwy_graph_model_copy ()
void	gwy_graph_model_assign ()
gint	gwy_graph_model_get_n_curves ()
gint	gwy_graph_model_add_curve ()
gint	gwy_graph_model_remove_curve_by_description ()
void	gwy_graph_model_remove_curve ()
GwyGraphCurveModel *	gwy_graph_model_get_curve_by_description ()
GwyGraphCurveModel *	gwy_graph_model_get_curve ()
gint	gwy_graph_model_get_curve_index ()
void	gwy_graph_model_replace_curve ()
void	gwy_graph_model_remove_all_curves ()
void	gwy_graph_model_append_curves ()
GwySIUnit *	gwy_graph_model_get_si_unit_x ()
GwySIUnit *	gwy_graph_model_get_si_unit_y ()
void	gwy_graph_model_set_units_from_data_line ()
void	gwy_graph_model_set_units_from_data_field ()
gboolean	gwy_graph_model_units_are_compatible ()
gboolean	gwy_graph_model_x_data_can_be_logarithmed ()
gboolean	gwy_graph_model_y_data_can_be_logarithmed ()
void	gwy_graph_model_set_axis_label ()
const gchar *	gwy_graph_model_get_axis_label ()
const gchar *	gwy_graph_model_get_title ()
gboolean	gwy_graph_model_get_x_range ()
gboolean	gwy_graph_model_get_y_range ()
gboolean	gwy_graph_model_get_ranges ()
GString *	gwy_graph_model_export_ascii ()

Properties

char *	axis-label-bottom	Read / Write
char *	axis-label-left	Read / Write
char *	axis-label-right	Read / Write
char *	axis-label-top	Read / Write
GwyGraphGridType	grid-type	Read / Write
int	label-frame-thickness	Read / Write
gboolean	label-has-frame	Read / Write
GwyGraphKeyPosition	label-position	Read / Write
double	label-relative-x	Read / Write
double	label-relative-y	Read / Write
gboolean	label-reverse	Read / Write
gboolean	label-visible	Read / Write
guint	n-curves	Read
GwySIUnit *	si-unit-x	Read / Write
GwySIUnit *	si-unit-y	Read / Write
char *	title	Read / Write
gboolean	x-logarithmic	Read / Write
double	x-max	Read / Write
gboolean	x-max-set	Read / Write
double	x-min	Read / Write
gboolean	x-min-set	Read / Write
gboolean	y-logarithmic	Read / Write
double	y-max	Read / Write
gboolean	y-max-set	Read / Write
double	y-min	Read / Write
gboolean	y-min-set	Read / Write

Signals

void	curve-data-changed	Run First
void	curve-notify	Run First

Types and Values

enum	GwyGraphGridType
enum	GwyGraphModelExportStyle
struct	GwyGraphModel
struct	GwyGraphModelClass

Object Hierarchy

    GObject
    ╰── GwyGraphModel

Implemented Interfaces

GwyGraphModel implements GwySerializable.

Includes

#include <libgwyui/gwyui.h>

Description

GwyGraphModel represents information about a graph necessary to fully reconstruct it.

Functions

gwy_graph_model_new()

GwyGraphModel *
gwy_graph_model_new (void);

Creates a new graph model.

Returns

New graph model as a GObject.

gwy_graph_model_new_alike()

GwyGraphModel *
gwy_graph_model_new_alike (GwyGraphModel *gmodel);

Creates new graph model object that has the same settings as gmodel .

This includes axis/label visibility, actual plotting range, etc. Curves are not duplicated or referenced.

Parameters

gmodel

A graph model.

Returns

New graph model.

gwy_graph_model_copy()

GwyGraphModel *
gwy_graph_model_copy (GwyGraphModel *gmodel);

Create a new graph curve model as a copy of an existing one.

This function is a convenience gwy_serializable_copy() wrapper.

Parameters

gmodel

A graph curve model to duplicate.

Returns

A copy of the graph curve model.

[transfer full]

gwy_graph_model_assign()

void
gwy_graph_model_assign (GwyGraphModel *destination,
                        GwyGraphModel *source);

Makes one data gmodel equal to another.

This function is a convenience gwy_serializable_assign() wrapper.

Parameters

destination	Target data gmodel.
source	Source data gmodel.

gwy_graph_model_get_n_curves()

gint
gwy_graph_model_get_n_curves (GwyGraphModel *gmodel);

Reports the number of curves in a graph model.

Parameters

gmodel

A graph model.

Returns

Number of curves in graph model.

gwy_graph_model_add_curve()

gint
gwy_graph_model_add_curve (GwyGraphModel *gmodel,
                           GwyGraphCurveModel *curve);

Adds a new curve to a graph model.

Parameters

gmodel	A graph model.
curve	A GwyGraphCurveModel representing the curve to add.

Returns

The index of the added curve in gmodel .

gwy_graph_model_remove_curve_by_description()

gint
gwy_graph_model_remove_curve_by_description
                               (GwyGraphModel *gmodel,
                                const gchar *description);

Removes all the curves having same description string as description .

Parameters

gmodel	A graph model.
description	Curve description (label).

Returns

The number of removed curves.

gwy_graph_model_remove_curve()

void
gwy_graph_model_remove_curve (GwyGraphModel *gmodel,
                              gint cindex);

Removes the curve having given index.

Parameters

gmodel	A graph model.
cindex	Curve index in graph model.

gwy_graph_model_get_curve_by_description()

GwyGraphCurveModel *
gwy_graph_model_get_curve_by_description
                               (GwyGraphModel *gmodel,
                                const gchar *description);

Finds a graph curve model in a graph model by its description.

Parameters

gmodel	A graph model.
description	Curve description (label).

Returns

The first curve that has description (label) given by description (no reference is added).

gwy_graph_model_get_curve()

GwyGraphCurveModel *
gwy_graph_model_get_curve (GwyGraphModel *gmodel,
                           gint cindex);

Gets a graph curve model in a graph model by its index.

Parameters

gmodel	A graph model.
cindex	Curve index in graph model.

Returns

The curve with index cindex (no reference is added).

gwy_graph_model_get_curve_index()

gint
gwy_graph_model_get_curve_index (GwyGraphModel *gmodel,
                                 GwyGraphCurveModel *curve);

Finds the index of a graph model curve.

Parameters

gmodel	A graph model.
curve	A curve model present in `gmodel` to find.

Returns

The index of curve in gmodel , -1 if it is not present there.

gwy_graph_model_replace_curve()

void
gwy_graph_model_replace_curve (GwyGraphModel *gmodel,
                               gint cindex,
                               GwyGraphCurveModel *curve);

Replaces a curve in a graph model.

Parameters

gmodel	A graph model.
cindex	Curve index in graph model.
curve	A curve model to put into `gmodel` at position `cindex` .

gwy_graph_model_remove_all_curves()

void
gwy_graph_model_remove_all_curves (GwyGraphModel *gmodel);

Removes all the curves from graph model

Parameters

gmodel

A graph model.

gwy_graph_model_append_curves()

void
gwy_graph_model_append_curves (GwyGraphModel *gmodel,
                               GwyGraphModel *source,
                               gint colorstep);

Appends all curves from another graph model to a graph model.

The colors of the curves can be updated, presumably to continue a preset color sequence. This is controlled by argument colorstep . When colorstep is zero no curve color modification is done. When it is positive, a block of curves of size colorstep is always given the same color, the first color being the first preset color corresponding to the number of curves already in gmodel . So pass colorstep =1 for individual curves, colorstep =2 for couples of curves (e.g. data and fit) that should have the same color, etc.

Parameters

gmodel	A graph model.
source	Graph model containing the curves to append.
colorstep	Block size for curve color updating.

gwy_graph_model_get_si_unit_x()

GwySIUnit *
gwy_graph_model_get_si_unit_x (GwyGraphModel *gmodel);

Returns ordinate SI unit of a graph model.

The returned object can be modified to change the graph ordinate units.

Parameters

gmodel

A graph model.

Returns

SI unit corresponding to the ordinate dimensions of the graph. Its reference count is not incremented.

gwy_graph_model_get_si_unit_y()

GwySIUnit *
gwy_graph_model_get_si_unit_y (GwyGraphModel *gmodel);

Returns abscissa SI unit of a graph model.

The returned object can be modified to change the graph abscissa units.

Parameters

gmodel

A graph model.

Returns

SI unit corresponding to the abscissa dimensions of the graph. Its reference count is not incremented.

gwy_graph_model_set_units_from_data_line()

void
gwy_graph_model_set_units_from_data_line
                               (GwyGraphModel *gmodel,
                                GwyDataLine *data_line);

Sets x and y graph model units to match a data line.

Parameters

gmodel	A graph model.
data_line	A data line to take units from.

gwy_graph_model_set_units_from_data_field()

void
gwy_graph_model_set_units_from_data_field
                               (GwyGraphModel *gmodel,
                                GwyDataField *data_field,
                                gint power_xy_in_x,
                                gint power_z_in_x,
                                gint power_xy_in_y,
                                gint power_z_in_y);

Sets x and y graph model units to units derived from a data field.

Parameters

gmodel	A graph model.
data_field	A data field.
power_xy_in_x	Power of field's lateral units to appear in graph's abscissa units.
power_z_in_x	Power of field's value units to appear in graph's abscissa units.
power_xy_in_y	Power of field's lateral units to appear in graph's ordinate units.
power_z_in_y	Power of field's value units to appear in graph's ordinate units.

gwy_graph_model_units_are_compatible()

gboolean
gwy_graph_model_units_are_compatible (GwyGraphModel *gmodel,
                                      GwyGraphModel *othergmodel);

Checks if the units of two graph models are compatible.

This function is useful namely as a pre-check for moving curves between graphs.

Parameters

gmodel	A graph model.
othergmodel	Another graph model.

Returns

TRUE if the abscissa and ordinate units of the two graphs are compatible.

gwy_graph_model_x_data_can_be_logarithmed()

gboolean
gwy_graph_model_x_data_can_be_logarithmed
                               (GwyGraphModel *gmodel);

Checks whehter x axis can be lograrithmed.

Parameters

gmodel

A graph model.

Returns

TRUE if all x-values are greater than zero (thus logarithmic display of x-data is feasible).

gwy_graph_model_y_data_can_be_logarithmed()

gboolean
gwy_graph_model_y_data_can_be_logarithmed
                               (GwyGraphModel *gmodel);

Checks whehter y axis can be lograrithmed.

Parameters

gmodel

A graph model.

Returns

TRUE if all y-values are greater than zero (thus logarithmic display of y-data is feasible).

gwy_graph_model_set_axis_label()

void
gwy_graph_model_set_axis_label (GwyGraphModel *gmodel,
                                GtkPositionType pos,
                                const gchar *label);

Sets one axis label of a graph model.

Parameters

gmodel	A graph model.
pos	Axis position.
label	The new label.

gwy_graph_model_get_axis_label()

const gchar *
gwy_graph_model_get_axis_label (GwyGraphModel *gmodel,
                                GtkPositionType pos);

Gets the label of a one graph model axis.

Parameters

gmodel	A graph model.
pos	Axis position.

Returns

The label as a string owned by the model.

gwy_graph_model_get_title()

const gchar *
gwy_graph_model_get_title (GwyGraphModel *gmodel);

Gets the graph model title.

Parameters

gmodel

A graph

Returns

The title as a string owned by the model.

gwy_graph_model_get_x_range()

gboolean
gwy_graph_model_get_x_range (GwyGraphModel *gmodel,
                             gdouble *x_min,
                             gdouble *x_max);

Gets the abscissa range of a graph.

Explicitly set minimum and maximum range properties take precedence over values calculated from curve abscissa ranges.

Parameters

gmodel	A graph model.
x_min	Location to store the minimum abscissa value, or `NULL`.
x_max	Location to store the maximum abscissa value, or `NULL`.

Returns

TRUE if the requested values were filled, FALSE is there are no data points and the ranges are not explicitly set.

gwy_graph_model_get_y_range()

gboolean
gwy_graph_model_get_y_range (GwyGraphModel *gmodel,
                             gdouble *y_min,
                             gdouble *y_max);

Gets the ordinate range of a graph.

Explicitly set minimum and maximum range properties take precedence over values calculated from curve ordinate ranges.

Parameters

gmodel	A graph model.
y_min	Location to store the minimum ordinate value, or `NULL`.
y_max	Location to store the maximum ordinate value, or `NULL`.

Returns

TRUE if the requested values were filled, FALSE is there are no data points and the ranges are not explicitly set.

gwy_graph_model_get_ranges()

gboolean
gwy_graph_model_get_ranges (GwyGraphModel *gmodel,
                            gboolean x_logscale,
                            gboolean y_logscale,
                            gdouble *x_min,
                            gdouble *x_max,
                            gdouble *y_min,
                            gdouble *y_max);

Gets the log-scale suitable range minima of a graph curve.

See gwy_graph_curve_model_get_ranges() for discussion.

Parameters

gmodel	A graph model.
x_logscale	`TRUE` if logarithmical scale is intended for the abscissa.
y_logscale	`TRUE` if logarithmical scale is intended for the ordinate.
x_min	Location to store the minimum abscissa value, or `NULL`.
x_max	Location to store the maximum abscissa value, or `NULL`.
y_min	Location to store the minimum ordinate value, or `NULL`.
y_max	Location to store the maximum ordinate value, or `NULL`.

Returns

TRUE if all requested output arguments were filled with the ranges.

gwy_graph_model_export_ascii()

GString *
gwy_graph_model_export_ascii (GwyGraphModel *model,
                              gboolean export_units,
                              gboolean export_labels,
                              gboolean export_metadata,
                              GwyGraphModelExportStyle export_style,
                              GString *string);

Exports a graph model data to a string.

The export format is specified by parameter export_style .

Parameters

model	A graph model.
export_units	`TRUE` to export units in the column header.
export_labels	`TRUE` to export labels in the column header.
export_metadata	`TRUE` to export all graph metadata within file header.
export_style	File format subtype to export to (e. g. plain, csv, gnuplot, etc.).
string	A string to append the text dump to, or `NULL` to allocate a new string.

Returns

Either string itself if it was not NULL, or a newly allocated GString.

Types and Values

enum GwyGraphGridType

Members

GWY_GRAPH_GRID_NONE
GWY_GRAPH_GRID_AUTO
GWY_GRAPH_GRID_USER

enum GwyGraphModelExportStyle

Graph ASCII export style.

Members

GWY_GRAPH_MODEL_EXPORT_ASCII_PLAIN	White-space separated data values, plain description lines and column headers, missing data represented with dashes.
GWY_GRAPH_MODEL_EXPORT_ASCII_GNUPLOT	White-space separated data values, curves serialised, description lines and column headers prefixed with `#`.
GWY_GRAPH_MODEL_EXPORT_ASCII_CSV	Semicolon separated data values and column headers, missing data represented as empty columns.
GWY_GRAPH_MODEL_EXPORT_ASCII_ORIGIN	Presently, the same as the plain format.
GWY_GRAPH_MODEL_EXPORT_ASCII_IGORPRO	Text wave format of Igor Pro (.itx).
GWY_GRAPH_MODEL_EXPORT_ASCII_POSIX	Flag that can be combined with the other formats, meaning locale-independent C/POSIX format of floating point numbers.
GWY_GRAPH_MODEL_EXPORT_ASCII_MERGED	Flag that can be combined with the other formats (except Igor Pro), requesting multi-column output with a single merged abscissa in the first column.

struct GwyGraphModel

struct GwyGraphModel;

struct GwyGraphModelClass

struct GwyGraphModelClass {
    GObjectClass parent_class;

    void (*curve_data_changed)(GwyGraphModel *gmodel,
                               gint i);
    void (*curve_notify)(GwyGraphModel *gmodel,
                         gint i,
                         GParamSpec *pspec);

    void (*reserved1)(void);
    void (*reserved2)(void);
    void (*reserved3)(void);
    void (*reserved4)(void);
};

Property Details

The `“axis-label-bottom”` property

  “axis-label-bottom”        char *

The label of the bottom axis.

Owner: GwyGraphModel

Flags: Read / Write

Default value: "x"

The `“axis-label-left”` property

  “axis-label-left”          char *

The label of the left axis.

Owner: GwyGraphModel

Flags: Read / Write

Default value: "y"

The `“axis-label-right”` property

  “axis-label-right”         char *

The label of the right axis.

Owner: GwyGraphModel

Flags: Read / Write

Default value: ""

The `“axis-label-top”` property

  “axis-label-top”           char *

The label of the top axis.

Owner: GwyGraphModel

Flags: Read / Write

Default value: ""

The `“grid-type”` property

  “grid-type”                GwyGraphGridType

Type of grid drawn on main graph area.

Owner: GwyGraphModel

Flags: Read / Write

Default value: GWY_GRAPH_GRID_AUTO

The `“label-frame-thickness”` property

  “label-frame-thickness”    int

Thickness of key label frame.

Owner: GwyGraphModel

Flags: Read / Write

Allowed values: [0,16]

Default value: 1

The `“label-has-frame”` property

  “label-has-frame”          gboolean

TRUE if key label has frame.

Owner: GwyGraphModel

Flags: Read / Write

Default value: TRUE

The `“label-position”` property

  “label-position”           GwyGraphKeyPosition

Position type of key label.

Owner: GwyGraphModel

Flags: Read / Write

Default value: GWY_GRAPH_KEY_NORTHEAST

The `“label-relative-x”` property

  “label-relative-x”         double

Relative screen x-coordinate of label inside the area for user label position.

Owner: GwyGraphModel

Flags: Read / Write

Allowed values: [0,1]

Default value: 1

The `“label-relative-y”` property

  “label-relative-y”         double

Relative screen y-coordinate of label inside the area for user label position.

Owner: GwyGraphModel

Flags: Read / Write

Allowed values: [0,1]

Default value: 0

The `“label-reverse”` property

  “label-reverse”            gboolean

TRUE if text and curve sample is switched in the key.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“label-visible”` property

  “label-visible”            gboolean

TRUE if key label is visible.

Owner: GwyGraphModel

Flags: Read / Write

Default value: TRUE

The `“n-curves”` property

  “n-curves”                 guint

The number of curves in graph model.

Owner: GwyGraphModel

Flags: Read

Default value: 0

The `“si-unit-x”` property

  “si-unit-x”                GwySIUnit *

The unit of horizontal axis values.

Units are set by value. The unit object does not change. Setting the property is the same as getting the unit object and using gwy_si_unit_assing() to modify it.

Owner: GwyGraphModel

Flags: Read / Write

The `“si-unit-y”` property

  “si-unit-y”                GwySIUnit *

Unit of y axis. Units are always passed by value, the unit object has a different identity than the object owned by the graph model.

Owner: GwyGraphModel

Flags: Read / Write

The `“title”` property

  “title”                    char *

The graph title.

Owner: GwyGraphModel

Flags: Read / Write

Default value: "New graph"

The `“x-logarithmic”` property

  “x-logarithmic”            gboolean

TRUE if x coordinate is logarithimic.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“x-max”` property

  “x-max”                    double

Requested maximum x value.

Owner: GwyGraphModel

Flags: Read / Write

Default value: 0

The `“x-max-set”` property

  “x-max-set”                gboolean

Whether x-max is set.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“x-min”` property

  “x-min”                    double

Requested minimum x value.

Owner: GwyGraphModel

Flags: Read / Write

Default value: 0

The `“x-min-set”` property

  “x-min-set”                gboolean

Whether x-min is set.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“y-logarithmic”` property

  “y-logarithmic”            gboolean

TRUE if y coordinate is logarithimic.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“y-max”` property

  “y-max”                    double

Requested maximum y value.

Owner: GwyGraphModel

Flags: Read / Write

Default value: 0

The `“y-max-set”` property

  “y-max-set”                gboolean

Whether y-max is set.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

The `“y-min”` property

  “y-min”                    double

Requested minimum y value.

Owner: GwyGraphModel

Flags: Read / Write

Default value: 0

The `“y-min-set”` property

  “y-min-set”                gboolean

Whether y-min is set.

Owner: GwyGraphModel

Flags: Read / Write

Default value: FALSE

Signal Details

The `“curve-data-changed”` signal

void
user_function (GwyGraphModel *gwygraphmodel,
               int            arg1,
               gpointer       user_data)

The ::curve-data-changed signal is emitted whenever any of the curves in a graph model emits “data-changed”.

Parameters

gwygraphmodel	The GwyGraphModel which received the signal.
arg1	The index of the changed curve in the model.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“curve-notify”` signal

void
user_function (GwyGraphModel *gwygraphmodel,
               int            arg1,
               GParamSpec    *arg2,
               gpointer       user_data)

The ::curve-data-changed signal is emitted whenever any of the curves in a graph model emits “notify”.

Parameters

gwygraphmodel	The GwyGraphModel which received the signal.
arg1	The index of the changed curve in the model.
arg2	The GParamSpec of the property that has changed.
user_data	user data set when the signal handler was connected.

Flags: Run First