From a65bbfa057c5c915d09cf1bc0291b63abae19e8f Mon Sep 17 00:00:00 2001
From: Pietro Gagliardi <pietro10@mac.com>
Date: Fri, 22 May 2020 18:46:48 -0400
Subject: [PATCH] Started re-adding uiWindow; this just lays down the bare
 minimum API we're re-adding.

---
 doc/00_index.md |  1 +
 doc/window.md   | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 ui.h            |  8 +++++++
 3 files changed, 64 insertions(+)
 create mode 100644 doc/window.md

diff --git a/doc/00_index.md b/doc/00_index.md
index ecae405f..e58dc7d0 100644
--- a/doc/00_index.md
+++ b/doc/00_index.md
@@ -3,6 +3,7 @@
 * [Using libui](using-libui.md)
 * [Initialization and the Main Loop](init-main.md)
 * [Controls](controls.md)
+** [Window](window.md)
 * Windows
 ** [Controls](windows-controls.md)
 * Unix
diff --git a/doc/window.md b/doc/window.md
new file mode 100644
index 00000000..d336abc9
--- /dev/null
+++ b/doc/window.md
@@ -0,0 +1,55 @@
+<!-- 22 may 2020 -->
+
+# Window controls
+
+## Overview
+
+TODO
+
+## Reference
+
+### `uiWindow`
+
+```c
+typedef struct uiWindow uiWindow;
+uiprivExtern uint32_t uiWindowType(void);
+#define uiWindow(obj) ((uiWindow *) uiCheckControlType((obj), uiWindowType()))
+```
+
+`uiWindow` is an opaque `uiControl` type that represents a window.
+
+Windows are the highest level of a control hierarchy that is visibile on screen. All controls that are current visible are contained within a `uiWindow`, and it is the size and position of the window that ultimately decides their size and position (though a control's minimum size may contribute to this). Windows also have titles, which are used to identify the window to the user.
+
+Windows are themselves controls, but behave slightly differently from other controls: they cannot be added as children of other controls (it is a programmer error to do so), they are hidden by default, and OS-level resources are created alongside the `uiWindow` object and survive for the duration of that object (see the OS-specific `uiControl` implementation notes for details).
+
+`uiWindowType()` is the type identifier of a `uiWindow` as passed to `uiCheckControlType()`. You rarely need to call this directly; the `uiWindow()` conversion macro does this for you.
+
+### `uiNewWindow()`
+
+```c
+uiWindow *uiNewWindow(void);
+```
+
+`uiWindow` creates a new window. The window will have the empty string as its title and will not have a child.
+
+TODO other parameters?
+
+### `uiWindowTitle()`
+
+```c
+const char *uiWindowTitle(uiWindow *w);
+```
+
+`uiWindowTitle()` returns `w`'s current title as a UTF-8 string.
+
+The memory storing the title is owned by libui and should not be modified. The returned pointer is valid until the title is changed or `w` is destroyed; in general, you should not store the returned string pointer directly for later use.
+
+### `uiWindowSetTitle()`
+
+```c
+void uiWindowSetTitle(uiWindow *w, const char *title);
+```
+
+`uiWindowSetTitle()` changes `w`'s title to `title`.
+
+It is a programmer error to pass `NULL` for `title`. If `title` is not valid UTF-8, `U+FFFD` characters will be used to sanitize the string.
diff --git a/ui.h b/ui.h
index c38980da..95a3d501 100644
--- a/ui.h
+++ b/ui.h
@@ -66,6 +66,14 @@ uiprivExtern void uiControlFree(uiControl *c);
 uiprivExtern void uiControlSetParent(uiControl *c, uiControl *parent);
 uiprivExtern void *uiControlImplData(uiControl *c);
 
+typedef struct uiWindow uiWindow;
+uiprivExtern uint32_t uiWindowType(void);
+#define uiWindow(obj) ((uiWindow *) uiCheckControlType((obj), uiWindowType()))
+
+uiprivExtern uiWindow *uiNewWindow(void);
+uiprivExtern const char *uiWindowTitle(uiWindow *w);
+uiprivExtern void uiWindowSetTitle(uiWindow *w, const char *title);
+
 #ifdef __cplusplus
 }
 #endif