teek 0.1.1 → 0.1.3

data/lib/teek.rb

@@ -4,6 +4,7 @@ require 'tcltklib'
 require_relative 'teek/version'
 require_relative 'teek/ractor_support'
 require_relative 'teek/widget'
+require_relative 'teek/photo'
 
 # Ruby interface to Tcl/Tk. Provides a thin wrapper around a Tcl interpreter
 # with Ruby callbacks, event bindings, and background work support.
@@ -47,13 +48,15 @@ module Teek
 
   class App
     attr_reader :interp, :widgets, :debugger
+    attr_writer :_pending_exception # @api private
 
-    def initialize(track_widgets: true, debug: false, &block)
+    def initialize(title: nil, track_widgets: true, debug: false, &block)
       @interp = Teek::Interp.new
       @interp.tcl_eval('package require Tk')
       hide
       @widgets = {}
       @widget_counters = Hash.new(0)
+      @_pending_exception = nil
       debug ||= !!ENV['TEEK_DEBUG']
       track_widgets = true if debug
       setup_widget_tracking if track_widgets
@@ -61,6 +64,7 @@ module Teek
         require_relative 'teek/debugger'
         @debugger = Teek::Debugger.new(self)
       end
+      set_window_title(title) if title
       instance_eval(&block) if block
     end
 
@@ -118,14 +122,24 @@ module Teek
 
     # Schedule a one-shot timer. Calls the block after +ms+ milliseconds.
     # @param ms [Integer] delay in milliseconds
+    # @param on_error [:raise, Proc, nil] error handling strategy:
+    #   - +:raise+ (default) — exception propagates to Tcl background error handler.
+    #   - +Proc+ — called with the exception; error is swallowed.
+    #   - +nil+ — error is silently swallowed.
     # @yield block to call when the timer fires
     # @return [String] timer ID, pass to {#after_cancel} to cancel
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/after.htm#M5 after ms
-    def after(ms, &block)
+    def after(ms, on_error: :raise, &block)
       cb_id = nil
       cb_id = @interp.register_callback(proc { |*|
-        block.call
-        @interp.unregister_callback(cb_id)
+        begin
+          block.call
+        rescue => e
+          raise if on_error == :raise
+          on_error.call(e) if on_error.is_a?(Proc)
+        ensure
+          @interp.unregister_callback(cb_id)
+        end
       })
       after_id = @interp.tcl_eval("after #{ms.to_i} {ruby_callback #{cb_id}}")
       after_id.instance_variable_set(:@cb_id, cb_id)
@@ -147,6 +161,33 @@ module Teek
       after_id
     end
 
+    # Schedule a repeating timer. Calls the block every +ms+ milliseconds
+    # until cancelled. The block runs on the main thread in the event loop,
+    # so it must be fast (don't block the UI).
+    #
+    # @param ms [Integer] interval in milliseconds
+    # @param on_error [:raise, Proc, nil] error handling strategy:
+    #   - +:raise+ (default) — cancels the timer and raises the exception
+    #     from the next call to {#update}.
+    #   - +Proc+ — called with the exception; timer keeps running.
+    #   - +nil+ — cancels the timer silently; error stored in {RepeatingTimer#last_error}.
+    # @yield block to call on each tick
+    # @return [RepeatingTimer] cancel handle
+    #
+    # @example Basic polling loop
+    #   timer = app.every(50) { update_display }
+    #   timer.cancel  # stop later
+    #
+    # @example With error handler (timer keeps running)
+    #   timer = app.every(100, on_error: ->(e) { log(e) }) { risky_work }
+    #
+    # @example Silent cancel on error
+    #   timer = app.every(50, on_error: nil) { maybe_fails }
+    #   timer.last_error  # => check later
+    def every(ms, on_error: :raise, &block)
+      RepeatingTimer.new(self, ms, on_error: on_error, &block)
+    end
+
     # Cancel a pending {#after} or {#after_idle} timer.
     # @param after_id [String] timer ID returned by {#after} or {#after_idle}
     # @return [void]
@@ -313,7 +354,8 @@ module Teek
     # @param widget [String] Tk widget path (e.g. ".frame1")
     # @return [void]
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/destroy.htm destroy
-    def destroy(widget)
+    def destroy(widget = '.')
+      raise ArgumentError, 'widget path cannot be nil' if widget.nil?
       tcl_eval("destroy #{widget}")
     end
 
@@ -388,6 +430,10 @@ module Teek
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/update.htm update
     def update
       @interp.tcl_eval('update')
+      if (e = @_pending_exception)
+        @_pending_exception = nil
+        raise e
+      end
     end
 
     # Process only pending idle callbacks (e.g. geometry redraws), then return.
@@ -413,6 +459,44 @@ module Teek
       @interp.tcl_eval("wm withdraw #{window}")
     end
 
