### JSFX UI: Hello World Example

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

A basic example demonstrating how to import the UI library, set it up in @init, and draw "Hello, world!" text in @gfx. Ensure the library is imported and memory is allocated before use.

```jsfx
desc:JSFX UI: Hello World
import ui-lib.jsfx-inc

@init
freemem = ui_setup(0);

@gfx
ui_start();
ui_text("Hello, world!");
```

--------------------------------

### Initialize UI Setup

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Sets up the UI environment, including screen stacking, drawing configurations, and resource reservations. It ensures the UI is properly initialized based on the provided stack start point.

```jsfx
function ui_setup(stackstart) local(uix_screenstack_end, uix_drawconfig_end) (
	// Mitigate some gnarly behaviour - see uix_prev_srate at top
	!srate ? (
		srate = uix_prev_srate;
		debug.gnarly_srate_hack += 1;
	);
	uix_prev_srate = srate;

	!uix_hassetup || stackstart != uix_screenstack ? (
		uix_hassetup = 1;

		uix_screenstack = stackstart;
		uix_screenstack_currentlayer = 0;
		uix_screenstack_end = stackstart + uix_screenstack_step*uix_screenstack_layercount;

		uix_drawconfig = uix_screenstack_end;
		uix_drawconfig_end = uix_drawconfig + uix_drawconfig_step*uix_drawconfig_count;
		uix_reserved_end = uix_drawconfig_end;

		uix_screen_reservations = uix_reserved_end;
		uix_reserved_end += 128;

		// Stop the pre-processor complaining
		UI_SPLIT_DIRECTION##;
	);

	uix_reserved_end;
);
```

--------------------------------

### JSFX-UI Hello World Example

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/1 - Hello World.md

This is the complete 'Hello World' example for JSFX-UI. It includes importing the library, setting up memory, and drawing text.

```eel2
desc:JSFX UI: Hello World
import ui-lib.jsfx-inc

@init
freemem = ui_setup(0);

@gfx
ui_start();
ui_text("Hello, world!");

```

--------------------------------

### JSFX UI: No Layout Example

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Demonstrates basic UI element drawing without explicit layout management. Requires ui-lib.jsfx-inc. Use in @init for setup and @gfx for drawing.

```jsfx
desc:JSFX UI: No Layout
import ui-lib.jsfx-inc

@init
freemem = ui_setup(0);
strcpy(#text, "button text");

@gfx
ui_start();

// Set the viewport
ui_set_rect(20, 20, 200, 50);
// Draw a control
control_button(#text);

// And again
ui_set_rect(20, 100, 50, 50);
value = control_dial(value, 0, 1);

// And again
ui_set_rect(20, 180, 200, 50);
inputstate = control_textinput(#text, inputstate);
```

--------------------------------

### Initialize UI Start

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Initializes the UI for interaction, setting up drawing parameters, handling mouse and scroll input, and managing click events. This function should be called at the start of the UI loop.

