teek 0.1.5 → 0.2.0

data/lib/teek/dialogs.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Teek
+  class App
+    # Show the native "choose file to open" dialog.
+    #
+    # @param filetypes [Array<Array>, nil] e.g.
+    #   +[["PNG Images", ".png"], ["All Files", "*"]]+ - the second
+    #   element of each pair can also be an array of extensions
+    #   (+["Images", [".png", ".jpg"]]+)
+    # @param initialdir [String, nil] directory the dialog starts in
+    # @param initialfile [String, nil] filename pre-filled in the dialog
+    # @param title [String, nil] dialog window title
+    # @param multiple [Boolean] allow selecting more than one file
+    # @param parent [String, nil] parent window (defaults to the root window)
+    # @return [String, Array<String>, nil] the chosen path (an array of
+    #   paths if +multiple:+), or +nil+ if the dialog was cancelled
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/getOpenFile.htm tk_getOpenFile
+    def choose_open_file(filetypes: nil, initialdir: nil, initialfile: nil,
+                          title: nil, multiple: false, parent: nil)
+      args = ['tk_getOpenFile']
+      args.push('-filetypes', build_filetypes(filetypes)) if filetypes
+      args.push('-initialdir', initialdir) if initialdir
+      args.push('-initialfile', initialfile) if initialfile
+      args.push('-title', title) if title
+      args.push('-parent', parent) if parent
+      args.push('-multiple', bool_to_tcl(true)) if multiple
+
+      result = tcl_invoke(*args)
+      return nil if result.empty?
+
+      multiple ? split_list(result) : result
+    end
+
+    # Show the native "choose file to save" dialog.
+    #
+    # @param filetypes [Array<Array>, nil] see {#choose_open_file}
+    # @param initialdir [String, nil] directory the dialog starts in
+    # @param initialfile [String, nil] filename pre-filled in the dialog
+    # @param title [String, nil] dialog window title
+    # @param defaultextension [String, nil] extension appended if the
+    #   typed filename doesn't already have one
+    # @param confirmoverwrite [Boolean] ask before overwriting an
+    #   existing file (Tk's own default is true; pass false to skip the
+    #   confirmation)
+    # @param parent [String, nil] parent window (defaults to the root window)
+    # @return [String, nil] the chosen path, or +nil+ if cancelled
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/getOpenFile.htm tk_getSaveFile
+    def choose_save_file(filetypes: nil, initialdir: nil, initialfile: nil,
+                          title: nil, defaultextension: nil, confirmoverwrite: true, parent: nil)
+      args = ['tk_getSaveFile']
+      args.push('-filetypes', build_filetypes(filetypes)) if filetypes
+      args.push('-initialdir', initialdir) if initialdir
+      args.push('-initialfile', initialfile) if initialfile
+      args.push('-title', title) if title
+      args.push('-defaultextension', defaultextension) if defaultextension
+      args.push('-confirmoverwrite', bool_to_tcl(false)) unless confirmoverwrite
+      args.push('-parent', parent) if parent
+
+      result = tcl_invoke(*args)
+      result.empty? ? nil : result
+    end
+
+    # Show a message box with one or more buttons.
+    #
+    # @param message [String] the main message text
+    # @param title [String, nil] dialog window title
+    # @param detail [String, nil] additional explanatory text, shown
+    #   smaller below +message+
+    # @param icon [:error, :info, :question, :warning] icon to display
+    # @param type [:ok, :okcancel, :abortretryignore, :yesno, :yesnocancel, :retrycancel]
+    #   which button(s) to show
+    # @param default [Symbol, nil] which button is focused by default
+    #   (e.g. +:cancel+); defaults to Tk's own choice if omitted
+    # @param parent [String, nil] parent window (defaults to the root window)
+    # @return [Symbol] the pressed button - +:ok+, +:cancel+, +:yes+,
+    #   +:no+, +:abort+, +:retry+, or +:ignore+
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/messageBox.htm tk_messageBox
+    def message_box(message:, title: nil, detail: nil, icon: :info, type: :ok,
+                     default: nil, parent: nil)
+      args = ['tk_messageBox', '-message', message.to_s]
+      args.push('-title', title) if title
+      args.push('-detail', detail) if detail
+      args.push('-icon', icon.to_s) if icon
+      args.push('-type', type.to_s) if type
+      args.push('-default', default.to_s) if default
+      args.push('-parent', parent) if parent
+
+      tcl_invoke(*args).to_sym
+    end
+
+    # Show the native color picker dialog.
+    #
+    # @param initial [String, nil] initial color (e.g. +"#ff0000"+)
+    # @param title [String, nil] dialog window title
+    # @param parent [String, nil] parent window (defaults to the root window)
+    # @return [String, nil] the chosen color as +"#rrggbb"+, or +nil+ if cancelled
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/chooseColor.htm tk_chooseColor
+    def choose_color(initial: nil, title: nil, parent: nil)
+      args = ['tk_chooseColor']
+      args.push('-initialcolor', initial) if initial
+      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
+    # @param x [Integer] screen x coordinate
+    # @param y [Integer] screen y coordinate
+    # @param entry [Integer, String, nil] index or label of the entry to
+    #   show as active
+    # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/menu.htm#M42 tk_popup
+    def popup_menu(menu, x:, y:, entry: nil)
+      args = ['tk_popup', menu.to_s, x.to_s, y.to_s]
+      args << entry.to_s if entry
+      tcl_invoke(*args)
+      nil
+    end
+
+    private
+
+    # Builds the nested Tcl list -filetypes expects:
+    # {{name extensionOrExtensionList} {name2 ...}}
+    def build_filetypes(filetypes)
+      entries = filetypes.map do |name, exts|
+        ext_arg = exts.is_a?(Array) ? make_list(*exts) : exts.to_s
+        make_list(name.to_s, ext_arg)
+      end
+      make_list(*entries)
+    end
+  end
+end

