Value intervals

Value intervals — An object holding an interval of two values

Synopsis

struct              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,
                                                         ...);

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

struct ClutterInterval

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

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.

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