teek 0.1.0 → 0.1.2

data/lib/teek.rb

@@ -3,6 +3,8 @@
 require 'tcltklib'
 require_relative 'teek/version'
 require_relative 'teek/ractor_support'
+require_relative 'teek/widget'
+require_relative 'teek/photo'
 
 # Ruby interface to Tcl/Tk. Provides a thin wrapper around a Tcl interpreter
 # with Ruby callbacks, event bindings, and background work support.
@@ -52,6 +54,7 @@ module Teek
       @interp.tcl_eval('package require Tk')
       hide
       @widgets = {}
+      @widget_counters = Hash.new(0)
       debug ||= !!ENV['TEEK_DEBUG']
       track_widgets = true if debug
       setup_widget_tracking if track_widgets
@@ -118,6 +121,7 @@ module Teek
     # @param ms [Integer] delay in milliseconds
     # @yield block to call when the timer fires
     # @return [String] timer ID, pass to {#after_cancel} to cancel
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/after.htm#M5 after ms
     def after(ms, &block)
       cb_id = nil
       cb_id = @interp.register_callback(proc { |*|
@@ -132,6 +136,7 @@ module Teek
     # Schedule a block to run once when the event loop is idle.
     # @yield block to call when the event loop is idle
     # @return [String] timer ID, pass to {#after_cancel} to cancel
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/after.htm#M9 after idle
     def after_idle(&block)
       cb_id = nil
       cb_id = @interp.register_callback(proc { |*|
@@ -146,6 +151,7 @@ module Teek
     # Cancel a pending {#after} or {#after_idle} timer.
     # @param after_id [String] timer ID returned by {#after} or {#after_idle}
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/after.htm#M7 after cancel
     def after_cancel(after_id)
       @interp.tcl_eval("after cancel #{after_id}")
       if (cb_id = after_id.instance_variable_get(:@cb_id))
@@ -206,6 +212,36 @@ module Teek
       @interp.tcl_eval(parts.join(' '))
     end
 
+    # Create a Tk widget and return a {Widget} wrapper.
+    #
+    # Auto-generates a unique path if none is given. The path is derived from
+    # the widget type and a monotonic counter.
+    #
+    # @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 kwargs keyword arguments passed to the Tk widget command
+    # @return [Widget] the created widget
+    #
+    # @example Auto-named
+    #   btn = app.create_widget('ttk::button', text: 'Click')
+    #   # btn.path => ".ttkbtn1"
+    #
+    # @example Explicit path
+    #   frm = app.create_widget('ttk::frame', '.myframe')
+    #
+    # @example Nested under a parent
+    #   frm = app.create_widget('ttk::frame')
+    #   btn = app.create_widget('ttk::button', parent: frm, text: 'Click')
+    #   # btn.path => ".ttkfrm1.ttkbtn1"
+    #
+    def create_widget(type, path = nil, parent: nil, **kwargs)
+      type_s = type.to_s
+      path ||= next_widget_path(type_s, parent)
+      command(type_s, path, **kwargs)
+      Widget.new(self, path)
+    end
+
     # Add a directory to Tcl's package search path.
     # @param path [String] directory containing Tcl packages
     # @return [void]
@@ -218,6 +254,7 @@ module Teek
     # @param version [String, nil] minimum version constraint
     # @return [String] the version that was loaded
     # @raise [Teek::TclError] if the package is not found
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/package.htm#M10 package require
     def require_package(name, version = nil)
       cmd = version ? "package require #{name} #{version}" : "package require #{name}"
       tcl_eval(cmd)
@@ -228,6 +265,7 @@ module Teek
     # List all packages known to this interpreter.
     # Scans +auto_path+ for package indexes before querying.
     # @return [Array<String>]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/package.htm#M7 package names
     def package_names
       scan_packages
       split_list(tcl_eval('package names'))
@@ -236,6 +274,7 @@ module Teek
     # Check if a package is already loaded in this interpreter.
     # @param name [String] package name
     # @return [Boolean]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/package.htm#M8 package present
     def package_present?(name)
       tcl_eval("package present #{name}")
       true
@@ -247,6 +286,7 @@ module Teek
     # Scans +auto_path+ for package indexes before querying.
     # @param name [String] package name
     # @return [Array<String>]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/package.htm#M14 package versions
     def package_versions(name)
       scan_packages
       split_list(tcl_eval("package versions #{name}"))
@@ -256,6 +296,7 @@ module Teek
     # @param name [String] variable name
     # @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}}")
     end
@@ -264,6 +305,7 @@ module Teek
     # @param name [String] variable name
     # @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}")
     end
@@ -271,15 +313,55 @@ module Teek
     # Destroy a widget and all its children.
     # @param widget [String] Tk widget path (e.g. ".frame1")
     # @return [void]
-    def destroy(widget)
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/destroy.htm destroy
+    def destroy(widget = '.')
+      raise ArgumentError, 'widget path cannot be nil' if widget.nil?
       tcl_eval("destroy #{widget}")
     end
 
+    # Measure the pixel width of a text string in a given font.
+    # Uses Tk's C font API directly — faster than the Tcl +font measure+ command.
+    # @param font [String] font description (e.g. "Helvetica 12", "TkDefaultFont")
+    # @param text [String] text to measure
+    # @return [Integer] pixel width
+    # @raise [Teek::TclError] if the font is not found
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkLib/MeasureChar.htm Tk_TextWidth
+    def text_width(font, text)
+      @interp.text_width(font, text)
+    end
+
+    # Get font metrics (ascent, descent, linespace) for a given font.
+    # Uses Tk's C font API directly.
+    # @param font [String] font description (e.g. "Helvetica 12", "TkDefaultFont")
+    # @return [Hash{Symbol => Integer}] +:ascent+, +:descent+, +:linespace+
+    # @raise [Teek::TclError] if the font is not found
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkLib/FontId.htm Tk_GetFontMetrics
+    def font_metrics(font)
+      @interp.font_metrics(font)
+    end
+
+    # Measure how many bytes of text fit within a pixel width limit.
+    # Useful for text truncation, ellipsis, and line wrapping.
+    # @param font [String] font description (e.g. "Helvetica 12")
+    # @param text [String] text to measure
+    # @param max_pixels [Integer] maximum pixel width (-1 for unlimited)
+    # @param opts [Hash] options
+    # @option opts [Boolean] :partial_ok allow partial character at boundary
+    # @option opts [Boolean] :whole_words break only at word boundaries
+    # @option opts [Boolean] :at_least_one always return at least one character
+    # @return [Hash{Symbol => Integer}] +:bytes+ and +:width+
+    # @raise [Teek::TclError] if the font is not found
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkLib/MeasureChar.htm Tk_MeasureChars
+    def measure_chars(font, text, max_pixels, **opts)
+      @interp.measure_chars(font, text, max_pixels, opts)
+    end
+
     # Show a busy cursor on a window while executing a block.
     # The cursor is restored even if the block raises.
     # @param window [String] Tk window path
     # @yield the work to perform while busy
     # @return the block's return value
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/busy.htm tk busy
     def busy(window: '.')
       tcl_eval("tk busy hold #{window}")
       tcl_eval('update idletasks')
@@ -290,6 +372,7 @@ module Teek
 
     # Enter the Tk event loop. Blocks until the application exits.
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkLib/MainLoop.htm Tk_MainLoop
     def mainloop
       if defined?(IRB) || defined?(Pry) || $0 == 'irb' || $0 == 'pry'
         warn "Teek: mainloop blocks the current thread and will make your REPL unresponsive.\n" \
@@ -304,12 +387,14 @@ module Teek
 
     # Process all pending events and idle callbacks, then return.
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/update.htm update
     def update
       @interp.tcl_eval('update')
     end
 
     # Process only pending idle callbacks (e.g. geometry redraws), then return.
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/update.htm update idletasks
     def update_idletasks
       @interp.tcl_eval('update idletasks')
     end
@@ -317,6 +402,7 @@ module Teek
     # Show a window. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M38 wm deiconify
     def show(window = '.')
       @interp.tcl_eval("wm deiconify #{window}")
     end
@@ -324,6 +410,7 @@ module Teek
     # Hide a window without destroying it. Defaults to the root window (".").
     # @param window [String] Tk window path
     # @return [void]
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M65 wm withdraw
     def hide(window = '.')
       @interp.tcl_eval("wm withdraw #{window}")
     end
@@ -332,6 +419,7 @@ module Teek
     # @param title [String] new title
     # @param window [String] Tk window path
     # @return [String] the 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}}")
     end
@@ -339,6 +427,7 @@ module Teek
     # Get a window's current title.
     # @param window [String] Tk window path
     # @return [String] current 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}")
     end
@@ -347,6 +436,7 @@ module Teek
     # @param geometry [String] geometry string
     # @param window [String] Tk window path
     # @return [String] the 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}")
     end
@@ -354,6 +444,7 @@ module Teek
     # Get a window's current geometry.
     # @param window [String] Tk window path
     # @return [String] geometry string (e.g. "400x300+0+0")
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/wm.htm#M42 wm geometry
     def window_geometry(window: '.')
       tcl_eval("wm geometry #{window}")
     end
@@ -363,6 +454,7 @@ module Teek
     # @param height [Boolean] allow vertical resize
     # @param window [String] Tk window path
     # @return [void]
+    # @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}")
     end
@@ -370,6 +462,7 @@ module Teek
     # Get whether a window is resizable.
     # @param window [String] Tk window path
     # @return [Array(Boolean, Boolean)] [width_resizable, height_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']
@@ -405,6 +498,7 @@ module Teek
     # @yield [*values] called when the event fires, with substitution values
     # @return [void]
     # @see #unbind
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/bind.htm bind
     #
     BIND_SUBS = {
       x: '%x', y: '%y',                   # window coordinates
@@ -431,6 +525,7 @@ module Teek
     # @param event [String] Tk event name, with or without angle brackets
     # @return [void]
     # @see #bind
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/bind.htm bind
     def unbind(widget, event)
       event_str = event.start_with?('<') ? event : "<#{event}>"
       @interp.tcl_eval("bind #{widget} #{event_str} {}")
@@ -481,6 +576,54 @@ module Teek
 
     private
 
+    # Short prefixes for common Tk widget types.
+    # The base name (after the last ::) is looked up here; the namespace
+    # prefix (e.g. "ttk") is prepended verbatim.  Unmapped types fall
+    # back to the full lowercased name with colons stripped.
+    WIDGET_PREFIXES = {
+      'button'      => 'btn',
+      'label'       => 'lbl',
+      'entry'       => 'ent',
+      'frame'       => 'frm',
+      'text'        => 'txt',
+      'canvas'      => 'cvs',
+      'scrollbar'   => 'sb',
+      'scale'       => 'scl',
+      'checkbutton' => 'chk',
+      'radiobutton' => 'rad',
+      'combobox'    => 'cbx',
+      'labelframe'  => 'lfrm',
+      'treeview'    => 'tv',
+      'notebook'    => 'nb',
+      'progressbar' => 'pbar',
+      'separator'   => 'sep',
+      'spinbox'     => 'spn',
+      'panedwindow' => 'pw',
+      'toplevel'    => 'top',
+      'menubutton'  => 'mbtn',
+      'sizegrip'    => 'sg',
+    }.freeze
+    private_constant :WIDGET_PREFIXES
+
+    def next_widget_path(type, parent)
+      prefix = widget_prefix(type)
+      @widget_counters[prefix] += 1
+      parent_path = parent ? parent.to_s : ''
+      if parent_path.empty? || parent_path == '.'
+        ".#{prefix}#{@widget_counters[prefix]}"
+      else
+        "#{parent_path}.#{prefix}#{@widget_counters[prefix]}"
+      end
+    end
+
+    def widget_prefix(type)
+      parts = type.downcase.split('::')
+      base = parts.pop
+      ns = parts.join
+      short = WIDGET_PREFIXES[base] || base
+      "#{ns}#{short}"
+    end
+
     # Force Tcl to scan auto_path for pkgIndex.tcl files so that
     # package_names and package_versions reflect all discoverable packages.
     def scan_packages

data/sample/calculator.rb

@@ -23,21 +23,18 @@ class Calculator
 
   def build_ui
     @app.show
-    @app.command(:wm, 'title', '.', 'Calculator')
-    @app.command(:wm, 'resizable', '.', 0, 0)
+    @app.set_window_title('Calculator')
+    @app.set_window_resizable(false, false)
 
     # Button style — use a larger font since macOS aqua theme
     # ignores vertical stretch; font size drives button height
     @app.tcl_eval('ttk::style configure Calc.TButton -font {{TkDefaultFont} 18}')
 
     # Display
-    @app.command(:set, '::display', '0')
-    @app.command('ttk::entry', '.display',
-      textvariable: '::display',
-      justify: :right,
-      state: :readonly,
-      font: '{TkDefaultFont} 24')
-    @app.command(:grid, '.display', row: 0, column: 0, columnspan: 4,
+    @app.set_variable('::display', '0')
+    @display = @app.create_widget('ttk::entry', textvariable: '::display',
+      justify: :right, state: :readonly, font: '{TkDefaultFont} 24')
+    @display.grid(row: 0, column: 0, columnspan: 4,
       sticky: :ew, padx: 4, pady: 4, ipady: 8)
 
     build_buttons
@@ -82,32 +79,30 @@ class Calculator
   # Click a button by its label (for demo/testing).
   # In recording mode, shows the pressed visual state briefly before invoking.
   def click(label, recording: false)
-    path = @buttons[label]
-    return unless path
+    widget = @buttons[label]
+    return unless widget
     if recording
-      @app.command(path, 'state', 'pressed')
+      widget.command('state', 'pressed')
       @app.after(80) {
-        @app.command(path, 'state', '!pressed')
-        @app.command(path, 'invoke')
+        widget.command('state', '!pressed')
+        widget.command(:invoke)
       }
     else
-      @app.command(path, 'invoke')
+      widget.command(:invoke)
     end
   end
 
   def button(text, row, col, style: :num, colspan: 1, &action)
-    @btn_id = (@btn_id || 0) + 1
     @buttons ||= {}
-    path = ".btn_#{@btn_id}"
-    @buttons[text] = path
-    @app.command('ttk::button', path, text: text, style: 'Calc.TButton',
+    widget = @app.create_widget('ttk::button', text: text, style: 'Calc.TButton',
       command: proc { |*| action.call })
-    @app.command(:grid, path, row: row, column: col, columnspan: colspan,
+    @buttons[text] = widget
+    widget.grid(row: row, column: col, columnspan: colspan,
       sticky: :nsew, padx: 2, pady: 2)
   end
 
   def update_display
-    @app.command(:set, '::display', @display_value)
+    @app.set_variable('::display', @display_value)
   end
 
   # --- Calculator logic ---

data/sample/debug_demo.rb

@@ -13,33 +13,31 @@ app.set_window_title('Debug Demo App')
 app.set_window_geometry('300x200')
 
 # Create some widgets
-app.tcl_eval('ttk::frame .f')
-app.tcl_eval('pack .f -fill both -expand 1 -padx 10 -pady 10')
+frame = app.create_widget('ttk::frame')
+app.command(:pack, frame, fill: :both, expand: 1, padx: 10, pady: 10)
 
-app.tcl_eval('ttk::label .f.lbl -text "Hello from the app"')
-app.tcl_eval('pack .f.lbl -pady 5')
+lbl = app.create_widget('ttk::label', parent: frame, text: 'Hello from the app')
+app.command(:pack, lbl, pady: 5)
 
-app.tcl_eval('ttk::entry .f.ent')
-app.tcl_eval('pack .f.ent -pady 5')
+ent = app.create_widget('ttk::entry', parent: frame)
+app.command(:pack, ent, pady: 5)
 
 # Button that creates more widgets dynamically
-counter = 0
-cb = app.register_callback(proc { |*|
-  counter += 1
-  app.tcl_eval("ttk::button .f.btn#{counter} -text {Button #{counter}}")
-  app.tcl_eval("pack .f.btn#{counter} -pady 2")
-})
-app.tcl_eval("ttk::button .f.add -text {Add Widget} -command {ruby_callback #{cb}}")
-app.tcl_eval('pack .f.add -pady 5')
+dynamic_widgets = []
+add_btn = app.create_widget('ttk::button', parent: frame, text: 'Add Widget',
+  command: proc { |*|
+    btn = app.create_widget('ttk::button', parent: frame, text: "Button #{dynamic_widgets.size + 1}")
+    app.command(:pack, btn, pady: 2)
+    dynamic_widgets << btn
+  })
+app.command(:pack, add_btn, pady: 5)
 
 # Button to destroy last widget
-rm_cb = app.register_callback(proc { |*|
-  if counter > 0
-    app.destroy(".f.btn#{counter}")
-    counter -= 1
-  end
-})
-app.tcl_eval("ttk::button .f.rm -text {Remove Widget} -command {ruby_callback #{rm_cb}}")
-app.tcl_eval('pack .f.rm -pady 5')
+rm_btn = app.create_widget('ttk::button', parent: frame, text: 'Remove Widget',
+  command: proc { |*|
+    widget = dynamic_widgets.pop
+    widget&.destroy
+  })
+app.command(:pack, rm_btn, pady: 5)
 
 app.mainloop