Application (Mojo)

addEventListener(id: Int, handler: EventHandler)

Registers an event handler for a widget identified by its id. This function allows you to associate a specific EventHandler instance with a UI widget, ensuring that when an event (like a click, keypress, or mouse movement) occurs on that widget, the appropriate handler logic is executed. The handler will only be triggered if the event type defined within the EventHandler matches the actual event that occurred.

Defined in: mjui/_app.mojo

app.addEventListener(1, handler)

setElementById(id: Int, element: FLTK_WIDGET_POINTER)

Associates a raw FLTK widget pointer (FLTK_WIDGET_POINTER) with a unique integer id. This mapping is crucial for managing UI elements dynamically. By assigning a simple integer ID, you can easily retrieve, update, or manipulate specific widgets throughout your application without needing to hold onto the raw FLTK pointer directly.

Defined in: mjui/_app.mojo

app.setElementById(22, label)

getElementById(id: Int) -> FLTK_WIDGET_POINTER

Retrieves the FLTK_WIDGET_POINTER associated with a given integer id. This function acts as a lookup mechanism, allowing your Mojo code to get a reference to an underlying FLTK widget based on the ID previously set with setElementById. This is fundamental for performing operations on specific UI components.

Defined in: mjui/_app.mojo

var label = app.getElementById(22)

markWindowPTRAsMain(ptr: FLTK_WIDGET_POINTER)

Designates a specific FLTK window pointer (ptr) as the main application window. This is important for the application's lifecycle management. The internal event loop will monitor this designated window for close events, and once it detects that this main window has been closed by the user, the application will gracefully terminate.

Defined in: mjui/_app.mojo

app.markWindowPTRAsMain(window)

attachLoopHook(hook: fn() raises)

Attaches a callable function (hook) to the application's main event loop. This mechanism allows you to inject custom logic that needs to be executed continuously on every iteration of the event loop. This is useful for tasks such as updating game states, performing animations, background processing, or any other operations that require regular execution while the UI is active.

Defined in: mjui/_app.mojo

app.attachLoopHook(my_hook)

execute()

Starts the main FLTK event loop. Calling this function initiates the continuous polling for and processing of UI events. It enters an infinite loop, constantly checking for user interactions (mouse clicks, keypresses, window events), dispatching them to any registered EventHandlers, and executing any attached loop hooks. The application will remain responsive and active until the designated main window is closed or an explicit exit signal is received, at which point the loop terminates.

Defined in: mjui/_app.mojo

app.execute()

EventHandler (Mojo)

set(trigger: Int, handler: Handler)

Sets both the trigger event type (trigger) and the handler function (handler) for this EventHandler. This function provides a convenient way to configure an event handler, specifying precisely which type of event it should respond to and what action it should take when that event occurs.

Defined in: mjui/EventHandler.mojo

handler.set(MJUI_KEYDOWN, my_handler)

attachHandler(handler: Handler)

Sets the handler function (handler) that will be executed when the associated event is triggered. This allows you to define the specific code block or logic that should run in response to an event, separating the event detection from the action to be performed.

Defined in: mjui/EventHandler.mojo

handler.attachHandler(my_handler)

attachTrigger(trigger: Int)

Sets the integer trigger event type that this EventHandler will respond to. By setting the trigger, you define which specific UI event (e.g., a button click, a key press) will cause this event handler to become active and execute its attached function.

Defined in: mjui/EventHandler.mojo

handler.attachTrigger(MJUI_KEYDOWN)

trigger()

Executes the currently attached handler function. This function is typically called internally by the event loop when an event matching the `trigger` is detected for the associated widget. You can also call it manually to programmatically invoke the handler's logic.

Defined in: mjui/EventHandler.mojo

handler.trigger()

Utility Functions (Mojo)

rgb(r: UInt32, g: UInt32, b: UInt32) -> UInt32

Converts individual red, green, and blue color components (each ranging from 0-255) into a single 32-bit unsigned integer. This packed integer format is the standard color representation used by FLTK (Fast Light Toolkit) and is essential when setting widget colors or drawing custom graphics.

Defined in: mjui/utils.mojo

var color = rgb(255, 128, 0)

str_to_int8(str: String) -> List[Int8]

Converts a Mojo String into a List of Int8 (ASCII character codes). This utility is vital for interoperability with C++ FFI (Foreign Function Interface) functions, which often expect string data to be provided as a null-terminated byte array. This function correctly transforms Mojo strings into this compatible format.

Defined in: mjui/utils.mojo

var ascii_codes = str_to_int8("Hello")

readFromStringBytes(bytes: StringBytes) -> String

Converts a StringBytes span (a low-level byte array representation, typically received from C++ FFI functions) back into a human-readable Mojo String. The function intelligently reads the byte array until it encounters a null terminator, ensuring that only the relevant string data is converted.

