ui.h

Go to the documentation of this file.

// 6 april 2015
 
// TODO add a uiVerifyControlType() function that can be used by control implementations to verify controls
 
// TODOs
// - make getters that return whether something exists accept a NULL pointer to discard the value (and thus only return that the thing exists?)
// - const-correct everything
// - normalize documentation between typedefs and structs
 
#ifndef __LIBUI_UI_H__
#define __LIBUI_UI_H__
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
// this macro is generated by cmake
#ifdef libui_EXPORTS
#ifdef _WIN32
#define _UI_EXTERN __declspec(dllexport) extern
#else
#define _UI_EXTERN __attribute__((visibility("default"))) extern
#endif
#else
// TODO add __declspec(dllimport) on windows, but only if not static
#define _UI_EXTERN extern
#endif
 
// C++ is really really really really really really dumb about enums, so screw that and just make them anonymous
// This has the advantage of being ABI-able should we ever need an ABI...
#define _UI_ENUM(s) typedef unsigned int s; enum
 
// This constant is provided because M_PI is nonstandard.
// This comes from Go's math.Pi, which in turn comes from http://oeis.org/A000796.
#define uiPi 3.14159265358979323846264338327950288419716939937510582097494459
 
// TODO uiBool?
 
// uiForEach represents the return value from one of libui's various ForEach functions.
_UI_ENUM(uiForEach) {
    uiForEachContinue,
    uiForEachStop,
};
 
typedef struct uiInitOptions uiInitOptions;
 
struct uiInitOptions {
    size_t Size;
};
 
_UI_EXTERN const char *uiInit(uiInitOptions *options);
_UI_EXTERN void uiUninit(void);
_UI_EXTERN void uiFreeInitError(const char *err);
 
_UI_EXTERN void uiMain(void);
_UI_EXTERN void uiMainSteps(void);
_UI_EXTERN int uiMainStep(int wait);
_UI_EXTERN void uiQuit(void);
 
_UI_EXTERN void uiQueueMain(void (*f)(void *data), void *data);
 
// TODO standardize the looping behavior return type, either with some enum or something, and the test expressions throughout the code
// TODO figure out what to do about looping and the exact point that the timer is rescheduled so we can document it; see https://github.com/andlabs/libui/pull/277
// TODO (also in the above link) document that this cannot be called from any thread, unlike uiQueueMain()
// TODO document that the minimum exact timing, either accuracy (timer burst, etc.) or granularity (15ms on Windows, etc.), is OS-defined
// TODO also figure out how long until the initial tick is registered on all platforms to document
// TODO also add a comment about how useful this could be in bindings, depending on the language being bound to
_UI_EXTERN void uiTimer(int milliseconds, int (*f)(void *data), void *data);
 
_UI_EXTERN void uiOnShouldQuit(int (*f)(void *data), void *data);
 
 
_UI_EXTERN void uiFreeText(char *text);
 
 
typedef struct uiControl uiControl;
struct uiControl {
    uint32_t Signature;
    uint32_t OSSignature;
    uint32_t TypeSignature;
    void (*Destroy)(uiControl *);
    uintptr_t (*Handle)(uiControl *);
    uiControl *(*Parent)(uiControl *);
    void (*SetParent)(uiControl *, uiControl *);
    int (*Toplevel)(uiControl *);
    int (*Visible)(uiControl *);
    void (*Show)(uiControl *);
    void (*Hide)(uiControl *);
    int (*Enabled)(uiControl *);
    void (*Enable)(uiControl *);
    void (*Disable)(uiControl *);
};
// TOOD add argument names to all arguments
#define uiControl(this) ((uiControl *) (this))
 
_UI_EXTERN void uiControlDestroy(uiControl *c);
 
_UI_EXTERN uintptr_t uiControlHandle(uiControl *c);
 
_UI_EXTERN uiControl *uiControlParent(uiControl *c);
 
_UI_EXTERN void uiControlSetParent(uiControl *c, uiControl *parent);
 
_UI_EXTERN int uiControlToplevel(uiControl *c);
 
_UI_EXTERN int uiControlVisible(uiControl *c);
 
_UI_EXTERN void uiControlShow(uiControl *c);
 
_UI_EXTERN void uiControlHide(uiControl *c);
 
_UI_EXTERN int uiControlEnabled(uiControl *c);
 
_UI_EXTERN void uiControlEnable(uiControl *c);
 
_UI_EXTERN void uiControlDisable(uiControl *c);
 
_UI_EXTERN uiControl *uiAllocControl(size_t n, uint32_t OSsig, uint32_t typesig, const char *typenamestr);
 
_UI_EXTERN void uiFreeControl(uiControl *c);
 
_UI_EXTERN void uiControlVerifySetParent(uiControl *c, uiControl *parent);
 
_UI_EXTERN int uiControlEnabledToUser(uiControl *c);
 
// TODO Move this to private API? According to old/new.md this should be used by toplevel controls.
_UI_EXTERN void uiUserBugCannotSetParentOnToplevel(const char *type);
 
 
typedef struct uiWindow uiWindow;
#define uiWindow(this) ((uiWindow *) (this))
 
_UI_EXTERN char *uiWindowTitle(uiWindow *w);
 
_UI_EXTERN void uiWindowSetTitle(uiWindow *w, const char *title);
 
_UI_EXTERN void uiWindowPosition(uiWindow *w, int *x, int *y);
 
_UI_EXTERN void uiWindowSetPosition(uiWindow *w, int x, int y);
 
_UI_EXTERN void uiWindowOnPositionChanged(uiWindow *w,
    void (*f)(uiWindow *sender, void *senderData), void *data);
 
_UI_EXTERN void uiWindowContentSize(uiWindow *w, int *width, int *height);
 
_UI_EXTERN void uiWindowSetContentSize(uiWindow *w, int width, int height);
 
_UI_EXTERN int uiWindowFullscreen(uiWindow *w);
 
_UI_EXTERN void uiWindowSetFullscreen(uiWindow *w, int fullscreen);
 
_UI_EXTERN void uiWindowOnContentSizeChanged(uiWindow *w,
    void (*f)(uiWindow *sender, void *senderData), void *data);
 
_UI_EXTERN void uiWindowOnClosing(uiWindow *w,
    int (*f)(uiWindow *sender, void *senderData), void *data);
 
_UI_EXTERN void uiWindowOnFocusChanged(uiWindow *w,
    void (*f)(uiWindow *sender, void *senderData), void *data);
 
_UI_EXTERN int uiWindowFocused(uiWindow *w);
 
_UI_EXTERN int uiWindowBorderless(uiWindow *w);
 
_UI_EXTERN void uiWindowSetBorderless(uiWindow *w, int borderless);
 
_UI_EXTERN void uiWindowSetChild(uiWindow *w, uiControl *child);
 
_UI_EXTERN int uiWindowMargined(uiWindow *w);
 
_UI_EXTERN void uiWindowSetMargined(uiWindow *w, int margined);
 
_UI_EXTERN int uiWindowResizeable(uiWindow *w);
 
_UI_EXTERN void uiWindowSetResizeable(uiWindow *w, int resizeable);
 
_UI_EXTERN uiWindow *uiNewWindow(const char *title, int width, int height, int hasMenubar);
 
 
typedef struct uiButton uiButton;
#define uiButton(this) ((uiButton *) (this))
 
_UI_EXTERN char *uiButtonText(uiButton *b);
 
_UI_EXTERN void uiButtonSetText(uiButton *b, const char *text);
 
_UI_EXTERN void uiButtonOnClicked(uiButton *b,
    void (*f)(uiButton *sender, void *senderData), void *data);
 
_UI_EXTERN uiButton *uiNewButton(const char *text);
 
 
typedef struct uiBox uiBox;
#define uiBox(this) ((uiBox *) (this))
 
_UI_EXTERN void uiBoxAppend(uiBox *b, uiControl *child, int stretchy);
 
_UI_EXTERN int uiBoxNumChildren(uiBox *b);
 
_UI_EXTERN void uiBoxDelete(uiBox *b, int index);
 
_UI_EXTERN int uiBoxPadded(uiBox *b);
 
