W3cubDocs

/GTK 4.0

GtkScale

GtkScale — A slider widget for selecting a value from a range

Properties

int digits Read / Write
gboolean draw-value Read / Write
gboolean has-origin Read / Write
GtkPositionType value-pos Read / Write

Types and Values

struct GtkScale

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkRange
                ╰── GtkScale

Implemented Interfaces

GtkScale implements GtkAccessible, GtkBuildable, GtkConstraintTarget and GtkOrientable.

Includes

#include <gtk/gtk.h>

Description

A GtkScale is a slider control used to select a numeric value. To use it, you’ll probably want to investigate the methods on its base class, GtkRange, in addition to the methods for GtkScale itself. To set the value of a scale, you would normally use gtk_range_set_value(). To detect changes to the value, you would normally use the “value-changed” signal.

Note that using the same upper and lower bounds for the GtkScale (through the GtkRange methods) will hide the slider itself. This is useful for applications that want to show an undeterminate value on the scale, without changing the layout of the application (such as movie or music players).

GtkScale as GtkBuildable

GtkScale supports a custom <marks> element, which can contain multiple <mark> elements. The “value” and “position” attributes have the same meaning as gtk_scale_add_mark() parameters of the same name. If the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual ”translatable” and “context” attributes.

CSS nodes

scale[.fine-tune][.marks-before][.marks-after]
├── [value][.top][.right][.bottom][.left]
├── marks.top
│   ├── mark
│   ┊    ├── [label]
│   ┊    ╰── indicator
┊   ┊
│   ╰── mark
├── marks.bottom
│   ├── mark
│   ┊    ├── indicator
│   ┊    ╰── [label]
┊   ┊
│   ╰── mark
╰── trough
    ├── [fill]
    ├── [highlight]
    ╰── slider

GtkScale has a main CSS node with name scale and a subnode for its contents, with subnodes named trough and slider.

The main node gets the style class .fine-tune added when the scale is in 'fine-tuning' mode.

If the scale has an origin (see gtk_scale_set_has_origin()), there is a subnode with name highlight below the trough node that is used for rendering the highlighted part of the trough.

If the scale is showing a fill level (see gtk_range_set_show_fill_level()), there is a subnode with name fill below the trough node that is used for rendering the filled in part of the trough.

If marks are present, there is a marks subnode before or after the trough node, below which each mark gets a node with name mark. The marks nodes get either the .top or .bottom style class.

The mark node has a subnode named indicator. If the mark has text, it also has a subnode named label. When the mark is either above or left of the scale, the label subnode is the first when present. Otherwise, the indicator subnode is the first.

The main CSS node gets the 'marks-before' and/or 'marks-after' style classes added depending on what marks are present.

If the scale is displaying the value (see “draw-value”), there is subnode with name value. This node will get the .top or .bottom style classes similar to the marks node.

Accessibility

GtkScale uses the GTK_ACCESSIBLE_ROLE_SLIDER role.

Functions

GtkScaleFormatValueFunc ()

char *
(*GtkScaleFormatValueFunc) (GtkScale *scale,
                            double value,
                            gpointer user_data);

Parameters

scale

The GtkScale

value

The numeric value to format

user_data

user data.

[closure]

Returns

A newly allocated string describing a textual representation of the given numerical value.

[not nullable]

gtk_scale_new ()

GtkWidget *
gtk_scale_new (GtkOrientation orientation,
               GtkAdjustment *adjustment);

Creates a new GtkScale.

Parameters

orientation

the scale’s orientation.

adjustment

the GtkAdjustment which sets the range of the scale, or NULL to create a new adjustment.

[nullable]

Returns

a new GtkScale

gtk_scale_new_with_range ()

GtkWidget *
gtk_scale_new_with_range (GtkOrientation orientation,
                          double min,
                          double max,
                          double step);

Creates a new scale widget with the given orientation that lets the user input a number between min and max (including min and max ) with the increment step . step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value.

Note that the way in which the precision is derived works best if step is a power of ten. If the resulting precision is not suitable for your needs, use gtk_scale_set_digits() to correct it.

Parameters

orientation

the scale’s orientation.

min

minimum value

max

maximum value

step

step increment (tick size) used with keyboard shortcuts

Returns

a new GtkScale

gtk_scale_set_format_value_func ()

void
gtk_scale_set_format_value_func (GtkScale *scale,
                                 GtkScaleFormatValueFunc func,
                                 gpointer user_data,
                                 GDestroyNotify destroy_notify);

func allows you to change how the scale value is displayed. The given function will return an allocated string representing value . That string will then be used to display the scale's value.

If NULL is passed as func , the value will be displayed on its own, rounded according to the value of the “digits” property.

Parameters

scale

a GtkScale

func

function that formats the value.

[nullable]

user_data

user data to pass to func .

[closure]

destroy_notify

destroy function for user_data .

[nullable]

gtk_scale_set_digits ()

void
gtk_scale_set_digits (GtkScale *scale,
                      int digits);