Defined in: mjui/utils.mojo

var s = readFromStringBytes(bytes)

createIdFrom(id: String) -> Int

Generates a simple integer ID from a given String. This is achieved by summing the ASCII character codes of the input string. While this method provides a quick and convenient way to get a unique identifier for widgets, it is important to note that it is not collision-proof for all possible string inputs and should be used where strict uniqueness guarantees are not paramount.

Defined in: mjui/utils.mojo

var widget_id = createIdFrom("button1")

convertStringToBytes(strn: String) -> StringBytes

Converts a Mojo String into a StringBytes span. This low-level byte representation is specifically designed for efficient and safe passing of string data to C++ FFI functions. It ensures that the string data is correctly formatted for consumption by the underlying C++ libraries.

Defined in: mjui/utils.mojo

var bytes = convertStringToBytes("Label")

Constants (Mojo)

Event Types

Event types used for widget and application event handling.

handler.attachTrigger(MJUI_PUSH)

Cursor Types

Cursor types for widgets and windows.

Layout Flags

Layout direction and resize flags for flex layouts.

Box Types

Box types for widget backgrounds and borders.

Label Types

Label rendering types for widgets.

Image Types

Image format constants for loading images.

Alignment

Alignment options for text and widgets.

Visual Schemes

Visual style schemes for the UI.

useScheme(GTK)

getEventNameFromNum(num: Int) -> String

Returns the string name corresponding to an integer event type number. This utility function is helpful for debugging and logging event information.

Defined in: mjui/const.mojo

var name = getEventNameFromNum(1)  # "MJUI_PUSH"

FFI Bindings (Mojo/C++)

Widget Management

mjuiGrabEvent() -> int64_t

Retrieves the next event from the event queue. The returned int64_t combines the widget ID and event type. Returns -2 if no event is available.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var event = mjuiGrabEvent()

mjuiShowWidget(widget)

Makes the given FLTK widget visible.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiShowWidget(my_button)

mjuiHideWidget(widget)

Hides the given FLTK widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiHideWidget(my_label)

mjuiRedraw(widget)

Forces the given FLTK widget to redraw itself immediately, updating its appearance on the screen.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiRedraw(my_input)

mjuiSetWidgetColor(widget, color)

Sets the background color of the specified FLTK widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiSetWidgetColor(my_button, rgb(255, 0, 0))

mjuiSetWidgetTextColor(widget, color)

Sets the color of the text label for the specified FLTK widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiSetWidgetTextColor(my_label, rgb(0, 0, 0))

mjuiSetWidgetSelectionColor(widget, color)

Sets the selection color for the FLTK widget, typically used for highlighting selected text in input fields or selected items in lists.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiSetWidgetSelectionColor(my_input, rgb(0, 128, 255))

mjuiSetWidgetBox(widget, box)

Applies a specific box type (Fl_Boxtype) to the FLTK widget, defining its border and background style.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiSetWidgetBox(my_button, MJUI_FLAT_BOX)

mjuiSetWidgetLabel(widget, label)

Sets the text label for the specified FLTK widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiSetWidgetLabel(my_label, convertStringToBytes("New Label"))

BEGIN_WIDGET_APPEND(group)

Marks the beginning of adding child widgets to an FLTK group widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

BEGIN_WIDGET_APPEND(my_layout)
// Add widgets here
END_WIDGET_APPEND(my_layout)

END_WIDGET_APPEND(group)

Marks the end of adding child widgets to an FLTK group widget.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

END_WIDGET_APPEND(my_layout)

mjuiGetWidgetHeight(widget)

Returns the current height of the specified FLTK widget in pixels.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var h = mjuiGetWidgetHeight(my_button)

mjuiGetWidgetWidth(widget)

Returns the current width of the specified FLTK widget in pixels.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var w = mjuiGetWidgetWidth(my_label)

mjuiWindowSetResizable(window, widget)

Makes a specific widget within an Fl_Window resizable, allowing it to adapt to window resizing.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiWindowSetResizable(my_window, my_layout)

mjuiApplyImage(widget, image)

Applies an Fl_Image to an FLTK widget, typically used for buttons, labels, or custom drawing areas.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var img = mjuiLoadImg(100, 100, PNG, convertStringToBytes("logo.png"))
mjuiApplyImage(my_label, img)

mjuiImageScale(img, width, height, proportional)

Scales an Fl_Image to the desired width and height. If proportional is 1, the image will be scaled maintaining its aspect ratio.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

mjuiImageScale(img, 200, 200, 1)

Window Management

mjuiCreateWindow(width, height, resize, fullscreen, no_border, title_r)

