Application

BBS::Application is the desktop layer of rubbs: a full-screen, mouse-aware event loop with a menubar, a statusbar, a background panel and a stack of switchable windows, Turbo Vision style. This page covers the Application.define DSL method by method, the instance API, the run loop and the app-to-door loop, the context hash, events, focus, the menubar and the statusbar. The windows themselves are on Windows, the widgets on Widgets.

The pieces

An application is a root container with layers drawn over it. Every frame is drawn in this order, from the back to the front:

The menubar and the statusbar exist only if the definition declares them (menubar and at least one status_hint). Without them the root panel and the windows get the whole screen.

The rendering is double-buffered: every frame is drawn into a fresh BBS::FrameBuffer, compared with the last one sent, and only the changed cells go down the line. A terminal resize (NAWS) is noticed at the next frame: the whole screen is redrawn and every window gets relayout.

A complete example

A shared notice board: a list of notes in a master-detail window, a form to write one, a menu with a door, status hints, a clock on the statusbar. It is the program the rest of the page refers to. Save it as notes.rb, run ruby notes.rb, then telnet localhost 2323.

require 'bbs'

# A tiny shared notice board: one list of notes for every caller.
class NoteStore
  Note = Struct.new(:id, :author, :title, :body, :at)

  def initialize
    @notes = []
    @mutex = Mutex.new
  end

  def all = @mutex.synchronize { @notes.dup }

  def add(author, title, body)
    return :empty if title.strip.empty?

    @mutex.synchronize { @notes << Note.new(@notes.size + 1, author, title.strip, body, Time.now) }
    :ok
  end
end

# A door: any callable(session, context) gets the raw line.
DICE = lambda do |session, context|
  session.write("\r\n  #{context[:username]} rolls: #{rand(1..6)} and #{rand(1..6)}\r\n")
  session.write("  Press ENTER to go back.\r\n")
  session.readline
end

NOTES_APP = BBS::Application.define do
  theme :synchronet do
    accent "\e[1;33;44m"
  end

  services notes: NoteStore.new

  door :dice, DICE, label: '&Dice'

  helpers do
    def me = context[:username] || 'guest'
    def clock = Time.now.strftime('%H:%M')

    def note_list
      open = windows.find { |w| w.is_a?(BBS::Windows::MasterDetail) }
      open ? raise_window(open) : open_window(:notes)
    end

    def refresh_notes
      windows.grep(BBS::Windows::MasterDetail).each { |w| w.replace_items(services[:notes].all) }
    end
  end

  window :notes, type: :master_detail do |w|
    w.title       ' Notes '
    w.maximizable true
    w.items       { |ctx| ctx[:notes].all }
    w.item_label  { |note, _ctx| note.title }
    w.render_detail do |note, width, _ctx|
      ["#{note.title} — #{note.author}", '', *BBS::FrameBuffer.wrap_ansi(note.body.to_s, width)]
    end
    w.bottom_meta   { |note, _ctx| note.at.strftime('%Y-%m-%d %H:%M') }
    w.empty_message '  No notes yet. Alt-N writes one.'
    w.action(label: '&New') { |_win, ctx| ctx[:app].open_window(:new_note); :keep }
  end

  window :new_note, type: :form do |w|
    w.title ' New note '
    w.width 60
    w.hint  'Alt-S saves, Esc cancels.'
    w.field :title, label: 'Title', max_length: 40
    w.field :body,  type: :textarea, rows: 5
    w.on_submit do |values, form, ctx|
      if ctx[:notes].add(ctx[:app].me, values[:title], values[:body]) == :empty
        form.error('A note needs a title.')
        :keep
      else
        ctx[:app].refresh_notes
        :close
      end
    end
  end

  menubar do
    menu '&File' do
      item '&Notes', shortcut: 'F2' do note_list end
      item '&New note', shortcut: 'F3' do open_window(:new_note) end
      separator
      item 'E&xit', shortcut: 'Alt-X' do :halt end
    end
    menu '&Doors' do
      doors
    end
    menu '&Help' do
      item '&About' do BBS::Dialogs.message(self, "Notes desk for #{me}.", title: ' About ') end
    end
  end

  status_hint('F2', 'Notes') { note_list }
  status_hint('F3', 'New', hidden: true) { open_window(:new_note) }
  status_hint('F10', 'Menu') { menubar.open(0) }
  status_hint('Alt-X', 'Bye') { :halt }

  on_tick { statusbar.right_text = "#{me} │ #{clock}" }
  on_door { |door, ctx| warn "#{ctx[:username]} enters #{door.name}" }

  init do
    statusbar.right_text = "#{me} │ #{clock}"
    note_list
  end
