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