## GwySpectra

GwySpectra — Collection of dataline representing point spectra.

## Synopsis

    #include <libprocess/gwyprocess.h>

                        GwySpectra;
                        GwySpectraClass;
    #define             gwy_spectra_duplicate               (spectra)
    GwySpectra*         gwy_spectra_new                     (void);
    GwySpectra*         gwy_spectra_new_alike               (GwySpectra *model);
    void                gwy_spectra_data_changed            (GwySpectra *spectra);
    GwySIUnit*          gwy_spectra_get_si_unit_xy          (GwySpectra *spectra);
    void                gwy_spectra_set_si_unit_xy          (GwySpectra *spectra,
                                                             GwySIUnit *si_unit);
    void                gwy_spectra_itoxy                   (GwySpectra *spectra,
                                                             guint i,
                                                             gdouble *x,
                                                             gdouble *y);
    gint                gwy_spectra_xytoi                   (GwySpectra *spectra,
                                                             gdouble x,
                                                             gdouble y);
    void                gwy_spectra_setpos                  (GwySpectra *spectra,
                                                             guint i,
                                                             gdouble x,
                                                             gdouble y);
    guint               gwy_spectra_get_n_spectra           (GwySpectra *spectra);
    GwyDataLine*        gwy_spectra_get_spectrum            (GwySpectra *spectra,
                                                             gint i);
    void                gwy_spectra_set_spectrum            (GwySpectra *spectra,
                                                             guint i,
                                                             GwyDataLine *new_spectrum);
    void                gwy_spectra_set_spectrum_selected   (GwySpectra *spectra,
                                                             guint i,
                                                             gboolean selected);
    gboolean            gwy_spectra_get_spectrum_selected   (GwySpectra *spectra,
                                                             guint i);
    void                gwy_spectra_find_nearest            (GwySpectra *spectra,
                                                             gdouble x,
                                                             gdouble y,
                                                             guint n,
                                                             guint *ilist);
    void                gwy_spectra_add_spectrum            (GwySpectra *spectra,
                                                             GwyDataLine *new_spectrum,
                                                             gdouble x,
                                                             gdouble y);
    void                gwy_spectra_remove_spectrum         (GwySpectra *spectra,
                                                             guint i);
    const gchar*        gwy_spectra_get_title               (GwySpectra *spectra);
    void                gwy_spectra_set_title               (GwySpectra *spectra,
                                                             const gchar *title);
    void                gwy_spectra_clear                   (GwySpectra *spectra);

## Object Hierarchy

      GObject
       +----GwySpectra

## Implemented Interfaces

GwySpectra implements GwySerializable.

## Properties

      "title"                    gchar*                : Read / Write

## Signals

      "data-changed"                                   : Run First

## Description

GwySpectra contains an array of GwyDataLines and coordinates representing where in a data field the spectrum was acquired.

## Details

### GwySpectra

    typedef struct _GwySpectra GwySpectra;

The GwySpectra struct contains private data only and should be accessed using the functions below.

Since 2.7

### GwySpectraClass

    typedef struct {
        GObjectClass parent_class;

        void (*data_changed)(GwySpectra *spectra);
        void (*reserved1)(void);
        void (*reserved2)(void);
        void (*reserved3)(void);
    } GwySpectraClass;

### gwy_spectra_duplicate()

    #define             gwy_spectra_duplicate(spectra)

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

`spectra` : | A Spectra object to duplicate.

Since 2.7

### gwy_spectra_new ()

    GwySpectra*         gwy_spectra_new                     (void);

Creates a new Spectra object containing zero spectra.

Returns : | A newly created spectra.

Since 2.7

### gwy_spectra_new_alike ()

    GwySpectra*         gwy_spectra_new_alike               (GwySpectra *model);

Creates a new Spectra object similar to an existing one, but containing zero spectra.

Use `gwy_spectra_duplicate()` if you want to copy a spectra object including the spectra in it.

`model` : | A Spectra object to take units from.
Returns : | A newly created Spectra object.

Since 2.7

### gwy_spectra_data_changed ()

    void                gwy_spectra_data_changed            (GwySpectra *spectra);

Emits signal "data_changed" on a spectra object.

`spectra` : | A spectra object.

Since 2.7

### gwy_spectra_get_si_unit_xy ()

    GwySIUnit*          gwy_spectra_get_si_unit_xy          (GwySpectra *spectra);

Gets SI unit used for the location co-ordinates of spectra.

`spectra` : | A spectra.
Returns : | SI unit corresponding to the the location co-ordinates of spectra object. Its reference count is not incremented.

Since 2.7

### gwy_spectra_set_si_unit_xy ()

    void                gwy_spectra_set_si_unit_xy          (GwySpectra *spectra,
                                                             GwySIUnit *si_unit);

Sets the SI unit corresponding to the location co-ordinates of the spectra object.

It does not assume a reference on `si_unit`, instead it adds its own reference.

`spectra` : | A Spectra object.
`si_unit` : | SI unit to be set.

Since 2.7

### gwy_spectra_itoxy ()

    void                gwy_spectra_itoxy                   (GwySpectra *spectra,
                                                             guint i,
                                                             gdouble *x,
                                                             gdouble *y);

Gets the coordinates of one spectrum.

`spectra` : | A spectra object.
`i` : | Index of a spectrum.
`x` : | Location to store the physical x coordinate of the spectrum.
`y` : | Location to store the physical x coordinate of the spectrum.

Since 2.7

