teek 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ff08eb5884f74dc6461c5ff1163a025b44b798e2e480bd4f2855210dd0f0fdf
-  data.tar.gz: 8e012ccf6a6fffe427630c033b288f784ed455552b064870b0bce054d11e62ee
+  metadata.gz: 1f75bdcd33165c47419853eabf3d2393f2b576648647f7ad17efef30df2da023
+  data.tar.gz: 636773f5d6a743dd2ef94a3365afd4647878cc0a4ef7842627a0d5325f6f5329
 SHA512:
-  metadata.gz: 878e28a9a7493abdccdce1a4b28e372ade4648b12392cdb0815581b4590ab69b601eceb1da686e01719c6930fe1e88c333d4751e80f3af7875ce84a2a391957c
-  data.tar.gz: 0cd4b0ae71353720e185455e3966b954b9b2e2237417ce0efc596ad9915234f6b79923d318a54a1f42ddf9a839e8e58857462017192f750cd1d4ef31ce92710a
+  metadata.gz: 892af65f50c58578001bd8a274b96ff2663630489c904218a066d049caa80a49a1bd5de6012d5a4333178e030f72fb55c7001396c39fcaa851868c6f2401b415
+  data.tar.gz: 661bb18457269fe174470e26f16fd070404dcb3f9c70740ec5d543b501365dd0733313bd2ff803fb7108285583f86b42da98153c65a3edf77d681ddf15e1b663

data/README.md

@@ -1,6 +1,16 @@
 # Teek
 
