アプリ設定ファイル (.app.toml)¶
Note
このページはアプリごとの設定です。システム自体の設定 (/etc/system_conf.toml と
/etc/wifi.toml) は システム設定 を参照してください。
Family mruby のアプリは、.app.rb の本体ファイルと 同名の .app.toml ファイル をペアで持ちます。.app.toml でアプリ名やウィンドウ設定を指定します。Ruby のアプリは、同じキーを .rb 先頭の #---fmrb コメントに書くこともでき (後述)、両方を使うこともできます。
ファイル名のルール¶
<app_handle_name>.app.rb # アプリ本体
<app_handle_name>.app.toml # 設定ファイル
例:
my_clock.app.rb
my_clock.app.toml
ペアで /app/<category>/ 以下に置きます(category は任意のサブディレクトリ。demo, game, tool 等が標準)。
.toml が要るのはどの場合か
ファイルを直接起動するとき — ファイル管理から実体をダブルクリックするとき — は同名の
.app.toml が必要です。無いと起動が断られ、理由がデスクトップに出ます。エディタの F5
やシェルからは .toml が無くても動き、その場合はファイル名がアプリ名になります。
| 言語 | 拡張子 |
|---|---|
| mruby | .app.rb |
| Lua | .app.lua |
| BASIC | .app.bas |
| MicroPython | .app.py |
| WebAssembly (C・TinyGo・Rust・Zig) | .app.wasm。WebAssembly のアプリ を参照 (開発版) |
キー一覧¶
| キー | 型 | 必須 | デフォルト | 用途 |
|---|---|---|---|---|
app_handle_name |
string | 任意 | (なし) | ハンドル名。慣例で本体ファイル名のベースと一致させる。システムは読まない |
app_screen_name |
string | 任意 | ファイル名 | 画面・ランチャー上に表示する名前 |
class |
string | 任意 | (なし) | 起動するクラス ("MyApp")。無ければ、ファイルが定義した FmrbApp の子クラス 1 つを起動する (ほかの子の親になっているものは数えない)。2 つ以上定義するファイルでは必要 |
default_window_mode |
string | 任意 | "window" |
"window" / "fullscreen" / "background" |
default_window_width |
integer | 任意 | 100 |
ウィンドウ幅 (px) |
default_window_height |
integer | 任意 | 100 |
ウィンドウ高さ (px) |
default_window_pos_x |
integer | 任意 | 50 |
ウィンドウ左上 X 座標 |
default_window_pos_y |
integer | 任意 | 50 |
ウィンドウ左上 Y 座標 |
resizable |
integer (0/1) | 任意 | 0 |
1 でユーザーがリサイズ可能 |
min_window_width |
integer | 任意 | 0 |
ユーザーが縮められる下限の幅。0 ならシステム既定 (64) |
min_window_height |
integer | 任意 | 0 |
ユーザーが縮められる下限の高さ。0 ならシステム既定 (64) |
large_memory |
integer (0/1) | 任意 | 0 |
1 で大きいヒープ領域を確保(メモリを多く使うアプリ用) |
launcher_visible |
bool / string | 任意 | true |
false または 0 でランチャーから非表示 |
rounded_corners |
bool / string | 任意 | true |
false でウィンドウ角の透過処理を無効化(fps を稼ぎたいときの最適化) |
app_screen_name_<lang> |
string | 任意 | (なし) | 言語別の表示名。例: app_screen_name_ja。システムの言語と一致するときに使われ、無ければ app_screen_name |
task_stack_kb |
integer | 任意 | 16 | アプリのタスクが使う C スタックの KB 数。スタック保護の例外が出るときだけ上げます。16〜64 に収められます |
fullscreen_switchable |
integer (0/1) | 任意 | 0 |
全画面アプリを Ctrl + Tab で退避・復帰させてよいなら 1(on_resume で描画面を作り直す必要があります) |
fullscreen_hires |
bool | 任意 | false |
全画面の間だけ 640x360 で動かしてよい (Modern とブラウザ版)。大きさは on_resize で届く |
window_frame |
string | 任意 | "normal" |
"none" で枠・タイトルバー・閉じるボタンの無いウィンドウ (後述) |
window_drag |
string | 任意 | "title" (枠つき)、"anywhere" (枠なし) |
ウィンドウをどこで掴んで動かすか: "title"・"anywhere"・"none" |
single_instance |
bool | 任意 | false |
同じファイルの 2 つ目の起動を断る |
exclusive_group |
string | 任意 | (なし) | 同じ名前 (15 バイトまで) を書いたアプリが動いている間は起動を断る。1 つしかない資源を取り合うアプリ向け |
movable |
bool | 任意 | false |
イメージに書いて別の端末へ運んでよい (動いているアプリを運ぶ) |
requires |
array | 任意 | (なし) | 運べるアプリが無いと続けられないメソッドの名前。それが無いビルドへは移らない |
screens / needs_pointer |
array / bool | 任意 | (なし) | Linux 版のキーボード専用のデスクトップ (320x170) 向け。描ける画面の形 (["426x240", "320x170"]) と、マウスなしで使えるなら needs_pointer = false。最初の [表] より前に書く |
icon |
string | 任意 | (拡張子別の既定) | アイコンファイルパス(.icon 形式) |
ウィンドウモード¶
| モード | 動作 | サイズ・位置 |
|---|---|---|
window |
タイトルバー付きのウィンドウ | default_window_* を使用 |
fullscreen |
画面全体を占有(他アプリは中断) | サイズは画面解像度、位置は (0, 0) 固定 |
background |
headless: ウィンドウを持たずに裏で動く (@gfx は nil) |
不要 |
fullscreen の場合、アプリの描画領域は画面全体です。window ではタイトルバー(11px)と枠線の内側です。どちらでも @gfx はその左上を (0, 0) として描き、大きさは @user_area_width × @user_area_height です。
全画面のアプリは fullscreen_switchable = 1 を宣言できます。宣言すると Ctrl + Tab で
退避して、後から同じ状態に戻れるようになります。
デスクトップ > アプリの切り替え を参照してください。
最小サンプル¶
app_handle_name = "hello"
app_screen_name = "Hello"
default_window_mode = "window"
default_window_width = 160
default_window_height = 80
default_window_pos_x = 20
default_window_pos_y = 30
対応する Ruby ファイル:
# /app/demo/hello.app.rb
class HelloApp < FmrbApp
def on_create
clear_user_area
@gfx.draw_text(4, 4, "Hello!", theme_fg)
@gfx.present
end
def on_update; 500; end
end
ファイルの末尾に起動のコードは要りません。ファイルが定義した FmrbApp の子クラスをランタイムが
起動します。
.rb ファイルの中の記述¶
同じキーは .rb 先頭のコメントにも書けるので、1 ファイルだけのアプリなら .app.toml は
要りません。囲みは先頭 512 バイトの中、最初のコードの行より前に置き、各行の先頭に # を
付けた TOML として書きます。
#---fmrb
# app_screen_name = "Hello"
# default_window_width = 200
# default_window_height = 120
#---
class HelloApp < FmrbApp
- 両方あるときはキーごとに合わせ、両方にあるキーは
.app.tomlが勝ちます。コメントに 既定を書き、.app.tomlで一部だけ上書きできます。 - この形で読むのは
.rbだけです (.lua・.bas・.pyはコメントの記号が違うため)。 - コメントだけの
.app.rbもランチャーに出ます。 - App Store で配るアプリには
.app.tomlが要ります (app_idなど導入のためのキーはそこから読まれます)。 - Ruby からは
FmrbApp.app_meta(path)で、合わせた記述を文字列の Hash として読めます。
枠なしのウィンドウ¶
window_frame = "none"
アバターやマスコットのための、枠・タイトルバー・閉じるボタンの無いウィンドウです。アプリの
描画領域はウィンドウ全体で、地は透けるので、アプリが描いた所だけが見えます。ウィンドウはどこを
掴んでも動かせ (window_drag = "anywhere"、ここでの既定)、動かさずに離せばクリック、動かさずに
1 秒押し続けると長押しです。右クリックと長押しは on_frameless_right_click(ev) を呼び、既定では
ウィンドウのメニュー (送る・読み直し・閉じる) が出ます。Ctrl+Q でも閉じられます。
既定ではウィンドウの四角全体がクリックを受けます。描いていない所のクリックを後ろへ通すには、
当たる形を申告します: set_hit_shape([[x, y, w, h], ...])、
set_hit_mask(hit_mask_from_art(rows, transparent: ".", scale: 3), x, y)、
add_hit_sprite(sprite)。その外の押下は後ろのウィンドウに届きます。見本は
/app/demo/avatar.app.rb です。
フルスクリーンアプリのサンプル¶
app_handle_name = "shooter"
app_screen_name = "Shooter"
default_window_mode = "fullscreen"
fullscreen ではウィンドウサイズや位置は無視されます。
大量メモリを必要とする場合¶
large_memory = 1 を指定すると、起動時に大きいメモリプールスロットが選択されます。
現在は1スロットのみ存在してます。
アイコン指定¶
icon = "usr/share/icon/blockgame.icon"
- ファイルは
/usr/share/icon/以下に置きます - 形式は テキスト形式。詳細は 画像・アイコンファイル を参照
iconを省略すると、本体ファイルの拡張子に応じた既定アイコンが使われます (.rb→ ruby、.lua→ lua、.bas→ basic、.py→ python、.wasm→ wasm)
ランチャーから隠す¶
開発中・デバッグ用アプリは launcher_visible = false で隠せます。
launcher_visible = false
リサイズ可能なウィンドウ¶
resizable = 1
1 でリサイズ可能。基底クラスは on_resize(w, h) を呼んでくれるので、サブクラスでオーバーライドして再描画してください。
アプリの配置先¶
/app/
├── demo/ # サンプル・デモ
├── game/ # ゲーム
│ └── rpg_demo/ # アプリと一緒にアセットを置く形式も可
│ ├── rpg_demo.app.rb
│ ├── rpg_demo.app.toml
│ ├── world.bmp
│ └── world.map.json
├── tool/ # ツール
└── (任意の名前)/
├── myapp.app.rb
└── myapp.app.toml
ランチャーは /app 直下のサブディレクトリをスキャンして .app.toml を検出します。さらに 1 階層下 (/app/<category>/<bundle>/*.app.toml)もスキャン対象なので、画像・マップなどのアセットをアプリと同じディレクトリにまとめる形式も有効です。
スキャンは起動時のみ
アプリ一覧は システム起動時に 1 回だけ スキャンされます。create_app や BLE で新規アプリを追加した後は、ランチャーを開いて右クリック で再スキャン、もしくは本体を再起動してください(Hello World ▸ ランチャーで反映する 参照)。
関連¶
- アプリの作り方は Hello World を参照
- アイコンファイルの作り方は 画像・アイコンファイル を参照