GwyDataView: Gwyddion Widgets Library Reference Manual

## GwyDataView GwyDataView — Data field displaying area |

## Functions

GtkWidget * | gwy_data_view_new ()
GwyPixmapLayer * | gwy_data_view_get_base_layer ()
void | gwy_data_view_set_base_layer ()
GwyPixmapLayer * | gwy_data_view_get_alpha_layer ()
void | gwy_data_view_set_alpha_layer ()
GwyVectorLayer * | gwy_data_view_get_top_layer ()
void | gwy_data_view_set_top_layer ()
const gchar * | gwy_data_view_get_data_prefix ()
void | gwy_data_view_set_data_prefix ()
gdouble | gwy_data_view_get_hexcess ()
gdouble | gwy_data_view_get_vexcess ()
void | gwy_data_view_set_zoom ()
gdouble | gwy_data_view_get_zoom ()
gdouble | gwy_data_view_get_real_zoom ()
GwyContainer * | gwy_data_view_get_data ()
void | gwy_data_view_coords_xy_clamp ()
void | gwy_data_view_coords_xy_cut_line ()
void | gwy_data_view_coords_xy_to_real ()
void | gwy_data_view_coords_real_to_xy ()
void | gwy_data_view_coords_real_to_xy_float ()
gdouble | gwy_data_view_get_xmeasure ()
gdouble | gwy_data_view_get_ymeasure ()
void | gwy_data_view_get_pixel_data_sizes ()
void | gwy_data_view_get_real_data_sizes ()
void | gwy_data_view_get_real_data_offsets ()
void | gwy_data_view_get_metric ()
GdkPixbuf * | gwy_data_view_get_pixbuf ()
GdkPixbuf * | gwy_data_view_export_pixbuf ()

## Properties

char * | data-prefix | Read / Write
double | zoom | Read / Write

## Signals

void | layer-plugged | Run First
void | layer-unplugged | Run First
void | redrawn | Run First
void | resized | Run First

## Types and Values

struct | GwyDataView
struct | GwyDataViewClass

## Object Hierarchy

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

## Implemented Interfaces

