## GwyGraphModel

GwyGraphModel — Representation of a graph

## Synopsis

    #include <libgwydgets/gwydgets.h>

                        GwyGraphModel;
                        GwyGraphModelClass;
    #define             gwy_graph_model_duplicate           (gmodel)
    GwyGraphModel*      gwy_graph_model_new                 (void);
    GwyGraphModel*      gwy_graph_model_new_alike           (GwyGraphModel *gmodel);
    gint                gwy_graph_model_get_n_curves        (GwyGraphModel *gmodel);
    gint                gwy_graph_model_add_curve           (GwyGraphModel *gmodel,
                                                             GwyGraphCurveModel *curve);
    gint                gwy_graph_model_remove_curve_by_description
                                                            (GwyGraphModel *gmodel,
                                                             const gchar *description);
    void                gwy_graph_model_remove_curve        (GwyGraphModel *gmodel,
                                                             gint cindex);
    GwyGraphCurveModel* gwy_graph_model_get_curve_by_description
                                                            (GwyGraphModel *gmodel,
                                                             const gchar *description);
    GwyGraphCurveModel* gwy_graph_model_get_curve           (GwyGraphModel *gmodel,
                                                             gint cindex);
    gint                gwy_graph_model_get_curve_index     (GwyGraphModel *gmodel,
                                                             GwyGraphCurveModel *curve);
    void                gwy_graph_model_remove_all_curves   (GwyGraphModel *gmodel);
    void                gwy_graph_model_set_units_from_data_line
                                                            (GwyGraphModel *model,
                                                             GwyDataLine *data_line);
    gboolean            gwy_graph_model_x_data_can_be_logarithmed
                                                            (GwyGraphModel *model);
    gboolean            gwy_graph_model_y_data_can_be_logarithmed
                                                            (GwyGraphModel *model);
    void                gwy_graph_model_set_axis_label      (GwyGraphModel *model,
                                                             GtkPositionType pos,
                                                             const gchar *label);
    const gchar*        gwy_graph_model_get_axis_label      (GwyGraphModel *model,
                                                             GtkPositionType pos);
    gboolean            gwy_graph_model_get_x_range         (GwyGraphModel *gmodel,
                                                             gdouble *x_min,
                                                             gdouble *x_max);
    gboolean            gwy_graph_model_get_y_range         (GwyGraphModel *gmodel,
                                                             gdouble *y_min,
                                                             gdouble *y_max);
    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);
    GString*            gwy_graph_model_export_ascii        (GwyGraphModel *model,
                                                             gboolean export_units,
                                                             gboolean export_labels,
                                                             gboolean export_metadata,
                                                             GwyGraphModelExportStyle export_style,
                                                             GString *string);

## Object Hierarchy

      GObject
       +----GwyGraphModel

## Implemented Interfaces

GwyGraphModel implements GwySerializable.

## Properties

      "axis-label-bottom"        gchar*                : Read / Write
      "axis-label-left"          gchar*                : Read / Write
      "axis-label-right"         gchar*                : Read / Write
      "axis-label-top"           gchar*                : Read / Write
      "grid-type"                GwyGraphGridType      : Read / Write
      "label-frame-thickness"    gint                  : Read / Write
      "label-has-frame"          gboolean              : Read / Write
      "label-position"           GwyGraphLabelPosition  : Read / Write
      "label-reverse"            gboolean              : Read / Write
      "label-visible"            gboolean              : Read / Write
      "n-curves"                 guint                 : Read
      "si-unit-x"                GwySIUnit*            : Read / Write
      "si-unit-y"                GwySIUnit*            : Read / Write
      "title"                    gchar*                : Read / Write
      "x-logarithmic"            gboolean              : Read / Write
      "x-max"                    gdouble               : Read / Write
      "x-max-set"                gboolean              : Read / Write
      "x-min"                    gdouble               : Read / Write
      "x-min-set"                gboolean              : Read / Write
      "y-logarithmic"            gboolean              : Read / Write
      "y-max"                    gdouble               : Read / Write
      "y-max-set"                gboolean              : Read / Write
      "y-min"                    gdouble               : Read / Write
      "y-min-set"                gboolean              : Read / Write

## Signals

      "curve-data-changed"                             : Run First
      "curve-notify"                                   : Run First

## Description

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

## Details

### GwyGraphModel

    typedef struct _GwyGraphModel GwyGraphModel;

### GwyGraphModelClass

    typedef struct {
        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);
    } GwyGraphModelClass;

