teek 0.1.5 → 0.2.0

data/lib/teek.rb

@@ -5,7 +5,15 @@ require_relative 'teek/version'
 require_relative 'teek/platform'
 require_relative 'teek/ractor_support'
 require_relative 'teek/widget'
+require_relative 'teek/callback_registry'
+require_relative 'teek/command_interceptors'
+require_relative 'teek/menu_interceptor'
+require_relative 'teek/tag_bind_interceptor'
+require_relative 'teek/canvas_bind_interceptor'
 require_relative 'teek/photo'
+require_relative 'teek/dialogs'
+require_relative 'teek/winfo'
+require_relative 'teek/wm'
 
 # Ruby interface to Tcl/Tk. Provides a thin wrapper around a Tcl interpreter
 # with Ruby callbacks, event bindings, and background work support.
@@ -30,6 +38,40 @@ require_relative 'teek/photo'
 # @see Teek::BackgroundWork
 module Teek
 
+  # Raised on a Tcl error (TCL_ERROR) from #tcl_eval, #tcl_invoke, or
+  # anything built on them. +message+ is the same short one-line Tcl
+  # result this exception has always carried; {#tcl_backtrace} and
+  # {#tcl_error_code} additionally expose Tcl's own +errorInfo+/+errorCode+
+  # for the failing call - captured immediately after the failing
+  # Tcl_Eval/Tcl_EvalObjv via Tcl_GetReturnOptions, before anything else
+  # can run and disturb them. Both are +nil+ for the handful of Ruby-level
+  # guard errors (e.g. "interpreter has been deleted") that never actually
+  # reached Tcl.
+  class TclError < RuntimeError
+    # @return [String, nil] Tcl's +errorInfo+ for the failing call - a
+    #   multi-line trace with a "while executing"/"invoked from within"
+    #   frame for each level of Tcl proc call the error unwound through
+    attr_reader :tcl_backtrace
+
+    # @return [String, nil] Tcl's +errorCode+ for the failing call (a Tcl
+    #   list, typically "NONE" unless the failing command set one explicitly)
+    attr_reader :tcl_error_code
+
+    # @api private
+    def initialize(message, tcl_backtrace = nil, tcl_error_code = nil)
+      super(message)
+      @tcl_backtrace = tcl_backtrace
+      @tcl_error_code = tcl_error_code
+    end
+  end
+
+  # Raised by App#command when more than one registered CommandInterceptor
+  # claims the same call. The message names each matching interceptor's
+  # label so it's clear which ones collided - built-in shape-matching bug,
+  # a custom interceptor overlapping a built-in one, or two custom
+  # interceptors overlapping each other.
+  class AmbiguousCommandError < RuntimeError; end
+
   def self.bool_to_tcl(val)
     val ? "1" : "0"
   end
@@ -48,19 +90,25 @@ module Teek
   ].freeze
 
   class App
-    attr_reader :interp, :widgets, :debugger
+    attr_reader :interp, :widgets, :debugger, :callback_registry, :winfo, :wm
     attr_writer :_pending_exception # @api private
 
     def initialize(title: nil, track_widgets: true, debug: false, &block)
       @interp = Teek::Interp.new
       @interp.tcl_eval('package require Tk')
+      @winfo = Teek::Winfo.new(self)
+      @wm = Teek::Wm.new(self)
       hide
       @widgets = {}
       @widget_counters = Hash.new(0)
+      @callback_registry = Teek::CallbackRegistry.new(self)
+      @widget_types_by_path = {}
       @_pending_exception = nil
       debug ||= !!ENV['TEEK_DEBUG']
       track_widgets = true if debug
+      @track_widgets = track_widgets
       setup_widget_tracking if track_widgets
+      setup_destroy_cleanup
       if debug
         require_relative 'teek/debugger'
         @debugger = Teek::Debugger.new(self)
@@ -73,6 +121,14 @@ module Teek
     # Prefer {#command} for building commands from Ruby values; use this
     # when you need Tcl-level features like variable substitution or
     # inline expressions that {#command} can't express.
