Application (FmrbApp)¶
FmrbApp is the application base class for Family mruby. User apps must inherit from FmrbApp and implement lifecycle methods.
Minimal Example¶
class MyApp < FmrbApp
def on_create
clear_user_area
@gfx.draw_text(4, 4, "Hello, mruby!", theme_fg)
@gfx.present
end
def on_update
100 # Wait 100ms
end
end
The file only defines the class. There is no starting code at the end: once the file has
been read, the runtime makes the FmrbApp subclass it defined and starts it. When a file
defines more than one subclass, name the one to start with class = "MyApp" in the
.app.toml (or the #---fmrb header); a file where none can be picked shows the reason in an
error window and the log, as does an exception while starting.
Window size and other settings are specified in a .app.toml file or a #---fmrb comment at the top of the .rb (see App Configuration File (.app.toml)).
Lifecycle¶
| Method | When Called | Return Value Meaning |
|---|---|---|
on_create |
Once when the app starts | Any (ignored) |
on_update |
Repeatedly within the main loop | Wait time in milliseconds until the next on_update. Default 330ms |
on_event(ev) |
On keyboard / mouse / gamepad / HID input | Any |
on_suspend |
When switching to a fullscreen app | Any |
on_resume |
When returning from a suspended state | Any |
on_resize(w, h) |
When the window changes size — a drag on the corner, or a switch to or from fullscreen. fullscreen? and the user area are already updated |
Any |
on_quit_request |
On Ctrl + Q, instead of closing outright |
Any |
on_checkpoint / on_restore |
When a movable app is written to an image, and when it carries on from one (another machine included). See Moving a running app | Any |
on_destroy |
Once when the app exits | Any |
(the file is read; the runtime makes the subclass and calls start)
start
+-- on_create
+-- main_loop:
+-- on_update -> wait for return value ms via _spin
+-- _spin dispatches on_event(ev), _handle_system_control(msg)
+-- repeats until the app stops (`running?` turns false)
+-- destroy -> on_destroy
on_update return value
A short value (10-30ms) increases the frame rate but consumes more CPU. For games, 16-33ms is a good target; for static UIs, 100-500ms is appropriate.
Event Handling (on_event(ev))¶
ev is a Hash, and you determine the event type with ev[:type].
Keyboard¶
def on_event(ev)
case ev[:type]
when :key_down
keycode = ev[:keycode] # Character code (platform-dependent)
scancode = ev[:scancode] # USB HID Usage ID (platform-independent)
modifier = ev[:modifier] # Modifier key bits (see below)
char = ev[:character] # Character (if available)
Log.info("key down: #{char.inspect}")
when :key_up
# ...
end
end
Modifier key bits (ev[:modifier]) layout:
| Bit | Value | Meaning |
|---|---|---|
| 0 | 0x01 | LSHIFT |
| 1 | 0x02 | RSHIFT |
| 2 | 0x04 | LCTRL |
| 3 | 0x08 | RCTRL |
| 4 | 0x10 | LALT |
| 5 | 0x20 | RALT |
Helper methods are provided:
ev_ctrl?(ev) # Ctrl is pressed
ev_shift?(ev) # Shift is pressed
ev_alt?(ev) # Alt is pressed
Note
Use scancode when identifying character keys. keycode values vary between platforms (e.g. SDL2 returns ASCII values).
FmrbConst::KEY_* / MOD_* constants
Since scancode values are USB HID Usage IDs, you can use constants like FmrbConst::KEY_ESC instead of writing raw values like 0x29 (ESC). Modifier key mask constants such as FmrbConst::MOD_CTRL are also available. See Constants > KEY_* / MOD_* for a full list.
Mouse¶
when :mouse_down, :mouse_up
ev[:button] # 1=left, 2=middle, 3=right
ev[:x] # X from the top-left of the app's area (where @gfx draws 0)
ev[:y] # Y, likewise
ev[:wx] # X from the window's top-left (title bar included)
ev[:wy] # Y, likewise
when :mouse_move
ev[:x], ev[:y]
ev[:x] / ev[:y] use the same origin as @gfx, so what you draw at a point and what a click
at that point reports agree. ev[:wx] / ev[:wy] are there for the rare app that cares about
the frame (its own close button, say).
Clicks on the title bar (the close button, and a right-click for the window menu: Send to,
Reload, Close) are handled by the base class before your on_event runs, so there is nothing to
call and no super(ev) to write.
Wheel¶
A wheel event reaches the window that has the keyboard, not the one under the pointer. Two
helpers read it, and both return nil when the event is not a wheel, so an app reads one
of them and moves on:
rows = wheel_rows(ev)
if rows
@scroll -= rows
redraw
end
| Method | |
|---|---|
wheel_rows(ev) |
Notches multiplied by the machine's wheel_lines setting. For anything whose rows are text rows |
wheel_notches(ev) |
The raw notch count. For a list whose rows are not text rows — the launcher's tiles are several lines tall, and wheel_lines sends them flying |
How far a notch reaches is the machine's setting, not each app's opinion.
Gamepad¶
when :gamepad_down, :gamepad_up
ev[:gamepad_id] # 0 and above
ev[:button] # 0..15
when :gamepad_axis
ev[:gamepad_id]
ev[:axis] # 0..5
ev[:value] # Axis value
FmrbConst::GP_* constants
Button numbers have constants like FmrbConst::GP_SQUARE / GP_CROSS / GP_START, and axis numbers have GP_AXIS_LX / GP_AXIS_LY, etc. See Constants > GP_* for details.
Window Operations¶
| Method | Purpose |
|---|---|
set_window_position(x, y) |
Change the window position |
clear_user_area(color = FmrbConst::THEME_WINDOW_BG) |
Fill the app's area (inside the title bar and border). The default follows the system theme, and the call redraws the window frame and marks any attached widgets |
draw_window_frame |
Draw the window frame again (title bar + border). clear_user_area already does this; call it only after drawing into the corners of the area, whose rounding the frame draws over |
window_gfx |
A second FmrbGfx on the same canvas whose (0, 0) is the window's top-left, for drawing outside the area — a frame or title of the app's own. Call set_font on @gfx; the font belongs to the canvas |
request_fullscreen(on) / toggle_fullscreen |
Switch between windowed and fullscreen. The VM keeps running, so app state survives; the answer arrives as on_resize, with fullscreen? and the user area already updated |
request_file_select(mode = "open") |
Invoke the system file selection dialog |
sync_file(path, dest: nil) |
Make the graphics/audio side's copy of a file match this one, transferring it only when it differs. A headless app can do this too |
request_reload |
Reload the script (the window menu's Reload) |
request_window_menu(x, y) |
Open the window menu (Send to, Reload, Close) at a point of the window |
Scrollbars moved: draw_scrollbar and scrollbar_hit are gone, and a scrollbar is now a
widget — see UI Widgets.
Use clear_user_area instead of @gfx.clear
@gfx.clear(color) fills the entire canvas, which also erases the title bar and close button. To preserve the window frame, use clear_user_area(color) instead.
Messaging¶
| Method | Purpose |
|---|---|
subscribe(topic) / unsubscribe(topic) |
Subscribe to a topic |
publish(topic, data=nil) |
Send to a topic |
send_message(dest_pid, msg_type, data) |
Direct message to the kernel or a specific app. data is automatically serialized via MessagePack |
For details and receive handlers, see Pub/Sub.
Timers¶
| Method | |
|---|---|
set_timer(interval) { ... } |
Run the block once, interval ms from now. Returns an id |
clear_timer(id) |
Cancel one that has not fired |
A timer is one-shot: to repeat, set the next one from inside the block. They are checked
once per turn of the app loop, so the resolution is whatever on_update returns.
Starting another app¶
request_run(path, prev_pid = nil) asks the kernel to spawn a file, optionally killing an
instance a previous request started. The answer arrives as an app-control message with the
new pid (nil when it failed). Paths are limited to /app and /home.
Extra canvases¶
create_canvas_gfx(width:, height:, z_offset: 1, transparent: false, transparent_color: 0)
returns an FmrbGfx bound to a canvas of the app's own, and delete_canvas_gfx(gfx)
releases it (they also go when the app does, including on a crash). Position and show it
with gfx.present(x, y); combine it with
set_viewport for a hardware-scrolled layer.
This is for fullscreen apps: the window manager does not follow extra canvases across a change of focus.
Collecting garbage while idle¶
self.idle_gc = true splits collection into steps taken while the app has nothing to do,
instead of stopping it for 100-200 ms in the middle of something. It is for an app that
must not pause — a player, an animation — and cannot get its allocation down to nothing.
The costs: generational mode goes off and does not come back on its own, and a step can delay a message by its own length. An app that is always busy gets the old behaviour back by itself.
Execution Control¶
| Method | Purpose |
|---|---|
start |
Starts the event loop (on_create is called). running? is true from here. The runtime calls it after reading the file; an app does not |
stop |
Ends it: running? turns false, and destroy follows after the next _spin |
destroy |
Notifies the kernel of exit, calls @gfx.destroy, on_destroy, _cleanup |
| on_quit_request | Called on Ctrl + Q instead of stopping the app outright. The default is to close; override it to ask first when there is unsaved work |
| request_early_update | End the current wait now, so the loop reaches on_update without waiting out the timeout the app asked for |
request_early_update is what lets an idle app sleep for a long time at all: without a way
out, "sleep until the next deadline" has to be capped at whatever the app might later be
asked to do in a hurry, which is a poll by another name. It only means anything from inside
a callback — on_control, on_event — because from on_update the next sleep is about to
be recomputed anyway.
Colours from the theme¶
Five readers give an app the system colours without naming a single number, so it follows the machine's theme and the user's colour overrides:
| Method | Role |
|---|---|
theme_bg |
The page background |
theme_fg |
Ink on theme_bg |
theme_accent |
Selection, emphasis |
theme_border |
Rules, boxes, muted text |
theme_fg_light |
Ink on the accent or on a button |
Settings and remembered state¶
Two small tables an app can keep without opening files itself. Both are TOML, take strings,
integers and true/false, and read as {} when the file is missing or broken.
| Method | Where | For |
|---|---|---|
app_settings / save_app_settings(hash) |
/home/<app_handle_name>.toml |
The user's choices (a player name, a level). Saving rewrites only the keys given, so comments the user wrote stay |
app_state / save_app_state(hash) |
/tmp/<app_handle_name>.state.toml |
What to come back to next time, such as the last folder. Lasts until the machine restarts, and is written only when a value changed |
def on_create
@dir = app_state["dir"] || "/home"
end
def on_destroy
save_app_state("dir" => @dir)
end
app_handle_name comes from the app's metadata, or else from the file name. The File
Manager uses app_state to reopen in the folder it was closed in.
What the app can read¶
| Description | |
|---|---|
@gfx (or gfx) |
FmrbGfx instance (drawing API; nil in headless mode) |
name |
App display name (from .toml app_screen_name) |
platform |
:esp32 or :linux |
running? |
true while the app is running |
fullscreen? |
true in fullscreen mode |
closable? |
Whether a click on the close button may stop the app. closable = false turns it off, for an app that owns the screen |
rounded_corners? |
Whether this window's corners are rounded, for an app drawing its own frame |
@window_width / @window_height |
Overall window size |
@pos_x / @pos_y |
Absolute coordinates of the window's top-left corner |
@user_area_width / @user_area_height |
Size of the app's area (where @gfx draws) |
frameless? |
true for a window with window_frame = "none" |
window_gfx |
Draws with the window's top-left as (0, 0) |
Names beginning with @_ belong to the base class
Since 2.1 the base keeps its own state in @_-prefixed variables, so anything you
assign that does not start with @_ is yours alone. @running and @name were the two
that hurt most — an app that set its own @running used to exit silently — and they are
now read through running? and name.
The sound chip is not one of these: an app makes its own with FmrbAudio.new(self).
(0, 0) is the top-left of the app's area
@gfx draws from the top-left of the area the app owns: inside the frame of a framed
window, the window's top-left for a frameless window (window_frame = "none"), and the
screen's top-left in fullscreen. Write the same code for all three and stay within
@user_area_width × @user_area_height. The origin moves with the window (fullscreen in and
out, a frame switched on or off, a move to a machine with another screen); the base keeps it
up to date, so on_resize only has to redraw. Sprites, set_sprite_clip and
UI widgets use the same origin.
File and Directory Paths¶
Pass root-relative paths (e.g. /home/foo.txt) or SD card paths like /mnt/sd/... directly to File.open / Dir.open. See File & I/O > File Namespace for details.
Class Methods¶
| Method | Purpose |
|---|---|
FmrbApp.language |
The UI language the user chose, "en" or "ja" |
FmrbApp.ps |
Array of Hash showing all process states (id, name, state, vm_type, mem_*, stack_water, etc.) |
FmrbApp.config(section) |
Read a specified section from the app's .toml |
FmrbApp.wallclock |
Current time ({year, month, day, hour, minute, second}) |
FmrbApp.gfx_stats |
Drawing statistics {cmds:, presents:} |
FmrbApp.wasm_stats / FmrbApp.wasm_app_stats(pid) |
The WebAssembly runtime (running, apps, pool_used, pool_total, traps ...; all 0 where there is none) and one WebAssembly app (pages, max_pages, binary_size, hook_us, hook_max_us, calls; nil when pid is not one) (development version) |
FmrbApp.sys_pool_info |
System memory pool information |
FmrbApp.pool_used |
How many bytes of its own pool this app has used, or -1. Subtract it across a piece of work to see the garbage that work made |
FmrbApp.heap_info |
ESP-IDF heap info (free, total, min_free, largest_block, etc.) |
FmrbApp.enable_cursor |
Show mouse cursor (delayed until the first mouse movement) |
FmrbApp.set_cursor_visible(visible) |
Immediately show/hide cursor. Useful for hiding in fullscreen games and restoring on exit |
FmrbApp.uptime_us / FmrbApp.uptime_ms |
Microseconds / milliseconds since boot (uptime_ms is in the development version) |
FmrbApp.wifi_info / FmrbApp.wifi_connected? |
The network the machine is on, and whether it is on one |
FmrbApp.usb_devices |
What is plugged into the USB host port |
FmrbApp.set_kana_mode(mode) |
Switch kana input: 0 ASCII, 1 hiragana, 2 katakana. The change comes back as a kana_mode event |
FmrbApp.audio_volume / FmrbApp.audio_muted? |
The volume step, and whether sound is muted |
FmrbApp.battery_level / FmrbApp.battery_charging? |
Battery percentage (nil without a battery), and whether it is charging |
FmrbApp.clipboard / FmrbApp.set_clipboard(text) |
The shared clipboard |
FmrbApp.app_meta(path) |
The metadata of an app file (.app.toml and #---fmrb merged) as a Hash of Strings, or nil |
FmrbApp.pid / FmrbApp.script_path |
This app's process id, and the file it was started from |
FmrbApp.checkpoint(pid) / FmrbApp.move(pid, to) |
Ask for another app to be written to an image, or moved to another machine (the shell's checkpoint / amove) |
FmrbApp._get_last_error |
Last app error (returns {name:, error:} if present) |
System settings (FmrbSystem)¶
The methods that change the machine's settings and services live in FmrbSystem, apart
from the ones an ordinary app uses. They are for the desktop and the settings apps:
| Method | Purpose |
|---|---|
FmrbSystem.set_wallclock(year, month, day, hour, minute, second) |
Set RTC / system time |
FmrbSystem.reboot |
Restart the machine |
FmrbSystem.power_actions / FmrbSystem.power(action) |
Which power actions the machine offers (:reset on a device; :power_off, :suspend and others on a Linux machine), and doing one |
FmrbSystem.set_audio_mute(on) / FmrbSystem.set_audio_volume(step) |
Mute, and set the volume |
FmrbSystem.wifi_networks(scan) / wifi_connect(ssid, password) / wifi_disconnect / wifi_forget(ssid) |
Wi-Fi settings |
FmrbSystem.ble_start / ble_state |
The Bluetooth LE service |
The full list (34 methods, including the Linux program's settings) is in sig/fmrb_system.rbs.
Calling one of these as FmrbApp.<name> is a NoMethodError.
Moving a running app¶
An app whose .app.toml says movable = true (and runs on mruby) can be written to an image
and carried on from it — on the same machine, or on another one over Asterism (the window
menu's Send to, the shell's checkpoint / amove).
| Method | Purpose |
|---|---|
checkpoint(restart: false) |
Ask for this app to be written to /tmp/<name>.ckpt and closed; restart: true starts it again at once. nil when asked, else a String saying why not |
move_to(node_id) |
Ask for this app to be moved to another machine |
on_checkpoint |
Called once the image is written, just before the app closes here (on_destroy does not come) |
on_restore |
Called before it carries on from the image. Instance variables, Tasks and timers are back, and so are the window and subscriptions; what was drawn is not, so redraw here. A move to a machine with another screen calls on_resize first |
on_checkpoint_refused(reason) |
The image could not be written or the move was refused; the app goes on |
The build at the other end may lack a method not common to every machine: check with
respond_to?, or list the ones the app cannot do without in requires = [...] in its
.app.toml so it is not moved to a build without them.
Constants¶
| Constant | Value | Purpose |
|---|---|---|
TITLE_BAR_H |
11 | Title bar height (px) |
CORNER_R |
4 | Window corner radius |
TRANSPARENT_COLOR |
0x01 | Transparent color (passes through during compositing) |
SCROLLBAR_W |
10 | Scrollbar width |
SCROLLBAR_BTN_H |
10 | Scrollbar button height |
Example: Increment a Counter on Button Press¶
class CounterApp < FmrbApp
def on_create
@count = 0
redraw
end
def on_event(ev)
if ev[:type] == :mouse_down && ev[:button] == 1
@count += 1
redraw
elsif ev[:type] == :key_down && ev[:character] == "r"
@count = 0
redraw
end
end
def on_update
300
end
private
def redraw
clear_user_area
@gfx.draw_text(4, 4, "Count: #{@count}", theme_fg)
@gfx.present
end
end