From a0ea6c871beb5293891578f1b0dd17102b880729 Mon Sep 17 00:00:00 2001
From: Kostas Kougios <kostas.kougios@googlemail.com>
Date: Mon, 5 Feb 2024 17:13:30 +0000
Subject: [PATCH] -

---
 docs/tutorial.md            | 48 +++++++++++++++++++++++++++++++++++++
 example-scripts/on-click.sc | 19 +++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100755 example-scripts/on-click.sc

diff --git a/docs/tutorial.md b/docs/tutorial.md
index 41516965..ad02e9c2 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -5,6 +5,8 @@ like to learn how to create user interfaces.
 
 This tutorial will use `scala-cli` but the same applies for `sbt` or `mill` projects that use the terminal21 libraries.
 
+All example code is under `example-scripts` of this repo, feel free to check the repo and run them.
+
 ## Creating a folder for our scripts
 
 Create a folder and a file `project.scala` into it. This file will help us include the library dependencies and also
@@ -155,3 +157,49 @@ Finally, when the universe is ready, we just clear the UI and render a paragraph
 session.clear()
 Paragraph(text = "Universe ready!").render()
 ```
+## Handling clicks
+
+Some UI elements allow us to attach an `onClick` handler. When the user clicks the element, our scala code runs.
+
+Let's see for example [on-click.sc](../example-scripts/on-click.sc). We will create a paragraph and a button. When the
+user clicks the button, the paragraph text will change and the script will exit.
+
+```scala
+#!/usr/bin/env -S scala-cli project.scala
+
+import org.terminal21.client.*
+import org.terminal21.client.components.*
+import org.terminal21.client.components.std.*
+import org.terminal21.client.components.chakra.*
+
+Sessions.withNewSession("on-click-example", "On Click Handler"): session =>
+  given ConnectedSession = session
+
+  @volatile var exit = false
+  val msg = Paragraph(text = "Waiting for user to click the button")
+  val button = Button(text = "Please click me").onClick: () =>
+    msg.withText("Button clicked.").renderChanges()
+    exit = true
+
+  Seq(msg, button).render()
+
+  session.waitTillUserClosesSessionOr(exit)
+```
+
+First we create the paragraph and button. We attach an `onClick` handler on the button:
+
+```scala
+  val button = Button(text = "Please click me").onClick: () =>
+    msg.withText("Button clicked.").renderChanges()
+    exit = true
+```
+Here we change the paragraph text and also update `exit` to `true`.
+
+Our script waits until var `exit` becomes true and then terminates.
+
+```scala
+session.waitTillUserClosesSessionOr(exit)
+```
+
+Now if we run it with `./on-click.sc` and click the button, the script will terminate.
+
diff --git a/example-scripts/on-click.sc b/example-scripts/on-click.sc
new file mode 100755
index 00000000..ef877a14
--- /dev/null
+++ b/example-scripts/on-click.sc
@@ -0,0 +1,19 @@
+#!/usr/bin/env -S scala-cli project.scala
+
+import org.terminal21.client.*
+import org.terminal21.client.components.*
+import org.terminal21.client.components.std.*
+import org.terminal21.client.components.chakra.*
+
+Sessions.withNewSession("on-click-example", "On Click Handler"): session =>
+  given ConnectedSession = session
+
+  @volatile var exit = false
+  val msg = Paragraph(text = "Waiting for user to click the button")
+  val button = Button(text = "Please click me").onClick: () =>
+    msg.withText("Button clicked.").renderChanges()
+    exit = true
+
+  Seq(msg, button).render()
+
+  session.waitTillUserClosesSessionOr(exit)