Drawing and theming

How rubbs puts colour and characters on the screen: BBS::Theme (every preset and every role key), the BBS::Ansi palette, the BBS::FrameBuffer that the Application draws into and diffs, BBS::Renderer for ERB screens in a flow, BBS::Banner, and BBS::Markdown, which turns Markdown into ANSI lines. Widgets that use all this are on Widgets. Everything here is checked against rubbs 1.0.0.

Themes

How a theme works

A BBS::Theme (lib/bbs/theme.rb) is a name and a Hash that maps role keys to ANSI SGR strings. Widgets never hard-code colours; they ask for a role (:button_focused, :window_title, :listbox_selected…) and draw with whatever SGR the theme gives. Switching the theme recolours the whole application.

BBS::Theme.new(name, styles)

A theme is frozen: change it with merge, which gives a new one. A role the Hash leaves out is not an error: the cell gets a nil style, and FrameBuffer#diff writes it after a plain \e[0m reset, so it shows in the terminal's default colours.

require 'bbs'

t = BBS::Theme.synchronet
p t[:accent]                          # => "\e[1;33;40m"
p t.style(:no_such_role)              # => nil
cyan = t.merge(accent: "\e[1;36;40m")
p [cyan.name, cyan[:accent]]          # => [:synchronet, "\e[1;36;40m"]
p t.frozen?                           # => true
t.merge(check_on: "\e[1;32m")         # ArgumentError: unknown theme roles: [:check_on]

Presets

The presets are data: one Hash each in BBS::Theme::PRESETS (lib/bbs/theme/presets.rb), and BBS::Theme.fetch(:name) builds one; the five class methods below are shorthands for it. The application uses synchronet when none is given (or BBS.config.theme, when set).

Role keys

Theme::ROLES: every key the presets define (all five define all of them), what draws with it in rubbs 1.0.0, and its synchronet value. Keys marked "not used by the gem" are there for your own widgets and screens. 1.0 dropped the roles nothing drew with: check_on, check_off, listbox_header, warning and reset.

Each SGR value in the presets starts with the background as well as the foreground (37;40, 37;44), and most start with 0;, so a style never inherits bold or dim from the cell drawn before it. Do the same in your own values.

Choosing a theme for an application

In the BBS::Application.define block, theme takes a theme instance or a preset name, or either of them plus a block of overrides:

require 'bbs'

APP = BBS::Application.define do
  theme BBS::Theme.nortoncommander
end

In 0.17.0 the bare Symbol form (theme :synchronet) stored the Symbol itself and crashed the first redraw with a TypeError, and APP.theme without arguments reset the stored theme; since 0.17.1 the Symbol takes the preset, and theme without arguments on the builder returns the theme set so far (nil when there was no theme call, which means synchronet).

Inside the application, theme returns the BBS::Theme in use, which is what you pass to BBS::Markdown.to_lines or use for a coloured string of your own:

helpers do
  def warn_line(text) = "#{theme[:error]}#{text}#{theme[:text]}"
end

Overriding keys

Inside a theme block every call with one argument sets that key; style(key, value) is the explicit form, and inherit switches the base the overrides are applied to:

require 'bbs'

APP = BBS::Application.define do
  theme :nortoncommander do
    inherit :neumanntronics              # optional: take another preset as the base
    window_border "\e[1;36;44m"
    accent        "\e[1;33;44m"
    style :screen, "\e[40m"
  end
end

Without the DSL, merge does the same:

require 'bbs'

custom = BBS::Theme.synchronet.merge(
  accent:         "\e[1;36;40m",
  button_focused: "\e[1;37;44m"
)

A theme of your own

Build a BBS::Theme from a full Hash. The simplest way to get every key is to start from a preset's Hash in Theme::PRESETS:

require 'bbs'

