GwySpectra: Gwyddion Data Processing Library Reference Manual

## GwySpectra GwySpectra — Collection of dataline representing point spectra. |

## Functions

#define | gwy_spectra_duplicate()
GwySpectra * | gwy_spectra_new ()
GwySpectra * | gwy_spectra_new_alike ()
void | gwy_spectra_data_changed ()
GwySIUnit * | gwy_spectra_get_si_unit_xy ()
void | gwy_spectra_set_si_unit_xy ()
void | gwy_spectra_itoxy ()
gint | gwy_spectra_xytoi ()
void | gwy_spectra_setpos ()
guint | gwy_spectra_get_n_spectra ()
GwyDataLine * | gwy_spectra_get_spectrum ()
void | gwy_spectra_set_spectrum ()
void | gwy_spectra_set_spectrum_selected ()
gboolean | gwy_spectra_get_spectrum_selected ()
void | gwy_spectra_find_nearest ()
void | gwy_spectra_add_spectrum ()
void | gwy_spectra_remove_spectrum ()
const gchar * | gwy_spectra_get_title ()
void | gwy_spectra_set_title ()
const gchar * | gwy_spectra_get_spectrum_x_label ()
void | gwy_spectra_set_spectrum_x_label ()
const gchar * | gwy_spectra_get_spectrum_y_label ()
void | gwy_spectra_set_spectrum_y_label ()
void | gwy_spectra_clear ()

## Properties

char * | spectrum-x-label | Read / Write
char * | spectrum-y-label | Read / Write
char * | title | Read / Write

## Signals

void | data-changed | Run First

## Types and Values

struct | GwySpectra
struct | GwySpectraClass

## Object Hierarchy

        GObject
        ╰── GwySpectra

## Implemented Interfaces

GwySpectra implements GwySerializable.

## Includes

    #include <libprocess/gwyprocess.h>

## Description

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

## Functions

### gwy_spectra_duplicate()

    #define             gwy_spectra_duplicate(spectra)

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

Adds a new spectrum to the spectra collection with a position of x, y.

The spectra collection takes a reference to `new_spectrum` .

#### Parameters

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

Removes the ith spectrum from the Spectra collection. The subsequent spectra are moved down one place.

#### Parameters

spectra | A spectra object. |
i | Index of spectrum to remove. |

Since: 2.7

### gwy_spectra_get_title ()

    const gchar *
    gwy_spectra_get_title (GwySpectra *spectra);

Gets the title of spectra.

#### Parameters

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.

#### Parameters

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

Since: 2.7

### gwy_spectra_get_spectrum_x_label ()

    const gchar *
    gwy_spectra_get_spectrum_x_label (GwySpectra *spectra);

Gets the spectrum abscissa label of a spectra object.

#### Parameters

spectra | A spectra object. |

#### Returns

The abscissa label. The string is owned by `spectra` and must not be modified nor freed.

Since: 2.40

### gwy_spectra_set_spectrum_x_label ()

    void
    gwy_spectra_set_spectrum_x_label (GwySpectra *spectra,
                                      const gchar *label);

Sets the spectrum abscissa label of a spectra object.

#### Parameters

spectra | A spectra object. |
label | New abscissa label. |

Since: 2.40

### gwy_spectra_get_spectrum_y_label ()

    const gchar *
    gwy_spectra_get_spectrum_y_label (GwySpectra *spectra);

Gets the spectrum ordinate label of a spectra object.

#### Parameters

spectra | A spectra object. |

#### Returns

The ordinate label. The string is owned by `spectra` and must not be modified nor freed.

Since: 2.40

### gwy_spectra_set_spectrum_y_label ()

    void
    gwy_spectra_set_spectrum_y_label (GwySpectra *spectra,
                                      const gchar *label);

Sets the spectrum ordinate label of a spectra object.

#### Parameters

spectra | A spectra object. |
label | New ordinate label. |

Since: 2.40

### gwy_spectra_clear ()

    void
    gwy_spectra_clear (GwySpectra *spectra);

Removes all spectra from the collection.

#### Parameters

spectra | A spectra object. |

Since: 2.7

## Types and Values

### struct GwySpectra

    struct GwySpectra;

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

Since: 2.7

### struct GwySpectraClass

    struct GwySpectraClass {
        GObjectClass parent_class;

        void (*data_changed)(GwySpectra *spectra);
    };

## Property Details

### The `“spectrum-x-label”` property

      “spectrum-x-label”         char *

Label of spectrum abscissa, as it should appear on extracted graphs.

Owner: GwySpectra

Flags: Read / Write

Default value: NULL

Since: 2.40

### The `“spectrum-y-label”` property

      “spectrum-y-label”         char *

Label of spectrum ordinate, as it should appear on extracted graphs.

Owner: GwySpectra

Flags: Read / Write

Default value: NULL

Since: 2.40

### The `“title”` property

      “title”                    char *

The spectra title.

Owner: GwySpectra

Flags: Read / Write

Default value: "New spectra"

## Signal Details

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

    void
    user_function (GwySpectra *gwyspectra,
                   gpointer    user_data)

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.

#### Parameters

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

Flags: Run First