tuile 0.15.0 → 0.16.0

data/book/10-locale.md

@@ -181,7 +181,7 @@ forever.
 
 ## When the locale changes under you
 
-{Tuile::Screen#locale=} fires {Tuile::Component#on_locale_changed}
+{Tuile::Screen#locale=} fires {Tuile::Component#handle_locale_changed}
 across the attached tree and then invalidates all of it — the same
 machinery {Tuile::Screen#theme=} uses, for the same reason.
 
@@ -194,7 +194,7 @@ The hook is for state you *pushed* somewhere when you last read the
 conventions. A date field's typing hint is the worked example: it lives
 in its editor's `placeholder`, written when the formats were last set, so
 a repaint alone would faithfully repaint the stale `dd.mm.yyyy`. The
-field overrides `on_locale_changed` to re-derive it — and, while it is
+field overrides `handle_locale_changed` to re-derive it — and, while it is
 there, to rewrite a buffer that still parses into the new primary format.
 Your own code does the same for a date you rendered into a
 {Tuile::Component::Label}, either by overriding the hook or by assigning

data/book/README.md

@@ -65,16 +65,17 @@ one, not to fill an outline.
    same queue rather than handled off the signal.
 5. **[Focus and the keyboard](05-focus.md).** The focus chain and
    `focusable?`, and the three-rung order in which a keystroke is offered
-   to the tree — Tab, global shortcuts, then `handle_key` delivered to
+   to the tree — Tab, global shortcuts, then `handle_key?` delivered to
    focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
    form's default button) belong on an ancestor, why a paste rides its own
-   path rather than the ladder, and how to write a status line over
-   `on_focus_changed` — Tuile draws none for you.
+   path rather than the ladder, and how the mouse takes a road of its own —
+   a press bubbling to one claimant that is then grabbed. Ends on writing a
+   status line over `on_focus_changed` — Tuile draws none for you.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
    time, opt-in component backgrounds that inherit down the tree
    (`bg_color`), light/dark auto-detection at startup and live OS
    appearance flips, pairing variants in a `ThemeDef`, app-specific custom
-   tokens, and rebuilding theme-derived content in `on_theme_changed`.
+   tokens, and rebuilding theme-derived content in `handle_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
    the shipped toolbox — the text inputs and views, the value fields, the
    selectors, Button, ProgressBar, Window, TabSheet, MenuBar, Popup and the
@@ -94,5 +95,5 @@ one, not to fill an outline.
    never prose*, detected from `locale(1)` only when the environment
    actually asked, with `Locale::ISO` as the floor. Why the name tables
    are keyed by the `Date` accessor that reads them, how a field follows
-   the session until you override it, and what `on_locale_changed` is
+   the session until you override it, and what `handle_locale_changed` is
    for.

data/examples/file_commander.rb

@@ -20,6 +20,14 @@ require "rainbow"
 require "tuile"
 
 module FileCommanderExample
+  # `hint` is the app's token, not Tuile's — the framework carries accents only
+  # for the chrome it paints itself, and the status line below is ours. Paired
+  # in a ThemeDef so it survives an OS appearance flip.
+  APP_THEME = Tuile::ThemeDef.new(
+    dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
+    light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+  )
+
   # Pastel X11 colors chosen to read on a black background.
   TYPE_COLORS = {
     directory: :lightskyblue,
@@ -45,7 +53,7 @@ module FileCommanderExample
     attr_reader :cwd
     attr_accessor :on_cwd_changed
 
-    def handle_key(key)
+    def handle_key?(key)
       return false unless active?
 
       if Tuile::Keys::BACKSPACES.include?(key)
@@ -56,7 +64,7 @@ module FileCommanderExample
       end
     end
 
-    def on_focus
+    def handle_focus
       super
       @on_cwd_changed&.call
     end
@@ -135,13 +143,13 @@ module FileCommanderExample
       # The status line. Every key here works in both panes, so the row never
       # changes and nothing needs to watch focus — a status line is only worth
       # wiring to Tuile::Screen#on_focus_changed= when its text actually varies
-      # with the focused component. `theme.hint` bakes its colors in, so the
+      # with the focused component. `theme.fg` bakes its colors in, so the
       # one thing this label does watch is a light/dark flip.
       @status = Tuile::Component::Label.new
       render_status = lambda do
         t = screen.theme
-        @status.text = "q #{t.hint("quit")}  Tab #{t.hint("Switch")}  " \
-                       "Enter #{t.hint("Open")}  Bksp #{t.hint("Up")}"
+        @status.text = "q #{t.fg(:hint, "quit")}  Tab #{t.fg(:hint, "Switch")}  " \
+                       "Enter #{t.fg(:hint, "Open")}  Bksp #{t.fg(:hint, "Up")}"
       end
       render_status.call
       @status.on_theme_changed = render_status
@@ -180,6 +188,7 @@ unless File.directory?(start_dir)
 end
 
 screen = Tuile::Screen.new
+screen.theme_def = FileCommanderExample::APP_THEME
 commander = FileCommanderExample::FileCommander.new(start_dir, start_dir)
 screen.content = commander
 commander.left_window.focus

data/examples/hello_world.rb

@@ -11,18 +11,31 @@
 
 require "tuile"
 
+# `hint` is the app's token, not Tuile's: the framework carries accents for the
+# chrome *it* paints, and a status line is the app's own (Tuile draws none).
+# Pairing the two shades in a ThemeDef is what makes it survive the user
+# flipping OS appearance — a bare `theme=` would be replaced on the next flip.
+# Both greys quantize to :bright_black on a 16-color terminal, so the
+# description stays dimmer than the key beside it even there.
+APP_THEME = Tuile::ThemeDef.new(
+  dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
+  light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+)
+
 # Screen must exist before any Component is built: components reach for
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
+screen.theme_def = APP_THEME
 
 window = Tuile::Component::Window.new("Tuile")
 window.content = Tuile::Component::Label.new("Hello, world!")
 
-# The status line. `theme.hint` styles the *description* half of a "key what"
-# pair, and bakes the color in — so the label rebuilds itself from
-# `on_theme_changed` to follow a light/dark flip.
+# The status line. `theme.fg` styles the *description* half of a "key what"
+# pair — dimmed, so the key is the element that pulls the eye — and bakes the
+# color in, so the label rebuilds itself from its `on_theme_changed` slot to follow a
+# light/dark flip.
 status = Tuile::Component::Label.new
-render_status = -> { status.text = "q #{screen.theme.hint("quit")}" }
+render_status = -> { status.text = "q #{screen.theme.fg(:hint, "quit")}" }
 render_status.call
 status.on_theme_changed = render_status