From cd983b255dd377453ff2098b7b13d309832c9b1b Mon Sep 17 00:00:00 2001 From: Pietro Gagliardi Date: Tue, 28 Apr 2015 13:52:03 -0400 Subject: [PATCH] Removed the old docs/ folder. Virtually all of it no longer applies. If I do decide to have control images in the documentation, the border size should be 2 pixels. --- docs/images/uiButton_unix.png | Bin 1402 -> 0 bytes docs/lifetimes.md | 109 --------------- docs/newcontrol_unix.md | 247 ---------------------------------- docs/newcontrol_windows.md | 102 -------------- docs/uiButton.md | 41 ------ docs/uiCheckbox.md | 55 -------- docs/uiEntry.md | 27 ---- docs/uiLabel.md | 27 ---- docs/uiOSContainer.md | 50 ------- 9 files changed, 658 deletions(-) delete mode 100644 docs/images/uiButton_unix.png delete mode 100644 docs/lifetimes.md delete mode 100644 docs/newcontrol_unix.md delete mode 100644 docs/newcontrol_windows.md delete mode 100644 docs/uiButton.md delete mode 100644 docs/uiCheckbox.md delete mode 100644 docs/uiEntry.md delete mode 100644 docs/uiLabel.md delete mode 100644 docs/uiOSContainer.md diff --git a/docs/images/uiButton_unix.png b/docs/images/uiButton_unix.png deleted file mode 100644 index 9ef281727ce7b07e27d8947139ee5db755fe5537..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1402 zcmV-=1%>*FP)g1qVq) zK~!ko?V4|F6J;F7KX=z&Z|%ky5XKz1DYDG~3L3MiB$64%wh%xahOlUWFd&G87{!1w zVMfq_h!73(C%%&q5pZz?gS--9#ApN*VMAaz7u=*<*KNIC+q=gXZDH6tU%1t<+&8(T z_w94JyU+8x?{j}1$?NqBY^6-HjUcsh#D7?pMN?A~ZEbA?gF&0jAV||Ra&vPjEG$Hp zqqQx?BjwViOX#{zNl6JFkH@Ap2l(PHAB8t^z)!8Lt1t*5$9$@P`?F#LXDbw9-YattlnXH83&r#uuzyd78!h zxA3IrpFO+6?<`R|{aHM>b04cFM(DWsH9IzLVS_uLPnO(|I?$#<5D^j*g7_gO^X|HL zDME;$TM$Sns16xLO(%Eyd{$J9q2reu=t2-~`<%sd*YRy{w7t>1n}yHUaW)WLM?cH@ z`Q^+kD`(Y-F3hB!Mc=PqvT0=%Gt0`USX#^e^WB(2VEKP!$LeY-W=GpsEZfZCD>~Lt zo^x#Ze=1xEL~I|HX<>AHPs3?Hx#jngCIkWnS(1_C6)P!7vVtUH>uJ;3dSnMrrGps^ z(A%2m>Hc%;-G6I{Gq4&h_y4R0-rXMrLYg>AB3PDrNL5=V=ShWt@As0(XqznRj=w zVxj}1`#NV1Y@v3|Uf$nT!vis_mK6iuKjz}dt=oB>=m`v;7bCL-Pb3`eKr4+2qfAcz z*+V40ooQm30@IO2nt7S9NbMMq;`iYSF4c+CrIL~TAhQ-$lH>iEX1|H7deB54oq@zV zB}r0Hh!8Tx0G@<4YAh~a3*PwUVtKjRDU&rW10|vVC8S|JXbJ&D(EVL>-t6GFi>Em7 z@gc5{m`YKmjFdi!=_9Xk@NgqnJ8sh6;Ui>4BS!YzL$=hyiBnf-zj2MGb{#2+r%swn zspBLcetL$M_TTy8;2!Gx9%I2no>)fpKNit1!iM9ZiHp%Ax~SiexIli8sH1m)={= zwzofE*`Z#v@iSOf_bSC6iLk-n0N;+LR7T3J4-gFv4V0CY4dI@gcrr6^$+s_RGi(qH z=oqE|BqWDMMtT~KSQ{&%)9crX01hpKbdM8R2qL;4ziuY=B!>%+$AhXw@BIV4eHak| zl8X@|HH_|Vf)=1?WM-=9K7aH|8bTdEew;aT=A?Si4AI-=rFVc)RfGd{cLkFE8`k}F z>HqGDaF8Bfl23#ph_ADsAJOr7b^Be)aF_kn-mY*PxGfv_FaWM;8o^)?m&;{S8AKU| zfu?DR!1MC*XliPrprF8pK8UcJo14kY%S(Llak*SvxNw1%mKJ-e+aO8PH1hNFnLK&& zt;tnV|Jk!{w;NSeZ_R_V_1|P!7NJmxKp>D<;kN7tpJA!L0N?M>Bc?e@LI3~&07*qo IM6N<$f^y20+W-In diff --git a/docs/lifetimes.md b/docs/lifetimes.md deleted file mode 100644 index 2b1b6925..00000000 --- a/docs/lifetimes.md +++ /dev/null @@ -1,109 +0,0 @@ -# Object lifetimes - -Know them. - -One of the more annoying parts of libui is that it has to juggle an OS control handle and at least one C data structure for a single uiControl, uiOSContainer, uiWindow, etc. To that end, this document exists to lay the ground rules for object lifetimes. - -## To end programmers - -TODO complain loudly if rules broken -TODO complain loudly if Destroying a control with a parent - -The rules for lifetimes are simple: - -- Removing a control from a container (for instance, with `uiBoxDelete()` or `uiTabDeletePage()`) does NOT destroy the control. -- Destroying a container (`uiWindowDestroy()`, `uiControlDestroy()` on a uiBox or uiTab, etc.) WILL destroy children. -- Otherwise, a control stays alive. -- It is an error to destroy a control while it is part of a container. -- It is an error to add a control to more than one container at once. - -Currently, breaking these rules results in undefined behavior. Error checks will be added soon. - -## Implementation - -Note that control implementations generally don't need to worry about backend-specific information; these are handled by the backends's convenience functions. If you bypass those, however, you *will* need to worry. - -### General - -A correct implementation of `uiControlDestroy()` would work like this: - -``` -if control is a child of either a parent (TODO or a container) - complain -destroy the OS control -free data structures -``` - -And in the case of uiOSContainer: - -``` -if there is a main control - set its parent to NULL - destroy it -destroy the OS handle -free data structures -``` - -In the case of uiBox and uiGrid: - -``` -for every child - set its parent to NULL - destroy it -free data structures -``` - -TODO uiGroup, uiTab - -As for uiWindow, we won't need to worry, as destroying a uiOSContainer will properly destroy its main control. - -``` -if necessary, change the OS window's child to make the uiOSContainer safe to destroy -destroy the uiOSContainer -destroy the OS window -free internal data structures -``` - -### Windows - -Windows has no reference counting for window handles. The only situations where a window handle can be destroyed are - -- with a call to `DestroyWindow()`, or -- by `DefWindowProc()` if it receives a `WM_CLOSE` message (when the user clicks the Close button on the titlebar of a toplevel window, for instance) - -The destruction process is simple: - -1. Any owned windows are destroyed. ([Source](http://stackoverflow.com/questions/29419291/is-my-subclassing-common-controls-tooltip-destroying-itself-in-wm-destroy-before)) -2. The window receives `WM_DESTROY`. -3. Any child windows are destroyed. -4. The window receives `WM_NCDESTROY`. - -TODO write this - -### Unix - -GtkWidgets are destroyed with the function `gtk_widget_destroy()`. For a container, which is also a widget, all children of the container at destruction time are also destroyed. - -GtkWidgets also have a reference count. Initially, a GtkWidget starts out as *floating* (referenceless but unowned). Adding a widget to a container removes the floating status and increments the refcount. Removing a widget from a container decreases the reference count (but does NOT destroy the widget in and of itself). Once the referencce count drops back to zero, `gtk_widget_destroy()` is called. - -What does this mean? In the normal case, you create a widget, add it to a container, and add the container to a GtkWindow (also a GtkWidget). Then, when you're done, you simply destroy the GtkWindow, which will destroy the widgets inside. - -Note that removing a widget from a container does not call `gtk_widget_destroy()`; it merely decrements the reference count of the widget. - -As with Windows, a `::delete-event` signal (which is sent when the user clicks a toplevel window's Close button) that is allowed to propagate will result in the window being destroyed. - -TODO describe what we need to do -TODO remove lifetimes.c? - -### Mac OS X - -While Cocoa is a reference-counted object environment, simple reference counting of AppKit objects does not really work, and monitoring reference counts for lifetimes is dicouraged. Why? Strong references that we may not know about (think internal bookkeeping or third-party tools). However, if we pretend these additional references don't exist, the lifetime view beccomes simple. - -When a view is created, it is created in a state where it is initially unowned; the documentation says we have to add it to the view hierarchy before we can use it. When a view is added to a superview, its reference count goes up (*retained*). When a view is removed from its superview, its reference count goes down (*released*). Once this virtual reference count goes to zero, the view is no longer safe to use. - -In other words, when we create a view, add it to a superview, then remove it again, we should consider the view destroyed. - -In the case of NSWindow, there's a property `releasedWhenClosed` that determines if a NSWindow is released when it is closed. (TODO before or after `windowWillClose`?) - -do the whole "keep a reference around" thing -TODO drop the deleted controls view diff --git a/docs/newcontrol_unix.md b/docs/newcontrol_unix.md deleted file mode 100644 index a5144598..00000000 --- a/docs/newcontrol_unix.md +++ /dev/null @@ -1,247 +0,0 @@ -# Writing new controls for the Unix backend - -The Unix backend uses GTK+ to do its UI work. GtkWidget provides the necessary functionality that uiControl needs, so if you have a valid GtkWidget, you're good to go. - -For this document, we will write a basic wrapper around [GtkSwitch](https://developer.gnome.org/gtk3/3.4/GtkSwitch.html). It will conform to the following simple interface: - -```c -typedef struct mySwitch mySwitch; -struct mySwitch { - uiControl base; - int (*On)(mySwitch *); -}; -#define mySwitch(x) ((mySwitch *) (x)) -#define mySwitchOn(s) ((*((s)->On))((s))) -``` - -To be able to create Unix backend controls, we need to include `ui_unix.h`, the file that contains the Unix backend function declarations. It requires that you include both `ui.h` and `` beforehand: - -```c -#include -#include "ui.h" -#include "ui_unix.h" -``` - -The first thing we need to do is define the data structure used for our new control. The first field of this data structure must be a mySwitch (not a pointer to a mySwitch). This allows us to use our data structure *as* the mySwitch: - -```c -struct xswitch { - mySwitch s; -``` - -We'll also store copies of the pointer to our switch's GtkWidget as both a GtkWidget and a GtkSwitch, to make things easier for us: - -```c - GtkWidget *widget; - GtkSwitch *xswitch; -}; -``` - -The good news is that all the work of implementing uiControl is done for you by libui. You only need to worry about destroying your data structure along witht he GtkWidget and implementing the other methods of your interface. - -Let's start by writing the code to destroy the switch data structure when the GtkSwitch is destroyed. This will be the GtkSwitch's `::destroy` signal handler implementation. Our `struct xswitch` is passed as the user data: - -```c -static void onDestroy(GtkWidget *widget, gpointer data) -{ - struct xswitch *s = (struct xswitch *) data; - - g_free(s); -} -``` - -We'll connect this when we write our constructor. - -Next, let's write the implementation of our `mySwitchOn()` method. Remember that a `struct xswitch` *is* a `mySwitch`, so we simply use a pointer cast to go from the this pointer (the first argument of the method) to our `struct xswitch`: - -```c -static int switchOn(mySwitch *ss) -{ - struct xswitch *s = (struct xswitch *) ss; - - return gtk_switch_get_active(s->xswitch) != FALSE; -} -``` - -Now we need to write the function that creates a new mySwitch. Start by creating a new `struct xswitch`. - -```c -mySwitch *newSwitch(void) -{ - struct xswitch *s; - - s = g_new0(struct xswitch, 1); -``` - -Remember that a `mySwitch` is a `uiControl`, and that a `struct xswitch` is a `mySwitch`. Therefore, a `struct xswitch` is also a `uiControl`. This will be important shortly. - -The next step is to actually create the widget. All the work is done for you by the libui function `uiUnixNewControl()`. - -The first argument to `uiUnixNewControl()` is a pointer to the `uiControl` that will be filled in with internal data structures and the various uiControl methods. All we need to do is pass in our new `struct xswitch` converted to a `uiControl` with our `uiControl()` conversion macro. - -The second argument is the GType that represents the GtkWidget that we want to create. In this case, it's `GTK_TYPE_SWITCH`: - -```c - uiUnixNewControl(uiControl(s), GTK_TYPE_SWITCH, -``` - -The next argument is a `gboolean` that, if `TRUE`, means the widget should be given a set of scrollbars. You don't have to worry about accessing the GtkScrolledWindow itself or whether you need a viewport; libui will take care of that for you. If you do specify `TRUE`, the next argument is another `gboolean` that, if `TRUE`, adds a border to the GtkScrolledWindow. - -For our purposes, however, we don't need scrolling: - -```c - FALSE, FALSE, -``` - -Finally, we pass in a `NULL`-terminated list of GObject construct properties to give to the new widget. This is exactly like `g_object_new()`. For our purposes, we don't need to pass any, so just pass `NULL`: - -```c - NULL); -``` - -We now have a fully usable uiControl, but we still need a fully usable mySwitch and a fully usable `struct xswitch`. So let's fill in the rest of the structure. - -First, we'll get a handle to the GtkSwitch itself and stuff that into our structure: - -```c - s->widget = GTK_WIDGET(uiControlHandle(uiControl(s))); - s->xswitch = GTK_SWITCH(s->widget); -``` - -You may choose to use macros to hide the nested call that gets the value of `s->widget`; the implementation of libui itself uses a macro called `WIDGET()` for this. - -Next, let's connect our `onDestroy()` handler from earlier: - -```c - g_signal_connect(s->widget, "destroy", G_CALLBACK(onDestroy), s); -``` - -Now we need to connect our mySwitch vtable functions. We do this by converting our `struct xswitch` to a `mySwitch` with the `mySwitch()` conversion macro and writing to the vtable entries: - -```c - mySwitch(s)->On = switchOn; -``` - -And finally we're done, so let's just return our mySwitch: - -```c - return mySwitch(s); -} -``` - -And that's it! You now have everything you need to build a complete Unix backend uiControl! You can chooose and use the members of your control's backing data structure to your heart's content. All the controls in libui follow the standard set above. - -Here's a complete working example showing our `mySwitch` control: - -```c -#include -#include "ui.h" -#include "ui_unix.h" - -typedef struct mySwitch mySwitch; -struct mySwitch { - uiControl base; - int (*On)(mySwitch *); -}; -#define mySwitch(x) ((mySwitch *) (x)) -#define mySwitchOn(s) ((*((s)->On))((s))) - -struct xswitch { - mySwitch s; - GtkWidget *widget; - GtkSwitch *xswitch; -}; - -static void onDestroy(GtkWidget *widget, gpointer data) -{ - struct xswitch *s = (struct xswitch *) data; - - g_free(s); -} - -static int switchOn(mySwitch *ss) -{ - struct xswitch *s = (struct xswitch *) ss; - - return gtk_switch_get_active(s->xswitch) != FALSE; -} - -mySwitch *newSwitch(void) -{ - struct xswitch *s; - - s = g_new0(struct xswitch, 1); - - uiUnixNewControl(uiControl(s), GTK_TYPE_SWITCH, - FALSE, FALSE, - NULL); - - s->widget = GTK_WIDGET(uiControlHandle(uiControl(s))); - s->xswitch = GTK_SWITCH(s->widget); - - g_signal_connect(s->widget, "destroy", G_CALLBACK(onDestroy), s); - - mySwitch(s)->On = switchOn; - - return mySwitch(s); -} - -mySwitch *s; -uiLabel *l; - -void onClicked(uiButton *b, void *data) -{ - if (mySwitchOn(s)) - uiLabelSetText(l, "Switch is on"); - else - uiLabelSetText(l, "Switch is off"); -} - -int onClosing(uiWindow *w, void *data) -{ - uiQuit(); - return 1; -} - -int main(void) -{ - uiInitOptions o; - const char *err; - uiWindow *w; - uiStack *stack; - uiButton *b; - - memset(&o, 0, sizeof (uiInitOptions)); - err = uiInit(&o); - if (err != NULL) { - fprintf(stderr, "error initializing ui: %s\n", err); - uiFreeInitError(err); - return 1; - } - - w = uiNewWindow("mySwitch Test", 200, 100); - uiWindowOnClosing(w, onClosing, NULL); - uiWindowSetMargined(w, 1); - stack = uiNewHorizontalStack(); - uiStackSetPadded(stack, 1); - uiWindowSetChild(w, uiControl(stack)); - - s = newSwitch(); - uiStackAppend(stack, uiControl(s), 0); - - b = uiNewButton("On?"); - uiButtonOnClicked(b, onClicked, NULL); - uiStackAppend(stack, uiControl(b), 0); - - l = uiNewLabel("");; - uiStackAppend(stack, uiControl(l), 1); - - // TODO autosize window - // TODO make sure label is centered when done here - uiWindowShow(w); - uiMain(); - return 0; -} -``` - -TODO show output diff --git a/docs/newcontrol_windows.md b/docs/newcontrol_windows.md deleted file mode 100644 index 0d250209..00000000 --- a/docs/newcontrol_windows.md +++ /dev/null @@ -1,102 +0,0 @@ -# Writing new controls for the Windows backend - -The Unix backend uses the raw Windows API to do its UI work. The good news is that you don't need to implement most of uiControl to make things work. The bad news is that you *do* need to implement uiControlPreferredSize(). (TODO rewrite this?) - -For this document, we will write a basic wrapper around the [trackbar control](xxxTODOxxxx) as a slider that goes from 0 to 99 inclusive. It will conform to the following interface: - -```c -typedef struct mySlider mySlider; -struct mySlider { - uiControl base; - int (*Pos)(mySlider *); -}; -#define mySlider(x) ((mySwitch *) (x)) -#define mySliderPos(s) ((*((s)->Pos))((s))) -``` - -Error checking will be omitted for the purposes of demonstration. - -To be able to create Windows backend controls, we need to include `ui_windows.h`, the file that contains the Windows backend function declarations. It requires that you include both `ui.h` and `` (and any other macros like `UNICODE` and Windows API headers like ``) beforehand: - -```c -#define UNICODE -#define _UNICODE -#define STRICT -#include -#include -#include "ui.h" -#include "ui_windows.h" -``` - -Before we can create trackbars, though, we need to make sure the trackbar control class is loaded. As the trackbar is provided by the Common Controls library, we do this with the `InitCommonControlsEx()` function: - -```c -static void registerSliderClass(void) -{ - static int initialized = 0; - INITCOMMONCONTROLSEX icc; - - if (initialized) - return; - initialized = 1; - ZeroMemory(&icc, sizeof (INITCOMMONCONTROLSEX)); - icc.dwSize = sizeof (INITCOMMONCONTROLSEX); - icc.dwICC = xxxTODOxxxxxx; - InitCommonControlsEx(&icc); -} -``` - -Now that we have that done, we can move on to writing the control itself. The first thing we need to do is define the data structure used for our new control. The first field of this data structure must be a mySlider (not a pointer to a mySlider). This allows us to use our data structure *as* the mySlider: - -```c -struct slider { - mySlider s; -``` - -We'll also store a copy of the slider's HWND to make things easier for us: - -```c - HWND hwnd; -}; -``` - -The good news is that most of the work of implementing uiControl is done for you by libui. You only need to provide a few things: - -- the parameters to the `CreateWindowExW()` call that creates the control's window -- handlers for `WM_COMMAND` and `WM_NOTIFY` that handle any `WM_COMMAND` and `WM_NOTIFY` messages the control sends to its parent window -- a handler for `WM_DESTROY` that does any cleanup that needs to be done -- an implementation of `uiControlPreferredSize()` -- the other methods of your interface - -We'll deal with the first bullet later. - -The handlers for `WM_COMMAND` and `WM_NOTIFY` that libui expects to see have specific signatures: - -```c -BOOL onWM_COMMAND(uiControl *c, WORD code, LRESULT *lResult); -BOOL onWM_NOTIFY(uiControl *c, NMHDR *nm, LRESULT *lResult); -``` - -You'll notice that they each take three parameters and return a `BOOL`. The first parameter to each is the uiControl itself. The last parameter is the address of an `LRESULT`. If your handler returns non-`FALSE`, libui will return the value you store in that `LRESULT` as the return value for the message. Otherwise, libui will send the message down the subclass chain. - -The second parameter is what's different. In the case of `WM_COMMAND`, this is just the command code (equivalent to `HIWORD(wParam)` in a real `WM_COMMAND` handler). In the case of `WM_NOTIFY`, this is the `NMHDR` of the notification (equivalent to `(NMHDR *) lParam` in a real `WM_NOTIFY` handler). - -The trackbar doesn't use `WM_COMMAND` at all, so we can simply return `FALSE` for that one: - -```c -static BOOL onWM_COMMAND(uiControl *c, WORD code, LRESULT *lResult) -{ - return FALSE; -} -``` - -A trackbar *does* use `WM_NOTIFY`, however. For the purposes of this example, we won't be processing notifications. If you were to add some event, such as `OnChanged()`, you would handle that here (in this case, via `xxTODOxxx`). - -```c -static BOOL onWM_NOTIFY(uiControl *c, NMHDR *nm, LRESULT *lResult) -{ - return FALSE; -} -``` - -ok TODO this was a bad example diff --git a/docs/uiButton.md b/docs/uiButton.md deleted file mode 100644 index 7a68dc23..00000000 --- a/docs/uiButton.md +++ /dev/null @@ -1,41 +0,0 @@ -# uiButton - -uiButton is a control which represents a clickable button. - -Windows | Unix | OS X ------|-----|----- -![Button on Windows](images/uiButton_windows.png)|![Button on Unix](images/uiButton_unix.png)|![Button on OS X](images/uiButton_darwin.png) - -uiButton derives from [uiControl](uiControl.md). - -## constructor NewButton() -```c -uiButton *uiNewButton(const char *text); -``` -Creates a new uiButton with the specifed text. - -## func Text() -```c -char *uiButtonText(uiButton *b); -``` -Returns the text shown on the uiButton. Free the returned string with `uiTextFree()`. - -## func SetText() -```c -void uiButtonSetText(uiButton *b, const char *text); -``` -Changes the text shown on the uiButton to the given text string. - -## func OnClicked() -```c -void uiButtonOnClicked(uiButton *b, void (*handler)(void *sender, void *data), void *data); -``` -Sets the function that is called when the user clicks the uiButton. If a handler was previously assigned, this call replaces the old handler with the given one. - -The `sender` argument to the callback is the `b` argument to `uiButtonOnClicked()`. It is of type `void *` to allow uiMenuItems to use the same callback functions. - -The `data` argument to the callback is the `data` argument to `uiButtonOnClicked()`. - -The default handler does nothing. - -TODO allow NULL to return to default? diff --git a/docs/uiCheckbox.md b/docs/uiCheckbox.md deleted file mode 100644 index b5f316c5..00000000 --- a/docs/uiCheckbox.md +++ /dev/null @@ -1,55 +0,0 @@ -# uiCheckbox - -uiCheckbox is a control which represents a box that can have a checkmark in it. - -Windows | Unix | OS X ------|-----|----- -![Checkbox on Windows](images/uiCheckbox_windows.png)|![Checkbox on Unix](images/uiCheckbox_unix.png)|![Checkbox on OS X](images/uiChekbox_darwin.png) - -uiCheckbox derives from [uiControl](uiControl.md). - -## constructor NewCheckbox() -```c -uiCheckbox *uiNewCheckbox(const char *text); -``` -Creates a new uiCheckbox with the specifed text. - -## func Text() -```c -char *uiCheckboxText(uiCheckbox *c); -``` -Returns the text shown on the uiCheckbox. Free the returned string with `uiTextFree()`. - -## func SetText() -```c -void uiCheckboxSetText(uiCheckbox *c, const char *text); -``` -Changes the text shown on the uiCheckbox to the given text string. - -## func OnToggled() -```c -void uiCheckboxOnToggled(uiCheckbox *c, void (*handler)(void *sender, void *data), void *data); -``` -Sets the function that is called when the user changes the checked state of the uiCheckbox. If a handler was previously assigned, this call replaces the old handler with the given one. - -The `sender` argument to the callback is the `c` argument to `uiCheckboxOnToggled()`. It is of type `void *` to allow uiMenuItems to use the same callback functions. - -The `data` argument to the callback is the `data` argument to `uiCheckboxOnToggled()`. - -The default handler does nothing. - -TODO allow NULL to return to default? - -## func Checked() -```c -int uiCheckboxChecked(uiCheckbox *c); -``` -Returns nonzero if the given uiCheckbox is currently chcecked, and zero otherwise. - -## func SetChecked() -```c -void uiCheckboxSetChecked(uiCheckbox *c, int checked) -``` -Changes the checked state of the given uiCheckbox. If `checked` is nonzero, the checkbox is checked. If zero, the checkbox is unchecked. - -Calling `uiCheckboxSetChecked()` does NOT trigger the `OnToggled()` event. diff --git a/docs/uiEntry.md b/docs/uiEntry.md deleted file mode 100644 index e70c1b35..00000000 --- a/docs/uiEntry.md +++ /dev/null @@ -1,27 +0,0 @@ -# uiEntry - -uiEntry is a control which represents an area where a user can enter a single line of text. - -Windows | Unix | OS X ------|-----|----- -![Entry on Windows](images/uiEntry_windows.png)|![Entry on Unix](images/uiEntry_unix.png)|![Entry on OS X](images/uiEntry_darwin.png) - -uiEntry derives from [uiControl](uiControl.md). - -## constructor NewEntry() -```c -uiEntry *uiNewEntry(void); -``` -Creates a new uiEntry. - -## func Text() -```c -char *uiEntryText(uiEntry *e); -``` -Returns the text currently entered in the uiEntry. Free the returned string with `uiTextFree()`. - -## func SetText() -```c -void uiEntrySetText(uiEntry *e, const char *text); -``` -Changes the text currently entered in the uiEntry to the given text string. diff --git a/docs/uiLabel.md b/docs/uiLabel.md deleted file mode 100644 index 058f2ff5..00000000 --- a/docs/uiLabel.md +++ /dev/null @@ -1,27 +0,0 @@ -# uiLabel - -uiLabel is a control which represents a line of text that labels an element or area of a GUI. - -Windows | Unix | OS X ------|-----|----- -![Label on Windows](images/uiLabel_windows.png)|![Label on Unix](images/uiLabel_unix.png)|![Label on OS X](images/uiLabel_darwin.png) - -uiLabel derives from [uiControl](uiControl.md). - -## constructor NewLabel() -```c -uiLabel *uiNewLabel(const char *text); -``` -Creates a new uiLabel with the specifed text. - -## func Text() -```c -char *uiLabelText(uiLabel *l); -``` -Returns the text shown on the uiLabel. Free the returned string with `uiTextFree()`. - -## func SetText() -```c -void uiLabelSetText(uiLabel *l, const char *text); -``` -Changes the text shown on the uiLabel to the given text string. diff --git a/docs/uiOSContainer.md b/docs/uiOSContainer.md deleted file mode 100644 index 698cdf4e..00000000 --- a/docs/uiOSContainer.md +++ /dev/null @@ -1,50 +0,0 @@ -# uiOSContainer -uiOSContainer is an interface that is used by uiWindow, uiTab, and uiGroup to hold all the OS control handles of a tree of uiControls. That is, when you add a uiControl to a uiWindow, uiTab, or uiGroup, its OS control handle (if any) and the OS control handles of its children (when applicable) are added to the OS control handle of the uiOSContainer. This is what allows uiWindow, uiTab, and uiGroup to hold more than one uiControl from the point of view of the OS. - -Note that the control hierarchy is flattened; that is, there is no unique uiOSContainer allocated to every single uiBox, uiGrid, or uiStack. This is to deal with systems where OS control handles are valuable. - -## field Internal -```c -void *Internal; -``` -This pointer is used internally by libui. Do not attempt to alter it or access/alter its data. - -## func Destroy() -```c -void uiOSContainerDestroy(uiOSContainer *p); -``` -Destroys the uiOSContainer. This also destroys the main child, if any. This is called by `uiWindowDestroy()` and uiTab's/uiGroup's `uiControlDestroy()`. - -## func Handle() -```c -uintptr_t uiOSContainerHandle(uiOSContainer *p); -``` -Returns the OS control handle that is backed by this uiOSContainer. On Windows, this is a HWND. On Unix, this is a GtkContainer. On Mac OS X, this is a NSView. The actual class types of this handle is internal to libui; you should only attempt to use this handle as if it was an instance of the specified classes or of their superclasses (GtkWidget, etc.). - -## func SetMainControl() -```c -void uiOSContainerSetMainControl(uiOSContainer *p, uiControl *c); -``` -Sets the main control of a uiOSContainer. The *main control* is the uiControl that represnets the root of the control hierarchy that a uiOSContainer is managing. This is the only ontrol that the uiOSContainer knows about directly; all children of this uiControl are handled transparently through the uiControl. For example, when the uiWindow, uiTab, or uiGroup holding this uiOSContainer is resized, the uiOSContainer resizes the main control, which in turn resizes its children. - -If the main control is already set, `SetMainControl()` replaces the main control. The old main control is NOT destroyed; its parent is merely set to `NULL` (and from there, all of the old main control's children's parents are also set to `NULL`). - -If `c` is `NULL`, the main control is unset. Otherwise, `SetMainControl()` sets the parent of `c` to itself, triggering a `uiControlSetParent()` of all of `c`'s children. - -`SetMainControl()` does not automatically update the uiOSContainer. - -## func SetMargins() -```c -void uiOSContainerSetMargins(uiOSContainer *p, intmax_t left, intmax_t top, intmax_t right, intmax_t bottom); -``` -Sets the margins that the uiOSContainer will give to the main control when it is resized. The units of the margins are defined by the backend (for the Windows backend, these are in dialog units; for the Unix and OS X backends, these are in pixels). - -The initial margins are all zero. - -`SetMargins()` does not automatically update the uiOSContainer. - -## func Update() -```c -void uiOSContainerUpdate(uiOSContainer *p); -``` -Tells the uiOSContainer to update itself in place. The main control is resized according to the uiOSContainer's size.