Teek::App | Teek API Documentation

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

after(ms, &block)

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

Parameters

ms Integer — delay in milliseconds

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, &block)
  cb_id = nil
  cb_id = @interp.register_callback(proc { |*|
    block.call
    @interp.unregister_callback(cb_id)
  })
  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

after_cancel(after_id)

Cancel a pending #after or #after_idle timer.

Parameters

after_id String — timer ID returned by #after or #after_idle

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

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

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

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

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

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

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

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]
  args.each do |arg|
    parts << tcl_value(arg)
  end
  kwargs.each do |key, value|
    parts << "-#{key}"
    parts << tcl_value(value)
  end
  @interp.tcl_eval(parts.join(' '))
end

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

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

destroy(widget)

Destroy a widget and all its children.

Parameters

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

Returns void

destroy

View source ▼

def destroy(widget)
  tcl_eval("destroy #{widget}")
end

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

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

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

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

Returns App — a new instance of App

View source ▼

def initialize(track_widgets: true, debug: false, &block)
  @interp = Teek::Interp.new
  @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
  if debug
    require_relative 'teek/debugger'
    @debugger = Teek::Debugger.new(self)
  end
  instance_eval(&block) if block
end

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

unregister_callback(id)

Remove a previously registered callback by its ID.

Parameters

id Integer — callback ID returned by #register_callback

Returns void

View source ▼

def unregister_callback(id)
  @interp.unregister_callback(id)
end

update

Process all pending events and idle callbacks, then return.

Returns void

update

View source ▼

def update
  @interp.tcl_eval('update')
end

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

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

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

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

debugger [R]

Returns the value of attribute debugger.

interp [R]

Returns the value of attribute interp.

widgets [R]

Returns the value of attribute widgets.

Teek API Documentation

Teek::App Class

Instance Methods ↑

Parameters

Parameters

Parameters

Example

See also

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Examples

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Options

Parameters

Parameters

Parameters

See also

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

See also

Parameters

Parameters

Parameters

Parameters

Attributes ↑

debugger [R]

interp [R]

widgets [R]