data/lib/teek/menu_interceptor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'command_interceptors'
+require_relative 'callback_registry'
+
+module Teek
+  # @api private
+  #
+  # Live-scan helper for the "menu" {CommandInterceptors} entry below.
+  #
+  # Menu entries are not windows (only the menu itself is one), so they
+  # never fire <Destroy>; entry deletion is silent and Tk renumbers the
+  # survivors internally. Because of that, entry-level callbacks can't be
+  # tracked by index or by any per-entry event - the only sound way to know
+  # which callbacks are still needed is to ask Tk what's actually live
+  # after every mutating call and release whatever dropped out.
+  module MenuInterceptor
+    ENTRY_SUBCOMMANDS = %w[add insert entryconfigure delete].freeze
+
+    LIVE_COMMANDS_TCL_PROC = <<~TCL.freeze
+      proc ::teek_menu_live_commands {path} {
+        set result {}
+        if {![winfo exists $path]} { return $result }
+        set last [$path index end]
+        if {$last eq "none"} { return $result }
+        for {set i 0} {$i <= $last} {incr i} {
+          set cmd ""
+          catch {set cmd [$path entrycget $i -command]}
+          lappend result $cmd
+        }
+        return $result
+      }
+    TCL
+
+    def self.live_command_ids(app, path)
+      app.ensure_tcl_helper(:menu_live_commands) { LIVE_COMMANDS_TCL_PROC }
+      raw = app.tcl_eval("::teek_menu_live_commands #{path}")
+      # \z anchors this to a BARE `ruby_callback <id>` with nothing after -
+      # correct today because teek never appends %-substitutions to a menu
+      # entry's -command (that only happens for App#bind's widget bindings).
+      # If substitution support is ever added here, this regex silently
+      # stops matching and those ids leak on rebuild/delete - drop the \z
+      # anchor (match just the leading `ruby_callback <id>`) if that changes.
+      app.split_list(raw).each_with_object({}) do |cmd, ids|
+        ids[Regexp.last_match(1)] = Regexp.last_match(1) if cmd =~ /\Aruby_callback (\S+)\z/
+      end
+    end
+  end
+
+  # Any add/insert/entryconfigure/delete on a menu goes through raw_command
+  # unchanged (any command: Proc it carries is already registered correctly
+  # by raw_command itself), then reconciles tracked entry callbacks against
+  # Tk's live entrycget values - see {MenuInterceptor}.
+  CommandInterceptors.register('menu', 'menu_entry') do |app, path, args, kwargs|
+    next nil unless MenuInterceptor::ENTRY_SUBCOMMANDS.include?(args[0]&.to_s)
+
+    result = app.raw_command(path, *args, **kwargs)
+    app.callback_registry.reconcile([:menu, path]) { |_before| MenuInterceptor.live_command_ids(app, path) }
+    result
+  end
+end

