Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyMarkerBox

GwyMarkerBox — Base class for box with movable markers.

Functions

gboolean (*GwyMarkerValidateFunc) ()
gint gwy_marker_box_get_selected_marker ()
void gwy_marker_box_set_selected_marker ()
gdouble gwy_marker_box_get_marker_position ()
gboolean gwy_marker_box_set_marker_position ()
gint gwy_marker_box_add_marker ()
gboolean gwy_marker_box_remove_marker ()
gint gwy_marker_box_get_nmarkers ()
const gdouble * gwy_marker_box_get_markers ()
void gwy_marker_box_set_markers ()
void gwy_marker_box_set_flipped ()
gboolean gwy_marker_box_get_flipped ()
void gwy_marker_box_set_highlight_selected ()
gboolean gwy_marker_box_get_highlight_selected ()
void gwy_marker_box_set_validator ()
GwyMarkerValidateFunc gwy_marker_box_get_validator ()

Properties

gboolean flipped Read / Write
gboolean highlight-selected Read / Write
gint selected-marker Read / Write

Signals

void marker-added Run First
void marker-moved Run First
void marker-removed Run First
void marker-selected Run First
void markers-set Run First

Types and Values

struct GwyMarkerBox
struct GwyMarkerBoxClass

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GwyMarkerBox
                    ╰── GwyHMarkerBox

Implemented Interfaces

GwyMarkerBox implements AtkImplementorIface and GtkBuildable.

Includes

#include <libgwydgets/gwydgets.h>

Description

GwyMarkerBox is a box with triangular markers that can be moved, added, and/or deleted. One or no marker can be selected.

Marker coordinates are always from the range [0.0, 1.0].

It is possible to fully control where and how user can move, add, and/or delete markers with marker validation function set with gwy_marker_box_set_validator(). By default, no validator is in effect and user can change markers completely freely.

Functions

GwyMarkerValidateFunc ()

gboolean
(*GwyMarkerValidateFunc) (GwyMarkerBox *mbox,
                          GwyMarkerOperationType optype,
                          gint *i,
                          gdouble *pos);

Marker validation function.

It is called for each single-marker change, both by user and by GwyMarkerBox methods. However, it is NOT called upon gwy_marker_box_set_markers() as it is unclear how the validation should proceed.

The function must not have any side-effects, that is it must not assume the operation will be actually performed when it returns TRUE.

Marker validator that allows free marker movement but disables insertion and removal could look:

1
2
3
4
5
6
7
8
9
10
11
static gboolean
validate_marker(GwyMarkerBox *mbox,
                GwyMarkerOperationType optype,
                gint *i,
                gdouble *pos)
{
    if (optype == GWY_MARKER_OPERATION_ADD
        || optype == GWY_MARKER_OPERATION_REMOVE)
        return FALSE;
    return TRUE;
}

Marker validator that assures markers are sorted and there is always a marker at 0.0 and another at 1.0 could look:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
static gboolean
validate_marker(GwyMarkerBox *mbox,
                GwyMarkerOperationType optype,
                gint *i,
                gdouble *pos)
{
    const gdouble *markers;
    gint j, n;

    n = gwy_marker_box_get_nmarkers(mbox);

    /* Insertions are sorted */
    if (optype == GWY_MARKER_OPERATION_ADD) {
        markers = gwy_marker_box_get_markers(mbox);
        for (j = 0; j < n; j++) {
            if (*pos < markers[j])
                break;
        }
        if (j == 0 || j == n)
            return FALSE;
        *i = j;
        return TRUE;
    }

    /* Nothing at all can be done with border markers */
    if (*i == 0 || *i == n-1)
        return FALSE;

    /* Inner markers can be moved only from previous to next */
    if (optype == GWY_MARKER_OPERATION_MOVE) {
        markers = gwy_marker_box_get_markers(mbox);
        *pos = CLAMP(*pos, markers[*i - 1], markers[*i + 1]);
    }
    return TRUE;
}

Parameters

mbox

The GwyMarkerBox to validate markers for.

 

optype

Marker operation to validate.

 

i

