README.md in whirled_peas-0.3.0 vs README.md in whirled_peas-0.4.0

@@ -20,17 +20,26 @@
 
     $ gem install whirled_peas
 
 ## Usage
 
+A Whirled Peas application consists of the following pieces
+
+1. [REQUIRED] The driver, which emits lightweight frame events
+1. [REQUIRED] The main template factory, which builds templates to convert frame events from the driver into terminal graphics
+1. [OPTIONAL] A loading screen template factory, which is used while content is loading
+
+These pieces are configured as following
+
 ```ruby
+# visualize.rb
 require 'whirled_peas'
 
 class TemplateFactory
   def build(frame, args)
     WhirledPeas.template do |body|
-      body.add_box do |_, settings|
+      body.add_box('Title') do |_, settings|
         settings.underline = true
         "Hello #{args['name']}"
       end
       # ...
     end
@@ -42,18 +51,44 @@
     producer.send_frame('starting', args: { 'name' => 'World' })
     # ...
   end
 end
 
-WhirledPeas.start(Driver.new, TemplateFactory.new)
+WhirledPeas.configure do |config|
+  config.driver = Driver.new
+  config.template_factory = TemplateFactory.new
+end
 ```
 
-A Whirled Peas application consists of two pieces
+Then the visualizer is started on the command line with
 
-1. The driver, which emits lightweight frame events
-1. The template factory, which builds templates to convert frame events from the driver into terminal graphics
+```
+$ whirled_peas start visualize.rb
+```
 
+The optional loading screen can be configured like
+
+````ruby
+class LoadingTemplateFactory
+  def build
+    WhirledPeas.template do |t|
+      t.add_box('Loading') do |box, settings|
+        settings.set_margin(top: 15)
+        settings.auto_margin = true
+        settings.full_border(color: :blue, style: :double)
+        "Loading..."
+      end
+    end
+  end
+end
+
+WhirledPeas.configure do |config|
+  # ...
+  config.loading_template_factory = LoadingTemplateFactory.new
+end
+```
+
 ### Driver
 
 The driver is the application code to be visualized. This is typically a lightweight wrapper around an existing application that conforms to the signature below.
 
 ```ruby
@@ -61,11 +96,11 @@
 #
 # @param producer [Producer] frame producer that sends events to the UI
 def start(producer)
   # application code here
 end
-```
+````
 
 The producer provides a single method
 
 ```ruby
 # Send frame events to the UI
@@ -111,10 +146,14 @@
 
 ### Template Factory
 
 To render the frame events sent by the driver, the application requires a template factory. This factory will be called for each frame event, with the frame name and the arguments supplied by the driver. A template factory can be a simple ruby class and thus can maintain state. Whirled Peas provides a few basic building blocks to make simple, yet elegant terminal-based UIs.
 
+#### Loading Template Factory
+
+`WhirledPeas.start` takes an optional template facotry to build a loading screen. This instance must implement `#build` (taking no arguments). The template returned by that method will be painted while the event loop is waiting for frames. The factory method will be called once per refresh cycle, so it's possible to implement animation.
+
 #### Building Blocks
 
 A template is created with `WhirledPeas.template`, which yields a `Template` object and `TemplateSettings`. This template object is a `ComposableElement`, which allows for attaching child elements and setting layout options. `GridElement` and `BoxElement` are two other composable elements and `TextElement` is a simple element that can hold a text/number value and has layout options, but cannot have any child elements.
 
 A `ComposableElement` provides the following methods to add child elements, each of these takes an optional string argument that is set as the name of the element (which can be useful when debugging).
@@ -193,10 +232,11 @@
 | `border`      | Set the border for the lements                                     | none    | `Box`, `Grid`,                    | Yes     |
 | `color`       | Foreground text color (see [Colors](#colors))                      |         | `Box`, `Grid`, `Template`, `Text` | Yes     |
 | `flow`        | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r`  | `Box`                             | Yes     |
 | `margin`      | Set the (left, top, right, bottom) margin of the element           | `0`     | `Box`, `Grid`                     | Yes     |
 | `padding`     | Set the (left, top, right, bottom) padding of the element          | `0`     | `Box`, `Grid`                     | Yes     |
+| `title_font`  | Font used to create "large" text (see [Large Text](#large-text))   |         | `Text`                            |
 | `transpose`   | Display grid elements top-to-bottom, then left-to-right            | `false` | `Grid`                            | No      |
 | `underline`   | `true` underlines the font                                         | `false` | `Box`, `Grid`, `Template`, `Text` | Yes     |
 | `width`       | Override the calculated with of an element                         |         | `Box`, `Grid`, `Text`             | No      |
 
 ##### Margin and Padding
@@ -302,10 +342,31 @@
 - `:bright_green`
 - `:bright_magenta`
 - `:bright_red`
 - `:bright_yellow`
 
+##### Large Text
+
+The `title_font` setting for `TextElement`s converts the standard terminal font into a large block font. The available fonts vary from system to system. Every system will have a `:default` font available, this font could look like
+
+```
+██████╗ ███████╗███████╗ █████╗ ██╗   ██╗██╗     ████████╗
+██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██║     ╚══██╔══╝
+██║  ██║█████╗  █████╗  ███████║██║   ██║██║        ██║
+██║  ██║██╔══╝  ██╔══╝  ██╔══██║██║   ██║██║        ██║
+██████╔╝███████╗██║     ██║  ██║╚██████╔╝███████╗   ██║
+╚═════╝ ╚══════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝
+```
+
+To print out a list of all available fonts as well as sample text in that font, run
+
+```
+$ whirled_peas title_fonts
+```
+
+Note: when using a title font with WhirledPeas for the first time on a system, the gem loads all fonts to check which ones are available. This can be a slow process and may cause a noticeable delay when running a visualization. Running the command above will cache the results and thus when a WhirledPeas visualization is run, there will be no lag from loading fonts.
+
 ### Example
 
 ```ruby
 class TemplateFactory
   def build(frame, args)
@@ -352,9 +413,67 @@
     elem.add_box('Title', &method(:title))
     elem.add_box('Sum', &method(:sum))
     elem.add_grid('NumberGrid', &method(:number_grid))
   end
 end
+```
+
+### Debugging
+
+The `whirled_peas` executable provides some commands that are helpful for debugging.
+
+#### list_frames
+
+List the frames sent by the driver
+
+```
+$ whirled_peas <config file> list_frames
+Frame 'start' displayed for 5 second(s)
+Frame 'move' displayed for 1 frame ({:direction=>'N'})
+...
+EOF frame detected
+```
+
+#### play_frame
+
+Displays a single frame for several seconds
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}'
+```
+
+Adding the `--debug` flag will result in just printing out the template's debug information, e.g.
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}' --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - Children
+    + TitleContainer [WhirledPeas::UI::BoxElement]
+...
+```
+
+#### loading
+
+Displays the configured loading screen for several seconds
+
+```
+$ whirled_peas <config file> loading
+```
+
+Adding the `--debug` flag will result in just printing out the loading template's debug information, e.g.
+
+```
+$ whirled_peas <config file> loading --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - Children
+    + TitleContainer [WhirledPeas::UI::BoxElement]
+...
 ```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.