+    # @note Any callback embedded in +script+ (e.g. a hand-built
+    #   +ruby_callback <id>+) is on you to register and release - none of
+    #   {#command}'s tracking applies here. Creating a widget this way
+    #   (instead of via {#command}/{#create_widget}/{#menu}) also means its
+    #   type is never recorded, so a registered {CommandInterceptors} entry
+    #   won't engage for it even on later, ordinary {#command} calls -
+    #   create widgets through those methods and reach for +tcl_eval+ for
+    #   everything else.
     # @param script [String] Tcl code to evaluate
     # @return [String] the Tcl result
     def tcl_eval(script)
@@ -92,10 +148,25 @@ module Teek
     #   throw :teek_break    - stop event propagation (like Tcl "break")
     #   throw :teek_continue - Tcl TCL_CONTINUE
     #   throw :teek_return   - Tcl TCL_RETURN
+    #
+    # +:teek_break+/+:teek_continue+ only mean something when Tcl actually
+    # dispatches the result through a context that knows how to handle
+    # TCL_BREAK/TCL_CONTINUE - Tk's bind mechanism does; a plain script
+    # invocation (a menu entry's or widget's `-command`) does not, and
+    # returning either code there is a Tcl error ("invoked break/continue
+    # outside of a loop"), not a no-op. +relay_break_continue: false+ is
+    # for exactly those non-bind callers: +throw+ is still caught (so it
+    # can't crash as an uncaught throw), but is treated as the callback
+    # simply finishing, instead of being relayed to Tcl. +:teek_return+ is
+    # always relayed either way - TCL_RETURN is safe in any context.
     # @param callable [#call] a Proc or lambda to invoke from Tcl
+    # @param relay_break_continue [Boolean] whether a caught :teek_break/
+    #   :teek_continue is relayed to Tcl as TCL_BREAK/TCL_CONTINUE (true,
+    #   for bind-dispatched callbacks) or silently absorbed (false, for
+    #   callbacks invoked as a plain script - menu/widget -command options)
     # @return [Integer] callback ID, usable as +ruby_callback <id>+ in Tcl
     # @see #unregister_callback
-    def register_callback(callable)
+    def register_callback(callable, relay_break_continue: true)
       wrapped = proc { |*args|
         caught = nil
         catch(:teek_break) do
@@ -109,7 +180,9 @@ module Teek
           caught ||= :continue
         end
         caught ||= :break
-        caught == :_none ? nil : caught
+        next nil if caught == :_none
+        next caught if caught == :return
+        relay_break_continue ? caught : nil
       }
       @interp.register_callback(wrapped)
     end
@@ -121,6 +194,20 @@ module Teek
       @interp.unregister_callback(id)
     end
 
+    # Evaluate +script+ once per App instance under +name+, skipping it on
+    # later calls. Meant for widget-behavior modules that need to define a
+    # Tcl-side helper proc (e.g. a scan routine) without re-sending and
+    # re-parsing that definition on every call.
+    # @param name [Symbol] unique name for this helper
+    # @yieldreturn [String] the Tcl script to evaluate the first time
+    # @return [void]
+    def ensure_tcl_helper(name)
+      @installed_tcl_helpers ||= {}
+      return if @installed_tcl_helpers[name]
+      @interp.tcl_eval(yield)
+      @installed_tcl_helpers[name] = true
+    end
+
     # 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:
@@ -230,10 +317,18 @@ module Teek
       Teek.bool_to_tcl(val)
     end
 
-    # Build and evaluate a Tcl command from Ruby values.
-    # Positional args are converted: Symbols pass bare, Procs become
-    # callbacks, everything else is brace-quoted. Keyword args become
-    # +-key value+ option pairs.
+    # Build and evaluate a Tcl command from Ruby values. Positional args
+    # are converted: Symbols pass bare, Procs become callbacks, everything
+    # else is brace-quoted. Keyword args become +-key value+ option pairs.
+    #
+    # Any Proc-valued arg or kwarg is tracked and released on overwrite,
+    # explicit removal, or the owning widget's destruction - there is no
+    # unsafe way to attach a callback through this method, regardless of
+    # whether the call happens to match a registered per-widget-type
+    # interceptor (see {CommandInterceptors}) or falls through to the
+    # generic default. Widget type is inferred automatically from calls
+    # shaped like widget creation (a {WIDGET_COMMANDS} name as +cmd+, the
+    # new path as the first positional arg) - not tied to +track_widgets+.
     # @example
     #   app.command(:pack, '.btn', side: :left, padx: 10)
     #   # evaluates: pack .btn -side left -padx {10}
