Value intervals

## Value intervals Value intervals — An object holding an interval of two values |

## Synopsis

                        ClutterInterval;
                        ClutterIntervalClass;
    ClutterInterval *   clutter_interval_new                (GType gtype,
                                                             ...);
    ClutterInterval *   clutter_interval_new_with_values    (GType gtype,
                                                             const GValue *initial,
                                                             const GValue *final);
    ClutterInterval *   clutter_interval_clone              (ClutterInterval *interval);
    GType               clutter_interval_get_value_type     (ClutterInterval *interval);
    void                clutter_interval_set_initial_value  (ClutterInterval *interval,
                                                             const GValue *value);
    void                clutter_interval_get_initial_value  (ClutterInterval *interval,
                                                             GValue *value);
    GValue *            clutter_interval_peek_initial_value (ClutterInterval *interval);
    void                clutter_interval_set_final_value    (ClutterInterval *interval,
                                                             const GValue *value);
    void                clutter_interval_get_final_value    (ClutterInterval *interval,
                                                             GValue *value);
    GValue *            clutter_interval_peek_final_value   (ClutterInterval *interval);
    void                clutter_interval_set_interval       (ClutterInterval *interval,
                                                             ...);
    void                clutter_interval_get_interval       (ClutterInterval *interval,
                                                             ...);

    gboolean            clutter_interval_compute_value      (ClutterInterval *interval,
                                                             gdouble factor,
                                                             GValue *value);
    gboolean            clutter_interval_validate           (ClutterInterval *interval,
                                                             GParamSpec *pspec);

    gboolean            (*ClutterProgressFunc)              (const GValue *a,
                                                             const GValue *b,
                                                             gdouble progress,
                                                             GValue *retval);
    void                clutter_interval_register_progress_func
                                                            (GType value_type,
                                                             ClutterProgressFunc func);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterInterval

## Properties

      "value-type"               GType*                : Read / Write / Construct Only

## Description

ClutterInterval is a simple object that can hold two values defining an interval. ClutterInterval can hold any value that can be enclosed inside a GValue.

Once a ClutterInterval for a specific GType has been instantiated the "value-type" property cannot be changed anymore.

ClutterInterval starts with a floating reference; this means that any object taking a reference on a ClutterInterval instance should also take ownership of the interval by using `g_object_ref_sink()`.

ClutterInterval is used by ClutterAnimation to define the interval of values that an implicit animation should tween over.

ClutterInterval can be subclassed to override the validation and value computation.

ClutterInterval is available since Clutter 1.0

## Details

### ClutterInterval

    typedef struct _ClutterInterval ClutterInterval;

The ClutterInterval structure contains only private data and should be accessed using the provided functions.

Since 1.0

### ClutterIntervalClass

    typedef struct {
      gboolean (* validate)      (ClutterInterval *interval,
                                  GParamSpec      *pspec);
      gboolean (* compute_value) (ClutterInterval *interval,
                                  gdouble          factor,
                                  GValue          *value);
    } ClutterIntervalClass;

The ClutterIntervalClass contains only private data.

`validate` () | virtual function for validating an interval using a GParamSpec
`compute_value` () | virtual function for computing the value inside an interval using an adimensional factor between 0 and 1

Since 1.0

### clutter_interval_new ()

    ClutterInterval *   clutter_interval_new                (GType gtype,
                                                             ...);

Creates a new ClutterInterval holding values of type `gtype`.

This function avoids using a GValue for the initial and final values of the interval:

      interval = clutter_interval_new (G_TYPE_FLOAT, 0.0, 1.0);
      interval = clutter_interval_new (G_TYPE_BOOLEAN, FALSE, TRUE);
      interval = clutter_interval_new (G_TYPE_INT, 0, 360);

`gtype` : | the type of the values in the interval
`...` : | the initial value and the final value of the interval
Returns : | the newly created ClutterInterval

Since 1.0

### clutter_interval_new_with_values ()

    ClutterInterval *   clutter_interval_new_with_values    (GType gtype,
                                                             const GValue *initial,
                                                             const GValue *final);

Creates a new ClutterInterval of type `gtype`, between `initial` and `final`.

This function is useful for language bindings.

`gtype` : | the type of the values in the interval
`initial` : | a GValue holding the initial value of the interval
`final` : | a GValue holding the final value of the interval
Returns : | the newly created ClutterInterval

Since 1.0

### clutter_interval_clone ()

    ClutterInterval *   clutter_interval_clone              (ClutterInterval *interval);

Creates a copy of `interval`.

`interval` : | a ClutterInterval
Returns : | the newly created ClutterInterval

Since 1.0

### clutter_interval_get_value_type ()

    GType               clutter_interval_get_value_type     (ClutterInterval *interval);

Retrieves the GType of the values inside `interval`.

`interval` : | a ClutterInterval
Returns : | the type of the value, or G_TYPE_INVALID

Since 1.0

### clutter_interval_set_initial_value ()

    void                clutter_interval_set_initial_value  (ClutterInterval *interval,
                                                             const GValue *value);

Sets the initial value of `interval` to `value`. The value is copied inside the ClutterInterval.

`interval` : | a ClutterInterval
`value` : | a GValue

Since 1.0

### clutter_interval_get_initial_value ()

    void                clutter_interval_get_initial_value  (ClutterInterval *interval,
                                                             GValue *value);

Retrieves the initial value of `interval` and copies it into `value`.

