badline 0.7.0 → 0.8.0

data/doc/media.md

@@ -0,0 +1,69 @@
+# Media
+
+The [README](../README.md#media) lists the formats badline takes. This
+page covers how device 8 and the true 1541 work, and how to attach media
+from Ruby.
+
+## Device 8 without a drive
+
+Apart from a `.g64`, which only a true drive can read, there is no 1541
+unless `--true-drive` asks for one. Device 8 works by trapping the
+KERNAL's `LOAD` and `SAVE` routines and its serial bus primitives, so
+files open by name through `OPEN` and `CHRIN` as well. `LOAD"$",8` lists
+the directory of any medium mounted there, as a 1541 does.
+
+The command channel answers `I`, `B-P` and `U1` block reads, which
+covers loaders that read blocks directly. On a writable disk image it
+also takes `SAVE` (with `@0:` to replace a file), files opened for
+writing or appending, `S` to scratch, `U2` and `B-W` block writes, and
+`B-A` and `B-F`. It doesn't rename, copy, format or validate disks.
+Loaders that upload their own code to the drive with `M-W` and `M-E`,
+and copy protection that reads raw GCR, won't work there, but do on a
+true drive.
+
+A directory mounted as device 8 serves the `.prg` and `.p00` files in it
+and the contents of any `.t64`, and `SAVE` writes a new `.prg`.
+
+## The true 1541
+
+`--true-drive` puts an emulated 1541 on device 8 instead, running its
+own DOS ROM on its own 6502 and talking to the machine over the serial
+bus. It reads `.d64` and `.g64` images, which it autostarts with the
+same `LOAD"*",8,1` and `RUN`, but not `.d71`, `.d81` or `.t64` images
+or directories. Loading runs at the speed of a real 1541, and the
+drive's red LED lights in the bottom right corner of the border.
+
+A `.g64` holds the disk's raw GCR, half tracks and all, so copy
+protection and fast loaders that read it work.
+
+## Write protection
+
+Disks given on the command line, inserted from the pause menu or by an
+`--at` insert go in write-protected, so the drive reports
+`26,WRITE PROTECT ON` for any write and the image file stays as it was.
+`--writable`, or WRITABLE on the pause menu's Drive page, lets writes go
+straight back to the image file. An image the host can't write, and a
+`.t64`, stay write-protected.
+
+## From Ruby
+
+`Badline::Media.attach(computer, path)` attaches any medium the
+command line takes, and autostarts it unless given `autostart: false`.
+`Badline::Media.insert_disk(computer, path)` swaps the disk image or
+directory in device 8 while the machine runs, for software that asks for
+another disk. Both write to disk images unless told otherwise:
+`insert_disk` takes `read_only: true`, and `attach` takes
+`disk: { read_only: true }`, as the test harnesses under `bin/` do. A
+`.g64` goes in the true 1541, and takes out a disk mounted through the
+traps, so `LOAD` and `SAVE` reach the 1541 too. With the 1541 in device
+8, a `.d64` goes in its drive as well.
+
+`Badline::Media::DiskSet.around(path)` lists the disks of the set a disk
+image belongs to, found by name in its folder, which the pause menu's
+PREVIOUS DISK and NEXT DISK step through.
+
+## The light pen
+
+Control port 1's fire line is also the VIC-II's light pen input, so
+joystick 1's fire button and the 1351's left button in port 1 latch the
+light pen registers.

data/doc/sid-player.md

@@ -0,0 +1,132 @@
+# The SID player
+
+The [README](../README.md#playing-and-rendering-sid-tunes) shows how to
+start it. This page covers the player in detail.
+
+```sh
+badline sid ~/C64Music/MUSICIANS/H/Hubbard_Rob               # play every tune below a directory
+badline sid tune.sid other.sid                               # play a queue of tunes
+badline --headless tune.sid                             # play, length from HVSC
+badline --headless -s 3 tune.sid                        # play the third subtune
+badline --headless --all-subtunes tune.sid              # play on through every subtune
+badline --seconds 180 tune.sid --audio-out out.aiff
+badline -s 3 --rate 48000 tune.sid --audio-out out.wav
+badline --headless --sid 8580 tune.sid
+badline --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slower
+```
+
+## The queue
+
+`badline sid FILE|DIR...` plays a queue of tunes in the SID player's
+window, in the order given, and a directory adds every `.sid` tune below
+it in path order. `badline sid --headless` plays the queue in the
+terminal instead. `badline sid` on its own opens the window with an
+empty queue. Dropping `.sid` files or folders on the window adds them
+to the end of the queue, and an empty queue starts playing them. A file
+that isn't a tune is skipped.
+
+`badline tune.sid` plays the tune in the SID player too, unless an
+option of the emulator's window, such as `--ntsc` or `--reu`, asks for
+the machine: then a tune for one SID runs on the emulated C64, started
+through a small driver after boot.
+
+`--subtune` (or `-s`) picks the first tune's subtune, counting from 1 as
+HVSC does, and defaults to the tune's own start subtune. Each tune plays
+that one subtune, and when it ends the player goes on to the next tune,
+stopping after the last. `a`, or `--all-subtunes`, turns on playing all
+subtunes, so that a subtune that ends goes on to the tune's next
+subtune, and a tune stepped to starts on its first subtune.
+
+`--sid auto`, the default, fits each of a tune's SIDs the model its
+header names. A tune written for 2 or 3 SIDs plays on as many, at the
+addresses its header gives, in stereo: SID 1 on the left, SID 2 on the
+right and SID 3 in the centre. A tune on one SID plays the same on both
+channels.
+
+Playback asks the device for 44.1 kHz and takes whatever rate it
+offers, unless `--rate` says otherwise. Ctrl-C stops it. The emulator
+window's own options, `--no-autostart`, `--writable`, `--sound`,
+`--true-drive`, `--reu`, `--ntsc` and `--verbose`, don't apply.
+
+## The window
+
+The window is worked with the mouse. Its header shows the tune's name,
+author and release, the tune the subtune covers at the moment when
+HVSC's STIL credits one, following the times STIL gives, and buttons
+that switch between three views and between the tune's own SID model,
+the 6581 and the 8580, which changes the chips playing on the spot. Its
+footer shows the time played on a bar you can click to seek, and buttons
+that pause, step between tunes and between a tune's subtunes, and turn
+shuffle, looping and all subtunes on and off.
+
+- The visualizer shows each voice's note, and how far off it is in
+  cents, over a scope of the voice's output, and the mixed output below
+  them. A tune on more than one SID gets a row of voices for each SID,
+  and the mix splits into its left and right.
+- The SID view shows one SID at a time, and for a tune on more than one,
+  a row of SID 1, 2 and 3 buttons at its top picks which. It shows each
+  voice's output, its control bits, pulse width, envelope settings, and
+  the envelope's level and stage, and the filter's modes, cutoff,
+  resonance, volume and its response on the chip playing.
+- The INFO view shows the tune's STIL entry and the subtune's, with a
+  scroll bar, the mouse wheel or the up and down keys for the long ones.
+
+The terminal's keys work in the window too, along with Tab to switch
+views and `c` to step through the SID models.
+
+## The terminal
+
+Played on a terminal, `--headless` and `sid` show each tune's name,
+author and release as it starts, then the tune's place in the queue, the
+subtune number and the time played against the subtune's length.
+`--headless` queues just the one tune.
+
+→ and ← step to the tune's next and previous subtune, stopping at its
+first and last. `n` and `p` step to the next and previous tune. `s`
+turns shuffle on and off, which plays the queue's tunes in a random
+order, and `l` turns looping on and off, so that the end of the queue
+goes on to its start. `,` and `.` seek 10 seconds back and forward
+within the subtune: a seek forward runs on silently from where the
+subtune is, and a seek back plays it again from its start up to the
+point asked for. Space pauses and `q` quits. The status line shows which
+modes are on, and they last until the player quits.
+
+`--no-tui`, or output that isn't a terminal, gives plain progress output
+instead and plays through the queue without the keys.
+
+## Rendering
+
+`--audio-out` renders one subtune to a 16-bit stereo PCM file. The
+file's extension picks the format, `.wav` or `.aiff`.
+
+## Lengths and STIL
+
+A `.sid` file doesn't store its length, so the player looks the tune up
+by MD5 in HVSC's `Songlengths.md5`. It finds the database through
+`--songlengths`, in a `DOCUMENTS` directory in any of the tune's parent
+directories (the layout of an HVSC collection), or under
+`$HVSC_BASE/DOCUMENTS`. Without a database or `--seconds` it runs for 60
+seconds, but a subtune that falls silent for 5 seconds before then ends
+there, when played and when rendered alike. Silent means the output
+holds within 16 steps of one level, since a 6581 idles at a DC offset
+rather than at zero. A subtune with a known length plays to its length
+whatever it sounds like.
+
+A tune in an HVSC collection also gets its entry in HVSC's `STIL.txt`,
+found the same way: comments, covers, and subtune names and composers.
+The tune's own fields follow its header, and each subtune's print as it
+starts.
+
+## Speed
+
+`badline` plays PSID and RSID tunes in real time. In `badline-ruby`,
+PSID tunes run on a CPU and RAM with only the SID clocked, at about
+twice real time, so they play smoothly, but RSID tunes set up their own
+interrupts, so they boot a full C64 first and run at about half real
+time. They render fine but stutter when played, and `badline-ruby` says
+so when it falls behind. Both builds run the same code, so they render
+the same file sample for sample. See
+[native/README.md](../native/README.md#without-the-window).
+
+The filter steps four cycles at a time; `--filter-chunk 1` steps it
+every cycle, which is exact and takes about twice as long.

data/doc/snapshots.md

@@ -0,0 +1,69 @@
+# Snapshots
+
+In the window, `F11` saves the whole machine to a new
+`badline-<date>-<time>.vsf` in the working directory, and `F12` goes
+back to the snapshot last saved or opened, in a new machine built as the
+saved one was. Both executables do this, and both open a `.vsf` given as
+the media. A snapshot that fails to open leaves the machine running as
+it was.
+
+## From Ruby
+
+`computer.save_snapshot(path)` saves, `computer.restore_snapshot(path)`
+takes a machine back to a snapshot, and `Badline::Snapshot.load(path)`
+builds a new machine as the saved one was built and restores it.
+`computer.snapshot` and `computer.restore(state)` do the same in memory,
+without a file. A restore that fails leaves the machine as it was.
+
+## What a snapshot holds
+
+A snapshot holds the machine as it was on the cycle it was saved: the
+chips down to the instruction step and the pixel pipeline, the RAM and
+any +60K or +256K expansion, the cartridge with its RAM and flash, a
+GEO-RAM, a true 1541 with its RAM, its VIAs and the disk under the head,
+a disk or directory mounted through the traps with its open channels,
+and the tape with its place on it. A restored machine runs on exactly
+as the saved one would have.
+
+A directory, a tape and a true drive's disk image open again from their
+paths when the snapshot is restored, the disk with its tracks as the
+drive last saw them. A disk image mounted through the traps comes back
+with its contents from the snapshot. What the host holds stays the
+host's: the keyboard, the joysticks, the mouse and paddles, sound, and
+blocks given to `on_init` that hadn't run yet, which a restore reports.
+
+A snapshot only restores in the badline version that wrote it, into a
+machine with the same chip models, RAM expansion and REU.
+`computer.snapshot` holds an REU's RAM, registers and transfer too, but
+a machine with an REU doesn't save to a file yet, as badline doesn't
+write VICE's REU module. Nor does an NTSC machine, as badline doesn't
+write an NTSC VIC-II in VICE's terms yet.
+
+## VICE
+
+Snapshots use VICE's `.vsf` format. badline writes VICE's modules for
+the CPU, RAM and CPU port, both CIAs, the SID and the VIC-II, plus the
+ones x64sc needs to open the file, with nothing attached to the
+cartridge, tape or user ports and no true drive. A `BADLINE` module,
+which VICE skips, holds the whole machine, and badline restores its own
+snapshots from it.
+
+x64sc 3.10 opens badline's snapshots, taken at the end of the
+instruction the CPU was in, as long as its VIC-II model matches
+(`-model c64` for the default machine). It keeps its own drives and
+leaves out the cartridge, the expansions and the tape.
+
+Snapshots x64sc saves open in badline through the same modules: the CPU
+at its instruction boundary, RAM, the CPU port, the CIAs' registers,
+timers and clocks, the SID's registers and reSID voice state, and the
+VIC-II's registers, beam position, counters and colour RAM. The VIC-II's
+pixel pipeline starts empty. badline reads the modules x64sc 3.7 to 3.10
+write, and VICE's development versions' `MAINC64CPU` and `VIC-IISC`. A
+module version it doesn't know is left out, or fails the restore for the
+CPU and RAM. It reports the modules it leaves out, such as the 1541
+drives, the cartridge, the datasette and the keyboard, and carries on
+without them. A snapshot of an NTSC machine fails, as badline reads only
+VICE's PAL VIC-II. Restored into a running machine, a VICE snapshot
+fails for a machine built another way, such as a C64C's snapshot in a
+C64, and otherwise takes the cartridge out and switches the machine off
+and on.

data/lib/badline/cartridge/freezer.rb

@@ -8,6 +8,8 @@ module Badline
     # cartridge ROM in Ultimax mode. The cartridge lets go of NMI when its
     # software acknowledges the freeze.
     module Freezer
+      def freezer? = true
+
       def press_button
         @button = true
         self.nmi = true if freeze_allowed?

data/lib/badline/cartridge.rb

@@ -179,6 +179,9 @@ module Badline
     # The RES line on the expansion port.
     def reset; end
 
+    # Whether the cartridge has a freeze button.
+    def freezer? = false
+
     # The freeze button, which cartridges without one ignore.
     def press_button; end
 

data/lib/badline/frontend/app.rb

@@ -7,8 +7,8 @@ module Badline
     # changed lines, present and wait. Pacer decides the cycles and the wait.
     class App
       SCALE = 2
+      DROPFILE = 0x1000
       TITLE = "Badline"
-      STAGES = %w[events emulate audio blit present wait].freeze
 
       # Takes the frame limit, the pacing, the snapshot path, the sound and
       # the verbosity from Options, and runs the timeline's events.
@@ -22,11 +22,11 @@ module Badline
         @screen = Screen.new(computer.vic)
         @led = DriveLed.for(computer)
         @controls = Controls.new(computer)
-        @spent = Array.new(STAGES.size, 0.0)
-        @slowest = 0.0
         open_window
         @sound = Sound.new(computer.sid, options.sound?, @verbose)
         @gamepads = Gamepads.new(computer, @verbose)
+        @frame_report = FrameReport.new(@sound)
+        @menu = PauseMenu.new(Painter.new(@renderer), options)
       end
 
       def run
@@ -34,8 +34,7 @@ module Badline
         @running = true
         @started = @reported = now
         @pacer.start(@started)
-        @reported_samples = 0
-        frame while @running
+        @menu.open? ? paused_frame : frame while @running
         @snapshots.finish
         @computer.drive1541&.flush
         @gamepads.close
@@ -64,9 +63,7 @@ module Badline
       end
 
       def finish_frame(stamps)
-        STAGES.size.times { |stage| @spent[stage] += stamps[stage + 1] - stamps[stage] }
-        took = stamps[-2] - stamps.first
-        @slowest = took if took > @slowest
+        @frame_report.add(stamps) if @verbose
         @frames += 1
         @timeline.run(@computer, @frames)
         @running = false if @frames == @frame_limit || @timeline.quit?(@frames)
@@ -95,8 +92,6 @@ module Badline
         @texture = SDL.SDL_CreateTexture(
           @renderer, SDL::PIXELFORMAT_RGB888, SDL::TEXTUREACCESS_STREAMING, Screen::WIDTH, Screen::HEIGHT
         )
-        SDL.rect_w(SDL.rect, Screen::WIDTH)
-        SDL.rect_h(SDL.rect, Screen::HEIGHT)
       end
 
       def close_window
@@ -107,7 +102,7 @@ module Badline
       end
 
       def handle_events
-        handle_event(SDL.event_type(SDL.event)) while SDL.SDL_PollEvent(SDL.event) != 0
+        handle_event(SDL.event_type(SDL.event)) while !@menu.open? && SDL.SDL_PollEvent(SDL.event) != 0
       end
 
       def handle_event(type)
@@ -122,6 +117,7 @@ module Badline
           @controls.mouse_button(SDL.event_button(SDL.event), type == SDL::MOUSEBUTTONDOWN)
         when SDL::CONTROLLERDEVICEADDED, SDL::CONTROLLERDEVICEREMOVED
           @gamepads.rescan
+        when DROPFILE then resume(false) unless @menu.drop(@computer, @controls, @sound)
         end
       end
 
@@ -145,20 +141,45 @@ module Badline
         @controls.computer = computer
         @gamepads.computer = computer
         @sound.sid = computer.sid
+        @snapshots.computer = computer
       end
 
       def handle_toggle(scancode)
         if scancode == Keys::TAB
-          @controls.cycle_mode(SDL.event_mod(SDL.event).anybits?(SDL::KMOD_SHIFT) ? -1 : 1)
-          SDL.SDL_SetRelativeMouseMode(@controls.pot_device? ? 1 : 0)
+          @controls.toggle_keys
         elsif scancode == Keys::F9
-          @controls.swap_ports
+          return open_menu
         else
           @sound.toggle_mute
         end
         update_title
       end
 
+      def open_menu = @menu.show(@computer, @controls, @sound)
+
+      # Closes the menu and runs the machine on from where it stood,
+      # pressing the cartridge's freeze button if asked.
+      def resume(freeze)
+        @menu.close
+        SDL.SDL_SetRelativeMouseMode(@controls.pot_device? ? 1 : 0)
+        @timeline.press_freeze(@computer, @frames) if freeze
+        @reported = now
+        @pacer.start(@reported)
+        update_title
+      end
+
+      # Runs a frame of the menu, which has the keys and the mouse while the
+      # machine stands still.
+      def paused_frame
+        action = @menu.frame(@renderer, @texture, @controls)
+        if action == :quit
+          @running = false
+        elsif !action.nil?
+          swap(@menu.computer) if action == :swap
+          resume(action == :freeze)
+        end
+      end
+
       def update_title
         title = TITLE
         title += " [#{@controls.tag}]" unless @controls.tag.empty?
@@ -183,12 +204,12 @@ module Badline
 
       def upload
         @screen.update
-        SDL.SDL_UpdateTexture(@texture, SDL.rect, @screen.pixels, Screen::ROW_BYTES)
+        SDL.SDL_UpdateTexture(@texture, nil, @screen.pixels, Screen::ROW_BYTES)
       end
 
       def draw
         SDL.SDL_RenderClear(@renderer)
-        SDL.SDL_RenderCopy(@renderer, @texture, SDL.rect, SDL.rect)
+        SDL.SDL_RenderCopy(@renderer, @texture, nil, nil)
         @led&.draw(@renderer)
         @timeline.screenshots(@frames + 1).each { |path| Screenshot.write(@renderer, path) }
         SDL.SDL_RenderPresent(@renderer)
@@ -197,28 +218,10 @@ module Badline
       def report(at)
         @pacer.check(50, at - @reported, at)
         @pacer.measure(50, at - @reported)
-        report_frames(at) if @verbose
-        @spent = Array.new(STAGES.size, 0.0)
-        @slowest = 0.0
+        @frame_report.show(at - @reported) if @verbose
         @reported = at
       end
 
-      def report_frames(at)
-        fps = 50 / (at - @reported)
-        stages = STAGES.each_with_index.map { |name, stage| "#{name} #{(@spent[stage] * 20).round(2)}" }
-        puts "#{fps.round(1)} fps, per frame ms: #{stages.join(' ')}, slowest work #{(@slowest * 1000).round(2)}"
-        report_sound(at) if @sound.on?
-      end
-
-      def report_sound(at)
-        sound = @sound
-        rate = (sound.queued - @reported_samples) / (at - @reported)
-        queue = sound.high.zero? ? "empty" : "#{(sound.low * 1000).round(1)}-#{(sound.high * 1000).round(1)} ms"
-        puts "  sound #{rate.round} samples/s, queue #{queue}, #{sound.underruns} underruns, #{sound.dropped} dropped"
-        sound.reset_levels
-        @reported_samples = sound.queued
-      end
-
       def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end

data/lib/badline/frontend/boot.rb

@@ -39,12 +39,19 @@ module Badline
         return computer
       end
 
+      start(options, media, options.writable?)
+    end
+
+    # A new machine built from the options, with `media`, if not nil,
+    # attached and started as the command line does, its disk writable if
+    # `writable`.
+    def self.start(options, media, writable)
       computer = Computer.new(sid_model: options.sid_model || Media.sid_model(media), reu: options.reu,
                               region: options.ntsc? ? Region::NTSC : Region::PAL)
       Media::TrueDrive.plug(computer) if options.true_drive?
       unless media.nil?
         puts Media.attach(computer, media, autostart: options.autostart?, subtune: options.subtune,
-                                           disk: { read_only: options.read_only? })
+                                           disk: { read_only: !writable })
       end
       computer
     end

data/lib/badline/frontend/buttons.rb

@@ -5,27 +5,43 @@ module Badline
     # The SID player's buttons: each is drawn where it goes on every frame,
     # and remembers its place, so a click finds the action under it. The
     # one under the pointer lights up, and one that's on is drawn reversed.
+    # They take the player's colours unless given others: the text, the text
+    # under the pointer, the background and, if any, a fill behind each
+    # button.
     class Buttons
       PAD = 2
       HEIGHT = Painter::GLYPH + (PAD * 2)
 
-      def initialize(painter)
+      def initialize(painter, colors = [SIDView::TEXT, SIDView::BRIGHT, PlayerScreen::BACKGROUND])
         @painter = painter
+        @text = colors[0]
+        @bright = colors[1]
+        @back = colors[2]
+        @fill = colors.size > 3 ? colors[3] : -1
         @lefts = []
         @tops = []
         @widths = []
         @heights = []
         @actions = []
+        @focusable = []
+        @toggles = {}
         @pointer_x = -1
         @pointer_y = -1
+        @focus = nil
       end
 
+      # The action of the button the keys have moved to, which lights up as
+      # the one under the pointer does, or nil.
+      attr_accessor :focus
+
       def forget
         @lefts.clear
         @tops.clear
         @widths.clear
         @heights.clear
         @actions.clear
+        @focusable.clear
+        @toggles.clear
       end
 
       def point(left, top)
@@ -38,11 +54,54 @@ module Badline
       def text(left, top, label, action, on: false)
         width = Painter.width(label) + (PAD * 2)
         place(left, top, width, HEIGHT, action)
-        @painter.box(left, top, width, HEIGHT, SIDView::TEXT) if on
-        @painter.text(left + PAD, top + PAD, label, on ? PlayerScreen::BACKGROUND : color(@actions.size - 1))
+        @painter.box(left, top, width, HEIGHT, @fill) if !on && @fill >= 0
+        @painter.box(left, top, width, HEIGHT, action == @focus ? @bright : @text) if on
+        @painter.text(left + PAD, top + PAD, label, on ? @back : color(@actions.size - 1))
         width
       end
 
+      # Draws a button as #text does, without the fill.
+      def plain(left, top, label, action, on: false)
+        fill = @fill
+        @fill = -1
+        width = text(left, top, label, action, on:)
+        @fill = fill
+        width
+      end
+
+      # Draws a button as wide as `box`, its left and top and width, with
+      # `label` at its left and `value`, if any, at its right, as a menu's
+      # row.
+      def row(box, label, action, value = "")
+        left = box[0]
+        top = box[1]
+        width = box[2]
+        place(left, top, width, HEIGHT, action)
+        @painter.box(left, top, width, HEIGHT, @fill) if @fill >= 0
+        color = color(@actions.size - 1)
+        @painter.text(left + PAD, top + PAD, label, color)
+        @painter.text(left + width - PAD - Painter.width(value), top + PAD, value, color) unless value.empty?
+      end
+
+      # Draws a row as #row does, with its choices at its right, `choices`
+      # holding their labels, their actions and the index of the one on.
+      # A click picks a choice, and pressing the row, `action`, picks the
+      # next, which #resolve gives.
+      def toggle(box, label, action, choices)
+        row(box, label, action)
+        labels = choices[0]
+        @toggles[action] = choices[1][(choices[2] + 1) % labels.size]
+        right = box[0] + box[2] - PAD
+        index = labels.size - 1
+        while index >= 0
+          width = Painter.width(labels[index]) + (PAD * 2)
+          right -= width
+          choice(right, box[1], labels[index], choices[1][index], index == choices[2])
+          right -= 2
+          index -= 1
+        end
+      end
+
       # Draws an icon button `scale` times the size of a glyph, and returns
       # its width.
       def icon(left, top, name, action, scale: 1)
@@ -58,17 +117,42 @@ module Badline
         place(box[0], box[1], box[2], box[3], action)
       end
 
-      # The action of the button at `left`, `top`, or nil.
+      # The action of the button at `left`, `top`, or nil: a toggle's
+      # choice before the row it sits on.
       def action_at(left, top)
+        found = nil
         index = 0
         while index < @actions.size
-          return @actions[index] if inside?(index, left, top)
+          if inside?(index, left, top)
+            return @actions[index] unless @focusable[index]
 
+            found ||= @actions[index]
+          end
           index += 1
         end
-        nil
+        found
       end
 
+      # Moves the focus `delta` buttons on, among those drawn from the
+      # `first` on, stopping at either end.
+      def shift(delta, first)
+        return if @actions.size <= first
+
+        focusable = []
+        (first...@actions.size).each { |index| focusable << @actions[index] if @focusable[index] }
+        return if focusable.empty?
+
+        from = focusable.index(@focus)
+        @focus = focusable[from.nil? ? 0 : (from + delta).clamp(0, focusable.size - 1)]
+      end
+
+      # The action pressing a button stands for: for a toggle's row, its
+      # next choice's.
+      def resolve(action) = @toggles.fetch(action, action)
+
+      # The action of the button drawn `index`th, or nil.
+      def action(index) = @actions[index]
+
       private
 
       def place(left, top, width, height, action)
@@ -77,9 +161,19 @@ module Badline
         @widths << width
         @heights << height
         @actions << action
+        @focusable << true
+      end
+
+      # A choice of a toggle, which a click picks but the keys pass by.
+      def choice(left, top, label, action, on)
+        width = Painter.width(label) + (PAD * 2)
+        place(left, top, width, HEIGHT, action)
+        @focusable[-1] = false
+        @painter.box(left, top, width, HEIGHT, @text) if on
+        @painter.text(left + PAD, top + PAD, label, on ? @back : color(@actions.size - 1))
       end
 
-      def color(index) = inside?(index, @pointer_x, @pointer_y) ? SIDView::BRIGHT : SIDView::TEXT
+      def color(index) = inside?(index, @pointer_x, @pointer_y) || @actions[index] == @focus ? @bright : @text
 
       def inside?(index, left, top)
         left >= @lefts[index] && left < @lefts[index] + @widths[index] &&