@@ -241,33 +336,126 @@ module Teek
     # @param args positional arguments
     # @param kwargs keyword arguments mapped to +-key value+ pairs
     # @return [String] the Tcl result
+    # @raise [AmbiguousCommandError] if more than one registered
+    #   interceptor claims the same call - see {CommandInterceptors}
     def command(cmd, *args, **kwargs)
-      parts = [cmd.to_s]
+      record_widget_type(cmd, args)
+
+      type = @widget_types_by_path[cmd.to_s]
+      entries = type ? CommandInterceptors.for_type(type) : []
+      matches = entries.map { |entry| [entry.label, entry.block.call(self, cmd, args, kwargs)] }
+                        .reject { |_label, result| result.nil? }
+
+      case matches.size
+      when 0 then raw_command(cmd, *args, **track_widget_option_callbacks(cmd, args, kwargs))
+      when 1 then matches.first.last
+      else
+        labels = matches.map(&:first).join(', ')
+        raise AmbiguousCommandError,
+          "#{matches.size} command interceptors (#{labels}) matched #{cmd.inspect} #{args.inspect} " \
+          "for widget type #{type.inspect}"
+      end
+    end
+
+    # The dumb Tcl builder underneath {#command} - no interceptor lookup,
+    # no per-widget-type awareness. Used internally by interceptors (to
+    # actually perform their Tcl work without re-entering dispatch) and by
+    # {#command}'s own generic fallback. Any Proc here still gets
+    # registered as a real, working callback (positional: bind-shaped,
+    # relay_break_continue: true; kwarg, via {#tcl_arg_value}: option-shaped,
+    # relay_break_continue: false) - it just isn't tracked for release.
+    # Prefer {#command}; call this directly only from within an
+    # interceptor.
+    #
+    # Built as a plain argv array passed to {Interp#tcl_invoke}
+    # (Tcl_EvalObjv) rather than a joined string handed to +tcl_eval+, so
+    # no value needs escaping - unbalanced braces, +$+, +[+, newlines,
+    # whatever, all pass through verbatim. There is nothing here for a
+    # value to "break out" of.
+    # @return [String] the Tcl result
+    def raw_command(cmd, *args, **kwargs)
+      argv = [cmd.to_s]
       i = 0
       while i < args.length
         arg = args[i]
         if arg.is_a?(Proc)
-          id = @interp.register_callback(arg)
+          id = register_callback(arg)
           subs = []
           while i + 1 < args.length && args[i + 1].is_a?(String) && args[i + 1].start_with?('%')
             subs << args[i + 1]
             i += 1
           end
-          parts << if subs.empty?
-                     "{ruby_callback #{id}}"
-                   else
-                     "{ruby_callback #{id} #{subs.join(' ')}}"
-                   end
+          argv << if subs.empty?
+                    "ruby_callback #{id}"
+                  else
+                    "ruby_callback #{id} #{subs.join(' ')}"
+                  end
         else
-          parts << tcl_value(arg)
+          argv << tcl_arg_value(arg)
         end
         i += 1
       end
       kwargs.each do |key, value|
