Value intervals: Clutter Reference Manual

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

## Functions

ClutterInterval * | clutter_interval_new ()
ClutterInterval * | clutter_interval_new_with_values ()
ClutterInterval * | clutter_interval_clone ()
GType | clutter_interval_get_value_type ()
void | clutter_interval_set_initial_value ()
void | clutter_interval_get_initial_value ()
GValue * | clutter_interval_peek_initial_value ()
void | clutter_interval_set_final_value ()
void | clutter_interval_get_final_value ()
GValue * | clutter_interval_peek_final_value ()
void | clutter_interval_set_interval ()
void | clutter_interval_get_interval ()
void | clutter_interval_set_initial ()
void | clutter_interval_set_final ()
gboolean | clutter_interval_is_valid ()
gboolean | clutter_interval_validate ()
gboolean | clutter_interval_compute_value ()
const GValue * | clutter_interval_compute ()
gboolean | (*ClutterProgressFunc) ()
void | clutter_interval_register_progress_func ()

## Properties

GValue * | final | Read / Write
GValue * | initial | Read / Write
GType * | value-type | Read / Write / Construct Only

## Types and Values

| ClutterInterval
struct | ClutterIntervalClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterInterval

## Implemented Interfaces

ClutterInterval implements ClutterScriptable.

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

## Functions

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

#### Parameters

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.

#### Parameters

gtype | the type of the values in the interval |
initial | a GValue holding the initial value of the interval. | [allow-none]
final | a GValue holding the final value of the interval. | [allow-none]

#### Returns

the newly created ClutterInterval

Since: 1.0

### clutter_interval_clone ()

    ClutterInterval *
    clutter_interval_clone (ClutterInterval *interval);

Creates a copy of `interval` .

#### Parameters

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` .

#### Parameters

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]

#### Parameters

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.

#### Parameters

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`

#### Parameters

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]

#### Parameters

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.

#### Parameters

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`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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

Since: 1.10

### clutter_interval_is_valid ()

    gboolean
    clutter_interval_is_valid (ClutterInterval *interval);

Checks if the `interval` has a valid initial and final values.

#### Parameters

interval | a ClutterInterval |

#### Returns

`TRUE` if the ClutterInterval has an initial and final values, and `FALSE` otherwise

Since: 1.12

### clutter_interval_validate ()

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

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

#### Parameters

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` .

#### Parameters

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

#### Parameters

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

#### Parameters

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` .

[skip]

#### Parameters

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

Since: 1.0

## Types and Values

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

#### Members

`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

## Property Details

### The `“final”` property

      “final”                    GValue *

The final value of the interval.

Owner: ClutterInterval

Flags: Read / Write

Since: 1.12

### The `“initial”` property

      “initial”                  GValue *

The initial value of the interval.

Owner: ClutterInterval

Flags: Read / Write

Since: 1.12

### The `“value-type”` property

      “value-type”               GType *

The type of the values in the interval.

Owner: ClutterInterval

Flags: Read / Write / Construct Only

Allowed values: void

Since: 1.0