glimmer-dsl-libui 0.2.0 → 0.2.4

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.1.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.4
 ## 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)
@@ -118,11 +118,17 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(200, 200, 90, 0, 360, false)
+      circle(200, 200, 90)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -191,7 +197,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.1.10](#-glimmer-dsl-for-libui-0111)
+- [Glimmer DSL for LibUI 0.2.4](#-glimmer-dsl-for-libui-024)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -199,6 +205,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Supported Controls](#supported-controls)
     - [Common Control Properties](#common-control-properties)
     - [Common Control Operations](#common-control-operations)
+    - [LibUI Operations](#libui-operations)
     - [Extra Dialogs](#extra-dialogs)
     - [Extra Operations](#extra-operations)
     - [Table API](#table-api)
@@ -235,6 +242,10 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Histogram](#histogram)
     - [Basic Transform](#basic-transform)
     - [Login](#login)
+    - [Timer](#timer)
+    - [Color The Circles](#color-the-circles)
+    - [Basic Draw Text](#basic-draw-text)
+    - [Custom Draw Text](#custom-draw-text)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -322,7 +333,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.1.10'
+gem 'glimmer-dsl-libui', '~> 0.2.4'
 ```
 
 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.
@@ -475,6 +486,13 @@ Control(Args) | Properties | Listeners
 - `hide`
 - `show`
 
+### LibUI Operations
+
+All operations that could normally be called on `LibUI` can also be called on `Glimmer::LibUI`, but some have enhancements as detailed below.
+
+- `Glimmer::LibUI::queue_main(&block)`: queues an operation to be run on the main event loop at the earliest opportunity possible
+- `Glimmer::LibUI::timer(time_in_seconds=0.1, repeat: true, &block)`: calls block after time_in_seconds has elapsed, repeating indefinitely unless repeat is `false` or an `Integer` for finite number of repeats. Block can return `false` or `true` to override next repetition.
+
 ### Extra Dialogs
 
 - `open_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
@@ -766,6 +784,8 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 
 `fill` and `stroke` accept [X11](https://en.wikipedia.org/wiki/X11_color_names) color `Symbol`s/`String`s like `:skyblue` and `'sandybrown'` or 6-number hex or 3-number hex-shorthand (as `Integer` or `String` with or without `0x` prefix)
 
+Available [X11](https://en.wikipedia.org/wiki/X11_color_names) colors can be obtained through `Glimmer::LibUI.x11_colors` method.
+
 Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wikipedia.org/wiki/X11_color_names) colors.
 
 Check [Histogram](#histogram) example for use of hex colors.
@@ -1258,9 +1278,7 @@ window('Notepad', 500, 300) {
 
 ### Midi Player
 
-This example has prerequisites:
-- Install [TiMidity](http://timidity.sourceforge.net) and ensure `timidity` command is in `PATH` (can be installed via [Homebrew](https://brew.sh) on Mac or [apt-get](https://help.ubuntu.com/community/AptGet/Howto) on Linux).
-- Add `*.mid` files to `~/Music` directory (you may copy the ones included in [sounds](sounds) directory)
+To run this example, install [TiMidity](http://timidity.sourceforge.net) and ensure `timidity` command is in `PATH` (can be installed via [Homebrew](https://brew.sh) on Mac or [apt-get](https://help.ubuntu.com/community/AptGet/Howto) on Linux).
 
 [examples/midi_player.rb](examples/midi_player.rb)
 
@@ -1399,7 +1417,7 @@ class TinyMidiPlayer
 
   def initialize
     @pid = nil
-    @music_directory = File.expand_path(ARGV[0] || '~/Music/')
+    @music_directory = File.expand_path('../sounds', __dir__)
     @midi_files      = Dir.glob(File.join(@music_directory, '**/*.mid'))
                           .sort_by { |path| File.basename(path) }
     at_exit { stop_midi }
@@ -1438,7 +1456,7 @@ class TinyMidiPlayer
   end
 
   def create_gui
-    menu('Help') { |m|
+    menu('Help') {
       menu_item('Version') {
         on_clicked do
           show_version
@@ -3523,11 +3541,17 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(200, 200, 90, 0, 360, false)
+      circle(200, 200, 90)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -3680,18 +3704,28 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc {
+      circle {
         x_center 200
         y_center 200
         radius 90
-        start_angle 0
-        sweep 360
-        is_negative false
       }
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc {
+        x_center 400
+        y_center 220
+        radius 180
+        start_angle 90
+        sweep 90
+        is_negative false
+      }
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -3791,13 +3825,19 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        arc(200, 200, 90, 0, 360, false)
-
+        circle(200, 200, 90)
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc(400, 220, 180, 90, 90, false)
+  
+        fill r: 204, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+      }
     end
-        
+    
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
     end
@@ -3950,20 +3990,30 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        arc {
+        circle {
           x_center 200
           y_center 200
           radius 90
-          start_angle 0
-          sweep 360
-          is_negative false
         }
-
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc {
+          x_center 400
+          y_center 220
+          radius 180
+          start_angle 90
+          sweep 90
+          is_negative false
+        }
+  
+        fill r: 204, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+      }
     end
-        
+    
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
     end
@@ -4486,6 +4536,908 @@ window('Login') {
 }.show
 ```
 
+### Timer
+
+To run this example, install [TiMidity](http://timidity.sourceforge.net) and ensure `timidity` command is in `PATH` (can be installed via [Homebrew](https://brew.sh) on Mac or [apt-get](https://help.ubuntu.com/community/AptGet/Howto) on Linux).
+
+[examples/timer.rb](examples/timer.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/timer.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/timer'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-timer.png](images/glimmer-dsl-libui-mac-timer.png)
+![glimmer-dsl-libui-mac-timer-in-progress.png](images/glimmer-dsl-libui-mac-timer-in-progress.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-timer.png](images/glimmer-dsl-libui-linux-timer.png)
+![glimmer-dsl-libui-linux-timer-in-progress.png](images/glimmer-dsl-libui-linux-timer-in-progress.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class Timer
+  include Glimmer
+  
+  SECOND_MAX = 59
+  MINUTE_MAX = 59
+  HOUR_MAX = 23
+  
+  def initialize
+    @pid = nil
+    @alarm_file = File.expand_path('../sounds/AlanWalker-Faded.mid', __dir__)
+    at_exit { stop_alarm }
+    setup_timer
+    create_gui
+  end
+
+  def stop_alarm
+    if @pid
+      if @th.alive?
+        Process.kill(:SIGKILL, @pid)
+        @pid = nil
+      else
+        @pid = nil
+      end
+    end
+  end
+
+  def play_alarm
+    stop_alarm
+    if @pid.nil?
+      begin
+        @pid = spawn "timidity -G 0.0-10.0 #{@alarm_file}"
+        @th = Process.detach @pid
+      rescue Errno::ENOENT
+        warn 'Timidty++ not found. Please install Timidity++.'
+        warn 'https://sourceforge.net/projects/timidity/'
+      end
+    end
+  end
+
+  def setup_timer
+    unless @setup_timer
+      Glimmer::LibUI.timer(1) do
+        if @started
+          seconds = @sec_spinbox.value
+          minutes = @min_spinbox.value
+          hours = @hour_spinbox.value
+          if seconds > 0
+            @sec_spinbox.value = seconds -= 1
+          end
+          if seconds == 0
+            if minutes > 0
+              @min_spinbox.value = minutes -= 1
+              @sec_spinbox.value = seconds = SECOND_MAX
+            end
+            if minutes == 0
+              if hours > 0
+                @hour_spinbox.value = hours -= 1
+                @min_spinbox.value = minutes = MINUTE_MAX
+                @sec_spinbox.value = seconds = SECOND_MAX
+              end
+              if hours == 0 && minutes == 0 && seconds == 0
+                @start_button.enabled = true
+                @stop_button.enabled = false
+                @started = false
+                unless @played
+                  play_alarm
+                  msg_box('Alarm', 'Countdown Is Finished!')
+                  @played = true
+                end
+              end
+            end
+          end
+        end
+      end
+      @setup_timer = true
+    end
+  end
+
+  def create_gui
+    window('Timer') {
+      margined true
+      
+      group('Countdown') {
+        vertical_box {
+          horizontal_box {
+            @hour_spinbox = spinbox(0, HOUR_MAX) {
+              stretchy false
+              value 0
+            }
+            label(':') {
+              stretchy false
+            }
+            @min_spinbox = spinbox(0, MINUTE_MAX) {
+              stretchy false
+              value 0
+            }
+            label(':') {
+              stretchy false
+            }
+            @sec_spinbox = spinbox(0, SECOND_MAX) {
+              stretchy false
+              value 0
+            }
+          }
+          horizontal_box {
+            @start_button = button('Start') {
+              on_clicked do
+                @start_button.enabled = false
+                @stop_button.enabled = true
+                @started = true
+                @played = false
+              end
+            }
+            
+            @stop_button = button('Stop') {
+              enabled false
+              
+              on_clicked do
+                @start_button.enabled = true
+                @stop_button.enabled = false
+                @started = false
+              end
+            }
+          }
+        }
+      }
+    }.show
+  end
+end
+
+Timer.new
+```
+
+### Color The Circles
+
+[examples/color_the_circles.rb](examples/color_the_circles.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/color_the_circles.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/color_the_circles'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-color-the-circles.png](images/glimmer-dsl-libui-mac-color-the-circles.png)
+![glimmer-dsl-libui-mac-color-the-circles-lost.png](images/glimmer-dsl-libui-mac-color-the-circles-lost.png)
+![glimmer-dsl-libui-mac-color-the-circles-won.png](images/glimmer-dsl-libui-mac-color-the-circles-won.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-color-the-circles.png](images/glimmer-dsl-libui-linux-color-the-circles.png)
+![glimmer-dsl-libui-linux-color-the-circles-lost.png](images/glimmer-dsl-libui-linux-color-the-circles-lost.png)
+![glimmer-dsl-libui-linux-color-the-circles-won.png](images/glimmer-dsl-libui-linux-color-the-circles-won.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class ColorTheCircles
+  include Glimmer
+  
+  WINDOW_WIDTH = 800
+  WINDOW_HEIGHT = 600
+  CIRCLE_MIN_RADIUS = 15
+  CIRCLE_MAX_RADIUS = 50
+  MARGIN_WIDTH = 55
+  MARGIN_HEIGHT = 155
+  TIME_MAX_EASY = 4
+  TIME_MAX_MEDIUM = 3
+  TIME_MAX_HARD = 2
+  TIME_MAX_INSANE = 1
+  
+  attr_accessor :score
+  
+  def initialize
+    @circles_data = []
+    @score = 0
+    @time_max = TIME_MAX_HARD
+    register_observers
+    setup_circle_factory
+  end
+  
+  def register_observers
+    observer = Glimmer::DataBinding::Observer.proc do |new_score|
+      @score_label.text = new_score.to_s
+      if new_score == -20
+        msg_box('You Lost!', 'Sorry! Your score reached -20')
+        restart_game
+      elsif new_score == 0
+        msg_box('You Won!', 'Congratulations! Your score reached 0')
+        restart_game
+      end
+    end
+    observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
+  end
+  
+  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
+      end
+      delay = rand * @time_max
+      Glimmer::LibUI.timer(delay, repeat: false, &consumer)
+    end
+    Glimmer::LibUI.queue_main(&consumer)
+  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
+    stroke_color = Glimmer::LibUI.x11_colors.sample
+    @circles_data << {
+      args: [circle_x_center, circle_y_center, circle_radius],
+      fill: nil,
+      stroke: stroke_color
+    }
+    @area.queue_redraw_all
+    self.score -= 1 # notifies score observers automatically of change
+  end
+  
+  def restart_game
+    @score = 0 # update variable directly to avoid notifying observers
+    @circles_data.clear
+  end
+  
+  def launch
+    menu('Actions') {
+      menu_item('Restart') {
+        on_clicked do
+          restart_game
+        end
+      }
+      
+      quit_menu_item
+    }
+    
+    menu('Difficulty') {
+      radio_menu_item('Easy') {
+        on_clicked do
+          @time_max = TIME_MAX_EASY
+        end
+      }
+      
+      radio_menu_item('Medium') {
+        on_clicked do
+          @time_max = TIME_MAX_MEDIUM
+        end
+      }
+      
+      radio_menu_item('Hard') {
+        checked true
+        
+        on_clicked do
+          @time_max = TIME_MAX_HARD
+        end
+      }
+      
+      radio_menu_item('Insane') {
+        on_clicked do
+          @time_max = TIME_MAX_INSANE
+        end
+      }
+    }
+    
+    menu('Help') {
+      menu_item('Instructions') {
+        on_clicked do
+          msg_box('Instructions', "Score goes down as circles are added.\nIf it reaches -20, you lose!\n\nClick circles to color and score!\nOnce score reaches 0, you win!\n\nBeware of concealed light-colored circles!\nThey are revealed once darker circles intersect them.\n\nThere are four levels of difficulty.\nChange via difficulty menu if the game gets too tough.")
+        end
+      }
+    }
+    
+    window('Color The Circles', WINDOW_WIDTH, WINDOW_HEIGHT) {
+      margined true
+      
+      grid {
+        button('Restart') {
+          left 0
+          top 0
+          halign :center
+          
+          on_clicked do
+            restart_game
+          end
+        }
+        
+        label('Score goes down as circles are added. If it reaches -20, you lose!') {
+          left 0
+          top 1
+          halign :center
+        }
+        
+        label('Click circles to color and score! Once score reaches 0, you win!') {
+          left 0
+          top 2
+          halign :center
+        }
+        
+        horizontal_box {
+          left 0
+          top 3
+          halign :center
+          
+          label('Score:') {
+            stretchy false
+          }
+          
+          @score_label = label(@score.to_s) {
+            stretchy false
+          }
+        }
+        
+        vertical_box {
+          left 0
+          top 4
+          hexpand true
+          vexpand true
+          halign :fill
+          valign :fill
+          
+          @area = area {
+            on_draw do |area_draw_params|
+              path {
+                rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
+                
+                fill :white
+              }
+              
+              @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
+          }
+        }
+        
+      }
+    }.show
+  end
+end
+
+ColorTheCircles.new.launch
+```
+
+### Basic Draw Text
+
+[examples/basic_draw_text.rb](examples/basic_draw_text.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_draw_text.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_draw_text'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-draw-text.png](images/glimmer-dsl-libui-mac-basic-draw-text.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-basic-draw-text.png](images/glimmer-dsl-libui-linux-basic-draw-text.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)
+
+# Michael Ende (1929-1995)
+# The Neverending Story is a fantasy novel by German writer Michael Ende,
+# The English version, translated by Ralph Manheim, was published in 1983.
+
+TITLE = 'Michael Ende (1929-1995) The Neverending Story'
+
+str1 = \
+  '  At last Ygramul sensed that something was coming toward ' \
+  'her. With the speed of lightning, she turned about, confronting ' \
+  'Atreyu with an enormous steel-blue face. Her single eye had a ' \
+  'vertical pupil, which stared at Atreyu with inconceivable malignancy. '
+
+str2 = \
+  '  A cry of fear escaped Bastian. '
+
+str3 = \
+  '  A cry of terror passed through the ravine and echoed from ' \
+  'side to side. Ygramul turned her eye to left and right, to see if ' \
+  'someone else had arrived, for that sound could not have been ' \
+  'made by the boy who stood there as though paralyzed with ' \
+  'horror. '
+
+str4 = \
+  '  Could she have heard my cry? Bastion wondered in alarm. ' \
+  "But that's not possible. "
+
+str5 = \
+  '  And then Atreyu heard Ygramuls voice. It was very high ' \
+  'and slightly hoarse, not at all the right kind of voice for that ' \
+  'enormous face. Her lips did not move as she spoke. It was the ' \
+  'buzzing of a great swarm of hornets that shaped itself into ' \
+  'words. '
+
+str = ''
+attr_str = UI.new_attributed_string(str)
+
+def attr_str.append(what, color)
+  case color
+  when :red
+    color_attribute = UI.new_color_attribute(0.0, 0.5, 0.0, 0.7)
+  when :green
+    color_attribute = UI.new_color_attribute(0.5, 0.0, 0.25, 0.7)
+  end
+  start = UI.attributed_string_len(self)
+  UI.attributed_string_append_unattributed(self, what)
+  UI.attributed_string_set_attribute(self, color_attribute, start, start + what.size)
+  UI.attributed_string_append_unattributed(self, "\n\n")
+end
+
+attr_str.append(str1, :green)
+attr_str.append(str2, :red)
+attr_str.append(str3, :green)
+attr_str.append(str4, :red)
+attr_str.append(str5, :green)
+
+Georgia = 'Georgia'
+
+handler_draw_event = Fiddle::Closure::BlockCaller.new(0, [1, 1, 1]) do |_, _, adp|
+  area_draw_params = UI::FFI::AreaDrawParams.new(adp)
+  default_font = UI::FFI::FontDescriptor.malloc
+  default_font.Family = Georgia
+  default_font.Size = 13
+  default_font.Weight = 500
+  default_font.Italic = 0
+  default_font.Stretch = 4
+  params = UI::FFI::DrawTextLayoutParams.malloc
+
+  # UI.font_button_font(font_button, default_font)
+  params.String = attr_str
+  params.DefaultFont = default_font
+  params.Width = area_draw_params.AreaWidth
+  params.Align = 0
+  text_layout = UI.draw_new_text_layout(params)
+  UI.draw_text(area_draw_params.Context, text_layout, 0, 0)
+  UI.draw_free_text_layout(text_layout)
+end
+
+handler.Draw         = handler_draw_event
+# Assigning to local variables
+# This is intended to protect Fiddle::Closure from garbage collection.
+handler.MouseEvent   = (c1 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.MouseCrossed = (c2 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.DragBroken   = (c3 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.KeyEvent     = (c4 = 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(TITLE, 600, 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'
+
+# Michael Ende (1929-1995)
+# The Neverending Story is a fantasy novel by German writer Michael Ende,
+# The English version, translated by Ralph Manheim, was published in 1983.
+class BasicDrawText
+  include Glimmer
+  
+  def alternating_color_string(initial: false, &block)
+    @index = 0 if initial
+    @index += 1
+    string {
+      if @index.odd?
+        color r: 0.5, g: 0, b: 0.25, a: 0.7
+      else
+        color r: 0, g: 0.5, b: 0, a: 0.7
+      end
+      
+      block.call + "\n\n"
+    }
+  end
+  
+  def launch
+    window('Michael Ende (1929-1995) The Neverending Story', 600, 400) {
+      margined true
+      
+      area {
+        text { # default arguments for x, y, and width are (0, 0, area_draw_params[:area_width])
+          # align :left # default alignment
+          default_font family: 'Georgia', size: 13, weight: :medium, italic: :normal, stretch: :normal
+            
+          alternating_color_string(initial: true) {
+            '  At last Ygramul sensed that something was coming toward ' \
+            'her. With the speed of lightning, she turned about, confronting ' \
+            'Atreyu with an enormous steel-blue face. Her single eye had a ' \
+            'vertical pupil, which stared at Atreyu with inconceivable malignancy. '
+          }
+          alternating_color_string {
+            '  A cry of fear escaped Bastian. '
+          }
+          alternating_color_string {
+            '  A cry of terror passed through the ravine and echoed from ' \
+            'side to side. Ygramul turned her eye to left and right, to see if ' \
+            'someone else had arrived, for that sound could not have been ' \
+            'made by the boy who stood there as though paralyzed with ' \
+            'horror. '
+          }
+          alternating_color_string {
+            '  Could she have heard my cry? Bastion wondered in alarm. ' \
+            "But that's not possible. "
+          }
+          alternating_color_string {
+            '  And then Atreyu heard Ygramuls voice. It was very high ' \
+            'and slightly hoarse, not at all the right kind of voice for that ' \
+            'enormous face. Her lips did not move as she spoke. It was the ' \
+            'buzzing of a great swarm of hornets that shaped itself into ' \
+            'words. '
+          }
+        }
+      }
+    }.show
+  end
+end
+
+BasicDrawText.new.launch
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+# Michael Ende (1929-1995)
+# The Neverending Story is a fantasy novel by German writer Michael Ende,
+# The English version, translated by Ralph Manheim, was published in 1983.
+class BasicDrawText
+  include Glimmer
+  
+  def alternating_color_string(initial: false, &block)
+    @index = 0 if initial
+    @index += 1
+    string {
+      if @index.odd?
+        color r: 0.5, g: 0, b: 0.25, a: 0.7
+      else
+        color r: 0, g: 0.5, b: 0, a: 0.7
+      end
+      
+      block.call + "\n\n"
+    }
+  end
+  
+  def launch
+    window('Michael Ende (1929-1995) The Neverending Story', 600, 400) {
+      margined true
+      
+      area {
+        on_draw do |area_draw_params|
+          text { # default arguments for x, y, and width are (0, 0, area_draw_params[:area_width])
+            # align :left # default alignment
+            default_font family: 'Georgia', size: 13, weight: :medium, italic: :normal, stretch: :normal
+              
+            alternating_color_string(initial: true) {
+              '  At last Ygramul sensed that something was coming toward ' \
+              'her. With the speed of lightning, she turned about, confronting ' \
+              'Atreyu with an enormous steel-blue face. Her single eye had a ' \
+              'vertical pupil, which stared at Atreyu with inconceivable malignancy. '
+            }
+            alternating_color_string {
+              '  A cry of fear escaped Bastian. '
+            }
+            alternating_color_string {
+              '  A cry of terror passed through the ravine and echoed from ' \
+              'side to side. Ygramul turned her eye to left and right, to see if ' \
+              'someone else had arrived, for that sound could not have been ' \
+              'made by the boy who stood there as though paralyzed with ' \
+              'horror. '
+            }
+            alternating_color_string {
+              '  Could she have heard my cry? Bastion wondered in alarm. ' \
+              "But that's not possible. "
+            }
+            alternating_color_string {
+              '  And then Atreyu heard Ygramuls voice. It was very high ' \
+              'and slightly hoarse, not at all the right kind of voice for that ' \
+              'enormous face. Her lips did not move as she spoke. It was the ' \
+              'buzzing of a great swarm of hornets that shaped itself into ' \
+              'words. '
+            }
+          }
+        end
+      }
+    }.show
+  end
+end
+
+BasicDrawText.new.launch
+```
+
+### Custom Draw Text
+
+[examples/custom_draw_text.rb](examples/custom_draw_text.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/custom_draw_text.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/custom_draw_text'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-custom-draw-text.png](images/glimmer-dsl-libui-mac-custom-draw-text.png)
+![glimmer-dsl-libui-mac-custom-draw-text-changed.png](images/glimmer-dsl-libui-mac-custom-draw-text-changed.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-custom-draw-text.png](images/glimmer-dsl-libui-linux-custom-draw-text.png)
+![glimmer-dsl-libui-linux-custom-draw-text-changed.png](images/glimmer-dsl-libui-linux-custom-draw-text-changed.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+# Michael Ende (1929-1995)
+# The Neverending Story is a fantasy novel by German writer Michael Ende,
+# The English version, translated by Ralph Manheim, was published in 1983.
+class CustomDrawText
+  include Glimmer
+  
+  def launch
+    window('Michael Ende (1929-1995) The Neverending Story', 600, 400) {
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          font_button { |fb|
+            label 'Font'
+            
+            on_changed do
+              @string.font = fb.font
+            end
+          }
+          color_button { |cb|
+            label 'Color'
+            
+            on_changed do
+              @string.color = cb.color
+            end
+          }
+          color_button { |cb|
+            label 'Background'
+            
+            on_changed do
+              @string.background = cb.color
+            end
+          }
+          combobox { |c|
+            label 'Underline'
+            items Glimmer::LibUI.enum_symbols(:underline).map(&:to_s).map {|word| word.split('_').map(&:capitalize).join(' ')}
+            selected 'None'
+            
+            on_selected do
+              @string.underline = c.selected_item.underscore
+            end
+          }
+        }
+        
+        area {
+          text { # default arguments for x, y, and width are (0, 0, area_draw_params[:area_width])
+            # align :left # default alignment
+              
+            @string = string {
+              '  At last Ygramul sensed that something was coming toward ' \
+              'her. With the speed of lightning, she turned about, confronting ' \
+              'Atreyu with an enormous steel-blue face. Her single eye had a ' \
+              'vertical pupil, which stared at Atreyu with inconceivable malignancy. ' \
+              "\n\n" \
+              '  A cry of fear escaped Bastian. ' \
+              "\n\n" \
+              '  A cry of terror passed through the ravine and echoed from ' \
+              'side to side. Ygramul turned her eye to left and right, to see if ' \
+              'someone else had arrived, for that sound could not have been ' \
+              'made by the boy who stood there as though paralyzed with ' \
+              'horror. ' \
+              "\n\n" \
+              '  Could she have heard my cry? Bastion wondered in alarm. ' \
+              "But that's not possible. " \
+              "\n\n" \
+              '  And then Atreyu heard Ygramuls voice. It was very high ' \
+              'and slightly hoarse, not at all the right kind of voice for that ' \
+              'enormous face. Her lips did not move as she spoke. It was the ' \
+              'buzzing of a great swarm of hornets that shaped itself into ' \
+              'words. ' \
+              "\n\n"
+            }
+          }
+        }
+      }
+    }.show
+  end
+end
+
+CustomDrawText.new.launch
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+# Michael Ende (1929-1995)
+# The Neverending Story is a fantasy novel by German writer Michael Ende,
+# The English version, translated by Ralph Manheim, was published in 1983.
+class CustomDrawText
+  include Glimmer
+  
+  def launch
+    window('Michael Ende (1929-1995) The Neverending Story', 600, 400) {
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          font_button { |fb|
+            label 'Font'
+            
+            on_changed do
+              @font = fb.font
+              @area.queue_redraw_all
+            end
+          }
+          color_button { |cb|
+            label 'Color'
+            
+            on_changed do
+              @color = cb.color
+              @area.queue_redraw_all
+            end
+          }
+          color_button { |cb|
+            label 'Background'
+            
+            on_changed do
+              @background = cb.color
+              @area.queue_redraw_all
+            end
+          }
+          combobox { |c|
+            label 'Underline'
+            items Glimmer::LibUI.enum_symbols(:underline).map(&:to_s).map {|word| word.split('_').map(&:capitalize).join(' ')}
+            selected 'None'
+            
+            on_selected do
+              @underline = c.selected_item.underscore
+              @area.queue_redraw_all
+            end
+          }
+        }
+        
+        @area = area {
+          on_draw do |area_draw_params|
+            text { # default arguments for x, y, and width are (0, 0, area_draw_params[:area_width])
+              # align :left # default alignment
+                
+              @string = string {
+                font @font unless @font.nil?
+                color @color unless @color.nil?
+                background @background unless @background.nil?
+                underline @underline unless @underline.nil?
+                
+                '  At last Ygramul sensed that something was coming toward ' \
+                'her. With the speed of lightning, she turned about, confronting ' \
+                'Atreyu with an enormous steel-blue face. Her single eye had a ' \
+                'vertical pupil, which stared at Atreyu with inconceivable malignancy. ' \
+                "\n\n" \
+                '  A cry of fear escaped Bastian. ' \
+                "\n\n" \
+                '  A cry of terror passed through the ravine and echoed from ' \
+                'side to side. Ygramul turned her eye to left and right, to see if ' \
+                'someone else had arrived, for that sound could not have been ' \
+                'made by the boy who stood there as though paralyzed with ' \
+                'horror. ' \
+                "\n\n" \
+                '  Could she have heard my cry? Bastion wondered in alarm. ' \
+                "But that's not possible. " \
+                "\n\n" \
+                '  And then Atreyu heard Ygramuls voice. It was very high ' \
+                'and slightly hoarse, not at all the right kind of voice for that ' \
+                'enormous face. Her lips did not move as she spoke. It was the ' \
+                'buzzing of a great swarm of hornets that shaped itself into ' \
+                'words. ' \
+                "\n\n"
+              }
+            }
+          end
+        }
+      }
+    }.show
+  end
+end
+
+CustomDrawText.new.launch
+
+```
+
 ## Contributing to glimmer-dsl-libui
 
 -   Check out the latest master to make sure the feature hasn't been