```jsfx
function ui_start(defaultScreen) local(i, click, clickdelta, imgW, imgH, retina_scaling) (
	uix_drawconfig_currentindex = 0;
	uix_drawconfig_current = uix_drawconfig;

	uix_hassetup ? (
		!ui_screen() ? (
			uix_screenstack_currentlayer = 0;
			i = 0;
			while (
				uix_screenstack[i] = 0;
				i += 1;
				i < uix_screenstack_step;
			);
			uix_screenstack[0] = defaultScreen;
		);

		gfx_dest = -1; // Draw to main screen
		gfx_mode = 0;
		gfx_a = 1;
		// Default colours
		gfx_clear = uix_clearcolor(242, 242, 242);

		retina_scaling = gfx_ext_retina ? gfx_ext_retina : 1;
		uix_drawconfig_current[uix_DRAWCONFIG#RETINA_SCALING] = retina_scaling;

		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_SCREEN] = -1;
		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_LEFT] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_WIDTH] = gfx_w;
		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_TOP] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_HEIGHT] = gfx_h;
		uix_drawconfig_current[uix_DRAWCONFIG#CLIP_ALPHA] = 1;

		uix_drawconfig_current[uix_DRAWCONFIG#RED] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#GREEN] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#BLUE] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#ALPHA] = 1;

		uix_drawconfig_current[uix_DRAWCONFIG#LEFT] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#TOP] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#WIDTH] = gfx_w/retina_scaling;
		uix_drawconfig_current[uix_DRAWCONFIG#HEIGHT] = gfx_h/retina_scaling;
		uix_drawconfig_current[uix_DRAWCONFIG#HALIGN] = 0.5;
		uix_drawconfig_current[uix_DRAWCONFIG#VALIGN] = 0.5;
		uix_drawconfig_current[uix_DRAWCONFIG#HPADDING] = 10;
		uix_drawconfig_current[uix_DRAWCONFIG#VPADDING] = 8;

		uix_drawconfig_current[uix_DRAWCONFIG#FONTINDEX] = 16;
		uix_drawconfig_current[uix_DRAWCONFIG#FONTFACE] = uix_default_fontface;
		uix_drawconfig_current[uix_DRAWCONFIG#FONTSIZE] = uix_default_fontsize;
		uix_drawconfig_current[uix_DRAWCONFIG#FONTBOLD] = 0;
		uix_drawconfig_current[uix_DRAWCONFIG#FONTITALIC] = 0;

		uix_font_dirty = 1;
		uix_setgfxfont();

		uix_interacted = (!!mouse_cap) || (mouse_cap != uix_mousecap_prev);
		uix_undo_pending ? (
			sliderchange(-1);
			uix_undo_pending = 0;
		);

		uix_prev_mouse_x = uix_mouse_x;
		uix_prev_mouse_y = uix_mouse_y;
		uix_mouse_x = mouse_x/retina_scaling;
		uix_mouse_y = mouse_y/retina_scaling;
		(mouse_cap&67) && (uix_mouse_x != uix_prev_mouse_x || uix_mouse_y != uix_prev_mouse_y) ? uix_interacted = 1;

		uix_scroll_y = mouse_wheel;
		uix_scroll_x = mouse_hwheel;
		mouse_wheel = mouse_hwheel = 0;
		uix_scroll_y || uix_scroll_x ? uix_interacted = 1;

		uix_unclick1 = (!(mouse_cap&1) && uix_mousecap_prev&1);
		uix_click1 = (mouse_cap&1 && !(uix_mousecap_prev&1)) ? (
			clickdelta = time_precise() - uix_click1_t;
			uix_click1_x = uix_mouse_x;
			uix_click1_y = uix_mouse_y;
			uix_click1 = 1;
			uix_click1_t = time_precise() - 0.001;
			clickdelta < uix_doubleclicktime ? (
				uix_click1count += 1;
			) : (
				uix_click1count = 1;
			);

		);
		uix_unclick2 = (!(mouse_cap&2) && uix_mousecap_prev&2);
		uix_click2 = (mouse_cap&2 && !(uix_mousecap_prev&2)) ? (
			clickdelta = time_precise() - uix_click2_t;
			uix_click2 = 1;
			uix_click2_x = uix_mouse_x;
			uix_click2_y = uix_mouse_y;
			uix_click2_t = time_precise() - 0.001;
			clickdelta < uix_doubleclicktime ? (
				uix_click2count += 1;
			) : (
				uix_click2count = 1;
			);
		);
		uix_unclick64 = (!(mouse_cap&64) && uix_mousecap_prev&64);
		uix_click64 = (mouse_cap&64 && !(uix_mousecap_prev&64)) ? (
			clickdelta = time_precise() - uix_click64_t;
			uix_click64 = 1;
			uix_click64_x = uix_mouse_x;
			uix_click64_y = uix_mouse_y;
			uix_click64_t = time_precise() - 0.001;
			clickdelta < uix_doubleclicktime ? (
				uix_click64count += 1;
			) : (
				uix_click64count = 1;
			);
		);
		uix_mousecap_prev = mouse_cap;

		uix_mouseblocked ? uix_click_block(); // Must be first, so unclick events get removed too
		!(mouse_cap&1) && !(mouse_cap&2) && !(mouse_cap&64) ? uix_mouseblocked = 0;

		// Keyboard
	);
);
```

--------------------------------

### Screen Management and Arguments

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Functions for starting, managing, and interacting with UI screens and their arguments.

```APIDOC
## POST /ui/screen

### Description
Manages UI screens, including starting, opening, closing, and retrieving the current screen.

### Method
POST

### Endpoint
/ui/screen

### Parameters
#### Query Parameters
- **action** (string) - Required - The action to perform (e.g., "start", "open", "close", "get").
- **screen_id** (string) - Optional - The ID of the screen to open or manage.
- **args** (object) - Optional - Arguments to pass to the screen.

### Request Example
```json
{
  "action": "open",
  "screen_id": "secondary",
  "args": {
    "param1": "value1"
  }
}
```

### Response
#### Success Response (200)
- **current_screen** (string) - The ID of the current screen.
- **screen_level** (integer) - The current depth of the screen stack.

#### Response Example
```json
{
  "current_screen": "main",
  "screen_level": 0
}
```
```

```APIDOC
## GET /ui/screen/level

### Description
Retrieves the current depth of the screen stack.

### Method
GET

### Endpoint
/ui/screen/level

### Response
#### Success Response (200)
- **depth** (integer) - The number of screens deep in the current stack (0 is the top level).

#### Response Example
```json
{
  "depth": 1
}
```
```

```APIDOC
## GET /ui/screen/arg

### Description
Retrieves a screen argument at a specific index.

### Method
GET

### Endpoint
/ui/screen/arg

### Parameters
#### Query Parameters
- **index** (integer) - Required - The index of the argument to retrieve (0-9).

### Response
#### Success Response (200)
- **value** (any) - The value of the screen argument.

#### Response Example
```json
{
  "value": "some_value"
}
```
```

```APIDOC
## POST /ui/screen/arg

### Description
Sets a screen argument at a specific index. This should be called after `ui_screen_open()` when setting arguments for a new screen.

### Method
POST

### Endpoint
/ui/screen/arg

### Parameters
#### Query Parameters
- **index** (integer) - Required - The index of the argument to set (0-9).
- **value** (any) - Required - The value to set for the argument.

### Request Example
```json
{
  "index": 0,
  "value": "new_argument_value"
}
```
```

--------------------------------

### ui_start / control_start

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Resets the UI state for the start of each frame. Must be called in @gfx.