_UI_EXTERN void uiBoxSetPadded(uiBox *b, int padded);
 
_UI_EXTERN uiBox *uiNewHorizontalBox(void);
 
_UI_EXTERN uiBox *uiNewVerticalBox(void);
 
 
typedef struct uiCheckbox uiCheckbox;
#define uiCheckbox(this) ((uiCheckbox *) (this))
 
_UI_EXTERN char *uiCheckboxText(uiCheckbox *c);
 
_UI_EXTERN void uiCheckboxSetText(uiCheckbox *c, const char *text);
 
_UI_EXTERN void uiCheckboxOnToggled(uiCheckbox *c,
    void (*f)(uiCheckbox *sender, void *senderData), void *data);
 
_UI_EXTERN int uiCheckboxChecked(uiCheckbox *c);
 
_UI_EXTERN void uiCheckboxSetChecked(uiCheckbox *c, int checked);
 
_UI_EXTERN uiCheckbox *uiNewCheckbox(const char *text);
 
 
typedef struct uiEntry uiEntry;
#define uiEntry(this) ((uiEntry *) (this))
 
_UI_EXTERN char *uiEntryText(uiEntry *e);
 
_UI_EXTERN void uiEntrySetText(uiEntry *e, const char *text);
 
_UI_EXTERN void uiEntryOnChanged(uiEntry *e,
    void (*f)(uiEntry *sender, void *senderData), void *data);
 
_UI_EXTERN int uiEntryReadOnly(uiEntry *e);
 
_UI_EXTERN void uiEntrySetReadOnly(uiEntry *e, int readonly);
 
_UI_EXTERN uiEntry *uiNewEntry(void);
 
_UI_EXTERN uiEntry *uiNewPasswordEntry(void);
 
_UI_EXTERN uiEntry *uiNewSearchEntry(void);
 
 
typedef struct uiLabel uiLabel;
#define uiLabel(this) ((uiLabel *) (this))
 
_UI_EXTERN char *uiLabelText(uiLabel *l);
 
_UI_EXTERN void uiLabelSetText(uiLabel *l, const char *text);
 
_UI_EXTERN uiLabel *uiNewLabel(const char *text);
 
 
typedef struct uiTab uiTab;
#define uiTab(this) ((uiTab *) (this))
 
_UI_EXTERN int uiTabSelected(uiTab *t);
 
_UI_EXTERN void uiTabSetSelected(uiTab *t, int index);
 
_UI_EXTERN void uiTabOnSelected(uiTab *t,
        void (*f)(uiTab *sender, void *senderData), void *data);
 
_UI_EXTERN void uiTabAppend(uiTab *t, const char *name, uiControl *c);
 
_UI_EXTERN void uiTabInsertAt(uiTab *t, const char *name, int index, uiControl *c);
 
_UI_EXTERN void uiTabDelete(uiTab *t, int index);
 
_UI_EXTERN int uiTabNumPages(uiTab *t);
 
_UI_EXTERN int uiTabMargined(uiTab *t, int index);
 
_UI_EXTERN void uiTabSetMargined(uiTab *t, int index, int margined);
 
_UI_EXTERN uiTab *uiNewTab(void);
 
 
typedef struct uiGroup uiGroup;
#define uiGroup(this) ((uiGroup *) (this))
 
_UI_EXTERN char *uiGroupTitle(uiGroup *g);
 
_UI_EXTERN void uiGroupSetTitle(uiGroup *g, const char *title);
 
_UI_EXTERN void uiGroupSetChild(uiGroup *g, uiControl *c);
 
_UI_EXTERN int uiGroupMargined(uiGroup *g);
 
_UI_EXTERN void uiGroupSetMargined(uiGroup *g, int margined);
 
_UI_EXTERN uiGroup *uiNewGroup(const char *title);
 
 
typedef struct uiSpinbox uiSpinbox;
#define uiSpinbox(this) ((uiSpinbox *) (this))
 
_UI_EXTERN int uiSpinboxValue(uiSpinbox *s);
 
_UI_EXTERN void uiSpinboxSetValue(uiSpinbox *s, int value);
 
_UI_EXTERN void uiSpinboxOnChanged(uiSpinbox *s,
    void (*f)(uiSpinbox *sender, void *senderData), void *data);
 
_UI_EXTERN uiSpinbox *uiNewSpinbox(int min, int max);
 
 
typedef struct uiSlider uiSlider;
#define uiSlider(this) ((uiSlider *) (this))
 
_UI_EXTERN int uiSliderValue(uiSlider *s);
 
_UI_EXTERN void uiSliderSetValue(uiSlider *s, int value);
 
_UI_EXTERN int uiSliderHasToolTip(uiSlider *s);
 
_UI_EXTERN void uiSliderSetHasToolTip(uiSlider *s, int hasToolTip);
 
_UI_EXTERN void uiSliderOnChanged(uiSlider *s,
    void (*f)(uiSlider *sender, void *senderData), void *data);
 
_UI_EXTERN void uiSliderOnReleased(uiSlider *s,
    void (*f)(uiSlider *sender, void *senderData), void *data);
 
_UI_EXTERN void uiSliderSetRange(uiSlider *s, int min, int max);
 
_UI_EXTERN uiSlider *uiNewSlider(int min, int max);
 
 
typedef struct uiProgressBar uiProgressBar;
#define uiProgressBar(this) ((uiProgressBar *) (this))
 
_UI_EXTERN int uiProgressBarValue(uiProgressBar *p);
 
_UI_EXTERN void uiProgressBarSetValue(uiProgressBar *p, int n);
 
_UI_EXTERN uiProgressBar *uiNewProgressBar(void);
 
 
typedef struct uiSeparator uiSeparator;
#define uiSeparator(this) ((uiSeparator *) (this))
 
_UI_EXTERN uiSeparator *uiNewHorizontalSeparator(void);
 
_UI_EXTERN uiSeparator *uiNewVerticalSeparator(void);
 
 
typedef struct uiCombobox uiCombobox;
#define uiCombobox(this) ((uiCombobox *) (this))
 
_UI_EXTERN void uiComboboxAppend(uiCombobox *c, const char *text);
 
_UI_EXTERN void uiComboboxInsertAt(uiCombobox *c, int index, const char *text);
 
_UI_EXTERN void uiComboboxDelete(uiCombobox *c, int index);
 
_UI_EXTERN void uiComboboxClear(uiCombobox *c);
 
_UI_EXTERN int uiComboboxNumItems(uiCombobox *c);
 
_UI_EXTERN int uiComboboxSelected(uiCombobox *c);
 
_UI_EXTERN void uiComboboxSetSelected(uiCombobox *c, int index);
 
_UI_EXTERN void uiComboboxOnSelected(uiCombobox *c,
    void (*f)(uiCombobox *sender, void *senderData), void *data);
 
_UI_EXTERN uiCombobox *uiNewCombobox(void);
 
 
typedef struct uiEditableCombobox uiEditableCombobox;
#define uiEditableCombobox(this) ((uiEditableCombobox *) (this))
 
_UI_EXTERN void uiEditableComboboxAppend(uiEditableCombobox *c, const char *text);
 
_UI_EXTERN char *uiEditableComboboxText(uiEditableCombobox *c);
 
_UI_EXTERN void uiEditableComboboxSetText(uiEditableCombobox *c, const char *text);
 
// TODO what do we call a function that sets the currently selected item and fills the text field with it?
// editable comboboxes have no consistent concept of selected item
 
_UI_EXTERN void uiEditableComboboxOnChanged(uiEditableCombobox *c,
    void (*f)(uiEditableCombobox *sender, void *senderData), void *data);
 
_UI_EXTERN uiEditableCombobox *uiNewEditableCombobox(void);
 
 
typedef struct uiRadioButtons uiRadioButtons;
#define uiRadioButtons(this) ((uiRadioButtons *) (this))
 
_UI_EXTERN void uiRadioButtonsAppend(uiRadioButtons *r, const char *text);
 
_UI_EXTERN int uiRadioButtonsSelected(uiRadioButtons *r);
 
_UI_EXTERN void uiRadioButtonsSetSelected(uiRadioButtons *r, int index);
 