Creates a new FLTK Fl_Double_Window with specified width, height, and options for resizeability, fullscreen mode, no_border, and a title.

Defined in: mjui/fltk_bindings/libc/Window/MJUIWindow.cc

var window = mjuiCreateWindow(800, 600, 1, 0, 0, convertStringToBytes("My App"))

mjuiWindowTitleSet(window, new_title_r)

Sets the title of the given Fl_Double_Window to new_title_r.

Defined in: mjui/fltk_bindings/libc/Window/MJUIWindow.cc

mjuiWindowTitleSet(window, convertStringToBytes("New Title"))

mjuiWindowVisibilityStatus(window, condition)

Returns the visibility status of the window. condition can be WINDOW_VISIBLE (0) or WINDOW_MINIMIZED (1). Returns 1 if true, 0 if false, -1 if condition is invalid.

Defined in: mjui/fltk_bindings/libc/Window/MJUIWindow.cc

var is_visible = mjuiWindowVisibilityStatus(window, 0)  # 0 = WINDOW_VISIBLE

mjuiWindowPositionSet(window, x, y)

Sets the top-left position of the Fl_Double_Window on the screen to (x, y).

Defined in: mjui/fltk_bindings/libc/Window/MJUIWindow.cc

mjuiWindowPositionSet(window, 100, 100)

Button & Input Widgets

mjuiCreateButton(x, y, w, h, id, label_r)

Creates a new custom FLTK Button widget at (x, y) with specified width, height, id, and a label.

Defined in: mjui/fltk_bindings/libc/Button/MJUIButton.cc

var button = mjuiCreateButton(100, 30, 10, 10, 1, convertStringToBytes("Click Me"))

mjuiCreateCheckButton(x, y, w, h, id, label_r)

Creates a new custom FLTK MJUI_CheckButton widget at (x, y) with specified width, height, id, and a label.

Defined in: mjui/fltk_bindings/libc/Button/MJUIButton.cc

var check = mjuiCreateCheckButton(100, 30, 10, 50, 2, convertStringToBytes("Check Me"))

mjuiCheckButtonGetState(checkButton)

Returns the current state of a MJUI_CheckButton (1 if checked, 0 if unchecked).

Defined in: mjui/fltk_bindings/libc/Button/MJUIButton.cc

var state = mjuiCheckButtonGetState(check)

mjuiCreateInput(x, y, w, h, id, numOnly, label_r)

Creates a single-line Input field. numOnly (1 for numeric only, 0 for any text) and label (placeholder) are configurable.

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

var input = mjuiCreateInput(10, 90, 200, 30, 3, 0, convertStringToBytes("Enter text..."))

mjuiCreateChoice(x, y, w, h)

Creates a select dropdown. Options can be added using mjuiAddOptionToChoice

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

var input = mjuiCreateInput(10, 90, 200, 30, 3, 0, convertStringToBytes("Enter text..."))

mjuiCreateMultilineInput(x, y, w, h, id, label_r)

Creates a multiline MultiLineInput field with a placeholder label.

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

var multi = mjuiCreateMultilineInput(10, 130, 200, 60, 4, convertStringToBytes("Multiline..."))

mjuiSetInputValue(input, value)

Sets the current value (text) of an FLTK Fl_Input widget.

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

mjuiSetInputValue(input, convertStringToBytes("Hello"))

mjuiGrabInput(input) -> StringBytes

Gets the current value (text) of an FLTK Fl_Input widget.

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

var bytes = mjuiGrabInput(input)
var str = readFromStringBytes(bytes) # This is necessary since grab input returns bytes

mjuiGrabChoice(input) -> Int

Gets the current index (text) of the selected option in FLTK Fl_Choice widget.

Defined in: mjui/fltk_bindings/libc/Input/MJUIInput.cc

var bytes = mjuiGrabChoice(input)
var str = readFromStringBytes(bytes) # This is necessary since grab input returns bytes

Label & Image Widgets

mjuiCreateLabel(x, y, width, height, id, text)

Creates a new custom FLTK MJUILabel widget at (x, y) with specified width, height, id, and text.

Defined in: mjui/fltk_bindings/libc/Label/MJUILabel.cc

var label = mjuiCreateLabel(10, 10, 200, 30, 5, convertStringToBytes("Hello World"))

mjuiSetTextProperties(label, size, color, type)

Sets the font size, color, and type (MJUI_LABEL_TYPE_NORMAL, etc.) of the text for an MJUILabel.

Defined in: mjui/fltk_bindings/libc/Label/MJUILabel.cc

mjuiSetTextProperties(label, 14, rgb(0, 0, 0), MJUI_LABEL_TYPE_NORMAL)

mjuiTextAlign(label, alignment)