Sets the number of decimal places that are displayed in the value. Also causes the value of the adjustment to be rounded to this number of digits, so the retrieved value matches the displayed one, if “draw-value” is TRUE when the value changes. If you want to enforce rounding the value when “draw-value” is FALSE, you can set “round-digits” instead.

Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into GtkScale. As an alternative, you can use gtk_scale_set_format_value_func() to format the displayed value yourself.

Parameters

scale

a GtkScale

digits

the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc

gtk_scale_set_draw_value ()

void
gtk_scale_set_draw_value (GtkScale *scale,
                          gboolean draw_value);

Specifies whether the current value is displayed as a string next to the slider.

Parameters

scale

a GtkScale

draw_value

TRUE to draw the value

gtk_scale_set_has_origin ()

void
gtk_scale_set_has_origin (GtkScale *scale,
                          gboolean has_origin);

If “has-origin” is set to TRUE (the default), the scale will highlight the part of the trough between the origin (bottom or left side) and the current value.

Parameters

scale

a GtkScale

has_origin

TRUE if the scale has an origin

gtk_scale_set_value_pos ()

void
gtk_scale_set_value_pos (GtkScale *scale,
                         GtkPositionType pos);

Sets the position in which the current value is displayed.

Parameters

scale

a GtkScale

pos

the position in which the current value is displayed

gtk_scale_get_digits ()

int
gtk_scale_get_digits (GtkScale *scale);

Gets the number of decimal places that are displayed in the value.

Parameters

scale

a GtkScale

Returns

the number of decimal places that are displayed

gtk_scale_get_draw_value ()

gboolean
gtk_scale_get_draw_value (GtkScale *scale);

Returns whether the current value is displayed as a string next to the slider.

Parameters

scale

a GtkScale

Returns

whether the current value is displayed as a string

gtk_scale_get_has_origin ()

gboolean
gtk_scale_get_has_origin (GtkScale *scale);

Returns whether the scale has an origin.

Parameters

scale

a GtkScale

Returns

TRUE if the scale has an origin.

gtk_scale_get_value_pos ()

GtkPositionType
gtk_scale_get_value_pos (GtkScale *scale);

Gets the position in which the current value is displayed.

Parameters

scale

a GtkScale

Returns

the position in which the current value is displayed

gtk_scale_get_layout ()

PangoLayout *
gtk_scale_get_layout (GtkScale *scale);

Gets the PangoLayout used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller.

Parameters

scale

A GtkScale

Returns

the PangoLayout for this scale, or NULL if the “draw-value” property is FALSE.

[transfer none][nullable]

gtk_scale_get_layout_offsets ()

void
gtk_scale_get_layout_offsets (GtkScale *scale,
                              int *x,
                              int *y);

Obtains the coordinates where the scale will draw the PangoLayout representing the text in the scale. Remember when using the PangoLayout function you need to convert to and from pixels using PANGO_PIXELS() or PANGO_SCALE.

If the “draw-value” property is FALSE, the return values are undefined.

Parameters

scale

a GtkScale

x

location to store X offset of layout, or NULL.

[out][allow-none]

y

location to store Y offset of layout, or NULL.

[out][allow-none]

gtk_scale_add_mark ()

void
gtk_scale_add_mark (GtkScale *scale,
                    double value,
                    GtkPositionType position,
                    const char *markup);

Adds a mark at value .

A mark is indicated visually by drawing a tick mark next to the scale, and GTK makes it easy for the user to position the scale exactly at the marks value.

If markup is not NULL, text is shown next to the tick mark.

To remove marks from a scale, use gtk_scale_clear_marks().

Parameters

scale

a GtkScale

value

the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment

position

where to draw the mark. For a horizontal scale, GTK_POS_TOP and GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, GTK_POS_LEFT and GTK_POS_TOP are drawn to the left of the scale, anything else to the right.

markup

Text to be shown at the mark, using Pango markup, or NULL.

[allow-none]

gtk_scale_clear_marks ()

void
gtk_scale_clear_marks (GtkScale *scale);

Removes any marks that have been added with gtk_scale_add_mark().

Parameters

scale

a GtkScale

Types and Values

struct GtkScale

struct GtkScale;

Property Details

The “digits” property

  “digits”                   int

The number of decimal places that are displayed in the value.

Owner: GtkScale

Flags: Read / Write

Allowed values: [-1,64]

Default value: 1

The “draw-value” property

  “draw-value”               gboolean

Whether the current value is displayed as a string next to the slider.

Owner: GtkScale

Flags: Read / Write

Default value: FALSE

The “has-origin” property

  “has-origin”               gboolean

Whether the scale has an origin.

Owner: GtkScale

Flags: Read / Write

Default value: TRUE

The “value-pos” property

  “value-pos”                GtkPositionType

The position in which the current value is displayed.

Owner: GtkScale

Flags: Read / Write

Default value: GTK_POS_TOP

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/GtkScale.html