GwyDataView: Gwyddion Widgets Library Reference Manual

## GwyDataView GwyDataView — Data field displaying area |

## Functions

GtkWidget * | gwy_data_view_new ()
GwyField * | gwy_data_view_get_field ()
void | gwy_data_view_set_field ()
GwyNield * | gwy_data_view_get_mask ()
void | gwy_data_view_set_mask ()
GwyVectorLayer * | gwy_data_view_get_interactive_layer ()
void | gwy_data_view_set_interactive_layer ()
gboolean | gwy_data_view_get_real_square ()
void | gwy_data_view_set_real_square ()
void | gwy_data_view_get_color_range ()
gboolean | gwy_data_view_get_fixed_color_range ()
void | gwy_data_view_set_fixed_color_range ()
void | gwy_data_view_unset_fixed_color_range ()
GwyColorMappingType | gwy_data_view_get_color_mapping ()
void | gwy_data_view_set_color_mapping ()
GwyGradient * | gwy_data_view_get_gradient ()
void | gwy_data_view_set_gradient ()
void | gwy_data_view_get_mask_color ()
void | gwy_data_view_set_mask_color ()
gdouble | gwy_data_view_get_hexcess ()
gdouble | gwy_data_view_get_vexcess ()
gdouble | gwy_data_view_get_zoom ()
void | gwy_data_view_set_zoom ()
gdouble | gwy_data_view_get_real_zoom ()
gboolean | gwy_data_view_coords_widget_clamp ()
gboolean | gwy_data_view_coords_widget_cut_line ()
void | gwy_data_view_coords_widget_to_real ()
void | gwy_data_view_coords_real_to_widget ()
gdouble | gwy_data_view_get_xmeasure ()
gdouble | gwy_data_view_get_ymeasure ()
gdouble | gwy_data_view_get_xzoom ()
gdouble | gwy_data_view_get_yzoom ()
void | gwy_data_view_set_resizable ()
void | gwy_data_view_get_pixel_data_sizes ()
void | gwy_data_view_get_real_data_sizes ()
void | gwy_data_view_get_real_pixel_sizes ()
void | gwy_data_view_get_metric ()
GdkPixbuf * | gwy_data_view_get_pixbuf ()
void | gwy_data_view_set_named_cursor ()

## Properties

GwyColorMappingType | color-mapping | Read / Write
GwyField * | field | Read / Write
GwyGradient * | gradient | Read / Write
GwyField * | mask | Read / Write
GwyRGBA * | mask-color | Read / Write
gboolean | real-square | Read / Write
gboolean | resizable | Read / Write
double | zoom | Read / Write

## Signals

void | redrawn | Run First
void | resized | Run First

## Types and Values

| GwyDataViewClassPrivate
struct | GwyDataView
struct | GwyDataViewClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GwyDataView

## Implemented Interfaces

GwyDataView implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyDataView is a basic two-dimensional data display widget. The actual rendering is performed by one or more GwyDataViewLayer's, pluggable into the data view. Each layer generally displays different data field from the container supplied to `gwy_data_view_new()`.

The size of a data view is affected by two factors: zoom and outer constraints. If an explicit size set by window manager or by Gtk+ means, the view scales the displayed data to fit into this size (while keeping x/y ratio). Zoom controlls the size a data view requests, and can be set with `gwy_data_view_set_zoom()`.

Several helper functions are available for transformation between screen coordinates in the view and physical coordinates in the displayed data field: `gwy_data_view_coords_widget_to_real()`, `gwy_data_view_get_xmeasure()`, `gwy_data_view_get_hexcess()`, and others. Physical coordinates are always taken from data field displayed by base layer.

## Functions

### gwy_data_view_new()

    GtkWidget *
    gwy_data_view_new (void);

Creates a new data field-displaying widget.

Use `gwy_data_view_set_field()` to set the data field to display.

[constructor]

#### Returns

A newly created data view as a GtkWidget.

[transfer full]

### gwy_data_view_get_field()

    GwyField *
    gwy_data_view_get_field (GwyDataView *view);

Gets the data field currently shown by the data view.

#### Parameters

view | A data view. |

