GtkAdjustment

GtkAdjustment — A GtkObject representing an adjustable bounded value

Synopsis


#include <gtk/gtk.h>


                    GtkAdjustment;
GtkObject*          gtk_adjustment_new                  (gdouble value,
                                                         gdouble lower,
                                                         gdouble upper,
                                                         gdouble step_increment,
                                                         gdouble page_increment,
                                                         gdouble page_size);
gdouble             gtk_adjustment_get_value            (GtkAdjustment *adjustment);
void                gtk_adjustment_set_value            (GtkAdjustment *adjustment,
                                                         gdouble value);
void                gtk_adjustment_clamp_page           (GtkAdjustment *adjustment,
                                                         gdouble lower,
                                                         gdouble upper);
void                gtk_adjustment_changed              (GtkAdjustment *adjustment);
void                gtk_adjustment_value_changed        (GtkAdjustment *adjustment);


Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkAdjustment

Properties


  "lower"                    gdouble               : Read / Write
  "page-increment"           gdouble               : Read / Write
  "page-size"                gdouble               : Read / Write
  "step-increment"           gdouble               : Read / Write
  "upper"                    gdouble               : Read / Write
  "value"                    gdouble               : Read / Write

Signals


  "changed"                                        : Run First / No Recursion
  "value-changed"                                  : Run First / No Recursion

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 GtkHScrollbar, GtkVScrollbar, GtkHScale, and GtkVScale).

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

The owner of the GtkAdjustment typically calls the gtk_adjustment_value_changed() and gtk_adjustment_changed() functions after changing the value and its bounds. This results in the emission of the "value_changed" or "changed" signal respectively.

Numerical Precision

The values in a GtkAdjustment are stored as double precision floating point values. More about the different floating point types can be found in the corresponding IEEE Floating Point Standard. In most GtkAdjustment applications, the value member contains a computed number, for instance because the adjustment is updated by a GtkSpinButton or GtkRange widget which assign adjustment values based on computations which use user input with pixel precision. When floats/doubles are computed, they almost never represent the exact number wanted or needed, but only an approximation of the real value, because floating point numbers are approximations of real numbers by design (needed to represent infinite precision numbers in a finite number of memory cells). In the case of a range, spin button or similar widget where the current value is represented by a floating point number (i.e. an inexact approximation of the real value needed), adjustment->upper and adjustment->lower may or may not be represented exactly in adjustment->value, depending on the implementation. That means, even if a spinner or range looks like it represents adjustment->lower or adjustment->upper in the graphical display, the actual adjustment->value may very well be off by a small number (epsilon) that corresponds to ca. half a pixel at the GUI. To compensate for such boundary cases accurately in user code, additional logic may be required, for instance:

Example 1. Epsilon comparison for adjustments

  /* retrieve a computed floating point value */
  double myval = gtk_spin_button_get_value (spinner);
  double myval = gtk_range_get_value (range);
  double myval = gtk_progress_get_value (progress_widget);
  double myval = gtk_adjustment_get_value (adjustment);
  /* adjust for border cases, assuming a screen resolution < 65536 pixels */
  const double epsilon = 0.0000152587890625; /* 1.0 / 2^16 */
  if (fabs (myval - adjustment->lower) < epsilon)
    myval = adjustment->lower;
  if (fabs (myval - (adjustment->upper - adjustment->page_size)) < epsilon)
    myval = adjustment->upper - adjustment->page_size;

While this compensation code makes some more implicit assumptions, like the range (adjustment->upper - adjustment->lower) not being significantly smaller than 1 and only being a few magnitudes larger than the amount of pixels on screen, and while all code that deals with floating point numbers always warrants a detailed precision analysis, it should work out well in practice for the vast majority of cases in Gtk+ and uses of adjustment->value in Gtk+ applications. But as mentioned, there are more issues that need to be taken care of when dealing with floating point numbers. Many of those are addressed by books like Numerical Recipes in C, in particular the chapter 1.3 Error, Accuracy, and Stability is a highly recommended read. And a further recommended reading is the paper What Every Computer Scientist Should Know About Floating-Point Arithmetic.

Details

GtkAdjustment

typedef struct _GtkAdjustment GtkAdjustment;

The GtkAdjustment struct contains the following fields.

gdouble lower; the minimum value.
gdouble upper; the maximum value.
gdouble value; the current value.
gdouble step_increment; the increment to use to make minor changes to the value. In a GtkScrollbar this increment is used when the mouse is clicked on the arrows at the top and bottom of the scrollbar, to scroll by a small amount.
gdouble page_increment; the increment to use to make major changes to the value. In a GtkScrollbar this increment is used when the mouse is clicked in the trough, to scroll by a large amount.
gdouble page_size; the page size. In a GtkScrollbar this is the size of the area which is currently visible.


gtk_adjustment_new ()

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

Creates a new GtkAdjustment.

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().

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 adjustment->lower and adjustment->upper.

Note that for adjustments which are used in a GtkScrollbar, the effective range of allowed values goes from adjustment->lower to adjustment->upper - adjustment->page_size.

adjustment : a GtkAdjustment.
value : the new value.

gtk_adjustment_clamp_page ()

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

Updates the GtkAdjustment value 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 "changed" signal will be emitted if the value is changed.

adjustment : a GtkAdjustment.
lower : the lower value.
upper : the upper value.

gtk_adjustment_changed ()

void                gtk_adjustment_changed              (GtkAdjustment *adjustment);

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 fields other than the value.

adjustment : a GtkAdjustment

gtk_adjustment_value_changed ()

void                gtk_adjustment_value_changed        (GtkAdjustment *adjustment);

Emits a "value_changed" signal from the GtkAdjustment. This is typically called by the owner of the GtkAdjustment after it has changed the GtkAdjustment value field.

adjustment : a GtkAdjustment

Property Details

The "lower" property

  "lower"                    gdouble               : Read / Write

The minimum value of the adjustment.

Default value: 0

Since 2.4


The "page-increment" property

  "page-increment"           gdouble               : Read / Write

The page increment of the adjustment.

Default value: 0

Since 2.4


The "page-size" property

  "page-size"                gdouble               : Read / Write

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.

Default value: 0

Since 2.4


The "step-increment" property

  "step-increment"           gdouble               : Read / Write

The step increment of the adjustment.

Default value: 0

Since 2.4


The "upper" property

  "upper"                    gdouble               : Read / Write

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

Default value: 0

Since 2.4


The "value" property

  "value"                    gdouble               : Read / Write

The value of the adjustment.

Default value: 0

Since 2.4

Signal Details

The "changed" signal

void                user_function                      (GtkAdjustment *adjustment,
                                                        gpointer       user_data)       : Run First / No Recursion

Emitted when one or more of the GtkAdjustment fields have been changed, other than the value field.

adjustment : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "value-changed" signal

void                user_function                      (GtkAdjustment *adjustment,
                                                        gpointer       user_data)       : Run First / No Recursion

Emitted when the GtkAdjustment value field has been changed.

adjustment : the object which received the signal.
user_data : user data set when the signal handler was connected.