Rajzolás és témák

Hogyan kerül szín és karakter a képernyőre a rubbs-ban: a BBS::Theme (minden preset és minden szerepkulcs), a BBS::Ansi paletta, a BBS::FrameBuffer, amibe az Application rajzol, és amit összehasonlít, a BBS::Renderer a flow-k ERB screenjeihez, a BBS::Banner, és a BBS::Markdown, ami Markdownból ANSI-sorokat készít. Az ezekre épülő widgetek a Widgetek oldalon vannak. Minden a rubbs 1.0.0 forrásával egyeztetve.

Témák

Hogyan működik egy téma

A BBS::Theme (lib/bbs/theme.rb) egy név és egy Hash, ami szerepkulcsokat képez le ANSI SGR-stringekre. A widgetek sosem égetnek be színt: egy szerepet kérnek (:button_focused, :window_title, :listbox_selected…), és azzal az SGR-rel rajzolnak, amit a téma ad. A téma cseréje az egész applicationt átszínezi.

BBS::Theme.new(name, styles)

A téma fagyasztott: a merge-dzsel változtatsz rajta, ami újat ad. Ha a Hashből kimarad egy szerep, az nem hiba: a cella nil stílust kap, a FrameBuffer#diff pedig egy sima \e[0m reset után írja ki, így a terminál alapszíneivel jelenik meg.

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]

Presetek

A presetek adatok: mindegyik egy Hash a BBS::Theme::PRESETS-ben (lib/bbs/theme/presets.rb), és a BBS::Theme.fetch(:név) épít belőlük témát; az alábbi öt osztálymetódus ennek rövidítése. Ha nincs megadva téma, az application a synchronet-et használja (vagy a BBS.config.theme-et, ha az be van állítva).

Szerepkulcsok

A Theme::ROLES: a presetek összes kulcsa (mind az öt mindet definiálja), mi rajzol vele a rubbs 1.0.0-ban, és a synchronet-beli értéke. A „a gem nem használja” jelzésű kulcsok a saját widgetjeidnek és screenjeidnek valók. Az 1.0 kidobta azokat a szerepeket, amelyekkel semmi nem rajzolt: a check_on, a check_off, a listbox_header, a warning és a reset szerepet.

A presetek minden SGR-értéke az előtér mellett a hátteret is megadja (37;40, 37;44), és többségük 0;-val kezdődik, így egy stílus sosem örökli az előtte rajzolt cella félkövérségét vagy halványságát. A saját értékeidben is így tégy.

Téma választása az applicationhöz

A BBS::Application.define blokkjában a theme egy téma-példányt vagy egy preset nevét várja, akár egy felülíró blokkal együtt:

require 'bbs'

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

A 0.17.0-ban a csupasz Symbol-alak (theme :synchronet) magát a Symbolt tárolta el, és az első újrarajzolás TypeError-ral elszállt, az argumentum nélküli APP.theme pedig visszaállította a tárolt témát; 0.17.1 óta a Symbol a presetet veszi, és a builder argumentum nélküli theme-je az eddig beállított témát adja vissza (nil-t, ha nem volt theme hívás, ami synchronet-et jelent).

Az applicationön belül a theme a használt BBS::Theme-et adja vissza; ezt kapja a BBS::Markdown.to_lines, és ebből színezhetsz saját stringet:

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

Kulcsok felülírása

A theme blokkban minden egyargumentumos hívás beállítja az adott kulcsot; a style(key, value) ennek explicit alakja, az inherit pedig lecseréli az alapot, amire a felülírások kerülnek:

require 'bbs'

APP = BBS::Application.define do
  theme :nortoncommander do
    inherit :neumanntronics              # opcionális: másik preset legyen az alap
    window_border "\e[1;36;44m"
    accent        "\e[1;33;44m"
    style :screen, "\e[40m"
  end
end

DSL nélkül a merge ugyanezt teszi:

require 'bbs'

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

Saját téma

Egy teljes Hashből építs BBS::Theme-et. A legegyszerűbben úgy kapod meg az összes kulcsot, ha egy preset Hashéből indulsz a Theme::PRESETS-ben:

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

A paletta: BBS::Ansi

A témán kívül minden szín egyetlen palettából jön, a BBS::Ansi-ból (lib/bbs/ansi.rb): a flow stílusai, egy soralapú board say-e, egy FakeOS, egy logsor, egy gyors door. A BBS::Color (Color.c(:yellow, text)) az 1.0 óta nincs meg; helyette a konstanst és egy resetet írj.

require 'bbs'

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

