GwyGraphCurveModel: Gwyddion Widgets Library Reference Manual

## GwyGraphCurveModel GwyGraphCurveModel — Representation of one graph curve |

## Functions

#define | gwy_graph_curve_model_duplicate()
GwyGraphCurveModel * | gwy_graph_curve_model_new ()
GwyGraphCurveModel * | gwy_graph_curve_model_new_alike ()
void | gwy_graph_curve_model_set_data ()
void | gwy_graph_curve_model_set_data_interleaved ()
void | gwy_graph_curve_model_set_data_from_dataline ()
void | gwy_graph_curve_model_enforce_order ()
gboolean | gwy_graph_curve_model_is_ordered ()
const gdouble * | gwy_graph_curve_model_get_xdata ()
const gdouble * | gwy_graph_curve_model_get_ydata ()
gint | gwy_graph_curve_model_get_ndata ()
gboolean | gwy_graph_curve_model_get_x_range ()
gboolean | gwy_graph_curve_model_get_y_range ()
gboolean | gwy_graph_curve_model_get_ranges ()
GwyCurveCalibrationData * | gwy_graph_curve_model_get_calibration_data ()
void | gwy_graph_curve_model_set_calibration_data ()

## Properties

GwyRGBA * | color | Read / Write
char * | description | Read / Write
GdkLineStyle | line-style | Read / Write
int | line-width | Read / Write
GwyGraphCurveType | mode | Read / Write
int | point-size | Read / Write
GwyGraphPointType | point-type | Read / Write

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyGraphCurveModel
struct | GwyGraphCurveModelClass

## Object Hierarchy

        GObject
        ╰── GwyGraphCurveModel

## Implemented Interfaces

GwyGraphCurveModel implements GwySerializable.

## Includes

    #include <libgwydgets/gwydgets.h>

## Description

GwyGraphCurveModel represents information about a graph curve necessary to fully reconstruct it.

## Functions

### gwy_graph_curve_model_duplicate()

    #define             gwy_graph_curve_model_duplicate(gcmodel)

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

#### Parameters

gcmodel | A graph curve model to duplicate. |

### gwy_graph_curve_model_new ()

    GwyGraphCurveModel *
    gwy_graph_curve_model_new (void);

Creates a new graph curve model.

#### Returns

New empty graph curve model as a GObject.

### gwy_graph_curve_model_new_alike ()

    GwyGraphCurveModel *
    gwy_graph_curve_model_new_alike (GwyGraphCurveModel *gcmodel);

Creates new graph curve model object that has the same settings as `gcmodel` .

Curve data are not duplicated.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

New graph curve model.

### gwy_graph_curve_model_set_data ()

    void
    gwy_graph_curve_model_set_data (GwyGraphCurveModel *gcmodel,
                                    const gdouble *xdata,
                                    const gdouble *ydata,
                                    gint n);

Sets curve model data from separated X and Y arrays.

If there were calibration data in the former `gcmodel` , they are removed.

The points should be ordered in ascending abscissa order, meaning `xdata` values ordered from smallest to largest. It is not enforced and you can create graphs of data the do not satisfy this condition. However, various graph functionality may be unavailable or degraded then. You also can use `gwy_graph_curve_model_enforce_order()` afterwards to ensure the recommended data point order.

#### Parameters

gcmodel | A graph curve model. |
xdata | X data points (array of size `n` ). |
ydata | Y data points (array of size `n` ). |
n | Number of points, i.e. items in `xdata` and `ydata` . |

### gwy_graph_curve_model_set_data_interleaved ()

    void
    gwy_graph_curve_model_set_data_interleaved
                                   (GwyGraphCurveModel *gcmodel,
                                    const gdouble *xydata,
                                    gint n);

Sets curve model data from an interleaved array.

The array should contain interleaved abscissa and ordinate values: x0, y0, x1, y1, x2, y2, etc. You can also typecast an array of GwyXY structs and pass it as `xydata` .

If there were calibration data in the former `gcmodel` , they are removed.

