GwyGrainValue: Gwyddion Library Reference Manual

## GwyGrainValue GwyGrainValue — Grain value resource type |

## Functions

GwyGrainValueGroup | gwy_grain_value_get_group ()
const gchar * | gwy_grain_value_get_symbol ()
void | gwy_grain_value_set_symbol ()
const gchar * | gwy_grain_value_get_symbol_markup ()
void | gwy_grain_value_set_symbol_markup ()
gint | gwy_grain_value_get_power_xy ()
void | gwy_grain_value_set_power_xy ()
gint | gwy_grain_value_get_power_z ()
void | gwy_grain_value_set_power_z ()
GwyGrainValueFlags | gwy_grain_value_get_flags ()
void | gwy_grain_value_set_flags ()
GwyGrainQuantity | gwy_grain_value_get_quantity ()
const gchar * | gwy_grain_value_get_expression ()
gboolean | gwy_grain_value_set_expression ()
const gchar * | gwy_grain_value_group_name ()
GwyInventory * | gwy_grain_values ()
GwyGrainValue * | gwy_grain_values_get_grain_value ()
GwyGrainValue * | gwy_grain_values_get_grain_value_by_symbol ()
GwyGrainValue * | gwy_grain_values_get_builtin_grain_value ()
void | gwy_nield_grain_values ()

## Types and Values

enum | GwyGrainValueGroup
enum | GwyGrainValueFlags
struct | GwyGrainValue
struct | GwyGrainValueClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyGrainValue

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### gwy_grain_value_get_group()

    GwyGrainValueGroup
    gwy_grain_value_get_group (GwyGrainValue *gvalue);

Gets the group of a grain value.

All user-defined grain values belong to `GWY_GRAIN_GROUP_USER` group, built-in grain values belong to other groups.

#### Parameters

gvalue | A grain value object. |

#### Returns

The group of `gvalue` .

### gwy_grain_value_get_symbol()

    const gchar *
    gwy_grain_value_get_symbol (GwyGrainValue *gvalue);

Gets the plain symbol representing a grain value.

The plain symbol is used in expressions. It has to be a valid identifier and it should be easy to type. (Note currently it is not possible to use user-defined grain quantities in expressions for other user-defined grain quantities.)

#### Parameters

gvalue | A grain value object. |

#### Returns

Plain symbol of `gvalue` , owned by `gvalue` .

### gwy_grain_value_set_symbol()

    void
    gwy_grain_value_set_symbol (GwyGrainValue *gvalue,
                                const gchar *symbol);

Sets the plain symbol representing a grain value.

See `gwy_grain_value_get_symbol()` for details.

#### Parameters

gvalue | A grain value object. |
symbol | The new symbol. |

### gwy_grain_value_get_symbol_markup()

    const gchar *
    gwy_grain_value_get_symbol_markup (GwyGrainValue *gvalue);

Gets the rich text symbol representing a grain value.

The returned value can contain Pango markup and is suitable for instance for graph axis labels.

#### Parameters

gvalue | A grain value object. |

#### Returns

Rich text symbol of `gvalue` , owned by `gvalue` .

### gwy_grain_value_set_symbol_markup()

    void
    gwy_grain_value_set_symbol_markup (GwyGrainValue *gvalue,
                                       const gchar *symbol);

Sets the rich text symbol representing a grain value.

See `gwy_grain_value_get_symbol_markup()` for details.

#### Parameters

gvalue | A grain value object. |
symbol | The new symbol. |

### gwy_grain_value_get_power_xy()

    gint
    gwy_grain_value_get_power_xy (GwyGrainValue *gvalue);

Gets the power of lateral dimensions in a grain value.

The units of a grain value are determined as the product of lateral units and value units, raised to certain powers. For instance lengths in the horizontal plane have xy power of 1 and areas have 2, whereas volumes have xy power of 2 and value power of 1.

#### Parameters

gvalue | A grain value object. |

#### Returns

The power of lateral dimensions.

### gwy_grain_value_set_power_xy()

    void
    gwy_grain_value_set_power_xy (GwyGrainValue *gvalue,
                                  gint power_xy);

Sets the power of lateral dimensions in a grain value.

#### Parameters

gvalue | A grain value object. |
power_xy | The new lateral dimensions power. |

### gwy_grain_value_get_power_z()

    gint
    gwy_grain_value_get_power_z (GwyGrainValue *gvalue);

Gets the power of value (height) in a grain value.

See `gwy_grain_value_get_power_xy()` for details.

#### Parameters

gvalue | A grain value object. |

#### Returns

The power of value (height).

### gwy_grain_value_set_power_z()

    void
    gwy_grain_value_set_power_z (GwyGrainValue *gvalue,
                                 gint power_z);

Sets the power of value (height) in a grain value.

#### Parameters

gvalue | A grain value object. |
power_z | The new value (height) power. |

### gwy_grain_value_get_flags()

    GwyGrainValueFlags
    gwy_grain_value_get_flags (GwyGrainValue *gvalue);

Obtains the special attributes of a grain quantity.

#### Parameters

gvalue | A grain value object. |

#### Returns

The special attribute flags set on `gvalue` . See GwyGrainValueFlags for their description.

### gwy_grain_value_set_flags()

    void
    gwy_grain_value_set_flags (GwyGrainValue *gvalue,
                               GwyGrainValueFlags flags);

