GwyMarkerBox (HEAD)

GwyMarkerBox — Base class for box with movable markers.

Functions

Properties

Signals

Types and Values

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

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

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

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

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

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

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

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

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

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

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

gwy_marker_box_get_flipped ()

gboolean
gwy_marker_box_get_flipped (GwyMarkerBox *mbox);

Returns whether a marker box is drawn upside down.

Parameters

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

gwy_marker_box_get_highlight_selected ()

gboolean
gwy_marker_box_get_highlight_selected (GwyMarkerBox *mbox);

Returns whether a marker box highlights selected marker.

Parameters

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

gwy_marker_box_get_validator ()

GwyMarkerValidateFunc
gwy_marker_box_get_validator (GwyMarkerBox *mbox);

Gets the marker validation function currently in use.

Parameters

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.

Owner: GwyMarkerBox

Flags: Read / Write

Default value: FALSE

The “highlight-selected” property

  “highlight-selected”       gboolean

Whether to visually differentiate selected marker.

Owner: GwyMarkerBox

Flags: Read / Write

Default value: TRUE

The “selected-marker” property

  “selected-marker”          int

The index of selected marker, -1 if none.

Owner: GwyMarkerBox

Flags: Read / Write

Allowed values: [-1,1024]

Default value: -1

Signal Details

The “marker-added” signal

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

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

Parameters

Flags: Run First

The “marker-moved” signal

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

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

Parameters

Flags: Run First

The “marker-removed” signal

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

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

Parameters

Flags: Run First

The “marker-selected” signal

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

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

Parameters

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

Flags: Run First