The points should be ordered in ascending abscissa order, meaning `xdata` values ordered from smallest to largest. It is not enforced and you can create graphs of data the do not satisfy this condition. However, various graph functionality may be unavailable or degraded then. You also can use `gwy_graph_curve_model_enforce_order()` afterwards to ensure the recommended data point order.

#### Parameters

gcmodel | A graph curve model. |
xydata | X and Y data points (array of size 2*`n` ). |
n | Number of points, i.e. half the number of items in `xydata` . |

Since: 2.45

### gwy_graph_curve_model_set_data_from_dataline ()

    void
    gwy_graph_curve_model_set_data_from_dataline
                                   (GwyGraphCurveModel *gcmodel,
                                    GwyDataLine *dline,
                                    gint from_index,
                                    gint to_index);

Sets graph curve model data from a data line.

The range of import can be modified using parameters `from_index` and `to_index` that are interpreted directly as data indices within the GwyDataLine. In the case that `from_index` == `to_index` , the full GwyDataLine is used.

If there were calibration data in the former `gcmodel` , they are removed.

#### Parameters

gcmodel | A graph curve model. |
dline | A data line. |
from_index | Data line index where to start. |
to_index | Data line index where to stop. |

### gwy_graph_curve_model_enforce_order ()

    void
    gwy_graph_curve_model_enforce_order (GwyGraphCurveModel *gcmodel);

Ensures curve model data points are ordered by abscissa in ascending order.

The function reorders the data points currently present in the model. It does not prevent functions such as `gwy_graph_curve_model_set_data()` from disrupting the order again. See its documentation for further remarks.

The "data-changed" signal is emitted if the data order actually changes.

#### Parameters

gcmodel | A graph curve model. |

Since: 2.45

### gwy_graph_curve_model_is_ordered ()

    gboolean
    gwy_graph_curve_model_is_ordered (GwyGraphCurveModel *gcmodel);

Checks if a curve model data points are ordered by abscissa in ascending order.

If the curve model has less than two points it is considered ordered by abscissa. Two points with the same abscissa are considered correctly ordered in both orders.

See `gwy_graph_curve_model_enforce_order()` for fixing the point order.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

`TRUE` if the graph curve model points are sorted by abscissa, `FALSE` when they are not.

Since: 2.46

### gwy_graph_curve_model_get_xdata ()

    const gdouble *
    gwy_graph_curve_model_get_xdata (GwyGraphCurveModel *gcmodel);

Gets y data points of a graph curve model.

The returned data are owned by the and cannot be modified nor freed. The returned pointer is valid only so long as the curve model exists and its data do not change.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

X data points, owned by the curve model.

### gwy_graph_curve_model_get_ydata ()

    const gdouble *
    gwy_graph_curve_model_get_ydata (GwyGraphCurveModel *gcmodel);

Gets y data points of a graph curve model.

The returned data are owned by the and cannot be modified nor freed. The returned pointer is valid only so long as the curve model exists and its data do not change.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

Y data points, owned by the curve model.

### gwy_graph_curve_model_get_ndata ()

    gint
    gwy_graph_curve_model_get_ndata (GwyGraphCurveModel *gcmodel);

Gets the number of points in a graph curve model.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

number of data points within the curve data

### gwy_graph_curve_model_get_x_range ()

    gboolean
    gwy_graph_curve_model_get_x_range (GwyGraphCurveModel *gcmodel,
                                       gdouble *x_min,
                                       gdouble *x_max);

Gets the abscissa range of a graph curve.

The values are cached in the curve model therefore repeated calls to this function (with unchanged data) are cheap.

If there are no data points in the curve, `x_min` and `x_max` are untouched and the function returns `FALSE`.

See also `gwy_graph_curve_model_get_ranges()` for a more high-level function.

#### Parameters

gcmodel | A graph curve 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 there are any data points in the curve and `x_min` , `x_max` were set.

### gwy_graph_curve_model_get_y_range ()

    gboolean
    gwy_graph_curve_model_get_y_range (GwyGraphCurveModel *gcmodel,
                                       gdouble *y_min,
                                       gdouble *y_max);

Gets the ordinate range of a graph curve.