```APIDOC
## ui_start / control_start

### Description
Resets the UI state for the start of each frame. Must be called in @gfx before any other UI code.

### Parameters
- **default_screen** (string) - Required - The default screen identifier.
- **theme** (string) - Optional - Theme name: "default", "tron", or "black" (for control_start only).
```

--------------------------------

### Initialize JSFX UI Library

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Required setup in the @init and @gfx blocks to allocate memory and reset the UI state for each frame.

```eel2
desc:My JSFX Plugin
import ui-lib.jsfx-inc

@init
// Allocate memory starting at index 0
// Returns first unused memory slot
freemem = ui_setup(0);

// If you have your own buffers, start them after freemem
buffer0 = freemem;
buffer1 = freemem + 1024;
freemem += 2048;

@gfx
// Reset UI state for each frame with default screen
ui_start("main");

// Or use control_start() to select a theme: "default", "tron", or "black"
// control_start("main", "tron");

ui_screen() == "main" ? (
    ui_text("Hello, world!");
) : ui_system();
```

--------------------------------

### JSFX UI Setup in @init

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/generate-ui.html

This code demonstrates how to set up the UI library in the @init section of your JSFX code. Ensure you allocate memory and call ui_setup.

```jsfx
@init
freemem = 0; // some empty section of the memory buffer
freemem = ui_setup(freemem); // returns the first index it's not using
```

--------------------------------

### Start UI Frame Initialization

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/1 - Hello World.md

Initialize the UI library for each frame by calling ui_start() at the beginning of the @gfx section. This ensures the UI is reset for rendering.

```eel2
@gfx
ui_start();

```

--------------------------------

### UI System Initialization and Error Handling

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Handles the main UI loop, checks for setup completion, and displays errors if ui_setup() has not been called. It also manages screen transitions.

```jsfx
!uix_latestchar || !uix_char_consumed ? (
			uix_latestchar = gfx_getchar();
			uix_latestchar == -1 ? uix_latestchar = 0;
		);
		uix_char_consumed = 0;

		uix_latestchar ? uix_interacted = 1;
	) : (
			uix_error = "ui_setup() has not been called";
	);
);
```

--------------------------------

### Basic Row Annotation

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/generate-ui.html

Starts a new row in the UI layout.

```jsfx
// ui:row
```

--------------------------------

### Allocate Custom Audio Buffers

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/1 - Hello World.md

When allocating custom audio buffers, ensure they are placed after the memory allocated by ui_setup() or provide a custom starting memory address to ui_setup().

```eel2
@init
freemem = ui_setup(0);
// Allocate two buffers of length 1024
buffer0 = freemem;
buffer1 = freemem + 1024;
freemem += 2048;

```

```eel2
@init
// Two buffers of length 1024
buffer0 = 0;
buffer1 = 1024;
// Next free memory slot is 2048
ui_setup(2048);

```

--------------------------------

### Initialize UI Control Theme

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Initializes the UI control theme based on the provided theme name and image buffer. Handles theme-specific setup and rendering.

```jsfx
function control_start(defaultPage, theme, imageBuffer) local(reset, i, x, y) (
	ui_start(defaultPage);
	// TODO: check retina here?
	reset = (uix_control_theme_prev != theme || uix_control_width_prev != gfx_w || uix_control_height_prev != gfx_h);
	uix_control_theme_prev = theme;
	uix_control_width_prev = gfx_w;
	uix_control_height_prev = gfx_h;

	theme == "black" ? (
		uix_control_theme = uix_THEME#BLACK_AND_WHITE(1);
		gfx_clear = 0;
		ui_color(255, 255, 255);
		ui_fontface("Trebuchet MS");
		ui_fontsize(20);
		ui_padding(10, 10);
	) : theme == "tron" ? (
		uix_control_theme = uix_THEME#TRON;
		gfx_clear = $x454545;
		reset ? (
			gfx_setimgdim(uix_control_reserved_screen, gfx_w, gfx_h);
			gfx_dest = uix_control_reserved_screen;
			ui_color(70, 70, 70);
			ui_fill();
			ui_color(67, 67, 67);
			gfx_y = 0;
			while (gfx_y < gfx_h) (
				gfx_line(0, gfx_y, gfx_w, gfx_y);
				gfx_y += 2;
			);
			gfx_dest = -1;
		);
		gfx_x = gfx_y = 0;
		gfx_blit(uix_control_reserved_screen, 1, 0);
		ui_color(245, 255, 255);
		ui_fontface("Verdana");
	) : theme == "bitmap-simple" ? (
		uix_control_theme = uix_THEME#BITMAP_SIMPLE;
		uix_control_theme_buffer = imageBuffer;

		y = 0;
		while (y < gfx_h) (
			x = 0;
			while (x < gfx_w) (
				gfx_blit(uix_control_theme_buffer, ui_retina(), 0, 20, 20, 120, 120, x, y);
				x += 120*ui_retina();
			);
			y += 120;
		);

		uix_control_color_from_theme(151, 30);
	) : (
		uix_control_theme = uix_THEME#DEFAULT;
		//ui_color(242, 242, 242);
	);
);
```

```jsfx
function control_start(defaultPage, theme) (
	control_start(defaultPage, theme, 0);
);
```

--------------------------------

### Enabling Retina Display Support with gfx_ext_retina

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Enable retina support and handle pixel scaling for custom drawing operations. Use ui_retina() to get the current scale and temporarily set it for precise pixel control.

