Coding Styles

日本語

UIng offers two equivalent ways to construct an interface. Both styles use the same controls and may be mixed in one application.

Regular API

The regular API is explicit and familiar. This guide mostly uses this form.


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

Block-based DSL

The block-based DSL keeps nested layouts visually close to their resulting control hierarchy:


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

Here is an example with a deeper nesting:


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

Both do ... end and { ... } pass a block. The following sections explain the common block forms and their equivalents in the regular API.

Configure a new object: new do ... end

For classes that support block construction, the new block lets you call methods on the new object without an explicit receiver. These two forms apply the same configuration:


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

# Block construction
button = UIng::Button.new("Save") do
  on_clicked { puts "Save clicked" }
end

new returns the created object regardless of the block's last expression. Creating an object does not attach it to a parent: use child or append to attach it. A Window also needs show to become visible.

You can receive the object as a block argument, such as do |button|. Use this explicit reference when assigning properties:


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

Writing just tooltip = "..." assigns a local variable, so write button.tooltip = "..." instead.

Internally, Crystal's with ... yield adds a lookup target for method calls without an explicit receiver; it does not change self itself. Outer local variables remain available. Inside an instance method, instance variables such as @entry still refer to the enclosing instance's variables.

Use the block result as a child: child do ... end

On Window and Group, child runs the block immediately and sets the returned Control as the child. These two forms have the same effect:


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

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

The block's last expression must return the Control to attach. The child block itself does not switch the implicit receiver. To configure the child, you can nest its own new block:


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

Here, the Box's new returns the Box, and child attaches it to the Window. The append calls inside the Box block are methods on that Box. You could also write:


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

Blocks that attach children

These blocks also run immediately and attach the child returned by their last expression. They do not switch the implicit receiver. In the table, control and bar stand for an existing Control and Toolbar, and parent stands for a Window or Group.

Target Block form Regular API equivalent
Window, Group child { control } parent.child = control
Window, Group set_child { control } parent.set_child(control) (alias for 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, and the Grid's coordinates and layout options have the same meaning as in the regular API. With an existing parent, you can use an explicit receiver, such as box.append(stretchy: true) do ... end.

Attachment methods such as Box#append themselves return Nil. If the last expression in a child block is box.append(...), it will not return a Control. End the block with box, or use Box.new do ... end as above.

Menu and toolbar item configuration blocks

These methods first create an item, then run a block where you can call methods on that item without an explicit receiver. They return the created item regardless of the block's last expression.

Target Methods accepting a configuration block Object configured and returned
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

Here, append_item is a method on the Menu; set_shortcut and on_clicked are methods on the new MenuItem. You can also receive the item with do |item|.

Create menus before the first Window. Quit items use UIng.on_should_quit instead of on_clicked. Add toolbar items before its first attachment. See Menu and Toolbar for details.

Event and lifecycle blocks

The same block syntax has different timing and meaning depending on the method receiving it:

Form Timing and purpose
new do ... end, item configuration blocks Configure the object immediately during construction
child do ... end, child attachment blocks Run immediately and attach the returned child
on_clicked do ... end and similar methods Register a callback that runs when the event occurs
draw, num_rows, etc. inside Handler.new Register callbacks that run for drawing or data queries
UIng.init do ... end Run after initialization and call uninit when the block exits

For example, draw do ... end inside Area::Handler.new do ... end registers a drawing callback, just like handler.draw do ... end; it does not draw immediately. Similarly, num_rows { rows.size } on a Table::Model::Handler registers the code used when the row count is queried. See Area and Table Model and Data.

The UIng.init block works with both the regular API and the DSL. See Runtime and Lifetime for individual resource cleanup.

Which to choose

  • Regular API: suits simple structures and code where you want the flow to be explicit.
  • DSL: suits deeply nested layouts that read best when written close to their hierarchy.

Both styles create the same controls. Either choice is fine as long as the project stays consistent.