Value intervals

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

## Synopsis

                        ClutterInterval;
    struct              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,
                                                             ...);
    void                clutter_interval_set_initial        (ClutterInterval *interval,
                                                             ...);
    void                clutter_interval_set_final          (ClutterInterval *interval,
                                                             ...);

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

    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

### struct ClutterIntervalClass

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

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:

    1
    2
    3
    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. [transfer full]

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.

Rename to: clutter_interval_set_initial

`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. [out caller-allocates]

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 : | the initial value of the interval. The value is owned by the ClutterInterval and it should not be modified or freed. [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.

Rename to: clutter_interval_set_final

`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. [out caller-allocates]

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 : | the final value of the interval. The value is owned by the ClutterInterval and it should not be modified or freed. [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:

    1
    2
    3
    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:

    1
    2
    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_set_initial ()

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

Variadic arguments version of `clutter_interval_set_initial_value()`.

This function is meant as a convenience for the C API.

Language bindings should use `clutter_interval_set_initial_value()` instead.

`interval` : | a ClutterInterval
`...` : | the initial value of the interval.

Since 1.10

### clutter_interval_set_final ()

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

Variadic arguments version of `clutter_interval_set_final_value()`.

This function is meant as a convenience for the C API.

Language bindings should use `clutter_interval_set_final_value()` instead.

`interval` : | a ClutterInterval
`...` : | the final value of the interval

Since 1.10

### 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

### 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 copies it into `value`.

`interval` : | a ClutterInterval
`factor` : | the progress factor, between 0 and 1
`value` : | return location for an initialized GValue. [out caller-allocates]
Returns : | `TRUE` if the operation was successful

Since 1.0

### clutter_interval_compute ()

    const GValue *      clutter_interval_compute            (ClutterInterval *interval,
                                                             gdouble factor);

Computes the value between the `interval` boundaries given the progress `factor`

Unlike `clutter_interval_compute_value()`, this function will return a const pointer to the computed value

You should use this function if you immediately pass the computed value to another function that makes a copy of it, like `g_object_set_property()`

`interval` : | a ClutterInterval
`factor` : | the progress factor, between 0 and 1
Returns : | a pointer to the computed value, or `NULL` if the computation was not successfull. [transfer none]

Since 1.4

### 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:

    1
    2
    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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    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.

Allowed values: void

Since 1.0