#### Returns

The currently displayed data field, possibly `NULL`.

[nullable][transfer none]

### gwy_data_view_set_field()

    void
    gwy_data_view_set_field (GwyDataView *view,
                             GwyField *field);

Sets the data field to display in a data view.

Setting the same field object repeatedly is generally a no-op. Emit GwyField::data-changed on `field` to notify the view to redraw.

#### Parameters

view | A data view. |
field | Data field to display (or `NULL`). | [transfer none][nullable]

### gwy_data_view_get_mask()

    GwyNield *
    gwy_data_view_get_mask (GwyDataView *view);

Gets the mask field currently shown by the data view.

#### Parameters

view | A data view. |

#### Returns

The currently displayed mask field, possibly `NULL`.

[nullable][transfer none]

### gwy_data_view_set_mask()

    void
    gwy_data_view_set_mask (GwyDataView *view,
                            GwyNield *mask);

Sets the mask field currently shown by the data view.

Setting the same nield object repeatedly is generally a no-op. Emit GwyNield::data-changed on `mask` to notify the view to redraw.

#### Parameters

view | A data view. |
mask | Number field to draw as the mask. | [transfer none][nullable]

### gwy_data_view_get_interactive_layer()

    GwyVectorLayer *
    gwy_data_view_get_interactive_layer (GwyDataView *view);

Returns the top layer this data view currently uses, or `NULL` if none is present.

#### Parameters

view | A data view. |

#### Returns

The currently used top layer.

### gwy_data_view_set_interactive_layer()

    void
    gwy_data_view_set_interactive_layer (GwyDataView *view,
                                         GwyVectorLayer *layer);

Plugs `layer` to `view` as the top layer.

If another top layer is present, it's unplugged.

The layer can be `NULL`, meaning no top layer is to be used.

#### Parameters

view | A data view. |
layer | A layer to be used as the top layer for `view` . |

### gwy_data_view_get_real_square()

    gboolean
    gwy_data_view_get_real_square (GwyDataView *view);

Gets the whether the aspect ratio of a data view should be based on physical or pixel coordinates.

#### Parameters

view | A data view. |

#### Returns

`TRUE` for square aspect ratio in physical coordinates; `FALSE` for square pixels.

### gwy_data_view_set_real_square()

    void
    gwy_data_view_set_real_square (GwyDataView *view,
                                   gboolean real_square);

Sets the whether the aspect ratio of a data view should be based on physical or pixel coordinates.

#### Parameters

view | A data view. |
real_square | `TRUE` for square aspect ratio in physical coordinates; `FALSE` for square pixels. |

### gwy_data_view_get_color_range()

    void
    gwy_data_view_get_color_range (GwyDataView *view,
                                   gdouble *min,
                                   gdouble *max);

Gets the actual colour mapping range of a data view.

The actual range is updated only when the widet is actually drawn. See `gwy_data_view_get_fixed_color_range()` for the fixed colour mapping range, which applied in the `GWY_COLOR_MAPPING_FIXED` mode.

#### Parameters

view | A data view. |
min | Location to store the data value corresponding to the beginning of colour mapping. | [out][nullable]
max | Location to store the data value corresponding to the end of colour mapping. | [out][nullable]

### gwy_data_view_get_fixed_color_range()

    gboolean
    gwy_data_view_get_fixed_color_range (GwyDataView *view,
                                         gdouble *min,
                                         gdouble *max);

Gets the fixed colour mapping range of a data view.

See `gwy_data_view_get_color_range()` for the actual range, even when it is automatic.

The function always fills the values. However, when it returns `FALSE` the values are not actually used.

#### Parameters

view | A data view. |
min | Location to store the data value corresponding to the beginning of fixed colour mapping. | [out][nullable]
max | Location to store the data value corresponding to the end of fixed colour mapping. | [out][nullable]

#### Returns

`TRUE` if the fixed range is set.

### gwy_data_view_set_fixed_color_range()

    void
    gwy_data_view_set_fixed_color_range (GwyDataView *view,
                                         gdouble min,
                                         gdouble max);

Sets the fixed colour mapping range of a data view.

