T-G-U-I

tgui/docs/tutorial-and-examples.md

@@ -76,7 +76,8 @@ input. The input's `action` and `params` are passed to the proc.
 
 ```dm
 /obj/machinery/my_machine/ui_act(action, params)
-  if(..())
+  . = ..()
+  if(.)
     return
   if(action == "change_color")
     var/new_color = params["color"]
@@ -88,13 +89,20 @@ input. The input's `action` and `params` are passed to the proc.
 ```
 
 The `..()` (parent call) is very important here, as it is how we check that the
-user is allowed to use this interface (to avoid so-called href exploits). It is
-also very important to clamp and sanitize all input here. Always assume the user
-is attempting to exploit the game.
+user is allowed to use this interface (to avoid so-called href exploits). When
+any event has been handled `..()` will return `TRUE`. It is important to clamp
+and sanitize all input here. Always assume the user is attempting to exploit the
+game.
+
+When `..()` has returned `TRUE` your interface can safely assume that the user's
+action has been handled already by some parent proc and you should not continue
+to handle this, instead preserving and returning the parent proc's return value.
 
 Also note the use of `. = TRUE` (or `FALSE`), which is used to notify the UI
-that this input caused an update. This is especially important for UIs that do
-not auto-update, as otherwise the user will never see their change.
+that this input has been handled. When `ui_act` eventually returns, a value of
+`TRUE` indicates that the input has been handled and that the UI should update.
+This is important for UIs that do not auto-update, as otherwise the user will
+not be able to see the interface update based on thier actions.
 
 ### Frontend