-        parts << "-#{key}"
-        parts << tcl_value(value)
+        argv << "-#{key}"
+        argv << tcl_arg_value(value)
+      end
+      @interp.tcl_invoke(*argv)
+    end
+
+    # {#command}'s fallback for any call that no registered interceptor
+    # claimed: registers any Proc-valued kwarg (e.g. command:,
+    # validatecommand:) as a callback tracked under +cmd+, releasing it if
+    # reconfigured or when the widget is destroyed. A widget's own options
+    # are never silently renumbered or invalidated out from under us the
+    # way menu entries are, so this uses a cheap in-memory
+    # {CallbackRegistry#reconcile} rather than a live-scan one.
+    #
+    # Tracked under the widget's own path, by +[*context, key]+, where
+    # +context+ is +args+ normalized to strings - except a bare +configure+
+    # (or widget creation - the container is the new widget's path, not the
+    # +cmd+ used to create it) normalizes to an empty context, since all
+    # three address the same underlying option namespace and must replace
+    # each other. Any other subcommand (e.g. a treeview's +heading col+)
+    # keeps its own args as part of the key, so two different targets
+    # sharing an option name (two columns both using +command:+) don't
+    # collide.
+    # @return [Hash] +kwargs+ with any Proc values swapped for the Tcl
+    #   script {#raw_command} embeds
+    def track_widget_option_callbacks(cmd, args, kwargs)
+      proc_kwargs = kwargs.select { |_, value| value.is_a?(Proc) }
+      return kwargs if proc_kwargs.empty?
+
+      if WIDGET_COMMANDS.include?(cmd.to_s) && args[0].is_a?(String)
+        widget_path = args[0]
+        context = []
+      else
+        widget_path = cmd.to_s
+        context = (args.empty? || args[0].to_s == 'configure') ? [] : args.map(&:to_s)
+      end
+
+      ids = {}
+      replacements = {}
+      proc_kwargs.each do |key, value|
+        id = register_callback(value, relay_break_continue: false)
+        ids[context + [key.to_s]] = id
+        replacements[key] = "ruby_callback #{id}"
       end
-      @interp.tcl_eval(parts.join(' '))
+      @callback_registry.reconcile([:widget_option, widget_path]) { |before| before.merge(ids) }
+      kwargs.merge(replacements)
+    end
+
+    # Records that +args[0]+ is a widget of type +cmd+, if this call looks
+    # like widget creation (+cmd+ is a known {WIDGET_COMMANDS} entry). Not
+    # tied to +track_widgets+ - this is what lets {#command} look up a
+    # registered interceptor for a bare path string on any later call,
+    # regardless of how the widget was created.
+    # @return [void]
+    def record_widget_type(cmd, args)
+      return unless WIDGET_COMMANDS.include?(cmd.to_s)
+      path = args[0]
+      return unless path.is_a?(String)
+
+      @widget_types_by_path[path] = cmd.to_s
     end
 
     # Create a Tk widget and return a {Widget} wrapper.
@@ -278,6 +466,10 @@ module Teek
     # @param type [String, Symbol] Tk widget command (e.g. 'ttk::button', :canvas)
     # @param path [String, nil] explicit Tk path, or nil for auto-naming
     # @param parent [Widget, String, nil] parent widget for path nesting
+    # @param idempotent [Boolean] skip the creation command if a widget
+    #   already exists at +path+ - for widgets meant to be fetched by a
+    #   stable, caller-chosen path and reused across many calls (see {#menu})
+    #   rather than freshly created each time
     # @param kwargs keyword arguments passed to the Tk widget command
     # @return [Widget] the created widget
     #
@@ -293,13 +485,33 @@ module Teek
     #   btn = app.create_widget('ttk::button', parent: frm, text: 'Click')
     #   # btn.path => ".ttkfrm1.ttkbtn1"
     #
-    def create_widget(type, path = nil, parent: nil, **kwargs)
+    def create_widget(type, path = nil, parent: nil, idempotent: false, **kwargs)
       type_s = type.to_s
       path ||= next_widget_path(type_s, parent)
-      command(type_s, path, **kwargs)
+      if idempotent && @winfo.exists?(path)
+        # Still record the type even though creation itself is skipped - a
+        # path that already existed (e.g. built with a raw tcl_eval) is
+        # otherwise never seen by #command, so no interceptor could ever
+        # engage for it.
+        record_widget_type(type_s, [path])
+      else
+        command(type_s, path, **kwargs)
+      end
       Widget.new(self, path)
     end
 
