whirled_peas 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a2a839ef0ed84dd94f346be47c38d65c0d23b6faa399abdf8f56023138788a4
-  data.tar.gz: 04a43d7c60d2e3896adea98036012bdba20448ecdf530947b72ca535ee5c3464
+  metadata.gz: 46a66b5e575d80b9e99cd263d8158ece7f500aebfc853df72bd340b7b67a0787
+  data.tar.gz: 6a097ab19829f97957eff088dab8aed0241b0d68a79a43681883a07e2a897790
 SHA512:
-  metadata.gz: dfff87fa6a87ed784b35b400ad9ac737508b4ded1e791840a3a3194a0ef22eae1ad517c9f8db9459b929e37ce132cfa97662f85762b0b02df691f58ececa7d19
-  data.tar.gz: 504e279d386d56d3b476220c4f8a015134c446b7a0cdcebc5c65db50ee750f48ce2b8b5e6a72ce0d3844bdca916f832230b7974dfdd5d982140b8bc15db003c6
+  metadata.gz: '093f92c928d2dda04cabe54d4bcc627f3083fcc1e1b68ceb413dc2ffcfa3e1f73427a91f9e5d1fee8992fcc1e88f601984e5e04f8b0a58183c5b44ac5e4d2c27'
+  data.tar.gz: '0300822358c0ceaeba6c998cbff96ac1c2d94198cc639062e77cfe041132630f94f8dd4ef56a6de45838b068480f0a8ebcc40c23c2b1a5e315ce990ead06ca93'

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## v0.5.0 - 2021-01-25
+## v0.7.0 - 2021-01-27
+
+BREAKING: the settings for the template now fills the full screen and disallows margin.
+
+- [b7c12c2](https://github.com/tcollier/whirled_peas/tree/b7c12c2c34d7077b9c2496d05ddd0c6d1eb90699): Update template to fill full screen with border sizing
+- [963b819](https://github.com/tcollier/whirled_peas/tree/963b8196f0d046ba03c893f07e5578bf8c88b7a3): Implement vertical alignment
+- [4bddd54](https://github.com/tcollier/whirled_peas/tree/4bddd54bec5c8f93d145c285379c1816f313f35e): Add `between`, `around`, and `evenly` alignments
+
+## v0.6.0 - 2021-01-25
 
 - [73df2af](https://github.com/tcollier/whirled_peas/tree/73df2af1f1eac37fe94f720dce16da1ed568dade): Add support for scroll bars along both axes
 - [f4f44e1](https://github.com/tcollier/whirled_peas/tree/f4f44e1ff6c75ed03cd682e3fa9921401dcd2d00): Implement remaining 3 flow directions for grids

data/README.md

@@ -172,7 +172,12 @@ To render the frame events sent by the driver, the application requires a templa
 
 #### Building Blocks
 
-A template is created with `WhirledPeas.template`, which yields a `Composer` object for a `Box` and `BoxSettings`. The composer allows for attaching child elements and the settings for setting layout options.
+A template is created with `WhirledPeas.template`, which yields a `Composer` object for a `Box` and `BoxSettings`. The composer allows for attaching child elements and the settings for setting layout options. The following attributes of the template's settings will be overridden before it is rendered to ensure that it fills the screen exactly
+
+- `margin` - all margin will be set to 0
+- `width` - will be set to the screen's width
+- `height` - will be set to the screen's height
+- `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).
 
@@ -239,23 +244,211 @@ end
 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 (allowed values: `:left`, `:center`, `:right`)            | `:left` | `Box`, `Grid`         | Yes                  |
-| `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`         | Yes                  |
-| `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                   |
-| `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                   |
+| 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`/`hieght` | `: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                   |
+
+##### Alignment
+
+The `align` setting takes one of several values
+
+- `:left` - align content starting at the leftmost edge of the container's content area
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃[child 1][child 2][child 3]            ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+- `:right` - align content starting at the rightmost edge of the container's content area
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃            [child 1][child 2][child 3]┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+- `:center` - align content starting in the horizontal center of the container's content area
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃      [child 1][child 2][child 3]      ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+- `:between` - distribute children so there is equal space between children no space outside of the children
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃[child 1]      [child 2]      [child 3]┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+- `:around` - distribute children so that they have equal spacing around them, space between two children is twice the space between an edge and a child.
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  [child 1]    [child 2]    [child 3]  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+- `:evenly` - distribute children so there is even spacing between any two children (or space to the edge)
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃   [child 1]   [child 2]   [child 3]   ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+The `valign` setting takes one of several values
+
+- `:top` - align content starting at the top of the container's content area
+
+```
+┏━━━━━━━━━┓
+┃[child 1]┃
+┃[child 2]┃
+┃[child 3]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┗━━━━━━━━━┛
+```
+
+- `:bottom` - align content starting at the bottom of the container's content area
+
+```
+┏━━━━━━━━━┓
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 1]┃
+┃[child 2]┃
+┃[child 3]┃
+┗━━━━━━━━━┛
+```
+
+- `:middle` - align content starting in the vertical middle of the container's content area
+
+```
+┏━━━━━━━━━┓
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 1]┃
+┃[child 2]┃
+┃[child 3]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┗━━━━━━━━━┛
+```
+
+- `:between` - distribute children so there is equal space between children no space outside of the children
+
+```
+┏━━━━━━━━━┓
+┃[child 1]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 2]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 3]┃
+┗━━━━━━━━━┛
+```
+
+- `:around` - distribute children so that they have equal spacing around them, space between two children is twice the space between an edge and a child.
+
+```
+┏━━━━━━━━━┓
+┃         ┃
+┃         ┃
+┃[child 1]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 2]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 3]┃
+┃         ┃
+┃         ┃
+┗━━━━━━━━━┛
+```
+
+- `:evenly` - distribute children so there is even spacing between any two children (or space to the edge)
+
+```
+┏━━━━━━━━━┓
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 1]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 2]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┃[child 3]┃
+┃         ┃
+┃         ┃
+┃         ┃
+┗━━━━━━━━━┛
+```
 
 ##### Position
 
@@ -263,11 +456,56 @@ Position settings dictate the relative position from where the painter would hav
 
 - `set_position(left:, top:)`
 
+##### Sizing Model
+
+The sizing model determines how to interpret the `width` and `height` settings. The default sizing model is `:content`, which sets the width and height of the cotent area, whereas `:border` sets the width and height of the element inlcuding the padding and border and scroll bars.
+
+###### Examples
+
+In the examples below, the `~` character represents padding and would not be displayed in the acutal rendered screen.
+
+```ruby
+settings.width = 10
+settings.height = 3
+settings.set_padding(left: 3, top: 1, right: 3, bottom: 1)
+settings.full_border
+
+## Content sizing
+settings.sizing = :content
+
+# Results in the box
+#
+#   ┏━━━━━━━━━━━━━━━━┓
+#   ┃~~~~~~~~~~~~~~~~┃
+#   ┃~~~1234567890~~~┃
+#   ┃~~~1234567890~~~┃
+#   ┃~~~1234567890~~~┃
+#   ┃~~~~~~~~~~~~~~~~┃
+#   ┗━━━━━━━━━━━━━━━━┛
+
+## Border sizing
+settings.sizing = :border
+
+# Results in the box
+#
+#   ┏━━━━━━━━┓
+#   ┃~~~12~~~┃
+#   ┗━━━━━━━━┛
+```
+
+Notice that a box rendered with `:border` sizing would fit exactly in the content area of a box with the same `width` and `height` that is rendered with `:content` sizing. For containers with no padding and no border, the resulting size is the same for either sizing model.
+
 ##### Margin
 
 Margin settings dictate the spacing on the outside (i.e. outside of the border) of each of the 4 sides of the container independently. To set these values, use
 
-- `set_margin(left:, top:, right:, bottom:)`
+- `set_margin(left:, top:, right:, bottom:, horiz:, vert:)` - set any combination of margin (note: setting `horiz` and `left`/`right` or setting `vert` and `top`/`bottom` is not allowed)
+- `margin.left=(value)` - set left margin
+- `margin.top=(value)` - set top margin
+- `margin.right=(value)` - set right margin
+- `margin.bottom=(value)` - set bottom margin
+- `margin.horiz=(value)` - set left and right margin to the same value
+- `margin.vert=(value)` - set top and bottom margin to the same value
 
 Note: values cannot be negative
 
@@ -275,7 +513,13 @@ Note: values cannot be negative
 
 Padding settings dictate the spacing on the inside (i.e. inside of the border) of each of the 4 sides of the container independently. To set these values, use
 
-- `set_padding(left:, top:, right:, bottom:)`
+- `set_padding(left:, top:, right:, bottom:, horiz:, vert:)` - set any combination of padding (note: setting `horiz` and `left`/`right` or setting `vert` and `top`/`bottom` is not allowed)
+- `padding.left=(value)` - set left padding
+- `padding.top=(value)` - set top padding
+- `padding.right=(value)` - set right padding
+- `padding.bottom=(value)` - set bottom padding
+- `padding.horiz=(value)` - set left and right padding to the same value
+- `padding.vert=(value)` - set top and bottom padding to the same value
 
 Note: values cannot be negative
 
@@ -283,14 +527,24 @@ Note: values cannot be negative
 
 Scroll settings dictate whether the scrollbar will be shown when child content is larger the the container's viewport. A scrollbar adds a unit to the dimensions of a container (as opposed to overwriting the leftmost/bottommost padding)
 
-- `set_padding(horiz:, vert:)`
+- `set_scrollbar(horiz:, vert:)` - set both scrollbar settings
+- `scrollbar.horiz=(flag)` - show/hide the horizontal scrollbar
+- `scrollbar.vert=(flag)` - show/hide the vertical scrollbar
 
 ##### Border
 
 The border settings consist of 6 boolean values (border are either width 1 or not shown), the 4 obvious values (`left`, `top`, `right`, and `bottom`) along with 2 other values for inner borders (`inner_horiz` and `inner_vert`) in a grid. A border also has a foreground color (defaults to `:white`) and a style. The background color is determined by the `bg_color` of the element. Border values can be set with
 
-- `set_border(left:, top:, right:, bottom:, inner_horiz:, inner_vert:, color:, style:)`
-- `full_border(style:, color:)`
+- `set_border(left:, top:, right:, bottom:, inner_horiz:, inner_vert:, color:, style:)` - set any combination of border settings
+- `full_border(style:, color:)` - set all borders to true and optionally set the style or color
+- `border.left=(flag)` - show/hide left border
+- `border.top=(flag)` - show/hide top border
+- `border.right=(flag)` - show/hide right border
+- `border.bottom=(flag)` - show/hide bottom border
+- `border.inner_horiz=(flag)` - show/hide inner horizontal border (dividing grid rows)
+- `border.inner_vert=(flag)` - show/hide inner vertical border (dividing grid columns)
+- `border.color=(flag)` - set the border color
+- `border.style=(flag)` - set the border style
 
 Available border styles are
 
@@ -332,52 +586,70 @@ Child elements can flow in one of 4 directions
 
 ```
 # In a Box