data/lib/teek/photo.rb

@@ -50,10 +50,45 @@ module Teek
         @counter += 1
         "teek_photo#{@counter}"
       end
+
+      # @api private
+      #
+      # Builds the proc registered as this instance's finalizer. Must not
+      # close over +self+ (the Photo instance) or any of its ivars
+      # directly - a finalizer that references its own object keeps that
+      # object permanently reachable, so it would never actually be
+      # collected. +name+/+app+ are plain local captures instead.
+      #
+      # Finalizers can run on any thread, so the delete goes through
+      # {Interp#queue_for_main} (fire-and-forget) rather than #tcl_eval,
+      # which would block on a cross-thread queue wait if called from a
+      # background thread - risky from inside a GC finalizer. The +catch+
+      # means a concurrent explicit #delete (or an interpreter that's
+      # already torn down by the time this runs) is a silent no-op, not
+      # an error with nowhere to go.
+      def finalizer_for(name, app)
+        proc do
+          begin
+            app.interp.queue_for_main(proc { app.tcl_eval("catch {image delete #{name}}") })
+          rescue Teek::TclError
+            # interpreter already torn down - nothing to clean up
+          end
+        end
+      end
     end
 
     # Create a new photo image.
     #
+    # The underlying Tk image is automatically deleted once this Photo
+    # object is garbage collected and nothing else references it - keep
+    # it around (an ivar, a collection, etc.) for as long as you need the
+    # image, the same contract as File or Socket. If only the image
+    # *name* is kept (e.g. passed into a widget's +image:+) and this
+    # wrapper is dropped, the image can be reclaimed out from under that
+    # reference; Tk shows a broken image rather than crashing, but the
+    # image won't come back - call {#delete} explicitly rather than
+    # relying on GC timing if you need deterministic cleanup.
+    #
     # @param app [Teek::App] the application instance
     # @param name [String, nil] Tcl image name (auto-generated if nil)
     # @param width [Integer, nil] image width in pixels
@@ -78,6 +113,21 @@ module Teek
       kwargs[:gamma] = gamma if gamma
 
       @app.command(:image, :create, :photo, @name, **kwargs)
+      ObjectSpace.define_finalizer(self, self.class.finalizer_for(@name, @app))
+    end
+
+    # Invoke a photo subcommand not covered by a dedicated method above
+    # (e.g. +copy+, +read+, +write+). Prepends the image name as the Tcl
+    # command, exactly like {Widget#command} does for widgets.
+    #
+    # @example Subsample a copy of another photo
+    #   thumb = Teek::Photo.new(app)
+    #   thumb.command(:copy, source_photo, subsample: 4)
+    # @param args positional arguments
+    # @param kwargs keyword arguments mapped to +-key value+ pairs
+    # @return [String] the Tcl result
+    def command(*args, **kwargs)
+      @app.command(@name, *args, **kwargs)
     end
 
     # Write RGBA pixel data to the image.
@@ -197,8 +247,13 @@ module Teek
 
     # Delete this photo image and free its resources.
     #
