ClutterActor: expose setter for the opacity override

Toolkits may need to paint actors internally outside the normal tree
(for example to create a shadow shape), in which case they need to
control the opacity directly.

https://bugzilla.gnome.org/show_bug.cgi?id=677412

Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>

1 files changed, 34 insertions, 4 deletions

diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 5735edfb7..e7c5c7f55 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -15753,20 +15753,50 @@ clutter_actor_create_pango_layout (ClutterActor *self,
   return layout;
 }
 
-/* Allows overriding the calculated paint opacity. Used by ClutterClone and
- * ClutterOffscreenEffect.
+/**
+ * clutter_actor_set_opacity_override:
+ * @self: a #ClutterActor
+ * @opacity: the override opacity value, or -1 to reset
+ *
+ * Allows overriding the calculated paint opacity (as returned by
+ * clutter_actor_get_paint_opacity()). This is used internally by
+ * ClutterClone and ClutterOffscreenEffect, and should be used by
+ * actors that need to mimick those.
+ *
+ * In almost all cases this should not used by applications.
+ *
+ * Stability: unstable
  */
 void
-_clutter_actor_set_opacity_override (ClutterActor *self,
+clutter_actor_set_opacity_override (ClutterActor *self,
                                      gint          opacity)
 {
   g_return_if_fail (CLUTTER_IS_ACTOR (self));
 
+  /* ensure bounds */
+  if (opacity >= 0)
+    opacity = CLAMP (opacity, 0, 255);
+  else
+    opacity = -1;
+
   self->priv->opacity_override = opacity;
 }
 
+/**
+ * clutter_actor_get_opacity_override:
+ * @self: a #ClutterActor
+ *
+ * See clutter_actor_set_opacity_override()
+ *
+ * Returns: the override value for the actor's opacity, or -1 if no override
+ *   is set.
+ *
+ * Since: 1.22
+ *
+ * Stability: unstable
+ */
 gint
-_clutter_actor_get_opacity_override (ClutterActor *self)
+clutter_actor_get_opacity_override (ClutterActor *self)
 {
   g_return_val_if_fail (CLUTTER_IS_ACTOR (self), -1);