_UI_EXTERN void uiRadioButtonsOnSelected(uiRadioButtons *r,
    void (*f)(uiRadioButtons *sender, void *senderData), void *data);
 
_UI_EXTERN uiRadioButtons *uiNewRadioButtons(void);
 
struct tm;
typedef struct uiDateTimePicker uiDateTimePicker;
#define uiDateTimePicker(this) ((uiDateTimePicker *) (this))
 
_UI_EXTERN void uiDateTimePickerTime(uiDateTimePicker *d, struct tm *time);
 
_UI_EXTERN void uiDateTimePickerSetTime(uiDateTimePicker *d, const struct tm *time);
 
_UI_EXTERN void uiDateTimePickerOnChanged(uiDateTimePicker *d,
    void (*f)(uiDateTimePicker *sender, void *senderData), void *data);
 
_UI_EXTERN uiDateTimePicker *uiNewDateTimePicker(void);
 
_UI_EXTERN uiDateTimePicker *uiNewDatePicker(void);
 
_UI_EXTERN uiDateTimePicker *uiNewTimePicker(void);
 
 
typedef struct uiMultilineEntry uiMultilineEntry;
#define uiMultilineEntry(this) ((uiMultilineEntry *) (this))
 
_UI_EXTERN char *uiMultilineEntryText(uiMultilineEntry *e);
 
_UI_EXTERN void uiMultilineEntrySetText(uiMultilineEntry *e, const char *text);
 
_UI_EXTERN void uiMultilineEntryAppend(uiMultilineEntry *e, const char *text);
 
_UI_EXTERN void uiMultilineEntryOnChanged(uiMultilineEntry *e,
    void (*f)(uiMultilineEntry *sender, void *senderData), void *data);
 
_UI_EXTERN int uiMultilineEntryReadOnly(uiMultilineEntry *e);
 
_UI_EXTERN void uiMultilineEntrySetReadOnly(uiMultilineEntry *e, int readonly);
 
_UI_EXTERN uiMultilineEntry *uiNewMultilineEntry(void);
 
_UI_EXTERN uiMultilineEntry *uiNewNonWrappingMultilineEntry(void);
 
 
typedef struct uiMenuItem uiMenuItem;
#define uiMenuItem(this) ((uiMenuItem *) (this))
 
_UI_EXTERN void uiMenuItemEnable(uiMenuItem *m);
 
_UI_EXTERN void uiMenuItemDisable(uiMenuItem *m);
 
_UI_EXTERN void uiMenuItemOnClicked(uiMenuItem *m,
    void (*f)(uiMenuItem *sender, uiWindow *window, void *senderData), void *data);
 
_UI_EXTERN int uiMenuItemChecked(uiMenuItem *m);
 
_UI_EXTERN void uiMenuItemSetChecked(uiMenuItem *m, int checked);
 
typedef struct uiMenu uiMenu;
#define uiMenu(this) ((uiMenu *) (this))
 
_UI_EXTERN uiMenuItem *uiMenuAppendItem(uiMenu *m, const char *name);
 
_UI_EXTERN uiMenuItem *uiMenuAppendCheckItem(uiMenu *m, const char *name);
 
_UI_EXTERN uiMenuItem *uiMenuAppendQuitItem(uiMenu *m);
 
_UI_EXTERN uiMenuItem *uiMenuAppendPreferencesItem(uiMenu *m);
 
_UI_EXTERN uiMenuItem *uiMenuAppendAboutItem(uiMenu *m);
 
_UI_EXTERN void uiMenuAppendSeparator(uiMenu *m);
 
_UI_EXTERN uiMenu *uiNewMenu(const char *name);
 
 
_UI_EXTERN char *uiOpenFile(uiWindow *parent);
 
_UI_EXTERN char *uiOpenFolder(uiWindow *parent);
 
_UI_EXTERN char *uiSaveFile(uiWindow *parent);
 
_UI_EXTERN void uiMsgBox(uiWindow *parent, const char *title, const char *description);
 
_UI_EXTERN void uiMsgBoxError(uiWindow *parent, const char *title, const char *description);
 
typedef struct uiArea uiArea;
typedef struct uiAreaHandler uiAreaHandler;
typedef struct uiAreaDrawParams uiAreaDrawParams;
typedef struct uiAreaMouseEvent uiAreaMouseEvent;
typedef struct uiAreaKeyEvent uiAreaKeyEvent;
 
typedef struct uiDrawContext uiDrawContext;
 
struct uiAreaHandler {
    void (*Draw)(uiAreaHandler *, uiArea *, uiAreaDrawParams *);
    // TODO document that resizes cause a full redraw for non-scrolling areas; implementation-defined for scrolling areas
    void (*MouseEvent)(uiAreaHandler *, uiArea *, uiAreaMouseEvent *);
    // TODO document that on first show if the mouse is already in the uiArea then one gets sent with left=0
    // TODO what about when the area is hidden and then shown again?
    void (*MouseCrossed)(uiAreaHandler *, uiArea *, int left);
    void (*DragBroken)(uiAreaHandler *, uiArea *);
    int (*KeyEvent)(uiAreaHandler *, uiArea *, uiAreaKeyEvent *);
};
 
// TODO RTL layouts?
// TODO reconcile edge and corner naming
_UI_ENUM(uiWindowResizeEdge) {
    uiWindowResizeEdgeLeft,
    uiWindowResizeEdgeTop,
    uiWindowResizeEdgeRight,
    uiWindowResizeEdgeBottom,
    uiWindowResizeEdgeTopLeft,
    uiWindowResizeEdgeTopRight,
    uiWindowResizeEdgeBottomLeft,
    uiWindowResizeEdgeBottomRight,
    // TODO have one for keyboard resizes?
    // TODO GDK doesn't seem to have any others, including for keyboards...
    // TODO way to bring up the system menu instead?
};
 
#define uiArea(this) ((uiArea *) (this))
// TODO give a better name
// TODO document the types of width and height
_UI_EXTERN void uiAreaSetSize(uiArea *a, int width, int height);
// TODO uiAreaQueueRedraw()
_UI_EXTERN void uiAreaQueueRedrawAll(uiArea *a);
_UI_EXTERN void uiAreaScrollTo(uiArea *a, double x, double y, double width, double height);
// TODO document these can only be called within Mouse() handlers
// TODO should these be allowed on scrolling areas?
// TODO decide which mouse events should be accepted; Down is the only one guaranteed to work right now
// TODO what happens to events after calling this up to and including the next mouse up?
// TODO release capture?
_UI_EXTERN void uiAreaBeginUserWindowMove(uiArea *a);
_UI_EXTERN void uiAreaBeginUserWindowResize(uiArea *a, uiWindowResizeEdge edge);
_UI_EXTERN uiArea *uiNewArea(uiAreaHandler *ah);
_UI_EXTERN uiArea *uiNewScrollingArea(uiAreaHandler *ah, int width, int height);
 
struct uiAreaDrawParams {
    uiDrawContext *Context;
 
    // TODO document that this is only defined for nonscrolling areas
    double AreaWidth;
    double AreaHeight;
 
    double ClipX;
    double ClipY;
    double ClipWidth;
    double ClipHeight;
};
 
typedef struct uiDrawPath uiDrawPath;
typedef struct uiDrawBrush uiDrawBrush;
typedef struct uiDrawStrokeParams uiDrawStrokeParams;
typedef struct uiDrawMatrix uiDrawMatrix;
 
typedef struct uiDrawBrushGradientStop uiDrawBrushGradientStop;
 
_UI_ENUM(uiDrawBrushType) {
    uiDrawBrushTypeSolid,
    uiDrawBrushTypeLinearGradient,
    uiDrawBrushTypeRadialGradient,
    uiDrawBrushTypeImage,
};
 
_UI_ENUM(uiDrawLineCap) {
    uiDrawLineCapFlat,
    uiDrawLineCapRound,
    uiDrawLineCapSquare,
};
 
_UI_ENUM(uiDrawLineJoin) {
    uiDrawLineJoinMiter,
    uiDrawLineJoinRound,
    uiDrawLineJoinBevel,
};
 