+    # Enable the Tk debug console. The console starts hidden and can be
+    # toggled with the given keyboard shortcut (default: F12).
+    #
+    # The Tk console is a built-in interactive Tcl shell — useful for
+    # inspecting variables, running Tcl commands, and debugging widget
+    # layouts at runtime. It is available on macOS and Windows only;
+    # on Linux this method is a no-op (Linux has the real terminal).
+    #
+    # @param keybinding [String] Tk event to toggle the console
+    #   (default: "<F12>")
+    # @return [Boolean] true if the console was created, false if
+    #   unavailable on this platform
+    # @example
+    #   app = Teek::App.new
+    #   app.add_debug_console            # F12 toggles console
+    #   app.add_debug_console("<F11>")   # custom key
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/console.htm console
+    def add_debug_console(keybinding = '<F12>')
+      @interp.create_console
+      @_console_visible = false
+
+      toggle = proc do |*|
+        if @_console_visible
+          tcl_eval('console hide')
+          @_console_visible = false
+        else
+          tcl_eval('console show')
+          @_console_visible = true
+        end
+      end
+
+      command(:bind, '.', keybinding, toggle)
+      true
+    rescue TclError => e
+      warn "Teek: debug console not available on this platform (#{e.message})"
+      false
+    end
+
     # Set a window's title.
     # @param title [String] new title
     # @param window [String] Tk window path
@@ -673,9 +757,122 @@ module Teek
         "{ruby_callback #{id}}"
       when Symbol
         value.to_s
+      when Array
+        "{#{value.map { |v| tcl_value(v) }.join(' ')}}"
       else
         "{#{value}}"
       end
     end
   end
+
+  # A cancellable repeating timer that fires on the main thread.
+  #
+  # Created via {App#every}. Reschedules itself after each tick using
+  # Tcl's +after+ command. The block runs in the event loop, so it
+  # must complete quickly to avoid blocking the UI.
+  #
+  # Tracks timing drift: if a tick fires significantly late (more than
+  # 2x the interval), a warning is printed to stderr. This helps catch
+  # blocks that are too slow for the requested interval.
+  #
+  # @see App#every
+  class RepeatingTimer
+    # @return [Integer] interval in milliseconds
+    attr_reader :interval
+
+    # @return [Exception, nil] the last error if the timer stopped due to an
+    #   unhandled exception, nil otherwise
+    attr_reader :last_error
+
+    # @return [Integer] number of ticks that fired late (> 2x interval)
+    attr_reader :late_ticks
+
+    # @api private
+    def initialize(app, ms, on_error: nil, &block)
+      raise ArgumentError, "interval must be positive, got #{ms}" if ms <= 0
+
+      @app = app
+      @interval = ms
+      @block = block
+      @on_error = on_error
+      @cancelled = false
+      @after_id = nil
+      @last_error = nil
+      @late_ticks = 0
+      @next_expected = nil
+      schedule
+    end
+
+    # Stop the timer. Safe to call multiple times.
+    # @return [void]
+    def cancel
+      return if @cancelled
+      @cancelled = true
+      @app.after_cancel(@after_id) if @after_id
+      @after_id = nil
+    end
+
+    # @return [Boolean] true if the timer has been cancelled
+    def cancelled?
+      @cancelled
+    end
+
+    # Change the interval. Takes effect on the next tick.
+    # @param ms [Integer] new interval in milliseconds
+    def interval=(ms)
+      raise ArgumentError, "interval must be positive, got #{ms}" if ms <= 0
+      @interval = ms
+    end
+
+    private
+
+    def schedule
+      return if @cancelled
+      @next_expected = now_ms + @interval
+      @after_id = @app.after(@interval) { tick }
+    end
+
+    def tick
+      return if @cancelled
+      check_drift
+      @block.call
+      schedule
+    rescue => e
+      @last_error = e
+      case @on_error
+      when :raise
+        @cancelled = true
+        # Store on App so it raises from the next app.update call.
+        # Don't re-raise here — that would go through rb_protect → bgerror.
+        @app._pending_exception = e
+      when Proc
+        begin
+          @on_error.call(e)
+        rescue => handler_err
+          @last_error = handler_err
+          @cancelled = true
+          @app._pending_exception = handler_err
+          return
+        end
+        schedule
+      when nil
+        @cancelled = true
+      end
+    end
+
+    def check_drift
+      return unless @next_expected
+      actual = now_ms
+      drift = actual - @next_expected
+      if drift > @interval
+        @late_ticks += 1
+        warn "Teek::RepeatingTimer: tick #{@late_ticks} fired #{drift.round}ms late " \
+             "(interval=#{@interval}ms)"
+      end
+    end
+
+    def now_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+  end
 end