tuile 0.15.0 → 0.16.0

data/lib/tuile/component/text_field.rb

@@ -22,7 +22,7 @@ module Tuile
     # - an **index** counts characters into {#text} — {#caret},
     #   {#max_text_length}, `text[i]`, every edit;
     # - a **column** counts terminal cells — {#rect}, {#cursor_position}, a
-    #   {MouseEvent}, and the private horizontal scroll offset `left_column`.
+    #   {Mouse::DownEvent}, and the private horizontal scroll offset `left_column`.
     #
     # They coincide only while every glyph is one column wide. A fullwidth CJK
     # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
@@ -103,15 +103,15 @@ module Tuile
         Point.new(rect.left + offset, rect.top)
       end
 
-      # Places the caret at the clicked column. A click on the right half of a
+      # Places the caret at the pressed column. A press on the right half of a
       # wide glyph lands *after* it, as in any editor.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && rect.contains?(event.point)
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         self.caret = index_at(event.x - rect.left + @left_column)
+        true
       end
 
       # @return [void]
@@ -129,7 +129,7 @@ module Tuile
       # "clear what I typed".
       # @param key [String]
       # @return [Boolean]
-      def handle_text_input_key(key)
+      def handle_text_input_key?(key)
         case key
         when *Keys::HOMES then self.caret = 0
         when *Keys::ENDS_ then self.caret = @text.length
@@ -159,7 +159,7 @@ module Tuile
       # Keeps the paste's **first line** and drops the rest, then trims what's
       # left to what {#max_text_length} still allows:
       #
-      #   f.handle_paste("name\nstreet\ncity")   # => true
+      #   f.handle_paste("name\nstreet\ncity")
       #   f.text                                 # => "name"
       #
       # Overshooting the cap trims rather than rejects, which is what typing the
@@ -175,17 +175,19 @@ module Tuile
       end
 
       # @return [void]
-      def on_text_mutated
+      def handle_text_mutated
+        super
         adjust_left_column
       end
 
       # @return [void]
-      def on_caret_mutated
+      def handle_caret_mutated
+        super
         adjust_left_column
       end
 
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         adjust_left_column
       end

data/lib/tuile/component/text_view.rb

@@ -20,8 +20,8 @@ module Tuile
     # splice a range in place. Turn on {#auto_scroll} to keep the latest content
     # in view.
     #
-    # Meant to be the content of a {Window} — focus indication and keyboard-hint
-    # surfacing rely on the surrounding window chrome.
+    # Meant to be the content of a {Window} — focus indication relies on the
+    # surrounding window chrome.
     class TextView < Component
       def initialize
         super
@@ -354,7 +354,7 @@ module Tuile
       # an unfocused view scrolls it (dispatch gates on focus, this doesn't).
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         case key
         when *Keys::DOWN_ARROWS then move_scroll_top_row_by(1)
         when *Keys::UP_ARROWS   then move_scroll_top_row_by(-1)
@@ -369,14 +369,18 @@ module Tuile
         true
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        case event.button
-        when :scroll_down then move_scroll_top_row_by(4)
-        when :scroll_up   then move_scroll_top_row_by(-4)
+      # Scrolls four rows a notch, and declines — so the notch bubbles to an
+      # ancestor scroller — once this view is at that end of its text.
+      # @param event [Mouse::ScrollEvent]
+      # @return [Boolean]
+      def handle_mouse_scroll?(event)
+        before = scroll_top_row
+        case event.direction
+        when :down then move_scroll_top_row_by(4)
+        when :up   then move_scroll_top_row_by(-4)
+        else return false
         end
+        scroll_top_row != before
       end
 
       # Paints the text into {#rect}.
@@ -405,7 +409,7 @@ module Tuile
       # minus {#scrollbar_columns}, and the latter varies with the width too.
       # A {#scrollbar_visibility=} flip rewraps from its own setter instead.
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         rewrap
       end

data/lib/tuile/component/time_field.rb

@@ -58,6 +58,19 @@ module Tuile
     # the field (or pressing ENTER) reddens what did not parse, and the next
     # edit clears it again.
     #
+    # == The value notice waits for the same gesture
+    # A prefix of a time can also parse *cleanly*: typing `13:45` passes
+    # through `13:4`, a perfectly good four minutes past one. So
+    # {HasValue#on_value_change} does not fire per keystroke, but when the user
+    # leaves the field or presses ENTER — and a form recalculating from it
+    # never sees those intermediate readings.
+    #
+    # {#value} does *not* wait: it is a live parse of the buffer at every
+    # moment, so a save gate reached without leaving the field reads the time
+    # on screen. Nor does a change nobody had to type — a {#value=}, a
+    # {#set_to}, an arrow-key step, a {#clear} and a reparse under a new
+    # {#step} all fire as they happen.
+    #
     # == Implementation details
     # - **The buffer is the single source of truth.** {#value} is a parse of it,
     #   recomputed on read — so {#step=} and a {Screen#locale=} can change the
@@ -182,6 +195,9 @@ module Tuile
       def value=(new_value)
         editor.text = new_value.nil? ? "" : coerce(new_value).strftime(formats.first)
         editor.caret = editor.text.length
+        # The edit above announced nothing ({#notify_on_edit?}); a time written
+        # rather than typed has no prefix to be mistaken for a value.
+        fire_if_changed
       end
 
       # Sets the value from its parts, so nothing assembles a `Time` on the
@@ -234,7 +250,7 @@ module Tuile
       #
       # Why precision rides the stride rather than a knob of its own, and what
       # that costs — seconds with a minute stride is unsayable — is
-      # `DECISIONS.md` `D_time_field`.
+      # `design/decisions.md` `D_time_field`.
       #
       # @param seconds [Integer] 1 up to (not including) a full day.
       # @return [void]
@@ -309,7 +325,7 @@ module Tuile
       # @param key [String]
       # @return [Boolean] `true` for the two page keys, else whatever `super`
       #   returns.
-      def handle_key(key)
+      def handle_key?(key)
         case key
         when Keys::PAGE_UP then step_by(SECONDS_PER_HOUR)
         when Keys::PAGE_DOWN then step_by(-SECONDS_PER_HOUR)
@@ -330,6 +346,12 @@ module Tuile
         settle(true)
       end
 
+      # `false`: a prefix of a time can parse cleanly (`13:4` for `13:45`), so
+      # the notice settles onto the commit gestures, exactly as the ink does.
+      # The class docs carry the case.
+      # @return [Boolean]
+      def notify_on_edit? = false
+
       # Every prefix of a time is bad input, so the well is latched to the
       # commit gestures instead of painted per keystroke: `1`, `13`, `13:` on
       # the way to `13:45` never redden, and a time the field cannot parse
@@ -341,10 +363,13 @@ module Tuile
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
       # @return [void]
-      def on_editor_change = settle(false)
+      def handle_editor_change
+        super
+        settle(false)
+      end
 
       # @return [void]
-      def on_locale_changed
+      def handle_locale_changed
         super
         reformat
       end