GwyRuler: Gwyddion Widgets Library Reference Manual

## GwyRuler GwyRuler — Ruler with units |

## Functions

GtkWidget * | gwy_ruler_new ()
void | gwy_ruler_set_orientation ()
GtkOrientation | gwy_ruler_get_orientation ()
void | gwy_ruler_set_range ()
void | gwy_ruler_get_range ()
GwyUnit * | gwy_ruler_get_unit ()
GwyUnitsPlacement | gwy_ruler_get_units_placement ()
void | gwy_ruler_set_units_placement ()
void | gwy_ruler_move_marker ()
gdouble | gwy_ruler_coord_real_to_widget ()
gdouble | gwy_ruler_coord_widget_to_real ()

## Properties

double | lower | Read / Write
double | max-size | Read / Write
double | position | Read / Write
GwyUnitsPlacement | units-placement | Read / Write
double | upper | Read / Write

## Types and Values

enum | GwyUnitsPlacement
struct | GwyRuler
struct | GwyRulerClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GwyRuler

## Implemented Interfaces

GwyRuler implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyRuler is a ruler similar to GtkRuler, but it is more suited for a scientific application. It is scale-independent and thus has no arbitrary limits on the ranges or interpretation of displayed values. It can display units on the ruler (this can be controlled with `gwy_ruler_set_units_placement()`) and cooperates with GwyUnit (see `gwy_ruler_get_unit()`).

## Functions

### gwy_ruler_new()

    GtkWidget *
    gwy_ruler_new (GtkOrientation orientation);

Creates a new ruler widget.

[constructor]

#### Parameters

orientation | Ruler orientation. |

#### Returns

A newly created ruler widget.

[transfer full]

### gwy_ruler_set_orientation()

    void
    gwy_ruler_set_orientation (GwyRuler *ruler,
                               GtkOrientation orientation);

Sets the orientation of a ruler.

#### Parameters

ruler | A GwyRuler. |
orientation | New ruler orientation. |

### gwy_ruler_get_orientation()

    GtkOrientation
    gwy_ruler_get_orientation (GwyRuler *ruler);

Gets the orientation of a ruler.

#### Parameters

ruler | A GwyRuler. |

#### Returns

The orientation.

### gwy_ruler_set_range()

    void
    gwy_ruler_set_range (GwyRuler *ruler,
                         gdouble lower,
                         gdouble upper,
                         gdouble position,
                         gdouble max_size);

Sets range and current value of a ruler.

#### Parameters

ruler | A GwyRuler |
lower | Lower limit of the ruler. |
upper | Upper limit of the ruler. |
position | Current position of the mark on the ruler. |
max_size | Maximum value used for calculating size of text labels. |

### gwy_ruler_get_range()

    void
    gwy_ruler_get_range (GwyRuler *ruler,
                         gdouble *lower,
                         gdouble *upper,
                         gdouble *position,
                         gdouble *max_size);

Retrieves values indicating the range and current position of a GwyRuler. See `gwy_ruler_set_range()`.

#### Parameters

ruler | A GwyRuler |
lower | Location to store lower limit of the ruler, or `NULL` |
upper | Location to store upper limit of the ruler, or `NULL` |
position | Location to store the current position of the mark on the ruler, or `NULL` |
max_size | Location to store the maximum size of the ruler used when calculating the space to leave for the text, or `NULL`. |

### gwy_ruler_get_unit()

    GwyUnit *
    gwy_ruler_get_unit (GwyRuler *ruler);

Returns the base units a ruler uses.

Modify the returned unit object to change the ruler units.

#### Parameters

ruler | A GwyRuler. |

#### Returns

The units the rules uses.

[transfer none]

### gwy_ruler_get_units_placement()

    GwyUnitsPlacement
    gwy_ruler_get_units_placement (GwyRuler *ruler);

Gets current units placement of ruler `ruler` .

#### Parameters

ruler | A GwyRuler |

#### Returns

The units placement.

### gwy_ruler_set_units_placement()

    void
    gwy_ruler_set_units_placement (GwyRuler *ruler,
                                   GwyUnitsPlacement placement);

Sets whether and where units should be placed on the ruler.

#### Parameters

ruler | A GwyRuler |
placement | Units placement specification. |

### gwy_ruler_move_marker()

    void
    gwy_ruler_move_marker (GwyRuler *ruler,
                           gdouble value);

Changes the position of a ruler marker.

The position is also automatically updated when pointer is moved over the marker. This function is meant for updating the ruler when pointer moves over other widgets.

#### Parameters

ruler | A GwyRuler. |
value | Value where to draw marker. |

### gwy_ruler_coord_real_to_widget()

    gdouble
    gwy_ruler_coord_real_to_widget (GwyRuler *ruler,
                                    gdouble value);

Transforms real coordinate to position on the ruler widget.

#### Parameters

ruler | A GwyRuler. |
value | Real value on the ruler. |

#### Returns

Position on widget corresponding to the value.

### gwy_ruler_coord_widget_to_real()

    gdouble
    gwy_ruler_coord_widget_to_real (GwyRuler *ruler,
                                    gdouble pos);

Transforms pixel position a ruler to real coordinate value.

#### Parameters

ruler | A GwyRuler. |
pos | Pixel position on the ruler, in widget coordinates. |

#### Returns

Ruler value corresponding to widget position.

## Types and Values

### enum GwyUnitsPlacement

Units placement on a GwyRuler.

#### Members

GWY_UNITS_PLACEMENT_NONE | Units are omitted. |
GWY_UNITS_PLACEMENT_AT_ZERO | Units are placed to major tick at zero, or to the leftmost position of zero is not present. |

### struct GwyRuler

    struct GwyRuler;

### struct GwyRulerClass

    struct GwyRulerClass {
        GtkWidgetClass parent_class;
    };

## Property Details

### The `“lower”` property

      “lower”                    double

Lower limit (minimum value).

Owner: GwyRuler

Flags: Read / Write

Default value: 0

### The `“max-size”` property

      “max-size”                 double

Maximum magnigude of values.

Owner: GwyRuler

Flags: Read / Write

Default value: 0

### The `“position”` property

      “position”                 double

Value where a mark should be drawn.

Owner: GwyRuler

Flags: Read / Write

Default value: 0

### The `“units-placement”` property

      “units-placement”          GwyUnitsPlacement

Placement of units.

Owner: GwyRuler

Flags: Read / Write

Default value: GWY_UNITS_PLACEMENT_NONE

### The `“upper”` property

      “upper”                    double

Upper limit (maximum value).

Owner: GwyRuler

Flags: Read / Write

Default value: 0