glimmer-dsl-libui 0.9.7 → 0.10.1

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.9.7
+# [<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.10.1
 ## Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library  ([Fukuoka Award Winning](http://www.digitalfukuoka.jp/topics/187?locale=ja))
 ### The Quickest Way From Zero To GUI
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
@@ -26,7 +26,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - [Declarative DSL syntax](#glimmer-gui-dsl-concepts) that visually maps to the GUI control hierarchy
 - [Convention over configuration](#smart-defaults-and-conventions) via smart defaults and automation of low-level details
 - Requiring the [least amount of syntax](#glimmer-gui-dsl-concepts) possible to build GUI
-- [Custom Control](#custom-keywords) support
+- [Custom Component](#custom-components) support (Custom Controls, Custom Windows, and Custom Shapes)
 - [Bidirectional/Unidirectional Data-Binding](#data-binding) to declaratively wire and automatically synchronize GUI Views with Models
 - [Scaffolding](#scaffold-application) for new custom windows/controls, apps, and gems
 - [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
@@ -351,12 +351,15 @@ Learn more about the differences between various [Glimmer](https://github.com/An
     - [Run Application](#run-application)
     - [Run Examples](#run-examples)
     - [Scaffold Application](#scaffold-application)
-    - [Scaffold Custom Window](#scaffold-custom-window)
     - [Scaffold Custom Control](#scaffold-custom-control)
-    - [Scaffold Custom Window Gem](#scaffold-custom-window-gem)
+    - [Scaffold Custom Window](#scaffold-custom-window)
+    - [Scaffold Custom Shape](#scaffold-custom-shape)
     - [Scaffold Custom Control Gem](#scaffold-custom-control-gem)
-    - [List Custom Window Gems](#list-custom-window-gems)
+    - [Scaffold Custom Window Gem](#scaffold-custom-window-gem)
+    - [Scaffold Custom Shape Gem](#scaffold-custom-shape-gem)
     - [List Custom Control Gems](#list-custom-control-gems)
+    - [List Custom Window Gems](#list-custom-window-gems)
+    - [List Custom Shape Gems](#list-custom-shape-gems)
     - [List Glimmer DSLs](#list-glimmer-dsls)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
@@ -381,9 +384,9 @@ Learn more about the differences between various [Glimmer](https://github.com/An
       - [Area Composite Shape](#area-composite-shape)
       - [Area Animation](#area-animation)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
-    - [Custom Controls](#custom-controls)
-      - [Method-Based Custom Controls](#method-based-custom-controls)
-      - [Class-Based Custom Controls](#class-based-custom-controls)
+    - [Custom Components](#custom-components)
+      - [Method-Based Custom Components](#method-based-custom-components)
+      - [Class-Based Custom Components](#class-based-custom-components)
     - [Observer Pattern](#observer-pattern)
     - [Data-Binding](#data-binding)
       - [Bidirectional (Two-Way) Data-Binding](#bidirectional-two-way-data-binding)
@@ -428,7 +431,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.9.7'
+gem 'glimmer-dsl-libui', '~> 0.10.1'
 ```
 
 Test that installation worked by running the [Glimmer Meta-Example](#examples):
@@ -624,7 +627,7 @@ Mac | Windows | Linux
 
 ### Scaffold Application
 
-Application scaffolding enables automatically generating the directories/files of a new desktop GUI application that follows the MVC architecture and can be packaged as a Ruby gem that includes a binary script for running the app conveniently.
+Application scaffolding enables automatically generating the directories/files of a new desktop GUI application that follows the MVC architecture and can be packaged as a Ruby gem that includes an executable script for running the app conveniently. It also ensures that software engineers follow the recommended Glimmer DSL for LibUI conventions and best practices. Application Scaffolding greatly improves software engineering productivity when building desktop applications with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui).
 
 Scaffold Glimmer DSL for LibUI application with this command:
 
@@ -722,7 +725,7 @@ Or by using the raw rake command:
 rake gemspec:generate
 ```
 
-Once you install the gem (e.g. `gem install hello_world`), you can simply run the app with its binary script:
+Once you install the gem (e.g. `gem install hello_world`), you can simply run the app with its executable script:
 
 ```
 app_name
@@ -736,8 +739,198 @@ hello_world
 
 ![glimmer-dsl-libui-mac-scaffold-app-initial-screen.png](images/glimmer-dsl-libui-mac-scaffold-app-initial-screen.png)
 
+### Scaffold Custom Control
+
+When you are in a scaffolded application, you can scaffold a new [custom control](#custom-components) (a control that you can put anything in to represent a view concept in your application) by running this command:
+
+```
+glimmer scaffold:customcontrol[name,namespace]
+```
+
+The `name` represents the [custom control](#custom-components) view class name (it can be underscored, and Glimmer will automatically classify it).
+
+The `namespace` is optional and represents the module that the [custom control](#custom-components) view class will live under. If left off, the main application class namespace is used (e.g. the top-level `HelloWorld` class namespace for a `hello_world` application).
+
+You can also use the shorter `cc` alias for `customcontrol`:
+
+```
+glimmer scaffold:cc[name,namespace]
+```
+
+For example by running this command under a `hello_world` application:
+
+```
+glimmer scaffold:cc[model_form]
+```
+
+That will generate this class under `app/hello_world/view/model_form`:
+
+```ruby
+class HelloWorld
+  module View
+    class ModelForm
+      include Glimmer::LibUI::CustomControl
+  
+      ## Add options like the following to configure CustomControl by outside consumers
+      #
+      # options :custom_text, :background_color
+      # option :foreground_color, default: :red
+      
+      # Replace example options with your own options
+      option :model
+      option :attributes
+  
+      ## Use before_body block to pre-initialize variables to use in body
+      #
+      #
+      before_body do
+        # Replace example code with your own before_body code
+        default_model_attributes = [:first_name, :last_name, :email]
+        default_model_class = Struct.new(*default_model_attributes)
+        self.model ||= default_model_class.new
+        self.attributes ||= default_model_attributes
+      end
+  
+      ## Use after_body block to setup observers for controls in body
+      #
+      # after_body do
+      #
+      # end
+  
+      ## Add control content under custom control body
+      ##
+      ## If you want to add a window as the top-most control,
+      ## consider creating a custom window instead
+      ## (Glimmer::LibUI::CustomWindow offers window convenience methods, like show and hide)
+      #
+      body {
+        # Replace example content (model_form custom control) with your own custom control content.
+        form {
+          attributes.each do |attribute|
+            entry { |e|
+              label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+              text <=> [model, attribute]
+            }
+          end
+        }
+      }
+  
+    end
+  end
+end
+```
+
+When the generated file is required in another view (e.g. `require 'hello_world/view/model_form'`), the [custom control](#custom-components) keyword `model_form` become available and reusable, like by calling:
+
+```ruby
+window {
+  vertical_box {
+    label('Form:')
+    model_form(model: some_model, attributes: array_of_attributes)
+  }
+}
+```
+
+Here is an example that generates a [custom control](#custom-components) with a namespace:
+
+```
+glimmer scaffold:cc[model_form,common]
+```
+
+That will generate this class under `app/common/view/model_form`:
+
+```ruby
+module Common
+  module View
+    class ModelForm
+      include Glimmer::LibUI::CustomControl
+  
+      ## Add options like the following to configure CustomControl by outside consumers
+      #
+      # options :custom_text, :background_color
+      # option :foreground_color, default: :red
+      
+      # Replace example options with your own options
+      option :model
+      option :attributes
+  
+      ## Use before_body block to pre-initialize variables to use in body
+      #
+      #
+      before_body do
+        # Replace example code with your own before_body code
+        default_model_attributes = [:first_name, :last_name, :email]
+        default_model_class = Struct.new(*default_model_attributes)
+        self.model ||= default_model_class.new
+        self.attributes ||= default_model_attributes
+      end
+  
+      ## Use after_body block to setup observers for controls in body
+      #
+      # after_body do
+      #
+      # end
+  
+      ## Add control content under custom control body
+      ##
+      ## If you want to add a window as the top-most control,
+      ## consider creating a custom window instead
+      ## (Glimmer::LibUI::CustomWindow offers window convenience methods, like show and hide)
+      #
+      body {
+        # Replace example content (model_form custom control) with your own custom control content.
+        form {
+          attributes.each do |attribute|
+            entry { |e|
+              label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+              text <=> [model, attribute]
+            }
+          end
+        }
+      }
+  
+    end
+  end
+end
+```
+
+When that file is required in another view (e.g. `require 'common/view/model_form'`), the `model_form` keyword becomes available:
+
+```ruby
+window {
+  vertical_box {
+    label('Form:')
+    model_form(model: some_model, attributes: array_of_attributes)
+  }
+}
+```
+
+If for whatever reason, you end up with 2 [custom control](#custom-components) views having the same name with different namespaces, then you can invoke the specific [custom control](#custom-components) you want by including the Ruby namespace in underscored format separated by double-underscores:
+
+```ruby
+window {
+  vertical_box {
+    label('Form:')
+    common__view__model_form(model: some_model, attributes: array_of_attributes)
+  }
+}
+```
+
+Or another `model_form` [custom control](#custom-components) view:
+
+```ruby
+window {
+  vertical_box {
+    label('Form:')
+    hello_world__view__model_form(model: some_model, attributes: array_of_attributes)
+  }
+}
+```
+
 ### Scaffold Custom Window
 
+A custom window is a specialization of a custom control that has a `window` as its `body` root.
+
 When you are in a scaffolded application, you can scaffold a new custom window (a window that you can put anything in to represent a view concept in your application) by running this command:
 
 ```
@@ -888,79 +1081,81 @@ Or another `train` custom window view:
 hello_world__view__train.show
 ```
 
-### Scaffold Custom Control
+### Scaffold Custom Shape
 
-When you are in a scaffolded application, you can scaffold a new custom control (a control that you can put anything in to represent a view concept in your application) by running this command:
+When you are in a scaffolded application, you can scaffold a new [custom shape](#custom-components) (a shape that you can put anything in to represent a view concept in your application) by running this command:
 
 ```
-glimmer scaffold:customcontrol[name,namespace]
+glimmer scaffold:customshape[name,namespace]
 ```
 
-The `name` represents the custom control view class name (it can be underscored, and Glimmer will automatically classify it).
+The `name` represents the [custom shape](#custom-components) view class name (it can be underscored, and Glimmer will automatically classify it).
 
-The `namespace` is optional and represents the module that the custom control view class will live under. If left off, the main application class namespace is used (e.g. the top-level `HelloWorld` class namespace for a `hello_world` application).
+The `namespace` is optional and represents the module that the [custom shape](#custom-components) view class will live under. If left off, the main application class namespace is used (e.g. the top-level `HelloWorld` class namespace for a `hello_world` application).
 
-You can also use the shorter `cc` alias for `customcontrol`:
+You can also use the shorter `cs` alias for `customshape`:
 
 ```
-glimmer scaffold:cc[name,namespace]
+glimmer scaffold:cs[name,namespace]
 ```
 
 For example by running this command under a `hello_world` application:
 
 ```
-glimmer scaffold:cw[model_form]
+glimmer scaffold:cs[heart]
 ```
 
-That will generate this class under `app/hello_world/view/model_form`:
+That will generate this class under `app/hello_world/view/heart`:
 
 ```ruby
 class HelloWorld
   module View
-    class ModelForm
-      include Glimmer::LibUI::CustomControl
+    class Heart
+      include Glimmer::LibUI::CustomShape
   
-      ## Add options like the following to configure CustomControl by outside consumers
+      ## Add options like the following to configure CustomShape by outside consumers
       #
-      # options :custom_text, :background_color
-      # option :foreground_color, default: :red
-      
-      # Replace example options with your own options
-      option :model
-      option :attributes
+      # options :option1, option2, option3
+      option :background_color, default: :red
+      option :size_width, default: 100
+      option :size_height, default: 100
+      option :location_x, default: 0
+      option :location_y, default: 0
   
       ## Use before_body block to pre-initialize variables to use in body
       #
       #
-      before_body do
-        # Replace example code with your own before_body code
-        default_model_attributes = [:first_name, :last_name, :email]
-        default_model_class = Struct.new(*default_model_attributes)
-        self.model ||= default_model_class.new
-        self.attributes ||= default_model_attributes
-      end
+      # before_body do
+      #
+      # end
   
-      ## Use after_body block to setup observers for controls in body
+      ## Use after_body block to setup observers for shapes in body
       #
       # after_body do
       #
       # end
   
-      ## Add control content under custom control body
-      ##
-      ## If you want to add a window as the top-most control,
-      ## consider creating a custom window instead
-      ## (Glimmer::LibUI::CustomWindow offers window convenience methods, like show and hide)
+      ## Add shape content under custom shape body
       #
       body {
-        # Replace example content (model_form custom control) with your own custom control content.
-        form {
-          attributes.each do |attribute|
-            entry { |e|
-              label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
-              text <=> [model, attribute]
-            }
-          end
+        # Replace example content below (heart shape) with custom shape content
+        shape(location_x, location_y) {
+          # This fill color is shared under all direct children of `shape`
+          fill background_color
+          
+          bezier(
+            size_width - size_width*0.66, size_height/2 - size_height*0.33,
+            size_width*0.65 - size_width*0.66, 0 - size_height*0.33,
+            size_width/2 - size_width*0.66, size_height*0.75 - size_height*0.33,
+            size_width - size_width*0.66, size_height - size_height*0.33
+          )
+          
+          bezier(
+            size_width - size_width*0.66, size_height/2 - size_height*0.33,
+            size_width*1.35 - size_width*0.66, 0 - size_height*0.33,
+            size_width*1.5 - size_width*0.66, size_height*0.75 - size_height*0.33,
+            size_width - size_width*0.66, size_height - size_height*0.33
+          )
         }
       }
   
@@ -969,72 +1164,83 @@ class HelloWorld
 end
 ```
 
-When the generated file is required in another view (e.g. `require 'hello_world/view/model_form'`), the custom control keyword `model_form` become available and reusable, like by calling:
+When the generated file is required in another view (e.g. `require 'hello_world/view/heart'`), the [custom shape](#custom-components) keyword `heart` become available and reusable, like by calling:
 
 ```ruby
 window {
-  vertical_box {
-    label('Form:')
-    model_form(model: some_model, attributes: array_of_attributes)
+  area {
+    heart
+  }
+}
+```
+
+You can pass `heart` options (as defined with `option` near the top of the class):
+
+```ruby
+window {
+  area {
+    heart(location_x: 25, location_y: 50)
   }
 }
 ```
 
-Here is an example that generates a custom control with a namespace:
+Here is an example that generates a [custom shape](#custom-components) with a namespace:
 
 ```
-glimmer scaffold:cw[model_form,common]
+glimmer scaffold:cs[heart,acme]
 ```
 
-That will generate this class under `app/common/view/model_form`:
+That will generate this class under `app/acme/view/heart`:
 
 ```ruby
-module Common
+module Acme
   module View
-    class ModelForm
-      include Glimmer::LibUI::CustomControl
+    class Heart
+      include Glimmer::LibUI::CustomShape
   
-      ## Add options like the following to configure CustomControl by outside consumers
+      ## Add options like the following to configure CustomShape by outside consumers
       #
-      # options :custom_text, :background_color
-      # option :foreground_color, default: :red
-      
-      # Replace example options with your own options
-      option :model
-      option :attributes
+      # options :option1, option2, option3
+      option :background_color, default: :red
+      option :size_width, default: 100
+      option :size_height, default: 100
+      option :location_x, default: 0
+      option :location_y, default: 0
   
       ## Use before_body block to pre-initialize variables to use in body
       #
       #
-      before_body do
-        # Replace example code with your own before_body code
-        default_model_attributes = [:first_name, :last_name, :email]
-        default_model_class = Struct.new(*default_model_attributes)
-        self.model ||= default_model_class.new
-        self.attributes ||= default_model_attributes
-      end
+      # before_body do
+      #
+      # end
   
-      ## Use after_body block to setup observers for controls in body
+      ## Use after_body block to setup observers for shapes in body
       #
       # after_body do
       #
       # end
   
-      ## Add control content under custom control body
-      ##
-      ## If you want to add a window as the top-most control,
-      ## consider creating a custom window instead
-      ## (Glimmer::LibUI::CustomWindow offers window convenience methods, like show and hide)
+      ## Add shape content under custom shape body
       #
       body {
-        # Replace example content (model_form custom control) with your own custom control content.
-        form {
-          attributes.each do |attribute|
-            entry { |e|
-              label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
-              text <=> [model, attribute]
-            }
-          end
+        # Replace example content below (heart shape) with your own custom shape content
+        shape(location_x, location_y) {
+          # This fill color is shared under all direct children of `shape`
+          fill background_color
+          
+          bezier(
+            size_width - size_width*0.66, size_height/2 - size_height*0.33,
+            size_width*0.65 - size_width*0.66, 0 - size_height*0.33,
+            size_width/2 - size_width*0.66, size_height*0.75 - size_height*0.33,
+            size_width - size_width*0.66, size_height - size_height*0.33
+          )
+          
+          bezier(
+            size_width - size_width*0.66, size_height/2 - size_height*0.33,
+            size_width*1.35 - size_width*0.66, 0 - size_height*0.33,
+            size_width*1.5 - size_width*0.66, size_height*0.75 - size_height*0.33,
+            size_width - size_width*0.66, size_height - size_height*0.33
+          )
         }
       }
   
@@ -1043,42 +1249,105 @@ module Common
 end
 ```
 
-When that file is required in another view (e.g. `require 'common/view/model_form'`), the `model_form` keyword becomes available:
+When that file is required in another view (e.g. `require 'acme/view/heart'`), the `heart` keyword becomes available:
 
 ```ruby
 window {
-  vertical_box {
-    label('Form:')
-    model_form(model: some_model, attributes: array_of_attributes)
+  area {
+    heart
   }
 }
 ```
 
-If for whatever reason, you end up with 2 custom control views having the same name with different namespaces, then you can invoke the specific custom control you want by including the Ruby namespace in underscored format separated by double-underscores:
+If for whatever reason, you end up with 2 [custom shape](#custom-components) views having the same name with different namespaces, then you can invoke the specific [custom shape](#custom-components) you want by including the Ruby namespace in underscored format separated by double-underscores:
 
 ```ruby
 window {
-  vertical_box {
-    label('Form:')
-    common__view__model_form(model: some_model, attributes: array_of_attributes)
+  area {
+    acme__view__heart
+  }
+}
+```
+
+Or another `heart` [custom shape](#custom-components) view:
+
+```ruby
+window {
+  area {
+    hello_world__view__heart
   }
 }
 ```
 
-Or another `model_form` custom control view:
+### Scaffold Custom Control Gem
+
+You can scaffold a Ruby gem around a reusable [custom control](#custom-components) to expose publicly and make available for multiple projects by running this command:
+
+```
+glimmer scaffold:gem:customcontrol[name,namespace]
+```
+
+That will generate a [custom control](#custom-components) gem project under the naming convention: `glimmer-libui-cc-name-namespace`
+
+The naming convention helps with discoverability of Ruby gems using the command `glimmer list:gems:customcontrol[query]` (or alias: `glimmer list:gems:cc[query]`) where filtering `query` is optional.
+
+The `name` is the [custom control](#custom-components) class name, which must not contain dashes by convention (multiple words can be concatenated or can use underscores between them).
+
+The `namespace` is needed to avoid clashing with other [custom control](#custom-components) gems that other software engineers might have thought of. It is recommended not to include dashes between words in it by convention yet concatenated words or underscores between them.
+
+Here is a shorter alias for the [custom control](#custom-components) gem scaffolding command:
+
+```
+glimmer scaffold:gem:cc[name,namespace]
+```
+
+You can package the newly scaffolded project as a Ruby gem by running this command:
+
+```
+glimmer package:gem
+```
+
+Or by using the raw rake command:
+
+```
+rake build
+```
+
+You can generate the application gemspec explicitly if needed with this command (though it is not needed to build the gem):
+
+```
+glimmer package:gemspec
+```
+
+Or by using the raw rake command:
+
+```
+rake gemspec:generate
+```
+
+Typically, consumers of the gem would include it in their own project, which makes the gem keyword available in the Glimmer GUI DSL anywhere `Glimmer`. `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomWindow`, `Glimmer::LibUI::CustomControl`, or `Glimmer::LibUI::CustomShape` is mixed.
+
+For example:
 
 ```ruby
+require 'glimmer-libui-cc-model_form-acme'
+
+...
 window {
   vertical_box {
     label('Form:')
-    hello_world__view__model_form(model: some_model, attributes: array_of_attributes)
+    
+    model_form(model: some_model, attributes: some_attributes)
   }
 }
+...
 ```
 
 ### Scaffold Custom Window Gem
 
-You can scaffold a Ruby gem around a reusable custom window by running this command:
+A custom window is a specialization of a custom control that has a `window` as its `body` root.
+
+You can scaffold a Ruby gem around a reusable custom window to expose publicly and make available for multiple projects by running this command:
 
 ```
 glimmer scaffold:gem:customwindow[name,namespace]
@@ -1122,9 +1391,9 @@ Or by using the raw rake command:
 rake gemspec:generate
 ```
 
-The project optionally allows you to run the custom window as its own separate app with a binary script (`bin/gem_name`) to see it, which helps with prototyping it.
+The project optionally allows you to run the custom window as its own separate app with a executable script (`bin/gem_name`) to see it, which helps with prototyping it.
 
-But, typically consumers of the gem would include it in their own project, which makes the gem keyword available in the Glimmer GUI DSL anywhere `Glimmer`. `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomWindow`, or `Glimmer::LibUI::CustomControl` is mixed.
+But, typically consumers of the gem would include it in their own project, which makes the gem keyword available in the Glimmer GUI DSL anywhere `Glimmer`. `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomWindow`, `Glimmer::LibUI::CustomControl`, or `Glimmer::LibUI::CustomShape` is mixed.
 
 For example:
 
@@ -1136,26 +1405,26 @@ greeter.show
 ...
 ```
 
-### Scaffold Custom Control Gem
+### Scaffold Custom Shape Gem
 
-You can scaffold a Ruby gem around a reusable custom control by running this command:
+You can scaffold a Ruby gem around a reusable [custom shape](#custom-components) to expose publicly and make available for multiple projects by running this command:
 
 ```
-glimmer scaffold:gem:customcontrol[name,namespace]
+glimmer scaffold:gem:customshape[name,namespace]
 ```
 
-That will generate a custom control gem project under the naming convention: `glimmer-libui-cc-name-namespace`
+That will generate a [custom shape](#custom-components) gem project under the naming convention: `glimmer-libui-cc-name-namespace`
 
-The naming convention helps with discoverability of Ruby gems using the command `glimmer list:gems:customcontrol[query]` (or alias: `glimmer list:gems:cc[query]`) where filtering `query` is optional.
+The naming convention helps with discoverability of Ruby gems using the command `glimmer list:gems:customshape[query]` (or alias: `glimmer list:gems:cs[query]`) where filtering `query` is optional.
 
-The `name` is the custom control class name, which must not contain dashes by convention (multiple words can be concatenated or can use underscores between them).
+The `name` is the [custom shape](#custom-components) class name, which must not contain dashes by convention (multiple words can be concatenated or can use underscores between them).
 
-The `namespace` is needed to avoid clashing with other custom control gems that other software engineers might have thought of. It is recommended not to include dashes between words in it by convention yet concatenated words or underscores between them.
+The `namespace` is needed to avoid clashing with other [custom shape](#custom-components) gems that other software engineers might have thought of. It is recommended not to include dashes between words in it by convention yet concatenated words or underscores between them.
 
-Here is a shorter alias for the custom control gem scaffolding command:
+Here is a shorter alias for the [custom shape](#custom-components) gem scaffolding command:
 
 ```
-glimmer scaffold:gem:cc[name,namespace]
+glimmer scaffold:gem:cs[name,namespace]
 ```
 
 You can package the newly scaffolded project as a Ruby gem by running this command:
@@ -1182,24 +1451,40 @@ Or by using the raw rake command:
 rake gemspec:generate
 ```
 
-Typically, consumers of the gem would include it in their own project, which makes the gem keyword available in the Glimmer GUI DSL anywhere `Glimmer`. `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomWindow`, or `Glimmer::LibUI::CustomControl` is mixed.
+Typically, consumers of the gem would include it in their own project, which makes the gem keyword available in the Glimmer GUI DSL anywhere `Glimmer`. `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomWindow`, `Glimmer::LibUI::CustomControl`, or `Glimmer::LibUI::CustomShape` is mixed.
 
 For example:
 
 ```ruby
-require 'glimmer-libui-cc-model_form-acme'
+require 'glimmer-libui-cs-heart-acme'
 
 ...
 window {
-  vertical_box {
-    label('Form:')
-    
-    model_form(model: some_model, attributes: some_attributes)
+  area {
+    heart
   }
 }
 ...
 ```
 
+### List Custom Control Gems
+
+Custom control gems are scaffolded to follow the naming convention: `glimmer-libui-cc-name-namespace`
+
+The naming convention helps with discoverability of Ruby gems using the command:
+
+```
+glimmer list:gems:customcontrol[query]
+```
+
+Or by using the shorter alias:
+
+```
+glimmer list:gems:cc[query]
+```
+
+The filtering `query` is optional.
+
 ### List Custom Window Gems
 
 Custom window gems are scaffolded to follow the naming convention: `glimmer-libui-cw-name-namespace`
@@ -1218,21 +1503,20 @@ glimmer list:gems:cw[query]
 
 The filtering `query` is optional.
 
+### List Custom Shape Gems
 
-### List Custom Control Gems
-
-Custom control gems are scaffolded to follow the naming convention: `glimmer-libui-cw-name-namespace`
+Custom shape gems are scaffolded to follow the naming convention: `glimmer-libui-cs-name-namespace`
 
 The naming convention helps with discoverability of Ruby gems using the command:
 
 ```
-glimmer list:gems:customcontrol[query]
+glimmer list:gems:customshape[query]
 ```
 
 Or by using the shorter alias:
 
 ```
-glimmer list:gems:cc[query]
+glimmer list:gems:cs[query]
 ```
 
 The filtering `query` is optional.
@@ -1725,7 +2009,7 @@ Learn more by checking out [examples](#examples).
 
 [EARLY ALPHA FEATURE]
 
-`refined_table` is a custom control provided exclusively by [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)
+`refined_table` is a [custom control](#custom-components) provided exclusively by [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)
 that includes filtering and pagination support out of the box and can handle very large amounts of data (e.g. 50,000 rows).
 
 It is currently an early alpha feature, so please test-drive and report issues if you encounter any.
@@ -1747,7 +2031,7 @@ API:
 
 - `refined_model_array` (`Array`): `model_array` with filtering and pagination applied (useful to grab a table row model by index).
 - `filtered_model_array` (`Array`): `model_array` with filtering applied, but without pagination
-- `table_proxy`: control proxy object for the `table` contained in the `refined_table` custom control
+- `table_proxy`: control proxy object for the `table` contained in the `refined_table` [custom control](#custom-components)
 
 If the initial `model_array` has no more than a single page of data, then pagination buttons are hidden (but, the filter field remains).
 
@@ -1990,7 +2274,7 @@ Mac | Windows | Linux
 **(ALPHA FEATURE)**
 
 [libui-ng](https://github.com/libui-ng/libui-ng) does not support `image` rendering outside of `table` yet.
-However, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) adds a special `image(file as String path or web URL, width as Numeric, height as Numeric)` custom control that renders an image unto an `area` pixel by pixel (and when possible to optimize, line by line).
+However, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) adds a special `image(file as String path or web URL, width as Numeric, height as Numeric)` [custom control](#custom-components) that renders an image unto an `area` pixel by pixel (and when possible to optimize, line by line).
 
 Given that it is very new and is not a [libui-ng](https://github.com/libui-ng/libui-ng)-native control, please keep these notes in mind:
 - It only supports the `.png` file format.
@@ -2163,7 +2447,7 @@ One final note is that in Linux, table images grow and shrink with the image siz
 
 ![linux table image](images/glimmer-dsl-libui-linux-basic-table-image.png)
 
-Check out [examples/basic_image.rb](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-image) (all versions) for examples of using `image` Glimmer custom control.
+Check out [examples/basic_image.rb](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-image) (all versions) for examples of using `image` Glimmer [custom control](#custom-components).
 
 #### Colors
 
@@ -2476,7 +2760,7 @@ BasicCompositeShape.launch
 
 If you need to animate `area` vector graphics, you just have to use the [`Glimmer::LibUI::timer`](#libui-operations) method along with making changes to shape attributes.
 
-Spinner example that has a fully customizable method-based custom control called `spinner`, which is destroyed if you click on it (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Spinner example that has a fully customizable method-based [custom control](#custom-components) called `spinner`, which is destroyed if you click on it (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -2605,21 +2889,21 @@ SpinnerExample.new.launch
 - Colors may be passed in as a hash of `:r`, `:g`, `:b`, `:a`, or `:red`, `:green`, `:blue`, `:alpha`, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color like `:skyblue`, or 6-char hex or 3-char hex (as `Integer` or `String` with or without `0x` prefix)
 - Color alpha value defaults to `1.0` when not specified.
 
-### Custom Controls
+### Custom Components
 
-Custom controls can be defined to represent custom controls (components) that provide new features or act as composites of [existing controls](#supported-keywords) that need to be reused multiple times in an application or across multiple applications. Custom controls save a lot of development time, improving productivity and maintainability immensely.
+Custom components like custom controls, custom windows, and custom shapes can be defined to provide new features or act as composites of existing controls/shapes that need to be reused multiple times in an application or across multiple applications. Custom components save a lot of development time through reuse, improving productivity and maintainability immensely.
 
 For example, you can define a custom `address_view` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
 
-There are two ways to define custom controls:
-- Method-Based: simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
-- Class-Based: define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
+There are two ways to define custom components:
+- Method-Based: simply define a method representing the custom component you want (e.g. `address_view`) with any options needed (e.g. `address(address_model: some_model)`).
+- Class-Based: define a class matching the camelcased name of the custom component by convention (e.g. the `address_view` custom component keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`, `include Glimmer::LibUI::CustomWindow`, or `include Glimmer::LibUI::CustomShape` depending on if the component represents a standard control, a whole window, or an [area canvas graphics shape](#area-path-shapes). Classes add the benefit of being able to distribute the custom components into a separate file for external reuse from multiple views or for sharing as a Ruby gem.
 
-It is OK to use the terms "custom control" and "custom keyword" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
+It is OK to use the terms "custom control", "custom component", and "custom keyword" synonymously though "custom component" is a broader term that covers things other than controls too like custom shapes (e.g. `cube`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
 
 #### Method-Based Custom Controls
 
-Simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
+Simply define a method representing the custom component you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
 
 Example that defines `form_field`, `address_form`, `label_pair`, and `address_view` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -2718,9 +3002,9 @@ window('Method-Based Custom Keyword') {
 
 ![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
 
-#### Class-Based Custom Controls
+#### Class-Based Custom Components
 
-Define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
+Define a class matching the camelcased name of the [custom control](#custom-components) by convention (e.g. the `address_view` [custom control](#custom-components) keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the [custom control](#custom-components)s into separate files and reuse externally from multiple places or share via Ruby gems.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -2850,13 +3134,185 @@ ClassBasedCustomControls.launch
 
 ![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
 
-You can also define Custom Window keywords, that is custom controls with `window` being the body root. These are also known as Applications. To define a Custom Window, you `include Glimmer::LibUI::CustomWindow` or `include Glimmer:LibUI::Application` and then you can invoke the `::launch` method on the class.
+Example of a `cube` custom shape (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+# class-based custom shape using Glimmer::LibUI::CustomShape mixin, which automatically
+# augments the Glimmer GUI DSL with the underscored version of the class name: `cube`
+# while accepting hash options matching the options declared on the class.
+# (e.g. `cube(location_x: 50, location_y: 100)` )
+class Cube
+  include Glimmer::LibUI::CustomShape
+  
+  DEFAULT_SIZE = 28
+  
+  option :location_x, default: 0
+  option :location_y, default: 0
+  option :rectangle_width, default: nil
+  option :rectangle_height, default: nil
+  option :cube_height, default: 75
+  option :background_color, default: :brown
+  option :foreground_color
+  option :line_thickness, default: 1
+    
+  # The before_body block executes before building the body
+  before_body do
+    self.rectangle_width ||= rectangle_height || cube_height || DEFAULT_SIZE
+    self.rectangle_height ||= rectangle_width || cube_height || DEFAULT_SIZE
+    self.cube_height ||= rectangle_width || rectangle_height || DEFAULT_SIZE
+    if foreground_color
+      self.foreground_color = Glimmer::LibUI.interpret_color(foreground_color)
+      self.foreground_color[:thickness] ||= line_thickness
+    else
+      self.foreground_color = [0, 0, 0, thickness: line_thickness]
+    end
+  end
+  
+  # Optionally, after_body could be defined to perform operations after building the body
+  # like setting up observers.
+  #
+  # after_body do
+  # end
+  
+  body {
+    # the shape keyword (alias for composite_shape) enables building a composite shape that is treated as one shape
+    # like a cube containing polygons, a polyline, a rectangle, and a line
+    # with the fill and stroke colors getting inherited by all children that do not specify them
+    shape(location_x, location_y) {
+      fill background_color
+      stroke foreground_color
+    
+      bottom = polygon(0, cube_height + rectangle_height / 2.0,
+              rectangle_width / 2.0, cube_height,
+              rectangle_width, cube_height + rectangle_height / 2.0,
+              rectangle_width / 2.0, cube_height + rectangle_height) {
+        # inherits fill property from parent shape if not set
+        # inherits stroke property from parent shape if not set
+      }
+      body = rectangle(0, rectangle_height / 2.0, rectangle_width, cube_height) {
+        # inherits fill property from parent shape if not set
+        # stroke is overridden to ensure a different value from parent
+        stroke thickness: 0
+      }
+      polyline(0, rectangle_height / 2.0 + cube_height,
+               0, rectangle_height / 2.0,
+               rectangle_width, rectangle_height / 2.0,
+               rectangle_width, rectangle_height / 2.0 + cube_height) {
+        # inherits stroke property from parent shape if not set
+      }
+      top = polygon(0, rectangle_height / 2.0,
+              rectangle_width / 2.0, 0,
+              rectangle_width, rectangle_height / 2.0,
+              rectangle_width / 2.0, rectangle_height) {
+        # inherits fill property from parent shape if not set
+        # inherits stroke property from parent shape if not set
+      }
+      line(rectangle_width / 2.0, cube_height + rectangle_height,
+           rectangle_width / 2.0, rectangle_height) {
+        # inherits stroke property from parent shape if not set
+      }
+    }
+  }
+end
+
+class BasicCustomShape
+  include Glimmer::LibUI::Application
+  
+  body {
+    window {
+      title 'Basic Custom Shape'
+      content_size 200, 225
+    
+      @area = area {
+        rectangle(0, 0, 200, 225) {
+          fill :white
+        }
+        
+        7.times do |n|
+          x_location = (rand*125).to_i%200 + (rand*15).to_i
+          y_location = (rand*125).to_i%200 + (rand*15).to_i
+          shape_color = [rand*125 + 130, rand*125 + 130, rand*125 + 130]
+          shape_size = 20+n
+
+          cube(
+            location_x: x_location,
+            location_y: y_location,
+            rectangle_width: shape_size*2,
+            rectangle_height: shape_size,
+            cube_height: shape_size*2,
+            background_color: shape_color,
+            line_thickness: 2
+          ) { |the_shape|
+            on_mouse_up do |area_mouse_event|
+              # Change color on mouse up without dragging
+              if @drag_shape.nil?
+                background_color = [rand(255), rand(255), rand(255)]
+                the_shape.fill = background_color
+              end
+            end
+
+            on_mouse_drag_start do |area_mouse_event|
+              @drag_shape = the_shape
+              @drag_x = area_mouse_event[:x]
+              @drag_y = area_mouse_event[:y]
+            end
+
+            on_mouse_drag do |area_mouse_event|
+              if @drag_shape && @drag_x && @drag_y
+                drag_distance_width = area_mouse_event[:x]  - @drag_x
+                drag_distance_height = area_mouse_event[:y] - @drag_y
+                @drag_shape.x += drag_distance_width
+                @drag_shape.y += drag_distance_height
+                @drag_x = area_mouse_event[:x]
+                @drag_y = area_mouse_event[:y]
+              end
+            end
+
+            on_mouse_drop do |area_mouse_event|
+              @drag_shape = nil
+              @drag_x = nil
+              @drag_y = nil
+            end
+          }
+        end
+        
+        # this general area on_mouse_drag listener is needed to ensure that dragging a shape
+        # outside of its boundaries would still move the dragged shape
+        on_mouse_drag do |area_mouse_event|
+          if @drag_shape && @drag_x && @drag_y
+            drag_distance_width = area_mouse_event[:x]  - @drag_x
+            drag_distance_height = area_mouse_event[:y] - @drag_y
+            @drag_shape.x += drag_distance_width
+            @drag_shape.y += drag_distance_height
+            @drag_x = area_mouse_event[:x]
+            @drag_y = area_mouse_event[:y]
+          end
+        end
+        
+        on_mouse_drop do |area_mouse_event|
+          @drag_shape = nil
+          @drag_x = nil
+          @drag_y = nil
+        end
+      }
+    }
+  }
+end
+
+BasicCustomShape.launch
+```
+
+![glimmer-dsl-libui-mac-basic-custom-shape.gif](/images/glimmer-dsl-libui-mac-basic-composite-shape.gif)
+
+You can also define Custom Window keywords, that is [custom control](#custom-components)s with `window` being the body root. These are also known as Applications. To define a Custom Window, you `include Glimmer::LibUI::CustomWindow` or `include Glimmer:LibUI::Application` and then you can invoke the `::launch` method on the class.
 
 The [`area`](#area-api) control can be utilized to build non-native custom controls from scratch by leveraging vector graphics, formattable text, keyboard events, and mouse events. This is demonstrated in the [Area-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#area-based-custom-controls) example.
 
 Defining custom controls enables unlimited extension of the [Glimmer GUI DSL](#glimmer-gui-dsl). The sky is the limit on what can be done with custom controls as a result. You can compose new visual vocabulary to build applications in any domain from higher concepts rather than [mere standard controls](#supported-keywords). For example, in a traffic signaling app, you could define `street`, `light_signal`, `traffic_sign`, and `car` as custom keywords and build your application from these concepts directly, saving enormous time and achieving much higher productivity.
 
-Learn more from custom control usage in [Method-Based Custom Keyword](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#method-based-custom-keyword), [Area-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#area-based-custom-controls), [Basic Scrolling Area](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-scrolling-area), [Histogram](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#histogram), and [Tetris](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#tetris) examples.
+Learn more from custom control usage in [Method-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#method--based-custom-controls), [Class-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#class-based-custom-controls), [Area-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#area-based-custom-controls), [Basic Composite Shape](), [Basic Custom Shape](), [Basic Scrolling Area](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-scrolling-area), [Histogram](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#histogram), and [Tetris](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#tetris) examples.
 
 ### Observer Pattern