### gwy_spectra_xytoi ()

    gint                gwy_spectra_xytoi                   (GwySpectra *spectra,
                                                             gdouble x,
                                                             gdouble y);

Finds the index of the spectrum closest to the location specified by the coordinates x and y.

`spectra` : | A spectra object.
`x` : | The x coordinate of the location of the spectrum.
`y` : | The y coordinate of the location of the spectrum.
Returns : | The index of the nearest spectrum. If there are no curves in the spectra, -1 is returned.

Since 2.7

### gwy_spectra_setpos ()

    void                gwy_spectra_setpos                  (GwySpectra *spectra,
                                                             guint i,
                                                             gdouble x,
                                                             gdouble y);

Sets the location coordinates of a spectrum.

`spectra` : | A spectra object.
`i` : | The index of a spectrum.
`x` : | The new x coordinate of the location of the spectrum.
`y` : | The new y coordinate of the location of the spectrum.

Since 2.7

### gwy_spectra_get_n_spectra ()

    guint               gwy_spectra_get_n_spectra           (GwySpectra *spectra);

Gets the number of spectra in a spectra object.

`spectra` : | A spectra object.
Returns : | The number of spectra.

Since 2.7

### gwy_spectra_get_spectrum ()

    GwyDataLine*        gwy_spectra_get_spectrum            (GwySpectra *spectra,
                                                             gint i);

Gets a dataline that contains the spectrum at index i.

`spectra` : | A Spectra object
`i` : | Index of a spectrum
Returns : | A GwyDataLine containing the spectrum, owned by `spectra`.

Since 2.7

### gwy_spectra_set_spectrum ()

    void                gwy_spectra_set_spectrum            (GwySpectra *spectra,
                                                             guint i,
                                                             GwyDataLine *new_spectrum);

Replaces the ith spectrum in the spectra object with a the supplied spectrum, new_spectrum. It takes its own reference to the New_Spectrum dataline.

`spectra` : | A spectra object.
`i` : | Index of a spectrum to replace
`new_spectrum` : | A GwyDataLine Object containing the new spectrum.

Since 2.7

### gwy_spectra_set_spectrum_selected ()

    void                gwy_spectra_set_spectrum_selected   (GwySpectra *spectra,
                                                             guint i,
                                                             gboolean selected);

Sets selected state of a spectrum in a spectra object.

`spectra` : | A spectra object.
`i` : | Index of a spectrum.
`selected` : | `TRUE` to make the spectrum selected, `FALSE` to deselect it.

Since 2.7

### gwy_spectra_get_spectrum_selected ()

    gboolean            gwy_spectra_get_spectrum_selected   (GwySpectra *spectra,
                                                             guint i);

Gets the selected state of a spectrum in a spectra object.

`spectra` : | A spectra object.
`i` : | Index of a spectrum.
Returns : | `TRUE` if spectrum is selected.

Since 2.7

### gwy_spectra_find_nearest ()

    void                gwy_spectra_find_nearest            (GwySpectra *spectra,
                                                             gdouble x,
                                                             gdouble y,
                                                             guint n,
                                                             guint *ilist);

Gets the list of the indices to spectra ordered by their distance from a given point.

List positions

`spectra` : | A spectra object.
`x` : | Point x-coordinate.
`y` : | Point y-coordinate.
`n` : | Number of indices to find. Array `ilist` must have at least this number of items.
`ilist` : | Array to place the spectra indices to. They will be sorted by the distance from (`x`, `y`). Positions after the number of spectra in `spectra` will be left untouched.

Since 2.7

### gwy_spectra_add_spectrum ()

    void                gwy_spectra_add_spectrum            (GwySpectra *spectra,
                                                             GwyDataLine *new_spectrum,
                                                             gdouble x,
                                                             gdouble y);

Appends a new_spectrum to the spectra collection with a position of x, y. gwy_spectra_add takes a refference to the supplied spectrum.

`spectra` : | A spectra object.
`new_spectrum` : | A GwyDataLine containing the spectrum to append.
`x` : | The physical x coordinate of the location of the spectrum.
`y` : | The physical y coordinate of the location of the spectrum.

Since 2.7

### gwy_spectra_remove_spectrum ()

    void                gwy_spectra_remove_spectrum         (GwySpectra *spectra,
                                                             guint i);

`spectra` : |
`i` : |

### gwy_spectra_get_title ()

    const gchar*        gwy_spectra_get_title               (GwySpectra *spectra);

Gets the title of spectra.

`spectra` : | A spectra object.
Returns : | A pointer to the title string (owned by the spectra object).

Since 2.7

### gwy_spectra_set_title ()

    void                gwy_spectra_set_title               (GwySpectra *spectra,
                                                             const gchar *title);

Sets the title of the spectra collection.

`spectra` : | A spectra object.
`title` : | The new title string.

Since 2.7

### gwy_spectra_clear ()

    void                gwy_spectra_clear                   (GwySpectra *spectra);

Removes all spectra from the collection.

`spectra` : | A spectra object.

Since 2.7

## Property Details

### The `"title"` property

      "title"                    gchar*                : Read / Write

The spectra title.

Default value: "New spectra"

## Signal Details

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

    void                user_function                      (GwySpectra *gwyspectra,
                                                            gpointer    user_data)       : Run First

The ::data-changed signal is never emitted by the spectra itself. It is intended as a means to notify other spectra users they should update themselves.

`gwyspectra` : | The GwySpectra which received the signal.
`user_data` : | user data set when the signal handler was connected.