+    # Wrap a Tk menu at the given path, creating it (tearoff disabled) if
+    # it doesn't exist yet. Safe to call repeatedly with the same path -
+    # it's a flyweight, not a handle you need to hold onto: call this again
+    # any time you're about to rebuild the menu (e.g. on every right-click).
+    # @param path [String] Tk menu path (e.g. ".card.ctx")
+    # @param kwargs extra options for the underlying `menu` command, used
+    #   only the first time this path is created
+    # @return [Widget]
+    def menu(path, **kwargs)
+      create_widget(:menu, path, idempotent: true, tearoff: 0, **kwargs)
+    end
+
     # Add a directory to Tcl's package search path.
     # @param path [String] directory containing Tcl packages
     # @return [void]
@@ -351,21 +563,25 @@ module Teek
     end
 
     # Set a Tcl variable. Useful for widget +textvariable+ and +variable+ options.
-    # @param name [String] variable name
+    # Goes through Tcl_SetVar directly (no re-parsing), so the value never
+    # needs escaping - braces, backslashes, +$+, +[+, whatever, all safe.
+    # @param name [String] variable name (array-element and namespaced forms work)
     # @param value [String] value to set
     # @return [String] the value
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/set.htm set
     def set_variable(name, value)
-      tcl_eval("set #{name} {#{value}}")
+      @interp.tcl_set_var(name.to_s, value.to_s)
     end
 
     # Get a Tcl variable's value.
-    # @param name [String] variable name
+    # @param name [String] variable name (array-element and namespaced forms work)
     # @return [String] the value
     # @raise [Teek::TclError] if the variable doesn't exist
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/set.htm set
     def get_variable(name)
-      tcl_eval("set #{name}")
+      value = @interp.tcl_get_var(name.to_s)
+      return value unless value.nil?
+      raise Teek::TclError, "can't read \"#{name}\": no such variable"
     end
 
     # Destroy a widget and all its children.
@@ -464,17 +680,19 @@ module Teek
     # Show a window. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
+    # @see Wm#deiconify
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M38 wm deiconify
     def show(window = '.')
-      @interp.tcl_eval("wm deiconify #{window}")
+      @wm.deiconify(window: window)
     end
 
     # Hide a window without destroying it. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
+    # @see Wm#withdraw
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M65 wm withdraw
     def hide(window = '.')
-      @interp.tcl_eval("wm withdraw #{window}")
+      @wm.withdraw(window: window)
     end
 
     # Enable the Tk debug console. The console starts hidden and can be
@@ -519,34 +737,38 @@ module Teek
     # @param title [String] new title
     # @param window [String] Tk window path
     # @return [String] the title
+    # @see Wm#set_title
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M63 wm title
     def set_window_title(title, window: '.')
-      tcl_eval("wm title #{window} {#{title}}")
+      @wm.set_title(title, window: window)
     end
 
     # Get a window's current title.
     # @param window [String] Tk window path
     # @return [String] current title
+    # @see Wm#title
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M63 wm title
     def window_title(window: '.')
-      tcl_eval("wm title #{window}")
+      @wm.title(window: window)
     end
 
     # Set a window's geometry (e.g. "400x300", "400x300+100+50").
     # @param geometry [String] geometry string
     # @param window [String] Tk window path
     # @return [String] the geometry
+    # @see Wm#set_geometry
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M42 wm geometry
     def set_window_geometry(geometry, window: '.')
-      tcl_eval("wm geometry #{window} #{geometry}")
+      @wm.set_geometry(geometry, window: window)
     end
 
     # Get a window's current geometry.
     # @param window [String] Tk window path
     # @return [String] geometry string (e.g. "400x300+0+0")
+    # @see Wm#geometry
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M42 wm geometry
     def window_geometry(window: '.')
-      tcl_eval("wm geometry #{window}")
+      @wm.geometry(window: window)
     end
 
     # Set whether a window is resizable.
@@ -554,18 +776,19 @@ module Teek
     # @param height [Boolean] allow vertical resize
     # @param window [String] Tk window path
     # @return [void]