end

BBS.configure do |c|
  c.port  = Integer(ENV.fetch('PORT', 2323))
  c.mouse = true
  c.flow  = BBS::Flow.define do
    ask :username, prompt: 'Your name'
    call do |ctx, runner|
      NOTES_APP.run(session: runner.session, session_id: ctx[:session_id], context: ctx)
      nil
    end
    say 'Bye!'
  end
end

BBS.start if $PROGRAM_NAME == __FILE__

What the caller sees after typing a name and writing one note:

  File   Doors   Help

  ╔═[■]═  Notes ══════════════════════════════════════════════════════1══[↑]═╗
  ║                                                                          ║
  ║   Hi                       Hi — Ann                                      ║
  ║                                                                          ║
  ║                            body                                          ║
  ║                                                                          ║
  ...
  ║ 2026-10-27 23:16                                                         ║
  ║                                                         [ New ] [ Close ]║
  ╚══════════════════════════════════════════════════════════════════════════┘

 F2 Notes  F10 Menu  Alt-X Bye                                      Ann │ 23:16

Things to notice:

• NOTES_APP is a definition (an Application::Builder), built once at load time and shared by every caller. Each call gets its own Application instance from it.
• Services are shared too: NoteStore.new runs once, so every caller sees the same notes. That is why the store has a mutex.
• Per-caller state goes in context (here :username, filled by the flow's ask).
• Window callbacks get a ctx hash; ctx[:app] is the running application, so helpers are reachable as ctx[:app].me.

Starting an application

From a Flow call step (the usual way)

require 'bbs'

APP = BBS::Application.define do
  status_hint('Alt-X', 'Quit') { :halt }
end

BBS.configure do |c|
  c.flow = BBS::Flow.define do
    ask :username, prompt: 'Name'
    call do |ctx, runner|
      APP.run(session: runner.session, session_id: ctx[:session_id], context: ctx)
      nil
    end
    say 'Goodbye!'
  end
end

BBS.start

Builder#run builds the application, runs it, and when the caller left it through a door, runs the door and builds the application again (see The app-door loop). The flow's own ctx is passed as the application's context, so what the flow asked (:username) and what the application writes into context survive both ways. Returning nil from the call step lets the flow go on (say 'Goodbye!'); returning :halt would end the call.

With the Flow app step

require 'bbs'

APP = BBS::Application.define do
  status_hint('Alt-X', 'Quit') { :halt }
end

FLOW = BBS::Flow.define do
  ask :username, prompt: 'Name'
  app APP
  say 'Goodbye!'
end

The app step is shorter: it runs APP.run(...) (Builder#run) with the flow's ctx, so the caller goes through doors here as well (since 0.17.1; before that the step built the application once and a door only ended it). The call form is still the one to use when the step needs code around the run; all the boards of the network (Teletype BBS, Feedia BBS, Alexandria BBS) use it.

Without a flow

Builder#build(session:, session_id:, context: {}) returns a ready Application; its run is the event loop alone. Anything that has a BBS::Session can call it (a door, a test, a custom server):

require 'bbs'

APP = BBS::Application.define do
  status_hint('Alt-X', 'Quit') { :halt }
end

def serve(session, session_id)
  app = APP.build(session: session, session_id: session_id, context: { username: 'guest' })
  app.run
end

The define DSL

BBS::Application.define { ... } evaluates the block on a fresh BBS::Application::Builder and returns it. Nothing is built yet: the builder records the definition, and build or run turns it into an application per caller.

The order of the calls inside define does not matter. build always does: application, menubar, statusbar, init, body.

theme

theme(base = nil, &block)

Sets the theme of the application, its menubar, statusbar and every window opened through it. The default is BBS::Theme.synchronet.

Inside the block (a ThemeBuilder):

require 'bbs'

APP = BBS::Application.define do
  theme :neumanntronics do
    accent      "\e[1;33;44m"
    style :text, "\e[0;37;44m"
  end
end

Without a block, pass a preset name or a BBS::Theme instance: theme :synchronet and theme BBS::Theme.synchronet are the same (since 0.17.1; in 0.17.0 the Symbol form crashed the first frame). theme with no arguments returns the theme set so far. The presets and the style keys are listed on Drawing.

services

services(hash = nil)

Merges hash into the services of the definition; call it as often as you like. Without an argument it returns the hash. The services become app.services and are spread into the ctx of every window spec callback (ctx[:notes]).

require 'bbs'

class Clock
  def now = Time.now
end

APP = BBS::Application.define do
  services clock: Clock.new
  services motd: 'Be excellent to each other.'

  window :motd, type: :info do |w|
    w.title ' Message of the day '
    w.body  { |ctx| [ctx[:motd], :spacer, ctx[:clock].now.to_s] }
  end

  init { open_window(:motd) }
end

The hash and its objects are created once and shared by all callers. Keep per-caller state in context, and make shared objects thread-safe: every caller runs in its own thread.

helpers

helpers { def name ... end }

The block is evaluated into a module, and every application built from the definition is extended with it. Helper methods run on the application, so they can call the whole instance API (open_window, context, services, statusbar, ...), and everything else that runs on the application can call them: menu items, status hints, init, on_tick, and window callbacks through ctx[:app].

require 'bbs'

APP = BBS::Application.define do
  helpers do
    def greet = BBS::Dialogs.message(self, "Hello, #{context[:username]}!")
    def sysop? = context[:username] == 'sysop'
  end

  menubar do
    menu '&Hello' do
      item '&Greet' do greet end
    end
  end

  init { greet if sysop? }
end

helpers can be called more than once; the methods accumulate in the same module.

window

window(name, type:) { |w| ... }

Registers a BBS::WindowSpec under name; type is :info, :form, :master_detail or :stream. Open it with app.open_window(name, **extras). Every attribute, field and callback is documented on Windows.

require 'bbs'

APP = BBS::Application.define do
  window :about, type: :info do |w|
    w.title ' About '
    w.body  ['Notes desk 1.0', :spacer, { kv: [['Ruby', RUBY_VERSION]] }]
  end

  status_hint('F1', 'About') { open_window(:about) }
end

door

door(name, program, label: nil)

Declares a BBS::Door. program is a BBS::FakeOS definition, a BBS::Flow, or anything that responds to call(session, context); label is the text of its menu item (& marks the hotkey) and defaults to the upcased name. The door does not run by itself: app.open_door(name) leaves the application through it, and doors inside a menu adds one item per declared door. Door programs are covered on Doors.

require 'bbs'

COIN = ->(session, _context) { side = %w[Heads Tails].sample; session.write("\r\n  #{side}!\r\n"); sleep 2 }

APP = BBS::Application.define do
  door :coin, COIN, label: '&Coin toss'

  menubar do
    menu '&Doors' do
      doors
    end
  end
  status_hint('F9', 'Coin') { open_door(:coin) }
end

menubar

menubar { menu(label) { item ...; separator; doors } }

Declares the menubar. The block is evaluated at every build, on a MenubarBuilder:

item options:

The item block runs with self set to the application and receives the Menubar::MenuItem. Its return value matters: :halt ends the application, anything else is ignored.

require 'bbs'

APP = BBS::Application.define do
  menubar do
    menu '&File' do
      item '&Open...', shortcut: 'F3' do BBS::Dialogs.message(self, 'Nothing to open.') end
      item '&Print', enabled: false
      separator
      item 'E&xit', shortcut: 'Alt-X' do :halt end
    end
    menu '&Help' do
      item '&About' do |it| BBS::Dialogs.message(self, "You picked #{it.label.delete('&')}.") end
    end
  end
end

How the menubar behaves for the caller is in The menubar.

status_hint

status_hint(key, label, hidden: false) { ... }

Adds one entry to the statusbar, in declaration order. The first status_hint creates the statusbar; a definition without one has no statusbar (and app.statusbar is nil).

require 'bbs'

APP = BBS::Application.define do
  status_hint('F1', 'Help') { BBS::Dialogs.message(self, 'Alt+letter opens a menu.') }
  status_hint('F3', 'Search', hidden: true) { BBS::Dialogs.input(self, prompt: 'Find:') }
  status_hint('Alt-X', 'Bye') { :halt }
end

A status hint only gets the key if no window and no menu used it first (see Event dispatch). Function keys are always free; a letter is not.

body

body { add(widget) }

The block runs on a small BodyContext with two methods: add(widget) (adds to the root panel and applies the theme) and app. It is the place for desktop widgets; init can do the same with add.

require 'bbs'

APP = BBS::Application.define do
  body do
    title = BBS::Widgets::Label.new(text: 'NOTES DESK', style_key: :accent, align: :center)
    title.layout(1, 3, app.cols, 1)
    add title
  end
end

body runs after init.

init

init { ... }

Runs on every freshly built application, after the menubar and the statusbar exist and before body. Open the first window, put widgets on the desktop, set statusbar.right_text, read context. It runs again after every door, because the application is rebuilt: guard one-off things with a context flag.

require 'bbs'

APP = BBS::Application.define do
  window :welcome, type: :info do |w|
    w.title ' Welcome '
    w.body  ['Glad you called.']
  end
  status_hint('Alt-X', 'Bye') { :halt }

  init do
    statusbar.right_text = Time.now.strftime('%H:%M')
    unless context[:welcomed]
      context[:welcomed] = true
      open_window(:welcome)
    end
  end
end

on_tick

on_tick { ... }

Runs on the application each time a second passes without input (the run loop reads keys with a one second timeout). Typical uses: a clock or a counter in statusbar.right_text, polling a service, presence updates. Windows have their own per-tick hook, Window#tick(app); on_tick runs first, then every open window's tick.

require 'bbs'

APP = BBS::Application.define do
  status_hint('Alt-X', 'Bye') { :halt }
  on_tick { statusbar.right_text = Time.now.strftime('%H:%M:%S') }
end

Ticks only fire while the caller is idle: someone typing steadily gets none. Do not rely on them for exact timing.

on_idle

on_idle { ... }

Runs on the application when the caller has been silent for the session's idle_seconds (since 0.19.0). Return :keep and the caller stays on, with the idle count starting again; return anything else and the loop shows "Disconnected after N s idle." and ends, as it does without the block.

require 'bbs'

APP = BBS::Application.define do
  on_idle do
    next nil if @asked                  # asked last time, no answer: drop
    @asked = true
    BBS::Dialogs.confirm(self, 'Still there?', on_yes: -> { @asked = false })
    :keep                               # one more idle period to answer
  end
end

The dialog does not block: it opens a window and the loop goes on, so the block returns :keep to give the caller one more idle period to answer. Without idle_seconds (on the session or in the config) there is no limit and the block never runs.

on_door

on_door { |door, context| ... }

Called by Builder#run just before it hands the line to a door, with the BBS::Door (name, label, program) and the context. The application is already gone at this point, so the block is called as a plain block (self is wherever define was written), not on the application.

require 'bbs'

APP = BBS::Application.define do
  door :coin, ->(session, _ctx) { session.write("Heads!\r\n"); sleep 1 }
  on_door { |door, context| warn "#{context[:username]} -> door #{door.label}" }
  status_hint('F9', 'Coin') { open_door(:coin) }
end

Builder methods

The builder has no readers since 1.0: the registered window specs and doors are the running application's window_specs and doors.

The instance API

Everything below is a method of the running BBS::Application. Helpers, menu items, status hints, init and on_tick call them directly; window callbacks through ctx[:app].

State

Building the screen

require 'bbs'

APP = BBS::Application.define do
  init do
    hint = BBS::Widgets::Label.new(text: 'F10 opens the menu', style_key: :text_dim)
    hint.layout(5, 5, 26, 1)
    add hint
  end
end

Windows

require 'bbs'

APP = BBS::Application.define do
  window :a, type: :info do |w| w.title ' A ' end
  window :b, type: :info do |w| w.title ' B ' end

  status_hint('F2', 'Both') { open_window(:a); open_window(:b) }
  status_hint('F3', 'A to front') do
    a = windows.find { |w| w.title == ' A ' }
    raise_window(a) if a
  end
  status_hint('F4', 'Close all') { close_window until windows.empty? }
end

Window numbers, switching, moving and sizing are covered on Windows.

Long work and the raw line

require 'bbs'
require 'net/http'

APP = BBS::Application.define do
  helpers do
    def fetch_motd
      text = with_loading('Fetching...') do
        Net::HTTP.get(URI('https://example.org/')).lines.first.to_s.strip
      rescue StandardError
        nil
      end
      BBS::Dialogs.message(self, text || 'No answer.', title: ' MOTD ')
    end

    def raw_screen
      with_line do |session|
        session.write("A plain terminal for a moment. Press ENTER.\r\n")
        session.readline
      end
    end
  end

  status_hint('F2', 'MOTD') { fetch_motd }
  status_hint('F3', 'Raw') { raw_screen }
end

The screen is not repainted while the with_loading block runs, and keys typed meanwhile wait in the line. with_line is the tool for ZMODEM downloads (BBS::Zmodem.send_files(session, ...), see Doors) and full-screen ANSI art viewers.

Running and leaving

open_door works from any handler: a menu item, a status hint, a window's key handler, a Dialogs.confirm callback, and also a window button (Info buttons, MasterDetail actions, the Form buttons) or a MasterDetail on_activate, which swallow the return value. It stops the event loop itself, so the application ends after the event being handled and Builder#run opens the door:

require 'bbs'

APP = BBS::Application.define do
  door :coin, ->(session, _ctx) { session.write("Heads!\r\n"); sleep 1 }

  window :lobby, type: :info do |w|
    w.title ' Lobby '
    w.body  ['Feeling lucky?']
    w.button(label: '&Toss a coin') do |_win, ctx|
      ctx[:app].open_door(:coin)
    end
  end

  init { open_window(:lobby) }
end

In 0.17.0 a button had to follow open_door with ctx[:app].stop!; since 0.17.1 that is no longer needed (it does no harm). When the run ends because the line was lost (line_lost?), Builder#run drops context[:door] without opening it, so a door picked just before a hang-up does not open.

The run loop

flowchart TD
  R[render the frame, send the diff] --> K{"readkey, 1 s timeout"}
  K -- nil: hung up --> E[end]
  K -- idle --> T["tick!: on_tick, then window.tick"]
  T --> I{"idle_seconds reached?"}
  I -- no --> R
  I -- yes --> M[message: Disconnected] --> E
  K -- key or mouse --> D[dispatch the event]
  D -- ":halt" --> E
  D --> R

Application#run:

1. Renders the frame and sends only what changed.
2. Waits up to one second for a key (Session#readkey(timeout: 1.0)).
3. No key in that second: runs tick!, and adds the second to the idle time. When the idle time reaches the session's idle_seconds (from BBS.config.idle_seconds; when set), runs the on_idle block: :keep starts the count again, anything else shows "Disconnected after N s idle." and ends.
4. A key or a mouse event: resets the idle time, wraps it in a BBS::Event and dispatches it. :halt from the dispatch ends the loop.
5. A hang-up (readkey returns nil, or IOError, EPIPE, ECONNRESET) ends the loop quietly.

An exception raised by a handler (a menu item, a callback) is written to stderr with the first three backtrace lines, and the event is dropped: one bug does not end the caller's session. On the way out the loop shows the cursor and clears the screen.

Event dispatch

Each event goes down this chain; the first one to take it stops it.

Consequences worth knowing:

• An Alt-letter that is the hotkey of a button in the active window presses that button, even when a menu has the same letter: the window comes before the menubar.
• A letter typed into a text field never reaches a status hint. Use function keys and Alt combinations for hints.
• With a window open, Tab belongs to the window; root widgets get no keys until the windows are closed.
• A click on the root panel goes to the focused root widget only. With two buttons on the desktop, only the focused one answers a click, and root buttons have no letter hotkeys.

Handler return values

Every handler in the chain (handle_event of a widget or window, a menu item, a status hint) answers with its return value:

Menu items and status hints count as taken whatever they return (except :halt).

The app-door loop

Builder#run is the loop around Application#run that takes the caller through doors:

sequenceDiagram
  participant F as Flow call step
  participant B as Builder#run
  participant A as Application
  participant D as Door
  F->>B: run(session:, session_id:, context: ctx)
  loop until no door
    B->>A: build + run
    A-->>B: ended (context[:door] set by open_door?)
    B->>B: door = context.delete(:door)
    B->>D: on_door(door, ctx), door.run(session, ctx)
    D-->>B: the program returned
  end
  B-->>F: returns

After a door the application is built again: init runs again, the windows that were open are gone, the menubar and the statusbar are new. Whatever must survive a door goes into context; the Teletype BBS keeps the unread count it has already rung the bell for in context[:mail_seen], and the start of the call in context[:call_started].

The loop also ends when the application ended because the line was lost (Application#line_lost?: a hang-up, the idle limit): a door already in context[:door] is dropped, not opened.

The context

context is a plain Hash owned by the caller's call, not by the application.

• Started from a flow, it is the flow's own ctx: :session_id, every ask answer (:username), whatever earlier steps stored.
• The application reads and writes it freely; the flow sees the changes after the application returns.
• It survives the app-door loop; a BBS::Flow door gets a copy of it (see Doors), a call(session, context) door gets the hash itself.
• open_door stores the door under :door for a moment; Builder#run removes it.

Window spec callbacks do not get context directly but a ctx merged from three sources, the later winning on equal keys:

ctx = { app: app, **app.context, **app.services, **extras }

ctx is a new Hash for each opened window: writing ctx[:x] = 1 does not change the context. Write ctx[:app].context[:x] = 1.

Events

BBS::Event (lib/bbs/event.rb) is the normalised input every widget and window receives:

Event = Struct.new(:kind, :key, :mouse, :x, :y, keyword_init: true)

require 'bbs'

event = BBS::Event.key(:alt_s)
p event.key?      # => true
p event.alt?      # => true
p event.alt_char  # => "s"
p BBS::Event.key('q').char?  # => true

A custom widget answers in handle_event(event):

require 'bbs'

class Counter < BBS::Widget
  attr_reader :count

  def initialize(**kw)
    super
    @count = 0
  end

  def focusable? = true

  def handle_event(event)
    return nil unless event.key? && event.key == '+'

    @count += 1
    :handled
  end

  def render(frame)
    frame.move(bounds.x, bounds.y)
    frame.write("Count: #{@count}", sgr: style(focused ? :input_focused : :text))
  end
end

The full list of key symbols and the mouse model are on Telnet and the store; writing widgets is on Widgets.

Focus

BBS::FocusManager (lib/bbs/focus_manager.rb) keeps track of the focused widget inside one container. Every window has one (window.focus_manager), and the root panel gets one when it first receives an event.

Moving the focus sets focused on both widgets and calls on_blur on the old one and on_focus on the new one. The candidates are looked up again on every move, so widgets added later take part; but the first focus is chosen when the manager is made. After building a window by hand, call window.reset_focus (a fresh manager), then window.focus_manager.focus(widget) to choose the start:

require 'bbs'

def open_search(app)
  win = BBS::Window.new(title: ' Search ')
  win.layout(20, 8, 40, 6)
  query = BBS::Widgets::TextInput.new(placeholder: 'words...')
  query.layout(22, 10, 36, 1)
  win.add(query)
  go = BBS::Widgets::Button.new(label: '&Go', on_click: ->(_b) { app.close_window(win) })
  go.layout(36, 12, 8, 1)
  win.add(go)
  win.reset_focus
  win.focus_manager.focus(query)
  app.open_window(win)
end

A left click inside a window focuses the widget under the pointer; the mouse wheel goes to the widget under the pointer even when another one has the focus.

The menubar

BBS::Menubar (lib/bbs/menu.rb) is the strip on row 1. The DSL builds it; it can also be made by hand.

Behaviour

• Each menu label is shown with its hotkey letter highlighted (&File → File).
• F10 opens the first menu, Alt-letter the menu with that hotkey. A click on a menu title opens it, a second click closes it. All of it goes through Menubar#handle_event; the key handling inside is private.
• While a menu is open it takes every key and click, so nothing leaks to the windows: Left/Right move to the neighbouring menu (wrapping), Up/Down move between items, skipping separators and disabled items, Enter picks, a letter picks the item with that hotkey, Esc or F10 closes. A click on an item picks it, a click outside closes the menu.
• Picking an item closes the menu, then runs the item's block. :halt from it ends the application.
• A dropdown near the right edge is shifted left so it fits on the screen.

Building one by hand

Menubar::MenuItem is a struct of label, shortcut, enabled, on_select, separator, hint; hotkey and display (the label without &) are derived. enabled? is what the menubar asks: false for a separator, the lambda's answer when enabled is callable (called as it is; only the DSL's item runs it on the application), otherwise true unless enabled is false.

require 'bbs'

def run_plain_app(session, session_id)
  app = BBS::Application.new(session: session, session_id: session_id, theme: BBS::Theme.dosnavigator)

  item = ->(label, shortcut: nil, &block) { BBS::Menubar::MenuItem.new(label: label, shortcut: shortcut, on_select: block) }
  app.menubar = BBS::Menubar.new
  app.menubar.menus << BBS::Menubar::Menu.new(label: '&File', items: [
    item.('&Hello') { BBS::Dialogs.message(app, 'Hello!') },
    BBS::Menubar::MenuItem.new(label: '', separator: true, enabled: false),
    item.('E&xit', shortcut: 'Alt-X') { :halt }
  ])

  app.statusbar = BBS::Statusbar.new(right_text: 'plain')
  app.statusbar.add_hint('F1', 'Hello') { BBS::Dialogs.message(app, 'Hello!') }
  app.statusbar.add_hint('Alt-X', 'Quit') { :halt }

  label = BBS::Widgets::Label.new(text: 'Background', style_key: :text)
  label.layout(3, 3, 20, 1)
  app.add(label)

  app.run
end

BBS::Application.new(session:, session_id:, context: {}, theme: nil, on_idle: nil, on_tick: nil, helpers: nil, services: {}, window_specs: {}, doors: {}) is what build calls; on_tick is a callable taking the application. on_idle is a callable taking the application, called at the idle limit (see on_idle).

The statusbar

BBS::Statusbar (lib/bbs/statusbar.rb) is the strip on the last row: hints on the left (the key in the :statusbar_key style, then the label), and an optional text on the right.

Hints that do not fit the width are left off, from the end; hidden hints take no room, which is the way to keep a key working while right_text gets the space. A hint whose block returns :halt ends the application; any other return value counts as handled.

require 'bbs'

APP = BBS::Application.define do
  status_hint('F1', 'Help') { BBS::Dialogs.message(self, 'No help yet.') }
  status_hint('F5', 'Refresh', hidden: true) { statusbar.right_text = 'refreshed' }
  status_hint('Alt-X', 'Bye') { :halt }

  init    { statusbar.right_text = "#{context[:username]} │ #{Time.now.strftime('%H:%M')}" }
  on_tick { statusbar.right_text = "#{context[:username]} │ #{Time.now.strftime('%H:%M')}" }
end

Key names in hints

'Ctrl-S' does not match anything (the key is :ctrl_s); write 'ctrl_s', or keep the key in a hidden hint and say "Ctrl-S" in the label of a visible one. Remember that Esc and Tab usually reach a window first.

Keys and mouse for the caller

What a caller can do in any rubbs application. Put a version of it in your Help menu; the Teletype BBS and Feedia BBS show one under Help → Keys.

The mouse works when the server has c.mouse = true and the terminal reports SGR or X10 mouse events (see Telnet and the store).

Real boards

See also

• Windows — BBS::Window, the window DSL, Info, Form, MasterDetail, Stream, dialogs
• Widgets — the controls inside windows and on the desktop
• Drawing — themes and style keys, the FrameBuffer
• Flow — the line-by-line layer that usually starts an application
• Doors — door programs, FakeOS, gateways, ZMODEM
• Telnet and the store — key symbols, the mouse, sessions