The fixed minimum and maximum apply if the mapping type `GWY_COLOR_MAPPING_FIXED`, as set by `gwy_data_view_set_color_mapping()`.

#### Parameters

view | A data view. |
min | Data value corresponding to the beginning of fixed colour mapping. |
max | Data value corresponding to the end of fixed colour mapping. |

### gwy_data_view_unset_fixed_color_range()

    void
    gwy_data_view_unset_fixed_color_range (GwyDataView *view);

Unsets the fixed colour mapping range of a data view.

When the values are unset, the colour mapping remains `GWY_COLOR_MAPPING_FIXED` but the values are not used. So the data view behaves as if the mapping was `GWY_COLOR_MAPPING_FULL`.

#### Parameters

view | A data view. |

### gwy_data_view_get_color_mapping()

    GwyColorMappingType
    gwy_data_view_get_color_mapping (GwyDataView *view);

Gets the colour mapping type of a data view.

#### Parameters

view | A data view. |

#### Returns

The mapping type used for visualising data values as colours.

### gwy_data_view_set_color_mapping()

    void
    gwy_data_view_set_color_mapping (GwyDataView *view,
                                     GwyColorMappingType mapping);

Sets the colour mapping type of a data view.

The mapping type determines how data values are visualised as colours.

#### Parameters

view | A data view. |
mapping | Colour mapping type to use. |

### gwy_data_view_get_gradient()

    GwyGradient *
    gwy_data_view_get_gradient (GwyDataView *view);

Gets the colour gradient use for data visualisation in a data view.

If no specific gradient has been set and the default one is used, the function returns `NULL`. This is consistent with getting the corresponding property. If you still need the GwyGradient object in such case, use `gwy_gradients_get_gradient()` with `NULL` argument.

#### Parameters

view | A data view. |

#### Returns

The current colour gradient, possibly `NULL`.

[transfer none][nullable]

### gwy_data_view_set_gradient()

    void
    gwy_data_view_set_gradient (GwyDataView *view,
                                GwyGradient *gradient);

Sets the colour gradient to use for data visualisation in a data view.

If `NULL` is passed as `gradient` , the data view will use the default gradient. Within libgwyui alone, the default gradient is greyscale. However, when Gwyddion user settings are loaded, the default gradient is set according to user preferences.

#### Parameters

view | A data view. |
gradient | Colour gradient to use for data visualisation. | [transfer none][nullable]

### gwy_data_view_get_mask_color()

    void
    gwy_data_view_get_mask_color (GwyDataView *view,
                                  GwyRGBA *color);

Gets the colour used for mask visualisation in a data view.

#### Parameters

view | A data view. |
color | Colour used for mask visualisation. | [out]

### gwy_data_view_set_mask_color()

    void
    gwy_data_view_set_mask_color (GwyDataView *view,
                                  const GwyRGBA *color);

Sets the colour used for mask visualisation in a data view.

#### Parameters

view | A data view. |
color | Colour to use for mask visualisation. |

### gwy_data_view_get_hexcess()

    gdouble
    gwy_data_view_get_hexcess (GwyDataView *view);

Return the horizontal excess of widget size to data size.

Do not use. Only useful for GwyDataWindow implementation.

#### Parameters

view | A data view. |

#### Returns

The execess.

### gwy_data_view_get_vexcess()

    gdouble
    gwy_data_view_get_vexcess (GwyDataView *view);

Return the vertical excess of widget size to data size.

Do not use. Only useful for GwyDataWindow implementation.

#### Parameters

view | A data view. |

#### Returns

The execess.

### gwy_data_view_get_zoom()

    gdouble
    gwy_data_view_get_zoom (GwyDataView *view);

Returns current ideal zoom of a data view.

More precisely the zoom value requested by `gwy_data_view_set_zoom()`, if it's in use (real zoom may differ a bit due to pixel rounding). If zoom was set by explicite widget size change, real and requested zoom are considered to be the same.

When a resize is queued, the new zoom value is returned.

In other words, this is the zoom `view` would like to have. Use `gwy_data_view_get_real_zoom()` to get the real zoom.

#### Parameters

view | A data view. |

#### Returns