+    # @see Wm#set_resizable
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M59 wm resizable
     def set_window_resizable(width, height, window: '.')
-      tcl_eval("wm resizable #{window} #{width ? 1 : 0} #{height ? 1 : 0}")
+      @wm.set_resizable(width, height, window: window)
     end
 
     # Get whether a window is resizable.
     # @param window [String] Tk window path
     # @return [Array(Boolean, Boolean)] [width_resizable, height_resizable]
+    # @see Wm#resizable
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M59 wm resizable
     def window_resizable(window: '.')
-      parts = tcl_eval("wm resizable #{window}").split
-      [parts[0] == '1', parts[1] == '1']
+      @wm.resizable(window: window)
     end
 
     # Bind a Tk event on a widget, with optional substitutions forwarded
@@ -616,6 +839,7 @@ module Teek
     def bind(widget, event, *subs, &block)
       event_str = event.start_with?('<') ? event : "<#{event}>"
       cb = register_callback(proc { |*args| block.call(*args) })
+      @callback_registry.reconcile([:bind, widget]) { |before| before.merge(event_str => cb) }
       tcl_subs = subs.map { |s| s.is_a?(Symbol) ? BIND_SUBS.fetch(s) : s.to_s }
       sub_str = tcl_subs.empty? ? '' : ' ' + tcl_subs.join(' ')
       @interp.tcl_eval("bind #{widget} #{event_str} {ruby_callback #{cb}#{sub_str}}")
@@ -629,9 +853,36 @@ module Teek
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/bind.htm bind
     def unbind(widget, event)
       event_str = event.start_with?('<') ? event : "<#{event}>"
+      @callback_registry.reconcile([:bind, widget]) { |before| before.reject { |k, _| k == event_str } }
       @interp.tcl_eval("bind #{widget} #{event_str} {}")
     end
 
+    # Register a handler for the window manager's close button
+    # (WM_DELETE_WINDOW - the titlebar close box, Cmd-W, Alt-F4, etc.,
+    # depending on platform).
+    #
+    # Tk's own default behavior (destroy the window) only applies when
+    # nothing else has claimed this protocol - setting a handler here
+    # replaces it, so the block is entirely responsible for deciding
+    # whether the window actually closes. Call {#destroy} yourself if you
+    # want it to; do nothing (or show a confirmation first) if you don't.
+    #
+    # @example Confirm before quitting
+    #   app.on_close { app.destroy('.') if app.message_box(message: 'Quit?', type: :yesno) == :yes }
+    # @example A toplevel that just hides instead of closing
+    #   app.on_close(window: settings_window) { app.tcl_eval("wm withdraw #{settings_window}") }
+    #
+    # @param window [String] Tk window path (default: the root window)
+    # @yield called when the window's close button is pressed
+    # @return [void]
+    # @see #bind
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/wm.htm#M46 wm protocol
+    def on_close(window: '.', &block)
+      cb = register_callback(block, relay_break_continue: false)
+      @callback_registry.reconcile([:wm_protocol, window]) { |before| before.merge('WM_DELETE_WINDOW' => cb) }
+      @interp.tcl_eval("wm protocol #{window} WM_DELETE_WINDOW {ruby_callback #{cb}}")
+    end
+
     # Register a widget as a file drop target.
     # After registration, dropping files onto the widget generates a single
     # +<<DropFile>>+ virtual event with all file paths as a Tcl list in the
@@ -761,11 +1012,6 @@ module Teek
         @widgets[path] = { class: cls, parent: File.dirname(path).gsub(/\A$/, '.') }
         @debugger&.on_widget_created(path, cls)
       })
-      @destroy_cb_id = @interp.register_callback(proc { |path|
-        next if path.start_with?('.teek_debug')
-        @widgets.delete(path)
-        @debugger&.on_widget_destroyed(path)
-      })
 
       # Tcl proc called on widget creation (trace leave)
       @interp.tcl_eval("proc ::teek_track_create {cmd_string code result op} {
@@ -776,37 +1022,51 @@ module Teek
         }
       }")
 