Sets the special attributes of a grain quantity.

The value of `flags` determines the complete new set of flags. To set individual flags, obtain the current set with `gwy_grain_value_get_flags()` first and then set/unset individual flags.

#### Parameters

gvalue | A grain value object. |
flags | The special attributes to set on `gvalue` . |

### gwy_grain_value_get_quantity()

    GwyGrainQuantity
    gwy_grain_value_get_quantity (GwyGrainValue *gvalue);

Gets the built-in grain quantity corresponding to a grain value.

#### Parameters

gvalue | A grain value object. |

#### Returns

The corresponding built-in GwyGrainQuantity if `gvalue` is a built-it grain value, -1 if `gvalue` is an user-defined grain value.

### gwy_grain_value_get_expression()

    const gchar *
    gwy_grain_value_get_expression (GwyGrainValue *gvalue);

Gets the expression of a user-defined grain value.

#### Parameters

gvalue | A grain value object. |

#### Returns

The expression as a string owned by `gvalue` , `NULL` if `gvalue` is a built-in grain value.

### gwy_grain_value_set_expression()

    gboolean
    gwy_grain_value_set_expression (GwyGrainValue *gvalue,
                                    const gchar *expression,
                                    GError **error);

Sets the expression of a user-defined grain value.

It is an error to call this function on a built-in quantity.

#### Parameters

gvalue | A grain value object. |
expression | New grain value expression. |
error | Return location for the error, or `NULL` to ignore errors. |

#### Returns

`TRUE` if the expression is compilable and references only known grain quantities. `FALSE` is the expression is not calculable, in this case the `gvalue` 's expression is unchanged.

### gwy_grain_value_group_name()

    const gchar *
    gwy_grain_value_group_name (GwyGrainValueGroup group);

Obtains the name of a grain value group.

#### Parameters

group | Grain value group. |

#### Returns

The grain value group name as a constant untranslated string, owned by the library.

### gwy_grain_values()

    GwyInventory *
    gwy_grain_values (void);

Gets the inventory with all the grain values.

#### Returns

Grain value inventory.

[transfer none]

### gwy_grain_values_get_grain_value()

    GwyGrainValue *
    gwy_grain_values_get_grain_value (const gchar *name);

Convenience function to get a grain quantity from `gwy_grain_values()` by name.

#### Parameters

name | Grain quantity name. |

#### Returns

Grain quantity identified by `name` or `NULL` if there is no such grain quantity.

[transfer none]

### gwy_grain_values_get_grain_value_by_symbol()

    GwyGrainValue *
    gwy_grain_values_get_grain_value_by_symbol
                                   (const gchar *symbol);

Convenience function to get a grain quantity from `gwy_grain_values()` by its symbol.

#### Parameters

symbol | Grain quantity symbol. |

#### Returns

Grain quantity with symbol `symbol` or `NULL` if there is no such grain quantity.

[transfer none]

### gwy_grain_values_get_builtin_grain_value()

    GwyGrainValue *
    gwy_grain_values_get_builtin_grain_value
                                   (GwyGrainQuantity quantity);

Obtains the built-in grain value corresponding to given enum value.

#### Parameters

quantity | A GwyGrainQuantity value. |

#### Returns

The built-in grain value corresponding to `quantity` , `NULL` if there is no such grain value.

[transfer none]

### gwy_nield_grain_values()

    void
    gwy_nield_grain_values (GwyNield *nield,
                            GwyField *field,
                            GwyGrainValue **gvalues,
                            guint nvalues,
                            gdouble **results);

Calculates a set of grain values.

See also `gwy_field_grains_get_quantities()` for a simplier function for built-in grain values.

#### Parameters

nield | Number field with numbered grains. |
field | Data field used for marking. For some values its values are not used, but its dimensions determine the dimensions of `grains` . |
gvalues | Array of grain value objects. |
nvalues | Number of items in `gvalues` . |
results | Array of length `nvalues` of arrays of length `ngrains` +1 of doubles to put the calculated values to. |

## Types and Values

### enum GwyGrainValueGroup

#### Members

GWY_GRAIN_GROUP_ID |  |
GWY_GRAIN_GROUP_POSITION |  |
GWY_GRAIN_GROUP_VALUE |  |
GWY_GRAIN_GROUP_AREA |  |
GWY_GRAIN_GROUP_VOLUME |  |
GWY_GRAIN_GROUP_BOUNDARY |  |
GWY_GRAIN_GROUP_SLOPE |  |
GWY_GRAIN_GROUP_CURVATURE |  |
GWY_GRAIN_GROUP_MOMENT |  |
GWY_GRAIN_GROUP_USER |  |

### enum GwyGrainValueFlags

Special attributes of grain values.

#### Members

GWY_GRAIN_SAME_UNITS | Certain grain quantities, such as the surface area or absolute inclination, are only meaningful if value (height) is the same physical quantity as lateral dimensions. These have this flag set to `TRUE`. |
GWY_GRAIN_IS_ANGLE | Angular quantities are internally always calculated in radians, however they can be presented in degrees in the user interface. To enable such special handling, set this flag to `TRUE`. |

### struct GwyGrainValue

    struct GwyGrainValue;

### struct GwyGrainValueClass

    struct GwyGrainValueClass {
        GwyResourceClass parent_class;
    };