Pointer to index of marker to validate. For insertion, it's the position the marker would be inserted to (but it's not there yet), for removal it's the position where it still is. The validator can change the index, but it has an effect only when a marker is being added.

 

pos

Pointer to requested marker position. The validator can change the position and the marker will be then moved or inserted to the changed position. For removal, its changes have no effect.

 

Returns

TRUE to allow requested the operation, FALSE to disallow it.

gwy_marker_box_get_selected_marker ()

gint
gwy_marker_box_get_selected_marker (GwyMarkerBox *mbox);

Gets the index of the currently selected marker in a marker box.

Parameters

mbox

A marker box.

 

Returns

The index of currently selected marker, -1 when none is selected.

gwy_marker_box_set_selected_marker ()

void
gwy_marker_box_set_selected_marker (GwyMarkerBox *mbox,
                                    gint i);

Selects a marker in a marker box.

Parameters

mbox

A marker box.

 

i

The index of marker to select. Pass -1 to unselect.

 

gwy_marker_box_get_marker_position ()

gdouble
gwy_marker_box_get_marker_position (GwyMarkerBox *mbox,
                                    gint i);

Gets the position of a marker in a marker box.

Parameters

mbox

A marker box.

 

i

The index of marker to get position of.

 

Returns

The marker position, in the range [0.0, 1.0].

gwy_marker_box_set_marker_position ()

gboolean
gwy_marker_box_set_marker_position (GwyMarkerBox *mbox,
                                    gint i,
                                    gdouble pos);

Moves a marker in a marker box.

Parameters

mbox

A marker box.

 

i

Index of marker to move.

 

pos

The new marker position, in the range [0.0, 1.0].

 

Returns

TRUE on success. If the move does not validate, FALSE is returned and the marker position does not change.

gwy_marker_box_add_marker ()

gint
gwy_marker_box_add_marker (GwyMarkerBox *mbox,
                           gint i,
                           gdouble pos);

Adds a marker to a marker box.

Parameters

mbox

A marker box.

 

i

Index to insert marker at.

 

pos

Position to insert marker to, in the range [0.0, 1.0].

 

Returns

On success, the index the marker was added at. If the insertion does not validate, -1 is returned and no marker is added.

gwy_marker_box_remove_marker ()

gboolean
gwy_marker_box_remove_marker (GwyMarkerBox *mbox,
                              gint i);

Removes a marker from a marker box.

Parameters

mbox

A marker box.

 

i

Index of marker to remove.

 

Returns

TRUE on success. If the removal does not validate, FALSE is returned and the marker is kept.

gwy_marker_box_get_nmarkers ()

gint
gwy_marker_box_get_nmarkers (GwyMarkerBox *mbox);

Gets the number of markers in a marker box.

Parameters

mbox

A marker box.

 

Returns

The number of markers.

gwy_marker_box_get_markers ()

const gdouble *
gwy_marker_box_get_markers (GwyMarkerBox *mbox);

Gets all markers in a marker box.

Parameters

mbox

A marker box.

 

Returns

The markers as an array of positions, owned by mbox . It must not be modified nor freed by caller and it's valid only until next marker change.

gwy_marker_box_set_markers ()

void
gwy_marker_box_set_markers (GwyMarkerBox *mbox,
                            gint n,
                            const gdouble *markers);

Sets positions of all markers in a marker box.

No validation is performed, even if validator is set. It's up to caller to set markers that do not logically conflict with the validator.

Parameters

mbox

A marker box.

 

n

The number of markers to set. If it is zero, markers can be NULL.

 

markers

Markers position.

 

gwy_marker_box_set_flipped ()

void
gwy_marker_box_set_flipped (GwyMarkerBox *mbox,
                            gboolean flipped);

Sets whether a marker box is drawn upside down.

Parameters

mbox

A marker box.

 

flipped

TRUE to draw markers upside down.

 

gwy_marker_box_get_flipped ()

gboolean
gwy_marker_box_get_flipped (GwyMarkerBox *mbox);

Returns whether a marker box is drawn upside down.

Parameters

mbox

A marker box.

 

Returns

TRUE if markers are drawn upside down.

gwy_marker_box_set_highlight_selected ()

