Commit a9463d4a authored by Manuel Genovés's avatar Manuel Genovés
Browse files

Add docstrings

parent 6736dd02
Pipeline #309864 failed with stage
in 2 minutes and 7 seconds
......@@ -4,6 +4,18 @@
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* AdwAnimationTarget:
*
* `AdwAnimationTarget` acts as a frame delegate which is called each tick of the animation
* and applies the current value.
*
* There are several `AdwAnimationTarget` implementations available, being
* `AdwPropertyAnimationTarget` (to be implemented) an easy way to bind the animation to a existing
* propert and `AdwCallbackAnimationTarget` a more flexible callback delegate which takes an arbitrary
* callback.
*/
#include "config.h"
#include "adw-animation-target.h"
......@@ -79,6 +91,17 @@ adw_callback_animation_target_init (AdwCallbackAnimationTarget *self)
{
}
/**
* adw_callback_animation_target_new:
* @callback: a `AdwAnimationTargetFunc`
* @user_data: the data to pass to @callback
*
* Creates a new `AdwCallbackAnimationTarget`.
*
* Returns: The newly created `AdwCallbackAnimationTarget`.
*
* Since: 1.0
*/
AdwAnimationTarget *
adw_callback_animation_target_new (AdwAnimationTargetFunc callback,
gpointer user_data)
......
......@@ -5,6 +5,25 @@
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* AdwAnimation:
*
* `AdwAnimation` is the base class of all the animation helpers libAdwaita
* provides.
*
* `AdwAnimation` contain functions for managing the playback of the animations
* such as [method@Gtk.AdwAnimation.play] or [method@Gtk.AdwAnimation.stop]
*
* All `AdwAnimations` are bound to a [class@Gtk.Widget] and animate a certain value. To
* what that value is hooked is determined by the specified [class@Adw.AnimationTarget],
* and how the value is animated depends on the kind of [class@Adw.Animation] used.
*
* libAdwaita provides the following kind of animations:
*
* - [class@Adw.TimedAnimation]: an animation which animates a value in a certain time
* using a specified interpolator
*/
#include "config.h"
#include "adw-animation-util-private.h"
......@@ -154,6 +173,13 @@ adw_animation_class_init (AdwAnimationClass *klass)
klass->estimate_duration = adw_animation_estimate_duration;
klass->calculate_value = adw_animation_calculate_value;
/**
* AdwAnimation:value: (attributes org.gtk.Property.get=adw_animation_get_value)
*
* The current value of the animation.
*
* Since: 1.0
*/
props[PROP_VALUE] =
g_param_spec_double ("value",
"Value",
......@@ -163,6 +189,13 @@ adw_animation_class_init (AdwAnimationClass *klass)
0,
G_PARAM_READABLE);
/**
* AdwAnimation:widget: (attributes org.gtk.Property.get=adw_animation_get_widget)
*
* The target widget whose property will be animated.
*
* Since: 1.0
*/
props[PROP_WIDGET] =
g_param_spec_object ("widget",
"Widget",
......@@ -170,23 +203,45 @@ adw_animation_class_init (AdwAnimationClass *klass)
GTK_TYPE_WIDGET,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
/**
* AdwAnimation:target: (attributes org.gtk.Property.get=adw_animation_get_target org.gtk.Property.set=adw_animation_set_target)
*
* Delegate for applying the animation value.
*
* Since: 1.0
*/
props[PROP_TARGET] =
g_param_spec_object ("target",
"Target",
"Target",
"Delegate for applying the animation value",
ADW_TYPE_ANIMATION_TARGET,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwAnimation:status: (attributes org.gtk.Property.get=adw_animation_get_status)
*
* Current status of the animation.
*
* Since: 1.0
*/
props[PROP_STATUS] =
g_param_spec_enum ("status",
"Status",
"Status of the animation",
"Current status of the animation",
ADW_TYPE_ANIMATION_STATUS,
ADW_ANIMATION_STATUS_NONE,
G_PARAM_READABLE);
g_object_class_install_properties (object_class, LAST_PROP, props);
/**
* AdwAnimation::done:
* @self: the `AdwAnimation` instance
*
* This signal is emitted after the animation has ended.
*
* Since: 1.0
*/
signals[SIGNAL_DONE] =
g_signal_new ("done",
G_TYPE_FROM_CLASS (klass),
......@@ -264,7 +319,14 @@ adw_animation_new (GtkWidget *widget,
NULL);
}
/**
* adw_animation_start:
* @self: a `AdwAnimation`
*
* Starts the animation.
*
* Since: 1.0
*/
void
adw_animation_start (AdwAnimation *self)
{
......@@ -298,6 +360,14 @@ adw_animation_start (AdwAnimation *self)
priv->tick_cb_id = gtk_widget_add_tick_callback (priv->widget, (GtkTickCallback) tick_cb, self, NULL);
}
/**
* adw_animation_stop:
* @self: a `AdwAnimation`
*
* Stops the animation and emmits the [signal@Adw.Animation::done] signal.
*
* Since: 1.0
*/
void
adw_animation_stop (AdwAnimation *self)
{
......
......@@ -5,6 +5,19 @@
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* AdwTimedAnimation:
*
* `AdwTimedAnimation` interpolates between two values in the required time.
*
* `AdwAnimation` lets you define the start and destination values, the duration of the
* animation, and the kind of interpolation which should be used for it.
*
* `AdwAnimation` lets you specify the number of times it should play (including indefinite)
* and the desired behavior, such as play the animation in reverse or alternate between
* normal and reverse in each iteration count.
*/
#include "config.h"
#include "adw-animation-util-private.h"
......@@ -54,7 +67,7 @@ adw_timed_animation_estimate_duration (AdwAnimation *animation)
if (self->repeat_count == -1)
return ADW_DURATION_INFINITE;
return self->duration * adw_timed_animation_get_repetitions (self);
return self->duration * adw_timed_animation_get_repeat_count (self);
}
static double
......@@ -122,7 +135,7 @@ adw_timed_animation_get_property (GObject *object,
switch (prop_id) {
case PROP_REPEAT_COUNT:
g_value_set_int (value, adw_timed_animation_get_repetitions (self));
g_value_set_int (value, adw_timed_animation_get_repeat_count (self));
break;
case PROP_REVERSE:
......@@ -164,7 +177,7 @@ adw_timed_animation_set_property (GObject *object,
switch (prop_id) {
case PROP_REPEAT_COUNT:
adw_timed_animation_set_repetitions (self, g_value_get_int (value));
adw_timed_animation_set_repeat_count (self, g_value_get_int (value));
break;
case PROP_REVERSE:
......@@ -208,7 +221,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
animation_class->estimate_duration = adw_timed_animation_estimate_duration;
animation_class->calculate_value = adw_timed_animation_calculate_value;
/**
* AdwTimedAnimation:repeat-count: (attributes org.gtk.Property.get=adw_timed_animation_get_repeat_count org.gtk.Property.set=adw_timed_animation_set_repeat_count)
*
* Number of times the animation should play. Set -1 for a looped animation.
*
* Since: 1.0
*/
props[PROP_REPEAT_COUNT] =
g_param_spec_int ("repeat-count",
"Repeat count",
......@@ -217,6 +236,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
1,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:reverse: (attributes org.gtk.Property.get=adw_timed_animation_get_reverse org.gtk.Property.set=adw_timed_animation_set_reverse)
*
* Wheter the animation should play backwards.
*
* Since: 1.0
*/
props[PROP_REVERSE] =
g_param_spec_boolean ("reverse",
"Reverse",
......@@ -224,6 +250,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
FALSE,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:alternate: (attributes org.gtk.Property.get=adw_timed_animation_get_alternate org.gtk.Property.set=adw_timed_animation_set_alternate)
*
* Wheter the animation should alternate playing forwards/backwards each time it's played.
*
* Since: 1.0
*/
props[PROP_ALTERNATE] =
g_param_spec_boolean ("alternate",
"Alternate",
......@@ -231,6 +264,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
FALSE,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:value-from: (attributes org.gtk.Property.get=adw_timed_animation_get_value_from org.gtk.Property.set=adw_timed_animation_set_value_from)
*
* Initial value of the animation.
*
* Since: 1.0
*/
props[PROP_VALUE_FROM] =
g_param_spec_double ("value-from",
"Initial value",
......@@ -240,6 +280,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:value-to: (attributes org.gtk.Property.get=adw_timed_animation_get_value_to org.gtk.Property.set=adw_timed_animation_set_value_to)
*
* Final value of the animation.
*
* Since: 1.0
*/
props[PROP_VALUE_TO] =
g_param_spec_double ("value-to",
"Final value",
......@@ -249,6 +296,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:duration: (attributes org.gtk.Property.get=adw_timed_animation_get_duration org.gtk.Property.set=adw_timed_animation_set_duration)
*
* Duration of the animation in ms.
*
* Since: 1.0
*/
props[PROP_DURATION] =
g_param_spec_uint ("duration",
"Duration",
......@@ -258,6 +312,13 @@ adw_timed_animation_class_init (AdwTimedAnimationClass *klass)
0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
/**
* AdwTimedAnimation:interpolator: (attributes org.gtk.Property.get=adw_timed_animation_get_interpolator org.gtk.Property.set=adw_timed_animation_set_interpolator)
*
* Easing function used in the animation.
*
* Since: 1.0
*/
props[PROP_INTERPOLATOR] =
g_param_spec_enum ("interpolator",
"Interpolator",
......@@ -275,6 +336,21 @@ adw_timed_animation_init (AdwTimedAnimation *self)
{
}
/**
* adw_timed_animation_new:
* @widget: the widget where the animation is created
* @from: the initial value of the animation
* @to: the final value of the animation
* @duration: the duration in ms of the animation
* @target_func: the delegate to be executed each tick of the animation
* @user_data: the data to be passed to @target_func
*
* Creates a new `AdwTimedAnimation`.
*
* Returns: The newly created `AdwTimedAnimation`.
*
* Since: 1.0
*/
AdwAnimation *
adw_timed_animation_new (GtkWidget *widget,
double from,
......@@ -298,17 +374,36 @@ adw_timed_animation_new (GtkWidget *widget,
NULL);
}
/**
* adw_timed_animation_get_repeat_count:
* @self: a `AdwTimedAnimation`
*
* Gets the number of times the animation has to run.
*
* Returns: the number of times the animation has to run or -1 if the animation has to loop.
*
* Since: 1.0
*/
int
adw_timed_animation_get_repetitions (AdwTimedAnimation *self)
adw_timed_animation_get_repeat_count (AdwTimedAnimation *self)
{
g_return_val_if_fail (ADW_IS_TIMED_ANIMATION (self), 0);
return self->repeat_count;
}
/**
* adw_timed_animation_set_repeat_count:
* @self: a `AdwTimedAnimation`
* @value: the number of times the animation has to run or -1 if the animation has to loop
*
* Sets the number of times the animation has to run.
*
* Since: 1.0
*/
void
adw_timed_animation_set_repetitions (AdwTimedAnimation *self,
int value)
adw_timed_animation_set_repeat_count (AdwTimedAnimation *self,
int value)
{
g_return_if_fail (ADW_IS_TIMED_ANIMATION (self));
......@@ -320,6 +415,16 @@ adw_timed_animation_set_repetitions (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_REPEAT_COUNT]);
}
/**
* adw_timed_animation_get_reverse:
* @self: a `AdwTimedAnimation`
*
* Gets wheter the animation has to play backwards.
*
* Returns: `TRUE` if the animation has to play backwards.
*
* Since: 1.0
*/
gboolean
adw_timed_animation_get_reverse (AdwTimedAnimation *self)
{
......@@ -328,6 +433,15 @@ adw_timed_animation_get_reverse (AdwTimedAnimation *self)
return self->reverse;
}
/**
* adw_timed_animation_set_reverse:
* @self: a `AdwTimedAnimation`
* @value: wheter the animation has to play backwards
*
* Sets wheter the animation has to play backwards.
*
* Since: 1.0
*/
void
adw_timed_animation_set_reverse (AdwTimedAnimation *self,
gboolean value)
......@@ -342,6 +456,16 @@ adw_timed_animation_set_reverse (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_REVERSE]);
}
/**
* adw_timed_animation_get_alternate:
* @self: a `AdwTimedAnimation`
*
* Gets wheter the animation has to alternate between regular and reverse playback when [property@Adw.TimedAnimation:repeat_count] is different than 1.
*
* Returns: `TRUE` if the animation has to alternate between regular and reverse playback.
*
* Since: 1.0
*/
gboolean
adw_timed_animation_get_alternate (AdwTimedAnimation *self)
{
......@@ -350,6 +474,15 @@ adw_timed_animation_get_alternate (AdwTimedAnimation *self)
return self->alternate;
}
/**
* adw_timed_animation_set_alternate:
* @self: a `AdwTimedAnimation`
* @value: wheter the animation has to alternate between regular and reverse playback
*
* Sets wheter the animation has to alternate between regular and reverse playback when [property@Adw.TimedAnimation:repeat_count] is different than 1.
*
* Since: 1.0
*/
void
adw_timed_animation_set_alternate (AdwTimedAnimation *self,
gboolean value)
......@@ -364,6 +497,16 @@ adw_timed_animation_set_alternate (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_ALTERNATE]);
}
/**
* adw_timed_animation_get_value_from:
* @self: a `AdwTimedAnimation`
*
* Gets the initial value of the animation
*
* Returns: the initial value of the animation.
*
* Since: 1.0
*/
double
adw_timed_animation_get_value_from (AdwTimedAnimation *self)
{
......@@ -372,6 +515,15 @@ adw_timed_animation_get_value_from (AdwTimedAnimation *self)
return self->value_from;
}
/**
* adw_timed_animation_set_value_from:
* @self: a `AdwTimedAnimation`
* @value: the initial value of the animation
*
* Sets the initial value of the animation.
*
* Since: 1.0
*/
void
adw_timed_animation_set_value_from (AdwTimedAnimation *self,
double value)
......@@ -386,6 +538,16 @@ adw_timed_animation_set_value_from (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_VALUE_FROM]);
}
/**
* adw_timed_animation_get_value_to:
* @self: a `AdwTimedAnimation`
*
* Gets the final value of the animation
*
* Returns: the final value of the animation.
*
* Since: 1.0
*/
double
adw_timed_animation_get_value_to (AdwTimedAnimation *self)
{
......@@ -394,6 +556,15 @@ adw_timed_animation_get_value_to (AdwTimedAnimation *self)
return self->value_to;
}
/**
* adw_timed_animation_set_value_to:
* @self: a `AdwTimedAnimation`
* @value: the final value of the animation
*
* Sets the final value of the animation.
*
* Since: 1.0
*/
void
adw_timed_animation_set_value_to (AdwTimedAnimation *self,
double value)
......@@ -408,6 +579,16 @@ adw_timed_animation_set_value_to (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_VALUE_TO]);
}
/**
* adw_timed_animation_get_duration:
* @self: a `AdwTimedAnimation`
*
* Gets the duration of the animation in ms
*
* Returns: the duration of the animation in ms.
*
* Since: 1.0
*/
guint
adw_timed_animation_get_duration (AdwTimedAnimation *self)
{
......@@ -416,6 +597,15 @@ adw_timed_animation_get_duration (AdwTimedAnimation *self)
return self->duration;
}
/**
* adw_timed_animation_set_duration:
* @self: a `AdwTimedAnimation`
* @value: the duration of the animation in ms
*
* Sets the duration of the animation in ms.
*
* Since: 1.0
*/
void
adw_timed_animation_set_duration (AdwTimedAnimation *self,
guint duration)
......@@ -430,6 +620,16 @@ adw_timed_animation_set_duration (AdwTimedAnimation *self,
g_object_notify_by_pspec (G_OBJECT (self), props[PROP_DURATION]);
}
/**
* adw_timed_animation_get_interpolator:
* @self: a `AdwTimedAnimation`
*
* Gets the [class@Adw.TimedAnimationInterpolator] of the animation.
*
* Returns: a [class@Adw.TimedAnimationInterpolator].
*
* Since: 1.0
*/
AdwTimedAnimationInterpolator
adw_timed_animation_get_interpolator (AdwTimedAnimation *self)
{
......@@ -438,6 +638,15 @@ adw_timed_animation_get_interpolator (AdwTimedAnimation *self)
return self->interpolator;
}
/**
* adw_timed_animation_set_interpolator:
* @self: a `AdwTimedAnimation`
* @interpolator: a `AdwTimedAnimationInterpolator`
*
* Sets the [class@Adw.TimedAnimationInterpolator] of the animation.
*
* Since: 1.0
*/
void
adw_timed_animation_set_interpolator (AdwTimedAnimation *self,
AdwTimedAnimationInterpolator interpolator)
......
......@@ -41,10 +41,10 @@ AdwAnimation *adw_timed_animation_new (GtkWidget *widget,
gpointer user_data) G_GNUC_WARN_UNUSED_RESULT;
ADW_AVAILABLE_IN_ALL
int adw_timed_animation_get_repetitions (AdwTimedAnimation *self);
int adw_timed_animation_get_repeat_count (AdwTimedAnimation *self);
ADW_AVAILABLE_IN_ALL
void adw_timed_animation_set_repetitions (AdwTimedAnimation *self,
int value);
void adw_timed_animation_set_repeat_count (AdwTimedAnimation *self,
int value);
ADW_AVAILABLE_IN_ALL
gboolean adw_timed_animation_get_reverse (AdwTimedAnimation *self);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment