Teek API Documentation

Teek::App Class

Inherits: Object

Instance Methods ↑

add_debug_console(keybinding '<F12>')

Enable the Tk debug console. The console starts hidden and can be toggled with the given keyboard shortcut (default: F12).

The Tk console is a built-in interactive Tcl shell — useful for inspecting variables, running Tcl commands, and debugging widget layouts at runtime. It is available on macOS and Windows only; on Linux this method is a no-op (Linux has the real terminal).

Parameters
  • keybinding String — Tk event to toggle the console (default: "")

Returns Boolean — true if the console was created, false if unavailable on this platform

Example
app = Teek::App.new
app.add_debug_console            # F12 toggles console
app.add_debug_console("<F11>")   # custom key
console |
View source ▼ 
def add_debug_console(keybinding = '<F12>')
  @interp.create_console
  @_console_visible = false

  toggle = proc do |*|
    if @_console_visible
      tcl_eval('console hide')
      @_console_visible = false
    else
      tcl_eval('console show')
      @_console_visible = true
    end
  end

  command(:bind, '.', keybinding, toggle)
  true
rescue TclError => e
  warn "Teek: debug console not available on this platform (#{e.message})"
  false
end
GitHub

add_package_path(path)

Add a directory to Tcl’s package search path.

Parameters
  • path String — directory containing Tcl packages

Returns void

View source ▼ 
def add_package_path(path)
  tcl_eval("lappend ::auto_path {#{path}}")
end
GitHub

after(ms, on_error: :raise, &block)

Schedule a one-shot timer. Calls the block after ms milliseconds.

Parameters
  • ms Integer — delay in milliseconds
  • on_error :raise, Proc, nil — error handling strategy: - :raise (default) — exception propagates to Tcl background error handler. - Proc — called with the exception; error is swallowed. - nil — error is silently swallowed.

Returns String — timer ID, pass to #after_cancel to cancel

@yield block to call when the timer fires

after ms |
View source ▼ 
def after(ms, on_error: :raise, &block)
  cb_id = nil
  cb_id = @interp.register_callback(proc { |*|
    begin
      block.call
    rescue => e
      raise if on_error == :raise
      on_error.call(e) if on_error.is_a?(Proc)
    ensure
      @interp.unregister_callback(cb_id)
    end
  })
  after_id = @interp.tcl_eval("after #{ms.to_i} {ruby_callback #{cb_id}}")
  after_id.instance_variable_set(:@cb_id, cb_id)
  after_id
end
GitHub

after_cancel(after_id)

Cancel a pending #after or #after_idle timer.

Parameters

Returns void

after cancel |
View source ▼ 
def after_cancel(after_id)
  @interp.tcl_eval("after cancel #{after_id}")
  if (cb_id = after_id.instance_variable_get(:@cb_id))
    @interp.unregister_callback(cb_id)
    after_id.instance_variable_set(:@cb_id, nil)
  end
  after_id
end
GitHub

after_idle(&block)

Schedule a block to run once when the event loop is idle.

Returns String — timer ID, pass to #after_cancel to cancel

@yield block to call when the event loop is idle

after idle |
View source ▼ 
def after_idle(&block)
  cb_id = nil
  cb_id = @interp.register_callback(proc { |*|
    block.call
    @interp.unregister_callback(cb_id)
  })
  after_id = @interp.tcl_eval("after idle {ruby_callback #{cb_id}}")
  after_id.instance_variable_set(:@cb_id, cb_id)
  after_id
end
GitHub

appearance

Get the macOS window appearance. No-op (returns nil) on non-macOS.

Returns String, nil — "aqua", "darkaqua", "auto", or nil on non-macOS

Example
app.appearance          # => "aqua", "darkaqua", or "auto"
app.appearance = :light # force light mode
app.appearance = :dark  # force dark mode
app.appearance = :auto  # follow system setting
See also
View source ▼ 
def appearance
  return nil unless aqua?
  if tk_major >= 9
    @interp.tcl_eval('wm attributes . -appearance').delete('"')
  else
    @interp.tcl_eval('tk::unsupported::MacWindowStyle appearance .')
  end
end
GitHub

appearance=(mode)

Set the macOS window appearance. No-op on non-macOS.

Parameters
  • mode Symbol, String — :light, :dark, :auto, or a raw Tk value

Returns void

View source ▼ 
def appearance=(mode)
  return unless aqua?
  value = case mode.to_sym
          when :light then 'aqua'
          when :dark  then 'darkaqua'
          when :auto  then 'auto'
          else mode.to_s
          end
  if tk_major >= 9
    @interp.tcl_eval("wm attributes . -appearance #{value}")
  else
    @interp.tcl_eval("tk::unsupported::MacWindowStyle appearance . #{value}")
  end
end
GitHub

bind(widget, event, *subs, &block)

View source ▼ 
def bind(widget, event, *subs, &block)
  event_str = event.start_with?('<') ? event : "<#{event}>"
  cb = register_callback(proc { |*args| block.call(*args) })
  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}}")
end
GitHub

bool_to_tcl(val)

Convert a Ruby boolean to a Tcl boolean string (“1” or “0”).

Parameters
  • val Boolean

Returns String — "1" or "0"

View source ▼ 
def bool_to_tcl(val)
  Teek.bool_to_tcl(val)
end
GitHub

busy(window: '.')

Show a busy cursor on a window while executing a block. The cursor is restored even if the block raises.

Parameters
  • window String — Tk window path

Returns — the block's return value

@yield the work to perform while busy

tk busy |
View source ▼ 
def busy(window: '.')
  tcl_eval("tk busy hold #{window}")
  tcl_eval('update idletasks')
  yield
ensure
  tcl_eval("tk busy forget #{window}")
end
GitHub

command(cmd, *args, **kwargs)

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.

Parameters
  • cmd Symbol, String — the Tcl command name
  • args — positional arguments
  • kwargs — keyword arguments mapped to -key value pairs

Returns String — the Tcl result

Example
app.command(:pack, '.btn', side: :left, padx: 10)
# evaluates: pack .btn -side left -padx {10}
View source ▼ 
def command(cmd, *args, **kwargs)
  parts = [cmd.to_s]
  i = 0
  while i < args.length
    arg = args[i]
    if arg.is_a?(Proc)
      id = @interp.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
    else
      parts << tcl_value(arg)
    end
    i += 1
  end
  kwargs.each do |key, value|
    parts << "-#{key}"
    parts << tcl_value(value)
  end
  @interp.tcl_eval(parts.join(' '))
end
GitHub

create_widget(type, path nil, parent: nil, **kwargs)

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.

Parameters
  • type String, Symbol — Tk widget command (e.g. 'ttk::button', :canvas)
  • path String, nil — explicit Tk path, or nil for auto-naming
  • parent Widget, String, nil — parent widget for path nesting
  • kwargs — keyword arguments passed to the Tk widget command

Returns Widget — the created widget

Examples
# Auto-named
btn = app.create_widget('ttk::button', text: 'Click')
# btn.path => ".ttkbtn1"
# Explicit path
frm = app.create_widget('ttk::frame', '.myframe')
# Nested under a parent
frm = app.create_widget('ttk::frame')
btn = app.create_widget('ttk::button', parent: frm, text: 'Click')
# btn.path => ".ttkfrm1.ttkbtn1"
View source ▼ 
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
GitHub

dark?

Returns true if the window is currently displayed in dark mode. Always returns false on non-macOS.

Returns Boolean

View source ▼ 
def dark?
  return false unless aqua?
  @interp.tcl_eval('tk::unsupported::MacWindowStyle isdark .').delete('"') == '1'
end
GitHub

destroy(widget '.')

Destroy a widget and all its children.

Parameters
  • widget String — Tk widget path (e.g. ".frame1")

Returns void

@raise ArgumentError

destroy |
View source ▼ 
def destroy(widget = '.')
  raise ArgumentError, 'widget path cannot be nil' if widget.nil?
  tcl_eval("destroy #{widget}")
end
GitHub

every(ms, on_error: :raise, &block)

Schedule a repeating timer. Calls the block every ms milliseconds until cancelled. The block runs on the main thread in the event loop, so it must be fast (don’t block the UI).

Parameters
  • ms Integer — interval in milliseconds
  • on_error :raise, Proc, nil — error handling strategy: - :raise (default) — cancels the timer and raises the exception from the next call to #update. - Proc — called with the exception; timer keeps running. - nil — cancels the timer silently; error stored in RepeatingTimer#last_error.

Returns RepeatingTimer — cancel handle

@yield block to call on each tick

Examples
# Basic polling loop
timer = app.every(50) { update_display }
timer.cancel  # stop later
# With error handler (timer keeps running)
timer = app.every(100, on_error: ->(e) { log(e) }) { risky_work }
# Silent cancel on error
timer = app.every(50, on_error: nil) { maybe_fails }
timer.last_error  # => check later
View source ▼ 
def every(ms, on_error: :raise, &block)
  RepeatingTimer.new(self, ms, on_error: on_error, &block)
end
GitHub

font_metrics(font)

Get font metrics (ascent, descent, linespace) for a given font. Uses Tk’s C font API directly.

Parameters
  • font String — font description (e.g. "Helvetica 12", "TkDefaultFont")

Returns Hash{Symbol => Integer} — :ascent, :descent, :linespace

@raise Teek::TclError if the font is not found

Tk_GetFontMetrics |
View source ▼ 
def font_metrics(font)
  @interp.font_metrics(font)
end
GitHub

get_variable(name)

Get a Tcl variable’s value.

Parameters
  • name String — variable name

Returns String — the value

@raise Teek::TclError if the variable doesn't exist

set |
View source ▼ 
def get_variable(name)
  tcl_eval("set #{name}")
end
GitHub

hide(window '.')

Hide a window without destroying it. Defaults to the root window (“.”).

Parameters
  • window String — Tk window path

Returns void

wm withdraw |
View source ▼ 
def hide(window = '.')
  @interp.tcl_eval("wm withdraw #{window}")
end
GitHub

initialize(title: nil, track_widgets: true, debug: false, &block)

Returns App — a new instance of App

View source ▼ 
def initialize(title: nil, track_widgets: true, debug: false, &block)
  @interp = Teek::Interp.new
  @interp.tcl_eval('package require Tk')
  hide
  @widgets = {}
  @widget_counters = Hash.new(0)
  @_pending_exception = nil
  debug ||= !!ENV['TEEK_DEBUG']
  track_widgets = true if debug
  setup_widget_tracking if track_widgets
  if debug
    require_relative 'teek/debugger'
    @debugger = Teek::Debugger.new(self)
  end
  set_window_title(title) if title
  instance_eval(&block) if block
end
GitHub

mainloop

Enter the Tk event loop. Blocks until the application exits.

Returns void

Tk_MainLoop |
View source ▼ 
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" \
         "  Instead, use app.update in a loop or call app.update manually between commands:\n" \
         "    app.show\n" \
         "    app.update          # process pending events\n" \
         "    # ... interact with your app ...\n" \
         "    app.update          # process again after changes"
  end
  @interp.mainloop
end
GitHub

make_list(*args)

Build a properly-escaped Tcl list from Ruby strings.

Parameters
  • args Array<String> — elements to join

Returns String — a Tcl-formatted list

View source ▼ 
def make_list(*args)
  Teek.make_list(*args)
end
GitHub

measure_chars(font, text, max_pixels, **opts)

Measure how many bytes of text fit within a pixel width limit. Useful for text truncation, ellipsis, and line wrapping.

Parameters
  • font String — font description (e.g. "Helvetica 12")
  • text String — text to measure
  • max_pixels Integer — maximum pixel width (-1 for unlimited)
  • opts Hash — options

Returns Hash{Symbol => Integer} — :bytes and :width

Options
  • :partial_ok Boolean — allow partial character at boundary
  • :whole_words Boolean — break only at word boundaries
  • :at_least_one Boolean — always return at least one character

@raise Teek::TclError if the font is not found

Tk_MeasureChars |
View source ▼ 
def measure_chars(font, text, max_pixels, **opts)
  @interp.measure_chars(font, text, max_pixels, opts)
end
GitHub

package_names

List all packages known to this interpreter. Scans auto_path for package indexes before querying.

Returns Array<String>

package names |
View source ▼ 
def package_names
  scan_packages
  split_list(tcl_eval('package names'))
end
GitHub

package_present?(name)

Check if a package is already loaded in this interpreter.

Parameters
  • name String — package name

Returns Boolean

package present |
View source ▼ 
def package_present?(name)
  tcl_eval("package present #{name}")
  true
rescue Teek::TclError
  false
end
GitHub

package_versions(name)

List available versions of a package. Scans auto_path for package indexes before querying.

Parameters
  • name String — package name

Returns Array<String>

package versions |
View source ▼ 
def package_versions(name)
  scan_packages
  split_list(tcl_eval("package versions #{name}"))
end
GitHub

register_callback(callable)

Register a Ruby callable as a Tcl callback. The callable can use throw for Tcl control flow: throw :teek_break - stop event propagation (like Tcl “break”) throw :teek_continue - Tcl TCL_CONTINUE throw :teek_return - Tcl TCL_RETURN

Parameters
  • callable #call — a Proc or lambda to invoke from Tcl

Returns Integer — callback ID, usable as ruby_callback <id> in Tcl

See also
View source ▼ 
def register_callback(callable)
  wrapped = proc { |*args|
    caught = nil
    catch(:teek_break) do
      catch(:teek_continue) do
        catch(:teek_return) do
          callable.call(*args)
          caught = :_none
        end
        caught ||= :return
      end
      caught ||= :continue
    end
    caught ||= :break
    caught == :_none ? nil : caught
  }
  @interp.register_callback(wrapped)
end
GitHub

require_package(name, version nil)

Load a Tcl package into this interpreter.

Parameters
  • name String — package name (e.g. "BWidget")
  • version String, nil — minimum version constraint

Returns String — the version that was loaded

@raise Teek::TclError if the package is not found

package require |
View source ▼ 
def require_package(name, version = nil)
  cmd = version ? "package require #{name} #{version}" : "package require #{name}"
  tcl_eval(cmd)
rescue Teek::TclError => e
  raise Teek::TclError, "Package '#{name}' not found. Ensure it is installed and on Tcl's auto_path. (#{e.message})"
end
GitHub

set_variable(name, value)

Set a Tcl variable. Useful for widget textvariable and variable options.

Parameters
  • name String — variable name
  • value String — value to set

Returns String — the value

set |
View source ▼ 
def set_variable(name, value)
  tcl_eval("set #{name} {#{value}}")
end
GitHub

set_window_geometry(geometry, window: '.')

Set a window’s geometry (e.g. “400x300”, “400x30010050”).

Parameters
  • geometry String — geometry string
  • window String — Tk window path

Returns String — the geometry

wm geometry |
View source ▼ 
def set_window_geometry(geometry, window: '.')
  tcl_eval("wm geometry #{window} #{geometry}")
end
GitHub

set_window_resizable(width, height, window: '.')

Set whether a window is resizable.

Parameters
  • width Boolean — allow horizontal resize
  • height Boolean — allow vertical resize
  • window String — Tk window path

Returns void

wm resizable |
View source ▼ 
def set_window_resizable(width, height, window: '.')
  tcl_eval("wm resizable #{window} #{width ? 1 : 0} #{height ? 1 : 0}")
end
GitHub

set_window_title(title, window: '.')

Set a window’s title.

Parameters
  • title String — new title
  • window String — Tk window path

Returns String — the title

wm title |
View source ▼ 
def set_window_title(title, window: '.')
  tcl_eval("wm title #{window} {#{title}}")
end
GitHub

show(window '.')

Show a window. Defaults to the root window (“.”).

Parameters
  • window String — Tk window path

Returns void

wm deiconify |
View source ▼ 
def show(window = '.')
  @interp.tcl_eval("wm deiconify #{window}")
end
GitHub

split_list(str)

Split a Tcl list string into a Ruby array of strings.

Parameters
  • str String — a Tcl-formatted list

Returns Array<String>

View source ▼ 
def split_list(str)
  Teek.split_list(str)
end
GitHub

tcl_eval(script)

Evaluate a raw Tcl script string and return the result. 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.

Parameters
  • script String — Tcl code to evaluate

Returns String — the Tcl result

View source ▼ 
def tcl_eval(script)
  @interp.tcl_eval(script)
end
GitHub

tcl_invoke(*args)

Invoke a Tcl command with pre-split arguments (no Tcl parsing). Safer than #tcl_eval when arguments may contain special characters.

Parameters
  • args Array<String> — command name followed by arguments

Returns String — the Tcl result

View source ▼ 
def tcl_invoke(*args)
  @interp.tcl_invoke(*args)
end
GitHub

tcl_to_bool(str)

Convert a Tcl boolean string (“0”, “1”, “yes”, “no”, etc.) to Ruby boolean.

Parameters
  • str String — a Tcl boolean value

Returns Boolean

View source ▼ 
def tcl_to_bool(str)
  Teek.tcl_to_bool(str)
end
GitHub

text_width(font, text)

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.

Parameters
  • font String — font description (e.g. "Helvetica 12", "TkDefaultFont")
  • text String — text to measure

Returns Integer — pixel width

@raise Teek::TclError if the font is not found

Tk_TextWidth |
View source ▼ 
def text_width(font, text)
  @interp.text_width(font, text)
end
GitHub

unbind(widget, event)

Remove an event binding previously set with #bind.

Parameters
  • widget String — Tk widget path or class tag
  • event String — Tk event name, with or without angle brackets

Returns void

See also
bind |
View source ▼ 
def unbind(widget, event)
  event_str = event.start_with?('<') ? event : "<#{event}>"
  @interp.tcl_eval("bind #{widget} #{event_str} {}")
end
GitHub

unregister_callback(id)

Remove a previously registered callback by its ID.

Parameters

Returns void

View source ▼ 
def unregister_callback(id)
  @interp.unregister_callback(id)
end
GitHub

update

Process all pending events and idle callbacks, then return.

Returns void

update |
View source ▼ 
def update
  @interp.tcl_eval('update')
  if (e = @_pending_exception)
    @_pending_exception = nil
    raise e
  end
end
GitHub

update_idletasks

Process only pending idle callbacks (e.g. geometry redraws), then return.

Returns void

update idletasks |
View source ▼ 
def update_idletasks
  @interp.tcl_eval('update idletasks')
end
GitHub

window_geometry(window: '.')

Get a window’s current geometry.

Parameters
  • window String — Tk window path

Returns String — geometry string (e.g. "400x30000")

wm geometry |
View source ▼ 
def window_geometry(window: '.')
  tcl_eval("wm geometry #{window}")
end
GitHub

window_resizable(window: '.')

Get whether a window is resizable.

Parameters
  • window String — Tk window path

Returns Array(Boolean, Boolean) — [width_resizable, height_resizable]

wm resizable |
View source ▼ 
def window_resizable(window: '.')
  parts = tcl_eval("wm resizable #{window}").split
  [parts[0] == '1', parts[1] == '1']
end
GitHub

window_title(window: '.')

Get a window’s current title.

Parameters
  • window String — Tk window path

Returns String — current title

wm title |
View source ▼ 
def window_title(window: '.')
  tcl_eval("wm title #{window}")
end
GitHub
Attributes ↑

_pending_exception= [W]

@api private

debugger [R]

Returns the value of attribute debugger.

interp [R]

Returns the value of attribute interp.

widgets [R]

Returns the value of attribute widgets.