PlexyUI API

PlexyUI API Reference

Generated from include/plexy/plexy_ui.h by scripts/generate_plexy_uikit_docs.py. Do not edit this page by hand; regenerate it from the header instead.

PlexyUI — Client Library for PlexyDesk GPU-Accelerated Widgets Renders widgets locally using libplexycanvas (SDF shaders, FreeType text, flexbox layout) and submits DMA-BUF frames via the standard plexy protocol. Client crash does not affect the compositor (plexyshell).

Opaque types

PlexyApp

typedef struct PlexyApp PlexyApp;

Opaque handle for the lifetime of a PlexyDesk application.

PlexyWindow

typedef struct PlexyWindow PlexyWindow;

Opaque handle for a PlexyDesk window and its widget tree.

Callback types

PlexyClickCallback

typedef void (*PlexyClickCallback)(uint32_t widget_id, void* userdata);

Called when a widget reports a click-style activation.

Parameters

Parameter	Type	Description
widget_id	uint32_t	Widget ID of the target control or container.
userdata	void*	Caller-provided context passed back into the callback.

PlexyValueCallback

typedef void (*PlexyValueCallback)(uint32_t widget_id, float value, void* userdata);

Called when a widget emits a numeric value change.

Parameters

Parameter	Type	Description
widget_id	uint32_t	Widget ID of the target control or container.
value	float	Numeric value to apply or report.
userdata	void*	Caller-provided context passed back into the callback.

PlexyTextCallback

typedef void (*PlexyTextCallback)(uint32_t widget_id, const char* text, void* userdata);

Called when widget text content changes.

Parameters

Parameter	Type	Description
widget_id	uint32_t	Widget ID of the target control or container.
text	const char*	Text content to display or apply.
userdata	void*	Caller-provided context passed back into the callback.

PlexyKeyCallback

typedef void (*PlexyKeyCallback)(uint32_t widget_id, uint32_t keycode, uint32_t mods, void* userdata);

Called when a widget receives keyboard input.

Parameters

Parameter	Type	Description
widget_id	uint32_t	Widget ID of the target control or container.
keycode	uint32_t	Key code supplied with a key event.
mods	uint32_t	Modifier state supplied with a key event.
userdata	void*	Caller-provided context passed back into the callback.

PlexyMenuCallback

typedef void (*PlexyMenuCallback)(uint32_t item_id, void* userdata);

Called when an application menubar item is chosen.

Parameters

Parameter	Type	Description
item_id	uint32_t	Identifier of a menu item.
userdata	void*	Caller-provided context passed back into the callback.

App lifecycle

These functions manage the lifetime of a PlexyDesk application object and its main loop.

plexy_app_create

PlexyApp* plexy_app_create(const char* name);

Create a top-level PlexyDesk application object.

Parameters

Parameter	Type	Description
name	const char*	Human-readable name used to identify the application.

• Returns: A new PlexyApp handle.

plexy_app_run

void plexy_app_run(PlexyApp* app);

Enter the application event loop and keep the UI running until it exits.

Parameters

Parameter	Type	Description
app	PlexyApp*	Application handle that owns the operation.

plexy_app_quit

void plexy_app_quit(PlexyApp* app);

Request that the application event loop stops.

Parameters

Parameter	Type	Description
app	PlexyApp*	Application handle that owns the operation.

plexy_app_destroy

void plexy_app_destroy(PlexyApp* app);

Release the application object and its remaining resources.

Parameters

Parameter	Type	Description
app	PlexyApp*	Application handle that owns the operation.

Window

These functions create, inspect, and destroy PlexyDesk windows.

plexy_window_create

PlexyWindow* plexy_window_create(PlexyApp* app, uint32_t width, uint32_t height, const char* title);

Create a new window for an application.

Parameters

Parameter	Type	Description
app	PlexyApp*	Application handle that owns the operation.
width	uint32_t	Requested width in pixels.
height	uint32_t	Requested height in pixels.
title	const char*	Human-readable label, title, or heading text.

• Returns: A new PlexyWindow handle.

plexy_window_root

uint32_t plexy_window_root(PlexyWindow* win);

Return the root widget ID for the window's layout tree.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

• Returns: The root widget ID for the window.

plexy_window_destroy

void plexy_window_destroy(PlexyWindow* win);