+    # Cancels the GC finalizer registered by {#initialize} - otherwise a
+    # later collection could delete an unrelated image if this name gets
+    # reused (e.g. an explicit +name:+ passed to a later Photo).
+    #
     # @return [void]
     def delete
+      ObjectSpace.undefine_finalizer(self)
       @app.tcl_eval("image delete #{@name}")
     end
 

data/lib/teek/tag_bind_interceptor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'command_interceptors'
+require_relative 'callback_registry'
+
+module Teek
+  # @api private
+  #
+  # Live-scan helper for the shared "text"/"ttk::treeview" {CommandInterceptors}
+  # entry below - both widgets have byte-identical `tag bind`/`tag names` shapes.
+  #
+  # Tags aren't windows, so a tag's bound callback never fires <Destroy> on
+  # its own; the widget that owns it is typically long-lived and reused
+  # (log panes, editors, tree views), so tags churn while the widget
+  # persists. Unlike menu entries, a tag name is a stable hash key Tk never
+  # renumbers, so reconciling is a straightforward full scan: enumerate
+  # every live tag (`tag names`), read back what's bound to each
+  # (`tag bind $tag` / `tag bind $tag $seq`), and release whatever dropped out.
+  module TagBindInterceptor
+    MUTATING_SUBCOMMANDS = %w[bind delete].freeze
+
+    LIVE_COMMANDS_TCL_PROC = <<~TCL.freeze
+      proc ::teek_tag_live_commands {path} {
+        set result {}
+        foreach tag [$path tag names] {
+          foreach seq [$path tag bind $tag] {
+            lappend result [$path tag bind $tag $seq]
+          }
+        }
+        return $result
+      }
+    TCL
+
+    def self.live_command_ids(app, path)
+      app.ensure_tcl_helper(:tag_live_commands) { LIVE_COMMANDS_TCL_PROC }
+      raw = app.tcl_eval("::teek_tag_live_commands #{path}")
+      # \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 tag-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.
+      app.split_list(raw).each_with_object({}) do |cmd, ids|
+        ids[Regexp.last_match(1)] = Regexp.last_match(1) if cmd =~ /\Aruby_callback (\S+)\z/
+      end
+    end
+
+    # A `tag bind`/`tag delete` call goes through raw_command unchanged (a
+    # bound Proc is registered exactly like any other bind-shaped
+    # positional arg), then reconciles tracked tag callbacks against Tk's
+    # live tag-bind state.
+    def self.call(app, path, args, kwargs)
+      return nil unless args[0]&.to_s == 'tag' && MUTATING_SUBCOMMANDS.include?(args[1]&.to_s)
+
+      result = app.raw_command(path, *args, **kwargs)
+      app.callback_registry.reconcile([:tag_bind, path]) { |_before| live_command_ids(app, path) }
+      result
+    end
+  end
+
+  # text and ttk::treeview share byte-identical `tag bind`/`tag names`
+  # shapes, so both register the same interceptor method.
+  CommandInterceptors.register('text', 'tag_bind') { |*a| TagBindInterceptor.call(*a) }
+  CommandInterceptors.register('ttk::treeview', 'tag_bind') { |*a| TagBindInterceptor.call(*a) }
+end

data/lib/teek/version.rb

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

data/lib/teek/widget.rb

@@ -36,7 +36,9 @@ module Teek
     #   btn.command(:invoke)                  # => .ttkbutton1 invoke
     #
     # @param args positional arguments
-    # @param kwargs keyword arguments mapped to -key value pairs
+    # @param kwargs keyword arguments mapped to -key value pairs; any Proc
+    #   value (e.g. command:) is tracked and released if reconfigured or
+    #   when this widget is destroyed
     # @return [String] the Tcl result
     def command(*args, **kwargs)
       @app.command(@path, *args, **kwargs)
@@ -51,7 +53,19 @@ module Teek
     # Check if this widget still exists in the Tk interpreter.
     # @return [Boolean]
     def exist?