-      # Tcl proc called on widget destruction (bind)
-      @interp.tcl_eval("bind all <Destroy> {ruby_callback #{@destroy_cb_id} %W}")
-
       # Add trace on each widget command
       Teek::WIDGET_COMMANDS.each do |cmd|
         @interp.tcl_eval("catch {trace add execution #{cmd} leave ::teek_track_create}")
       end
     end
 
-    def tcl_value(value)
+    # Installed unconditionally (unlike widget-creation tracking, which is
+    # opt-out via track_widgets: false) so that bind-callback cleanup always
+    # runs. A single `bind all <Destroy>` script is used because Tcl's bind
+    # command replaces rather than appends per tag+event, so widget-tracking
+    # cleanup is folded into the same callback rather than installed separately.
+    def setup_destroy_cleanup
+      @destroy_cb_id = @interp.register_callback(proc { |path|
+        @callback_registry.forget_all_for_path(path)
+        next if path.start_with?('.teek_debug')
+        if @track_widgets
+          @widgets.delete(path)
+          @debugger&.on_widget_destroyed(path)
+        end
+      })
+      @interp.tcl_eval("bind all <Destroy> {ruby_callback #{@destroy_cb_id} %W}")
+    end
+
+    # Resolves a Ruby value to the plain string {#raw_command} passes as
+    # one +tcl_invoke+ argv element - no Tcl quoting of any kind, since
+    # +tcl_invoke+ (Tcl_EvalObjv) never re-parses its arguments.
+    def tcl_arg_value(value)
       case value
       when Proc
-        id = @interp.register_callback(value)
-        "{ruby_callback #{id}}"
+        # A Proc reaching tcl_arg_value is always a kwarg/option value
+        # (e.g. -command), never a bind script - see #register_callback's
+        # note on why break/continue can't be relayed there.
+        id = register_callback(value, relay_break_continue: false)
+        "ruby_callback #{id}"
       when Symbol
         value.to_s
       when Array
-        "{#{value.map { |v| tcl_value(v) }.join(' ')}}"
+        # Each element becomes its own well-formed Tcl list element via
+        # make_list (which quotes only where needed), so this produces a
+        # single argv value that Tk parses back out as a proper list -
+        # nested arrays fall out for free, since make_list happily
+        # accepts an already-list-shaped string as one of its elements.
+        make_list(*value.map { |v| tcl_arg_value(v) })
       else
-        tcl_quote_string(value.to_s)
-      end
-    end
-
-    # Brace-quote a string for Tcl, falling back to double-quote quoting
-    # when the string ends with a backslash (Tcl treats \} as an escaped
-    # brace, preventing the closing brace from terminating the group).
-    def tcl_quote_string(s)
-      if s.end_with?('\\')
-        '"' + s.gsub(/[\\\[\]$"]/) { |c| "\\#{c}" } + '"'
-      else
-        "{#{s}}"
+        value.to_s
       end
     end
   end

data/teek.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions = ["ext/teek/extconf.rb"]
-  spec.required_ruby_version = ">= 3.2"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rake-compiler", "~> 1.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teek
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - James Cook
@@ -137,14 +137,22 @@ files:
 - lib/teek/background_none.rb
 - lib/teek/background_ractor4x.rb
 - lib/teek/background_thread.rb
+- lib/teek/callback_registry.rb
+- lib/teek/canvas_bind_interceptor.rb
+- lib/teek/command_interceptors.rb
 - lib/teek/debugger.rb
 - lib/teek/demo_support.rb
+- lib/teek/dialogs.rb
+- lib/teek/menu_interceptor.rb
 - lib/teek/method_coverage_service.rb
 - lib/teek/photo.rb
 - lib/teek/platform.rb
 - lib/teek/ractor_support.rb
+- lib/teek/tag_bind_interceptor.rb
 - lib/teek/version.rb
 - lib/teek/widget.rb
+- lib/teek/winfo.rb
+- lib/teek/wm.rb
 - teek.gemspec
 homepage: https://github.com/jamescook/teek
 licenses:
@@ -158,7 +166,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="