Destroy a window and release its widget tree.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

Widget creation

These functions create widgets and containers inside an existing window.

plexy_label

uint32_t plexy_label(PlexyWindow* win, uint32_t parent, const char* text);

Create a label and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
text	const char*	Text content to display or apply.

• Returns: A widget ID for the created or referenced widget.

plexy_button

uint32_t plexy_button(PlexyWindow* win, uint32_t parent, const char* text);

Create a button and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
text	const char*	Text content to display or apply.

• Returns: A widget ID for the created or referenced widget.

plexy_text_input

uint32_t plexy_text_input(PlexyWindow* win, uint32_t parent, const char* placeholder);

Create a text input and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
placeholder	const char*	Placeholder text shown before the user enters content.

• Returns: A widget ID for the created or referenced widget.

plexy_text_area

uint32_t plexy_text_area(PlexyWindow* win, uint32_t parent, const char* initial_text);

Create a text area and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
initial_text	const char*	Initial text content for the widget.

• Returns: A widget ID for the created or referenced widget.

plexy_checkbox

uint32_t plexy_checkbox(PlexyWindow* win, uint32_t parent, const char* label);

Create a checkbox and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
label	const char*	Display label shown with the widget.

• Returns: A widget ID for the created or referenced widget.

plexy_switch_widget

uint32_t plexy_switch_widget(PlexyWindow* win, uint32_t parent, const char* label);

Create a switch widget and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
label	const char*	Display label shown with the widget.

• Returns: A widget ID for the created or referenced widget.

plexy_slider

uint32_t plexy_slider(PlexyWindow* win, uint32_t parent, float min, float max, float initial);

Create a slider and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
min	float	Minimum allowed value for the control.
max	float	Maximum allowed value for the control.
initial	float	Initial numeric value for the control.

• Returns: A widget ID for the created or referenced widget.

plexy_progress

uint32_t plexy_progress(PlexyWindow* win, uint32_t parent, float value);

Create a progress and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
value	float	Numeric value to apply or report.

• Returns: A widget ID for the created or referenced widget.

plexy_separator

uint32_t plexy_separator(PlexyWindow* win, uint32_t parent);

Create a separator and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_spacer

uint32_t plexy_spacer(PlexyWindow* win, uint32_t parent);

Create a spacer and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_panel

uint32_t plexy_panel(PlexyWindow* win, uint32_t parent);

Create a panel and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_scroll_view

uint32_t plexy_scroll_view(PlexyWindow* win, uint32_t parent);

Create a scroll view and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_list_view

uint32_t plexy_list_view(PlexyWindow* win, uint32_t parent, const char* items_text);

Create a list view and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
items_text	const char*	Text payload describing the initial items for the view.

• Returns: A widget ID for the created or referenced widget.

plexy_icon_view

uint32_t plexy_icon_view(PlexyWindow* win, uint32_t parent, const char* items_text);

Create a icon view and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
items_text	const char*	Text payload describing the initial items for the view.

• Returns: A widget ID for the created or referenced widget.

plexy_list_clear

void plexy_list_clear(PlexyWindow* win, uint32_t list_view_id);

Remove all items from a list view.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
list_view_id	uint32_t	Widget ID of the target list view.

plexy_list_append

uint32_t plexy_list_append(PlexyWindow* win, uint32_t list_view_id, const char* item_text);

Append a new item to a list view and return the new child widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
list_view_id	uint32_t	Widget ID of the target list view.
item_text	const char*	Text content for an inserted list or icon item.

• Returns: A widget ID for the created or referenced widget.

plexy_list_select

void plexy_list_select(PlexyWindow* win, uint32_t list_view_id, int index);

Select an item in a list view by index.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
list_view_id	uint32_t	Widget ID of the target list view.
index	int	Zero-based item index.

plexy_icon_clear

void plexy_icon_clear(PlexyWindow* win, uint32_t icon_view_id);

Remove all items from an icon view.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
icon_view_id	uint32_t	Widget ID of the target icon view.

plexy_icon_append

uint32_t plexy_icon_append(PlexyWindow* win, uint32_t icon_view_id, const char* item_text);

Append a new item to an icon view and return the new child widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
icon_view_id	uint32_t	Widget ID of the target icon view.
item_text	const char*	Text content for an inserted list or icon item.

