View Source Owl.ProgressBar (Owl v0.12.0)

A live progress bar widget.

Single bar

Owl.ProgressBar.start(id: :users, label: "Creating users", total: 1000)

Enum.each(1..1000, fn _ ->
  Process.sleep(10)
  Owl.ProgressBar.inc(id: :users)
end)

Owl.LiveScreen.await_render()

Multiple bars

1..10
|> Enum.map(fn index ->
  Task.async(fn ->
    range = 1..Enum.random(100..500)

    label = "Demo Progress ##{index}"

    Owl.ProgressBar.start(
      id: {:demo, index},
      label: label,
      total: range.last,
      timer: true,
      bar_width_ratio: 0.3,
      filled_symbol: "#",
      partial_symbols: []
    )

    Enum.each(range, fn _ ->
      Process.sleep(Enum.random(10..50))
      Owl.ProgressBar.inc(id: {:demo, index})
    end)
  end)
end)
|> Task.await_many(:infinity)

Owl.LiveScreen.await_render()

Summary

Types

id()

Functions

inc(opts \\ [])

Increases current value by step.

render(params)

Renders a progress bar that can be consumed by Owl.IO.puts/2.

start(opts)

Starts a progress bar on Owl.LiveScreen.

Types

id()

@type id() :: any()

Functions

inc(opts \\ [])

@spec inc(id: id(), step: integer()) :: :ok

Increases current value by step.

When current value becomes equal to total, then progress bar terminates.

Options

:id - an required identifier of the progress bar.
:step - a value by which current value should be increased. Defaults to 1.

Examples

Owl.ProgressBar.inc(id: "Creating users")

Owl.ProgressBar.inc(id: "Creating users", step: 10)

render(params)

@spec render(%{
  optional(:current_time) => nil | integer(),
  optional(:start_time) => nil | integer(),
  optional(:screen_width) => nil | pos_integer(),
  optional(:absolute_values) => nil | boolean(),
  bar_width_ratio: float(),
  label: Owl.Data.t(),
  total: pos_integer(),
  current: non_neg_integer(),
  start_symbol: Owl.Data.t(),
  end_symbol: Owl.Data.t(),
  filled_symbol: Owl.Data.t(),
  partial_symbols: [Owl.Data.t()],
  empty_symbol: Owl.Data.t()
}) :: Owl.Data.t()

Renders a progress bar that can be consumed by Owl.IO.puts/2.

Used as a callback for blocks in Owl.LiveScreen.

Examples

iex> Owl.ProgressBar.render(%{
...>   label: "Demo",
...>   total: 200,
...>   current: 60,
...>   bar_width_ratio: 0.7,
...>   start_symbol: "[",
...>   end_symbol: "]",
...>   filled_symbol: "#",
...>   partial_symbols: [],
...>   empty_symbol: ".",
...>   screen_width: 40
...> }) |> to_string()
"Demo      [######.................]  30%"

iex> Owl.ProgressBar.render(%{
...>   label: "Demo",
...>   total: 200,
...>   current: 8,
...>   bar_width_ratio: 0.2,
...>   start_symbol: "|",
...>   absolute_values: true,
...>   end_symbol: "|",
...>   filled_symbol: "█",
...>   partial_symbols: ["▏", "▎", "▍", "▌", "▋", "▊", "▉"],
...>   empty_symbol: " ",
...>   screen_width: 40,
...>   start_time: -576460748012758993,
...>   current_time: -576460748012729828
...> }) |> to_string()
"Demo         8/200 00:29.2 |▎     |   4%"

iex> Owl.ProgressBar.render(%{
...>   label: "Demo",
...>   total: 200,
...>   current: 8,
...>   bar_width_ratio: 0.7,
...>   start_symbol: "[",
...>   end_symbol: "]",
...>   filled_symbol: Owl.Data.tag("≡", :cyan),
...>   partial_symbols: [Owl.Data.tag("-", :green), Owl.Data.tag("=", :blue)],
...>   empty_symbol: " ",
...>   screen_width: 40
...> })|> Owl.Data.to_chardata() |> to_string()
"Demo      [[34m=[39m                      ]   4%[0m"

iex> Owl.ProgressBar.render(%{
...>   label: "Demo",
...>   total: 200,
...>   current: 60,
...>   bar_width_ratio: 0.95,
...>   start_symbol: "[",
...>   end_symbol: "]",
...>   filled_symbol: "#",
...>   partial_symbols: [],
...>   empty_symbol: ".",
...>   screen_width: 40
...> }) |> to_string()
"D…[#########......................]  30%"

iex> Owl.ProgressBar.render(%{
...>   label: "Demo",
...>   total: 200,
...>   current: 60,
...>   bar_width_ratio: 1,
...>   start_symbol: "[",
...>   end_symbol: "]",
...>   filled_symbol: "#",
...>   partial_symbols: [],
...>   empty_symbol: ".",
...>   screen_width: 40
...> }) |> to_string()
"[#########........................]  30%"

start(opts)

@spec start(
  label: Owl.Data.t(),
  id: id(),
  total: pos_integer(),
  timer: boolean(),
  absolute_values: boolean(),
  current: non_neg_integer(),
  bar_width_ratio: nil | float(),
  start_symbol: Owl.Data.t(),
  end_symbol: Owl.Data.t(),
  filled_symbol: Owl.Data.t(),
  partial_symbols: [Owl.Data.t()],
  empty_symbol: Owl.Data.t(),
  screen_width: pos_integer(),
  live_screen_server: GenServer.server()
) :: DynamicSupervisor.on_start_child()

Starts a progress bar on Owl.LiveScreen.

Options

:id - an id of the progress bar. Required.
:label - a label of the progress bar. Required.
:total - a total value. Required.
:current - a current value. Defaults to 0.
:bar_width_ratio - a bar width ratio. Defaults to 0.7.
:timer - set to true to launch a timer and display it before the bar in format MM:SS. Defaults to false.
:absolute_values - set to true to show absolute values before the bar in format current/total. Defaults to false.
:start_symbol - a symbol that is rendered at the beginning of the progress bar. Defaults to "[".
:end_symbol - a symbol that rendered at the end of the progress bar. Defaults to "]".
:filled_symbol - a symbol that use used when current value is big enough to fill the cell. Defaults to "≡"
:partial_symbols - a list of symbols that are used when current value is too small to render filled_symbol. Defaults to ["-", "="].
:empty_symbol - an empty symbol. Defaults to " ".
:screen_width - a width of output data. Defaults to width of the terminal or 80 symbols, if a terminal is not available.
:live_screen_server - a reference to Owl.LiveScreen server. Defaults to Owl.LiveScreen.