GwyAdjustBar: Gwyddion Widgets Library Reference Manual

## GwyAdjustBar GwyAdjustBar — Compact adjustment visualisation and modification |

## Functions

GtkWidget * | gwy_adjust_bar_new ()
void | gwy_adjust_bar_set_adjustment ()
GtkAdjustment * | gwy_adjust_bar_get_adjustment ()
void | gwy_adjust_bar_set_snap_to_ticks ()
gboolean | gwy_adjust_bar_get_snap_to_ticks ()
void | gwy_adjust_bar_set_mapping ()
GwyScaleMappingType | gwy_adjust_bar_get_mapping ()
void | gwy_adjust_bar_set_has_check_button ()
gboolean | gwy_adjust_bar_get_has_check_button ()
void | gwy_adjust_bar_set_bar_sensitive ()
gboolean | gwy_adjust_bar_get_bar_sensitive ()
GtkWidget * | gwy_adjust_bar_get_label ()
GtkWidget * | gwy_adjust_bar_get_check_button ()

## Properties

GtkAdjustment * | adjustment | Read / Write
gboolean | has-check-button | Read / Write
GwyScaleMappingType | mapping | Read / Write
gboolean | snap-to-ticks | Read / Write

## Signals

void | change-value | Action

## Types and Values

enum | GwyScaleMappingType
struct | GwyAdjustBar
struct | GwyAdjustBarClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GwyAdjustBar

## Implemented Interfaces

GwyAdjustBar implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyAdjustBar is a compact widget for visualisation and modification of the value of an GtkAdjustment. It can contain a label with an overlaid bar that can be clicked, dragged or modified by the scroll-wheel by the user. Since the widget does not take keyboard focus and does not display a numerical value, it should be usually paired with a GtkSpinButton sharing the same adjustment. This spin button would also be the typical mnemonic widget for the adjustment bar.

GwyAdjustBar supports several different types of mapping between screen positions and values of the underlying adjustment. Nevertheless, the default mapping (signed square root, `GWY_SCALE_MAPPING_SQRT`) should fit most situations.

## Functions

### gwy_adjust_bar_new()

    GtkWidget *
    gwy_adjust_bar_new (GtkAdjustment *adjustment,
                        const gchar *label);

Creates a new adjustment bar.

The label text, if any, is set with mnemonic enabled. However, you still need to assign it to a widget (presumably a GtkSpinButton) using `gtk_label_set_mnemonic_widget()`.

#### Parameters

adjustment | The adjustment the adjust bar should use, or `NULL`. |
label | Text of the adjustment bar label, or `NULL`. |

#### Returns

A new adjustment bar.

### gwy_adjust_bar_set_adjustment()

    void
    gwy_adjust_bar_set_adjustment (GwyAdjustBar *adjbar,
                                   GtkAdjustment *adjustment);

Sets the adjustment that an adjustment bar visualises.

#### Parameters

adjbar | An adjustment bar. |
adjustment | Adjustment to use for the value. |

### gwy_adjust_bar_get_adjustment()

    GtkAdjustment *
    gwy_adjust_bar_get_adjustment (GwyAdjustBar *adjbar);

Obtains the adjustment that an adjustment bar visualises.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

The adjustment used by `adjbar` . If no adjustment was set and the default one is used, function returns `NULL`.

### gwy_adjust_bar_set_snap_to_ticks()

    void
    gwy_adjust_bar_set_snap_to_ticks (GwyAdjustBar *adjbar,
                                      gboolean setting);

Sets the snapping behaviour of an adjustment bar.

Note the ‘multiples of step size’ condition in fact applies to the difference from the minimum value. The maximum adjustment value is always permissible, even if it does not satisfy this condition. Values modified by the user (i.e. emission of signal "change-value") are snapped, however, values set explicitly `gtk_adjustment_set_value()` are kept intact.

Setting this option to `TRUE` immediately causes an adjustment value change if it does not satisfy the condition.

It is usually a poor idea to enable snapping for non-linear mappings.

#### Parameters

adjbar | An adjustment bar. |
setting | `TRUE` to restrict values to multiples of step size, `FALSE` to permit any values. |

### gwy_adjust_bar_get_snap_to_ticks()

    gboolean
    gwy_adjust_bar_get_snap_to_ticks (GwyAdjustBar *adjbar);

Sets the snapping behaviour of an adjustment bar.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

`TRUE` if values are restricted to multiples of step size.

### gwy_adjust_bar_set_mapping()

    void
    gwy_adjust_bar_set_mapping (GwyAdjustBar *adjbar,
                                GwyScaleMappingType mapping);

Sets the mapping function type for an adjustment bar.

#### Parameters

adjbar | An adjustment bar. |
mapping | Mapping function type between values and screen positions in the adjustment bar. |

### gwy_adjust_bar_get_mapping()

    GwyScaleMappingType
    gwy_adjust_bar_get_mapping (GwyAdjustBar *adjbar);

Gets the mapping function type of an adjustment bar.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