• Returns: A widget ID for the created or referenced widget.

plexy_icon_select

void plexy_icon_select(PlexyWindow* win, uint32_t icon_view_id, int index);

Select an item in an icon view by index.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
icon_view_id	uint32_t	Widget ID of the target icon view.
index	int	Zero-based item index.

plexy_destroy_widget

void plexy_destroy_widget(PlexyWindow* win, uint32_t widget_id);

Remove a widget from the window and destroy it.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.

Layout containers (convenience)

These helpers create common container shapes for arranging child widgets.

plexy_row

uint32_t plexy_row(PlexyWindow* win, uint32_t parent);

Create a row and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_column

uint32_t plexy_column(PlexyWindow* win, uint32_t parent);

Create a column and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

macOS-style widgets

These widgets model shell-like controls, navigation elements, and drawers.

plexy_toolbar

uint32_t plexy_toolbar(PlexyWindow* win, uint32_t parent);

Create a toolbar and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_toolbar_item

uint32_t plexy_toolbar_item(PlexyWindow* win, uint32_t parent, const char* label);

Create a toolbar item and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
label	const char*	Display label shown with the widget.

• Returns: A widget ID for the created or referenced widget.

plexy_sidebar

uint32_t plexy_sidebar(PlexyWindow* win, uint32_t parent);

Create a sidebar and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_sidebar_item

uint32_t plexy_sidebar_item(PlexyWindow* win, uint32_t parent, const char* label);

Create a sidebar item and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
label	const char*	Display label shown with the widget.

• Returns: A widget ID for the created or referenced widget.

plexy_sidebar_item_with_icon

uint32_t plexy_sidebar_item_with_icon(PlexyWindow* win, uint32_t parent, const char* label, const char* icon_name);

Create a sidebar item with icon and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
label	const char*	Display label shown with the widget.
icon_name	const char*	Icon name value.

• Returns: A widget ID for the created or referenced widget.

plexy_sidebar_section

uint32_t plexy_sidebar_section(PlexyWindow* win, uint32_t parent, const char* title);

Create a sidebar section and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
title	const char*	Human-readable label, title, or heading text.

• Returns: A widget ID for the created or referenced widget.

plexy_search_field

uint32_t plexy_search_field(PlexyWindow* win, uint32_t parent, const char* placeholder);

Create a search field and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
placeholder	const char*	Placeholder text shown before the user enters content.

• Returns: A widget ID for the created or referenced widget.

plexy_breadcrumb

uint32_t plexy_breadcrumb(PlexyWindow* win, uint32_t parent, const char* path);

Create a breadcrumb and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
path	const char*	Path text or breadcrumb string.

• Returns: A widget ID for the created or referenced widget.

plexy_split_view

uint32_t plexy_split_view(PlexyWindow* win, uint32_t parent);

Create a split view and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.

• Returns: A widget ID for the created or referenced widget.

plexy_status_bar

uint32_t plexy_status_bar(PlexyWindow* win, uint32_t parent, const char* text);

Create a status bar and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
text	const char*	Text content to display or apply.

• Returns: A widget ID for the created or referenced widget.

plexy_drawer

uint32_t plexy_drawer(PlexyWindow* win, uint32_t parent, int edge, float size);

Create a drawer and return its widget ID.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
parent	uint32_t	Parent widget ID that will contain the new child widget.
edge	int	Drawer edge constant indicating which side the drawer attaches to.
size	float	Generic size value or drawer size.

• Returns: A widget ID for the created or referenced widget.

plexy_drawer_set_open

void plexy_drawer_set_open(PlexyWindow* win, uint32_t drawer_id, int open, int animated);

Open or close a drawer and optionally animate the change.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
drawer_id	uint32_t	Drawer id value.
open	int	Whether the drawer should be open.
animated	int	Whether the state change should be animated.

plexy_drawer_toggle

void plexy_drawer_toggle(PlexyWindow* win, uint32_t drawer_id, int animated);

Toggle a drawer between open and closed states.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
drawer_id	uint32_t	Drawer id value.
animated	int	Whether the state change should be animated.

plexy_drawer_is_open

int plexy_drawer_is_open(PlexyWindow* win, uint32_t drawer_id);