```eel2
@gfx
gfx_ext_retina = 1;  // Enable retina support

ui_start("main");

// ui_retina() returns current pixel scale (1 or 2)
scale = ui_retina();

// For custom drawing, temporarily set 1:1 pixel scale
ui_push();
    old_scale = ui_retina(1);

    // Now viewport coordinates are in actual pixels
    gfx_circle(ui_left() + ui_width()/2,
               ui_top() + ui_height()/2,
               20, 1);

    // Restore previous scale
    ui_retina(old_scale);
ui_pop();

// Mouse functions remain scaled down for consistency
x_ratio = ui_mouse_xratio();  // Still 0-1 regardless of retina

```

--------------------------------

### Draw Custom Themed Controls

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

This example demonstrates how to draw custom themed controls with different states like enabled, disabled, passive, inset, and technical. It utilizes ui_split_topratio, ui_pad, control_background_*, ui_text, control_finish_*, and ui_split_next functions.

```javascript
ui_split_topratio(1/5);
	ui_pad();
	control_background_enabled(state);
	ui_text("enabled");
	control_finish_enabled(state);
ui_split_next();
	ui_pad();
	control_background_disabled(state);
	ui_text("disabled");
	control_finish_disabled(state);
ui_split_next();
	ui_pad();
	control_background_passive(state);
	ui_text("passive");
	control_finish_passive(state);
ui_split_next();
	ui_pad();
	control_background_inset(state);
	ui_text("inset");
	control_finish_inset(state);
ui_split_next();
	ui_pad();
	control_background_technical(state);
	ui_text("technical");
	control_finish_technical(state);
ui_split_next();
	ui_pop();
```

--------------------------------

### Create Horizontal, Vertical, and Dial Controls

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/3 - Controls.md

Example of implementing different slider types and a dial, using layout functions to constrain their size.

```eel2
ui_pad();
ui_split_bottom(30);
	slider1 = control_hslider(slider1, 0, 100, 0);
ui_pop();

ui_padbottom();
ui_split_left(30);
	slider1 = control_vslider(slider1, 0, 100, 0);
ui_pop();

ui_push_height(50);
	slider1 = control_dial(slider1, 0, 100, 0);
ui_pop();
```

--------------------------------

### Start UI Frame with Default Screen

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Resets UI state for a new frame. Must be called in @gfx before other UI code. Accepts a default screen identifier.

```jsfx
@gfx

ui_start("main");
```

--------------------------------

### Handle Retina Scaling for Custom Controls

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Example demonstrating how to manage retina scaling for custom UI elements. It resets the scale to 1-to-1, draws using the adjusted viewport, and then restores the original scale.

```javascript
// Reset to 1-to-1 scale
old_pixel_scale = ui_retina(1);

/* Draw something using viewport */
gfx_rect(ui_left(), ui_top(), ...);

//Set back to the old one
ui_retina(old_pixel_scale);

/* Logic involving mouse-pointer */
xratio = ui_mouse_xratio();
```

--------------------------------

### Start UI Frame with Themed Screen

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Resets UI state for a new frame with a specified theme. Must be called in @gfx before other UI code. Available themes: "default", "tron", "black".

```jsfx
@gfx

control_start("main", "tron")
```

--------------------------------

### Create Slider Controls with Different Curves

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

This example shows how to create horizontal sliders with varying curve parameters to control the value-to-position mapping. It includes sliders with positive, negative, and zero curve values, as well as a slider_x variant.

```javascript
ui_split_topratio(1/4);
	ui_split_left(70);
		ui_text("curve=0");
	ui_pop();
	value = control_slider_left(value, 0, 1, 0, 0.5);
ui_split_next();
	ui_split_left(70);
		ui_text("curve=2");
	ui_pop();
	value = control_slider_left(value, 0, 1, 2, 0.5);
ui_split_next();
	ui_split_left(70);
		ui_text("curve=-2");
	ui_pop();
	value = control_slider_left(value, 0, 1, -2, 0.5);
ui_split_next();
	ui_split_left(70);
		ui_text("slider_x");
	ui_pop();
	value = control_slider_x(value, 0, 1, 0, 0.5);
ui_pop();
```

--------------------------------

### ui_setup

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Initializes the memory buffer for the UI library. Must be called in @init.

```APIDOC
## ui_setup

### Description
Sets up a section of the memory buffer for use by the UI library. This must be called in @init before any other UI code.

### Parameters
- **freemem** (number) - Required - Index in the memory array.

### Response
- **new_freemem** (number) - The index of the first unused memory block.
```

--------------------------------

### Manage UI Screens

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Demonstrates basic screen navigation using ui_start, ui_screen, ui_screen_open, and ui_screen_close.

```JSFX
@gfx

ui_start("main");

ui_screen() == "main" ? (
	control_button("open screen") ? (
		ui_screen_open("secondary");
	);
) : ui_screen() == "secondary" ? (
	control_button("close screen") ? (
		ui_screen_close();
	);
) : ui_system();
```

--------------------------------

### Get Click Count

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the number of times an element has been clicked.

```jsfx
function ui_clickcount(i) (
	uix_clickcount(i);
);
```

--------------------------------

### Get Screen Depth

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the current depth of the screen stack.

```JSFX
depth = ui_screen_level()
```

```JSFX
depth = ui_screen_level();
```

