glimmer-dsl-libui 0.0.28 → 0.1.3

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.0.28
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.1.3
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ce2853efdbecf6ebdc73/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-libui/maintainability)
@@ -19,7 +19,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - Scaffolding for new custom controls, apps, and gems
 - Native-Executable packaging on Mac, Windows, and Linux.
 
-Example:
+Hello, World!
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -32,6 +32,98 @@ window('hello world').show
 ![glimmer-dsl-libui-mac-basic-window.png](images/glimmer-dsl-libui-mac-basic-window.png)
 ![glimmer-dsl-libui-linux-basic-window.png](images/glimmer-dsl-libui-linux-basic-window.png)
 
+Basic Table Progress Bar
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+data = [
+  ['task 1', 0],
+  ['task 2', 15],
+  ['task 3', 100],
+  ['task 4', 75],
+  ['task 5', -1],
+]
+
+window('Task progress', 300, 200) {
+  horizontal_box {
+    table {
+      text_column('Task')
+      progress_bar_column('Progress')
+
+      cell_rows data
+    }
+  }
+}.show
+```
+
+![glimmer-dsl-libui-mac-basic-table-progress-bar.png](images/glimmer-dsl-libui-mac-basic-table-progress-bar.png)
+![glimmer-dsl-libui-linux-basic-table-progress-bar.png](images/glimmer-dsl-libui-linux-basic-table-progress-bar.png)
+
+Area Gallery
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Area Gallery', 400, 400) {
+  vertical_box {
+    area {
+      path { # declarative stable path
+        square(0, 0, 100)
+        square(100, 100, 400)
+        
+        fill r: 102, g: 102, b: 204
+      }
+      path { # declarative stable path
+        rectangle(0, 100, 100, 400)
+        rectangle(100, 0, 400, 100)
+        
+        fill r: 204, g: 102, b: 204
+      }
+      path { # declarative stable path
+        figure(100, 100) {
+          line(100, 400)
+          line(400, 100)
+          line(400, 400)
+
+          closed true
+        }
+
+        fill r: 202, g: 102, b: 104, a: 0.5
+        stroke thickness: 1, r: 0, g: 0, b: 0
+      }
+      path { # declarative stable path
+        figure(0, 0) {
+          bezier(200, 100, 100, 200, 400, 100)
+          bezier(300, 100, 100, 300, 100, 400)
+          bezier(100, 300, 300, 100, 400, 400)
+
+          closed true
+        }
+
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke thickness: 2, r: 0, g: 0, b: 0
+      }
+      path { # declarative stable path
+        arc(200, 200, 90, 0, 360, false)
+
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke thickness: 2, r: 0, g: 0, b: 0
+      }
+    }
+  }
+}.show
+```
+
+![glimmer-dsl-libui-mac-area-gallery.png](images/glimmer-dsl-libui-mac-area-gallery.png)
+![glimmer-dsl-libui-linux-area-gallery.png](images/glimmer-dsl-libui-linux-area-gallery.png)
+
+[Check Out Many More Examples Over Here!](#examples)
+
 NOTE: [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) is in early alpha mode (only supports included [examples](#examples)). Please help make better by contributing, adopting for small or low risk projects, and providing feedback. It is still an early alpha, so the more feedback and issues you report the better.
 
 Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interested in:
@@ -43,9 +135,10 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.0.28](#-glimmer-dsl-for-libui-0028)
+- [Glimmer DSL for LibUI 0.1.3](#-glimmer-dsl-for-libui-013)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
+  - [Girb (Glimmer IRB)](#girb-glimmer-irb)
   - [API](#api)
     - [Supported Controls](#supported-controls)
     - [Common Control Properties](#common-control-properties)
@@ -53,11 +146,11 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Extra Dialogs](#extra-dialogs)
     - [Extra Operations](#extra-operations)
     - [Table API](#table-api)
+    - [Area API](#area-api)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
     - [API Gotchas](#api-gotchas)
     - [Original API](#original-api)
   - [Glimmer Style Guide](#glimmer-style-guide)
-  - [Girb (Glimmer IRB)](#girb-glimmer-irb)
   - [Examples](#examples)
     - [Basic Window](#basic-window)
     - [Basic Button](#basic-button)
@@ -80,6 +173,9 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Table Checkbox Text](#basic-table-checkbox-text)
     - [Basic Table Progress Bar](#basic-table-progress-bar)
     - [Form Table](#form-table)
+    - [Basic Area](#basic-area)
+    - [Dynamic Area](#dynamic-area)
+    - [Area Gallery](#area-gallery)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -167,7 +263,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.0.28'
+gem 'glimmer-dsl-libui', '~> 0.1.3'
 ```
 
 Add `require 'glimmer-dsl-libui'` at the top, and then `include Glimmer` into the top-level main object for testing or into an actual class for serious usage.
@@ -194,6 +290,24 @@ end
 Application.new.launch
 ```
 
+If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), check out [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. You may refer to the [API](#api) later on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
+
+## Girb (Glimmer IRB)
+
+You can run the `girb` command (`bin/girb` if you cloned the project locally) to do some quick and dirty experimentation and learning:
+
+```
+girb
+```
+
+This gives you `irb` with the `glimmer-dsl-libui` gem loaded and the `Glimmer` module mixed into the main object for easy experimentation with GUI.
+
+![glimmer-dsl-libui-girb.png](images/glimmer-dsl-libui-girb.png)
+
+For a more advanced code editing tool, check out the [Meta-Example (The Example of Examples)](#examples).
+
+Gotcha: On the Mac, when you close a window opened in `girb`, it remains open until you enter `exit` or open another GUI window.
+
 ## API
 
 Any control returned by a [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) keyword declaration can be introspected for its properties and updated via object-oriented attributes (standard Ruby `attr`/`attr=` or `set_attr`).
@@ -223,17 +337,21 @@ w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0
 Control(Args) | Properties | Listeners
 ------------- | ---------- | ---------
 `about_menu_item` | None | `on_clicked`
+`area` | None | `on_draw`
+`arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)` | `x_center` (`Numeric`), `y_center` (`Numeric`), `radius` (`Numeric`), `start_angle` (`Numeric`), `sweep` (`Numeric`), `is_negative` (Boolean) | None
+`bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)` | `c1_x` (`Numeric`), `c1_y` (`Numeric`), `c2_x` (`Numeric`), `c2_y` (`Numeric`), `end_x` (`Numeric`), `end_y` (`Numeric`) | None
 `button(text as String)` | `text` (`String`) | `on_clicked`
 `button_column(name as String)` | `enabled` (Boolean) | None
 `checkbox(text as String)` | `checked` (Boolean), `text` (`String`) | `on_toggled`
-`checkbox_column(name as String)` | `editable` (Boolean) [Windows-only due to a current libui limitation] | None
-`checkbox_text_column(name as String)` | `editable` (Boolean) [Windows-only due to a current libui limitation], `editable_checkbox` (Boolean) [Windows-only due to a current libui limitation], `editable_text` (Boolean) | None
+`checkbox_column(name as String)` | `editable` (Boolean) | None
+`checkbox_text_column(name as String)` | `editable` (Boolean), `editable_checkbox` (Boolean), `editable_text` (Boolean) | None
 `combobox` | `items` (`Array` of `String`), `selected` (`Integer`) | `on_selected`
 `color_button` | `color` (Array of `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float`), `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float` | `on_changed`
 `date_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`, `mday` as `Integer`, `mon` as `Integer`, `year` as `Integer`, `wday` as `Integer`, `yday` as `Integer`, `dst` as Boolean) | `on_changed`
 `date_time_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`, `mday` as `Integer`, `mon` as `Integer`, `year` as `Integer`, `wday` as `Integer`, `yday` as `Integer`, `dst` as Boolean) | `on_changed`
 `editable_combobox` | `items` (`Array` of `String`), `text` (`String`) | `on_changed`
 `entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
+`figure(x as Numeric, y as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `closed` (Boolean) | None
 `font_button` | `font` [read-only] (`Hash` of keys: `:family`, `:size`, `:weight`, `:italic`, `:stretch`), `family` as `String`, `size` as `Float`, `weight` as `Integer`, `italic` as `Integer`, `stretch` as `Integer` | `on_changed`
 `form` | `padded` (Boolean) | None
 `grid` | `padded` (Boolean) | None
@@ -245,19 +363,23 @@ Control(Args) | Properties | Listeners
 `image_column(name as String)` | None | None
 `image_text_column(name as String)` | None | None
 `label(text as String)` | `text` (`String`) | None
+`line(x as Numeric, y as Numeric)` | `x` (`Numeric`), `y` (`Numeric`) | None
 `menu(text as String)` | None | None
 `menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
 `multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `msg_box(window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `msg_box_error(window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `non_wrapping_multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
+`path` | `fill` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`), `stroke` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, `:cap` as `Numeric`, `:join` as `Numeric`, `:thickness` as `Numeric`, `:miter_limit` as `Numeric` ) | None
 `preferences_menu_item` | None | `on_clicked`
 `progress_bar` | `value` (`Numeric`) | None
 `progress_bar_column(name as String)` | None | None
 `quit_menu_item` | None | `on_clicked`
 `radio_buttons` | `selected` (`Integer`) | `on_selected`
+`rectangle(x as Numeric, y as Numeric, width as Numeric, height as Numeric)` |  `x` (`Numeric`), `y` (`Numeric`), `width` (`Numeric`), `height` (`Numeric`) | None
 `slider(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
 `spinbox(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
+`square(x as Numeric, y as Numeric, length as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `length` (`Numeric`) | None
 `tab` | `margined` (Boolean), `num_pages` (`Integer`) | None
 `tab_item(name as String)` | `index` [read-only] (`Integer`), `margined` (Boolean), `name` [read-only] (`String`) | None
 `table` | `cell_rows` (`Array` (rows) of `Arrays` (row columns) of cell values (e.g. `String` values for `text_column` cells or `Array` of `image`/`String` for `image_text_column`)), `editable` as Boolean | None
@@ -302,6 +424,7 @@ Control(Args) | Properties | Listeners
 - `ControlProxy::image_proxies`: returns all instantiated `image` proxies in the application
 - `ControlProxy::main_window_proxy`: returns the first window proxy instantiated in the application
 - `ControlProxy#window_proxy`: returns the window proxy parent for a control
+- `ControlProxy#content {...}`: re-opens control's content to add more nested controls or properties
 
 ### Table API
 
@@ -321,6 +444,148 @@ Note that the `cell_rows` property declaration results in "implicit data-binding
 - Inserting cell rows: Calling `Array#<<`, `Array#push`, `Array#prepend`, or any insertion/addition `Array` method automatically inserts rows in actual `table` control
 - Changing cell rows: Calling `Array#[]=`, `Array#map!`, or any update `Array` method automatically updates rows in actual `table` control
 
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+data = [
+  ['Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO', '80014'],
+  ['Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA', '02101'],
+  ['Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL', '60007'],
+  ['Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA', '98101'],
+  ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA', '90001'],
+]
+
+window('Contacts', 600, 600) { |w|
+  margined true
+  
+  vertical_box {
+    form {
+      stretchy false
+      
+      @name_entry = entry {
+        label 'Name'
+      }
+      @email_entry = entry {
+        label 'Email'
+      }
+      @phone_entry = entry {
+        label 'Phone'
+      }
+      @city_entry = entry {
+        label 'City'
+      }
+      @state_entry = entry {
+        label 'State'
+      }
+    }
+    
+    button('Save Contact') {
+      stretchy false
+      
+      on_clicked do
+        new_row = [@name_entry.text, @email_entry.text, @phone_entry.text, @city_entry.text, @state_entry.text]
+        if new_row.include?('')
+          msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+        else
+          data << new_row # automatically inserts a row into the table due to implicit data-binding
+          @name_entry.text = ''
+          @email_entry.text = ''
+          @phone_entry.text = ''
+          @city_entry.text = ''
+          @state_entry.text = ''
+        end
+      end
+    }
+    
+    table {
+      text_column('Name')
+      text_column('Email')
+      text_column('Phone')
+      text_column('City')
+      text_column('State')
+
+      cell_rows data # implicit data-binding
+    }
+  }
+}.show
+```
+
+![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
+
+Learn more by checking out [examples](#examples).
+
+### Area API
+
+The `area` control can be used in one of two ways:
+- Declaratively via stable paths: useful for stable paths that will not change later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Paths proxy objects are preserved across redraws assuming there would be few stable paths (mostly for decorative reasons).
+- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change. Open an `on_draw` listener block and nest `path(area_draw_params)` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
+
+Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Area', 400, 400) {
+  margined true
+  
+  vertical_box {
+    area {
+      path { # a stable path is added declaratively
+        rectangle(0, 0, 400, 400)
+        
+        fill r: 102, g: 102, b: 204, a: 1.0
+      }
+    }
+  }
+}.show
+```
+
+![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png)
+
+Here is the same example using a semi-declarative `area` with `on_draw` listener and a dynamic path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Area', 400, 400) {
+  margined true
+  
+  vertical_box {
+    area {
+      on_draw do |area_draw_params|
+        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+          rectangle(0, 0, 400, 400)
+          
+          fill r: 102, g: 102, b: 204, a: 1.0
+        }
+      end
+    }
+  }
+}.show
+```
+
+Check [examples/dynamic_area.rb](#dynamic-area) for a more detailed semi-declarative example.
+
+Available nested `path` shapes:
+- `rectangle(x as Numeric, y as Numeric, width as Numeric, height as Numeric)`
+- `square(x as Numeric, y as Numeric, length as Numeric)`
+- `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)`
+- `line(x as Numeric, y as Numeric)`
+- `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)`
+- `figure(x as Numeric, y as Numeric)` (composite that can contain other shapes) (can set `closed true` to connect last point to first point automatically)
+
+In general, it is recommended to use declarative stable paths whenever feasible since they require less code and simpler maintenance. But, in more advanced cases, semi-declarative dynamic paths could be used instead, especially if there are thousands of paths.
+
+To redraw an `area`, you may call `#queue_redraw_all` method.
+
 ### Smart Defaults and Conventions
 
 - `horizontal_box`, `vertical_box`, `grid`, and `form` controls have `padded` as `true` upon instantiation to ensure more user-friendly GUI by default
@@ -349,11 +614,14 @@ Note that the `cell_rows` property declaration results in "implicit data-binding
 - Table `cell_rows` data has implicit data-binding to table cell values for deletion, insertion, and change (done by diffing `cell_rows` value before and after change and auto-informing `table` of deletions [`LibUI.table_model_row_deleted`], insertions [`LibUI.table_model_row_deleted`], and changes [`LibUI.table_model_row_changed`]). When deleting data rows from `cell_rows` array, then actual rows from the `table` are automatically deleted. When inserting data rows into `cell_rows` array, then actual `table` rows are automatically inserted. When updating data rows in `cell_rows` array, then actual `table` rows are automatically updated.
 - `image` instances are automatically freed from memory after `window` is destroyed.
 - `image` `width` and `height` can be left off if it has one `image_part` only as they default to the same `width` and `height` of the `image_part`
+- `area` paths are specified declaratively with figures underneath (e.g. `rectangle`) and `area` draw listener is automatically generated
+- Observe figure properties (e.g. `rectangle` `width`) for changes and automatically redraw containing area accordingly
+- Observe `path` `fill` and `stroke` hashes for changes and automatically redraw containing area accordingly
 
 ### API Gotchas
 
 - There is no proper way to destroy `grid` children due to [libui](https://github.com/andlabs/libui) not offering any API for deleting them from `grid` (no `grid_delete` similar to `box_delete` for `horizontal_box` and `vertical_box`).
-- `table` `checkbox_column` and `checkbox_text_column` checkbox editing currently only works in Windows due to a current limitation in [libui](https://github.com/andlabs/libui).
+- `table` `checkbox_column` and `checkbox_text_column` checkbox editing only works on Windows and Linux (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
 
 ### Original API
 
@@ -369,21 +637,9 @@ check out the [libui C headers](https://github.com/andlabs/libui/blob/master/ui.
 - Control listeners are always declared starting with on_ prefix and affixing listener event method name afterwards in underscored lowercase form. Their multi-line blocks have a `do; end` style.
 - Pure logic multi-line blocks that do not constitute GUI DSL view elements have `do; end` style to clearly separate logic code from view code.
 
-## Girb (Glimmer IRB)
-
-You can run the `girb` command (`bin/girb` if you cloned the project locally):
-
-```
-girb
-```
-
-This gives you `irb` with the `glimmer-dsl-libui` gem loaded and the `Glimmer` module mixed into the main object for easy experimentation with GUI.
-
-Gotcha: On the Mac, when you close a window opened in `girb`, it remains open until you enter `exit` or open another GUI window.
-
 ## Examples
 
-These examples include reimplementions of the examples in the [LibUI](https://github.com/kojix2/LibUI) project utilizing the [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) as well as brand new examples.
+The following examples include reimplementions of the examples in the [LibUI](https://github.com/kojix2/LibUI) project utilizing the [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) as well as brand new examples.
 
 To browse all examples, simply launch the [Meta-Example](examples/meta_example.rb), which lists all examples and displays each example's code when selected. It also enables code editing to facilitate experimentation and learning.
 
@@ -2581,6 +2837,441 @@ window('Contacts', 600, 600) { |w|
 }.show
 ```
 
+### Basic Area
+
+[examples/basic_area.rb](examples/basic_area.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_area.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/basic_area'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-basic-area.png](images/glimmer-dsl-libui-linux-basic-area.png)
+
+[LibUI](https://github.com/kojix2/LibUI) Original Version:
+
+```ruby
+require 'libui'
+
+UI = LibUI
+
+UI.init
+
+handler = UI::FFI::AreaHandler.malloc
+area    = UI.new_area(handler)
+brush   = UI::FFI::DrawBrush.malloc
+
+handler_draw_event = Fiddle::Closure::BlockCaller.new(0, [1, 1, 1]) do |_, _, area_draw_params|
+  path = UI.draw_new_path(0)
+  UI.draw_path_add_rectangle(path, 0, 0, 400, 400)
+  UI.draw_path_end(path)
+  brush.Type = 0
+  brush.R = 0.4
+  brush.G = 0.4
+  brush.B = 0.8
+  brush.A = 1.0
+  area_draw_params = UI::FFI::AreaDrawParams.new(area_draw_params)
+  UI.draw_fill(area_draw_params.Context, path, brush.to_ptr)
+  UI.draw_free_path(path)
+end
+
+handler.Draw         = handler_draw_event
+handler.MouseEvent   = Fiddle::Closure::BlockCaller.new(0, [0]) {}
+handler.MouseCrossed = Fiddle::Closure::BlockCaller.new(0, [0]) {}
+handler.DragBroken   = Fiddle::Closure::BlockCaller.new(0, [0]) {}
+handler.KeyEvent     = Fiddle::Closure::BlockCaller.new(0, [0]) {}
+
+box = UI.new_vertical_box
+UI.box_set_padded(box, 1)
+UI.box_append(box, area, 1)
+
+main_window = UI.new_window('Basic Area', 400, 400, 1)
+UI.window_set_margined(main_window, 1)
+UI.window_set_child(main_window, box)
+
+UI.window_on_closing(main_window) do
+  UI.control_destroy(main_window)
+  UI.quit
+  0
+end
+UI.control_show(main_window)
+
+UI.main
+UI.quit
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Area', 400, 400) {
+  margined true
+  
+  vertical_box {
+    area {
+      path { # a stable path is added declaratively
+        rectangle(0, 0, 400, 400)
+        
+        fill r: 102, g: 102, b: 204, a: 1.0
+      }
+    }
+  }
+}.show
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Area', 400, 400) {
+  margined true
+  
+  vertical_box {
+    area {
+      on_draw do |area_draw_params|
+        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+          rectangle(0, 0, 400, 400)
+          
+          fill r: 102, g: 102, b: 204, a: 1.0
+        }
+      end
+    }
+  }
+}.show
+```
+
+### Dynamic Area
+
+[examples/dynamic_area.rb](examples/dynamic_area.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/dynamic_area.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/dynamic_area'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-dynamic-area.png](images/glimmer-dsl-libui-mac-dynamic-area.png)
+![glimmer-dsl-libui-mac-dynamic-area-updated.png](images/glimmer-dsl-libui-mac-dynamic-area-updated.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-dynamic-area.png](images/glimmer-dsl-libui-linux-dynamic-area.png)
+![glimmer-dsl-libui-linux-dynamic-area-updated.png](images/glimmer-dsl-libui-linux-dynamic-area-updated.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Dynamic Area', 240, 500) {
+  margined true
+  
+  vertical_box {
+    label('Rectangle Properties') {
+      stretchy false
+    }
+    
+    form {
+      stretchy false
+      
+      @x_spinbox = spinbox(0, 1000) {
+        label 'x'
+        value 25
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @y_spinbox = spinbox(0, 1000) {
+        label 'y'
+        value 25
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @width_spinbox = spinbox(0, 1000) {
+        label 'width'
+        value 150
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @height_spinbox = spinbox(0, 1000) {
+        label 'height'
+        value 150
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @red_spinbox = spinbox(0, 255) {
+        label 'red'
+        value 102
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @green_spinbox = spinbox(0, 255) {
+        label 'green'
+        value 102
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @blue_spinbox = spinbox(0, 255) {
+        label 'blue'
+        value 204
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+      
+      @alpha_spinbox = spinbox(0, 100) {
+        label 'alpha'
+        value 100
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
+      }
+    }
+    
+    @area = area {
+      on_draw do |area_draw_params|
+        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+          rectangle(@x_spinbox.value, @y_spinbox.value, @width_spinbox.value, @height_spinbox.value)
+          
+          fill r: @red_spinbox.value, g: @green_spinbox.value, b: @blue_spinbox.value, a: @alpha_spinbox.value / 100.0
+        }
+      end
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Dynamic Area', 240, 600) {
+  margined true
+  
+  vertical_box {
+    label('Rectangle Properties') {
+      stretchy false
+    }
+    
+    form {
+      stretchy false
+      
+      @x_spinbox = spinbox(0, 1000) {
+        label 'x'
+        value 25
+        
+        on_changed do
+          @rectangle.x = @x_spinbox.value # updating properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @y_spinbox = spinbox(0, 1000) {
+        label 'y'
+        value 25
+        
+        on_changed do
+          @rectangle.y = @y_spinbox.value # updating properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @width_spinbox = spinbox(0, 1000) {
+        label 'width'
+        value 150
+        
+        on_changed do
+          @rectangle.width = @width_spinbox.value # updating properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @height_spinbox = spinbox(0, 1000) {
+        label 'height'
+        value 150
+        
+        on_changed do
+          @rectangle.height = @height_spinbox.value # updating properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @red_spinbox = spinbox(0, 255) {
+        label 'red'
+        value 102
+        
+        on_changed do
+          @path.fill[:r] = @red_spinbox.value # updating hash properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @green_spinbox = spinbox(0, 255) {
+        label 'green'
+        value 102
+        
+        on_changed do
+          @path.fill[:g] = @green_spinbox.value # updating hash properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @blue_spinbox = spinbox(0, 255) {
+        label 'blue'
+        value 204
+        
+        on_changed do
+          @path.fill[:b] = @blue_spinbox.value # updating hash properties automatically triggers area.queue_redraw_all
+        end
+      }
+      
+      @alpha_spinbox = spinbox(0, 100) {
+        label 'alpha'
+        value 100
+        
+        on_changed do
+          @path.fill[:a] = @alpha_spinbox.value / 100.0 # updating hash properties automatically triggers area.queue_redraw_all
+        end
+      }
+    }
+    
+    area {
+      @path = path { # stable path
+        @rectangle = rectangle(@x_spinbox.value, @y_spinbox.value, @width_spinbox.value, @height_spinbox.value)
+        
+        fill r: @red_spinbox.value, g: @green_spinbox.value, b: @blue_spinbox.value, a: @alpha_spinbox.value / 100.0
+      }
+    }
+  }
+}.show
+```
+
+### Area Gallery
+
+[examples/area_gallery.rb](examples/area_gallery.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/area_gallery.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/area_gallery'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-area-gallery.png](images/glimmer-dsl-libui-mac-area-gallery.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-area-gallery.png](images/glimmer-dsl-libui-linux-area-gallery.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Area Gallery', 400, 400) {
+  vertical_box {
+    area {
+      path { # declarative stable path
+        square(0, 0, 100)
+        square(100, 100, 400)
+        
+        fill r: 102, g: 102, b: 204
+      }
+      path { # declarative stable path
+        rectangle(0, 100, 100, 400)
+        rectangle(100, 0, 400, 100)
+        
+        fill r: 204, g: 102, b: 204
+      }
+      path { # declarative stable path
+        figure(100, 100) {
+          line(100, 400)
+          line(400, 100)
+          line(400, 400)
+
+          closed true
+        }
+
+        fill r: 202, g: 102, b: 104, a: 0.5
+        stroke thickness: 1, r: 0, g: 0, b: 0
+      }
+      path { # declarative stable path
+        figure(0, 0) {
+          bezier(200, 100, 100, 200, 400, 100)
+          bezier(300, 100, 100, 300, 100, 400)
+          bezier(100, 300, 300, 100, 400, 400)
+
+          closed true
+        }
+
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke thickness: 2, r: 0, g: 0, b: 0
+      }
+      path { # declarative stable path
+        arc(200, 200, 90, 0, 360, false)
+
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke thickness: 2, r: 0, g: 0, b: 0
+      }
+    }
+  }
+}.show
+```
+
 ## Contributing to glimmer-dsl-libui
 
 -   Check out the latest master to make sure the feature hasn't been