From 0ce03767256a3fb1b542cf91a1d45f2c57c92fd3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Florian=20M=C3=BCllner?= <fmuellner@gnome.org>
Date: Sat, 21 Jul 2018 03:18:29 +0200
Subject: [PATCH] docs: Update animation section

Replace the existing Tweener section with a small outline of the
Clutter animation API and our wrappers.

https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/669
---
 HACKING.md | 72 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 43 insertions(+), 29 deletions(-)

diff --git a/HACKING.md b/HACKING.md
index a9a92ea8d..3e2450b18 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -84,7 +84,6 @@ don't use.
 
     const Main = imports.ui.main;
     const Params = imports.misc.params;
-    const Tweener = imports.ui.tweener;
     const Util = imports.misc.util;
 ```
 The alphabetical ordering should be done independently of the location of the
@@ -277,34 +276,49 @@ If your usage of an object is like a hash table (and thus conceptually the keys
 can have special chars in them), don't use quotes, but use brackets: `{ bar: 42
 }`, `foo['bar']`.
 
-## Getters, setters, and Tweener
+## Animations
+
+Most objects that are animated are actors, and most properties used in animations
+are animatable, which means they can use implicit animations:
 
-Getters and setters should be used when you are dealing with an API that is
-designed around setting properties, like Tweener. If you want to animate an
-arbitrary property, create a getter and setter, and use Tweener to animate the
-property.
 ```javascript
-    var ANIMATION_TIME = 2000;
-
-    var MyClass = class {
-        constructor() {
-            this.actor = new St.BoxLayout();
-            this._position = 0;
-        }
-
-        get position() {
-            return this._position;
-        }
-
-        set position(value) {
-            this._position = value;
-            this.actor.set_position(value, value);
-        }
-    };
-
-    let myThing = new MyClass();
-    Tweener.addTween(myThing,
-                     { position: 100,
-                       time: ANIMATION_TIME,
-                       transition: 'easeOutQuad' });
+    moveActor(actor, x, y) {
+        actor.ease({
+            x,
+            y,
+            duration: 500, // ms
+            mode: Clutter.AnimationMode.EASE_OUT_QUAD
+        });
+    }
+```
+
+The above is a convenience wrapper around the actual Clutter API, and should generally
+be preferred over the more verbose:
+
+```javascript
+    moveActor(actor, x, y) {
+        actor.save_easing_state();
+
+        actor.set_easing_duration(500);
+        actor.set_easing_mode(Clutter.AnimationMode.EASE_OUT_QUAD);
+        actor.set({
+            x,
+            y
+        });
+
+        actor.restore_easing_state();
+    }
+```
+
+There is a similar convenience API around Clutter.PropertyTransition to animate
+actor (or actor meta) properties that cannot use implicit animations:
+
+```javascript
+    desaturateActor(actor, desaturate) {
+        let factor = desaturate ? 1.0 : 0.0;
+        actor.ease_property('@effects.desaturate.factor', factor, {
+            duration: 500, // ms
+            mode: Clutter.AnimationMode.EASE_OUT_QUAD
+        });
+    }
 ```