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 ()
void | gwy_graph_model_remove_curve ()
gint | gwy_graph_model_find_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 ()
GwyUnit * | gwy_graph_model_get_unit_x ()
GwyUnit * | gwy_graph_model_get_unit_y ()
void | gwy_graph_model_set_units_from_line ()
void | gwy_graph_model_set_units_from_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
char * | title | Read / Write
GwyUnit * | unit-x | Read / Write
GwyUnit * | unit-y | 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()

    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_find_curve_by_description()

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

Finds the first graph curve model in a graph model with matching description string.

#### Parameters

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

#### Returns

The curve index if found, a negative value (-1) if not found.

### 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_unit_x()

    GwyUnit *
    gwy_graph_model_get_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_unit_y()

    GwyUnit *
    gwy_graph_model_get_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_line()

    void
    gwy_graph_model_set_units_from_line (GwyGraphModel *gmodel,
                                         GwyLine *line);

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

#### Parameters

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

### gwy_graph_model_set_units_from_field()

    void
    gwy_graph_model_set_units_from_field (GwyGraphModel *gmodel,
                                          GwyField *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. |
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. | [nullable]

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

[nullable]

### gwy_graph_model_get_title()

    const gchar *
    gwy_graph_model_get_title (GwyGraphModel *gmodel);

Gets the graph model title.

#### Parameters

gmodel | A graph model. |

#### Returns

The title as a string owned by the model.

[nullable]

### 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);
    };

## 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 `“title”` property

      “title”                    char *

The graph title.

Owner: GwyGraphModel

Flags: Read / Write

Default value: "New graph"

### The `“unit-x”` property

      “unit-x”                   GwyUnit *

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_unit_assign()` to modify it.

Owner: GwyGraphModel

Flags: Read / Write

### The `“unit-y”` property

      “unit-y”                   GwyUnit *

The unit of vertical 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_unit_assign()` to modify it.

Owner: GwyGraphModel

Flags: Read / Write

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