Drafter.Widget.Rule (drafter v0.3.1)

Renders a horizontal or vertical divider line, optionally with an embedded title.

Component tag

Tag :rule, built by Drafter.App as {:rule, opts}:

rule(opts)

There is no positional argument; every prop comes from opts.

Options

:orientation - :horizontal | :vertical. Default :horizontal. Any other value raises a CaseClauseError from render/2.
:title - String.t/0 embedded in a horizontal rule, or nil. Default nil. Ignored when the orientation is :vertical. A title that is as wide as the rect, once padded with a space on each side, is truncated and no line characters are drawn.
:title_align - :left | :center | :right. Default :center. Only read when :title is set.
:line_style - :solid | :double | :dashed | :thick. Default :solid. Selects ─ ═ ╌ ━ horizontally and │ ║ ╎ ┃ vertically. Any other value raises a KeyError from render/2.
:style - map/0 of style overrides merged over the computed theme style. Default %{}.
:height - pos_integer/0 read only by preferred_height/2, never by mount/1. Default 1.

Every option except :height is live-updatable: update/2 folds each recognised key into the state and update_props_from_mount/3 passes the full mount props through.

Usage

rule()
rule(title: "Section", line_style: :double)
rule(orientation: :vertical)

Summary

Functions

component_tag()

The component tag this widget registers under.

focused(state)

from_component_opts(args, opts)

Builds the props map for a {:rule, opts} element.

handle_event(event, state)

Ignores every event and returns {:noreply, state}. The rule is not focusable.

mount(props)

Builds the widget state from props.

preferred_height(args, opts)

The number of rows the element asks for: opts[:height], default 1.

render(state, rect)

Draws the rule into rect.

unmount(state)

Callback implementation for Drafter.Widget.unmount/1.

update(props, state)

Folds props into state, one key at a time.

update_props_from_mount(mount_props, existing_state, opts)

Passes the mount props through unchanged, so every option is live-updatable through the component tree.

Types

t()

@type t() :: %Drafter.Widget.Rule{
  app_module: module() | nil,
  line_style: :solid | :double | :dashed | :thick,
  orientation: :horizontal | :vertical,
  style: map(),
  title: String.t() | nil,
  title_align: :left | :center | :right
}

Functions

component_tag()

@spec component_tag() :: :rule

The component tag this widget registers under.

iex> Drafter.Widget.Rule.component_tag()
:rule

focused(state)

from_component_opts(args, opts)

@spec from_component_opts(
  term(),
  keyword()
) :: Drafter.Widget.props()

Builds the props map for a {:rule, opts} element.

The positional argument is ignored. :__app_module__ becomes :app_module; every other option keeps its name and the default stated in the module doc.

iex> Drafter.Widget.Rule.from_component_opts(nil, [])
%{orientation: :horizontal, title: nil, title_align: :center, style: %{}, line_style: :solid, app_module: nil}

iex> Drafter.Widget.Rule.from_component_opts(nil, title: "Section", title_align: :left).title_align
:left

handle_event(event, state)

@spec handle_event(Drafter.Event.t(), t()) :: {:noreply, t()}

Ignores every event and returns {:noreply, state}. The rule is not focusable.

mount(props)

@spec mount(Drafter.Widget.props()) :: t()

Builds the widget state from props.

Reads :orientation (default :horizontal), :title (default nil), :title_align (default :center), :style (default %{}), :line_style (default :solid) and :app_module (default nil).

iex> Drafter.Widget.Rule.mount(%{})
%Drafter.Widget.Rule{orientation: :horizontal, title: nil, title_align: :center, style: %{}, line_style: :solid, app_module: nil}

iex> Drafter.Widget.Rule.mount(%{title: "Section", line_style: :double}).line_style
:double

preferred_height(args, opts)

@spec preferred_height(
  term(),
  keyword()
) :: pos_integer()

The number of rows the element asks for: opts[:height], default 1.

iex> Drafter.Widget.Rule.preferred_height(nil, [])
1

iex> Drafter.Widget.Rule.preferred_height(nil, height: 3)
3

render(state, rect)

@spec render(t(), Drafter.Widget.rect()) :: [Drafter.Draw.Strip.t()]

Draws the rule into rect.

A horizontal rule returns rect.height strips with the line on row div(rect.height, 2) and blanks elsewhere. A vertical rule returns rect.height strips each holding the line character followed by rect.width - 1 spaces, or [] when rect.width is not positive.

unmount(state)

Callback implementation for Drafter.Widget.unmount/1.

update(props, state)

@spec update(Drafter.Widget.props() | keyword(), t()) :: t()

Folds props into state, one key at a time.

Recognises :orientation, :title, :title_align, :style, :line_style and :app_module; any other key is ignored and leaves the state untouched. props may be a map or a keyword list.

iex> state = Drafter.Widget.Rule.mount(%{})
iex> Drafter.Widget.Rule.update(%{title: "New", unknown: 1}, state).title
"New"

update_props_from_mount(mount_props, existing_state, opts)

@spec update_props_from_mount(Drafter.Widget.props(), term(), keyword()) ::
  Drafter.Widget.props()

Passes the mount props through unchanged, so every option is live-updatable through the component tree.

iex> props = Drafter.Widget.Rule.from_component_opts(nil, title: "Section")
iex> Drafter.Widget.Rule.update_props_from_mount(props, %{}, []) == props
true