Report whether a drawer is currently open.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
drawer_id	uint32_t	Drawer id value.

• Returns: A non-zero value when the drawer is open, otherwise zero.

Layout properties

These functions change how a widget is positioned, aligned, or sized inside its parent layout.

plexy_flex_direction

void plexy_flex_direction(PlexyWindow* win, uint32_t widget_id, int direction);

Set the flex direction property on an existing widget.

Note: 0=row, 1=column

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
direction	int	Layout direction constant, such as row or column.

plexy_justify

void plexy_justify(PlexyWindow* win, uint32_t widget_id, int justify);

Set the justify property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
justify	int	Main-axis justification constant.

plexy_align

void plexy_align(PlexyWindow* win, uint32_t widget_id, int align);

Set the align property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
align	int	Cross-axis alignment constant.

plexy_flex_grow

void plexy_flex_grow(PlexyWindow* win, uint32_t widget_id, float grow);

Set the flex grow property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
grow	float	Flex growth factor used during layout.

plexy_size

void plexy_size(PlexyWindow* win, uint32_t widget_id, float width, float height);

Set the size property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
width	float	Requested width in pixels.
height	float	Requested height in pixels.

plexy_margin

void plexy_margin(PlexyWindow* win, uint32_t widget_id, float top, float right, float bottom, float left);

Set the margin property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
top	float	Top edge distance or coordinate.
right	float	Right edge distance.
bottom	float	Bottom edge distance.
left	float	Left edge distance.

plexy_padding

void plexy_padding(PlexyWindow* win, uint32_t widget_id, float top, float right, float bottom, float left);

Set the padding property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
top	float	Top edge distance or coordinate.
right	float	Right edge distance.
bottom	float	Bottom edge distance.
left	float	Left edge distance.

plexy_gap

void plexy_gap(PlexyWindow* win, uint32_t widget_id, float gap);

Set the gap property on an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
gap	float	Spacing inserted between child items.

Widget state

These functions update widget content or toggle widget state after creation.

plexy_set_text

void plexy_set_text(PlexyWindow* win, uint32_t widget_id, const char* text);

Replace the text content of an existing widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
text	const char*	Text content to display or apply.

plexy_set_value

void plexy_set_value(PlexyWindow* win, uint32_t widget_id, float value);

Set the numeric value of a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
value	float	Numeric value to apply or report.

plexy_set_visible

void plexy_set_visible(PlexyWindow* win, uint32_t widget_id, int visible);

Show or hide a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
visible	int	Visibility flag, typically non-zero for visible.

plexy_set_enabled

void plexy_set_enabled(PlexyWindow* win, uint32_t widget_id, int enabled);

Enable or disable user interaction for a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
enabled	int	Enabled flag, typically non-zero for enabled.

plexy_set_readonly

void plexy_set_readonly(PlexyWindow* win, uint32_t widget_id, int readonly);

Toggle whether a text-capable widget is read-only.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
readonly	int	Read-only flag, typically non-zero to prevent editing.

Style

These functions control visual appearance such as color, corner radius, and surface material.

plexy_set_corner_radius

void plexy_set_corner_radius(PlexyWindow* win, uint32_t widget_id, float radius);

Set the widget corner radius.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
radius	float	Corner radius value.

plexy_set_elevation

void plexy_set_elevation(PlexyWindow* win, uint32_t widget_id, float level);

Set the widget elevation or depth styling level.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
level	float	Elevation level used to influence depth styling.

plexy_set_fill_color

void plexy_set_fill_color(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a);

Apply a fill color using RGBA components.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
r	float	Red color component.
g	float	Green color component.
b	float	Blue color component.
a	float	Alpha or opacity component.

plexy_set_fill_color_hex

void plexy_set_fill_color_hex(PlexyWindow* win, uint32_t widget_id, const char* hex);

Apply a fill color using a hex color string.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
hex	const char*	Hexadecimal color string.

plexy_set_text_color

void plexy_set_text_color(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a);

Apply a text color using RGBA components.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
r	float	Red color component.
g	float	Green color component.
b	float	Blue color component.
a	float	Alpha or opacity component.

plexy_set_text_color_hex

void plexy_set_text_color_hex(PlexyWindow* win, uint32_t widget_id, const char* hex);