// this is the default for botoh cairo and Direct2D (in the latter case, from the C++ helper functions)
// Core Graphics doesn't explicitly specify a default, but NSBezierPath allows you to choose one, and this is the initial value
// so we're good to use it too!
#define uiDrawDefaultMiterLimit 10.0
 
_UI_ENUM(uiDrawFillMode) {
    uiDrawFillModeWinding,
    uiDrawFillModeAlternate,
};
 
struct uiDrawMatrix {
    double M11;
    double M12;
    double M21;
    double M22;
    double M31;
    double M32;
};
 
struct uiDrawBrush {
    uiDrawBrushType Type;
 
    // solid brushes
    double R;
    double G;
    double B;
    double A;
 
    // gradient brushes
    double X0;      // linear: start X, radial: start X
    double Y0;      // linear: start Y, radial: start Y
    double X1;      // linear: end X, radial: outer circle center X
    double Y1;      // linear: end Y, radial: outer circle center Y
    double OuterRadius;     // radial gradients only
    uiDrawBrushGradientStop *Stops;
    size_t NumStops;
    // TODO extend mode
    // cairo: none, repeat, reflect, pad; no individual control
    // Direct2D: repeat, reflect, pad; no individual control
    // Core Graphics: none, pad; before and after individually
    // TODO cairo documentation is inconsistent about pad
 
    // TODO images
 
    // TODO transforms
};
 
struct uiDrawBrushGradientStop {
    double Pos;
    double R;
    double G;
    double B;
    double A;
};
 
struct uiDrawStrokeParams {
    uiDrawLineCap Cap;
    uiDrawLineJoin Join;
    // TODO what if this is 0? on windows there will be a crash with dashing
    double Thickness;
    double MiterLimit;
    double *Dashes;
    // TOOD what if this is 1 on Direct2D?
    // TODO what if a dash is 0 on Cairo or Quartz?
    size_t NumDashes;
    double DashPhase;
};
 
_UI_EXTERN uiDrawPath *uiDrawNewPath(uiDrawFillMode fillMode);
_UI_EXTERN void uiDrawFreePath(uiDrawPath *p);
 
_UI_EXTERN void uiDrawPathNewFigure(uiDrawPath *p, double x, double y);
_UI_EXTERN void uiDrawPathNewFigureWithArc(uiDrawPath *p, double xCenter, double yCenter, double radius, double startAngle, double sweep, int negative);
_UI_EXTERN void uiDrawPathLineTo(uiDrawPath *p, double x, double y);
// notes: angles are both relative to 0 and go counterclockwise
// TODO is the initial line segment on cairo and OS X a proper join?
// TODO what if sweep < 0?
_UI_EXTERN void uiDrawPathArcTo(uiDrawPath *p, double xCenter, double yCenter, double radius, double startAngle, double sweep, int negative);
_UI_EXTERN void uiDrawPathBezierTo(uiDrawPath *p, double c1x, double c1y, double c2x, double c2y, double endX, double endY);
// TODO quadratic bezier
_UI_EXTERN void uiDrawPathCloseFigure(uiDrawPath *p);
 
// TODO effect of these when a figure is already started
_UI_EXTERN void uiDrawPathAddRectangle(uiDrawPath *p, double x, double y, double width, double height);
 
_UI_EXTERN int uiDrawPathEnded(uiDrawPath *p);
_UI_EXTERN void uiDrawPathEnd(uiDrawPath *p);
 
_UI_EXTERN void uiDrawStroke(uiDrawContext *c, uiDrawPath *path, uiDrawBrush *b, uiDrawStrokeParams *p);
_UI_EXTERN void uiDrawFill(uiDrawContext *c, uiDrawPath *path, uiDrawBrush *b);
 
// TODO primitives:
// - rounded rectangles
// - elliptical arcs
// - quadratic bezier curves
 
_UI_EXTERN void uiDrawMatrixSetIdentity(uiDrawMatrix *m);
_UI_EXTERN void uiDrawMatrixTranslate(uiDrawMatrix *m, double x, double y);
_UI_EXTERN void uiDrawMatrixScale(uiDrawMatrix *m, double xCenter, double yCenter, double x, double y);
_UI_EXTERN void uiDrawMatrixRotate(uiDrawMatrix *m, double x, double y, double amount);
_UI_EXTERN void uiDrawMatrixSkew(uiDrawMatrix *m, double x, double y, double xamount, double yamount);
_UI_EXTERN void uiDrawMatrixMultiply(uiDrawMatrix *dest, uiDrawMatrix *src);
_UI_EXTERN int uiDrawMatrixInvertible(uiDrawMatrix *m);
_UI_EXTERN int uiDrawMatrixInvert(uiDrawMatrix *m);
_UI_EXTERN void uiDrawMatrixTransformPoint(uiDrawMatrix *m, double *x, double *y);
_UI_EXTERN void uiDrawMatrixTransformSize(uiDrawMatrix *m, double *x, double *y);
 
_UI_EXTERN void uiDrawTransform(uiDrawContext *c, uiDrawMatrix *m);
 
// TODO add a uiDrawPathStrokeToFill() or something like that
_UI_EXTERN void uiDrawClip(uiDrawContext *c, uiDrawPath *path);
 
_UI_EXTERN void uiDrawSave(uiDrawContext *c);
_UI_EXTERN void uiDrawRestore(uiDrawContext *c);
 
// uiAttribute stores information about an attribute in a
// uiAttributedString.
//
// You do not create uiAttributes directly; instead, you create a
// uiAttribute of a given type using the specialized constructor
// functions. For every Unicode codepoint in the uiAttributedString,
// at most one value of each attribute type can be applied.
//
// uiAttributes are immutable and the uiAttributedString takes
// ownership of the uiAttribute object once assigned, copying its
// contents as necessary.
// TODO define whether all this, for both uiTableValue and uiAttribute, is undefined behavior or a caught error
typedef struct uiAttribute uiAttribute;
 
// @role uiAttribute destructor
// uiFreeAttribute() frees a uiAttribute. You generally do not need to
// call this yourself, as uiAttributedString does this for you. In fact,
// it is an error to call this function on a uiAttribute that has been
// given to a uiAttributedString. You can call this, however, if you
// created a uiAttribute that you aren't going to use later.
_UI_EXTERN void uiFreeAttribute(uiAttribute *a);
 
// uiAttributeType holds the possible uiAttribute types that may be
// returned by uiAttributeGetType(). Refer to the documentation for
// each type's constructor function for details on each type.
_UI_ENUM(uiAttributeType) {
    uiAttributeTypeFamily,
    uiAttributeTypeSize,
    uiAttributeTypeWeight,
    uiAttributeTypeItalic,
    uiAttributeTypeStretch,
    uiAttributeTypeColor,
    uiAttributeTypeBackground,
    uiAttributeTypeUnderline,
    uiAttributeTypeUnderlineColor,
    uiAttributeTypeFeatures,
};
 
// uiAttributeGetType() returns the type of a.
// TODO I don't like this name
_UI_EXTERN uiAttributeType uiAttributeGetType(const uiAttribute *a);
 
// uiNewFamilyAttribute() creates a new uiAttribute that changes the
// font family of the text it is applied to. family is copied; you do not
// need to keep it alive after uiNewFamilyAttribute() returns. Font
// family names are case-insensitive.
_UI_EXTERN uiAttribute *uiNewFamilyAttribute(const char *family);
 
// uiAttributeFamily() returns the font family stored in a. The
// returned string is owned by a. It is an error to call this on a
// uiAttribute that does not hold a font family.
_UI_EXTERN const char *uiAttributeFamily(const uiAttribute *a);
 
// uiNewSizeAttribute() creates a new uiAttribute that changes the
// size of the text it is applied to, in typographical points.
_UI_EXTERN uiAttribute *uiNewSizeAttribute(double size);
 
// uiAttributeSize() returns the font size stored in a. It is an error to
// call this on a uiAttribute that does not hold a font size.
_UI_EXTERN double uiAttributeSize(const uiAttribute *a);
 