Sets the text alignment within an MJUILabel.

Defined in: mjui/fltk_bindings/libc/Label/MJUILabel.cc

mjuiTextAlign(label, ALIGN_CENTER)

mjuiLoadImg(width, height, imgType, path)

Loads an image from the specified path with desired width, height, and imgType (e.g., PNG, JPEG, SVG, GIF, ANIM_GIF). Returns an Fl_Image pointer.

Defined in: mjui/fltk_bindings/libc/Label/MJUILabel.cc

var img = mjuiLoadImg(100, 100, PNG, convertStringToBytes("logo.png"))

Layouts & Containers

mjuiCreateLayoutFlex(x, y, w, h, dir)

Creates a new FLTK MJUI_Flex layout container at (x, y) with specified width, height, and layout direction (MJUI_MJUIEX_HORIZONTAL or MJUI_MJUIEX_VERTICAL).

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

var layout = mjuiCreateLayoutFlex(0, 0, 800, 600, MJUI_MJUIEX_VERTICAL)

mjuiSetFlexResize(l, r)

Sets the resize direction for a MJUI_Flex layout. r is RESIZE_XY, RESIZE_XONLY, or RESIZE_YONLY.

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

mjuiSetFlexResize(layout, RESIZE_XY)

mjuiSetFlexMarginGapSettings(l, margin, gap)

Sets the margin (spacing around the layout) and gap (spacing between child widgets) for a MJUI_Flex layout. Pass -1 for either to keep current value.

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

mjuiSetFlexMarginGapSettings(layout, 10, 5)

mjuiSetFlex(l, w, span)

Sets the flex span for a specific widget within a MJUI_Flex layout. The span determines how much space the widget occupies relative to other flex items.

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

mjuiSetFlex(layout, my_button, 2)

mjuiSetMarginExplicit(l, left, top, right, bottom)

Sets explicit left, top, right, and bottom margins for a MJUI_Flex layout.

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

mjuiSetMarginExplicit(layout, 5, 5, 5, 5)

mjuiFlexCalculateLayout(l)

Forces the MJUI_Flex layout to recalculate and apply its child widget positions and sizes based on its current properties.

Defined in: mjui/fltk_bindings/libc/Layout/MJUILayouts.cc

mjuiFlexCalculateLayout(layout)

mjuiScrollContainer(x, y, w, h)

Creates a new Fl_Scroll container widget at (x, y) with specified width and height, enabling scrollability for its children.

Defined in: mjui/fltk_bindings/libc/Layout/Containers.cc

var scroll = mjuiScrollContainer(0, 0, 400, 300)

mjuiScrollSetBarBGColor(s, c, sbar)

Sets the background color of the scroll bar for an Fl_Scroll container. sbar selects which scroll bar: 0 for vertical, 1 for horizontal, 2 for both.

Defined in: mjui/fltk_bindings/libc/Layout/Containers.cc

mjuiScrollSetBarBGColor(scroll, rgb(220, 220, 220), 0)

mjuiScrollSetBarFGColor(s, c, sbar)

Sets the foreground color of the scroll bar for an Fl_Scroll container. sbar selects which scroll bar: 0 for vertical, 1 for horizontal, 2 for both.

Defined in: mjui/fltk_bindings/libc/Layout/Containers.cc

mjuiScrollSetBarFGColor(scroll, rgb(100, 100, 100), 0)

mjuiScrollBy(s, x, y)

Scrolls the Fl_Scroll container by x pixels horizontally and y pixels vertically from its current position.

Defined in: mjui/fltk_bindings/libc/Layout/Containers.cc

mjuiScrollBy(scroll, 0, 50)  # Scrolls down by 50 pixels

Event Loop & Utility

mjuiGrabEvent() -> int64_t

Retrieves the next event from the event queue. The returned int64_t combines the widget ID and event type. Returns -2 if no event is available.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var event = mjuiGrabEvent()

fl_check() -> Int

Processes any pending FLTK events and returns 1 if there are still events to process, 0 otherwise. Used to keep the UI responsive without blocking.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

while fl_check():
    # Do background work

fl_ready() -> Int

Checks if there are any FLTK events ready to be processed. Returns 1 if events are ready, 0 otherwise.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

if fl_ready() == 1:
    fl_check()

mjuiEventKey() -> Int

Returns the integer key code of the most recent keyboard event. Useful for custom key handling in event-driven code.

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

var key = mjuiEventKey()

useScheme(scheme: Int)

Sets the global FLTK visual scheme. scheme can be GTK (0), GLEAM (1), or PLASTIC (2).

Defined in: mjui/fltk_bindings/libc/BaseWidgetHelpers.cc

useScheme(GTK)
useScheme(GLEAM)
useScheme(PLASTIC)