README.md in whirled_peas-0.9.1 vs README.md in whirled_peas-0.10.0
- old
+ new
@@ -83,11 +83,12 @@
### Application
The application is code to be visualized that integrates with Whirled Peas by providing the signature below
```ruby
-# Start the application and pass frame events to the producer to be rendered by the UI
+# Start the application and pass frame events to the producer to be rendered
+# by the UI
#
# @param producer [Producer] frame producer that sends events to the UI
def start(producer)
# application code here
end
@@ -96,31 +97,45 @@
The producer provides the following methods
```ruby
# Add a frame to be displayed
#
-# @param name [String] application defined name for the frame. The template factory will be provided this name
-# @param duration [Number] time in seconds this frame should be displayed for (defaults to 1 frame)
-# @param args [Hash<Symbol, Object>] key value pairs to send as arguments to the template factory
+# @param name [String] (required) application defined name for the frame. The
+# template factory will be provided this name
+# @param duration [Number] (optional) time in seconds this frame should be
+# displayed for (defaults to 1 frame)
+# @param args [Hash<Symbol, Object>] (optional) key/value pairs to send as
+# arguments to the template factory
def add_frame(name, duration:, args:)
end
-# Create and yield a frameset instance that allows applications to add multiple frames to play over the
-# given duration. Adding frames to the yielded frameset will result in playback that is eased by the
-# gvien `easing` and `effect` arguments (default is `:linear` easing)
+# Create and yield a frameset instance that allows applications to add multiple
+# frames to play over the given duration. Adding frames to the yielded frameset
+# will result in playback that is eased by the given `easing` and `effect`
+# arguments (default is `:linear` easing)
+#
+# @param duration [Number] (required) total duration for which all frames in
+# frameset will be displayed
+# @param easing [Symbol] (optional) easing function to be used to transition
+# through all frames (defaults to `:linear`)
+# @param effect [Symbol] (optional) how to apply the easing function (defaults
+# to `:in_out`, also available are `:in` and `:out`)
+# @yield [Frameset] instance that provides `#add_frame(name, args:)`
def frameset(duration, easing:, effect:, &block)
end
```
A frameset instance provides one method
```ruby
-# Add a frame to be displayed, the duration will be determine by the number of frames in the frameset along
-# with the duration and easing of the frameset
+# Add a frame to be displayed, the duration will be determine by the number of
+# frames in the frameset along with the duration and easing of the frameset
#
-# @param name [String] application defined name for the frame. The template factory will be provided this name
-# @param args [Hash<Symbol, Object>] key value pairs to send as arguments to the template factory
+# @param name [String] (required) application defined name for the frame. The
+# template factory will be provided this name
+# @param args [Hash<Symbol, Object>] (optional) key/value pairs to send as
+# arguments to the template factory
def add_frame(name, args:)
end
```
**IMPORTANT**: the keys in the `args` hash must be symbols!
@@ -230,34 +245,50 @@
end
```
#### Settings
-Each element type has an associated settings type, which provide a custom set of options to format the output. Child settings will inherit from the parent, where applicable
-The available settigs are
+Each element type has an associated settings type, which provide a custom set of options to format the output. Child settings will inherit from the parent, where applicable. The table below lists all settings along with which element types the settings can be applied to (`Grid` and `Box` are containers)
| Setting | Description | Default | Availability | Inherited |
| ------------ | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- |
-| `align` | Justifies the content in the horizontal direction | `:left` | `Container` | No |
+| `align` | Justifies the content in the horizontal direction | `:left` | containers | No |
| `axis_color` | Color used to paint the axes of the graph (see [Colors](#colors)) | | `Graph` | No |
| `bg_color` | Background color (see [Colors](#colors)) | | all | Yes |
| `bold` | `true` makes the font bold | `false` | all | Yes |
-| `border` | Set the border for the lements | none | `Container`, | Only style and color |
+| `border` | Set the border for the lements | none | containers, | Only style and color |
| `color` | Foreground text color (see [Colors](#colors)) | | all | Yes |
-| `flow` | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r` | `Container` | No |
+| `flow` | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r` | containers | No |
| `height` | Override the calculated height of an element's content area | | all | No |
-| `margin` | Set the (left, top, right, bottom) margin of the element | `0` | `Container` | No |
+| `margin` | Set the (left, top, right, bottom) margin of the element | `0` | containers | No |
| `num_cols` | Number of columns in the grid (must be set!) | | `Grid` | No |
-| `padding` | Set the (left, top, right, bottom) padding of the element | `0` | `Container` | No |
-| `position` | Set the (left, top) position of the element relative to parent content area | `0` | `Container` | No |
+| `padding` | Set the (left, top, right, bottom) padding of the element | `0` | containers | No |
+| `position` | Set the (left, top) position of the element relative to parent content area | `0` | containers | No |
| `scrollbar` | Display a scroll bar for vertical or horizontal scrolling | | `Box` | No |
| `sizing` | Sizing model (`:content` or `:border`) used in conjunction with `width`/`height` | `:content` | `Box` | No |
| `title_font` | Font used for "large" text (see [Large Text](#large-text), ignores `underline`) | | `Text` | No |
| `underline` | `true` underlines the font | `false` | all | Yes |
| `width` | Override the calculated width of an element's content area | | all | No |
-| `valign` | Justifies the content in the vertical direction | `:top` | `Container` | No |
+| `valign` | Justifies the content in the vertical direction | `:top` | containers | No |
+##### Themes
+
+The template builder (`WhirledPeas.template`) takes an optional `theme` argument. You can provide the name of a predefined theme (run `whirled_peas themes` to see a list with samples) or define you own with the following
+You can define your own theme
+
+```ruby
+WhirledPeas.define_theme(:my_theme) do |theme|
+ theme.bg_color = :bright_white
+ theme.color = :blue
+ theme.border_color = :bright_green
+ theme.axis_color = :bright_red
+ theme.title_font = :default
+end
+```
+
+Theme settings will be used as default settings throughout the template, however theme settings can be overridden on any element.
+
##### Alignment
The `align` setting takes one of several values
- `:left` - align content starting at the leftmost edge of the container's content area
@@ -1008,10 +1039,11 @@
frames Print out list of frames generated by application
help Show detailed help for a command
play Play an animation from an application or prerecorded file
record Record animation to a file
still Show the specified still frame
+ themes List all themes with sample template rendered in the theme
```
#### `debug`
Print the template tree for specified frame.
@@ -1094,9 +1126,22 @@
```
# Usage: whirled_peas still <config file> <frame> [args as a JSON string]
% whirled_peas still my_app.rb greeting '{"name":"World"}'
# Still frame is displayed
+```
+
+#### `themes`
+
+List all themes and display a small sample screen in each. Running this with no extra command line arguments will display all the built-in themes. Adding the path to a Whirled Peas configuration file will inlcude any themes defined in that configuration.
+
+```
+# Usage: whirled_peas themes [config file]
+% whirled_peas themes
+# Display all system themes
+
+% whirled_peas themes my_app.rb
+# Display app-defined themes and all system themes
```
## 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.