GwyMarkerBox: Gwyddion Widgets Library Reference Manual

## 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
int | 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.

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

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