// uiTextWeight represents possible text weights. These roughly
// map to the OS/2 text weight field of TrueType and OpenType
// fonts, or to CSS weight numbers. The named constants are
// nominal values; the actual values may vary by font and by OS,
// though this isn't particularly likely. Any value between
// uiTextWeightMinimum and uiTextWeightMaximum, inclusive,
// is allowed.
//
// Note that due to restrictions in early versions of Windows, some
// fonts have "special" weights be exposed in many programs as
// separate font families. This is perhaps most notable with
// Arial Black. libui does not do this, even on Windows (because the
// DirectWrite API libui uses on Windows does not do this); to
// specify Arial Black, use family Arial and weight uiTextWeightBlack.
_UI_ENUM(uiTextWeight) {
    uiTextWeightMinimum = 0,
    uiTextWeightThin = 100,
    uiTextWeightUltraLight = 200,
    uiTextWeightLight = 300,
    uiTextWeightBook = 350,
    uiTextWeightNormal = 400,
    uiTextWeightMedium = 500,
    uiTextWeightSemiBold = 600,
    uiTextWeightBold = 700,
    uiTextWeightUltraBold = 800,
    uiTextWeightHeavy = 900,
    uiTextWeightUltraHeavy = 950,
    uiTextWeightMaximum = 1000,
};
 
// uiNewWeightAttribute() creates a new uiAttribute that changes the
// weight of the text it is applied to. It is an error to specify a weight
// outside the range [uiTextWeightMinimum,
// uiTextWeightMaximum].
_UI_EXTERN uiAttribute *uiNewWeightAttribute(uiTextWeight weight);
 
// uiAttributeWeight() returns the font weight stored in a. It is an error
// to call this on a uiAttribute that does not hold a font weight.
_UI_EXTERN uiTextWeight uiAttributeWeight(const uiAttribute *a);
 
// uiTextItalic represents possible italic modes for a font. Italic
// represents "true" italics where the slanted glyphs have custom
// shapes, whereas oblique represents italics that are merely slanted
// versions of the normal glyphs. Most fonts usually have one or the
// other.
_UI_ENUM(uiTextItalic) {
    uiTextItalicNormal,
    uiTextItalicOblique,
    uiTextItalicItalic,
};
 
// uiNewItalicAttribute() creates a new uiAttribute that changes the
// italic mode of the text it is applied to. It is an error to specify an
// italic mode not specified in uiTextItalic.
_UI_EXTERN uiAttribute *uiNewItalicAttribute(uiTextItalic italic);
 
// uiAttributeItalic() returns the font italic mode stored in a. It is an
// error to call this on a uiAttribute that does not hold a font italic
// mode.
_UI_EXTERN uiTextItalic uiAttributeItalic(const uiAttribute *a);
 
// uiTextStretch represents possible stretches (also called "widths")
// of a font.
//
// Note that due to restrictions in early versions of Windows, some
// fonts have "special" stretches be exposed in many programs as
// separate font families. This is perhaps most notable with
// Arial Condensed. libui does not do this, even on Windows (because
// the DirectWrite API libui uses on Windows does not do this); to
// specify Arial Condensed, use family Arial and stretch
// uiTextStretchCondensed.
_UI_ENUM(uiTextStretch) {
    uiTextStretchUltraCondensed,
    uiTextStretchExtraCondensed,
    uiTextStretchCondensed,
    uiTextStretchSemiCondensed,
    uiTextStretchNormal,
    uiTextStretchSemiExpanded,
    uiTextStretchExpanded,
    uiTextStretchExtraExpanded,
    uiTextStretchUltraExpanded,
};
 
// uiNewStretchAttribute() creates a new uiAttribute that changes the
// stretch of the text it is applied to. It is an error to specify a strech
// not specified in uiTextStretch.
_UI_EXTERN uiAttribute *uiNewStretchAttribute(uiTextStretch stretch);
 
// uiAttributeStretch() returns the font stretch stored in a. It is an
// error to call this on a uiAttribute that does not hold a font stretch.
_UI_EXTERN uiTextStretch uiAttributeStretch(const uiAttribute *a);
 
// uiNewColorAttribute() creates a new uiAttribute that changes the
// color of the text it is applied to. It is an error to specify an invalid
// color.
_UI_EXTERN uiAttribute *uiNewColorAttribute(double r, double g, double b, double a);
 
// uiAttributeColor() returns the text color stored in a. It is an
// error to call this on a uiAttribute that does not hold a text color.
_UI_EXTERN void uiAttributeColor(const uiAttribute *a, double *r, double *g, double *b, double *alpha);
 
// uiNewBackgroundAttribute() creates a new uiAttribute that
// changes the background color of the text it is applied to. It is an
// error to specify an invalid color.
_UI_EXTERN uiAttribute *uiNewBackgroundAttribute(double r, double g, double b, double a);
 
// TODO reuse uiAttributeColor() for background colors, or make a new function...
 
// uiUnderline specifies a type of underline to use on text.
_UI_ENUM(uiUnderline) {
    uiUnderlineNone,
    uiUnderlineSingle,
    uiUnderlineDouble,
    uiUnderlineSuggestion,      // wavy or dotted underlines used for spelling/grammar checkers
};
 
// uiNewUnderlineAttribute() creates a new uiAttribute that changes
// the type of underline on the text it is applied to. It is an error to
// specify an underline type not specified in uiUnderline.
_UI_EXTERN uiAttribute *uiNewUnderlineAttribute(uiUnderline u);
 
// uiAttributeUnderline() returns the underline type stored in a. It is
// an error to call this on a uiAttribute that does not hold an underline
// style.
_UI_EXTERN uiUnderline uiAttributeUnderline(const uiAttribute *a);
 
// uiUnderlineColor specifies the color of any underline on the text it
// is applied to, regardless of the type of underline. In addition to
// being able to specify a custom color, you can explicitly specify
// platform-specific colors for suggestion underlines; to use them
// correctly, pair them with uiUnderlineSuggestion (though they can
// be used on other types of underline as well).
//
// If an underline type is applied but no underline color is
// specified, the text color is used instead. If an underline color
// is specified without an underline type, the underline color
// attribute is ignored, but not removed from the uiAttributedString.
_UI_ENUM(uiUnderlineColor) {
    uiUnderlineColorCustom,
    uiUnderlineColorSpelling,
    uiUnderlineColorGrammar,
    uiUnderlineColorAuxiliary,      // for instance, the color used by smart replacements on macOS or in Microsoft Office
};
 
// uiNewUnderlineColorAttribute() creates a new uiAttribute that
// changes the color of the underline on the text it is applied to.
// It is an error to specify an underline color not specified in
// uiUnderlineColor.
//
// If the specified color type is uiUnderlineColorCustom, it is an
// error to specify an invalid color value. Otherwise, the color values
// are ignored and should be specified as zero.
_UI_EXTERN uiAttribute *uiNewUnderlineColorAttribute(uiUnderlineColor u, double r, double g, double b, double a);
 
// uiAttributeUnderlineColor() returns the underline color stored in
// a. It is an error to call this on a uiAttribute that does not hold an
// underline color.
_UI_EXTERN void uiAttributeUnderlineColor(const uiAttribute *a, uiUnderlineColor *u, double *r, double *g, double *b, double *alpha);
 
// uiOpenTypeFeatures represents a set of OpenType feature
// tag-value pairs, for applying OpenType features to text.
// OpenType feature tags are four-character codes defined by
// OpenType that cover things from design features like small
// caps and swashes to language-specific glyph shapes and
// beyond. Each tag may only appear once in any given
// uiOpenTypeFeatures instance. Each value is a 32-bit integer,
// often used as a Boolean flag, but sometimes as an index to choose
// a glyph shape to use.
//
// If a font does not support a certain feature, that feature will be
// ignored. (TODO verify this on all OSs)
//
// See the OpenType specification at
// https://www.microsoft.com/typography/otspec/featuretags.htm
// for the complete list of available features, information on specific
// features, and how to use them.
// TODO invalid features
typedef struct uiOpenTypeFeatures uiOpenTypeFeatures;
 