--------------------------------

### Initialize UI Memory Allocation

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/1 - Hello World.md

Set up memory for the UI library in the @init section using ui_setup(). The return value indicates the next available memory slot.

```eel2
@init
freemem = ui_setup(0);

```

--------------------------------

### Named Group Annotation

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/generate-ui.html

Starts a new group and assigns it a specific name.

```jsfx
// ui:group name=Some Group Name
```

--------------------------------

### Basic Group Annotation

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/generate-ui.html

Starts a new group within the current row.

```jsfx
// ui:group
```

--------------------------------

### Get Latest Character Input

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Retrieves the most recent character input by the user.

```jsfx
function ui_key() (
	uix_latestchar;
);
```

--------------------------------

### Build the library using Node.js

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/README.md

Commands to assemble the final library code using the JSFX preprocessor.

```bash
node build.js
# or
npm run build
```

```bash
npm run nodemon -- ../my-jsfx-set/ui-lib.jsfx-inc
```

--------------------------------

### Text Width and Height

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Functions to get the width and height of rendered text.

```APIDOC
## GET /api/ui/text_width

### Description
Gets the width of the rendered text.

### Method
GET

### Endpoint
/api/ui/text_width

### Parameters
#### Query Parameters
- **#text** (string) - Required - The text to measure.

### Response
#### Success Response (200)
- **text_width** (integer) - The width of the text in pixels.

### Response Example
```json
{
  "text_width": 100
}
```

## GET /api/ui/text_height

### Description
Gets the height of the rendered text.

### Method
GET

### Endpoint
/api/ui/text_height

### Parameters
#### Query Parameters
- **#text** (string) - Required - The text to measure.

### Response
#### Success Response (200)
- **text_height** (integer) - The height of the text in pixels.

### Response Example
```json
{
  "text_height": 20
}
```
```

--------------------------------

### Define Default Screen

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/4 - Screens.md

Initialize the UI with a default screen identifier using ui_start.

```eel2
@gfx
ui_start("main"); // Our default screen is called "main"
```

--------------------------------

### Get Viewport Position

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Functions to retrieve the current viewport's boundaries and dimensions.

```APIDOC
## Get Viewport Position

### Description
These functions return the boundaries and dimensions of the current viewport. The right and bottom edges are the first pixels *not* included in the viewport.

### Methods
- `ui_left()`
- `ui_right()`
- `ui_top()`
- `ui_bottom()`
- `ui_width()`
- `ui_height()`

### Parameters
None

### Response
#### Success Response (200)
- **left_x** (integer) - The x-coordinate of the left edge.
- **right_x** (integer) - The x-coordinate of the right edge (exclusive).
- **top_y** (integer) - The y-coordinate of the top edge.
- **bottom_y** (integer) - The y-coordinate of the bottom edge (exclusive).
- **width** (integer) - The width of the viewport.
- **height** (integer) - The height of the viewport.

### Response Example
```
local left_x = ui_left()
local width = ui_width()
```
```

--------------------------------

### Get Mouse Delta Y

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the vertical distance the mouse has moved since the last frame.

```jsfx
function ui_mouse_dy() (
	uix_mouse_y - uix_prev_mouse_y;
);
```

--------------------------------

### Get Mouse Delta X

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the horizontal distance the mouse has moved since the last frame.

```jsfx
function ui_mouse_dx() (
	uix_mouse_x - uix_prev_mouse_x;
);
```

--------------------------------

### Draw UI Border

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Draws a border around UI elements. No specific setup or constraints are mentioned.

```javascript
ui_border();
```

--------------------------------

### Manage Screens

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Use ui_screen_open and ui_screen_close to navigate. Arguments can be passed between screens using ui_screen_arg.

```eel2
@gfx
ui_start("main");

ui_screen() == "main" ? (
    ui_split_topratio(0.5);
        control_button("Open Settings") ? (
            ui_screen_open("settings");
            ui_screen_arg(0, volume);  // Pass current volume as argument
        );
    ui_pop();

    sprintf(#vol, "Volume: %.0f", volume);
    ui_text(#vol);

) : ui_screen() == "settings" ? (
    // Read argument passed from main screen
    initial_volume = ui_screen_arg(0);

    ui_split_top(50);
        ui_text("Settings Screen");
    ui_pop();

    ui_split_bottom(50);
        control_button("Back") ? (
            ui_screen_close();
        );
    ui_pop();

    ui_push_height(40);
        volume = control_slider_left(volume, 0, 100, 0, initial_volume);
    ui_pop();

) : control_system();  // Handle unknown screens and built-in dialogs
```

--------------------------------

### Implement Buttons and Indicators

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/3 - Controls.md

Demonstrates using control_button and control_indicator_button to trigger logic based on user interaction.

```eel2
ui_split_top(50);
	control_button("+ 1") ? (
		press_counter += 1;
	);
ui_split_next();
	control_indicator_button("Reset", press_counter > 0) ? (
		press_counter = 0;
	);
ui_pop();

ui_textnumber(press_counter, "%i");
```

--------------------------------

### Get Horizontal Scroll Value

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the horizontal scroll amount if the mouse is hovering over the element, otherwise 0.

```jsfx
function ui_scroll_x() (
	ui_hover() ? uix_scroll_x : 0;
);
```

--------------------------------