Apply a text color using a hex color string.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
hex	const char*	Hexadecimal color string.

plexy_set_font_size

void plexy_set_font_size(PlexyWindow* win, uint32_t widget_id, float size);

Set the rendered font size for the widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
size	float	Generic size value or drawer size.

plexy_set_border

void plexy_set_border(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a, float width);

Set border color and width for a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
r	float	Red color component.
g	float	Green color component.
b	float	Blue color component.
a	float	Alpha or opacity component.
width	float	Requested width in pixels.

plexy_set_glass

void plexy_set_glass(PlexyWindow* win, uint32_t widget_id, float opacity);

Apply a glass-style material effect with the given opacity.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
opacity	float	Opacity amount for the material effect.

plexy_set_glass_material

void plexy_set_glass_material(PlexyWindow* win, uint32_t widget_id, float opacity);

Apply the full glass material treatment with the given opacity.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
opacity	float	Opacity amount for the material effect.

plexy_set_surface_material

void plexy_set_surface_material(PlexyWindow* win, uint32_t widget_id);

Switch the widget back to an opaque surface-style material.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.

Events

These functions register callbacks and direct focus for interactive widgets.

plexy_on_click

void plexy_on_click(PlexyWindow* win, uint32_t widget_id, PlexyClickCallback cb, void* userdata);

Register a click callback for a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
cb	PlexyClickCallback	Callback function invoked when the event fires.
userdata	void*	Caller-provided context passed back into the callback.

plexy_on_value_changed

void plexy_on_value_changed(PlexyWindow* win, uint32_t widget_id, PlexyValueCallback cb, void* userdata);

Register a callback for value changes.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
cb	PlexyValueCallback	Callback function invoked when the event fires.
userdata	void*	Caller-provided context passed back into the callback.

plexy_on_text_changed

void plexy_on_text_changed(PlexyWindow* win, uint32_t widget_id, PlexyTextCallback cb, void* userdata);

Register a callback for text changes.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
cb	PlexyTextCallback	Callback function invoked when the event fires.
userdata	void*	Caller-provided context passed back into the callback.

plexy_on_key

void plexy_on_key(PlexyWindow* win, uint32_t widget_id, PlexyKeyCallback cb, void* userdata);

Register a callback for widget key events.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
cb	PlexyKeyCallback	Callback function invoked when the event fires.
userdata	void*	Caller-provided context passed back into the callback.

plexy_set_focus

void plexy_set_focus(PlexyWindow* win, uint32_t widget_id);

Move keyboard focus to the specified widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.

plexy_on_menu

void plexy_on_menu(PlexyWindow* win, PlexyMenuCallback cb, void* userdata);

Register a callback for desktop menubar item selections.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
cb	PlexyMenuCallback	Callback function invoked when the event fires.
userdata	void*	Caller-provided context passed back into the callback.

App menubar model (desktop menubar integration)

These functions describe an application menu structure for the desktop menubar.

plexy_menu_begin

int plexy_menu_begin(PlexyWindow* win, int supported, const char* app_title);

Begin describing an application menu model for the desktop menubar.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
supported	int	Flag indicating whether desktop menubar support is available.
app_title	const char*	Application title to expose through the menubar model.

• Returns: An integer status or result code.

plexy_menu_add

int plexy_menu_add(PlexyWindow* win, uint32_t menu_id, const char* title);

Create a new menu within the current menubar model.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
menu_id	uint32_t	Identifier of the target menu.
title	const char*	Human-readable label, title, or heading text.

• Returns: An integer status or result code.

plexy_menu_add_item

int plexy_menu_add_item(PlexyWindow* win, uint32_t menu_id, uint32_t item_id, const char* label, int enabled);

Add a menu item to an existing menu.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
menu_id	uint32_t	Identifier of the target menu.
item_id	uint32_t	Identifier of a menu item.
label	const char*	Display label shown with the widget.
enabled	int	Enabled flag, typically non-zero for enabled.

• Returns: An integer status or result code.

plexy_menu_commit

int plexy_menu_commit(PlexyWindow* win);

Submit the completed menubar model to the shell.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

• Returns: An integer status or result code.

Batch updates (reduces IPC round-trips)

These functions group a series of widget updates so they can be applied together.

plexy_batch_begin

void plexy_batch_begin(PlexyWindow* win);