The values are cached in the curve model therefore repeated calls to this function (with unchanged data) are cheap.

If there are no data points in the curve, `x_min` and `x_max` are untouched and the function returns `FALSE`.

See also `gwy_graph_curve_model_get_ranges()` for a more high-level function.

#### Parameters

gcmodel | A graph curve 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 there are any data points in the curve and `x_min` , `x_max` were set.

### gwy_graph_curve_model_get_ranges ()

    gboolean
    gwy_graph_curve_model_get_ranges (GwyGraphCurveModel *gcmodel,
                                      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.

Parameters `x_logscale` and `y_logscale` determine which axis or axes are intended to use logarithmical scale. The range of displayble values for an axis generally depends on the other axis too as it acts as a filter. When both `x_logscale` and `y_logscale` are `FALSE`, the returned minima are identical to those returned by `gwy_graph_curve_model_get_x_range()` and `gwy_graph_curve_model_get_y_range()`.

The return values are cached in the curve model therefore repeated calls to this function (with unchanged data) are cheap.

If there are no data points that would be displayable with the intended logarithmical scale setup, the output arguments are untouched and `FALSE` is returned.

#### Parameters

gcmodel | A graph curve 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 to, or `NULL`. |
x_max | Location to store the maximum abscissa value to, or `NULL`. |
y_min | Location to store the minimum ordinate value to, or `NULL`. |
y_max | Location to store the maximum ordinate value to, or `NULL`. |

#### Returns

`TRUE` if the output arguments were filled with the ranges.

Since: 2.8

### gwy_graph_curve_model_get_calibration_data ()

    GwyCurveCalibrationData *
    gwy_graph_curve_model_get_calibration_data
                                   (GwyGraphCurveModel *gcmodel);

Get pointer to actual calibration data for curve.

#### Parameters

gcmodel | A graph curve model. |

#### Returns

Pointer to the calibration data of present curve (NULL if none).

Since: 2.23

### gwy_graph_curve_model_set_calibration_data ()

    void
    gwy_graph_curve_model_set_calibration_data
                                   (GwyGraphCurveModel *gcmodel,
                                    const GwyCurveCalibrationData *calibration);

Set calibration data for curve.

The function makes a deep copy of `calibration` .

#### Parameters

gcmodel | A graph curve model. |
calibration | Curve calibration data |

Since: 2.23

## Types and Values

### struct GwyGraphCurveModel

    struct GwyGraphCurveModel;

### struct GwyGraphCurveModelClass

    struct GwyGraphCurveModelClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyGraphCurveModel *model);

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

## Property Details

### The `“color”` property

      “color”                    GwyRGBA *

Curve color.

Owner: GwyGraphCurveModel

Flags: Read / Write

### The `“description”` property

      “description”              char *

Curve description. It appears on graph key.

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: "curve"

### The `“line-style”` property

      “line-style”               GdkLineStyle

Curve line style. Curve mode has to include lines for the line to be visible.

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GDK_LINE_SOLID

### The `“line-width”` property

      “line-width”               int

Curve line width.

Owner: GwyGraphCurveModel

Flags: Read / Write

Allowed values: [0,100]

Default value: 1

### The `“mode”` property

      “mode”                     GwyGraphCurveType

Curve plotting mode (line, points, ...).

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GWY_GRAPH_CURVE_LINE

### The `“point-size”` property

      “point-size”               int

Curve point symbol size.

Owner: GwyGraphCurveModel

Flags: Read / Write

Allowed values: [0,100]

Default value: 5

### The `“point-type”` property

      “point-type”               GwyGraphPointType

Curve point symbol type. Curve mode has toinclude points for the symbols to be visible.

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GWY_GRAPH_POINT_SQUARE

## Signal Details

### The `“data-changed”` signal

    void
    user_function (GwyGraphCurveModel *gwygraphcurvemodel,
                   gpointer            user_data)

The ::data-changed signal is emitted whenever curve data is set with a function like `gwy_graph_curve_model_set_data()`.

#### Parameters

gwygraphcurvemodel | The GwyGraphCurveModel which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First