README.md in whirled_peas-0.8.0 vs README.md in whirled_peas-0.9.0

- old
+ new

@@ -91,23 +91,40 @@ def start(producer) # application code here end ``` -The producer provides a single method +The producer provides the following methods ```ruby -# Send frame events to the UI +# 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 def add_frame(name, duration:, args:) - # implementation 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) +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 +# +# @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 +def add_frame(name, args:) +end +``` + **IMPORTANT**: the keys in the `args` hash must be symbols! #### Example Simple application that loads a set of numbers and looks for a pair that adds up to 1,000 @@ -153,10 +170,11 @@ - `sizing` - will be set `:border` to ensure the entire box fits on the screen and fills it entirely. A `Composer` 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). - `add_box` - yields a `Composer` for a `Box` and a `BoxSettings`, which will be added to the parent's children +- `add_graph` - yields a `nil` and a `GraphSettings`, which will be added to the parent's children, the block should return an array of numbers - `add_grid` - yields a `Composer` for a `Grid` and a `GridSettings`, which will be added to the parent's children - `add_text` - yields `nil` and a `TextSettings`, which will be added to the parent's children E.g. @@ -215,29 +233,30 @@ #### 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 -| Setting | Description | Default | Availability | Inherited | -| ------------ | -------------------------------------------------------------------------------- | ---------- | --------------------- | -------------------- | -| `align` | Justifies the content in the horizontal direction | `:left` | `Box`, `Grid` | No | -| `bg_color` | Background color (see [Colors](#colors)) | | `Box`, `Grid`, `Text` | Yes | -| `bold` | `true` makes the font bold | `false` | `Box`, `Grid`, `Text` | Yes | -| `border` | Set the border for the lements | none | `Box`, `Grid`, | Only style and color | -| `color` | Foreground text color (see [Colors](#colors)) | | `Box`, `Grid`, `Text` | Yes | -| `flow` | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r` | `Box`, `Grid` | No | -| `height` | Override the calculated height of an element's content area | | `Box`, `Grid` | No | -| `margin` | Set the (left, top, right, bottom) margin of the element | `0` | `Box`, `Grid` | 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` | `Box`, `Grid` | No | -| `position` | Set the (left, top) position of the element relative to parent content area | `0` | `Box`, `Grid` | 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` | `Box`, `Grid`, `Text` | Yes | -| `width` | Override the calculated width of an element's content area | | `Box`, `Grid` | No | -| `valign` | Justifies the content in the vertical direction | `:top` | `Box`, `Grid` | No | +| Setting | Description | Default | Availability | Inherited | +| ------------ | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- | +| `align` | Justifies the content in the horizontal direction | `:left` | `Container` | 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 | +| `color` | Foreground text color (see [Colors](#colors)) | | all | Yes | +| `flow` | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r` | `Container` | 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 | +| `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 | +| `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 | ##### Alignment The `align` setting takes one of several values @@ -669,12 +688,270 @@ $ 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 +#### Easing +The play duration of a frame within a frameset is determined by the easing function and effect along with the frames relative position within the frameset. The three effects are + +- `:in` - apply easing only to the start of the frameset +- `:out` - apply easing only to the end of the frameset +- `:in_out` - apply easing to the start and end of the frameset + +The available easing functions are + +- `:bezier` + +``` +# bezier (in) +┃ ▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▄▀▀ +┃ ▄▄▀ +┃ ▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀▀ +┃ ▄▄▄▀▀▀ +┃▄▄▄▄▄▄▄▄▄▄▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# bezier (out) +┃ ▄▄▄▀▀▀▀▀▀▀▀▀ +┃ ▄▄▄▀▀▀ +┃ ▄▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀ +┃ ▄▀▀ +┃ ▄▄▀▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃▄▄▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# bezier (in_out) +┃ ▄▄▄▀▀▀▀▀▀ +┃ ▄▄▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▀▀ +┃▄▄▄▄▄▄▄▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +`:linear` + +``` +# linear (in) +┃ ▄▄▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃▄▄▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# linear (out) +┃ ▄▄▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃▄▄▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# linear (in_out) +┃ ▄▄▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃▄▄▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +`:parametric` + +``` +# parametric (in) +┃ ▄ +┃ ▄▀ +┃ ▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▄▀▀ +┃ ▄▄▄▄▀▀ +┃▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# parametric (out) +┃ ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀▀▀▀ +┃ ▄▄▀▀▀▀ +┃ ▄▄▀▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀ +┃ ▄▀ +┃▄▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# parametric (in_out) +┃ ▄▄▄▀▀▀▀▀▀▀▀▀ +┃ ▄▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀▀ +┃▄▄▄▄▄▄▄▄▄▄▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +`:quadratic` + +``` +# quadratic (in) +┃ ▄▄ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▄▀▀ +┃ ▄▄▄▀▀▀ +┃▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# quadratic (out) +┃ ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀ +┃ ▄▄▄▀▀▀ +┃ ▄▄▀▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃▄▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +``` +# quadratic (in_out) +┃ ▄▄▄▀▀▀▀▀▀▀ +┃ ▄▄▀▀▀ +┃ ▄▀▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀ +┃ ▄▀▀ +┃ ▄▄▀ +┃ ▄▄▀ +┃ ▄▄▄▀▀ +┃▄▄▄▄▄▄▄▄▀▀▀ +┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### Full template example + ```ruby class TemplateFactory def build(frame, args) set_state(frame, args) WhirledPeas.template do |composer, settings| @@ -838,19 +1115,18 @@ Usage: screen_test [file] [options] If not file or options are provide, all tests are run If no file is provided, the supported options are ---help print this usage statement and exit ---view-pending interactively display and optionally save rendered output for each pending test ---view-failed interactively display and optionally save rendered output for each faiing test + --help print this usage statement and exit + --view-pending interactively display and optionally save rendered output for each pending test + --view-failed interactively display and optionally save rendered output for each faiing test -If the file provide is a screen test, the supported options are ---run run screen test for given file ---view interactively display and optionally save the file's test output ---template print out template tree for the test template ---debug render the test template without displying it, printing out debug information - +If a screen test file is provided as the first argument, the supported options are + --run run screen test for given file + --view interactively display and optionally save the file's test output + --template print out template tree for the test template + --debug render the test template without displying it, printing out debug information ``` ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/whirled_peas. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/whirled_peas/blob/master/CODE_OF_CONDUCT.md).