コンテンツにスキップ

アプリ (FmrbApp)

FmrbApp は Family mruby のアプリケーション基底クラスです。ユーザーアプリは 必ず FmrbApp を継承して ライフサイクルメソッドを実装します。

最小サンプル

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  # 100ms 待つ
  end
end

ファイルにはクラスを書くだけです。末尾に起動のコードは要りません。ファイルを読み終えると、 ランタイムがそのファイルで定義された FmrbApp の子クラスを作って起動します。1 つのファイルに 子クラスを 2 つ以上書くときは、.app.toml (か #---fmrb の囲み) に class = "MyApp" と書いて 起動するものを名指しします。決まらないときや起動中に例外が出たときは、理由がエラーウィンドウとログに 出ます。

ウィンドウサイズなどは .app.toml か、.rb 先頭の #---fmrb コメントで指定します(アプリ設定ファイル (.app.toml) 参照)。

ライフサイクル

メソッド 呼び出し条件 戻り値の意味
on_create アプリ起動時に1回 任意(無視される)
on_update メインループ内で繰り返し 次回 on_update までの待機ミリ秒。デフォルト 330ms
on_event(ev) キーボード/マウス/ゲームパッド/HID 受信時 任意
on_suspend フルスクリーンアプリに切り替えられたとき 任意
on_resume 中断状態から復帰したとき 任意
on_resize(w, h) ウィンドウの大きさが変わったとき。角のドラッグや全画面の切り替え。fullscreen? と描画可能領域は更新済み 任意
on_quit_request Ctrl + Q のとき。すぐ閉じる代わりに呼ばれる 任意
on_checkpoint / on_restore 運べるアプリがイメージに書かれたとき、イメージから続けるとき (別の端末を含む)。動いているアプリを運ぶ を参照 任意
on_destroy アプリ終了時に1回 任意
(ファイルを読み終えると、ランタイムが子クラスを作って start を呼ぶ)
start
  └─ on_create
       └─ main_loop:
            ├─ on_update  → 戻り値 ms 分 _spin で待機
            ├─ _spin 中に on_event(ev), _handle_system_control(msg) をディスパッチ
            └─ アプリが止まるまで繰り返し (`running?` が false になるまで)
  └─ destroy → on_destroy

on_update の戻り値

短い値(10〜30ms)にするとフレームレートが上がりますが CPU を消費します。ゲームでは 16〜33ms、静的 UI では 100〜500ms が目安です。

イベントハンドリング (on_event(ev))

ev は Hash で、ev[:type] でイベント種別を判定します。

キーボード

def on_event(ev)
  case ev[:type]
  when :key_down
    keycode  = ev[:keycode]    # 文字コード(プラットフォーム依存)
    scancode = ev[:scancode]   # USB HID Usage ID(プラットフォーム共通)
    modifier = ev[:modifier]   # 修飾キービット (下記参照)
    char     = ev[:character]  # 文字(あれば)
    Log.info("key down: #{char.inspect}")
  when :key_up
    # ...
  end
end

修飾キービット(ev[:modifier])の構成:

ビット 値 意味
0 0x01 LSHIFT
1 0x02 RSHIFT
2 0x04 LCTRL
3 0x08 RCTRL
4 0x10 LALT
5 0x20 RALT

判定ヘルパが用意されています:

ev_ctrl?(ev)   # Ctrl が押されている
ev_shift?(ev)  # Shift が押されている
ev_alt?(ev)    # Alt が押されている

Note

文字キーを判定するときは scancode を使ってください。keycode はプラットフォーム間で値が変わります(SDL2 はアスキーを返す等)。

FmrbConst::KEY_* / MOD_* 定数

scancode の値は USB HID Usage ID なので、生の 0x29 (ESC)等を書く代わりに FmrbConst::KEY_ESC などの定数が使えます。修飾キーも FmrbConst::MOD_CTRL などのマスク定数があります。一覧は 定数 ▸ KEY_* / MOD_* を参照。

マウス

when :mouse_down, :mouse_up
  ev[:button]  # 1=左, 2=中, 3=右
  ev[:x]       # アプリの描画領域の左上からの X (@gfx の 0 と同じ所)
  ev[:y]       # 同じく Y
  ev[:wx]      # ウィンドウの左上 (タイトルバーを含む) からの X
  ev[:wy]      # 同じく Y
when :mouse_move
  ev[:x], ev[:y]

ev[:x] / ev[:y] は @gfx と原点が同じなので、描いた位置とクリックの位置が食い違いません。 ev[:wx] / ev[:wy] は、枠を気にする珍しいアプリ (自前の閉じるボタンなど) のためのものです。

タイトルバー上のクリック(閉じるボタンと、右クリックで出るウィンドウのメニュー: 送る・読み直し・閉じる)は、 アプリの on_event が呼ばれる前に基底クラスが処理します。呼ぶものは何もなく、super(ev) も書きません。

ホイール

ホイールのイベントは、カーソルの下のウィンドウではなく、キーボードの入力先になっているウィンドウに届きます。 読み取りは 2 つのどちらかで、ホイール以外のイベントなら nil が返るので、そのまま次へ 進めます。

rows = wheel_rows(ev)
if rows
  @scroll -= rows
  redraw
end
メソッド
wheel_rows(ev) 段数に本体の wheel_lines 設定を掛けたもの。行が文字の行であるものはこちら
wheel_notches(ev) 段数そのもの。行が文字の行でない一覧向け。ランチャーの升目は数行分の高さがあり、wheel_lines では飛びすぎます

1 段でどれだけ動くかは本体の設定であって、アプリごとの都合ではありません。

ゲームパッド

when :gamepad_down, :gamepad_up
  ev[:gamepad_id]  # 0以降
  ev[:button]      # 0..15
when :gamepad_axis
  ev[:gamepad_id]
  ev[:axis]        # 0..5
  ev[:value]       # 軸値

FmrbConst::GP_* 定数

ボタン番号には FmrbConst::GP_SQUARE / GP_CROSS / GP_START 等、軸番号には GP_AXIS_LX / GP_AXIS_LY などの定数があります。詳細は 定数 ▸ GP_* を参照。

ウィンドウ操作

メソッド 用途
set_window_position(x, y) ウィンドウ位置を変更
clear_user_area(color = FmrbConst::THEME_WINDOW_BG) アプリの描画領域(タイトルバー・枠の内側)を塗りつぶす。既定色はシステムのテーマに従い、この呼び出しでウィンドウ枠の描き直しと、付いている部品の再描画指定も行われる
draw_window_frame ウィンドウ枠(タイトルバー + 縁)を描き直す。clear_user_area が済ませるので、呼ぶのは描画領域の隅に描いたあと (枠の角の丸みが描画領域にかかるため) だけ
window_gfx 同じキャンバスに描く 2 つめの FmrbGfx で、(0, 0) がウィンドウの左上。描画領域の外 (自前の枠やタイトル) に描くときに使う。書体はキャンバスで共通なので set_font は @gfx で呼ぶ
request_fullscreen(on) / toggle_fullscreen ウィンドウと全画面を切り替える。VM は動いたままなのでアプリの状態は残る。結果は on_resize で届き、そのとき fullscreen? と描画可能領域は更新済み
request_file_select(mode = "open") システムのファイル選択ダイアログを呼び出し
sync_file(path, dest: nil) 描画・音声側にあるファイルの複製を、こちらのものと一致させる。違うときだけ転送する。画面を持たないアプリでも使える
request_reload スクリプトをリロード(ウィンドウのメニューの「読み直し」)
request_window_menu(x, y) ウィンドウのメニュー(送る・読み直し・閉じる)をウィンドウ内の位置に出す

スクロールバーは移動しました。draw_scrollbar と scrollbar_hit は無くなり、部品になって います。UI 部品 を参照してください。

@gfx.clear の代わりに clear_user_area

@gfx.clear(color) は キャンバス全体 を塗りつぶすため、タイトルバーや閉じるボタンも消えます。ウィンドウ枠を保ちたい場合は clear_user_area(color) を使ってください。

メッセージング

メソッド 用途
subscribe(topic) / unsubscribe(topic) トピックの購読
publish(topic, data=nil) トピックへ送信
send_message(dest_pid, msg_type, data) カーネルや特定アプリへの直接送信。data は MessagePack で自動シリアライズされる

詳細と受信ハンドラは Pub/Sub を参照。

タイマ

メソッド
set_timer(interval) { ... } interval ミリ秒後にブロックを 1 回実行します。id を返します
clear_timer(id) まだ発火していないものを取り消します

タイマは 1 回限りです。繰り返したいときは、ブロックの中で次を張り直します。確認はアプリの ループ 1 周につき 1 回なので、細かさは on_update の戻り値で決まります。

別のアプリを起動する

request_run(path, prev_pid = nil) はカーネルにファイルの起動をリクエストします。前の要求で 起動したものがあれば、その pid を渡して先に止められます。結果は新しい pid を載せた アプリ制御メッセージとして届きます (失敗なら nil)。渡せるのは /app と /home の下だけです。

キャンバスを増やす

create_canvas_gfx(width:, height:, z_offset: 1, transparent: false, transparent_color: 0) は、アプリ自身が持つキャンバスに結びついた FmrbGfx を返します。delete_canvas_gfx(gfx) で解放します (アプリが終わるとき、落ちたときにも自動で解放されます)。位置を決めて出すのは gfx.present(x, y) で、set_viewport と 組み合わせるとハードウェアでスクロールする層になります。

これは全画面のアプリ向けです。ウィンドウの管理は、焦点が移ったときに増やしたキャンバスまでは 面倒を見ません。

暇なときに GC を進める

self.idle_gc = true にすると、回収を細かく分けて、アプリが何もしていない時間に少しずつ 進めます。途中で 100〜200 ミリ秒止まるのを避けたいアプリ — 演奏やアニメーション — で、かつ 確保を無くしきれないときのためのものです。

代償が 2 つあります。世代別モードが切れて自動では戻らないことと、1 回の刻みの分だけ メッセージが遅れうることです。ずっと忙しいアプリは、放っておいても元の挙動に戻ります。

実行制御

メソッド 用途
start イベントループ開始(on_create が呼ばれる)。ここから running? は true。ファイルを読み終えたあとランタイムが呼ぶので、アプリは呼ばない
stop 終わらせる。running? が false になり、次の _spin の後 destroy へ
destroy カーネルへ exit を通知し、@gfx.destroy、on_destroy、_cleanup

| on_quit_request | Ctrl + Q のときに、すぐ終了する代わりに呼ばれる。既定は終了。保存していないものがあるなら、上書きして先に尋ねる | | request_early_update | 今の待ちをすぐ終える。アプリが指定した待ち時間を待たずに on_update へ進む |

request_early_update があるおかげで、暇なアプリは長く眠れます。抜ける手立てが無いと 「次の期限まで眠る」は、後から急ぎで頼まれるかもしれない用事に合わせて短く刻むしかなく、 それは名前を変えた定期確認です。意味があるのはコールバックの中 (on_control、on_event) だけで、on_update からでは次の待ち時間がどのみち計算し直されます。

テーマの色を使う

数値を 1 つも書かずにシステムの色を取れる読み取りが 5 つあります。これを使えば、本体の テーマと利用者の配色の上書きに自動的に従います。

メソッド 役割
theme_bg 地の色
theme_fg theme_bg の上に乗る文字の色
theme_accent 選択、強調
theme_border 罫線、囲み、控えめな文字
theme_fg_light 強調色やボタンの上に乗る文字の色

設定と、覚えておく状態

アプリが自分でファイルを開かずに持てる、小さな表が 2 つあります。どちらも TOML で、 文字列・整数・true/false を入れられ、ファイルが無いか壊れているときは {} として読めます。

メソッド 置き場所 用途
app_settings / save_app_settings(hash) /home/<app_handle_name>.toml 利用者の選択 (名前やレベルなど)。保存は渡したキーの行だけを書き換えるので、利用者が書いたコメントは残ります
app_state / save_app_state(hash) /tmp/<app_handle_name>.state.toml 次に開いたときに戻る所 (最後に開いたフォルダなど)。本体を再起動するまで残り、値が変わったときだけ書きます
def on_create
  @dir = app_state["dir"] || "/home"
end

def on_destroy
  save_app_state("dir" => @dir)
end

app_handle_name はアプリのメタデータから、無ければファイル名から決まります。File Manager は app_state を使って、閉じたときのフォルダで開き直します。

アプリから読めるもの

内容
@gfx (gfx でも可) FmrbGfx インスタンス(描画 API。headless モードでは nil)
name アプリの表示名(.toml の app_screen_name)
platform :esp32 または :linux
running? アプリが動作中なら true
fullscreen? フルスクリーンならば true
closable? クローズボタンでアプリを止めてよいか。画面を占有するアプリは closable = false で切れます
rounded_corners? このウィンドウの角が丸いかどうか。枠を自分で描くアプリ向け
@window_width / @window_height ウィンドウ全体のサイズ
@pos_x / @pos_y ウィンドウ左上の絶対座標
@user_area_width / @user_area_height アプリの描画領域(@gfx が描く所)のサイズ
frameless? window_frame = "none" の枠なしウィンドウなら true
window_gfx ウィンドウの左上を (0, 0) として描く

@_ で始まる名前は基底クラスのものです

2.1 から、基底クラスは自分の状態を @_ 付きの変数に持ちます。@_ で始まらない変数は アプリのものだと考えてかまいません。とくに困っていたのが @running と @name で、 アプリが自分の @running を置くと黙って終了していました。今は running? と name で 読みます。

音源はここには入りません。アプリが FmrbAudio.new(self) で自分の分を作ります。

(0, 0) はアプリの描画領域の左上

@gfx は、アプリが描いてよい描画領域の左上から描きます。枠のあるウィンドウでは枠の内側、 枠なし (window_frame = "none") ではウィンドウの左上、全画面では画面の左上です。どの形でも 同じコードで描き、幅 @user_area_width・高さ @user_area_height に収めます。原点は全画面への 出入り・枠の切り替え・画面の大きさの違う端末への移動で変わりますが、基底が持ち直すので on_resize では描き直すだけで済みます。スプライト、set_sprite_clip、UI 部品 も 同じ原点です。

ファイル・ディレクトリのパス

File.open / Dir.open にはルート相対のパス(/home/foo.txt など)や SD カードの /mnt/sd/... をそのまま渡します。詳細は ファイル・I/O ▸ ファイル名前空間 を参照。

クラスメソッド

メソッド 用途
FmrbApp.language 利用者が選んだ表示言語。"en" か "ja"
FmrbApp.ps 全プロセスの状態(id, name, state, vm_type, mem_*, stack_water など)の Array of Hash
FmrbApp.config(section) アプリの .toml から指定セクションを読み出し
FmrbApp.wallclock 現在時刻 ({year, month, day, hour, minute, second})
FmrbApp.gfx_stats 描画統計 {cmds:, presents:}
FmrbApp.wasm_stats / FmrbApp.wasm_app_stats(pid) WebAssembly のランタイムの様子 (running、apps、pool_used、pool_total、traps など。ランタイムの無い端末では全部 0) と、1 つの WebAssembly のアプリ の様子 (pages、max_pages、binary_size、hook_us、hook_max_us、calls。pid が WebAssembly のアプリでなければ nil) (開発版)
FmrbApp.sys_pool_info システムメモリプール情報
FmrbApp.pool_used 自分のプールを何バイト使ったか。読めないときは -1。処理の前後で引き算すると、その処理が出したごみの量が分かります
FmrbApp.heap_info ESP-IDF ヒープ情報(free, total, min_free, largest_block ほか)
FmrbApp.enable_cursor マウスカーソルを表示(最初のマウス移動まで遅延あり)
FmrbApp.set_cursor_visible(visible) カーソルの即時表示/非表示。フルスクリーンゲームで非表示にし、終了時に戻す用途
FmrbApp.uptime_us / FmrbApp.uptime_ms 起動からのマイクロ秒 / ミリ秒 (uptime_ms は開発中の版)
FmrbApp.wifi_info / FmrbApp.wifi_connected? つながっているネットワークの情報と、つながっているかどうか
FmrbApp.usb_devices USB ホスト端子につながっているもの
FmrbApp.set_kana_mode(mode) かな入力の切替。0 ASCII、1 ひらがな、2 カタカナ。結果は kana_mode イベントで返ります
FmrbApp.audio_volume / FmrbApp.audio_muted? 音量の段と、ミュート中かどうか
FmrbApp.battery_level / FmrbApp.battery_charging? 電池の残量 (%。電池の無い機種では nil) と、充電中かどうか
FmrbApp.clipboard / FmrbApp.set_clipboard(text) 共有のクリップボード
FmrbApp.app_meta(path) アプリファイルの記述 (.app.toml と #---fmrb を合わせたもの) を文字列の Hash で。アプリでなければ nil
FmrbApp.pid / FmrbApp.script_path 自分のプロセス id と、起動したファイル
FmrbApp.checkpoint(pid) / FmrbApp.move(pid, to) ほかのアプリをイメージに書く・別の端末へ移すよう頼む (Shell の checkpoint / amove)
FmrbApp._get_last_error 最後のアプリエラー(あれば {name:, error:})

本体の設定 (FmrbSystem)

本体の設定やサービスを変えるメソッドは、普通のアプリが使うものと分けて FmrbSystem に あります。デスクトップと設定のアプリのためのものです。

メソッド 用途
FmrbSystem.set_wallclock(year, month, day, hour, minute, second) RTC・システム時刻を設定
FmrbSystem.reboot 再起動します
FmrbSystem.power_actions / FmrbSystem.power(action) この端末でできる電源の操作 (端末では :reset、Linux 機では :power_off・:suspend など) と、その実行
FmrbSystem.set_audio_mute(on) / FmrbSystem.set_audio_volume(step) ミュートと音量
FmrbSystem.wifi_networks(scan) / wifi_connect(ssid, password) / wifi_disconnect / wifi_forget(ssid) WiFi の設定
FmrbSystem.ble_start / ble_state Bluetooth LE のサービス

全部 (34 個。Linux 版の設定を含む) は sig/fmrb_system.rbs にあります。これらを FmrbApp.<名前> で呼ぶと NoMethodError になります。

動いているアプリを運ぶ

.app.toml に movable = true と書いた (mruby で動く) アプリは、イメージに書いて、そこから 続けられます。同じ端末でも、Asterism でつながった別の端末でもかまいません (ウィンドウの メニューの「送る」、Shell の checkpoint / amove)。

メソッド 用途
checkpoint(restart: false) 自分を /tmp/<名前>.ckpt に書いて閉じるよう頼む。restart: true ですぐ起動し直す。頼めたら nil、頼めないときは理由の文字列
move_to(node_id) 自分を別の端末へ移すよう頼む
on_checkpoint イメージが書けて、ここで閉じる直前に呼ばれる (on_destroy は来ない)
on_restore イメージから続ける直前に呼ばれる。インスタンス変数・Task・タイマ、ウィンドウと購読は戻っているが、描いた絵は戻らないのでここで描き直す。画面の大きさが違う端末へ移ったときは先に on_resize が来る
on_checkpoint_refused(reason) イメージが書けなかった・移動を断られた。アプリはそのまま続く

移った先のビルドには、すべての端末に共通でないメソッドが無いことがあります。respond_to? で 確認するか、無いと続けられないものを .app.toml の requires = [...] に書くと、それが無い ビルドへは移りません。

定数

定数 値 用途
TITLE_BAR_H 11 タイトルバーの高さ (px)
CORNER_R 4 ウィンドウ角の半径
TRANSPARENT_COLOR 0x01 透明色(合成時に透過)
SCROLLBAR_W 10 スクロールバー幅
SCROLLBAR_BTN_H 10 スクロールバーボタン高さ

サンプル: ボタンを押されたら数値を増やす

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