AMBER = BBS::Theme.new(:amber, BBS::Theme::PRESETS[:mono].merge(
  screen:           "\e[40m",
  text:             "\e[0;33;40m",
  text_dim:         "\e[0;2;33;40m",
  text_bright:      "\e[1;33;40m",
  label:            "\e[0;33;40m",
  accent:           "\e[1;33;40m",
  window_bg:        "\e[40m",
  window_border:    "\e[0;33;40m",
  window_title:     "\e[1;33;40m",
  window_title_focused: "\e[0;30;43m",
  window_text:      "\e[0;33;40m",
  button:           "\e[0;30;43m",
  button_focused:   "\e[1;37;43m",
  input:            "\e[0;33;40m",
  input_focused:    "\e[0;30;43m",
  listbox:          "\e[0;33;40m",
  listbox_selected: "\e[0;30;43m",
  listbox_focused:  "\e[1;37;43m"
))

APP = BBS::Application.define do
  theme AMBER
end

The palette: BBS::Ansi

Every colour outside a theme comes from one palette, BBS::Ansi (lib/bbs/ansi.rb): a flow's styles, a line-by-line board's say, a FakeOS, a log line, a quick door. BBS::Color (Color.c(:yellow, text)) is gone since 1.0; write the constant and a reset instead.

require 'bbs'

p "#{BBS::Ansi::CYAN}hello#{BBS::Ansi::RESET}"    # => "\e[0;36mhello\e[0m"

BBS::Petscii::Colors are the C64 names of the same sequences (WH YE CY LG GR DG LB BL GN RD PU OR, RV RO for reverse on and off; see Commodore 64), and a component takes a Hash of roles in these colours: BBS::Selector::COLORS, the Flow's FlowRunner::STYLES, a FakeOS's colors. On a C64 graphics canvas the same colours turn into C64 codes: BBS::Petscii::Canvas.color(YE) == Canvas::YELLOW.

BBS::FrameBuffer

BBS::FrameBuffer (lib/bbs/frame_buffer.rb) is an off-screen grid of cells, each a character and an SGR string. The Application draws a whole frame into one, compares it with the previous frame, and sends only the difference. Widgets get one in render(frame).

Double buffering and the delta diff

Every redraw of the Application (the private render_screen) does this:

1. Make an empty next frame of the terminal's size. Keep the committed frame (what the terminal shows now); on the first draw or after a resize, start from an empty one and clear the screen.
2. Fill next with the theme's screen style, draw the desktop, the windows bottom to top, the menubar and the statusbar.
3. delta = next.diff(committed); if it is not empty, write it wrapped in cursor hide/show (\e[?25l … \e[?25h) and make next the committed frame.

So after a key press only the cells that changed travel down the line: moving a list selection costs two rows, a ticking clock a few characters. The same works by hand:

require 'bbs'

committed = BBS::FrameBuffer.new(20, 2)
nxt = BBS::FrameBuffer.new(20, 2)
nxt.move(1, 1)
nxt.write('Time: 12:00', sgr: "\e[1;33m")
p nxt.diff(committed)     # => "\e[1;1H\e[0m\e[1;33mTime: 12:00\e[0m"
committed = nxt

nxt = BBS::FrameBuffer.new(20, 2)
nxt.move(1, 1)
nxt.write('Time: 12:01', sgr: "\e[1;33m")
p nxt.diff(committed)     # => "\e[1;11H\e[0m\e[1;33m1\e[0m"   only the changed digit
p nxt.diff(nxt)           # => ""

Constants

Class methods for ANSI strings

These work on strings that contain SGR escapes, counting only the visible characters. An escape sequence is what BBS::Ansi::CSI_RE matches (/\e\[[\d;?]*[A-Za-z~]/: SGR, cursor moves, \e[2~-style keys, and since 1.0 private-mode sequences such as \e[?25l); it replaces the FrameBuffer::ANSI_ESC_RE of 0.x.

require 'bbs'

fb = BBS::FrameBuffer
p fb.plain("\e[?25l\e[1;33mbright\e[0m")           # => "bright"
p fb.visible_width("\e[1;33mbright\e[0m normal")    # => 13
p fb.clip_ansi("\e[1;33mbright\e[0m normal", 4)     # => "\e[1;33mbrig"
p fb.wrap_ansi("\e[1;32mthe quick brown fox jumps\e[0m over", 10)
# => ["\e[1;32mthe quick", "\e[1;32mbrown fox", "\e[1;32mjumps\e[0m over"]
p fb.wrap_ansi('anextremelylongword here', 8)       # => ["anextremelylongword", "here"]
p fb.text("ok\xFFok")                               # => "ok?ok"

Drawing

All coordinates are 1-based columns and rows, like the terminal's. Anything outside the frame is clipped, at any edge, so you can draw partly off-screen safely.

write_ansi interprets the escapes the way a terminal would, inside the frame:

• An SGR sequence (\e[...m) adds to the current style; a reset (\e[0m or \e[m) returns to base_sgr, not to "no style". This is how a coloured word inside a blue window keeps the blue background after it.
• \e[NC (cursor forward) writes N spaces in the current style, as ANSI art uses it.
• Every other CSI sequence is dropped, cursor moves (\e[ROW;COLH) included, so text inside a widget cannot jump out of it; the cursor: option of 0.x is gone. Control characters are dropped too (including \n and \r): one call writes one line.

require 'bbs'

fb = BBS::FrameBuffer.new(20, 4)
fb.move(1, 1)
fb.write('Hello', sgr: "\e[1;33m")
fb.move(18, 1)
fb.write('clipped')                                        # only "cli" fits
fb.move(1, 2)
fb.write_ansi("a\e[1mb\e[0mc\e[3Cd", base_sgr: "\e[44m")   # styles: 44 / 44+bold / 44, three spaces, d
fb.move(1, 3)
fb.write_ansi("x\e[4;10Hy")                                # H ignored: "xy"

The resulting frame:

Hello            cli
abc   d
xy

A framed panel on a patterned background, with its shadow:

require 'bbs'

fb = BBS::FrameBuffer.new(32, 9)
fb.fill(x: 1, y: 1, width: 32, height: 9, sgr: "\e[44m", char: '░')
fb.box(x: 3, y: 2, width: 24, height: 6, sgr: "\e[1;37;44m", fill_sgr: "\e[44m",
       style: :double, title: 'Inbox', title_sgr: "\e[1;33;44m", title_indent: 4)
fb.shadow(x: 3, y: 2, width: 24, height: 6)
fb.hline(x: 4, y: 4, length: 22)
fb.vline(x: 15, y: 5, length: 2)
fb.move(5, 3)
fb.write('3 new messages', sgr: "\e[0;37;44m")

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░╔═════ Inbox═══════════╗░░░░░░
░░║ 3 new messages       ║  ░░░░
░░║──────────────────────║  ░░░░
░░║           │          ║  ░░░░
░░║           │          ║  ░░░░
░░╚══════════════════════╝  ░░░░
░░░░                        ░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Character width

The frame buffer counts one cell per Ruby character. That is right for ASCII, Latin letters with precomposed accents, box drawing, block and braille characters, which is everything the gem itself draws. It is wrong for:

• wide characters (CJK, most emoji): stored in one cell but shown in two columns by the terminal, so the rest of the line shifts right by one per character;
• combining marks (e plus U+0301): counted as two cells but shown in one.

visible_width, clip_ansi, wrap_ansi and Markdown tables count the same way. Normalise text to NFC (text.unicode_normalize(:nfc)) and keep wide characters out of anything that has to line up.

BBS::Renderer: ERB screens

BBS::Renderer (lib/bbs/renderer.rb) renders an ERB template into a string for a sequential, flow-style screen. It is what the Flow screen step uses (see Flow). It has nothing to do with the frame buffer: the double buffering is done by FrameBuffer#diff, described above.

BBS::Renderer.render(name, vars = {}, dir: BBS.config.screens_dir)

ERB runs with trim_mode: '-' (so -%> swallows the newline), and every \n in the result is turned into \r\n for the telnet line. The template can call these helpers:

screens/welcome.erb:

<%= clr %><%= banner 'Welcome' %>
   <%= green %>Hello <%= @username %>!<%= reset %>
<% if @new_mail > 0 -%>
   <%= yellow %>You have <%= @new_mail %> new message(s).<%= reset %>
<% end -%>

require 'bbs'

out = BBS::Renderer.render('welcome', { username: 'tasi', new_mail: 2 }, dir: 'screens')

Written to the terminal (the box and greeting bright green, the mail line bright yellow):

╔═══════════╗
║  Welcome  ║
╚═══════════╝
   Hello tasi!
   You have 2 new message(s).

BBS::Banner

The Flow banner and big_banner steps use BBS::Banner (lib/bbs/banner.rb), which returns ready-to-send strings with \r\n line ends and a two-space indent:

require 'bbs'

print BBS::Banner.render_big('BBS', font: 'small').gsub("\r\n", "\n")

    ___ ___ ___
   | _ ) _ ) __|
   | _ \ _ \__ \
   |___/___/___/

BBS::Markdown

BBS::Markdown (lib/bbs/markdown.rb) turns Markdown text into an Array of ANSI-coloured lines that fit a given width. Feed the result to a BBS::Widgets::ScrollView, an Info window with scrolling, or write the lines out yourself.

BBS::Markdown.to_lines(text, width:, theme:)

Inside an application, the usual call is:

lines = BBS::Markdown.to_lines(text, width: width - 1, theme: ctx[:app].theme)

Each styled span ends with the theme's text SGR, so the text after it gets its background back: this matters on a tinted window background. Plain paragraph lines do not start with an SGR of their own; the ScrollView draws them with text as the base style. When you write the lines straight to a session, put theme[:text] in front of each.

What it understands

A sample, rendered at width 36 with synchronet:

require 'bbs'

md = <<~MD
  # Welcome
  ## Rules
  ### Small print
  Be **nice**, *kind* and _brief_. See [the wiki](https://wiki.example) or run `help`.
  This line joins the paragraph above and wraps at the width.

  > Quoted text gets a gutter
  > on every line.

  - first item
  - second item that is long enough to wrap onto a second line
    continued here
    - nested
  1. one
  2. two

  ---

  | Name | Calls | Note |
  |:-----|------:|:----:|
  | ra   | 12    | ok   |
  | **zed** | 3 |  |
MD
lines = BBS::Markdown.to_lines(md, width: 36, theme: BBS::Theme.synchronet)
puts lines.map { |l| BBS::FrameBuffer.plain(l) }

Without the colours (in the terminal: Welcome bright white, Rules yellow, Small print cyan, nice bright white, kind and brief dim, the wiki yellow, help cyan, the bullets and numbers yellow, the rule and the table frame cyan):

Welcome
Rules
Small print
Be nice, kind and brief. See the
wiki or run help. This line joins
the paragraph above and wraps at the
width.

│ Quoted text gets a gutter
│ on every line.

• first item
• second item that is long enough to
  wrap onto a second line continued
  here
  • nested
1. one
2. two

────────────────────────────────────

┌──────┬───────┬──────┐
│ Name │ Calls │ Note │
├──────┼───────┼──────┤
│ ra   │    12 │  ok  │
│ zed  │     3 │      │
└──────┴───────┴──────┘

A table that does not fit is shrunk, then its cells are clipped (width 30):

┌──────────┬─────────────────┐
│ Door     │ Description     │
├──────────┼─────────────────┤
│ SERMO    │ An AI character │
│ Impostor │ Social deductio │
└──────────┴─────────────────┘

Limits

Checked against the source; rely on none of these working:

• A backslash does not stop emphasis. Escapes are applied after the emphasis rules, so \*not italic\* still becomes italic and the backslashes stay: the result is a backslash, a dim not italic, and a backslash. The same goes for \_x\_. An escape does work where no emphasis rule matches, e.g. 2\*3\*4 gives 2*3*4 and \# no heading gives # no heading.
• Escapes are removed inside code spans too: `a\*b` shows a*b.
• No __bold__, ~~strike~~, HTML or entities (shown as written), setext headings (=== under a line), indented code blocks, hard line breaks (two trailing spaces), or task lists (- [ ] keeps the brackets).
• Images: ![alt](src) shows ! and the alt text in the link colour.
• Nested quotes: > > x gives one gutter and a literal > x.
• Level 3 to 6 headings look the same.
• Code blocks are clipped, not wrapped; a word longer than the width is not broken.
• Wide characters count as one column (see Character width above).

See also

• rubbs — overview
• Widgets — what draws with these roles
• Application — the theme DSL in context, the run loop
• Art and graphics screens — drawings, the C64 graphics canvas
• Flow — screen, banner and big_banner steps