-[child 1] [child 2] ... [child N]
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃[child 1] [child 2] ... [child N]┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 # In a Grid
-[child 1] [child 2] [child 3]
-[chiid 4] [child 5]
+┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃[child 1]┃[child 2]┃[child 3]┃
+┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
+┃[chiid 4]┃[child 5]┃         ┃
+┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
 ```
 
 - `:r2l` right-to-left
 
 ```
 # In a Box
-[child N] [child N - 1] ... [child 1]
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃[child N] [child N - 1] ... [child 1]┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 # In a Grid
-[child 3] [child 2] [child 1]
-          [chiid 5] [child 4]
+┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃[child 3]┃[child 2]┃[child 1]┃
+┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
+┃         ┃[chiid 5]┃[child 4]┃
+┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
 ```
 
 - `:t2b` top-to-bottom
 
 ```
 # In a Box
-[child 1]
-[child 2]
- ...
-[child N]
+┏━━━━━━━━━┓
+┃[child 1]┃
+┃[child 2]┃
+┃ ...     ┃
+┃[child N]┃
+┗━━━━━━━━━┛
 
 # In a Grid
-[child 1] [child 4]
-[child 2] [child 5]
-[child 3]
+┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃[child 1]┃[child 3]┃[child 5]┃
+┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
+┃[child 2]┃[child 4]┃         ┃
+┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
 ```
 
 - `:b2t` bottom-to-top
 
 ```
 # In a Box
-[child N]
-[child N - 1]
- ...
-[child 1]
+┏━━━━━━━━━━━━━┓
+┃[child N]    ┃
+┃[child N - 1]┃
+┃ ...         ┃
+┃[child 1]    ┃
+┗━━━━━━━━━━━━━┛
 
 # In a Grid
-[child 3]
-[child 2] [child 5]
-[child 1] [child 4]
+┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃[child 2]┃[child 4]┃         ┃
+┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
+┃[child 1]┃[child 3]┃[child 5]┃
+┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
 ```
 
 ##### Colors