From 8834548d0748e2fc76c55c9b49e5c6a2e3bae578 Mon Sep 17 00:00:00 2001
From: Jeff Carr <jcarr@wit.com>
Date: Wed, 5 Mar 2025 02:59:51 -0600
Subject: [PATCH] add notes

---
 widget.proto | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/widget.proto b/widget.proto
index ebe3f97..0cbc7ea 100644
--- a/widget.proto
+++ b/widget.proto
@@ -13,12 +13,13 @@ message Size  {
         int64                 height       = 2;
 }
 
+// used for grid layouts
 message Location  {
         int64                 x            = 1;
         int64                 y            = 2;
 }
 
-message Tree {
+message Tree {                                   // `autogenpb:marshal`
         Widget                parent       = 1;
         repeated Widget       children     = 2;
 }
@@ -31,31 +32,31 @@ message Widget {
         google.protobuf.Any   TK           = 5;
         WidgetType            Type         = 6;
         Location              location     = 7;
-                                                 // Size                  size         = 3;
-                                                 // string                color        = 5;
 }
 
 message Widgets {                                // `autogenpb:marshal`
         string                uuid         = 1;  // `autogenpb:uuid:0331fcd7-3c8c-43e4-be1b-77db6a6bc58c`
         string                version      = 2;  // `autogenpb:version:v1`
-        repeated Widget       Widgets      = 3;
-        Tree                  tree         = 4;
+        repeated Widget       Widgets      = 3;  // this never gets used, but it's not worth violating the autogenpb standard
+        Tree                  tree         = 4;  // everything is sent from go.wit.com/gui here
 }
 
-// todo: fix autogenpb to look for enum
+//
+// Widget names should try to match [Wikipedia Graphical widget]
+// TODO: fix autogenpb to look for enum
 enum WidgetType {
 	Root                = 0;  // the master 'root' node of the binary tree
-	Flag                = 1;  //
+	Flag                = 1;  // internal use
 	Window              = 2;  //
 	Tab                 = 3;  // a tab like in firefox
-	Box                 = 4;  //
+	Box                 = 4;  // must be either Vertical or Horizontal arrangment
 	Group               = 5;  // think 'Appetizers' on a restaurant menu
-	Grid                = 6;  // like drawers in a chest
-	Button              = 7;  //
-	Checkbox            = 8;  //
+	Grid                = 6;  // like drawers in a chest or post office boxes
+	Button              = 7;  // user can click on this
+	Checkbox            = 8;  // true or false
 	Dropdown            = 9;  //
-	Combobox            = 10; //
-	Label               = 11; //
-	Textbox             = 12; //
-	TablePB             = 13; //
+	Combobox            = 10; // a dropdown menu that can be edited by the user
+	Label               = 11; // a simple label
+	Textbox             = 12; // enter text
+	TablePB             = 13; // special case to allow the arbitrary GUI display of any other protobuf
 }