-      @app.tcl_eval("winfo exists #{@path}") == '1'
+      @app.winfo.exists?(@path)
+    end
+
+    # @return [Integer] current width in pixels
+    # @see Winfo#width
+    def width
+      @app.winfo.width(@path)
+    end
+
+    # @return [Integer] current height in pixels
+    # @see Winfo#height
+    def height
+      @app.winfo.height(@path)
     end
 
     # Pack this widget.
@@ -88,6 +102,15 @@ module Teek
       @app.unbind(@path, event)
     end
 
+    # Register a handler for this window's close button (WM_DELETE_WINDOW).
+    # Meant for toplevels; see {App#on_close} for the full behavior.
+    # @yield called when the window's close button is pressed
+    # @return [void]
+    # @see App#on_close
+    def on_close(&block)
+      @app.on_close(window: @path, &block)
+    end
+
     def inspect
       "#<Teek::Widget #{@path}>"
     end

data/lib/teek/winfo.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Teek
+  # Thin, typed wrapper around Tk's `winfo` command family - one method
+  # per subquery, coerced to the right Ruby type, reached via {App#winfo}.
+  #
+  # Grouped behind a single accessor instead of a dozen-plus flat App
+  # methods, since `winfo` is itself one big, well-known Tcl command
+  # namespace - knowing Tcl's `winfo width` gets you to {#width} directly.
+  # Every method accepts a path String or anything that responds to
+  # +to_s+ with one (a {Widget}, for instance).
+  #
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/winfo.htm winfo
+  class Winfo
+    # @api private
+    def initialize(app)
+      @app = app
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] current width in pixels
+    def width(path)
+      query('width', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] current height in pixels
+    def height(path)
+      query('height', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] requested (natural) width in pixels
+    def reqwidth(path)
+      query('reqwidth', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] requested (natural) height in pixels
+    def reqheight(path)
+      query('reqheight', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] x coordinate of the window's top-left corner, in screen pixels
+    def rootx(path)
+      query('rootx', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] y coordinate of the window's top-left corner, in screen pixels
+    def rooty(path)
+      query('rooty', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] x coordinate relative to the parent widget
+    def x(path)
+      query('x', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Integer] y coordinate relative to the parent widget
+    def y(path)
+      query('y', path).to_i
+    end
+
+    # @param path [String, Widget] any window on the same screen (default: the root window)
+    # @return [Integer] the mouse pointer's current x coordinate, in screen pixels
+    def pointerx(path = '.')
+      query('pointerx', path).to_i
+    end
+
+    # @param path [String, Widget] any window on the same screen (default: the root window)
+    # @return [Integer] the mouse pointer's current y coordinate, in screen pixels
+    def pointery(path = '.')
+      query('pointery', path).to_i
+    end
+
+    # @param path [String, Widget]
+    # @return [Boolean] whether a window currently exists at +path+
+    def exists?(path)
+      query('exists', path) == '1'
+    end
+
+    # @param path [String, Widget]
+    # @return [String] the Tk widget class (e.g. +"TButton"+, +"Frame"+)
+    def class_name(path)
+      query('class', path)
+    end
+
+    # @param path [String, Widget]
+    # @return [Boolean] whether the window is currently mapped (actually displayed)
+    def ismapped?(path)
+      query('ismapped', path) == '1'
+    end
+
+    private
+
+    def query(subcommand, path)
+      @app.tcl_invoke('winfo', subcommand, path.to_s)
+    end
+  end
+end

data/lib/teek/wm.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/wm.htm wm
+  class Wm
+    # @api private
+    def initialize(app)
+      @app = app
+    end
+
+    # @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)
+    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)
+    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)
+    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)
+    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])]
+    end
+
+    # @param width [Boolean] allow horizontal resize
+    # @param height [Boolean] allow vertical resize
+    # @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))
+    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)
+    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)
+    end
+  end
+end