GwyDataView implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgwydgets/gwydgets.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()`.

A base layer (set with `gwy_data_view_set_base_layer()`) must be always present, and normally it is always a GwyLayerBasic.

Other layers are optional. Middle, or alpha, layer (set with `gwy_data_view_set_alpha_layer()`) used to display masks is normally always a GwyLayerMask. Top layer, if present, is a GwyVectorLayer allowing to draw selections with mouse and otherwise interace with the view, it is set with `gwy_data_view_set_top_layer()`.

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_xy_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 (GwyContainer *data);

Creates a new data-displaying widget for `data` .

A newly created GwyDataView doesn't display anything. You have to add some layers to it, at least a base layer with `gwy_data_view_set_base_layer()`, and possibly others with `gwy_data_view_set_alpha_layer()` and `gwy_data_view_set_top_layer()`.

The top layer is special. It must be a vector layer and can receive mouse and keyboard events.

The base layer it also special. It must be always present, and must not be transparent or vector.

#### Parameters

data | A GwyContainer containing the data to display. |

#### Returns

A newly created data view as a GtkWidget.

### gwy_data_view_get_base_layer ()

    GwyPixmapLayer *
    gwy_data_view_get_base_layer (GwyDataView *data_view);

Returns the base layer this data view currently uses.

A base layer should be always present.

#### Parameters

data_view | A data view. |

#### Returns

The currently used base layer.

### gwy_data_view_set_base_layer ()

    void
    gwy_data_view_set_base_layer (GwyDataView *data_view,
                                  GwyPixmapLayer *layer);

Plugs `layer` to `data_view` as the base layer.

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

The layer must not be a vector layer. Theoretically, it can be `NULL` to use no base layer, but then `data_view` will probably display garbage.

#### Parameters

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

### gwy_data_view_get_alpha_layer ()

    GwyPixmapLayer *
    gwy_data_view_get_alpha_layer (GwyDataView *data_view);

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

#### Parameters

data_view | A data view. |

#### Returns

The currently used alpha layer.

### gwy_data_view_set_alpha_layer ()

    void
    gwy_data_view_set_alpha_layer (GwyDataView *data_view,
                                   GwyPixmapLayer *layer);

Plugs `layer` to `data_view` as the alpha layer.

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

The layer must not be a vector layer. It can be `NULL`, meaning no alpha layer is to be used.

#### Parameters

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

### gwy_data_view_get_top_layer ()

    GwyVectorLayer *
    gwy_data_view_get_top_layer (GwyDataView *data_view);

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

#### Parameters

data_view | A data view. |

#### Returns

The currently used top layer.

### gwy_data_view_set_top_layer ()

    void
    gwy_data_view_set_top_layer (GwyDataView *data_view,
                                 GwyVectorLayer *layer);

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

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

The layer must be a vector layer. It can be `NULL`, meaning no top layer is to be used.

#### Parameters

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

### gwy_data_view_get_data_prefix ()

    const gchar *
    gwy_data_view_get_data_prefix (GwyDataView *data_view);

Gets the prefix for the container data channel that the data view is currently set to display.

#### Parameters

data_view | A data view. |

#### Returns

The container data prefix (eg. "/0/data").

### gwy_data_view_set_data_prefix ()

    void
    gwy_data_view_set_data_prefix (GwyDataView *data_view,
                                   const gchar *prefix);

Sets the prefix for the container data channel to display in a data view.

This function only affects where the data view itself takes parameters from, it does not affect layer keys.

#### Parameters

data_view | A data view. |
prefix | Container prefix for data (eg. "/0/data"). |

### gwy_data_view_get_hexcess ()

    gdouble
    gwy_data_view_get_hexcess (GwyDataView *data_view);

Return the horizontal excess of widget size to data size.

Do not use. Only useful for GwyDataWindow implementation.

#### Parameters

data_view | A data view. |

#### Returns

The execess.

### gwy_data_view_get_vexcess ()

    gdouble
    gwy_data_view_get_vexcess (GwyDataView *data_view);

Return the vertical excess of widget size to data size.

Do not use. Only useful for GwyDataWindow implementation.

#### Parameters

data_view | A data view. |

#### Returns

The execess.

### gwy_data_view_set_zoom ()

    void
    gwy_data_view_set_zoom (GwyDataView *data_view,
                            gdouble zoom);

Sets zoom of `data_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

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