The zoom as a ratio between ideal displayed size and base data field size.

### gwy_data_view_set_zoom()

    void
    gwy_data_view_set_zoom (GwyDataView *view,
                            gdouble zoom);

Sets zoom of `view` to `zoom` .

Zoom greater than 1 means larger image on screen and vice versa.

Note window manager can prevent the window from resize and thus the zoom from change.

#### Parameters

view | A data view. |
zoom | A new zoom value. |

### gwy_data_view_get_real_zoom()

    gdouble
    gwy_data_view_get_real_zoom (GwyDataView *view);

Returns current real zoom of a data view.

This is the zoom value a data view may not wish to have, but was imposed by window manager or other constraints. Unlike ideal zoom set by `gwy_data_view_set_zoom()`, this value cannot be set.

When a resize is queued, the current (old) value is returned.

#### Parameters

view | A data view. |

#### Returns

The zoom as a ratio between real displayed size and base data field size.

### gwy_data_view_coords_widget_clamp()

    gboolean
    gwy_data_view_coords_widget_clamp (GwyDataView *view,
                                       gdouble *xscr,
                                       gdouble *yscr);

Fixes screen coordinates `xscr` and `yscr` to be inside the data-displaying area (which can be smaller than widget size).

#### Parameters

view | A data view. |
xscr | A screen x-coordinate relative to widget origin. |
yscr | A screen y-coordinate relative to widget origin. |

#### Returns

`TRUE` if coordinates are inside the widget area.

### gwy_data_view_coords_widget_cut_line()

    gboolean
    gwy_data_view_coords_widget_cut_line (GwyDataView *view,
                                          gdouble *x0scr,
                                          gdouble *y0scr,
                                          gdouble *x1scr,
                                          gdouble *y1scr);

Fixes screen coordinates of line endpoints to be inside the data-displaying area (which can be smaller than widget size).

#### Parameters

view | A data view. |
x0scr | First point screen x-coordinate relative to widget origin. |
y0scr | First point screen y-coordinate relative to widget origin. |
x1scr | Second point screen x-coordinate relative to widget origin. |
y1scr | Second point screen y-coordinate relative to widget origin. |

#### Returns

`TRUE` if line was entirely inside the area.

### gwy_data_view_coords_widget_to_real()

    void
    gwy_data_view_coords_widget_to_real (GwyDataView *view,
                                         gdouble xscr,
                                         gdouble yscr,
                                         gdouble *xreal,
                                         gdouble *yreal);

Recomputes screen coordinates relative to widget origin to physical coordinates in the sample.

Note that data fields offsets are not taken into account. Coordinates `xreal` , `yreal` are just relative coordinates to the top left field corner.

#### Parameters

view | A data view. |
xscr | A screen x-coordinate relative to widget origin. |
yscr | A screen y-coordinate relative to widget origin. |
xreal | Where the physical x-coordinate in the data sample should be stored. |
yreal | Where the physical y-coordinate in the data sample should be stored. |

### gwy_data_view_coords_real_to_widget()

    void
    gwy_data_view_coords_real_to_widget (GwyDataView *view,
                                         gdouble xreal,
                                         gdouble yreal,
                                         gdouble *xscr,
                                         gdouble *yscr);

Recomputes physical coordinate in the sample to screen coordinate relative to widget origin, keeping them as floating point values.

Note that data fields offsets are not taken into account. Coordinates `xreal` , `yreal` are just relative coordinates to the top left field corner.

#### Parameters

view | A data view. |
xreal | A physical x-coordinate in the data sample. |
yreal | A physical y-coordinate in the data sample. |
xscr | Where the screen x-coordinate relative to widget origin should be stored. |
yscr | Where the screen y-coordinate relative to widget origin should be stored. |

### gwy_data_view_get_xmeasure()

    gdouble
    gwy_data_view_get_xmeasure (GwyDataView *view);

Returns the ratio between horizontal physical lengths and horizontal screen lengths in pixels.

Note that screen pixels are not image pixels. The ratio between real horizontal distances and image pixel distances can be obtained using `gwy_field_get_dx()` on the displayed GwyField or by `gwy_data_view_get_real_pixel_sizes()`.