-A Ruby interface to Tcl/Tk.
+Ruby apps for the desktop, built on Tcl/Tk.
+
+**Building an app?** Start with [teek-ui](teek-ui/README.md) — a DSL for declaring widgets, layout, and events instead of hand-writing Tk mechanics:
+
+```
+gem install teek-ui
+```
+
+That pulls in `teek` (below) transitively. Think Rails and Rack: you write against teek-ui, and teek is the engine underneath it.
+
+This repo/gem is **teek** itself — the low-level Ruby↔Tcl/Tk binding teek-ui compiles down to. It's the right layer to reach for directly if you're embedding Tk in an existing app, building your own abstraction on top, or want direct control over widget mechanics — but most app authors want teek-ui instead.
 
 [API Documentation](https://jamescook.github.io/teek/)
 
@@ -294,6 +304,22 @@ Dropped files arrive as a Tcl list in the `:data` substitution. Use `split_list`
 
 See [`sample/drop_demo.rb`](sample/drop_demo.rb) for a complete example.
 
+## Multiple Interpreters
+
+Teek can create more than one Tcl/Tk interpreter in a process — each `Teek::App.new` is a fully independent interpreter with its own widget tree, callbacks, and `.` main window — and the low-level `Interp#create_slave(name, safe)` primitive wraps Tcl's master/slave (child) interpreters. **In practice you almost never want either.** Two hard constraints make multi-interpreter setups more trouble than they solve:
+
+- **The event loop is singular.** Tcl's notifier and event queue are per *thread*, not per interpreter. One `mainloop` drives every interpreter on that thread and exits only when the last window anywhere closes; multiple `mainloop` calls do not compose. Multi-interpreter buys you no concurrency — the GUI still runs on one thread.
+- **GUI is main-thread-only on macOS.** Tk on Aqua sits on Cocoa, which requires the main thread. You can run several interpreters *on the main thread*, but you cannot own Tk windows or run a Tk event loop on a background thread on macOS. (X11 is more permissive, but code that leans on that won't port.)
+
+So teek's stance is a hard lean **against** multiple interpreters. Reach for what you actually need instead:
+
+- **More windows** → use `toplevel`, not more interpreters. One interpreter manages any number of top-level windows.
+- **Concurrency / a responsive UI during heavy work** → use Background Work (Ractors) plus `after`/`after_idle`, which marshal results back to the main thread. See [Background Work](#background-work).
+- **Isolating state or widget names** → use Tcl namespaces and a widget-path naming convention within a single interpreter.
+- **Running untrusted Tcl** → this is the one legitimate reason for a separate (safe) interpreter. The `Interp#create_slave` primitive exists, but a safe slave has **no Tk** by default and isn't wired into the `App`/widget layer — treat GUI-in-a-sandbox as advanced, unsupported territory for now.
+
+If you do run multiple `Teek::App`s, keep them all on the main thread and let a single one own the `mainloop`.
+
 ## Known Issues
 
 - **File drop on Linux/Wayland** — `register_drop_target` does not yet work under Wayland. The current implementation uses the X11 XDND protocol, which is not compatible with Wayland's native drag-and-drop. Workaround: select an Xorg/X11 session at the login screen (e.g., "GNOME on Xorg"). Native Wayland support via `wl_data_device` is planned.

data/Rakefile

@@ -293,6 +293,15 @@ namespace :sdl2 do
   task test: 'sdl2:compile'
 end
 
+namespace :ui do
+  Rake::TestTask.new(:test) do |t|
+    t.libs << 'teek-ui/test' << 'teek-ui/lib'
+    t.test_files = FileList['teek-ui/test/**/test_*.rb'] - FileList['teek-ui/test/test_helper.rb']
+    t.ruby_opts << '-r test_helper'
+    t.verbose = true
+  end
+end
+
 task :default => :compile
 
 namespace :release do
@@ -510,6 +519,31 @@ namespace :docker do
       sh cmd
     end
 
+    desc "Run teek-ui tests in Docker"
+    task ui: :build do
+      tcl_version = tcl_version_from_env
+      ruby_version = ruby_version_from_env
+      image_name = docker_image_name(tcl_version, ruby_version)
+
+      require 'fileutils'
+      FileUtils.mkdir_p('coverage')
+
+      warn_if_containers_running(image_name)
+
+      puts "Running teek-ui tests in Docker (Ruby #{ruby_version}, Tcl #{tcl_version})..."
+      cmd = "docker run --rm --init"
+      cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+      cmd += " -e TCL_VERSION=#{tcl_version}"
+      if ENV['COVERAGE'] == '1'
+        cmd += " -e COVERAGE=1"
+        cmd += " -e COVERAGE_NAME=#{ENV['COVERAGE_NAME'] || 'ui'}"
+      end
+      cmd += " #{image_name}"
+      cmd += " xvfb-run -a bundle exec rake ui:test"
+
+      sh cmd
+    end
+
     desc "Run all tests (teek + teek-sdl2) with coverage and generate report"
     task all: 'docker:build' do
       tcl_version = tcl_version_from_env
@@ -520,7 +554,7 @@ namespace :docker do
       FileUtils.rm_rf('coverage')
       FileUtils.mkdir_p('coverage/results')
 
-      # Run all three test suites with coverage enabled and distinct COVERAGE_NAMEs
+      # Run all test suites with coverage enabled and distinct COVERAGE_NAMEs
       ENV['COVERAGE'] = '1'
 
       ENV['COVERAGE_NAME'] = 'main'
@@ -531,6 +565,11 @@ namespace :docker do
       Rake::Task['docker:build'].reenable
       Rake::Task['docker:test:sdl2'].invoke
 
+      ENV['COVERAGE_NAME'] = 'ui'
+      Rake::Task['docker:test:ui'].reenable
+      Rake::Task['docker:build'].reenable
+      Rake::Task['docker:test:ui'].invoke
+
       # Collate inside Docker (paths match /app/lib/...)
       puts "Collating coverage results..."
       cmd = "docker run --rm --init"

data/lib/teek/callback_registry.rb

@@ -70,6 +70,23 @@ module Teek
       end
     end
 
+    # Diagnostic aggregate, not itself load-bearing for cleanup - a live
+    # snapshot of how many tracked callback ids currently exist, grouped
+    # by the tag every {#reconcile} container is already keyed on
+    # (+:bind+, +:menu+, +:canvas_bind+, +:tag_bind+, +:widget_option+,
+    # +:wm_protocol+, ...). Counts individual ids, not containers - a
+    # single container can hold several (e.g. one widget bound to
+    # several events). A tag with nothing currently tracked under it is
+    # simply absent from the result, not present with a zero count.
+    # @return [Hash{Object => Integer}]
+    def counts_by_tag
+      counts = Hash.new(0)
+      @entries.each do |(tag, _path), ids|
+        counts[tag] += ids.size unless ids.empty?
+      end
+      counts
+    end
+
     private
 
     # Convention, not a type check: every container is [feature_tag, path].

data/lib/teek/canvas_bind_interceptor.rb

@@ -51,15 +51,15 @@ module Teek
         rescue Teek::TclError
           ''
         end
-        # \z anchors this to a BARE `ruby_callback <id>` with nothing
-        # after. raw_command's generic positional-Proc handling
-        # technically allows a caller to pass %-substitutions to a
-        # canvas-bind-shaped app.command call (the same mechanism
-        # App#bind uses), but nothing in teek does that today. If a
-        # caller ever does, this regex silently stops matching and that
-        # id leaks on rebuild/delete - drop the \z anchor (match just
-        # the leading `ruby_callback <id>`) if that changes.
-        after[[tag_or_id, seq]] = Regexp.last_match(1) if current =~ /\Aruby_callback (\S+)\z/
+        # Matches a bare `ruby_callback <id>` or one followed by
+        # %-substitution codes (`ruby_callback <id> %x %y`) -
+        # raw_command's generic positional-Proc handling allows a caller
+        # to pass %-substitutions to a canvas-bind-shaped app.command
+        # call (the same mechanism App#bind uses; CanvasItem#on_drag and
+        # #on_right_click's menu form both do). `\S+` is greedy and stops
+        # at the first space, so it can't overrun into the substitution
+        # codes themselves.
+        after[[tag_or_id, seq]] = Regexp.last_match(1) if current =~ /\Aruby_callback (\S+)(?:\s|\z)/
       end
     end
   end

data/lib/teek/clipboard.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Teek
+  # Thin, typed wrapper around Tk's `clipboard` command family, reached
+  # via {App#clipboard}.
+  #
+  # Doesn't touch text widgets' own copy/cut/paste at all - `ttk::entry`/
+  # `text` already bind `<<Copy>>`/`<<Cut>>`/`<<Paste>>` to the expected
+  # platform keys (Control-c/x/v, plus their Command-key equivalents on
+  # macOS) via Tk's own built-in class bindings, with nothing for teek to
+  # wire up. This class is purely for reading/writing the clipboard
+  # directly from app code (e.g. a "Copy to Clipboard" button that isn't
+  # itself a text widget's own selection).
+  #
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/clipboard.htm clipboard
+  class Clipboard
+    # @api private
+    def initialize(app)
+      @app = app
+    end
+
+    # Replace the clipboard's contents outright - Tk's own `clipboard
+    # clear` followed by `clipboard append` two-step, done as one call.
+    # @param text [String]
+    # @return [void]
+    def set(text)
+      @app.tcl_invoke('clipboard', 'clear')
+      @app.tcl_invoke('clipboard', 'append', '--', text.to_s)
+      nil
+    end
+
+    # @return [String, nil] the clipboard's current text, or +nil+ if
+    #   it's empty/has no owner (Tk raises a TclError for this rather
+    #   than returning an empty string)
+    def get
+      @app.tcl_invoke('clipboard', 'get')
+    rescue Teek::TclError
+      nil
+    end
+
+    # Clear the clipboard without setting new contents.
+    # @return [void]
+    def clear
+      @app.tcl_invoke('clipboard', 'clear')
+      nil
+    end
+  end
+end

data/lib/teek/dialogs.rb

@@ -106,6 +106,26 @@ module Teek
       result.empty? ? nil : result
     end
 
+    # Show the native "choose directory" dialog.
+    #
+    # @param initialdir [String, nil] directory the dialog starts in
+    # @param mustexist [Boolean] restrict the choice to an already-existing
+    #   directory (Tk's own default is false, allowing a not-yet-created one)
+    # @param title [String, nil] dialog window title
+    # @param parent [String, nil] parent window (defaults to the root window)
+    # @return [String, nil] the chosen directory path, or +nil+ if cancelled
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/chooseDirectory.htm tk_chooseDirectory
+    def choose_dir(initialdir: nil, mustexist: false, title: nil, parent: nil)
+      args = ['tk_chooseDirectory']
+      args.push('-initialdir', initialdir) if initialdir
+      args.push('-mustexist', bool_to_tcl(true)) if mustexist
+      args.push('-title', title) if title
+      args.push('-parent', parent) if parent
+
+      result = tcl_invoke(*args)
+      result.empty? ? nil : result
+    end
+
     # Pop up a menu at the given screen coordinates.
     #
     # @param menu [Widget, String] the menu to pop up

data/lib/teek/repeating_timer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Teek
+  # 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

data/lib/teek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teek
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/teek/widget.rb

@@ -102,13 +102,42 @@ module Teek
       @app.unbind(@path, event)
     end
 
+    # This widget as a {Window} - the window-scoped counterpart covering
+    # `wm` subcommands and composite behaviors (on_close, grab_set/
+    # grab_release, modal). Meant for toplevels.
+    # @return [Window]
+    def window
+      @app.window(@path)
+    end
+
     # Register a handler for this window's close button (WM_DELETE_WINDOW).
-    # Meant for toplevels; see {App#on_close} for the full behavior.
+    # Meant for toplevels; see {Window#on_close} for the full behavior.
     # @yield called when the window's close button is pressed
     # @return [void]
-    # @see App#on_close
+    # @see Window#on_close
     def on_close(&block)
-      @app.on_close(window: @path, &block)
+      window.on_close(&block)
+    end
+
+    # Grab input on this window. See {Window#grab_set}.
+    # @param global [Boolean]
+    # @return [void]
+    def grab_set(global: false)
+      window.grab_set(global: global)
+    end
+
+    # Release a grab previously set on this window. See {Window#grab_release}.
+    # @return [void]
+    def grab_release
+      window.grab_release
+    end
+
+    # Make this window modal. See {Window#modal}.
+    # @param global [Boolean]
+    # @yield optional - runs with the grab and focus already set
+    # @return [void]
+    def modal(global: false, &block)
+      window.modal(global: global, &block)
     end
 
     def inspect

data/lib/teek/window.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Teek
+  # A single toplevel window, addressed by its Tk path - the window-scoped
+  # counterpart to {Widget} (which covers any widget of any type). Groups
+  # every `wm` subcommand alongside composite window-lifecycle behaviors
+  # (on_close, grab_set/grab_release, modal) that would otherwise keep
+  # growing as more and more +window:+-kwarg methods flattened onto {App}
+  # - `app.window(path).thing` reads better than threading `window:`
+  # through a dozen unrelated top-level methods, and gives callers (like
+  # teek-ui's DSL) one coherent object per window instead of loose parts.
+  #
+  # `App#wm` ({Wm}) and App's own `window_title`/`set_window_title`/etc.
+  # convenience methods, plus `App#on_close`/`#grab_set`/`#grab_release`/
+  # `#modal`, all delegate here internally - nothing about those public
+  # methods changed, this is where their actual work happens now.
+  #
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/wm.htm wm
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/grab.htm grab
+  class Window
+    attr_reader :path
+
+    # @api private
+    def initialize(app, path)
+      @app = app
+      @path = path.to_s
+    end
+
+    # @return [String] the Tk window path
+    def to_s
+      @path
+    end
+
+    # -- wm subcommands --
+
+    # @return [String] the window's current title
+    def title
+      @app.tcl_invoke('wm', 'title', @path)
+    end
+
+    # @param value [String] new title
+    # @return [String] the title
+    def set_title(value)
+      @app.tcl_invoke('wm', 'title', @path, value.to_s)
+    end
+
+    # @return [String] geometry string (e.g. +"400x300+0+0"+)
+    def geometry
+      @app.tcl_invoke('wm', 'geometry', @path)
+    end
+
+    # @param value [String] new geometry (e.g. +"400x300"+, +"400x300+100+50"+)
+    # @return [String] the geometry
+    def set_geometry(value)
+      @app.tcl_invoke('wm', 'geometry', @path, value.to_s)
+    end
+
+    # @return [Array(Boolean, Boolean)] [width_resizable, height_resizable]
+    def resizable
+      parts = @app.tcl_invoke('wm', 'resizable', @path).split
+      [@app.tcl_to_bool(parts[0]), @app.tcl_to_bool(parts[1])]
+    end
+
+    # @param width [Boolean] allow horizontal resize
+    # @param height [Boolean] allow vertical resize
+    # @return [void]
+    def set_resizable(width, height)
+      @app.tcl_invoke('wm', 'resizable', @path, @app.bool_to_tcl(width), @app.bool_to_tcl(height))
+    end
+
+    # Show the window (map it if withdrawn/iconified).
+    # @return [void]
+    def deiconify
+      @app.tcl_invoke('wm', 'deiconify', @path)
+    end
+
+    # Hide the window without destroying it.
+    # @return [void]
+    def withdraw
+      @app.tcl_invoke('wm', 'withdraw', @path)
+    end
+
+    # -- composite behaviors --
+
+    # 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 {App#destroy} yourself if
+    # you want it to; do nothing (or show a confirmation first) if you don't.
+    #
+    # @example Confirm before quitting
+    #   app.window.on_close { app.destroy('.') if app.message_box(message: 'Quit?', type: :yesno) == :yes }
+    # @example A toplevel that just hides instead of closing
+    #   app.window(settings_window).on_close { app.window(settings_window).withdraw }
+    #
+    # @yield called when the window's close button is pressed
+    # @return [void]
+    # @see App#bind
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/wm.htm#M46 wm protocol
+    def on_close(&block)
+      cb = @app.register_callback(block, relay_break_continue: false)
+      @app.callback_registry.reconcile([:wm_protocol, @path]) { |before| before.merge('WM_DELETE_WINDOW' => cb) }
+      @app.tcl_eval("wm protocol #{@path} WM_DELETE_WINDOW {ruby_callback #{cb}}")
+    end
+
+    # Set the input grab on the window - while held, mouse and keyboard
+    # events outside it (and its descendants) are redirected to it, the
+    # building block {#modal} uses. `grab` is its own Tcl command family,
+    # separate from `wm`.
+    # @param global [Boolean] a global grab blocks input to every other
+    #   application too, not just this one - almost never what you want;
+    #   local (the default) is scoped to this application.
+    # @return [void]
+    # @see #grab_release
+    # @see #modal
+    def grab_set(global: false)
+      args = ['grab', 'set']
+      args << '-global' if global
+      args << @path
+      @app.tcl_invoke(*args)
+      nil
+    end
+
+    # Release a grab previously set with {#grab_set}. Safe to call even if
+    # the window never held the grab - Tk itself treats that as a no-op.
+    # @return [void]
+    def grab_release
+      @app.tcl_invoke('grab', 'release', @path)
+      nil
+    end
+
+    # Make the window modal: grabs input and sets focus on it immediately.
+    # Release it explicitly with {#grab_release} (typically from the
+    # window's own dismiss/close handling) when the dialog is done - the
+    # grab is NOT released automatically just because this method returns,
+    # since a modal dialog is meant to stay grabbed for its whole visible
+    # lifetime, not just its setup.
+    #
+    # Two safety nets guard against a stuck grab locking out the rest of
+    # the display: if the window is destroyed while still grabbed (a crash
+    # mid-modal, or just forgetting to call {#grab_release} first), a
+    # <Destroy> binding releases it; if the optional setup block itself
+    # raises, the grab is released immediately rather than left dangling
+    # on a half-shown dialog.
+    #
+    # @example
+    #   settings = app.window(settings_path)
+    #   settings.modal { settings.deiconify }
+    #   # ... later, from the window's own on_close/dismiss handler ...
+    #   settings.grab_release
+    #
+    # @param global [Boolean] see {#grab_set}
+    # @yield optional - runs with the grab and focus already set
+    # @return [void]
+    # @see #grab_set
+    # @see #grab_release
+    def modal(global: false)
+      grab_set(global: global)
+      # -force: a modal dialog should own keyboard focus immediately, not
+      # merely be first in line whenever the app next happens to get it
+      # (plain `focus` only takes effect once the app already has input
+      # focus at the OS/WM level).
+      @app.tcl_invoke('focus', '-force', @path)
+      @app.bind(@path, 'Destroy') { grab_release }
+      yield if block_given?
+      nil
+    rescue
+      grab_release
+      raise
+    end
+  end
+end

data/lib/teek/wm.rb

@@ -3,20 +3,15 @@
 module Teek
   # Thin, typed wrapper around Tk's `wm` (window manager) command family -
   # one method per subcommand, coerced to the right Ruby type, reached via
-  # {App#wm}.
-  #
-  # Grouped behind a single accessor instead of more flat App methods, for
-  # the same reason {Winfo} is: `wm` is itself one big, well-known Tcl
-  # command namespace, so knowing Tcl's `wm title` gets you to {#title}
-  # directly. App's own +set_window_title+/+window_geometry+/etc. are kept
-  # as thin delegates to this - use whichever reads better to you, they're
-  # the same underlying call.
-  #
-  # Composite behaviors that orchestrate more than a single +wm+ subcommand
-  # (App#on_close's callback tracking, for instance) stay top-level App/
-  # Widget methods rather than living here - this class is only 1:1 Tcl
-  # command wrappers, nothing with Ruby-side state of its own.
+  # {App#wm}. Kept for callers already using +app.wm.title(window: ...)+ -
+  # every method here is a one-line delegate to {Window}, which is where
+  # the actual `wm`/`grab` work now lives (see {Window}'s own doc comment
+  # for why - the same window-scoped operations kept growing as more and
+  # more +window:+-kwarg methods flattened onto {App}).
   #
+  # @note Prefer +app.window(path)+ for new code - the same calls, without
+  #   repeating +window:+ on every one when you're working with one window
+  #   repeatedly.
   # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/wm.htm wm
   class Wm
     # @api private
@@ -27,34 +22,33 @@ module Teek
     # @param window [String, Widget] (default: the root window)
     # @return [String] the window's current title
     def title(window: '.')
-      @app.tcl_invoke('wm', 'title', window.to_s)
+      @app.window(window).title
     end
 
     # @param value [String] new title
     # @param window [String, Widget] (default: the root window)
     # @return [String] the title
     def set_title(value, window: '.')
-      @app.tcl_invoke('wm', 'title', window.to_s, value.to_s)
+      @app.window(window).set_title(value)
     end
 
     # @param window [String, Widget] (default: the root window)
     # @return [String] geometry string (e.g. +"400x300+0+0"+)
     def geometry(window: '.')
-      @app.tcl_invoke('wm', 'geometry', window.to_s)
+      @app.window(window).geometry
     end
 
     # @param value [String] new geometry (e.g. +"400x300"+, +"400x300+100+50"+)
     # @param window [String, Widget] (default: the root window)
     # @return [String] the geometry
     def set_geometry(value, window: '.')
-      @app.tcl_invoke('wm', 'geometry', window.to_s, value.to_s)
+      @app.window(window).set_geometry(value)
     end
 
     # @param window [String, Widget] (default: the root window)
     # @return [Array(Boolean, Boolean)] [width_resizable, height_resizable]
     def resizable(window: '.')
-      parts = @app.tcl_invoke('wm', 'resizable', window.to_s).split
-      [@app.tcl_to_bool(parts[0]), @app.tcl_to_bool(parts[1])]
+      @app.window(window).resizable
     end
 
     # @param width [Boolean] allow horizontal resize
@@ -62,21 +56,21 @@ module Teek
     # @param window [String, Widget] (default: the root window)
     # @return [void]
     def set_resizable(width, height, window: '.')
-      @app.tcl_invoke('wm', 'resizable', window.to_s, @app.bool_to_tcl(width), @app.bool_to_tcl(height))
+      @app.window(window).set_resizable(width, height)
     end
 
     # Show a window (map it if withdrawn/iconified).
     # @param window [String, Widget] (default: the root window)
     # @return [void]
     def deiconify(window: '.')
-      @app.tcl_invoke('wm', 'deiconify', window.to_s)
+      @app.window(window).deiconify
     end
 
     # Hide a window without destroying it.
     # @param window [String, Widget] (default: the root window)
     # @return [void]
     def withdraw(window: '.')
-      @app.tcl_invoke('wm', 'withdraw', window.to_s)
+      @app.window(window).withdraw
     end
   end
 end

data/lib/teek.rb

@@ -14,6 +14,9 @@ require_relative 'teek/photo'
 require_relative 'teek/dialogs'
 require_relative 'teek/winfo'
 require_relative 'teek/wm'
+require_relative 'teek/window'
+require_relative 'teek/clipboard'
+require_relative 'teek/repeating_timer'
 
 # Ruby interface to Tcl/Tk. Provides a thin wrapper around a Tcl interpreter
 # with Ruby callbacks, event bindings, and background work support.
@@ -90,7 +93,7 @@ module Teek
   ].freeze
 
   class App
-    attr_reader :interp, :widgets, :debugger, :callback_registry, :winfo, :wm
+    attr_reader :interp, :widgets, :debugger, :callback_registry, :winfo, :wm, :clipboard
     attr_writer :_pending_exception # @api private
 
     def initialize(title: nil, track_widgets: true, debug: false, &block)
@@ -98,6 +101,7 @@ module Teek
       @interp.tcl_eval('package require Tk')
       @winfo = Teek::Winfo.new(self)
       @wm = Teek::Wm.new(self)
+      @clipboard = Teek::Clipboard.new(self)
       hide
       @widgets = {}
       @widget_counters = Hash.new(0)
@@ -680,19 +684,19 @@ module Teek
     # Show a window. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
-    # @see Wm#deiconify
+    # @see Window#deiconify
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M38 wm deiconify
     def show(window = '.')
-      @wm.deiconify(window: window)
+      self.window(window).deiconify
     end
 
     # Hide a window without destroying it. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
-    # @see Wm#withdraw
+    # @see Window#withdraw
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M65 wm withdraw
     def hide(window = '.')
-      @wm.withdraw(window: window)
+      self.window(window).withdraw
     end
 
     # Enable the Tk debug console. The console starts hidden and can be
@@ -737,38 +741,38 @@ module Teek
     # @param title [String] new title
     # @param window [String] Tk window path
     # @return [String] the title
-    # @see Wm#set_title
+    # @see Window#set_title
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M63 wm title
     def set_window_title(title, window: '.')
-      @wm.set_title(title, window: window)
+      self.window(window).set_title(title)
     end
 
     # Get a window's current title.
     # @param window [String] Tk window path
     # @return [String] current title
-    # @see Wm#title
+    # @see Window#title
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M63 wm title
     def window_title(window: '.')
-      @wm.title(window: window)
+      self.window(window).title
     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 Window#set_geometry
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M42 wm geometry
     def set_window_geometry(geometry, window: '.')
-      @wm.set_geometry(geometry, window: window)
+      self.window(window).set_geometry(geometry)
     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 Window#geometry
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M42 wm geometry
     def window_geometry(window: '.')
-      @wm.geometry(window: window)
+      self.window(window).geometry
     end
 
     # Set whether a window is resizable.
@@ -776,19 +780,19 @@ module Teek
     # @param height [Boolean] allow vertical resize
     # @param window [String] Tk window path
     # @return [void]
-    # @see Wm#set_resizable
+    # @see Window#set_resizable
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M59 wm resizable
     def set_window_resizable(width, height, window: '.')
-      @wm.set_resizable(width, height, window: window)
+      self.window(window).set_resizable(width, height)
     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 Window#resizable
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M59 wm resizable
     def window_resizable(window: '.')
-      @wm.resizable(window: window)
+      self.window(window).resizable
     end
 
     # Bind a Tk event on a widget, with optional substitutions forwarded
@@ -857,6 +861,20 @@ module Teek
       @interp.tcl_eval("bind #{widget} #{event_str} {}")
     end
 
+    # A single toplevel window, addressed by path - groups `wm` subcommands
+    # and composite window-lifecycle behaviors ({#on_close}, {#grab_set}/
+    # {#grab_release}, {#modal}) into one object instead of threading
+    # +window:+ through a pile of unrelated flat methods. This app's own
+    # +window_title+/+set_window_title+/etc., {#wm}, {#on_close},
+    # {#grab_set}, {#grab_release}, and {#modal} all delegate here
+    # internally - use whichever reads better to you, they're the same
+    # underlying calls.
+    # @param path [String, Widget] (default: the root window)
+    # @return [Window]
+    def window(path = '.')
+      Window.new(self, path)
+    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).
@@ -875,12 +893,46 @@ module Teek
     # @param window [String] Tk window path (default: the root window)
     # @yield called when the window's close button is pressed
     # @return [void]
-    # @see #bind
+    # @note Prefer +app.window(window).on_close { }+ for new code - this
+    #   flat method is kept for compatibility and just delegates there.
+    # @see Window#on_close
     # @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}}")
+      self.window(window).on_close(&block)
+    end
+
+    # Set the input grab on window. See {Window#grab_set}.
+    # @param window [String, Widget] (default: the root window)
+    # @param global [Boolean]
+    # @return [void]
+    # @note Prefer +app.window(window).grab_set+ for new code - this flat
+    #   method is kept for compatibility and just delegates there.
+    # @see #grab_release
+    # @see #modal
+    def grab_set(window: '.', global: false)
+      self.window(window).grab_set(global: global)
+    end
+
+    # Release a grab previously set with {#grab_set}. See {Window#grab_release}.
+    # @param window [String, Widget] (default: the root window)
+    # @return [void]
+    # @note Prefer +app.window(window).grab_release+ for new code - this
+    #   flat method is kept for compatibility and just delegates there.
+    def grab_release(window: '.')
+      self.window(window).grab_release
+    end
+
+    # Make window modal. See {Window#modal}.
+    # @param window [String, Widget] (default: the root window)
+    # @param global [Boolean] see {#grab_set}
+    # @note Prefer +app.window(window).modal { }+ for new code - this flat
+    #   method is kept for compatibility and just delegates there.
+    # @yield optional - runs with the grab and focus already set
+    # @return [void]
+    # @see #grab_set
+    # @see #grab_release
+    def modal(window: '.', global: false, &block)
+      self.window(window).modal(global: global, &block)
     end
 
     # Register a widget as a file drop target.
@@ -1070,115 +1122,4 @@ module Teek
       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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teek
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - James Cook
@@ -139,6 +139,7 @@ files:
 - lib/teek/background_thread.rb
 - lib/teek/callback_registry.rb
 - lib/teek/canvas_bind_interceptor.rb
+- lib/teek/clipboard.rb
 - lib/teek/command_interceptors.rb
 - lib/teek/debugger.rb
 - lib/teek/demo_support.rb
@@ -148,9 +149,11 @@ files:
 - lib/teek/photo.rb
 - lib/teek/platform.rb
 - lib/teek/ractor_support.rb
+- lib/teek/repeating_timer.rb
 - lib/teek/tag_bind_interceptor.rb
 - lib/teek/version.rb
 - lib/teek/widget.rb
+- lib/teek/window.rb
 - lib/teek/winfo.rb
 - lib/teek/wm.rb
 - teek.gemspec