### gwy_data_view_get_zoom ()

    gdouble
    gwy_data_view_get_zoom (GwyDataView *data_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 `data_view` would like to have. Use `gwy_data_view_get_real_zoom()` to get the real zoom.

#### Parameters

data_view | A data view. |

#### Returns

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

### gwy_data_view_get_real_zoom ()

    gdouble
    gwy_data_view_get_real_zoom (GwyDataView *data_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

data_view | A data view. |

#### Returns

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

### gwy_data_view_get_data ()

    GwyContainer *
    gwy_data_view_get_data (GwyDataView *data_view);

Returns the data container used by `data_view` .

#### Parameters

data_view | A data view. |

#### Returns

The data as a GwyContainer.

### gwy_data_view_coords_xy_clamp ()

    void
    gwy_data_view_coords_xy_clamp (GwyDataView *data_view,
                                   gint *xscr,
                                   gint *yscr);

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

#### Parameters

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

### gwy_data_view_coords_xy_cut_line ()

    void
    gwy_data_view_coords_xy_cut_line (GwyDataView *data_view,
                                      gint *x0scr,
                                      gint *y0scr,
                                      gint *x1scr,
                                      gint *y1scr);

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

#### Parameters

data_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. |

Since: 2.11

### gwy_data_view_coords_xy_to_real ()

    void
    gwy_data_view_coords_xy_to_real (GwyDataView *data_view,
                                     gint xscr,
                                     gint 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

data_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_xy ()

    void
    gwy_data_view_coords_real_to_xy (GwyDataView *data_view,
                                     gdouble xreal,
                                     gdouble yreal,
                                     gint *xscr,
                                     gint *yscr);

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

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

#### Parameters

data_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_coords_real_to_xy_float ()

    void
    gwy_data_view_coords_real_to_xy_float (GwyDataView *data_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

data_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. |

Since: 2.45

### gwy_data_view_get_xmeasure ()

    gdouble
    gwy_data_view_get_xmeasure (GwyDataView *data_view);

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

#### Parameters

data_view | A data view. |

#### Returns

The horizontal measure.

### gwy_data_view_get_ymeasure ()

    gdouble
    gwy_data_view_get_ymeasure (GwyDataView *data_view);

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

#### Parameters

data_view | A data view. |

#### Returns

The vertical measure.

### gwy_data_view_get_pixel_data_sizes ()

    void
    gwy_data_view_get_pixel_data_sizes (GwyDataView *data_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_data_field_get_xres()` and `gwy_data_field_get_yres()` of the data field displayed by the base layer.

#### Parameters

data_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 *data_view,
                                       gdouble *xreal,
                                       gdouble *yreal);

Obtains physical dimensions of data displayed by a data view.

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

#### Parameters

data_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_data_offsets ()

    void
    gwy_data_view_get_real_data_offsets (GwyDataView *data_view,
                                         gdouble *xoffset,
                                         gdouble *yoffset);

Obtains physical offsets of data displayed by a data view.

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

#### Parameters

data_view | A data view. |
xoffset | Location to store physical x-offset of the top corner of displayed data without excess (or `NULL`). |
yoffset | Location to store physical y-offset of the top corner of displayed data without excess (or `NULL`). |

Since: 2.16

### gwy_data_view_get_metric ()

    void
    gwy_data_view_get_metric (GwyDataView *data_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

data_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 *data_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

data_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.

### gwy_data_view_export_pixbuf ()

    GdkPixbuf *
    gwy_data_view_export_pixbuf (GwyDataView *data_view,
                                 gdouble zoom,
                                 gboolean draw_alpha,
                                 gboolean draw_top);

Exports data view to a pixbuf.

#### Parameters

data_view | A data view. |
zoom | Zoom to export data with (unrelated to data view zoom). |
draw_alpha | `TRUE` to draw alpha layer (mask). |
draw_top | `TRUE` to draw top layer (selection). |

#### Returns

A newly created pixbuf, it must be freed by caller.

## Types and Values

### struct GwyDataView

    struct GwyDataView;

### struct GwyDataViewClass

    struct GwyDataViewClass {
        GtkWidgetClass parent_class;

        /* Signals */
        void (*redrawn)(GwyDataView *data_view);
        void (*resized)(GwyDataView *data_view);
        void (*layer_plugged)(GwyDataView *data_view,
                              GwyDataViewLayerType layer);
        void (*layer_unplugged)(GwyDataView *data_view,
                                GwyDataViewLayerType layer);

        void (*reserved1)(void);
        void (*reserved2)(void);
    };

## Property Details

### The `“data-prefix”` property

      “data-prefix”              char *

The :data-prefix property is the container prefix the data displayed by this view lies under.

Note it is only used for items used by GwyDataView itself, layers have their own keys.

Owner: GwyDataView

Flags: Read / Write

Default value: NULL

### The `“zoom”` property

      “zoom”                     double

The :zoom property is the ratio between displayed and real data size.

Owner: GwyDataView

Flags: Read / Write

Allowed values: [0.0625,16]

Default value: 1

## Signal Details

### The `“layer-plugged”` signal

    void
    user_function (GwyDataView         *arg1,
                   GwyDataViewLayerType gwydataview,
                   gpointer             user_data)

The ::layer-plugged signal is emitted when a layer is plugged into a GwyDataView.

When a layer replaces an existing layer, ::layer-unplugged is emitted once the old layer is unplugged, then ::layer-plugged when the new is plugged.

#### Parameters

arg1 | Which layer was plugged (a GwyDataViewLayerType value). |
gwydataview | The GwyDataView which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“layer-unplugged”` signal

    void
    user_function (GwyDataView         *arg1,
                   GwyDataViewLayerType gwydataview,
                   gpointer             user_data)

The ::layer-unplugged signal is emitted when a layer is unplugged from a GwyDataView.

When a layer replaces an existing layer, ::layer-unplugged is emitted once the old layer is unplugged, then ::layer-plugged when the new is plugged.

#### Parameters

arg1 | Which layer was unplugged (a GwyDataViewLayerType value). |
gwydataview | The GwyDataView which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### 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,

gwypixfield --

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