GwyGraphCurveModel: Gwyddion Widgets Library Reference Manual

## GwyGraphCurveModel GwyGraphCurveModel — Representation of one graph curve |

## Functions

const GwyEnum * | gwy_graph_curve_mode_get_enum ()
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_line ()
GwyGraphCurveModel * | gwy_graph_curve_model_copy ()
void | gwy_graph_curve_model_assign ()
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_n_data ()
gboolean | gwy_graph_curve_model_get_x_range ()
gboolean | gwy_graph_curve_model_get_y_range ()
gboolean | gwy_graph_curve_model_get_ranges ()
void | gwy_graph_curve_model_get_color ()
const gchar * | gwy_graph_curve_model_get_description ()
const GwyRGBA * | gwy_graph_get_preset_color ()
guint | gwy_graph_get_n_preset_colors ()

## Properties

GwyRGBA * | color | Read / Write
char * | description | Read / Write
GwyLineStyle | line-style | Read / Write
double | line-width | Read / Write
GwyGraphCurveMode | mode | Read / Write
double | point-size | Read / Write
GwySymbolType | point-type | Read / Write

## Signals

void | data-changed | Run First

## Types and Values

enum | GwyGraphCurveMode
struct | GwyGraphCurveModel
struct | GwyGraphCurveModelClass

## Object Hierarchy

        GObject
        ╰── GwyGraphCurveModel

## Implemented Interfaces

GwyGraphCurveModel implements GwySerializable.

## Includes

    #include <libgwyui/gwyui.h>

## Description

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

## Functions

### gwy_graph_curve_mode_get_enum()

    const GwyEnum *
    gwy_graph_curve_mode_get_enum (void);

Returns GwyEnum for GwyGraphCurveMode enum type.

#### Returns

`NULL`-terminated GwyEnum which must not be modified nor freed.

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

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. group 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` .

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 group in `xydata` . |

### gwy_graph_curve_model_set_data_from_line()

    void
    gwy_graph_curve_model_set_data_from_line
                                   (GwyGraphCurveModel *gcmodel,
                                    GwyLine *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 GwyLine. In the case that `from_index` == `to_index` , the full GwyLine is used.

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

    GwyGraphCurveModel *
    gwy_graph_curve_model_copy (GwyGraphCurveModel *gcmodel);

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

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

gcmodel | A graph curve model to duplicate. |

#### Returns

A copy of the graph curve model.

[transfer full]

### gwy_graph_curve_model_assign()

    void
    gwy_graph_curve_model_assign (GwyGraphCurveModel *destination,
                                  GwyGraphCurveModel *source);

Makes one data gcmodel equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target data gcmodel. |
source | Source data gcmodel. |

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

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

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

    gint
    gwy_graph_curve_model_get_n_data (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.

### gwy_graph_curve_model_get_color()

    void
    gwy_graph_curve_model_get_color (GwyGraphCurveModel *gcmodel,
                                     GwyRGBA *color);

Gets the color of a graph curve model.

This is a convenience function for getting GwyGraphCurveModel:color because `g_object_get()` is unwieldy for getting structs.

#### Parameters

gcmodel | A graph curve model. |
color | Location where to fill the curve color. |

### gwy_graph_curve_model_get_description()

    const gchar *
    gwy_graph_curve_model_get_description (GwyGraphCurveModel *gcmodel);

Gets the description of a graph curve model.

#### Parameters

gcmodel | A graph curve model |

#### Returns

The description as a string owned by the model.

### gwy_graph_get_preset_color()

    const GwyRGBA *
    gwy_graph_get_preset_color (guint i);

Gets a preset graph curve colour.

Preset colours are a set of selected colours one can use to distingush graph curves when there is no reason to prefer a particular colour. Note that the preset colours are not guaranteed to never change (including their total number), although it happens rarely.

#### Parameters

i | Colour number, starting from 0 which is always black. It can be any number but colours start to repeat after `gwy_graph_get_n_preset_colors()` colours. |

#### Returns

A constant colour that must not be neither modified nor freed.

### gwy_graph_get_n_preset_colors()

    guint
    gwy_graph_get_n_preset_colors (void);

Gets the number of distinct colors `gwy_graph_get_preset_color()` can return.

#### Returns

The number of distinct colors.

## Types and Values

### enum GwyGraphCurveMode

Graph curve plotting type.

#### Members

GWY_GRAPH_CURVE_HIDDEN | Curve is invisible. |
GWY_GRAPH_CURVE_POINTS | Curve data is plotted with symbols. |
GWY_GRAPH_CURVE_LINE | Curve data is plotted with a line. |
GWY_GRAPH_CURVE_LINE_POINTS | Curve data is plotted with symbols and a line. |

### struct GwyGraphCurveModel

    struct GwyGraphCurveModel;

### struct GwyGraphCurveModelClass

    struct GwyGraphCurveModelClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyGraphCurveModel *model);
    };

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

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

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GWY_LINE_SOLID

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

      “line-width”               double

Curve line width.

Owner: GwyGraphCurveModel

Flags: Read / Write

Allowed values: [0,100]

Default value: 1

### The `“mode”` property

      “mode”                     GwyGraphCurveMode

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

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GWY_GRAPH_CURVE_LINE

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

      “point-size”               double

Curve point symbol size.

Owner: GwyGraphCurveModel

Flags: Read / Write

Allowed values: [0,100]

Default value: 8

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

      “point-type”               GwySymbolType

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

Owner: GwyGraphCurveModel

Flags: Read / Write

Default value: GWY_SYMBOL_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