GwySpectra: Gwyddion Library Reference Manual

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

## Functions

GwySpectra * | gwy_spectra_new ()
GwySpectra * | gwy_spectra_new_alike ()
void | gwy_spectra_data_changed ()
GwySpectra * | gwy_spectra_copy ()
void | gwy_spectra_assign ()
GwyUnit * | gwy_spectra_get_unit_xy ()
void | gwy_spectra_getpos ()
void | gwy_spectra_setpos ()
guint | gwy_spectra_get_n_spectra ()
GwyLine * | 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 * | 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 <libgwyddion/gwyddion.h>

## Description

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

## Functions

### gwy_spectra_new()

    GwySpectra *
    gwy_spectra_new (void);

Creates a new spectrum set containing zero spectra.

[constructor]

#### Returns

A newly created spectra.

[transfer full]

### gwy_spectra_new_alike()

    GwySpectra *
    gwy_spectra_new_alike (GwySpectra *model);

Creates a new spectrum set similar to an existing one, but containing zero spectra.

Use `gwy_spectra_copy()` if you want to copy a spectrum set including the spectra in it.

#### Parameters

model | A spectrum set to take units from. |

#### Returns

A newly created spectra.

[transfer full]

### gwy_spectra_data_changed()

    void
    gwy_spectra_data_changed (GwySpectra *spectra);

Emits signal "data_changed" on a spectrum set.

#### Parameters

spectra | A spectrum set. |

### gwy_spectra_copy()

    GwySpectra *
    gwy_spectra_copy (GwySpectra *spectra);

Create a new spectrum set as a copy of an existing one.

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

#### Parameters

spectra | A spectrum set to duplicate. |

#### Returns

A copy of the spectrum set.

[transfer full]

### gwy_spectra_assign()

    void
    gwy_spectra_assign (GwySpectra *destination,
                        GwySpectra *source);

Makes one spectrum set equal to another.

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

#### Parameters

destination | Target spectrum set. |
source | Source spectrum set. |

### gwy_spectra_get_unit_xy()

    GwyUnit *
    gwy_spectra_get_unit_xy (GwySpectra *spectra);

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

The returned object can be modified to change the spectra lateral units.

#### Parameters

spectra | A spectra. |

#### Returns

Unit corresponding to the location co-ordinates of spectrum set.

[transfer none]

### gwy_spectra_getpos()

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

Gets the coordinates of one spectrum.

#### Parameters

spectra | A spectrum set. |
i | Index of a spectrum. |
x | Location to store the physical x coordinate of the spectrum. | [out]
y | Location to store the physical x coordinate of the spectrum. | [out]

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

### gwy_spectra_get_n_spectra()

    guint
    gwy_spectra_get_n_spectra (GwySpectra *spectra);

Gets the number of spectra in a spectrum set.

#### Parameters

spectra | A spectrum set. |

#### Returns

The number of spectra.

### gwy_spectra_get_spectrum()

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

Gets a line that contains the spectrum at index i.

#### Parameters

spectra | A spectrum set. |
i | Index of a spectrum |

#### Returns

A GwyLine containing the spectrum, owned by `spectra` .

[transfer none]

### gwy_spectra_set_spectrum()

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

Replaces a spectrum in a spectrum set.

#### Parameters

spectra | A spectrum set. |
i | Index of a spectrum to replace |
new_spectrum | A GwyLine Object containing the new spectrum. |

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

#### Parameters

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

### gwy_spectra_get_spectrum_selected()

    gboolean
    gwy_spectra_get_spectrum_selected (GwySpectra *spectra,
                                       guint i);

Gets the selected state of a spectrum in a spectrum set.

#### Parameters

spectra | A spectrum set. |
i | Index of a spectrum. |

#### Returns

`TRUE` if spectrum is selected.

### gwy_spectra_find_nearest()

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

Finds spectra closest to given coordinates.

Point indices in `ilist` will be sorted by the distance from (`x` , `y` ) from the closes to the farthest.

It is not an error to pass `n` larger than the number of spectra. However, the positions after the number of spectra in `spectra` will be left uninitialised.

#### Parameters

spectra | A spectrum set. |
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. |

### gwy_spectra_add_spectrum()

    void
    gwy_spectra_add_spectrum (GwySpectra *spectra,
                              GwyLine *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 spectrum set. |
new_spectrum | A GwyLine 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. |

### 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 spectrum set. |
i | Index of spectrum to remove. |

### gwy_spectra_get_title()

    const gchar *
    gwy_spectra_get_title (GwySpectra *spectra);

Gets the title of spectra.

#### Parameters

spectra | A spectrum set. |

#### Returns

A pointer to the title string (owned by the spectrum set).

### gwy_spectra_set_title()

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

Sets the title of the spectra collection.

#### Parameters

spectra | A spectrum set. |
title | The new title string. |

### gwy_spectra_get_spectrum_x_label()

    const gchar *
    gwy_spectra_get_spectrum_x_label (GwySpectra *spectra);

Gets the spectrum abscissa label of a spectrum set.

#### Parameters

spectra | A spectrum set. |

#### Returns

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

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

#### Parameters

spectra | A spectrum set. |
label | New abscissa label. |

### gwy_spectra_get_spectrum_y_label()

    const gchar *
    gwy_spectra_get_spectrum_y_label (GwySpectra *spectra);

Gets the spectrum ordinate label of a spectrum set.

#### Parameters

spectra | A spectrum set. |

#### Returns

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

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

#### Parameters

spectra | A spectrum set. |
label | New ordinate label. |

### gwy_spectra_clear()

    void
    gwy_spectra_clear (GwySpectra *spectra);

Removes all spectra from the collection.

#### Parameters

spectra | A spectrum set. |

## Types and Values

### struct GwySpectra

    struct GwySpectra;

### struct GwySpectraClass

    struct GwySpectraClass {
        GObjectClass parent_class;

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

## Property Details

### The `“title”` property

      “title”                    char *

The spectra title.

Owner: GwySpectra

Flags: Read / Write

Default value: NULL

## Signal Details

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

    void
    user_function (GwySpectra *gwyspectra,
                   gpointer    user_data)

The ::data-changed signal is never emitted by the object itself. It is intended as a means to notify object users they should update themselves, usually when a computation modifying the data is finished.

#### Parameters

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

Flags: Run First