Skip to content

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