GtkAdjustment

GtkAdjustment — A representation of an adjustable bounded value

Properties

double lower Read / Write
double page-increment Read / Write
double page-size Read / Write
double step-increment Read / Write
double upper Read / Write
double value Read / Write

Signals

void changed No Recursion
void value-changed No Recursion

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkAdjustment

Includes

#include <gtk/gtk.h>

Description

The GtkAdjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several GTK+ widgets, including GtkSpinButton, GtkViewport, and GtkRange (which is a base class for GtkScrollbar and GtkScale).

The GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the GtkAdjustment to control the value.

Functions

gtk_adjustment_new ()

GtkAdjustment *
gtk_adjustment_new (gdouble value,
                    gdouble lower,
                    gdouble upper,
                    gdouble step_increment,
                    gdouble page_increment,
                    gdouble page_size);

Creates a new GtkAdjustment.

Parameters

value

the initial value

lower

the minimum value

upper

the maximum value

step_increment

the step increment

page_increment

the page increment

page_size

the page size

Returns

a new GtkAdjustment

gtk_adjustment_get_value ()

gdouble
gtk_adjustment_get_value (GtkAdjustment *adjustment);

Gets the current value of the adjustment. See gtk_adjustment_set_value().

Parameters

adjustment

a GtkAdjustment

Returns

The current value of the adjustment

gtk_adjustment_set_value ()

void
gtk_adjustment_set_value (GtkAdjustment *adjustment,
                          gdouble value);

Sets the GtkAdjustment value. The value is clamped to lie between “lower” and “upper”.

Note that for adjustments which are used in a GtkScrollbar, the effective range of allowed values goes from “lower” to “upper” - “page-size”.

Parameters

adjustment

a GtkAdjustment

value

the new value

gtk_adjustment_clamp_page ()

void
gtk_adjustment_clamp_page (GtkAdjustment *adjustment,
                           gdouble lower,
                           gdouble upper);

Updates the “value” property to ensure that the range between lower and upper is in the current page (i.e. between “value” and “value” + “page-size”). If the range is larger than the page size, then only the start of it will be in the current page.

A “value-changed” signal will be emitted if the value is changed.

Parameters

adjustment

a GtkAdjustment

lower

the lower value

upper

the upper value

gtk_adjustment_changed ()

void
gtk_adjustment_changed (GtkAdjustment *adjustment);

gtk_adjustment_changed has been deprecated since version 3.18 and should not be used in newly-written code.

GTK+ emits “changed” itself whenever any of the properties (other than value) change

Emits a “changed” signal from the GtkAdjustment. This is typically called by the owner of the GtkAdjustment after it has changed any of the GtkAdjustment properties other than the value.

Parameters

adjustment

a GtkAdjustment

gtk_adjustment_value_changed ()

void
gtk_adjustment_value_changed (GtkAdjustment *adjustment);

gtk_adjustment_value_changed has been deprecated since version 3.18 and should not be used in newly-written code.

GTK+ emits “value-changed” itself whenever the value changes

Emits a “value-changed” signal from the GtkAdjustment. This is typically called by the owner of the GtkAdjustment after it has changed the “value” property.

Parameters

adjustment

a GtkAdjustment

gtk_adjustment_configure ()

void
gtk_adjustment_configure (GtkAdjustment *adjustment,
                          gdouble value,
                          gdouble lower,
                          gdouble upper,
                          gdouble step_increment,
                          gdouble page_increment,
                          gdouble page_size);

Sets all properties of the adjustment at once.

Use this function to avoid multiple emissions of the “changed” signal. See gtk_adjustment_set_lower() for an alternative way of compressing multiple emissions of “changed” into one.

Parameters

adjustment

a GtkAdjustment

value

the new value

lower

the new minimum value

upper

the new maximum value

step_increment

the new step increment

page_increment

the new page increment

page_size

the new page size

Since: 2.14

gtk_adjustment_get_lower ()

gdouble
gtk_adjustment_get_lower (GtkAdjustment *adjustment);

Retrieves the minimum value of the adjustment.

Parameters

adjustment

a GtkAdjustment

Returns

The current minimum value of the adjustment

Since: 2.14

gtk_adjustment_get_page_increment ()

gdouble
gtk_adjustment_get_page_increment (GtkAdjustment *adjustment);

Retrieves the page increment of the adjustment.

Parameters

adjustment

a GtkAdjustment

Returns

The current page increment of the adjustment

Since: 2.14

gtk_adjustment_get_page_size ()

gdouble
gtk_adjustment_get_page_size (GtkAdjustment *adjustment);

Retrieves the page size of the adjustment.

Parameters

adjustment

a GtkAdjustment

Returns

The current page size of the adjustment

Since: 2.14

