Started re-adding uiWindow; this just lays down the bare minimum API we're re-adding.

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

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.

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