### Get Vertical Scroll Value

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the vertical scroll amount if the mouse is hovering over the element, otherwise 0.

```jsfx
function ui_scroll_y() (
	ui_hover() ? uix_scroll_y : 0;
);
```

--------------------------------

### Layout with Buttons and Technical Graph

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/5 - Custom Graphics.md

Demonstrates using theme functions to create a consistent UI layout. control_button creates buttons, control_background_technical sets up a technical display background, and ui_graph draws the graph data. control_finish_technical applies the final styling.

```eel2
ui_split_bottom(50);
	// Button on left
	ui_split_left(50);
		control_button("Left");
	ui_pop();
	// Button on right
	ui_split_right(50);
		control_button("Right");
	ui_pop();
	
	// Fill the rest with a graph
	control_background_technical();
	ui_graph(buffer, buffer_length, -1, 1);
	control_finish_technical();
ui_pop();
```

--------------------------------

### Get Press Duration

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Calculates the duration a mouse button has been held down. Returns 0 if the mouse is not hovering or the button is not pressed.

```jsfx
function ui_press(i) (
	!i ? i = 1;
	ui_hover() && mouse_cap&i && uix_clickwasinside(i) ? (
		time_precise() - uix_click_t(i);
	) : 0;
);
```

--------------------------------

### Manage Viewport Stacks

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Use push and pop operations to create nested layouts and isolate styling changes like color and dimensions.

```eel2
@gfx
ui_start("main");

// Stack level 1: full screen
ui_push();
    // Stack level 2: modify color
    ui_color(255, 0, 255);
    ui_border();  // Draws purple border
ui_pop();

// Back to level 1: default color restored
ui_text("Default color text");

// Create nested viewports with specific dimensions
ui_push_height(50);
    ui_push_width(200);
        ui_color(0, 192, 255);
        ui_fill();
        ui_color(255, 255, 255);
        ui_text("Fixed size box");
    ui_pop();
ui_pop();
```

--------------------------------

### Basic UI Layout Elements

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Demonstrates the use of ui_border and ui_padding for structuring the UI layout. ui_pad is a shorthand for ui_padding.

```javascript
ui_border();
    
    ui_padding(pad_x, pad_y);
    ui_pad();
    
    ui_border();
```

--------------------------------

### Get Current Screen ID

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the ID of the currently displayed screen from the screen stack. Returns 'error' if the UI has not been set up.

```jsfx
function ui_screen() (
	uix_hassetup
		? (uix_screenstack + uix_screenstack_step*uix_screenstack_currentlayer)[0]
		: "error";
);
```

--------------------------------

### Initialize UI Drawing Configuration

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Sets up variables for drawing configuration, including step size, count, and current drawing state. Used for managing UI element appearance.

```jsfx
uix_drawconfig_step = uix_DRAWCONFIG##;
uix_drawconfig_count = 100;
```

--------------------------------

### Get Mouse Position

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the mouse cursor's position relative to the current viewport. Can be obtained in absolute pixels or as a ratio.

```jsfx
relative_x = ui_mouse_x()
relative_x = ui_mouse_xratio()
relative_x = ui_mouse_y()
relative_y = ui_mouse_yratio();
```

```jsfx
x = ui_mouse_x();
y = ui_mouse_y();
x_ratio = ui_mouse_xratio();
y_ratio = ui_mouse_yratio();
```

--------------------------------

### Get Text Dimensions

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the width and height of a given text element. Ensure the text element is properly defined before calling.

```jsfx
text_width = ui_text_width(#text);
text_height = ui_text_height(#text);
```

--------------------------------

### Import JSFX-UI Library

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/1 - Hello World.md

Import the JSFX-UI library by including 'ui-lib.jsfx-inc' in your effect's header. Ensure the file is in the same directory as your effect.

```eel2
desc:JSFX UI: Hello World

import ui-lib.jsfx-inc

```

--------------------------------

### Implement Multi-Screen Logic

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/4 - Screens.md

Use ui_screen to check the current screen identifier and render content accordingly.

```eel2
@gfx
ui_start("main");

ui_screen() == "main" ? (
	ui_text("Main screen");
) : ui_screen() == "second" ? (
	ui_text("Second screen");
);
```

--------------------------------

### Get Line Height

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the current height of a single line of text. This may reset gfx font parameters if necessary.

```javascript
line_height = ui_texth();
```

--------------------------------

### Draw a basic button

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/2 - The Viewport Stack.md

Initializes the UI and draws a button that fills the entire available viewport.

```eel2
@gfx
ui_start();

control_button("Press me");
```

--------------------------------

### Create Themed Custom Graphics

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Utilize `control_background_*()` and `control_finish_*()` functions to build custom UI controls that adhere to the current theme. This allows for consistent styling across different controls.

```eel2
@gfx
ui_start("main");

// Custom meter using "inset" style
ui_split_top(30);
    control_background_inset();

    // Draw meter fill
    ui_push();
        meter_width = ui_width() * meter_value;
        ui_set_rect(ui_left(), ui_top(), meter_width, ui_height());
        ui_color(0, 200, 100);
        ui_fill();
    ui_pop();

    control_finish_inset();
ui_pop();

// Custom graph using "technical" style
ui_split_bottom(100);
    control_background_technical();
    // Theme sets appropriate color for graph
    ui_graph(audio_buffer, buffer_length, -1, 1);
    control_finish_technical();
ui_pop();

// Custom button with shared state for composite control
ui_push_height(50);
    state = control_state();  // Get current interaction state

    ui_split_leftratio(0.5);
        control_background_enabled(state);
        ui_text("Left Half");
        control_finish_enabled(state);
    ui_pop();

    control_background_enabled(state);
    ui_text("Right Half");
    control_finish_enabled(state);

    // Both halves highlight together on hover/press
ui_pop();
```