#### Parameters

view | A data view. |

#### Returns

The horizontal measure.

### gwy_data_view_get_ymeasure()

    gdouble
    gwy_data_view_get_ymeasure (GwyDataView *view);

Returns the ratio between vertical physical lengths and vertical screen lengths in pixels.

Note that screen pixels are not image pixels. The ratio between real vertical distances and image pixel distances can be obtained using `gwy_field_get_dy()` on the displayed GwyField or by `gwy_data_view_get_real_pixel_sizes()`.

#### Parameters

view | A data view. |

#### Returns

The vertical measure.

### gwy_data_view_get_xzoom()

    gdouble
    gwy_data_view_get_xzoom (GwyDataView *view);

Gets the ratio between screen and image horizontal coordinates in a data view.

#### Parameters

view | A data view. |

#### Returns

The ratio between horizontal image and screen pixel sizes.

### gwy_data_view_get_yzoom()

    gdouble
    gwy_data_view_get_yzoom (GwyDataView *view);

Gets the ratio between screen and image vertical coordinates in a data view.

#### Parameters

view | A data view. |

#### Returns

The ratio between vertical image and screen pixel sizes.

### gwy_data_view_set_resizable()

    void
    gwy_data_view_set_resizable (GwyDataView *view,
                                 gboolean resizable);

Sets the resizeability of a data view.

By default, data views adapt to any size they get allocated and request very small minimum size. This is useful in data windows which should be freely resizeable, for instance.

Module dialogs usually have small fixed-size previews. The data view never grows, but could be still shrinked. In such case `resizable` should be set to `FALSE` to prevent the shrinking. The data view will then request minimum size according to zoom.

#### Parameters

view | A data view. |
resizable | `TRUE` to make the data view user-resizeable; `FALSE` to request fixed size according to the zoom. |

### gwy_data_view_get_pixel_data_sizes()

    void
    gwy_data_view_get_pixel_data_sizes (GwyDataView *view,
                                        gint *xres,
                                        gint *yres);

Obtains pixel dimensions of data displayed by a data view.

This is a convenience method, the same values could be obtained by `gwy_field_get_xres()` and `gwy_field_get_yres()` of the data field.

#### Parameters

view | A data view. |
xres | Location to store x-resolution of displayed data (or `NULL`). |
yres | Location to store y-resolution of displayed data (or `NULL`). |

### gwy_data_view_get_real_data_sizes()

    void
    gwy_data_view_get_real_data_sizes (GwyDataView *view,
                                       gdouble *xreal,
                                       gdouble *yreal);

Obtains physical dimensions of data displayed by a data view.

Physical coordinates are always taken from base data field. This is a convenience method, the same values could be obtained by `gwy_field_get_xreal()` and `gwy_field_get_yreal()` of the data field.

#### Parameters

view | A data view. |
xreal | Location to store physical x-dimension of the displayed data without excess (or `NULL`). |
yreal | Location to store physical y-dimension of the displayed data without excess (or `NULL`). |

### gwy_data_view_get_real_pixel_sizes()

    void
    gwy_data_view_get_real_pixel_sizes (GwyDataView *view,
                                        gdouble *dx,
                                        gdouble *dy);

Obtains physical sampling steps of data displayed by a data view.

Physical coordinates are always taken from base data field. This is a convenience method, the same values could be obtained by `gwy_field_get_dx()` and `gwy_field_get_dy()` of the data field.

#### Parameters

view | A data view. |
dx | Location to store physical sampling step along the x-axis of the displayed image (or `NULL`). |
dy | Location to store physical sampling step along the y-axis of the displayed image (or `NULL`). |

### gwy_data_view_get_metric()

    void
    gwy_data_view_get_metric (GwyDataView *view,
                              gdouble *metric);

Fills metric matrix for a data view.

The metric matrix essentially transforms distances in physical coordinates to screen distances. It is to be used with functions like `gwy_math_find_nearest_point()` and `gwy_math_find_nearest_line()` when the distance should be screen-Euclidean.

#### Parameters

view | A data view. |
metric | Metric matrix 2x2 (stored in sequentially by rows: m11, m12, m12, m22). |

