brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

state: Documentation and introspection annotation fixes

Browse Source
This commit is contained in:
Emmanuele Bassi 2010-05-20 18:57:27 +01:00
parent c2abb827a3
commit ae3dc9bd5e
1 changed files with 110 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
clutter/clutter-state.c
View File

@ -413,11 +413,17 @@ clutter_state_new_frame (ClutterTimeline *timeline,
/** /**
* clutter_state_change: * clutter_state_change:
* @state_name: a #ClutterState * @state_name: a #ClutterState
* @animate: whether we should animate the transition or not. * @animate: whether we should animate the transition or not
* *
* Change to @state_name and spend duration msecs when doing so. * Change the current state of #ClutterState to @state_name
* *
* Return value: the #ClutterTimeline that drives the #ClutterState instance. * If @animate is %FALSE, the state transition will happen immediately;
* otherwise, the state transition will be animated over the duration
* set using clutter_state_set_duration()
*
* Return value: the #ClutterTimeline that drives the state transition
*
* Since: 1.4
*/ */
ClutterTimeline * ClutterTimeline *
clutter_state_change (ClutterState *this, clutter_state_change (ClutterState *this,
@ -428,7 +434,7 @@ clutter_state_change (ClutterState *this,
State *state; State *state;
g_return_val_if_fail (CLUTTER_IS_STATE (this), NULL); g_return_val_if_fail (CLUTTER_IS_STATE (this), NULL);
g_return_val_if_fail (target_state_name, NULL); g_return_val_if_fail (target_state_name != NULL, NULL);
if (target_state_name == NULL) if (target_state_name == NULL)
target_state_name = "default"; target_state_name = "default";
@ -439,9 +445,7 @@ clutter_state_change (ClutterState *this,
if (target_state_name == priv->target_state_name) if (target_state_name == priv->target_state_name)
{ {
/* Avoiding transitioning if the desired state /* Avoid transitioning if the desired state is already current */
* is already current
*/
return priv->timeline; return priv->timeline;
} }
@ -524,23 +528,29 @@ clutter_state_change (ClutterState *this,
/** /**
* clutter_state_set: * clutter_state_set:
* @state: a #ClutterState instance. * @state: a #ClutterState instance.
* @source_state_name: the name of the source state keys are being added for. * @source_state_name: the name of the source state keys are being added for
* @target_state_name: the name of the target state keys are being added for. * @target_state_name: the name of the target state keys are being added for
* @first_object: a #GObject * @first_object: a #GObject
* @first_property_name: the property to specify a key for * @first_property_name: a property of @first_object to specify a key for
* @first_mode: the id of the alpha function to use * @first_mode: the id of the alpha function to use
* @...: the value first_property_name should have in state_name, followed by * @Varargs: the value @first_property_name should have in @state_name,
* more object,property_name,mode,value,... or NULL to terminate the varargs. * followed by object, property name, mode, value tuples, terminated
* by %NULL
* *
* Adds multiple keys to a named state of a #ClutterState instance, specifying * Adds multiple keys to a named state of a #ClutterState instance, specifying
* the easing mode and value a given property of an object should have at a * the easing mode and value a given property of an object should have at a
* given progress of the animation. The mode specified is the mode used when * given progress of the animation.
* going to this key from the previous key of the property_name, If a given *
* object, state_name, property triple already exist the mode and value will be * The mode specified is the easing mode used when going to from the previous
* replaced with the new values for the existing key. If a the property_name is * key to the specified key.
* prefixed with "delayed::" two additional arguments are expected per key with a *
* value relative to the full state time to pause before transitioning and * If a given object, state_name, property tuple already exist then the mode
* after transitioning within the total transition time. * and value will be replaced with the new specified values.
*
* If a the property_name is prefixed with "delayed::" two additional
* arguments per key are expected: a value relative to the full state time
* to pause before transitioning and a similar value to pause after
* transitioning.
* *
* Since: 1.4 * Since: 1.4
*/ */
@ -654,13 +664,17 @@ clutter_state_set (ClutterState *state,
* @property_name: the property to set a key for * @property_name: the property to set a key for
* @mode: the id of the alpha function to use * @mode: the id of the alpha function to use
* @value: the value for property_name of object in state_name * @value: the value for property_name of object in state_name
* @pre_delay: relative time of the transition to be idle in the beginning of the transition * @pre_delay: relative time of the transition to be idle in the beginning
* @post_delay: relative time of the transition to be idle in the end of the transition * of the transition
* @post_delay: relative time of the transition to be idle in the end of
* the transition
* *
* Sets one specific end key for a state_name, object, property_name * Sets one specific end key for a state_name, object, property_name
* combination. * combination.
* *
* Returns: the #ClutterState instance, allowing chaining of multiple calls. * Return value: the #ClutterState instance, allowing chaining of
* multiple calls
*
* Since: 1.4 * Since: 1.4
*/ */
ClutterState * ClutterState *
@ -755,40 +769,53 @@ clutter_state_set_key (ClutterState *this,
* clutter_state_get_states: * clutter_state_get_states:
* @state: a #ClutterState instance. * @state: a #ClutterState instance.
* *
* Get a list of all the state names managed by this #ClutterState. * Gets a list of all the state names managed by this #ClutterState.
*
* Return value: (transfer container) (element-type utf8): a newly allocated
* #GList of state names. The contents of the returned #GList are owned
* by the #ClutterState and should not be modified or freed. Use
* g_list_free() to free the resources allocated by the returned list when
* done using it
* *
* Returns: a GList of const gchar * containing state names.
* Since: 1.4 * Since: 1.4
*/ */
GList * GList *
clutter_state_get_states (ClutterState *state) clutter_state_get_states (ClutterState *state)
{ {
g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
return g_hash_table_get_keys (state->priv->states); return g_hash_table_get_keys (state->priv->states);
} }
/** /**
* clutter_state_get_keys: * clutter_state_get_keys:
* @state: a #ClutterState instance. * @state: a #ClutterState instance.
* @source_state_name: the source transition name to query for, or NULL for all * @source_state_name: (allow-none): the source transition name to query,
* source state. * or %NULL for all source states
* @target_state_name: the target transition name to query for, or NULL for all * @target_state_name: (allow-none): the target transition name to query,
* target state. * or %NULL for all target states
* @object: the specific object instance to list keys for, or NULL for all * @object: (allow-none): the specific object instance to list keys for,
* managed objects. * or %NULL for all managed objects
* @property_name: the property name to search for or NULL for all properties. * @property_name: (allow-none): the property name to search for, or %NULL
* for all properties.
* *
* Returns a list of pointers to opaque structures with accessor functions * Returns a list of pointers to opaque structures with accessor functions
* that describe the keys added to an animator. * that describe the keys added to an animator.
* *
* Return value: a GList of #ClutterAnimtorKey<!-- -->s. * Return value: (transfer container) (element-type ClutterStateKey): a
* newly allocated #GList of #ClutterStateKey<!-- -->s. The contents of
* the returned list are owned by the #ClutterState and should not be
* modified or freed. Use g_list_free() to free the resources allocated
* by the returned list when done using it
*
* Since: 1.4 * Since: 1.4
*/ */
GList * GList *
clutter_state_get_keys (ClutterState *state, clutter_state_get_keys (ClutterState *state,
const gchar *source_state_name, const gchar *source_state_name,
const gchar *target_state_name, const gchar *target_state_name,
GObject *object, GObject *object,
const gchar *property_name) const gchar *property_name)
{ {
GList *s, *state_list; GList *s, *state_list;
GList *targets = NULL; GList *targets = NULL;
@ -801,13 +828,9 @@ clutter_state_get_keys (ClutterState *state,
property_name = g_intern_string (property_name); property_name = g_intern_string (property_name);
if (target_state_name != NULL) if (target_state_name != NULL)
{ state_list = g_list_append (NULL, (gpointer) target_state_name);
state_list = g_list_append (NULL, (void*)target_state_name);
}
else else
{ state_list = clutter_state_get_states (state);
state_list = clutter_state_get_states (state);
}
if (source_state_name) if (source_state_name)
source_state = g_hash_table_lookup (state->priv->states, source_state = g_hash_table_lookup (state->priv->states,
@ -825,31 +848,35 @@ clutter_state_get_keys (ClutterState *state,
for (k = target_state->keys; k; k = k->next) for (k = target_state->keys; k; k = k->next)
{ {
ClutterStateKey *key = k->data; ClutterStateKey *key = k->data;
if ((object == NULL || (object == key->object)) && if ((object == NULL || (object == key->object)) &&
(source_state_name == NULL || source_state == key->source_state) && (source_state_name == NULL || source_state == key->source_state) &&
(property_name == NULL || (property_name == NULL ||
((property_name == key->property_name)))) ((property_name == key->property_name))))
{ {
targets = g_list_append (targets, key); targets = g_list_prepend (targets, key);
} }
} }
} }
} }
g_list_free (state_list); g_list_free (state_list);
return targets;
return g_list_reverse (targets);
} }
/** /**
* clutter_state_remove_key: * clutter_state_remove_key:
* @state: a #ClutterState instance. * @state: a #ClutterState instance.
* @source_state_name: the source state name to query for, or NULL for all * @source_state_name: (allow-none): the source state name to query,
* source state. * or %NULL for all source states
* @target_state_name: the target state name to query for, or NULL for all * @target_state_name: (allow-none): the target state name to query,
* target state. * or %NULL for all target states
* @object: the specific object instance to list keys for, or NULL for all * @object: (allow-none): the specific object instance to list keys for,
* managed objects. * or %NULL for all managed objects
* @property_name: the property name to search for or NULL for all properties. * @property_name: (allow-none): the property name to search for,
* or %NULL for all properties.
* *
* Removes all keys matching the search criteria passed in arguments. * Removes all keys matching the search criteria passed in arguments.
* *
@ -857,10 +884,10 @@ clutter_state_get_keys (ClutterState *state,
*/ */
void void
clutter_state_remove_key (ClutterState *state, clutter_state_remove_key (ClutterState *state,
const gchar *source_state_name, const gchar *source_state_name,
const gchar *target_state_name, const gchar *target_state_name,
GObject *object, GObject *object,
const gchar *property_name) const gchar *property_name)
{ {
g_return_if_fail (CLUTTER_IS_STATE (state)); g_return_if_fail (CLUTTER_IS_STATE (state));
@ -874,9 +901,11 @@ clutter_state_remove_key (ClutterState *state,
* clutter_state_get_timeline: * clutter_state_get_timeline:
* @state: a #ClutterState * @state: a #ClutterState
* *
* Get the timeline driving the #ClutterState * Gets the timeline driving the #ClutterState
* *
* Return value: the #ClutterTimeline that drives the state change animations. * Return value: (transfer none): the #ClutterTimeline that drives
* the state change animations. The returned timeline is owned
* by the #ClutterState and it should not be unreferenced directly
* *
* Since: 1.4 * Since: 1.4
*/ */
@ -950,10 +979,12 @@ clutter_state_init (ClutterState *self)
* @source_state_name: the name of a source state * @source_state_name: the name of a source state
* @target_state_name: the name of a target state * @target_state_name: the name of a target state
* *
* Retrieve a ClutterAnimation that is being used for transitioning between two * Retrieves the #ClutterAnimator that is being used for transitioning
* state if any. * between the two states, if any has been set
* *
* Returns: a #ClutterAnimator instance or NULL * Return value: (transfer none): a #ClutterAnimator instance, or %NULL
*
* Since: 1.4
*/ */
ClutterAnimator * ClutterAnimator *
clutter_state_get_animator (ClutterState *state, clutter_state_get_animator (ClutterState *state,
@ -993,13 +1024,21 @@ clutter_state_get_animator (ClutterState *state,
* @state: a #ClutterState instance. * @state: a #ClutterState instance.
* @source_state_name: the name of a source state * @source_state_name: the name of a source state
* @target_state_name: the name of a target state * @target_state_name: the name of a target state
* @animator: a #ClutterAnimator instance. * @animator: (allow-none): a #ClutterAnimator instance, or %NULL to
* unset an existing #ClutterAnimator
* *
* Specify a ClutterAnimation to be used when transitioning between the two * Specifies a #ClutterAnimator to be used when transitioning between
* named state, this allows specifying a transition between the state that is * the two named states.
*
* The @animator allows specifying a transition between the state that is
* more elaborate than the basic transitions other allowed by the simple * more elaborate than the basic transitions other allowed by the simple
* tweening of #ClutterState. Pass NULL to unset an existing animator. * tweening of properties defined in the #ClutterState keys.
* ClutterState takes a reference on the passed in animator if any. *
* If @animator is %NULL it will unset an existing animator.
*
* #ClutterState will take a reference on the passed @animator, if any
*
* Since: 1.4
*/ */
void void
clutter_state_set_animator (ClutterState *state, clutter_state_set_animator (ClutterState *state,
@ -1050,12 +1089,14 @@ clutter_state_set_animator (ClutterState *state,
static gpointer static gpointer
clutter_state_key_copy (gpointer boxed) clutter_state_key_copy (gpointer boxed)
{ {
ClutterStateKey *key = boxed; if (boxed != NULL)
{
ClutterStateKey *key = boxed;
if (key != NULL) key->ref_count += 1;
key->ref_count += 1; }
return key; return boxed;
} }
GType GType