The passed GValue must be initialized to the value held by the ClutterInterval.

`interval` : | a ClutterInterval
`value` : | a GValue

Since 1.0

### clutter_interval_peek_initial_value ()

    GValue *            clutter_interval_peek_initial_value (ClutterInterval *interval);

Gets the pointer to the initial value of `interval`

`interval` : | a ClutterInterval
Returns : | transfer none. transfer none.

Since 1.0

### clutter_interval_set_final_value ()

    void                clutter_interval_set_final_value    (ClutterInterval *interval,
                                                             const GValue *value);

Sets the final value of `interval` to `value`. The value is copied inside the ClutterInterval.

`interval` : | a ClutterInterval
`value` : | a GValue

Since 1.0

### clutter_interval_get_final_value ()

    void                clutter_interval_get_final_value    (ClutterInterval *interval,
                                                             GValue *value);

Retrieves the final value of `interval` and copies it into `value`.

The passed GValue must be initialized to the value held by the ClutterInterval.

`interval` : | a ClutterInterval
`value` : | a GValue

Since 1.0

### clutter_interval_peek_final_value ()

    GValue *            clutter_interval_peek_final_value   (ClutterInterval *interval);

Gets the pointer to the final value of `interval`

`interval` : | a ClutterInterval
Returns : | transfer none. transfer none.

Since 1.0

### clutter_interval_set_interval ()

    void                clutter_interval_set_interval       (ClutterInterval *interval,
                                                             ...);

Variable arguments wrapper for `clutter_interval_set_initial_value()` and `clutter_interval_set_final_value()` that avoids using the GValue arguments:

      clutter_interval_set_interval (interval, 0, 50);
      clutter_interval_set_interval (interval, 1.0, 0.0);
      clutter_interval_set_interval (interval, FALSE, TRUE);

This function is meant for the convenience of the C API; bindings should reimplement this function using the GValue-based API.

`interval` : | a ClutterInterval
`...` : | the initial and final values of the interval

Since 1.0

### clutter_interval_get_interval ()

    void                clutter_interval_get_interval       (ClutterInterval *interval,
                                                             ...);

Variable arguments wrapper for `clutter_interval_get_initial_value()` and `clutter_interval_get_final_value()` that avoids using the GValue arguments:

      gint a = 0, b = 0;
      clutter_interval_get_interval (interval, &a, &b);

This function is meant for the convenience of the C API; bindings should reimplement this function using the GValue-based API.

`interval` : | a ClutterInterval
`...` : | return locations for the initial and final values of the interval

Since 1.0

### clutter_interval_compute_value ()

    gboolean            clutter_interval_compute_value      (ClutterInterval *interval,
                                                             gdouble factor,
                                                             GValue *value);

Computes the value between the `interval` boundaries given the progress `factor` and puts it into `value`.

`interval` : | a ClutterInterval
`factor` : | the progress factor, between 0 and 1
`value` : | return location for an initialized GValue
Returns : | `TRUE` if the operation was successful

Since 1.0

### clutter_interval_validate ()

    gboolean            clutter_interval_validate           (ClutterInterval *interval,
                                                             GParamSpec *pspec);

Validates the initial and final values of `interval` against a GParamSpec.

`interval` : | a ClutterInterval
`pspec` : | a GParamSpec
Returns : | `TRUE` if the ClutterInterval is valid, `FALSE` otherwise

Since 1.0

### ClutterProgressFunc ()

    gboolean            (*ClutterProgressFunc)              (const GValue *a,
                                                             const GValue *b,
                                                             gdouble progress,
                                                             GValue *retval);

Prototype of the progress function used to compute the value between the two ends `a` and `b` of an interval depending on the value of `progress`.

The GValue in `retval` is already initialized with the same type as `a` and `b`.

This function will be called by ClutterInterval if the type of the values of the interval was registered using `clutter_interval_register_progress_func()`.

`a` : | the initial value of an interval
`b` : | the final value of an interval
`progress` : | the progress factor, between 0 and 1
`retval` : | the value used to store the progress
Returns : | `TRUE` if the function successfully computed the value and stored it inside `retval`

Since 1.0

### clutter_interval_register_progress_func ()

    void                clutter_interval_register_progress_func
                                                            (GType value_type,
                                                             ClutterProgressFunc func);

Sets the progress function for a given `value_type`, like:

      clutter_interval_register_progress_func (MY_TYPE_FOO,
                                               my_foo_progress);

Whenever a ClutterInterval instance using the default "compute_value" implementation is set as an interval between two GValue of type `value_type`, it will call `func` to establish the value depending on the given progress, for instance:

      static gboolean
      my_int_progress (const GValue *a,
                       const GValue *b,
                       gdouble       progress,
                       GValue       *retval)
      {
        gint ia = g_value_get_int (a);
        gint ib = g_value_get_int (b);
        gint res = factor * (ib - ia) + ia;

        g_value_set_int (retval, res);

        return TRUE;
      }

      clutter_interval_register_progress_func (G_TYPE_INT, my_int_progress);

To unset a previously set progress function of a GType, pass `NULL` for `func`.

`value_type` : | a GType
`func` : | a ClutterProgressFunc, or `NULL` to unset a previously set progress function

Since 1.0

## Property Details

### The `"value-type"` property

      "value-type"               GType*                : Read / Write / Construct Only

The type of the values in the interval.

Since 1.0