glimmer-dsl-libui 0.2.11 → 0.2.15

data/README.md

@@ -1,7 +1,6 @@
-# [<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.2.11
+# [<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.2.15
 ## 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)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 [Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/kojix2/LibUI) is a prerequisite-free Ruby desktop development GUI library. No need to pre-install any prerequisites. Just install the gem and have platform-independent native GUI that just works!
@@ -10,13 +9,11 @@
 
 The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) as opposed to [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) or [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk) is the fact that [SWT](https://www.eclipse.org/swt/) and [Tk](https://www.tcl.tk/) are more mature than mid-alpha [libui](https://github.com/andlabs/libui) as GUI toolkits. Still, if there is only a need to build a small simple application, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) could be a good convenient choice due to having zero prerequisites beyond the dependencies included in the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui). Also, just like [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk), its apps start instantly and have a small memory footprint. [LibUI](https://github.com/kojix2/LibUI) is a promising new GUI toolkit that might prove quite worthy in the future.
 
-**(Note: although LibUI works on Windows, this project has not been tested on Windows yet. It has only been verified on Mac x64 and Linux x64)**
-
 [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) aims to provide a DSL similar to the [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) to enable more productive desktop development in Ruby with:
 - Declarative DSL syntax that visually maps to the GUI control hierarchy
 - Convention over configuration via smart defaults and automation of low-level details
 - Requiring the least amount of syntax possible to build GUI
-- Custom Control support
+- Custom Keyword support
 - [Far Future Plan] Bidirectional Data-Binding to declaratively wire and automatically synchronize GUI with Business Models
 - [Far Future Plan] Scaffolding for new custom controls, apps, and gems
 - [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
@@ -134,11 +131,9 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text(160, 40, 100) { # x, y, width
-      string {
+      string('Area Gallery') {
         font family: 'Times', size: 14
         color :black
-        
-        'Area Gallery'
       }
     }
     
@@ -214,7 +209,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
   - [API](#api)
-    - [Supported Controls](#supported-controls)
+    - [Supported Keywords](#supported-keywords)
     - [Common Control Properties](#common-control-properties)
     - [Common Control Operations](#common-control-operations)
     - [LibUI Operations](#libui-operations)
@@ -262,13 +257,18 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Draw Text](#basic-draw-text)
     - [Custom Draw Text](#custom-draw-text)
     - [Method-Based Custom Keyword](#method-based-custom-keyword)
-  - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
+  - [Applications](#applications)
+    - [Manga2PDF](#manga2pdf)
+    - [Befunge98 GUI](#befunge98-gui)
+    - [i3off Gtk Ruby](#i3off-gtk-ruby)
+  - [Process](#process)
+  - [Resources](#resources)
   - [Help](#help)
     - [Issues](#issues)
     - [Chat](#chat)
-  - [Process](#process)
   - [Planned Features and Feature Suggestions](#planned-features-and-feature-suggestions)
   - [Change Log](#change-log)
+  - [Contributing](#contributing)
   - [Contributors](#contributors)
   - [License](#license)
 
@@ -282,10 +282,10 @@ The Glimmer GUI DSL provides object-oriented declarative hierarchical syntax for
 - Requires the minimum amount of syntax needed to describe an app's GUI
 
 The Glimmer GUI DSL follows these simple concepts in mapping from [LibUI](https://github.com/kojix2/LibUI) syntax:
-- **Control**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
-- **Content/Properties/Listeners Block**: Any keyword may be optionally followed by a Ruby curly-brace multi-line-block containing nested controls (content) and/or properties (attributes) (e.g. `window('hello world', 300, 200, true) {button('greet')}`). It optionally receives one arg representing the control (e.g. `button('greet') {|b| on_clicked { puts b.text}}`)
-- **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `control_set_property` methods.
-- **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (e.g. `on_clicked {puts 'clicked'}` inside `button`). Behind the scenes, listeners correspond to `control_on_event` methods.
+- **Keyword(args)**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
+- **Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls (e.g. `window {title 'hello world'; on_closing {puts 'Bye'}; button('greet')}`). Content block optionally receives one arg representing the control (e.g. `button('greet') {|b| on_clicked { puts b.text}}`)
+- **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
+- **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (e.g. `on_clicked {puts 'clicked'}` inside `button`). Optionally, the listener block can receive an arg representing the control (e.g. `on_clicked {|btn| puts btn.text}`). Behind the scenes, listeners correspond to `LibUI.control_on_event` methods.
 
 Example of an app written in [LibUI](https://github.com/kojix2/LibUI)'s procedural imperative syntax:
 
@@ -349,7 +349,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.11'
+gem 'glimmer-dsl-libui', '~> 0.2.15'
 ```
 
 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.
@@ -409,7 +409,7 @@ w.set_title 'aloha'
 puts w.title # => aloha
 ```
 
-Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed.
+Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped [LibUI](https://github.com/kojix2/LibUI) Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -418,9 +418,11 @@ w = window('hello world') # => #<Glimmer::LibUI::WindowProxy:0x00007fde4ea39fb0
 w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0 free=0x0000000000000000>
 ```
 
-### Supported Controls
+### Supported Keywords
 
-Control(Args) | Properties | Listeners
+These are all the supported keywords. Note that some keywords do not represent controls, but produce objects that are used as the property values of controls (e.g. `image` builds objects to use in `cell_rows` for a `table` with an image column)
+
+Keyword(Args) | Properties | Listeners
 ------------- | ---------- | ---------
 `about_menu_item` | None | `on_clicked`
 `area` | None | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`, `on_key_event(area_key_event)`, `on_key_down(area_key_event)`, `on_key_up(area_key_event)`
@@ -456,6 +458,8 @@ Control(Args) | Properties | Listeners
 `matrix(m11 = nil as Numeric, m12 = nil as Numeric, m21 = nil as Numeric, m22 = nil as Numeric, m31 = nil as Numeric, m32 = nil as Numeric)` | `m11` (`Numeric`), `m12` (`Numeric`), `m21` (`Numeric`), `m22` (`Numeric`), `m31` (`Numeric`), `m32` (`Numeric`) | None
 `menu(text as String)` | None | None
 `menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
+`message_box` (alias for `msg_box`; see for arguments) | None | None
+`message_box_error` (alias for `msg_box_error`; see for arguments) | None | None
 `multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `msg_box(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `msg_box_error(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
@@ -472,7 +476,7 @@ Control(Args) | Properties | Listeners
 `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
-`string` | `font`, `color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `background` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `underline`, `underline_color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `open_type_features` | None
+`string(string = '')` | `font`, `color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `background` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `underline`, `underline_color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `open_type_features`, `string` (`String`) | 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 | `on_changed {|row, type, row_data| ...}`, `on_edited {|row, row_data| ...}`
@@ -517,8 +521,8 @@ All operations that could normally be called on `LibUI` can also be called on `G
 
 ### Extra Dialogs
 
-- `open_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
-- `save_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
+- `open_file(window as Glimmer::LibUI::WindowProxy = ControlProxy::main_window_proxy)`: returns selected file (`String`) or `nil` if cancelled
+- `save_file(window as Glimmer::LibUI::WindowProxy = ControlProxy::main_window_proxy)`: returns selected file (`String`) or `nil` if cancelled
 
 ### Extra Operations
 
@@ -531,13 +535,13 @@ All operations that could normally be called on `LibUI` can also be called on `G
 
 ### Table API
 
-The `table` control must first declare its columns via one of these column keywords (mentioned in [Supported Controls](#supported-controls)):
+The `table` control must first declare its columns via one of these column keywords (mentioned in [Supported Keywords](#supported-keywords)):
   - `background_color_column`: expects color cell values
   - `button_column`: expects `String` cell values
   - `checkbox_column`: expects Boolean cell values
   - `checkbox_text_column`: expects dual-element `Array` of Boolean and `String` cell values
   - `checkbox_text_color_column`: expects triple-element `Array` of Boolean, `String`, and color cell values
-  - `image_column`: expects `image` cell values (produced by `image` and `image_part` keywords as per [Supported Controls](#supported-controls))
+  - `image_column`: expects `image` cell values (produced by `image` and `image_part` keywords as per [Supported Keywords](#supported-keywords))
   - `image_text_column`: expects dual-element `Array` of `image` and `String` cell values
   - `image_text_color_column`: expects triple-element `Array` of `image`, `String`, and color cell values
   - `text_column`: expects `String` cell values
@@ -599,6 +603,7 @@ window('Contacts', 600, 600) { |w|
           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
+          @unfiltered_data = data.dup
           @name_entry.text = ''
           @email_entry.text = ''
           @phone_entry.text = ''
@@ -608,6 +613,25 @@ window('Contacts', 600, 600) { |w|
       end
     }
     
+    search_entry { |se|
+      stretchy false
+      
+      on_changed do
+        filter_value = se.text
+        @unfiltered_data ||= data.dup
+        # Unfilter first to remove any previous filters
+        data.replace(@unfiltered_data) # affects table indirectly through implicit data-binding
+        # Now, apply filter if entered
+        unless filter_value.empty?
+          data.filter! do |row_data| # affects table indirectly through implicit data-binding
+            row_data.any? do |cell|
+              cell.to_s.downcase.include?(filter_value.downcase)
+            end
+          end
+        end
+      end
+    }
+    
     table {
       text_column('Name')
       text_column('Email')
@@ -616,6 +640,10 @@ window('Contacts', 600, 600) { |w|
       text_column('State')
 
       cell_rows data # implicit data-binding
+      
+      on_changed do |row, type, row_data|
+        puts "Row #{row} #{type}: #{row_data}"
+      end
     }
   }
 }.show
@@ -628,8 +656,8 @@ Learn more by checking out [examples](#examples).
 ### Area API
 
 The `area` control is a canvas-like control for drawing paths that 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. Path 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 that receives a `area_draw_params` argument and nest `path` 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.
+- Declaratively via stable paths: useful for stable paths that will not change often later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be relatively few stable paths (mostly for decorative reasons).
+- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change very often. Open an `on_draw` listener block that receives a `area_draw_params` argument and nest `path` 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)):
 
@@ -816,19 +844,23 @@ Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wi
 
 Check [Histogram](#histogram) example for use of hex colors.
 
-To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` element in html, which contains a string of text).
+To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {[attributes]; string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` or `<p>` element in html, which contains a string of text). Alternatively, you can nest attributed `string(string_value) {[attributes]}` if `string_value` is a short single-line string. An attributed `string` value can be changed dynamically via its `string` property.
 
-`text` control can have the following properties:
+`text` has the following properties:
 - `default_font`:
 - `align`: `:left` (default), `:center`, or `:right` (`align` currently seems not to work on the Mac)
+- `x`: x coordinate in relation to parent `area` top-left corner
+- `y`: y coordinate in relation to parent `area` top-left corner
+- `width` (default: area width - x*2): width of text to display
 
-`string` can have the following properties:
+`string` has the following properties:
 - `font`: font descriptor hash consisting of `:family`, `:size`, `:weight` (`[:minimum, :thin, :ultra_light, :light, :book, :normal, :medium, :semi_bold, :bold, :ultra_bold, :heavy, :ultra_heavy, :maximum]`), `:italic` (`[:normal, :oblique, :italic]`), and `:stretch` (`[:ultra_condensed, :extra_condensed, :condensed, :semi_condensed, :normal, :semi_expanded, :expanded, :extra_expanded, :ultra_expanded]`) key values
 - `color`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `background`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `underline`: one of `:none`, `:single`, `:double`, `:suggestion`, `:color_custom`, `:color_spelling`, `:color_grammar`, `:color_auxiliary`
 - `underline_color`: one of `:spelling`, `:grammar`, `:auxiliary`, rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `open_type_features`: Open Type Features (https://www.microsoft.com/typography/otspec/featuretags.htm) consist of `open_type_tag`s nested in content block, which accept (`a`, `b`, `c`, `d`, `Integer`) arguments.
+- `string`: string value (`String`)
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -849,12 +881,13 @@ window('area text drawing') {
           open_type_tag 'l', 'i', 'g', 'a', 1
         }
         
-        "This is a test\n\n"
+        "This is a demonstration\n" \
+        "of a very long\n" \
+        "attributed string\n" \
+        "spanning multiple lines\n\n"
       }
       
-      string {
-        'This is another test'
-      }
+      string('This is a short unattributed string')
     }
   }
 }.show
@@ -888,9 +921,11 @@ window('area text drawing') {
 - 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`
+- Automatically provide shifted `:key` characters in `area_key_event` provided in `area` key listeners `on_key_event`, `on_key_down`, and `on_key_up`
 - `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
+- Observe `text` and `string` properties for changes and automatically redraw containing area accordingly
 - All controls are protected from garbage collection until no longer needed (explicitly destroyed), so there is no need to worry about surprises.
 - All resources are freed automatically once no longer needed or left to garbage collection.
 - When nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
@@ -1008,8 +1043,13 @@ window('Method-Based Custom Keyword') {
 ### 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 only works on Windows and Linux (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- `table` `checkbox_column` and `checkbox_text_column` checkbox editing only works on Linux and Windows (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
 - `text` `align` property seems not to work on the Mac ([libui](https://github.com/andlabs/libui) has an [issue](https://github.com/andlabs/libui/pull/407) about it)
+- `text` `string` `background` does not work on Windows due to an [issue in libui](https://github.com/andlabs/libui/issues/347).
+- `arc` shape does not work on Windows unless a figure is started due to implementation of [libui](https://github.com/andlabs/libui).
+- `table` controls on Windows intentionally get an extra empty row at the end because if any row were to be deleted for the first time, double-deletion happens due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
+- `table` `progress_bar` column on Windows cannot be updated with a positive value if it started initially with `-1` (it ignores update to avoid crashing due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
+- It seems that [libui](https://github.com/andlabs/libui) does not support nesting multiple `area` controls under a `grid` as only the first one shows up in that scenario. To workaround that limitation, use a `vertical_box` with nested `horizontal_box`s instead to include multiple `area`s in a GUI.
 
 ### Original API
 
@@ -1024,7 +1064,7 @@ I am documenting options for packaging, which I have not tried myself, but figur
 
 For Windows, the [LibUI](https://github.com/kojix2/LibUI) project recommends [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application), which builds Windows executables from Ruby source.
 
-For Mac, consider [Platybus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
+For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
 
 For Linux, simply package your app as a [Ruby Gem](https://guides.rubygems.org/what-is-a-gem/) and [build rpm package from Ruby Gem](https://www.redpill-linpro.com/sysadvent/2015/12/07/building-rpms-from-gems.html) or [build deb package from Ruby Gem](https://openpreservation.org/blogs/building-debian-package-ruby-program/).
 
@@ -1111,15 +1151,20 @@ class MetaExample
   end
   
   def run_example(example)
-    command = "ruby -r #{glimmer_dsl_libui_file} #{example} 2>&1"
-    result = ''
-    IO.popen(command) do |f|
-      f.each_line do |line|
-        result << line
-        puts line
+    Thread.new do
+      command = "ruby -r #{glimmer_dsl_libui_file} #{example} 2>&1"
+      result = ''
+      IO.popen(command) do |f|
+        sleep(0.0001) # yield to main thread
+        f.each_line do |line|
+          result << line
+          puts line
+          $stdout.flush # for Windows
+          sleep(0.0001) # yield to main thread
+        end
       end
+      Glimmer::LibUI.queue_main { msg_box('Error Running Example', result) } if result.downcase.include?('error')
     end
-    msg_box('Error Running Example', result) if result.downcase.include?('error')
   end
   
   def launch
@@ -3375,8 +3420,6 @@ Linux
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3906,11 +3949,9 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text(160, 40, 100) { # x, y, width
-      string {
+      string('Area Gallery') {
         font family: 'Times', size: 14
         color :black
-        
-        'Area Gallery'
       }
     }
     
@@ -4214,11 +4255,9 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
       text(160, 40, 100) { # x, y, width
-        string {
+        string('Area Gallery') {
           font family: 'Times', size: 14
           color :black
-          
-          'Area Gallery'
         }
       }
     end
@@ -5139,8 +5178,8 @@ class ColorTheCircles
   
   WINDOW_WIDTH = 800
   WINDOW_HEIGHT = 600
-  CIRCLE_MIN_RADIUS = 15
-  CIRCLE_MAX_RADIUS = 50
+  SHAPE_MIN_SIZE = 15
+  SHAPE_MAX_SIZE = 75
   MARGIN_WIDTH = 55
   MARGIN_HEIGHT = 155
   TIME_MAX_EASY = 4
@@ -5154,6 +5193,7 @@ class ColorTheCircles
     @circles_data = []
     @score = 0
     @time_max = TIME_MAX_HARD
+    @game_over = false
     register_observers
     setup_circle_factory
   end
@@ -5162,9 +5202,11 @@ class ColorTheCircles
     observer = Glimmer::DataBinding::Observer.proc do |new_score|
       @score_label.text = new_score.to_s
       if new_score == -20
+        @game_over = true
         msg_box('You Lost!', 'Sorry! Your score reached -20')
         restart_game
       elsif new_score == 0
+        @game_over = true
         msg_box('You Won!', 'Congratulations! Your score reached 0')
         restart_game
       end
@@ -5174,11 +5216,13 @@ class ColorTheCircles
   
   def setup_circle_factory
     consumer = Proc.new do
-      if @circles_data.empty?
-        # start with 3 circles to make more challenging
-        add_circle until @circles_data.size > 3
-      else
-        add_circle
+      unless @game_over
+        if @circles_data.empty?
+          # start with 3 circles to make more challenging
+          add_circle until @circles_data.size > 3
+        else
+          add_circle
+        end
       end
       delay = rand * @time_max
       Glimmer::LibUI.timer(delay, repeat: false, &consumer)
@@ -5187,12 +5231,12 @@ class ColorTheCircles
   end
   
   def add_circle
-    circle_x_center = rand * (WINDOW_WIDTH - MARGIN_WIDTH - CIRCLE_MAX_RADIUS) + CIRCLE_MAX_RADIUS
-    circle_y_center = rand * (WINDOW_HEIGHT - MARGIN_HEIGHT - CIRCLE_MAX_RADIUS) + CIRCLE_MAX_RADIUS
-    circle_radius = rand * (CIRCLE_MAX_RADIUS - CIRCLE_MIN_RADIUS) + CIRCLE_MIN_RADIUS
+    circle_x = rand * (WINDOW_WIDTH - MARGIN_WIDTH - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
+    circle_y = rand * (WINDOW_HEIGHT - MARGIN_HEIGHT - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
+    circle_size = rand * (SHAPE_MAX_SIZE - SHAPE_MIN_SIZE) + SHAPE_MIN_SIZE
     stroke_color = Glimmer::LibUI.x11_colors.sample
     @circles_data << {
-      args: [circle_x_center, circle_y_center, circle_radius],
+      args: [circle_x, circle_y, circle_size],
       fill: nil,
       stroke: stroke_color
     }
@@ -5203,8 +5247,28 @@ class ColorTheCircles
   def restart_game
     @score = 0 # update variable directly to avoid notifying observers
     @circles_data.clear
+    @game_over = false
   end
   
+  def color_circle(x, y)
+    clicked_circle_data = @circles_data.find do |circle_data|
+      circle_data[:fill].nil? && circle_data[:circle]&.include?(x, y)
+    end
+    if clicked_circle_data
+      clicked_circle_data[:fill] = clicked_circle_data[:stroke]
+      push_colored_circle_behind_uncolored_circles(clicked_circle_data)
+      @area.queue_redraw_all
+      self.score += 1 # notifies score observers automatically of change
+    end
+  end
+  
+  def push_colored_circle_behind_uncolored_circles(colored_circle_data)
+    removed_colored_circle_data = @circles_data.delete(colored_circle_data)
+    last_colored_circle_data = @circles_data.select {|cd| cd[:fill]}.last
+    last_colored_circle_data_index = @circles_data.index(last_colored_circle_data) || -1
+    @circles_data.insert(last_colored_circle_data_index + 1, removed_colored_circle_data)
+  end
+
   def launch
     menu('Actions') {
       menu_item('Restart') {
@@ -5292,45 +5356,35 @@ class ColorTheCircles
           }
         }
         
-        vertical_box {
+        @area = area {
           left 0
           top 4
           hexpand true
           vexpand true
           halign :fill
           valign :fill
-          
-          @area = area {
-            on_draw do |area_draw_params|
+
+          on_draw do |area_draw_params|
+            path {
+              rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
+
+              fill :white
+            }
+
+            @circles_data.each do |circle_data|
               path {
-                rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
-                
-                fill :white
+                circle_data[:circle] = circle(*circle_data[:args])
+
+                fill circle_data[:fill]
+                stroke circle_data[:stroke]
               }
-              
-              @circles_data.each do |circle_data|
-                path {
-                  circle_data[:circle] = circle(*circle_data[:args])
-                  
-                  fill circle_data[:fill]
-                  stroke circle_data[:stroke]
-                }
-              end
-            end
-            
-            on_mouse_down do |area_mouse_event|
-              clicked_circle_data = @circles_data.find do |circle_data|
-                circle_data[:fill].nil? && circle_data[:circle].include?(area_mouse_event[:x], area_mouse_event[:y])
-              end
-              if clicked_circle_data
-                clicked_circle_data[:fill] = clicked_circle_data[:stroke]
-                @area.queue_redraw_all
-                self.score += 1 # notifies score observers automatically of change
-              end
             end
-          }
+          end
+
+          on_mouse_down do |area_mouse_event|
+            color_circle(area_mouse_event[:x], area_mouse_event[:y])
+          end
         }
-        
       }
     }.show
   end
@@ -5962,38 +6016,50 @@ window('Method-Based Custom Keyword') {
 }.show
 ```
 
-## Contributing to glimmer-dsl-libui
+## Applications
 
--   Check out the latest master to make sure the feature hasn't been
-    implemented or the bug hasn't been fixed yet.
--   Check out the issue tracker to make sure someone already hasn't
-    requested it and/or contributed it.
--   Fork the project.
--   Start a feature/bugfix branch.
--   Commit and push until you are happy with your contribution.
--   Make sure to add tests for it. This is important so I don't break it
-    in a future version unintentionally.
--   Please try not to mess with the Rakefile, version, or history. If
-    you want to have your own version, or is otherwise necessary, that
-    is fine, but please isolate to its own commit so I can cherry-pick
-    around it.
+Here are some applications built with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)
 
-## Help
+### Manga2PDF
 
-### Issues
+Download and merge manga images into a single pdf file.
 
-You may submit [issues](https://github.com/AndyObtiva/glimmer/issues) on [GitHub](https://github.com/AndyObtiva/glimmer/issues).
+https://github.com/PinGunter/manga2pdf
 
-[Click here to submit an issue.](https://github.com/AndyObtiva/glimmer/issues)
+![manga2pdf screenshot](https://raw.githubusercontent.com/PinGunter/manga2pdf/master/screenshots/manga2pdf-gui.png)
 
-### Chat
+### Befunge98 GUI
 
-If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+Ruby implementation of the Befunge-98 programmming language.
+
+https://github.com/AndyObtiva/befunge98/tree/gui
+
+![befunge98 gui screenshot](https://raw.githubusercontent.com/AndyObtiva/befunge98/master/gui/glimmer-dsl-libui/befunge98_gui_glimmer_dsl_libui/screenshots/befunge98_gui_glimmer_dsl_libui_example.png)
+
+### i3off Gtk Ruby
+
+https://github.com/iraamaro/i3off-gtk-ruby
 
 ## Process
 
 [Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
 
+## Resources
+
+- [libui C Library](https://github.com/andlabs/libui)
+- [LibUI Ruby Bindings](https://github.com/kojix2/LibUI)
+- [Code Master Blog](https://andymaleh.blogspot.com/search/label/LibUI)
+
+## Help
+
+### Issues
+
+If you encounter [issues](https://github.com/AndyObtiva/glimmer-dsl-libui/issues) that are not reported, discover missing features that are not mentioned in [TODO.md](TODO.md), or think up better ways to use [libui](https://github.com/andlabs/libui) than what is possible with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), you may submit an [issue](https://github.com/AndyObtiva/glimmer-dsl-libui/issues/new) or [pull request](https://github.com/AndyObtiva/glimmer-dsl-libui/compare) on [GitHub](https://github.com).
+
+### Chat
+
+If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
 ## Planned Features and Feature Suggestions
 
 These features have been planned or suggested. You might see them in a future version of [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui). You are welcome to contribute more feature suggestions.
@@ -6004,6 +6070,22 @@ These features have been planned or suggested. You might see them in a future ve
 
 [CHANGELOG.md](CHANGELOG.md)
 
+## Contributing
+
+-   Check out the latest master to make sure the feature hasn't been
+    implemented or the bug hasn't been fixed yet.
+-   Check out the issue tracker to make sure someone already hasn't
+    requested it and/or contributed it.
+-   Fork the project.
+-   Start a feature/bugfix branch.
+-   Commit and push until you are happy with your contribution.
+-   Make sure to add tests for it. This is important so I don't break it
+    in a future version unintentionally.
+-   Please try not to mess with the Rakefile, version, or history. If
+    you want to have your own version, or is otherwise necessary, that
+    is fine, but please isolate to its own commit so I can cherry-pick
+    around it.
+
 ## Contributors
 
 * [Andy Maleh](https://github.com/AndyObtiva) (Founder)

data/VERSION

@@ -1 +1 @@
-0.2.11
+0.2.15

data/bin/girb_runner.rb

@@ -27,7 +27,7 @@ require_relative '../lib/glimmer-dsl-libui'
 
 include Glimmer
 
-GIRB_RUNNER_EXIT_FILE = "#{Etc.getpwuid.dir}/.girb_runner_exit"
+GIRB_RUNNER_EXIT_FILE = "#{Dir.home}/.girb_runner_exit"
 FileUtils.rm_rf GIRB_RUNNER_EXIT_FILE
 
 @exit_method = method(:exit)

data/examples/area_gallery.rb

@@ -55,11 +55,9 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text(160, 40, 100) { # x, y, width
-      string {
+      string('Area Gallery') {
         font family: 'Times', size: 14
         color :black
-        
-        'Area Gallery'
       }
     }