GwyGraphModel: Gwyddion Widgets Library Reference Manual

## GwyGraphModel GwyGraphModel — Representation of a graph |

## Functions

#define | gwy_graph_model_duplicate()
GwyGraphModel * | gwy_graph_model_new ()
GwyGraphModel * | gwy_graph_model_new_alike ()
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 ()
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 ()
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
GwyGraphLabelPosition | 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

struct | GwyGraphModel
struct | GwyGraphModelClass

## Object Hierarchy

        GObject
        ╰── GwyGraphModel

## Implemented Interfaces

GwyGraphModel implements GwySerializable.

## Includes

    #include <libgwydgets/gwydgets.h>

## Description

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

## Functions

### gwy_graph_model_duplicate()

    #define             gwy_graph_model_duplicate(gmodel)

Convenience macro doing `gwy_serializable_duplicate()` with all the necessary typecasting.

#### Parameters

gmodel | A graph model to duplicate. |

### 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_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` . |

Since: 2.51

### 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. |

Since: 2.41

### 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. |

Since: 2.51

### 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.

Since: 2.41

### gwy_graph_model_x_data_can_be_logarithmed ()

    gboolean
    gwy_graph_model_x_data_can_be_logarithmed
                                   (GwyGraphModel *model);

Checks whehter x axis can be lograrithmed.

#### Parameters

model | 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 *model);

Checks whehter y axis can be lograrithmed.

#### Parameters

model | 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 *model,
                                    GtkPositionType pos,
                                    const gchar *label);

Sets one axis label of a graph model.

#### Parameters

model | 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 *model,
                                    GtkPositionType pos);

Gets the label of a one graph model axis.

#### Parameters

model | A graph model. |
pos | Axis position. |

#### Returns

The label 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.

Since: 2.8

### 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

### struct GwyGraphModel

    struct GwyGraphModel;

### struct GwyGraphModelClass

    struct GwyGraphModelClass {
        GObjectClass parent_class;

        void (*curve_data_changed)(GwyGraphModel *model,
                                   gint i);
        void (*curve_notify)(GwyGraphModel *model,
                             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”           GwyGraphLabelPosition

Position type of key label.

Owner: GwyGraphModel

Flags: Read / Write

Default value: GWY_GRAPH_LABEL_NORTHEAST

### The `“label-relative-x”` property

      “label-relative-x”         double

Relative screen X-coordinate of label inside the area.

This value has any effect only if the label position is `GWY_GRAPH_LABEL_USER`.

Owner: GwyGraphModel

Flags: Read / Write

Allowed values: [0,1]

Default value: 1

Since: 2.45

### The `“label-relative-y”` property

      “label-relative-y”         double

Relative screen Y-coordinate of label inside the area.

This value has any effect only if the label position is `GWY_GRAPH_LABEL_USER`.

Owner: GwyGraphModel

Flags: Read / Write

Allowed values: [0,1]

Default value: 0

Since: 2.45

### The `“label-reverse”` property

      “label-reverse”            gboolean

TRUE if text and curve sample is switched in 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 *

Unit of x 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 `“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