コーディングスタイル

English

UIngには、インターフェースを構築するための同等な2つの書き方があります。 どちらも同じコントロールを使用しており、1つのアプリケーション内で併用できます。

通常のAPI

通常のAPIは明示的で分かりやすい書き方です。このガイドでは主にこの形式を 使用します。


window = UIng::Window.new("Hello", 300, 200)
window.child = UIng::Label.new("Hello from UIng")

ブロックベースのDSL

ブロックベースのDSLでは、ネストしたレイアウトと実際のコントロール階層を 近い形で記述できます。


UIng::Window.new("Hello", 300, 200) {
  child { UIng::Label.new("Hello from UIng") }
}

複雑な入れ子構造の例です。


UIng.init do
  UIng::Window.new("Hello World", 300, 200) { |win|
    on_closing { UIng.quit; true }
    child {
      UIng::Button.new("Click me") {
        on_clicked {
          win.msg_box("Info", "Button clicked!")
        }
      }
    }
    show
  }

  UIng.main
end

do ... endと{ ... }は、どちらもブロックを渡す書き方です。 以下では、よく使うブロックの役割と通常のAPIとの対応を説明します。

作ったオブジェクトを設定する: new do ... end

ブロック構築に対応するクラスでは、newのブロック内で、作ったオブジェクトの メソッドをレシーバなしで呼べます。次の2つは同じ設定を行います。


# 通常のAPI
button = UIng::Button.new("Save")
button.on_clicked { puts "Save clicked" }

# ブロック構築
button = UIng::Button.new("Save") do
  on_clicked { puts "Save clicked" }
end

newは、ブロックの最後の式によらず、生成したオブジェクトを返します。 ただし、生成しただけでは親には取り付けられません。childやappendで 取り付けます。Windowの表示にもshowが必要です。

必要ならdo |button|のようにオブジェクトを引数で受け取れます。 プロパティへの代入には、この明示的な参照を使います。


button = UIng::Button.new("Save") do |button|
  button.tooltip = "Save the document"
  on_clicked { puts "Save clicked" }
end

tooltip = "..."だけではローカル変数への代入になるため、 button.tooltip = "..."と書きます。

内部ではCrystalのwith ... yieldを使っています。これはレシーバを省略した メソッド呼び出しの探索先を追加する仕組みで、self自体は変わりません。 外側のローカル変数も使えます。インスタンスメソッド内で書いた@entryなどの インスタンス変数は、その外側のインスタンスのものを参照します。

ブロックの結果を子にする: child do ... end

WindowとGroupのchildは、ブロックをその場で実行し、返されたControlを 子に設定します。次の2つは同じ意味です。


window.child = UIng::Label.new("Hello")

window.child do
  UIng::Label.new("Hello")
end

ブロックの最後の式が、取り付けるControlである必要があります。 child自体はレシーバを切り替えません。子の設定には、さらにその子の newのブロックを使えます。


window.child do
  UIng::Box.new(:vertical, padded: true) do
    append UIng::Label.new("Name")
    append UIng::Entry.new, stretchy: true
  end
end

この例ではBoxのnewがBoxを返し、childがそれをWindowに取り付けます。 Box内のappendは、そのBoxのメソッドです。次のようにも書けます。


box = UIng::Box.new(:vertical, padded: true)
box.append(UIng::Label.new("Name"))
box.append(UIng::Entry.new, stretchy: true)
window.child = box

子を追加するブロックの一覧

次のブロックもその場で実行され、最後の式が返した子を取り付けます。 ブロック内でレシーバは切り替わりません。表のcontrolとbarは、 生成済みのControlとToolbar、parentはWindowまたはGroupを表します。

対象 ブロック形式 通常のAPIでの対応
Window、Group child { control } parent.child = control
Window、Group set_child { control } parent.set_child(control)(childの別名)
Box append(stretchy: true) { control } box.append(control, stretchy: true)
Form append("Name") { control } form.append("Name", control)
Grid append(left: 0, top: 0) { control } grid.append(control, left: 0, top: 0)
Grid insert_at(existing, :trailing) { control } grid.insert_at(control, existing, :trailing)
Tab append("Page", margined: true) { control } tab.append("Page", control, margined: true)
Tab insert_at("Page", 0) { control } tab.insert_at("Page", 0, control)
Window toolbar { bar } window.toolbar = bar

stretchy、margined、Gridの座標や配置オプションは、通常のAPIと同じ意味です。 既存の親を使う場合は、box.append(stretchy: true) do ... endのように レシーバを明示して呼べます。

Box#appendなどの追加メソッド自体の戻り値はNilです。 childの最後の式がbox.append(...)になると、Controlを返せません。 その場合は最後にboxを置くか、上の例のようにBox.new do ... endを使います。

メニュー項目・ツールバー項目の設定ブロック

これらは、項目を先に作り、その項目のメソッドをレシーバなしで呼べる 設定ブロックを実行します。戻り値は、ブロックの最後の式によらず生成した項目です。

対象 設定ブロックを渡せるメソッド 設定対象・戻り値
Menu append_item、append_check_item MenuItem
Menu append_preferences_item、append_about_item、append_quit_item MenuItem
Toolbar append_button、append_toggle_button ToolbarItem

UIng::Menu.new("File") do
  append_item("Open") do
    set_shortcut('O', UIng::Modifiers::Primary)
    on_clicked { |window| window.try &.open_file }
  end
end

この例のappend_itemはMenu、set_shortcutとon_clickedは生成した MenuItemのメソッドです。do |item|で項目を受け取ることもできます。

Menuは最初のWindowより先に作ります。Quit項目の終了処理は on_clickedではなくUIng.on_should_quitに登録します。Toolbarの項目は 最初の取り付けより先に追加します。詳しくはMenuと Toolbarを参照してください。

イベントやライフサイクルのブロックとの違い

同じブロック構文でも、呼び出すメソッドによって実行のタイミングと意味が異なります。

書き方 実行のタイミング・役割
new do ... end、項目の設定ブロック 作成時にその場で設定する
child do ... end、子を追加するブロック その場で実行し、返された子を取り付ける
on_clicked do ... endなど コールバックを登録し、イベント発生時に実行する
Handler.new内のdraw、num_rowsなど コールバックを登録し、描画やデータの問い合わせ時に実行する
UIng.init do ... end 初期化後に実行し、ブロック終了時にuninitする

たとえばArea::Handler.new do ... end内のdraw do ... endは、 その場で描画する命令ではありません。handler.draw do ... endと同じ描画 コールバックの登録です。Table::Model::Handlerのnum_rows { rows.size }も、 行数を問い合わせられたときの処理を登録します。詳しくはAreaと Tableのモデルとデータ供給を参照してください。

UIng.initのブロックは、通常のAPIでもDSLでも使えます。 個別リソースの解放方法はランタイムと寿命管理を参照してください。

使い分け

  • 通常のAPI: 構造が単純な場合や、コードの流れを明示的に追いたい場合に向きます。
  • DSL: 入れ子の深いレイアウトを、実際の階層に近い形で書きたい場合に向きます。

どちらを選んでも生成されるコントロールは同じです。プロジェクト内で 統一しておけば、どちらを使っても問題ありません。