void
gwy_marker_box_set_highlight_selected (GwyMarkerBox *mbox,
                                       gboolean highlight);

Sets whether a marker box highlights selected marker.

Parameters

mbox

A marker box.

 

highlight

TRUE to visually differentiate selected marker, FALSE to draw markers uniformly.

 

gwy_marker_box_get_highlight_selected ()

gboolean
gwy_marker_box_get_highlight_selected (GwyMarkerBox *mbox);

Returns whether a marker box highlights selected marker.

Parameters

mbox

A marker box.

 

Returns

TRUE if selected marker is visually differentiated, FALSE if markers are drawn uniformly.

gwy_marker_box_set_validator ()

void
gwy_marker_box_set_validator (GwyMarkerBox *mbox,
                              GwyMarkerValidateFunc validate);

Sets marker box marker validation function.

It is used the next time an attempt to change markers is made, no revalidation is done immediately. It's up to caller to set a validator that do not logically conflict with the distribution of markers.

Parameters

mbox

A marker box.

 

validate

Marker validation function. Pass NULL to disable validation.

 

gwy_marker_box_get_validator ()

GwyMarkerValidateFunc
gwy_marker_box_get_validator (GwyMarkerBox *mbox);

Gets the marker validation function currently in use.

Parameters

mbox

A marker box.

 

Returns

The marker validation function.

Types and Values

struct GwyMarkerBox

struct GwyMarkerBox;

struct GwyMarkerBoxClass

struct GwyMarkerBoxClass {
    GtkWidgetClass parent_class;

    /* signals */
    void (*marker_selected)(GwyMarkerBox *mbox,
                            gint i);
    void (*marker_moved)(GwyMarkerBox *mbox,
                         gint i);
    void (*marker_added)(GwyMarkerBox *mbox,
                         gint i);
    void (*marker_removed)(GwyMarkerBox *mbox,
                           gint i);
    void (*markers_set)(GwyMarkerBox *mbox);

    /* virtual methods */
    void (*draw_box)(GwyMarkerBox *mbox);
    void (*draw_marker)(GwyMarkerBox *mbox,
                        gint i);

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

Property Details

The “flipped” property

  “flipped”                  gboolean

Whether marks are drawn upside down.

Flags: Read / Write

Default value: FALSE

The “highlight-selected” property

  “highlight-selected”       gboolean

Whether to visually differentiate selected marker.

Flags: Read / Write

Default value: TRUE

The “selected-marker” property

  “selected-marker”          gint

The index of selected marker, -1 if none.

Flags: Read / Write

Allowed values: [-1,1024]

Default value: -1

Signal Details

The “marker-added” signal

void
user_function (GwyMarkerBox *arg1,
               gint          gwymarkerbox,
               gpointer      user_data)

The ::marker-added signal is emitted when a marker is added.

Parameters

arg1

The index a marker was added at.

 

gwymarkerbox

The GwyMarkerBox which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

The “marker-moved” signal

void
user_function (GwyMarkerBox *arg1,
               gint          gwymarkerbox,
               gpointer      user_data)

The ::marker-moved signal is emitted when a marker is moved.

Parameters

arg1

The index of moved marker.

 

gwymarkerbox

The GwyMarkerBox which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

The “marker-removed” signal

void
user_function (GwyMarkerBox *arg1,
               gint          gwymarkerbox,
               gpointer      user_data)

The ::marker-removed signal is emitted when a marker is removed.

Parameters

arg1

The index a marker was removed from.

 

gwymarkerbox

The GwyMarkerBox which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

The “marker-selected” signal

void
user_function (GwyMarkerBox *arg1,
               gint          gwymarkerbox,
               gpointer      user_data)

The ::marker-selected signal is emitted when marker selection changes.

Parameters

arg1

The index of selected marker, -1 when marker was unselected.

 

gwymarkerbox

The GwyMarkerBox which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

The “markers-set” signal

void
user_function (GwyMarkerBox *gwymarkerbox,
               gpointer      user_data)

The ::markers-set signal is emitted when markers are explicitly set with gwy_marker_box_set_markers().

Parameters

gwymarkerbox

The GwyMarkerBox which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS