inputs.md 8.6 KB
Inputs
Text
Draws a text input box. The buffer should store an editable UTF-8 string. Normally it accepts all keys as input except
control characters, but you can further filter the keys: UI_FILTER_ID (a UNIX id), UI_FILTER_VAR (a variable name,
same as UNIX id but first character can't be 0-9), UI_FILTER_EXPR (an expression, same as variable plus parenthesis
and operators), and UI_FILTER_HEX (only allows hexadecimal 0-9A-F keys). The UI_FILTER_PASS filters not the input,
but the output, displays asterisks. Copy'n'paste works too. If the ui_textosk.h module is included, then on input
an on-screen keyboard is displayed from software, otherwise OS-native OSK is only shown if the platform supports it.
| Parameter | Description |
|---|---|
form->type |
UI_TEXT |
form->ptr |
Pointer to a buffer |
form->max |
Size of the buffer |
form->inc |
0 for all, or a UI_FILTER_x key filter |
Selectbox
Draws a selectbox. When the users clicks on it, opens a selection popup.
| Parameter | Description |
|---|---|
form->type |
UI_SELECT |
form->ptr |
Pointer to an int value |
form->optc |
Maximum value plus 1, number of options |
form->optv |
Pointer to a string array, options |
form->m |
Right margin |
Optionlist
Draws an option selector. Same as a selectbox, just with a number input box visual, no popup.
| Parameter | Description |
|---|---|
form->type |
UI_OPTION |
form->ptr |
Pointer to an int value |
form->optc |
Maximum value plus 1, number of options |
form->optv |
Pointer to a string array, options |
form->m |
Left and right margin |
Float
Draws a floating point number input box.
| Parameter | Description |
|---|---|
form->type |
UI_FLOAT |
form->ptr |
Pointer to the value |
form->fmin |
Minimum value |
form->fmax |
Maximum value |
form->finc |
Increment value |
form->m |
Left and right margin |
Integer
Draws an integer input box. The number in the define specifies how many bits used to store the variable.
| Parameter | Description |
|---|---|
form->type |
UI_INT8 / UI_INT16 / UI_INT32 / UI_INT64 |
form->ptr |
Pointer to the value |
form->min |
Minimum value |
form->max |
Maximum value |
form->inc |
Increment value |
form->m |
Left and right margin |
Slider
Draws an integer slider box (32 bit only).
| Parameter | Description |
|---|---|
form->type |
UI_SLIDER |
form->ptr |
Pointer to the int value |
form->min |
Minimum value |
form->max |
Maximum value |
form->inc |
Increment value |
Vertical Scrollbar
Draws an integer as a vertical scroll bar (32 bit only). The [containers] have their own scrollbars, so this is only if you want to use for whatever other reason.
| Parameter | Description |
|---|---|
form->type |
UI_VSCRBAR |
form->ptr |
Pointer to the int value |
form->max |
Maximum value |
Horizontal Scrollbar
Draws an integer as a horizontal scroll bar (32 bit only).
| Parameter | Description |
|---|---|
form->type |
UI_HSCRBAR |
form->ptr |
Pointer to the int value |
form->max |
Maximum value |
Color
Draws an integer as color (32 bit only). When the users clicks on it, opens a color picker.
| Parameter | Description |
|---|---|
form->type |
UI_COLOR |
form->ptr |
Pointer to the int value |
File
Draws a text input box. The buffer should store an editable UTF-8 string, a file path. When the user clicks on it, opens a
[path] picker, which can be used to easily edit the string. See the description of the str parameter there. Requires including
the ui_file.h module.
| Parameter | Description |
|---|---|
form->type |
UI_FILE |
form->ptr |
Pointer to a buffer with path |
form->max |
Size of the buffer |
form->min |
Minimum height of the path picker |
form->str |
Index to the localized strings array (or 0) |
Path
Draws a path picker. The str parameter is the first index in the localized strings array of 8 strings, which must contain:
file name, size, modification date/time, just now, N minutes ago, an hour ago, N hours ago, yesterday. Requires including the
ui_file.h module.
| Parameter | Description |
|---|---|
form->type |
UI_PATH |
form->ptr |
Pointer to a buffer with path |
form->max |
Size of the buffer |
form->str |
Index to the localized strings array (or 0) |
form->data |
Pointer to an ui_path_t context |
The ui_path_t structure looks like:
| Field | Description |
|---|---|
flags |
Path flags |
exts |
Extension list (or NULL) |
select |
Selection okay callback (or NULL) |
The flags are:
| Define | Description |
|---|---|
UI_PATH_SEARCH |
Display a search field too |
UI_PATH_NEWDIR |
Display an add new directory button |
UI_PATH_ONLYDIR |
Only list directories |
UI_PATH_HIDDEN |
Display hidden files too |
The extension list is a zero terminated string list, and the whole string is terminated by two null bytes, for example
png\0jpg\0\0. If given, then only files with extensions listed here are shown.
If the select callback is NULL, then simply sub-directories are entered, and files are returned. If it's given with
typedef int (*ui_form_select)(char *path, int isdir);
then it's supposed to return 1 if the selected path should be returned, or 0 if not. If 0 returned, then sub-directories are
entered and nothing happens with files. The path argument ends in a directory separator if it's a directory and then isdir
is 1. This can be used to add a further criteria to selecting a path, like a directory containing a certain file or a file
starting with a certain magic or not. The callback might implement whatever additional checks it wants.