--------------------------------

### Get Pixel Color from Theme Buffer

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Retrieves the color of a pixel from a specified theme buffer. Used internally for theme-specific color mapping.

```jsfx
function uix_control_color_from_theme(x, y, a) local(old_dest, r, g, b, old_x, old_y) (
	old_x = gfx_x;
	old_y = gfx_y;
	old_dest = gfx_dest;

	gfx_dest = uix_control_theme_buffer;
	gfx_x = x;
	gfx_y = y;
	gfx_getpixel(r, g, b);

	gfx_dest = old_dest;
	gfx_x = old_x;
	gfx_y = old_y;

	ui_color(r*255, g*255, b*255, a);
);
function uix_control_color_from_theme(x, y) (
	uix_control_color_from_theme(x, y, 1);
);
```

--------------------------------

### Get Latest Printable Character Input

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Retrieves the most recent character input if it is a printable ASCII character (32-126). Returns 0 otherwise.

```jsfx
function ui_key_printable() (
	uix_latestchar >= 32 && uix_latestchar < 127 ? (
		uix_latestchar;
	) : 0;
);
```

--------------------------------

### ui_screen_open

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Opens a new screen on top of the screen stack.

```APIDOC
## ui_screen_open

### Description
Opens a new screen on top of the stack of screens. The stack is limited to 10 layers deep.

### Parameters
- **screen_id** (string) - Required - The identifier of the screen to open.
```

--------------------------------

### Get Click Duration

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Calculates the duration of a completed click event. Returns 0 if the mouse is not up, the click was not inside the element, or the mouse is not hovering.

```jsfx
function ui_click(i) (
	ui_mouse_up(i) && uix_clickwasinside(i) && ui_hover() ? (
		time_precise() - uix_click_t(i);
	) : 0;
);
```

--------------------------------

### Get Screen Argument by Index

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Retrieves an argument from the current screen's stack based on its index. Returns an error if the index is out of bounds.

```jsfx
function ui_screen_arg(index) local(screen, offset) (
	screen = (uix_screenstack + uix_screenstack_step*uix_screenstack_currentlayer);
	offset = index + UI_SCREEN#;
	offset < uix_screenstack_step ? (
		screen[offset];
	) : (
		ui_error("Screens only have 10 arguments");
	);
);
```

--------------------------------

### Integrate Built-in System Screens

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/4 - Screens.md

Use control_system to handle unrecognized screen identifiers and provide built-in functionality.

```eel2
@gfx
ui_start("main");

ui_screen() == "main" ? (
	ui_text("Main screen");
) : ui_screen() == "second" ? (
	ui_text("Second screen");
) : control_system();
```

--------------------------------

### Get Current Viewport Dimensions

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the boundaries and dimensions of the current viewport. Note that right and bottom edges are the first pixels *not* included.

```javascript
left_x = ui_left()

right_x = ui_right()

top_y = ui_top()

bottom_y = ui_bottom()

width = ui_width()

height = ui_height()
```

--------------------------------

### Create element stacks with ui_split_next

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/2 - The Viewport Stack.md

Uses ui_split_next to reuse the previous split dimensions for subsequent elements in a layout.

```eel2
ui_split_bottom(50);
	control_button("Press me");
ui_split_next();
	control_button("Then press me");
ui_pop();
ui_text("Hello, world!");
```

--------------------------------

### Get Mouse Movement Delta

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Returns the change in mouse position (dx, dy) since the last frame. Useful for tracking mouse movement.

```jsfx
dx = ui_mouse_dx()
dy = ui_mouse_dy()
```

```jsfx
dx = ui_mouse_dx();
dy = ui_mouse_dy();

// Draw mouse movement
mx = mouse_x;
my = mouse_y;
gfx_line(mx, my, mx - dx, my - dy);
```

--------------------------------

### Layout Splitting with UI Controls

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Demonstrates using ui_split_topratio to divide the UI area and placing various dial controls within those splits.

```JSFX
ui_split_topratio(1/3);
	value = control_dial_left(value, 0, 1);
ui_split_next();
	value = control_dial(value, 0, 1);
ui_split_next();
	angle = control_dial_angle(angle, 0);
ui_pop();
```

--------------------------------

### Graphing Buffer Data with ui_graph()

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Visualize buffer data using ui_graph(). Supports circular buffers with an offset parameter and automatic scaling. Use for real-time data display.

```eel2
@init
freemem = ui_setup(0);
buffer = freemem;
buffer_length = 512;
freemem += buffer_length;

// Fill with sine wave
i = 0;
while (i < buffer_length) (
    buffer[i] = sin(i / buffer_length * 4 * $pi);
    i += 1;
);

@gfx
ui_start("main");

ui_split_topratio(0.5);
    control_background_technical();

    // Fixed Y range
    ui_color(0, 255, 128);
    ui_graph(buffer, buffer_length, -1, 1);

    control_finish_technical();
ui_pop();

ui_split_bottom(100);
    control_background_technical();

    // Auto-scaled (both values same = auto-scale around that value)
    ui_color(255, 128, 0);
    ui_graph(buffer, buffer_length, 0, 0);

    // Circular buffer with offset
    ui_color(128, 128, 255);
    ui_graph(buffer, buffer_length, write_index, buffer_length, -1, 1);

    control_finish_technical();
ui_pop();

```