A BBS::Petscii::Colors ugyanezeknek a szekvenciáknak a C64-es nevei (WH YE CY LG GR DG LB BL GN RD PU OR, valamint RV RO az inverz be- és kikapcsolásához; lásd Commodore 64), és egy komponens ezekből a színekből álló szerep-Hasht kap: a BBS::Selector::COLORS-t, a Flow FlowRunner::STYLES-át, egy FakeOS colors-át. A C64 grafikus vásznán ugyanezekből C64-es színkód lesz: BBS::Petscii::Canvas.color(YE) == Canvas::YELLOW.

BBS::FrameBuffer

A BBS::FrameBuffer (lib/bbs/frame_buffer.rb) egy képernyőn kívüli cellarács; minden cella egy karakter és egy SGR-string. Az Application egy egész képkockát rajzol bele, összeveti az előzővel, és csak a különbséget küldi el. A widgetek a render(frame)-ben kapnak egyet.

Dupla pufferelés és delta diff

Az Application minden újrarajzolása (a privát render_screen) ezt csinálja:

1. Készít egy üres, terminálméretű next képkockát. Megtartja a committed képkockát (amit a terminál most mutat); az első rajzoláskor vagy átméretezés után üresről indul, és letörli a képernyőt.
2. Kitölti a next-et a téma screen stílusával, kirajzolja az asztalt, a window-kat alulról felfelé, a menüsort és a státuszsort.
3. delta = next.diff(committed); ha nem üres, kurzorrejtés és -mutatás (\e[?25l … \e[?25h) közé csomagolva kiírja, és a next lesz az új committed képkocka.

Így egy billentyűleütés után csak a megváltozott cellák mennek le a vonalon: egy listakijelölés mozgatása két sorba kerül, egy ketyegő óra néhány karakterbe. Kézzel is ugyanez működik:

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"   csak a megváltozott számjegy
p nxt.diff(nxt)           # => ""

Konstansok

Osztálymetódusok ANSI-stringekhez

Ezek SGR-escape-eket tartalmazó stringeken dolgoznak, és csak a látható karaktereket számolják. Escape-szekvencia az, amire a BBS::Ansi::CSI_RE illeszkedik (/\e\[[\d;?]*[A-Za-z~]/: SGR, kurzormozgatás, \e[2~-féle billentyűk, és 1.0 óta a privát módú szekvenciák is, mint a \e[?25l); ez váltja a 0.x FrameBuffer::ANSI_ESC_RE-jét.

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"

Rajzolás

Minden koordináta 1-től számozott oszlop és sor, mint a terminálban. A képkockán kívül eső részt bármelyik szélen levágja, így nyugodtan rajzolhatsz részben a képernyőn kívülre.

A write_ansi úgy értelmezi az escape-eket, ahogy egy terminál tenné, a képkockán belül:

• Egy SGR-szekvencia (\e[...m) hozzáadódik az aktuális stílushoz; egy reset (\e[0m vagy \e[m) a base_sgr-hez tér vissza, nem a „stílus nélkülihez”. Így tartja meg egy kék window-ban egy színes szó utáni szöveg a kék hátteret.
• A \e[NC (kurzor előre) N szóközt ír az aktuális stílusban, ahogy az ANSI-art használja.
• Minden más CSI-szekvencia elvész, a kurzormozgatás (\e[SOR;OSZLOPH) is, így egy widgeten belüli szöveg nem ugorhat ki belőle; a 0.x cursor: opciója megszűnt. A vezérlőkarakterek is elvesznek (a \n és a \r is): egy hívás egy sort ír.

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')                                        # csak a "cli" fér ki
fb.move(1, 2)
fb.write_ansi("a\e[1mb\e[0mc\e[3Cd", base_sgr: "\e[44m")   # stílusok: 44 / 44+bold / 44, három szóköz, d
fb.move(1, 3)
fb.write_ansi("x\e[4;10Hy")                                # a H nem számít: "xy"

Az eredmény:

Hello            cli
abc   d
xy

Keretes panel mintás háttéren, árnyékkal:

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       ║  ░░░░
░░║──────────────────────║  ░░░░
░░║           │          ║  ░░░░
░░║           │          ║  ░░░░
░░╚══════════════════════╝  ░░░░
░░░░                        ░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Karakterszélesség

A framebuffer Ruby-karakterenként egy cellát számol. Ez helyes az ASCII-ra, az előre komponált ékezetes latin betűkre, a keretrajzoló, blokk- és braille-karakterekre, vagyis mindarra, amit maga a gem rajzol. Hibás viszont:

• a széles karaktereknél (CJK, a legtöbb emoji): egy cellában tárolódnak, de a terminál két oszlopon mutatja őket, így a sor maradéka karakterenként eggyel jobbra csúszik;
• a kombináló jeleknél (e plusz U+0301): két cellának számítanak, de egy oszlopon látszanak.

A visible_width, a clip_ansi, a wrap_ansi és a Markdown-táblázatok ugyanígy számolnak. Normalizáld a szöveget NFC-re (text.unicode_normalize(:nfc)), és ami pontosan egymás alá kell kerüljön, abba ne tegyél széles karaktert.

BBS::Renderer: ERB screenek

A BBS::Renderer (lib/bbs/renderer.rb) egy ERB-sablonból stringet állít elő egy soros, flow-stílusú screenhez. Ezt használja a Flow screen lépése (lásd Flow). A framebufferhez nincs köze: a dupla pufferelést a fent leírt FrameBuffer#diff végzi.

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

Az ERB trim_mode: '-'-dal fut (így a -%> elnyeli a sortörést), és az eredmény minden \n-je \r\n lesz a telnetvonal kedvéért. A sablon ezeket a helpereket hívhatja:

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')

A terminálra írva (a keret és az üdvözlés élénkzöld, a levelekről szóló sor élénksárga):

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

BBS::Banner

A Flow banner és big_banner lépése a BBS::Banner-t (lib/bbs/banner.rb) használja, ami küldésre kész, \r\n sorvégű, két szóközzel behúzott stringeket ad:

require 'bbs'

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

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

BBS::Markdown

A BBS::Markdown (lib/bbs/markdown.rb) Markdown-szövegből ANSI-val színezett sorok tömbjét készíti, adott szélességre. Az eredményt egy BBS::Widgets::ScrollView-nak, egy görgethető Info window-nak adhatod, vagy magad írhatod ki a sorokat.

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

Applicationön belül a szokásos hívás:

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

Minden stílusos szakasz a téma text SGR-jével zárul, így az utána következő szöveg visszakapja a hátterét: színezett window-háttéren ez számít. A sima bekezdéssorok nem kezdődnek saját SGR-rel; a ScrollView text alapstílussal rajzolja őket. Ha a sorokat közvetlenül egy sessionre írod, mindegyik elé tedd oda a theme[:text]-et.

Amit ért

Egy minta 36-os szélességen, synchronet-tel:

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) }

Színek nélkül (a terminálban: a Welcome élénkfehér, a Rules sárga, a Small print cián, a nice élénkfehér, a kind és a brief halvány, a the wiki sárga, a help cián, a listajelek és -számok sárgák, a vonal és a táblázatkeret cián):

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 │      │
└──────┴───────┴──────┘

Egy el nem férő táblázat szűkül, aztán a cellái vágódnak (30-as szélesség):

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

Korlátok

A forrással ellenőrizve; ezek egyikére se építs:

• A backslash nem állítja meg a kiemelést. Az escape-ek a kiemelési szabályok után érvényesülnek, így a \*not italic\* mégis dőlt lesz, a backslashek pedig megmaradnak: az eredmény egy backslash, egy halvány not italic, majd még egy backslash. Ugyanez a helyzet a \_x\_-szel. Ahol nem illeszkedik kiemelési szabály, ott működik az escape: a 2\*3\*4-ből 2*3*4, a \# no heading-ből # no heading lesz.
• A kódszakaszokon belül is eltűnnek az escape-ek: a `a\*b` a*b-t mutat.
• Nincs __félkövér__, ~~áthúzás~~, HTML vagy entitás (úgy jelennek meg, ahogy le vannak írva), setext-címsor (=== egy sor alatt), behúzott kódblokk, kemény sortörés (két sorvégi szóköz) és feladatlista (a - [ ] megtartja a szögletes zárójelet).
• Képek: a ![alt](src) egy !-et és az alt szöveget mutatja a link színében.
• Beágyazott idézet: a > > x egy jelet és egy szó szerinti > x-et ad.
• A harmadiktól a hatodik szintig a címsorok egyformák.
• A kódblokkok vágódnak, nem tördelődnek; a szélességnél hosszabb szót nem vágja el.
• A széles karakterek egy oszlopnak számítanak (lásd fent, Karakterszélesség).

Lásd még

• rubbs — áttekintés
• Widgetek — ami ezekkel a szerepekkel rajzol
• Application — a theme DSL a helyén, a futási ciklus
• Rajzok és grafikus képernyők — rajzok, a C64 grafikus vászna
• Flow — a screen, banner és big_banner lépések