Glimmer DSL for LibUI

Glimmer DSL for LibUI handles much of the low-level resource management automatically:

• Automatic Cleanup: When a control is destroyed, it is automatically removed from its parent container (horizontal_box, vertical_box, form, window, or group).
• Data Binding: When a control with a data-binding is destroyed, the observer registration is automatically deregistered.
• Memory Management:
  • image instances and table model instances are automatically freed after the window is destroyed.
  • font_button and color_button controls automatically manage font descriptors and color value pointers.
• Garbage Collection: All controls are protected from Ruby's garbage collection until they are explicitly destroyed, ensuring stability during the GUI lifecycle.

You can apply transformations to graphics within an area using transform blocks or by providing a matrix.

• Declarative Nature: area, path, and nested shapes are declarative. The order of fill, stroke, and transform calls does not matter.
• Automatic Cleanup: Any transform applied within a block is automatically reversed at the end of that block. This prevents transformations on one path from affecting subsequent paths.
• Inheritance: You can set a matrix or transform directly on an area to apply it to all nested paths.
• Matrix Reuse: For complex transformations, you can define a matrix block and reuse it across different elements.

# Using a transform block
transform {
  translate 100, 100
  rotate 100, 100, -9 * n
}

# Using a reusable matrix
m1 = matrix {
  translate 100, 100
  rotate 100, 100, -9 * n
}
transform m1

Glimmer DSL for LibUI supports two ways to bind data to a table:

1. Implicit Data-Binding: Pass the data object (like an Array) directly to cell_rows. Any changes to the array (like delete_at or updating an index) are automatically reflected in the table.
2. Explicit Data-Binding: Use the cell_rows <= [self, :attribute_name, ...] syntax. This binds the table to a specific attribute of an object. When the attribute is updated (e.g., self.animals = new_array), the table updates automatically.

# Implicit
table { 
  cell_rows data 
}

# Explicit
table { 
  cell_rows <= [self, :animals, column_attributes: {'Animal' => :name}] 
}

Instead of redrawing one large canvas for a complex game or dynamic UI, you can represent individual components (like Tetris blocks) as separate area widgets. This approach ensures that when a single component changes (e.g., a color change), only that specific small area is redrawn, significantly improving performance for high-frequency updates.

# Conceptual pattern from the Tetris example:
# Each block is its own area containing squares and polygons
block[:area] = area {
  block[:background_square] = square(0, 0, block_size) { fill color }
  block[:top_bevel_edge] = polygon { 
    point_array 0, 0, block_size, 0, ... 
    fill color_variant
  }
  # ... other bevel edges and borders
}

Glimmer proxy objects automatically proxy method calls to the wrapped LibUI Fiddle pointer. For example, calling window_proxy.title automatically invokes the corresponding LibUI operation (e.g., LibUI.window_title(window_proxy.libui).to_s) without requiring you to manually manage the Fiddle pointer.

w = window('hello world')
w.title == LibUI.window_title(w.libui).to_s # => true

The modern version of Glimmer DSL for LibUI supports data-binding, allowing you to link UI properties directly to model attributes. This reduces the need for manual observer registration for every individual UI element.

In the Tic Tac Toe example, the string property of an area text element is bound to a specific cell in the board model using the <= operator:

string <= [@tic_tac_toe_board[row + 1, column + 1], :sign]

This syntax tells the UI to automatically update the text whenever the :sign attribute of the object at [@tic_tac_toe_board[row + 1, column + 1]] changes.

# Example of data-binding a string property to a model attribute
text(23, 19) {
  string {
    font family: 'Arial', size: 16
    string <= [@tic_tac_toe_board[row + 1, column + 1], :sign]
  }
}

The table control simplifies data management by automatically constructing the required TableModelHandler, TableModel, and TableParams based on your cell_rows and nested columns (like text_column).

Automatic Synchronization: The cell_rows data has implicit data-binding. When you modify the cell_rows array, the table is automatically updated:

• Deleting a row from cell_rows deletes the corresponding row in the UI.
• Inserting a row into cell_rows inserts a row in the UI.
• Updating a value in cell_rows updates the cell in the UI.

In Glimmer DSL for LibUI, you can achieve bidirectional data-binding for widget values (like spinbox or color_button) using the <=> operator. To ensure the UI updates (e.g., redrawing an area) when the data changes, use the after_write option within the binding.

For example, when a spinbox value changes, you can trigger a redraw of an @area component:

spinbox(0, 100) { |sb|
  stretchy false
  value <=> [self, "datapoints[#{i}]", after_write: -> { @area.queue_redraw_all }]
}