From d7659db41afcf9e45886e4095a3c9dc0fcc88a55 Mon Sep 17 00:00:00 2001 From: Ben Campbell Date: Sun, 7 Jan 2018 21:45:20 +1300 Subject: [PATCH] document API calls for button, box, checkbox, entry, tab and group --- ui.h | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) diff --git a/ui.h b/ui.h index 5a2069e8..64cf3706 100644 --- a/ui.h +++ b/ui.h @@ -113,65 +113,217 @@ _UI_EXTERN int uiWindowMargined(uiWindow *w); _UI_EXTERN void uiWindowSetMargined(uiWindow *w, int margined); _UI_EXTERN uiWindow *uiNewWindow(const char *title, int width, int height, int hasMenubar); +// uiButton is a common pushbutton, containing a text label. typedef struct uiButton uiButton; #define uiButton(this) ((uiButton *) (this)) + +// uiButtonText returns the button label text. +// The returned text is owned by the caller and should be freed with uiFreeText() _UI_EXTERN char *uiButtonText(uiButton *b); + +// uiButtonSetText sets the text label on the button _UI_EXTERN void uiButtonSetText(uiButton *b, const char *text); + +// uiButtonOnClicked sets the function which is called when the button +// is clicked (or otherwise activated). +// A button may only have one OnClicked function registered at a time. +// The data value is passed on to the callback. _UI_EXTERN void uiButtonOnClicked(uiButton *b, void (*f)(uiButton *b, void *data), void *data); + +// uiNewButton creates a new uiButton, with the label from `text`. _UI_EXTERN uiButton *uiNewButton(const char *text); +// uiBox is a ontrol that holds a group of Controls horizontally +// or vertically. If horizontally, then all controls have the same +// height. If vertically, then all controls have the same width. +// By default, each control has its preferred width (horizontal) +// or height (vertical); if a control is marked "stretchy", it will +// take whatever space is left over. If multiple controls are marked +// stretchy, they will be given equal shares of the leftover space. +// There can also be space between each control ("padding"). +// Destroying a uiBox will also destroy it's children. typedef struct uiBox uiBox; #define uiBox(this) ((uiBox *) (this)) + +// uiBoxAppend adds a child control to the uiBox. _UI_EXTERN void uiBoxAppend(uiBox *b, uiControl *child, int stretchy); + +// uiBoxDelete removes a child control from the box +// TODO: confirm: is the child destroyed? _UI_EXTERN void uiBoxDelete(uiBox *b, int index); + +// uiBoxPadded returns true if the box is set to apply standard +// padding between children. _UI_EXTERN int uiBoxPadded(uiBox *b); + +// uiBoxSetPadded enables or disables padding between children. +// The exact amount of padding depends on the platform - libui +// attempts to conform to 'native' style recomendations. _UI_EXTERN void uiBoxSetPadded(uiBox *b, int padded); + +// uiNewHorizontalBox creates a new uiBox which lays out it's +// children horizontally _UI_EXTERN uiBox *uiNewHorizontalBox(void); + +// uiNewVerticalBox creates a new uiBox which lays out it's +// children vertically _UI_EXTERN uiBox *uiNewVerticalBox(void); +// uiCheckbox is a control that represents a box with a text label at its +// side. When the user clicks the checkbox, a check mark will appear +// in the box; clicking it again removes the check. typedef struct uiCheckbox uiCheckbox; #define uiCheckbox(this) ((uiCheckbox *) (this)) + +// uiCheckboxText returns a copy of the checkbox label. +// The returned string should be freed with uiFreeText() after use _UI_EXTERN char *uiCheckboxText(uiCheckbox *c); + +// uiCheckboxSetText sets the checkbox label text _UI_EXTERN void uiCheckboxSetText(uiCheckbox *c, const char *text); + +// uiCheckboxOnToggled installs the callback function which will be +// called when the checkbox state is changed. +// Any previously installed callback will be overriden. +// The `data` parameter is passed verbatim to the callback when +// it is invoked. +// The callback will only be invoked in response to user interaction - +// calling uiCheckboxSetChecked() will not trigger it. _UI_EXTERN void uiCheckboxOnToggled(uiCheckbox *c, void (*f)(uiCheckbox *c, void *data), void *data); + +// uiCheckboxChecked returns the current state of the checkbox - +// true for checked, false for unchecked. _UI_EXTERN int uiCheckboxChecked(uiCheckbox *c); + +// uiCheckboxSetChecked sets the state of the checkbox. +// This will not trigger the uiCheckboxOnToggled callback. _UI_EXTERN void uiCheckboxSetChecked(uiCheckbox *c, int checked); + +// uiNewCheckbox creates a new uiCheckbox control. +// The checkbox label will be set to the `text` param. _UI_EXTERN uiCheckbox *uiNewCheckbox(const char *text); +// uiEntry is a control that represents a space that the user can +// type a single line of text into. typedef struct uiEntry uiEntry; #define uiEntry(this) ((uiEntry *) (this)) + +// uiEntryText returns a copy of the currently-entered text +// The returned string should be freed with uiFreeText() after use _UI_EXTERN char *uiEntryText(uiEntry *e); + +// uiEntrySetText sets the entry contents to `text` +// This will not trigger the uiEntryOnChanged callback. _UI_EXTERN void uiEntrySetText(uiEntry *e, const char *text); + +// uiEntryOnChanged installs a callback function to be invoked whenever +// the user alters the text. +// It will not be called in response to uiEntrySetText() +// Any previously installed callback will be overriden. +// The callback will receive `data` as a parameter. _UI_EXTERN void uiEntryOnChanged(uiEntry *e, void (*f)(uiEntry *e, void *data), void *data); + +// uiEntryReadOnly returns whether the uiEntry can be changed. _UI_EXTERN int uiEntryReadOnly(uiEntry *e); + +// uiEntryReadOnly sets whether the uiEntry can be changed. _UI_EXTERN void uiEntrySetReadOnly(uiEntry *e, int readonly); + +// uiNewEntry creates a standard single-line text entry control. _UI_EXTERN uiEntry *uiNewEntry(void); + +// uiNewPasswordEntry creates a uiEntry suitable for entering passwords. +// The text entered will be obscured, according to the native +// style of the runtime platform. _UI_EXTERN uiEntry *uiNewPasswordEntry(void); + +// uiNewSearchEntry creates a uiEntry for entering searches, with +// appearance according to the styles and conventions of the runtime +// platform (eg - some platforms display a little magnifying glass +// image beside the text). _UI_EXTERN uiEntry *uiNewSearchEntry(void); +// uiLabel is a Control that represents a line of text that cannot be +// interacted with. typedef struct uiLabel uiLabel; #define uiLabel(this) ((uiLabel *) (this)) + + +// uiLabelText returns a copy of the currently-showing text +// The returned string should be freed with uiFreeText() after use _UI_EXTERN char *uiLabelText(uiLabel *l); + +// uiLabelSetText sets the text of the label. _UI_EXTERN void uiLabelSetText(uiLabel *l, const char *text); + +// uiNewLabel creates a new uiLabel control, showing the given text. _UI_EXTERN uiLabel *uiNewLabel(const char *text); +// uiTab is a control that holds tabbed pages of controls. Each tab +// has a label. The user can click on the tabs themselves to switch +// pages. Individual pages can also have margins. +// When destroyed, a uiTab will also destroy all it's child controls. typedef struct uiTab uiTab; #define uiTab(this) ((uiTab *) (this)) + +// uiTabAppend adds the given page to the end of the uiTab. _UI_EXTERN void uiTabAppend(uiTab *t, const char *name, uiControl *c); + +// uiTabInsertAt adds the given page to the uiTab such that it is the +// nth page of the uiTab (starting at 0). _UI_EXTERN void uiTabInsertAt(uiTab *t, const char *name, int before, uiControl *c); + + +// uiTabDelete deletes the nth page of the Tab. +// TODO: confirm: is Destroy called on the page? _UI_EXTERN void uiTabDelete(uiTab *t, int index); + +// uiTabNumPages returns the number of pages in the uiTab. _UI_EXTERN int uiTabNumPages(uiTab *t); + +// uiTabMargined returns whether page n (starting at 0) of the uiTab +// has margins around its child. _UI_EXTERN int uiTabMargined(uiTab *t, int page); + +// uiTabSetMargined controls whether page n (starting at 0) of the uiTab +// has margins around its child. The size of the margins are +// determined by the OS and its best practices. _UI_EXTERN void uiTabSetMargined(uiTab *t, int page, int margined); + +// uiNewTab creates a new uiTab control _UI_EXTERN uiTab *uiNewTab(void); +// uiGroup is a control that holds another control and wraps it around +// a labelled box (though some systems make this box invisible). +// You can use this to group related controls together. +// When the uiGroup is destroyed, it will destroy it's child in turn. typedef struct uiGroup uiGroup; #define uiGroup(this) ((uiGroup *) (this)) + +// uiGroupTitle returns the currently-set title +// The returned string should be freed with uiFreeText() after use _UI_EXTERN char *uiGroupTitle(uiGroup *g); + +// uiGroupSetTitle sets the group's title to `title` _UI_EXTERN void uiGroupSetTitle(uiGroup *g, const char *title); + + +// uiGroupSetChild sets the Group's child to `child`. +// If `child` is null, the Group will not have a child. +// Any existing child will be destroyed (TODO: confirm!) _UI_EXTERN void uiGroupSetChild(uiGroup *g, uiControl *c); + + +// uiGroupMargined returns whether the group has margins around its child. _UI_EXTERN int uiGroupMargined(uiGroup *g); + + +// uiGroupSetMargined controls whether the group has margins around its +// child. The size of the margins are determined by the OS and its +// best practices. _UI_EXTERN void uiGroupSetMargined(uiGroup *g, int margined); + +// uiNewGroup creates a new uiGroup _UI_EXTERN uiGroup *uiNewGroup(const char *title); // spinbox/slider rules: