From 8f919adbc2068a68acee63ffcefa1ffb69587231 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Florian=20M=C3=BCllner?= <fmuellner@gnome.org>
Date: Fri, 1 Sep 2023 01:40:36 +0200
Subject: [PATCH] doc: Add looking glass documentation

Looking glass is not just helpful for development, but also when
asking users to provide relevant information.

Having it in-tree makes it easy to reference, and ensures that
the documentation is still in a maintained place when plans to
retire the wiki go head.

The content is based on the [wiki-page] with updated code samples,
small sections on added features, and outdated references removed
(anyone remember project looking glass?).

[wiki-page]: https://wiki.gnome.org/Projects/GnomeShell/LookingGlass

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/2932>
---
 docs/lookingGlass.md | 95 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/lookingGlass.md

diff --git a/docs/lookingGlass.md b/docs/lookingGlass.md
new file mode 100644
index 000000000..f626eb908
--- /dev/null
+++ b/docs/lookingGlass.md
@@ -0,0 +1,95 @@
+# Looking Glass
+
+Looking Glass is GNOME Shell's integrated debugger and inspector tool.
+
+You currently run it by pressing <kbd>Alt</kbd> <kbd>F2</kbd>,
+and typing `lg`<kbd>Return</kbd>.
+
+You can leave Looking Glass by pressing <kbd>Esc</kbd> in its
+Evaluator pane.
+
+Looking Glass has five major panes (Evaluator, Windows, Extensions,
+Actors and Flags) and one tool (the Picker).
+
+## Evaluator
+
+This is an interactive JavaScript prompt. You can type arbitrary
+JavaScript at the prompt, and it will be evaluated. Try, in order:
+
+```js
+1+1
+
+global.get_window_actors()
+
+global.get_window_actors().forEach(w => w.ease({duration: 3000, mode: Clutter.AnimationMode.EASE_OUT_QUAD, scale_x: 0.3, scale_y: 0.3}))
+
+global.get_window_actors().forEach(w => w.set_scale(1, 1))
+
+global.get_window_actors()[0]
+
+it.scale_x
+```
+
+### Special evaluator features
+
+This last bit, the `it`, deserves more explanation. One thing about the
+Evaluator that's different from say Python's default interactive prompt is
+that each computed value is saved by default, and can be referred back to.
+Typing r(*number* ) will get you back the result with that number, and `it`
+is the last result.
+
+The evaluator also has a history feature; you can press <kbd>↑</kbd> and
+<kbd>↓</kbd> to access previously used entries. The history is automatically
+saved to the dconf key `/org/gnome/shell/looking-glass-history`, and loaded
+when you restart the shell.
+
+### Imports
+
+Some common modules like Clutter, GObject or Main are pre-imported and always
+available.
+
+Additional modules can be loaded using dynamic imports:
+```js
+Util = await import('../misc/util.js')
+{Panel} = await import('./panel.js')
+{default: Pango} = await import('gi://Pango')
+```
+
+### Slowing Down Animations
+
+You can use Looking Glass to access the global `St.Settings` object and set
+its `slow_down_factor` property:
+
+```js
+St.Settings.get().slow_down_factor = 5
+```
+
+Any value greater than 1 makes all shell animations slower. This is
+particularly useful when implementing a new animation behavior.
+
+## Windows
+
+This is a list of all open windows and related information,
+like the associated app.
+
+## Extensions
+
+This is a list of all currently installed extensions. You can use
+the View Source link to quickly access the extension folder.
+
+## Actors
+
+This pane gives access to a complete tree of the actor hierarchy.
+It is useful when an actor cannot be selected with the picker or
+accessed via code in the evaluator.
+
+## Flags
+
+This pane provides easy access to a list of Mutter and Clutter debug flags.
+
+## The Picker
+
+The picker allows you to visually select any object from the shell's scene.
+When you do, it's inserted as a result into the Evaluator pane.
+
+During picking, you can scroll to move up and down the actor hierarchy.