### gwy_data_view_get_pixbuf()

    GdkPixbuf *
    gwy_data_view_get_pixbuf (GwyDataView *view,
                              gint max_width,
                              gint max_height);

Creates and returns a pixbuf from the data view.

If the data is not square, the resulting pixbuf is also nonsquare. The returned pixbuf also never has an alpha channel.

#### Parameters

view | A data view. |
max_width | Pixbuf width that should not be exceeeded. Value smaller than 1 means unlimited size. |
max_height | Pixbuf height that should not be exceeeded. Value smaller than 1 means unlimited size. |

#### Returns

The pixbuf as a newly created GdkPixbuf, it should be freed when no longer needed. It is never larger than the actual data size, as `max_width` and `max_height` are only upper limits.

[transfer full]

### gwy_data_view_set_named_cursor()

    void
    gwy_data_view_set_named_cursor (GwyDataView *view,
                                    const gchar *name);

Sets the pointer cursor for a data view to a named cursor.

The cursor name is the same as one would pass to `gdk_cursor_new_from_name()`.

The data view needs to be realised.

This function is intended for the implementation of editable data view layers. If an application sets the cursor, a data view layer will likely change it again soon.

#### Parameters

view | A data view. |
name | A cursor name, or `NULL`. |

## Types and Values

### GwyDataViewClassPrivate

    typedef struct _GwyDataViewClassPrivate GwyDataViewClassPrivate;

### struct GwyDataView

    struct GwyDataView;

### struct GwyDataViewClass

    struct GwyDataViewClass {
        GtkWidgetClass parent_class;

        /* Signals */
        void (*redrawn)(GwyDataView *view);
        void (*resized)(GwyDataView *view);
    };

## Property Details

### The `“color-mapping”` property

      “color-mapping”            GwyColorMappingType

Type of mapping from data values to colors.

Owner: GwyDataView

Flags: Read / Write

Default value: GWY_COLOR_MAPPING_FULL

### The `“field”` property

      “field”                    GwyField *

Data field to display.

Owner: GwyDataView

Flags: Read / Write

### The `“gradient”` property

      “gradient”                 GwyGradient *

Color gradient used for data visualization.

Owner: GwyDataView

Flags: Read / Write

### The `“mask”` property

      “mask”                     GwyField *

Mask field to display.

Owner: GwyDataView

Flags: Read / Write

### The `“mask-color”` property

      “mask-color”               GwyRGBA *

Color use for mask visualization.

Owner: GwyDataView

Flags: Read / Write

### The `“real-square”` property

      “real-square”              gboolean

Whether to display data with physical aspect ratio (as opposed to square pixels).

Owner: GwyDataView

Flags: Read / Write

Default value: FALSE

### The `“resizable”` property

      “resizable”                gboolean

Whether resizing by the user is enabled.

Owner: GwyDataView

Flags: Read / Write

Default value: TRUE

### The `“zoom”` property

      “zoom”                     double

The size of a pixel on screen, in horizontal direction.

Owner: GwyDataView

Flags: Read / Write

Allowed values: [0.015625,64]

Default value: 1

## Signal Details

### The `“redrawn”` signal

    void
    user_function (GwyDataView *gwydataview,
                   gpointer     user_data)

The ::redrawn signal is emitted when GwyDataView redraws pixbufs after an update. That is, when it's the right time to get a new pixbuf from `gwy_data_view_get_pixbuf()`.

#### Parameters

gwydataview | The GwyDataView which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“resized”` signal

    void
    user_function (GwyDataView *gwydataview,
                   gpointer     user_data)

The ::resized signal is emitted when GwyDataView wants to be resized, that is when the dimensions of base data field changes or square mode is changed. Its purpose is to subvert the normal resizing logic of GwyDataWindow (due to geometry hints, its size requests are generally ignored, so an explicit resize is needed). You should usually ignore it.

#### Parameters

gwydataview | The GwyDataView which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GwyDataWindow -- window combining data view with other controls, GwyDataViewLayer -- layers a data view is composed of,

pixbuf-render --

low level functions for painting data fields, Gwy3DView -- OpenGL 3D data display