// uiOpenTypeFeaturesForEachFunc is the type of the function
// invoked by uiOpenTypeFeaturesForEach() for every OpenType
// feature in otf. Refer to that function's documentation for more
// details.
typedef uiForEach (*uiOpenTypeFeaturesForEachFunc)(const uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t value, void *data);
 
// @role uiOpenTypeFeatures constructor
// uiNewOpenTypeFeatures() returns a new uiOpenTypeFeatures
// instance, with no tags yet added.
_UI_EXTERN uiOpenTypeFeatures *uiNewOpenTypeFeatures(void);
 
// @role uiOpenTypeFeatures destructor
// uiFreeOpenTypeFeatures() frees otf.
_UI_EXTERN void uiFreeOpenTypeFeatures(uiOpenTypeFeatures *otf);
 
// uiOpenTypeFeaturesClone() makes a copy of otf and returns it.
// Changing one will not affect the other.
_UI_EXTERN uiOpenTypeFeatures *uiOpenTypeFeaturesClone(const uiOpenTypeFeatures *otf);
 
// uiOpenTypeFeaturesAdd() adds the given feature tag and value
// to otf. The feature tag is specified by a, b, c, and d. If there is
// already a value associated with the specified tag in otf, the old
// value is removed.
_UI_EXTERN void uiOpenTypeFeaturesAdd(uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t value);
 
// uiOpenTypeFeaturesRemove() removes the given feature tag
// and value from otf. If the tag is not present in otf,
// uiOpenTypeFeaturesRemove() does nothing.
_UI_EXTERN void uiOpenTypeFeaturesRemove(uiOpenTypeFeatures *otf, char a, char b, char c, char d);
 
// uiOpenTypeFeaturesGet() determines whether the given feature
// tag is present in otf. If it is, *value is set to the tag's value and
// nonzero is returned. Otherwise, zero is returned.
//
// Note that if uiOpenTypeFeaturesGet() returns zero, value isn't
// changed. This is important: if a feature is not present in a
// uiOpenTypeFeatures, the feature is NOT treated as if its
// value was zero anyway. Script-specific font shaping rules and
// font-specific feature settings may use a different default value
// for a feature. You should likewise not treat a missing feature as
// having a value of zero either. Instead, a missing feature should
// be treated as having some unspecified default value.
_UI_EXTERN int uiOpenTypeFeaturesGet(const uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t *value);
 
// uiOpenTypeFeaturesForEach() executes f for every tag-value
// pair in otf. The enumeration order is unspecified. You cannot
// modify otf while uiOpenTypeFeaturesForEach() is running.
_UI_EXTERN void uiOpenTypeFeaturesForEach(const uiOpenTypeFeatures *otf, uiOpenTypeFeaturesForEachFunc f, void *data);
 
// uiNewFeaturesAttribute() creates a new uiAttribute that changes
// the font family of the text it is applied to. otf is copied; you may
// free it after uiNewFeaturesAttribute() returns.
_UI_EXTERN uiAttribute *uiNewFeaturesAttribute(const uiOpenTypeFeatures *otf);
 
// uiAttributeFeatures() returns the OpenType features stored in a.
// The returned uiOpenTypeFeatures object is owned by a. It is an
// error to call this on a uiAttribute that does not hold OpenType
// features.
_UI_EXTERN const uiOpenTypeFeatures *uiAttributeFeatures(const uiAttribute *a);
 
// uiAttributedString represents a string of UTF-8 text that can
// optionally be embellished with formatting attributes. libui
// provides the list of formatting attributes, which cover common
// formatting traits like boldface and color as well as advanced
// typographical features provided by OpenType like superscripts
// and small caps. These attributes can be combined in a variety of
// ways.
//
// Attributes are applied to runs of Unicode codepoints in the string.
// Zero-length runs are elided. Consecutive runs that have the same
// attribute type and value are merged. Each attribute is independent
// of each other attribute; overlapping attributes of different types
// do not split each other apart, but different values of the same
// attribute type do.
//
// The empty string can also be represented by uiAttributedString,
// but because of the no-zero-length-attribute rule, it will not have
// attributes.
//
// A uiAttributedString takes ownership of all attributes given to
// it, as it may need to duplicate or delete uiAttribute objects at
// any time. By extension, when you free a uiAttributedString,
// all uiAttributes within will also be freed. Each method will
// describe its own rules in more details.
//
// In addition, uiAttributedString provides facilities for moving
// between grapheme clusters, which represent a character
// from the point of view of the end user. The cursor of a text editor
// is always placed on a grapheme boundary, so you can use these
// features to move the cursor left or right by one "character".
// TODO does uiAttributedString itself need this
//
// uiAttributedString does not provide enough information to be able
// to draw itself onto a uiDrawContext or respond to user actions.
// In order to do that, you'll need to use a uiDrawTextLayout, which
// is built from the combination of a uiAttributedString and a set of
// layout-specific properties.
typedef struct uiAttributedString uiAttributedString;
 
// uiAttributedStringForEachAttributeFunc is the type of the function
// invoked by uiAttributedStringForEachAttribute() for every
// attribute in s. Refer to that function's documentation for more
// details.
typedef uiForEach (*uiAttributedStringForEachAttributeFunc)(const uiAttributedString *s, const uiAttribute *a, size_t start, size_t end, void *data);
 
// @role uiAttributedString constructor
// uiNewAttributedString() creates a new uiAttributedString from
// initialString. The string will be entirely unattributed.
_UI_EXTERN uiAttributedString *uiNewAttributedString(const char *initialString);
 
// @role uiAttributedString destructor
// uiFreeAttributedString() destroys the uiAttributedString s.
// It will also free all uiAttributes within.
_UI_EXTERN void uiFreeAttributedString(uiAttributedString *s);
 
// uiAttributedStringString() returns the textual content of s as a
// '\0'-terminated UTF-8 string. The returned pointer is valid until
// the next change to the textual content of s.
_UI_EXTERN const char *uiAttributedStringString(const uiAttributedString *s);
 
// uiAttributedStringLength() returns the number of UTF-8 bytes in
// the textual content of s, excluding the terminating '\0'.
_UI_EXTERN size_t uiAttributedStringLen(const uiAttributedString *s);
 
// uiAttributedStringAppendUnattributed() adds the '\0'-terminated
// UTF-8 string str to the end of s. The new substring will be
// unattributed.
_UI_EXTERN void uiAttributedStringAppendUnattributed(uiAttributedString *s, const char *str);
 
// uiAttributedStringInsertAtUnattributed() adds the '\0'-terminated
// UTF-8 string str to s at the byte position specified by at. The new
// substring will be unattributed; existing attributes will be moved
// along with their text.
_UI_EXTERN void uiAttributedStringInsertAtUnattributed(uiAttributedString *s, const char *str, size_t at);
 
// TODO add the Append and InsertAtExtendingAttributes functions
// TODO and add functions that take a string + length
 
// uiAttributedStringDelete() deletes the characters and attributes of
// s in the byte range [start, end).
_UI_EXTERN void uiAttributedStringDelete(uiAttributedString *s, size_t start, size_t end);
 
// TODO add a function to uiAttributedString to get an attribute's value at a specific index or in a specific range, so we can edit
 
// uiAttributedStringSetAttribute() sets a in the byte range [start, end)
// of s. Any existing attributes in that byte range of the same type are
// removed. s takes ownership of a; you should not use it after
// uiAttributedStringSetAttribute() returns.
_UI_EXTERN void uiAttributedStringSetAttribute(uiAttributedString *s, uiAttribute *a, size_t start, size_t end);
 
// uiAttributedStringForEachAttribute() enumerates all the
// uiAttributes in s. It is an error to modify s in f. Within f, s still
// owns the attribute; you can neither free it nor save it for later
// use.
// TODO reword the above for consistency (TODO and find out what I meant by that)
// TODO define an enumeration order (or mark it as undefined); also define how consecutive runs of identical attributes are handled here and sync with the definition of uiAttributedString itself
_UI_EXTERN void uiAttributedStringForEachAttribute(const uiAttributedString *s, uiAttributedStringForEachAttributeFunc f, void *data);
 
// TODO const correct this somehow (the implementation needs to mutate the structure)
_UI_EXTERN size_t uiAttributedStringNumGraphemes(uiAttributedString *s);
 