The type of mapping function between values and screen positions.

### gwy_adjust_bar_set_has_check_button()

    void
    gwy_adjust_bar_set_has_check_button (GwyAdjustBar *adjbar,
                                         gboolean setting);

Sets whether an adjustment bar has a check button.

#### Parameters

adjbar | An adjustment bar. |
setting | `TRUE` to enable a check button; `FALSE` to disable it. |

### gwy_adjust_bar_get_has_check_button()

    gboolean
    gwy_adjust_bar_get_has_check_button (GwyAdjustBar *adjbar);

Reports whether an adjustment bar has a check button.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

`TRUE` if the adjustment bar has a check button.

### gwy_adjust_bar_set_bar_sensitive()

    void
    gwy_adjust_bar_set_bar_sensitive (GwyAdjustBar *adjbar,
                                      gboolean sensitive);

Sets the sensitivity of an adjustment bar.

The bar's sensitivity can be controlled separately. This is useful when `adjbar` has a check button because otherwise the bar is the entire widget and the function is not different from `gtk_widget_set_sensitive()`. However, if you want to enable and disable the adjustment bar via the check button, use this function instead of `gtk_widget_set_sensitive()` which would make insensitive also the check button.

#### Parameters

adjbar | An adjustment bar. |
sensitive | `TRUE` to make the widget's bar sensitive. |

### gwy_adjust_bar_get_bar_sensitive()

    gboolean
    gwy_adjust_bar_get_bar_sensitive (GwyAdjustBar *adjbar);

Reports whether an adjustment bar is sensitive.

See `gwy_adjust_bar_set_bar_sensitive()` for discussion.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

`TRUE` if the widget's bar is sensitive.

### gwy_adjust_bar_get_label()

    GtkWidget *
    gwy_adjust_bar_get_label (GwyAdjustBar *adjbar);

Gets the label widget inside an adjustment bar.

Use `gtk_label_set_mnemonic_widget()` to set the mnemonic widget for the label or change the label text.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

The label widget.

### gwy_adjust_bar_get_check_button()

    GtkWidget *
    gwy_adjust_bar_get_check_button (GwyAdjustBar *adjbar);

Gets the check button of an adjustment bar.

Connect to the "toggled" signal of the check button. Modifying it is not recommended.

#### Parameters

adjbar | An adjustment bar. |

#### Returns

The check button widget, or `NULL` if there is none.

## Types and Values

### enum GwyScaleMappingType

Type of adjustment bar mapping functions.

#### Members

GWY_SCALE_MAPPING_LINEAR | Linear mapping between values and screen positions. This recommended for signed additive quantities of a limited range. |
GWY_SCALE_MAPPING_SQRT | Screen positions correspond to ‘signed square roots’ of the value. This is the recommended general-purpose default mapping type as it works with both signed and usigned quantities and offers good sensitivity for both large and small values. |
GWY_SCALE_MAPPING_LOG | Screen positions correspond to logarithms of values. The adjustment range must contain only positive values. For quantities of extreme ranges this mapping may be preferred to `GWY_SCALE_MAPPING_SQRT`. |
GWY_SCALE_MAPPING_LOG1P | Screen positions correspond to logarithms of values with 1 added fist. The adjustment range must contain only non-negative values. This mapping may be preferred for integer quantities with extreme ranges which also include zero. (Since 2.62) |

### struct GwyAdjustBar

    struct GwyAdjustBar;

Adjustment bar widget visualising an adjustment.

The GwyAdjustBar struct contains private data only and should be accessed using the functions below.

### struct GwyAdjustBarClass

    struct GwyAdjustBarClass {
        GtkBinClass parent_class;

        void (*change_value)(GwyAdjustBar *adjbar, gdouble value);
    };

Class of adjustment bars visualising adjustments.

## Property Details

### The `“adjustment”` property

      “adjustment”               GtkAdjustment *

Adjustment representing the value.

Owner: GwyAdjustBar

Flags: Read / Write

### The `“has-check-button”` property

      “has-check-button”         gboolean

Whether the adjust bar has a check button.

Owner: GwyAdjustBar

Flags: Read / Write

Default value: FALSE

### The `“mapping”` property

      “mapping”                  GwyScaleMappingType

Mapping function between values and screen positions.

Owner: GwyAdjustBar

Flags: Read / Write

Default value: GWY_SCALE_MAPPING_SQRT

### The `“snap-to-ticks”` property

      “snap-to-ticks”            gboolean

Whether only values that are multiples of step size are allowed.

Owner: GwyAdjustBar

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“change-value”` signal

    void
    user_function (GwyAdjustBar *gwyadjustbar,
                   double        arg1,
                   gpointer      user_data)

The ::change-value signal is emitted when the user interactively changes the value.

It is an action signal.

#### Parameters

gwyadjustbar | The GwyAdjustBar which received the signal. |
arg1 | New value for `gwyadjustbar` . |
user_data | user data set when the signal handler was connected. |

Flags: Action