### gwy_graph_model_duplicate()

    #define             gwy_graph_model_duplicate(gmodel)

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

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

`gmodel` : | A graph model.
Returns : | New graph model.

### gwy_graph_model_get_n_curves ()

    gint                gwy_graph_model_get_n_curves        (GwyGraphModel *gmodel);

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

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

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

`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);

`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 model curve by its index.

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

`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_remove_all_curves ()

    void                gwy_graph_model_remove_all_curves   (GwyGraphModel *gmodel);

Removes all the curves from graph model

`gmodel` : | A graph model.

### gwy_graph_model_set_units_from_data_line ()

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

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

`model` : | A graph model.
`data_line` : | A data line to take units from.

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

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

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

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

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

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

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

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

The export format is specified by parameter `export_style`.

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

## Property Details

### The `"axis-label-bottom"` property

      "axis-label-bottom"        gchar*                : Read / Write

The label of the bottom axis.

Default value: "x"

### The `"axis-label-left"` property

      "axis-label-left"          gchar*                : Read / Write

The label of the left axis.

Default value: "y"

### The `"axis-label-right"` property

      "axis-label-right"         gchar*                : Read / Write

The label of the right axis.

Default value: ""

### The `"axis-label-top"` property

      "axis-label-top"           gchar*                : Read / Write

The label of the top axis.

Default value: ""

### The `"grid-type"` property

      "grid-type"                GwyGraphGridType      : Read / Write

Type of grid drawn on main graph area.

Default value: GWY_GRAPH_GRID_AUTO

### The `"label-frame-thickness"` property

      "label-frame-thickness"    gint                  : Read / Write

Thickness of key label frame.

Allowed values: [0,16]

Default value: 1

### The `"label-has-frame"` property

      "label-has-frame"          gboolean              : Read / Write

TRUE if key label has frame.

Default value: TRUE

### The `"label-position"` property

      "label-position"           GwyGraphLabelPosition  : Read / Write

Position type of key label.

Default value: GWY_GRAPH_LABEL_NORTHEAST

### The `"label-reverse"` property

      "label-reverse"            gboolean              : Read / Write

TRUE if text and curve sample is switched in key.

Default value: FALSE

### The `"label-visible"` property

      "label-visible"            gboolean              : Read / Write

TRUE if key label is visible.

Default value: TRUE

### The `"n-curves"` property

      "n-curves"                 guint                 : Read

The number of curves in graph model.

Default value: 0

### The `"si-unit-x"` property

      "si-unit-x"                GwySIUnit*            : Read / Write

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.

### The `"si-unit-y"` property

      "si-unit-y"                GwySIUnit*            : Read / Write

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.

### The `"title"` property

      "title"                    gchar*                : Read / Write

The graph title.

Default value: "New graph"

### The `"x-logarithmic"` property

      "x-logarithmic"            gboolean              : Read / Write

TRUE if x coordinate is logarithimic.

Default value: FALSE

### The `"x-max"` property

      "x-max"                    gdouble               : Read / Write

Requested maximum x value.

Default value: 0

### The `"x-max-set"` property

      "x-max-set"                gboolean              : Read / Write

Whether x-max is set.

Default value: FALSE

### The `"x-min"` property

      "x-min"                    gdouble               : Read / Write

Requested minimum x value.

Default value: 0

### The `"x-min-set"` property

      "x-min-set"                gboolean              : Read / Write

Whether x-min is set.

Default value: FALSE

### The `"y-logarithmic"` property

      "y-logarithmic"            gboolean              : Read / Write

TRUE if y coordinate is logarithimic.

Default value: FALSE

### The `"y-max"` property

      "y-max"                    gdouble               : Read / Write

Requested maximum y value.

Default value: 0

### The `"y-max-set"` property

      "y-max-set"                gboolean              : Read / Write

Whether y-max is set.

Default value: FALSE

### The `"y-min"` property

      "y-min"                    gdouble               : Read / Write

Requested minimum y value.

Default value: 0

### The `"y-min-set"` property

      "y-min-set"                gboolean              : Read / Write

Whether y-min is set.

Default value: FALSE

## Signal Details

### The `"curve-data-changed"` signal

    void                user_function                      (GwyGraphModel *gwygraphmodel,
                                                            gint           arg1,
                                                            gpointer       user_data)          : Run First

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

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

### The `"curve-notify"` signal

    void                user_function                      (GwyGraphModel *gwygraphmodel,
                                                            gint           arg1,
                                                            GParamSpec    *arg2,
                                                            gpointer       user_data)          : Run First

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

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