// TODO const correct this somehow (the implementation needs to mutate the structure)
_UI_EXTERN size_t uiAttributedStringByteIndexToGrapheme(uiAttributedString *s, size_t pos);
 
// TODO const correct this somehow (the implementation needs to mutate the structure)
_UI_EXTERN size_t uiAttributedStringGraphemeToByteIndex(uiAttributedString *s, size_t pos);
 
// uiFontDescriptor provides a complete description of a font where
// one is needed. Currently, this means as the default font of a
// uiDrawTextLayout and as the data returned by uiFontButton.
// All the members operate like the respective uiAttributes.
typedef struct uiFontDescriptor uiFontDescriptor;
 
struct uiFontDescriptor {
    // TODO const-correct this or figure out how to deal with this when getting a value
    char *Family;
    double Size;
    uiTextWeight Weight;
    uiTextItalic Italic;
    uiTextStretch Stretch;
};
 
_UI_EXTERN void uiLoadControlFont(uiFontDescriptor *f);
_UI_EXTERN void uiFreeFontDescriptor(uiFontDescriptor *desc);
 
// uiDrawTextLayout is a concrete representation of a
// uiAttributedString that can be displayed in a uiDrawContext.
// It includes information important for the drawing of a block of
// text, including the bounding box to wrap the text within, the
// alignment of lines of text within that box, areas to mark as
// being selected, and other things.
//
// Unlike uiAttributedString, the content of a uiDrawTextLayout is
// immutable once it has been created.
//
// TODO talk about OS-specific differences with text drawing that libui can't account for...
typedef struct uiDrawTextLayout uiDrawTextLayout;
 
// uiDrawTextAlign specifies the alignment of lines of text in a
// uiDrawTextLayout.
// TODO should this really have Draw in the name?
_UI_ENUM(uiDrawTextAlign) {
    uiDrawTextAlignLeft,
    uiDrawTextAlignCenter,
    uiDrawTextAlignRight,
};
 
// uiDrawTextLayoutParams describes a uiDrawTextLayout.
// DefaultFont is used to render any text that is not attributed
// sufficiently in String. Width determines the width of the bounding
// box of the text; the height is determined automatically.
typedef struct uiDrawTextLayoutParams uiDrawTextLayoutParams;
 
// TODO const-correct this somehow
struct uiDrawTextLayoutParams {
    uiAttributedString *String;
    uiFontDescriptor *DefaultFont;
    double Width;
    uiDrawTextAlign Align;
};
 
// @role uiDrawTextLayout constructor
// uiDrawNewTextLayout() creates a new uiDrawTextLayout from
// the given parameters.
//
// TODO
// - allow creating a layout out of a substring
// - allow marking compositon strings
// - allow marking selections, even after creation
// - add the following functions:
//  - uiDrawTextLayoutHeightForWidth() (returns the height that a layout would need to be to display the entire string at a given width)
//  - uiDrawTextLayoutRangeForSize() (returns what substring would fit in a given size)
//  - uiDrawTextLayoutNewWithHeight() (limits amount of string used by the height)
// - some function to fix up a range (for text editing)
_UI_EXTERN uiDrawTextLayout *uiDrawNewTextLayout(uiDrawTextLayoutParams *params);
 
// @role uiDrawFreeTextLayout destructor
// uiDrawFreeTextLayout() frees tl. The underlying
// uiAttributedString is not freed.
_UI_EXTERN void uiDrawFreeTextLayout(uiDrawTextLayout *tl);
 
// uiDrawText() draws tl in c with the top-left point of tl at (x, y).
_UI_EXTERN void uiDrawText(uiDrawContext *c, uiDrawTextLayout *tl, double x, double y);
 
// uiDrawTextLayoutExtents() returns the width and height of tl
// in width and height. The returned width may be smaller than
// the width passed into uiDrawNewTextLayout() depending on
// how the text in tl is wrapped. Therefore, you can use this
// function to get the actual size of the text layout.
_UI_EXTERN void uiDrawTextLayoutExtents(uiDrawTextLayout *tl, double *width, double *height);
 
// TODO metrics functions
 
// TODO number of lines visible for clipping rect, range visible for clipping rect?
 
 
typedef struct uiFontButton uiFontButton;
#define uiFontButton(this) ((uiFontButton *) (this))
 
_UI_EXTERN void uiFontButtonFont(uiFontButton *b, uiFontDescriptor *desc);
 
_UI_EXTERN void uiFontButtonOnChanged(uiFontButton *b,
    void (*f)(uiFontButton *sender, void *senderData), void *data);
 
_UI_EXTERN uiFontButton *uiNewFontButton(void);
 
_UI_EXTERN void uiFreeFontButtonFont(uiFontDescriptor *desc);
 
_UI_ENUM(uiModifiers) {
    uiModifierCtrl  = 1 << 0, 
    uiModifierAlt   = 1 << 1, 
    uiModifierShift = 1 << 2, 
    uiModifierSuper = 1 << 3, 
};
 
// TODO document drag captures
struct uiAreaMouseEvent {
    // TODO document what these mean for scrolling areas
    double X;
    double Y;
 
    // TODO see draw above
    double AreaWidth;
    double AreaHeight;
 
    int Down;
    int Up;
 
    int Count;
 
    uiModifiers Modifiers;
 
    uint64_t Held1To64;
};
 
_UI_ENUM(uiExtKey) {
    uiExtKeyEscape = 1,
    uiExtKeyInsert,         // equivalent to "Help" on Apple keyboards
    uiExtKeyDelete,
    uiExtKeyHome,
    uiExtKeyEnd,
    uiExtKeyPageUp,
    uiExtKeyPageDown,
    uiExtKeyUp,
    uiExtKeyDown,
    uiExtKeyLeft,
    uiExtKeyRight,
    uiExtKeyF1,         // F1..F12 are guaranteed to be consecutive
    uiExtKeyF2,
    uiExtKeyF3,
    uiExtKeyF4,
    uiExtKeyF5,
    uiExtKeyF6,
    uiExtKeyF7,
    uiExtKeyF8,
    uiExtKeyF9,
    uiExtKeyF10,
    uiExtKeyF11,
    uiExtKeyF12,
    uiExtKeyN0,         // numpad keys; independent of Num Lock state
    uiExtKeyN1,         // N0..N9 are guaranteed to be consecutive
    uiExtKeyN2,
    uiExtKeyN3,
    uiExtKeyN4,
    uiExtKeyN5,
    uiExtKeyN6,
    uiExtKeyN7,
    uiExtKeyN8,
    uiExtKeyN9,
    uiExtKeyNDot,
    uiExtKeyNEnter,
    uiExtKeyNAdd,
    uiExtKeyNSubtract,
    uiExtKeyNMultiply,
    uiExtKeyNDivide,
};
 
struct uiAreaKeyEvent {
    char Key;
    uiExtKey ExtKey;
    uiModifiers Modifier;
 
    uiModifiers Modifiers;
 
    int Up;
};
 
 
typedef struct uiColorButton uiColorButton;
#define uiColorButton(this) ((uiColorButton *) (this))
 
_UI_EXTERN void uiColorButtonColor(uiColorButton *b, double *r, double *g, double *bl, double *a);
 
_UI_EXTERN void uiColorButtonSetColor(uiColorButton *b, double r, double g, double bl, double a);
 
_UI_EXTERN void uiColorButtonOnChanged(uiColorButton *b,
    void (*f)(uiColorButton *sender, void *senderData), void *data);
 
_UI_EXTERN uiColorButton *uiNewColorButton(void);
 
 
typedef struct uiForm uiForm;
#define uiForm(this) ((uiForm *) (this))
 
_UI_EXTERN void uiFormAppend(uiForm *f, const char *label, uiControl *c, int stretchy);
 
_UI_EXTERN int uiFormNumChildren(uiForm *f);
 
_UI_EXTERN void uiFormDelete(uiForm *f, int index);
 
_UI_EXTERN int uiFormPadded(uiForm *f);
 
_UI_EXTERN void uiFormSetPadded(uiForm *f, int padded);
 