gtk_adjustment_get_step_increment ()

gdouble
gtk_adjustment_get_step_increment (GtkAdjustment *adjustment);

Retrieves the step increment of the adjustment.

Parameters

adjustment

a GtkAdjustment

Returns

The current step increment of the adjustment.

Since: 2.14

gtk_adjustment_get_minimum_increment ()

gdouble
gtk_adjustment_get_minimum_increment (GtkAdjustment *adjustment);

Gets the smaller of step increment and page increment.

Parameters

adjustment

a GtkAdjustment

Returns

the minimum increment of adjustment

Since: 3.2

gtk_adjustment_get_upper ()

gdouble
gtk_adjustment_get_upper (GtkAdjustment *adjustment);

Retrieves the maximum value of the adjustment.

Parameters

adjustment

a GtkAdjustment

Returns

The current maximum value of the adjustment

Since: 2.14

gtk_adjustment_set_lower ()

void
gtk_adjustment_set_lower (GtkAdjustment *adjustment,
                          gdouble lower);

Sets the minimum value of the adjustment.

When setting multiple adjustment properties via their individual setters, multiple “changed” signals will be emitted. However, since the emission of the “changed” signal is tied to the emission of the “notify” signals of the changed properties, it’s possible to compress the “changed” signals into one by calling g_object_freeze_notify() and g_object_thaw_notify() around the calls to the individual setters.

Alternatively, using a single g_object_set() for all the properties to change, or using gtk_adjustment_configure() has the same effect of compressing “changed” emissions.

Parameters

adjustment

a GtkAdjustment

lower

the new minimum value

Since: 2.14

gtk_adjustment_set_page_increment ()

void
gtk_adjustment_set_page_increment (GtkAdjustment *adjustment,
                                   gdouble page_increment);

Sets the page increment of the adjustment.

See gtk_adjustment_set_lower() about how to compress multiple emissions of the “changed” signal when setting multiple adjustment properties.

Parameters

adjustment

a GtkAdjustment

page_increment

the new page increment

Since: 2.14

gtk_adjustment_set_page_size ()

void
gtk_adjustment_set_page_size (GtkAdjustment *adjustment,
                              gdouble page_size);

Sets the page size of the adjustment.

See gtk_adjustment_set_lower() about how to compress multiple emissions of the GtkAdjustment::changed signal when setting multiple adjustment properties.

Parameters

adjustment

a GtkAdjustment

page_size

the new page size

Since: 2.14

gtk_adjustment_set_step_increment ()

void
gtk_adjustment_set_step_increment (GtkAdjustment *adjustment,
                                   gdouble step_increment);

Sets the step increment of the adjustment.

See gtk_adjustment_set_lower() about how to compress multiple emissions of the “changed” signal when setting multiple adjustment properties.

Parameters

adjustment

a GtkAdjustment

step_increment

the new step increment

Since: 2.14

gtk_adjustment_set_upper ()

void
gtk_adjustment_set_upper (GtkAdjustment *adjustment,
                          gdouble upper);

Sets the maximum value of the adjustment.

Note that values will be restricted by upper - page-size if the page-size property is nonzero.

See gtk_adjustment_set_lower() about how to compress multiple emissions of the “changed” signal when setting multiple adjustment properties.

Parameters

adjustment

a GtkAdjustment

upper

the new maximum value

Since: 2.14

Types and Values

GtkAdjustment

typedef struct _GtkAdjustment GtkAdjustment;

The GtkAdjustment contains only private fields and should not be directly accessed.

Property Details

The “lower” property

  “lower”                    double

The minimum value of the adjustment.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

The “page-increment” property

  “page-increment”           double

The page increment of the adjustment.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

The “page-size” property

  “page-size”                double

The page size of the adjustment. Note that the page-size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value, e.g. in a GtkSpinButton.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

The “step-increment” property

  “step-increment”           double

The step increment of the adjustment.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

The “upper” property

  “upper”                    double

The maximum value of the adjustment. Note that values will be restricted by upper - page-size if the page-size property is nonzero.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

The “value” property

  “value”                    double

The value of the adjustment.

Owner: GtkAdjustment

Flags: Read / Write

Default value: 0

Since: 2.4

Signal Details

The “changed” signal

void
user_function (GtkAdjustment *adjustment,
               gpointer       user_data)

Emitted when one or more of the GtkAdjustment properties have been changed, other than the “value” property.

Parameters

adjustment

the object which received the signal

user_data

user data set when the signal handler was connected.

Flags: No Recursion

The “value-changed” signal

void
user_function (GtkAdjustment *adjustment,
               gpointer       user_data)

Emitted when the “value” property has been changed.

Parameters

adjustment

the object which received the signal

user_data

user data set when the signal handler was connected.

Flags: No Recursion

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