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

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;

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

Generated by GTK-Doc V1.11