_UI_EXTERN uiForm *uiNewForm(void);
 
 
_UI_ENUM(uiAlign) {
    uiAlignFill,    
    uiAlignStart,   
    uiAlignCenter,  
    uiAlignEnd, 
};
 
_UI_ENUM(uiAt) {
    uiAtLeading,    
    uiAtTop,    
    uiAtTrailing,   
    uiAtBottom, 
};
 
typedef struct uiGrid uiGrid;
#define uiGrid(this) ((uiGrid *) (this))
 
_UI_EXTERN void uiGridAppend(uiGrid *g, uiControl *c, int left, int top, int xspan, int yspan, int hexpand, uiAlign halign, int vexpand, uiAlign valign);
 
_UI_EXTERN void uiGridInsertAt(uiGrid *g, uiControl *c, uiControl *existing, uiAt at, int xspan, int yspan, int hexpand, uiAlign halign, int vexpand, uiAlign valign);
 
_UI_EXTERN int uiGridPadded(uiGrid *g);
 
_UI_EXTERN void uiGridSetPadded(uiGrid *g, int padded);
 
_UI_EXTERN uiGrid *uiNewGrid(void);
 
 
typedef struct uiImage uiImage;
 
_UI_EXTERN uiImage *uiNewImage(double width, double height);
 
_UI_EXTERN void uiFreeImage(uiImage *i);
 
_UI_EXTERN void uiImageAppend(uiImage *i, void *pixels, int pixelWidth, int pixelHeight, int byteStride);
 
typedef struct uiTableValue uiTableValue;
 
_UI_EXTERN void uiFreeTableValue(uiTableValue *v);
 
_UI_ENUM(uiTableValueType) {
    uiTableValueTypeString,
    uiTableValueTypeImage,
    uiTableValueTypeInt,
    uiTableValueTypeColor,
};
 
_UI_EXTERN uiTableValueType uiTableValueGetType(const uiTableValue *v);
 
_UI_EXTERN uiTableValue *uiNewTableValueString(const char *str);
 
_UI_EXTERN const char *uiTableValueString(const uiTableValue *v);
 
_UI_EXTERN uiTableValue *uiNewTableValueImage(uiImage *img);
 
_UI_EXTERN uiImage *uiTableValueImage(const uiTableValue *v);
 
_UI_EXTERN uiTableValue *uiNewTableValueInt(int i);
 
_UI_EXTERN int uiTableValueInt(const uiTableValue *v);
 
_UI_EXTERN uiTableValue *uiNewTableValueColor(double r, double g, double b, double a);
 
_UI_EXTERN void uiTableValueColor(const uiTableValue *v, double *r, double *g, double *b, double *a);
 
 
_UI_ENUM(uiSortIndicator) {
    uiSortIndicatorNone,
    uiSortIndicatorAscending,
    uiSortIndicatorDescending
};
 
typedef struct uiTableModel uiTableModel;
 
typedef struct uiTableModelHandler uiTableModelHandler;
struct uiTableModelHandler {
    int (*NumColumns)(uiTableModelHandler *, uiTableModel *);
 
    uiTableValueType (*ColumnType)(uiTableModelHandler *, uiTableModel *, int column);
 
    int (*NumRows)(uiTableModelHandler *, uiTableModel *);
 
    uiTableValue *(*CellValue)(uiTableModelHandler *mh, uiTableModel *m, int row, int column);
 
    void (*SetCellValue)(uiTableModelHandler *, uiTableModel *, int, int, const uiTableValue *);
};
 
_UI_EXTERN uiTableModel *uiNewTableModel(uiTableModelHandler *mh);
 
_UI_EXTERN void uiFreeTableModel(uiTableModel *m);
 
_UI_EXTERN void uiTableModelRowInserted(uiTableModel *m, int newIndex);
 
_UI_EXTERN void uiTableModelRowChanged(uiTableModel *m, int index);
 
_UI_EXTERN void uiTableModelRowDeleted(uiTableModel *m, int oldIndex);
// TODO reordering/moving
 
#define uiTableModelColumnNeverEditable (-1)
#define uiTableModelColumnAlwaysEditable (-2)
 
typedef struct uiTableTextColumnOptionalParams uiTableTextColumnOptionalParams;
struct uiTableTextColumnOptionalParams {
    int ColorModelColumn;
};
 
typedef struct uiTableParams uiTableParams;
struct uiTableParams {
    uiTableModel *Model;
    int RowBackgroundColorModelColumn;
};
 
typedef struct uiTable uiTable;
#define uiTable(this) ((uiTable *) (this))
 
_UI_EXTERN void uiTableAppendTextColumn(uiTable *t,
    const char *name,
    int textModelColumn,
    int textEditableModelColumn,
    uiTableTextColumnOptionalParams *textParams);
 
_UI_EXTERN void uiTableAppendImageColumn(uiTable *t,
    const char *name,
    int imageModelColumn);
 
_UI_EXTERN void uiTableAppendImageTextColumn(uiTable *t,
    const char *name,
    int imageModelColumn,
    int textModelColumn,
    int textEditableModelColumn,
    uiTableTextColumnOptionalParams *textParams);
 
_UI_EXTERN void uiTableAppendCheckboxColumn(uiTable *t,
    const char *name,
    int checkboxModelColumn,
    int checkboxEditableModelColumn);
 
_UI_EXTERN void uiTableAppendCheckboxTextColumn(uiTable *t,
    const char *name,
    int checkboxModelColumn,
    int checkboxEditableModelColumn,
    int textModelColumn,
    int textEditableModelColumn,
    uiTableTextColumnOptionalParams *textParams);
 
_UI_EXTERN void uiTableAppendProgressBarColumn(uiTable *t,
    const char *name,
    int progressModelColumn);
 
_UI_EXTERN void uiTableAppendButtonColumn(uiTable *t,
    const char *name,
    int buttonModelColumn,
    int buttonClickableModelColumn);
 
_UI_EXTERN int uiTableHeaderVisible(uiTable *t);
 
_UI_EXTERN void uiTableHeaderSetVisible(uiTable *t, int visible);
 
_UI_EXTERN uiTable *uiNewTable(uiTableParams *params);
 
 
_UI_EXTERN void uiTableOnRowClicked(uiTable *t,
    void (*f)(uiTable *t, int row, void *data),
    void *data);
 
_UI_EXTERN void uiTableOnRowDoubleClicked(uiTable *t,
    void (*f)(uiTable *t, int row, void *data),
    void *data);
 
_UI_EXTERN void uiTableHeaderSetSortIndicator(uiTable *t,
    int column,
    uiSortIndicator indicator);
 
_UI_EXTERN uiSortIndicator uiTableHeaderSortIndicator(uiTable *t, int column);
 
_UI_EXTERN void uiTableHeaderOnClicked(uiTable *t,
    void (*f)(uiTable *sender, int column, void *senderData), void *data);
 
_UI_EXTERN int uiTableColumnWidth(uiTable *t, int column);
 
_UI_EXTERN void uiTableColumnSetWidth(uiTable *t, int column, int width);
 
_UI_ENUM(uiTableSelectionMode) {
        uiTableSelectionModeNone,
        uiTableSelectionModeZeroOrOne,  
        uiTableSelectionModeOne,        
        uiTableSelectionModeZeroOrMany, 
};
 
_UI_EXTERN uiTableSelectionMode uiTableGetSelectionMode(uiTable *t);
 
_UI_EXTERN void uiTableSetSelectionMode(uiTable *t, uiTableSelectionMode mode);
 
_UI_EXTERN void uiTableOnSelectionChanged(uiTable *t, void (*f)(uiTable *t, void *data), void *data);
 
typedef struct uiTableSelection uiTableSelection;
struct uiTableSelection
{
    int NumRows; 
    int *Rows;   
};
 
_UI_EXTERN uiTableSelection* uiTableGetSelection(uiTable *t);
 
_UI_EXTERN void uiTableSetSelection(uiTable *t, uiTableSelection *sel);
 
_UI_EXTERN void uiFreeTableSelection(uiTableSelection* s);
 
#ifdef __cplusplus
}
#endif
 
#endif