Begin a batch of widget changes.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

plexy_batch_end

void plexy_batch_end(PlexyWindow* win);

End a batch of widget changes and flush the grouped update.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

Retained Path Drawing (Bezier)

These functions build retained vector paths and query rendered widget bounds.

plexy_path_clear

void plexy_path_clear(PlexyWindow* win);

Clear any retained path drawing commands.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

plexy_path_begin

void plexy_path_begin(PlexyWindow* win);

Start defining a new retained path.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

plexy_path_move_to

void plexy_path_move_to(PlexyWindow* win, float x, float y);

Move the current drawing cursor to a new position.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
x	float	X coordinate or output storage for the X position.
y	float	Y coordinate or output storage for the Y position.

plexy_path_line_to

void plexy_path_line_to(PlexyWindow* win, float x, float y);

Append a straight line segment to the current path.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
x	float	X coordinate or output storage for the X position.
y	float	Y coordinate or output storage for the Y position.

plexy_path_bezier_to

void plexy_path_bezier_to(PlexyWindow* win, float cp1x, float cp1y, float cp2x, float cp2y, float x, float y);

Append a cubic Bezier curve to the current path.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
cp1x	float	First Bezier control point X coordinate.
cp1y	float	First Bezier control point Y coordinate.
cp2x	float	Second Bezier control point X coordinate.
cp2y	float	Second Bezier control point Y coordinate.
x	float	X coordinate or output storage for the X position.
y	float	Y coordinate or output storage for the Y position.

plexy_path_set_stroke

void plexy_path_set_stroke(PlexyWindow* win, float r, float g, float b, float a, float width);

Set stroke color and width for retained path drawing.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
r	float	Red color component.
g	float	Green color component.
b	float	Blue color component.
a	float	Alpha or opacity component.
width	float	Requested width in pixels.

plexy_path_stroke

void plexy_path_stroke(PlexyWindow* win);

Render the current retained path as a stroke.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.

plexy_widget_bounds

int plexy_widget_bounds(PlexyWindow* win, uint32_t widget_id, float* x, float* y, float* width, float* height);

Query the current bounds of a widget.

Parameters

Parameter	Type	Description
win	PlexyWindow*	Window handle that owns or contains the widget tree.
widget_id	uint32_t	Widget ID of the target control or container.
x	float*	X coordinate or output storage for the X position.
y	float*	Y coordinate or output storage for the Y position.
width	float*	Requested width in pixels.
height	float*	Requested height in pixels.

• Returns: An integer status or result code.

Constants

Justify content

Constants used to choose how child widgets are distributed on the main layout axis.

Constant	Value	Description
PLEXY_JUSTIFY_START	0	Pack items toward the start of the main axis.
PLEXY_JUSTIFY_END	1	Pack items toward the end of the main axis.
PLEXY_JUSTIFY_CENTER	2	Center items along the main axis.
PLEXY_JUSTIFY_SPACE_BETWEEN	3	Distribute free space between items.
PLEXY_JUSTIFY_SPACE_AROUND	4	Distribute free space around items.
PLEXY_JUSTIFY_SPACE_EVENLY	5	Distribute free space evenly before, between, and after items.

Align items

Constants used to choose how child widgets align on the cross axis.

Constant	Value	Description
PLEXY_ALIGN_START	0	Align items at the start of the cross axis.
PLEXY_ALIGN_END	1	Align items at the end of the cross axis.
PLEXY_ALIGN_CENTER	2	Center items on the cross axis.
PLEXY_ALIGN_STRETCH	3	Stretch items to fill the cross axis.

Flex direction

Constants used to choose whether a layout flows as a row or a column.

Constant	Value	Description
PLEXY_FLEX_ROW	0	Lay out children horizontally.
PLEXY_FLEX_COLUMN	1	Lay out children vertically.

Drawer edges

Constants used to attach a drawer to a specific edge of its parent window.

Constant	Value	Description
PLEXY_DRAWER_LEFT	0	Attach the drawer to the left edge.
PLEXY_DRAWER_RIGHT	1	Attach the drawer to the right edge.
PLEXY_DRAWER_TOP	2	Attach the drawer to the top edge.
PLEXY_DRAWER_BOTTOM	3	Attach the drawer to the bottom edge.