README.md in whirled_peas-0.10.0 vs README.md in whirled_peas-0.11.0
- old
+ new
@@ -243,42 +243,98 @@
template.add_box do
"Hello!"
end
```
+#### Components
+
+A component is a composition of the core building blocks. This gem includes a handful of components and third parties can also add components using `WhirledPeas.register_component(name, component_class)` (the convention for `name` is a snake cased symbol). A component class must be constructed with no arguments, though can supply basic setters to allow for customizations. A component must also implement `#compose(composer, settings)`, which should attach elements to the composer. Thus a template can integrate with the component like
+
+```ruby
+WhirledPeas.template do |composer, settings|
+ # Attach the component registered with the name `:my_component` to the template
+ WhirledPeas.component(composer, settings, :my_component) do |component|
+ # Configure the component
+ end
+end
+```
+
+##### `:list_with_active`
+
+This component presents a list of content (either horizontally of vertically) and places the item specified by `active_index` in the preferred position.
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ green, blue, *indigo*, viole┃
+┃ ▗▄▄▄▄▄▄▄▄▄▄▄▄▄▄▖ ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+Note: in the diagram above, the item specified by the active index is highlighted with `*`s, these are for illustration onlhy. The component can highlight the item with a color and/or background color, but will _not_ add the `*`s.
+
+This component takes the following options
+
+**Required**
+
+- `active_index` - the index of the active item
+- `items` - the array of items to be displayed in the box
+
+**Optional**
+
+- `active_bg_color` - background color of the active item
+- `active_color` - text color of the active item
+- `flow` - `:l2r` or `:t2b`
+- `separator` - string used to separate items in the list, e.g. `", "` for a horizontal list or `"----"` for a vertical list
+- `viewport_size` - number of characters of the viewport in the flow direction
+
+**Example**
+
+```ruby
+WhirledPeas.template do |composer, settings|
+ WhirledPeas.component(composer, settings, :list_with_active) do |component|
+ component.items = %w[red orange yellow green blue indigo violet]
+ component.separator = ', '
+ component.active_index = active
+ component.viewport_size = 27
+ component.active_color = :blue
+ component.active_bg_color = :bright_yellow
+ end
+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 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` | 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 | 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` | 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` | 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` | 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` | containers | No |
+| Setting | Description | Default | Availability | Inherited |
+| --------------- | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- |
+| `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 | 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` | 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` | 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` | containers | No |
+| `content_start` | Set the (left, top, right, bottom) position of children | `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` | 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|
+WhirledPeas.register_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
@@ -471,14 +527,22 @@
┃ ┃
┃ ┃
┗━━━━━━━━━┛
```
-##### Position
+##### Content Start
-Position settings dictate the relative position from where the painter would have preferred to place the container. Negative numbers move the container left/up and positive numbers move it right/down. To set these values, use
+Content start settings dictate the relative position from the content area where the children will get painted. Positive values for `left`/`top` result in moving the children leftward/downward, negative values shift children rightward/upward. Setting `right` or `bototm` will result in the end of the children to be painted relative to the right/bottom of the content area.
-- `set_position(left:, top:)`
+To set these values, use
+
+- `set_content_start(left:, top:, right:, bottom:)`
+- `content_start.left=`
+- `content_start.top=`
+- `content_start.right=`
+- `content_start.bottom=`
+
+Note: setting `left` and `right` or `top` and `bottom` is not supported
##### 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.