--------------------------------

### Get Current Screen ID

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Returns the identifier of the current screen. Useful for conditional drawing based on the active screen. Should be called after ui_start() or control_start().

```jsfx
@gfx

ui_start("main");

ui_screen() == "main" ? (
	/* draw your main screen */
) : ui_system();
```

--------------------------------

### ui_push_height/width

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Functions to push a new viewport to the stack with a specified height or width.

```APIDOC
## ui_push_height / ui_push_width

### Description
These methods push a new viewport to the stack with a specified height or width, determined by current alignment.

### Parameters
#### Request Body
- **pixels** (integer) - Required - Size in pixels (>= 0)
- **ratio** (number) - Required - Size as a ratio (between 0 and 1)
- **#text** (string) - Required - Size based on text dimensions
```

--------------------------------

### Get Current Control State

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the current interaction state of a UI control (press, hover, drag, or none). Useful for state-dependent styling or behavior.

```jsfx
function control_state() (
	ui_press() ? "press" : ui_hover() ? "hover" : ui_drag() ? "drag" : "none";
);
```

--------------------------------

### Navigate Between Screens

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/4 - Screens.md

Manage the screen stack using ui_screen_open and ui_screen_close triggered by user interactions.

```eel2
@gfx
ui_start("main");

ui_screen() == "main" ? (
	control_button("Open second screen") ? (
		ui_screen_open("second");
	);
) : ui_screen() == "second" ? (
	control_button("Close screen") ? (
		ui_screen_close();
	);
) : control_system();
```

--------------------------------

### Get Control Interaction State

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Retrieves the current mouse interaction state of the control. The state can be 'press', 'hover', 'drag', or 'none', with 'press' having the highest precedence.

```javascript
state = control_state()
```

--------------------------------

### Handle Sample Rate Initialization Workaround

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Stores the previous sample rate to work around a potential JSFX bug where srate might be 0 in @init under specific conditions. This ensures accurate audio processing.

```jsfx
uix_prev_srate = 44100;
```

--------------------------------

### Handle Screen Arguments

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Sets or retrieves arguments for screens. When setting, call after ui_screen_open.

```JSFX
ui_screen_arg(index, value)
```

```JSFX
value = ui_screen_arg(index)
```

```JSFX
// Read argument for current screen
foobar = ui_screen_arg(0);

// Open new screen with argument
should_open_screen ? (
	ui_screen_open("screen2");
	ui_screen_arg(0, foobar);
);
```

--------------------------------

### Push and Pop Viewport State

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Demonstrates creating a nested state using ui_push and ui_pop to isolate UI changes.

```JSFX
// stack starts with just 1 state

ui_push();
	// stack is now 2 levels deep
	ui_color(255, 0, 255);
	ui_border(); // draws in purple
ui_pop();
// stack is now 1 deep again

// The colour change above applied
// to the state we popped off,
// so this draws in default colour
ui_text("some text");
```

--------------------------------

### Initialize UI Memory Buffer

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/doc/html/index.html

Sets up a memory buffer for UI elements. Must be called in @init before other UI code. Returns the index of the first unused memory slot.

```jsfx
@init

//Unused section of memory buffer
freemem = 0;

// Returns end of allocated block (first unused index)
freemem = ui_setup(freemem);
```

--------------------------------

### Get Current Screen Layer Depth

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/ui-lib.txt

Returns the current depth of the screen stack, indicating how many screens are currently open. Useful for managing UI flow.

```jsfx
function ui_screen_level() (
	uix_screenstack_currentlayer;
);
```

--------------------------------

### Implement Dialog Control

Source: https://context7.com/geraintluff/jsfx-ui-lib/llms.txt

Use control_dialog to create modal popups. It returns 1 for OK, -1 for cancel, and 0 if no action is taken.

```eel2
@gfx
ui_start("main");

ui_screen() == "main" ? (
    control_button("Show Dialog") ? (
        ui_screen_open("confirm_dialog");
    );

) : ui_screen() == "confirm_dialog" ? (
    // Dialog with title, width, height, OK text, cancel text
    result = control_dialog("Confirm Action", 300, 150, "Confirm", "Cancel");

    ui_text("Are you sure you want to proceed?");

    result == 1 ? (
        // User clicked OK
        action_confirmed = 1;
    ) : result == -1 ? (
        // User clicked Cancel
        action_confirmed = 0;
    );

) : control_system();
```

--------------------------------

### Splitting UI with Ratios and Text Width

Source: https://github.com/geraintluff/jsfx-ui-lib/blob/master/tour/2 - The Viewport Stack.md

Use ratio-based or text-based splitting to dynamically allocate space for UI elements.

```eel2
ui_split_topratio(0.5);
	ui_text("This section takes up 50% of the available vertical space");
ui_pop();

ui_split_lefttext("Auto-sized button");
	control_button("Auto-sized button");
ui_pop();

ui_text("remaining space");
```