From d749a725503b562d36942d484c8e7500bdbeb12f Mon Sep 17 00:00:00 2001
From: "Robert C. Martin" <unclebob@cleancoder.com>
Date: Sat, 19 Feb 2022 08:50:33 -0600
Subject: [PATCH] Some comments and clojure/spec updates.

---
 src/more_speech/ui/application.clj | 23 ++++++++++++++++++++---
 src/more_speech/ui/widget.clj      | 16 ++++++++++++++++
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/src/more_speech/ui/application.clj b/src/more_speech/ui/application.clj
index 6d0c3d4..b9b54f7 100644
--- a/src/more_speech/ui/application.clj
+++ b/src/more_speech/ui/application.clj
@@ -1,3 +1,14 @@
+;;
+;; Application is the highest level widget and must be the :application
+;; member of state.
+;;
+;; Members
+;; :graphics -- The instance of the graphics protocol.
+;; :update-articles -- Set to true if the article window content needs updating.
+;; :mouse-locked-to -- nil if no lock.  Otherwise the path of the widget to which
+;;                     the mouse is locked.
+;;
+
 (ns more-speech.ui.application
   (:require [clojure.spec.alpha :as s]
             [more-speech.ui.widget :refer [widget
@@ -12,21 +23,27 @@
             [more-speech.nostr.events :as events]
             [more-speech.ui.config :as config]))
 
+(s/def ::path (s/tuple [keyword?]))
+(s/def ::graphics #(satisfies? g/graphics %))
+(s/def ::mouse-locked-to #(or (nil? %) (satisfies? widget %)))
 (s/def ::nicknames (s/map-of number? string?))
 (s/def ::chronological-text-events (s/coll-of number?))
 (s/def ::text-event-map (s/map-of number? ::events/event))
 (s/def ::open-thread (s/coll-of number? :kind set?))
 (s/def ::update-articles boolean?)
-(s/def ::application (s/keys :req-un [::nicknames
+(s/def ::application (s/keys :req-un [::path
+                                      ::graphics
+                                      ::update-articles
+                                      ::mouse-locked-to
+                                      ::nicknames
                                       ::chronological-text-events
                                       ::text-event-map
                                       ::open-thread
-                                      ::update-articles
                                       ]))
 
 (declare setup-application)
 
-(defrecord application [path graphics nicknames]
+(defrecord application [path graphics update-articles mouse-locked-to]
   widget
   (setup-widget [widget state]
     (setup-application widget path state))
diff --git a/src/more_speech/ui/widget.clj b/src/more_speech/ui/widget.clj
index 2f55aa4..71c8e36 100644
--- a/src/more_speech/ui/widget.clj
+++ b/src/more_speech/ui/widget.clj
@@ -1,3 +1,19 @@
+;; Widgets form a hierarchy. Any member of a widget that satisfies? the widget
+;; protocol will be considered a child widget.  The setup-widget, update-widget,
+;; and draw-widget functions are propagated through all the children.
+;;
+;; Widgets are addressed through their path from the state. The :path member
+;; contains that path.  (get-in state (:path widget)) will return the current
+;; version of the widget.  (assoc-in state (:path widget) widget) puts any
+;; updates to the widget back into the state.
+;;
+;; The :x and :y members are in global (screen) coordinates.  The :h and :w
+;; members are in pixels.  By convention child widgets should fit within the
+;; x,y,w,h bounds of their parents.
+;;
+;; Mouse gestures are typically routed to the deepest child that contains them.
+;;
+
 (ns more-speech.ui.widget
   (:require [more-speech.util.geometry :refer [inside-rect]]))