smgui/docs/en/inputs.md

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.