Teek::UI::Session Class

add(parent_name)

Build and immediately realize a subtree into the already-running app, as a child of an already-realized widget named parent_name - for dynamic UIs (adding cards/rows/menu entries at runtime), not just the initial build. The block uses the exact same widget DSL as everywhere else (a.button(...), a.column(...) ``, …); new widgets show up immediately, routed through the same Teek::App#command/leak-cleanup path the initial realize uses, so destroying an added widget reclaims its callbacks the normal way.

Unlike the initial #realize, this does not run Validator - it’s already-known-good territory (the session realized once already); validating one small addition on every call would be wasted work.

Parameters

• parent_name Symbol — an already-realized widget's name

Returns nil

@raise NotRealizedError if the session, or the named parent, isn't realized yet

@raise ArgumentError if no widget is declared under parent_name

@yieldparam ui Session the same builder, block-scoped under parent_name

View source ▼

def add(parent_name)
  raise_unless_realized!

  parent_node = @document.find(parent_name) or
    raise ArgumentError, "no widget named :#{parent_name} in this build"
  raise NotRealizedError, "##{parent_name} is not realized yet" unless parent_node.realized

  before = parent_node.children.length
  vars_before = @vars.length
  images_before = @images.length
  push_stack(parent_node)
  @in_add = true
  begin
    yield self if block_given?
  ensure
    @in_add = false
    pop_stack
  end

  # A var/image declared inside this block needs to be real before
  # the new widget subtree realizes, exactly like the initial
  # #realize orders them - a widget referencing one via
  # bind:/image: assumes it's already backed by the time IT gets
  # created (see Var#realize/Image#realize).
  @vars[vars_before..].each { |v| v.realize(@app) }
  @images[images_before..].each { |img| img.realize(@app) }

  realizer = Realizer.new(@app, @document, default_scroll: @scroll)
  # A lazy: true child built in this block (see WidgetDSL#append_container)
  # stays unrealized here too, exactly like one built during the
  # initial realize - it's realized later, on demand (see Handle#realize!).
  parent_node.children[before..].each { |child| realizer.realize_subtree(child, parent_node) unless child.lazy? }

  nil
end

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

Returns Object, nil — see #every

View source ▼

def after(ms, on_error: :raise, &block)
  if @app
    @app.after(ms, on_error: on_error, &block)
  else
    @timers << Timer.new(kind: :after, ms: ms, on_error: on_error, block: block)
    nil
  end
end

app

Returns Teek::App — the underlying app - the DSL's escape hatch. Anything the DSL doesn't wrap yet is one call away: `ui.app.command(...)`.

@raise NotRealizedError if called before #realize

View source ▼

def app
  raise_unless_realized!
  @app
end

busy(window: '.', &block)

Show a busy cursor over window for the duration of the block - Teek::App#busy already restores it even if the block raises, nothing extra to do here for that.

Parameters

• window String — Tk window path

Returns — the block's return value

@raise NotRealizedError if called before #realize

@yield the work to perform while busy

View source ▼

def busy(window: '.', &block)
  raise_unless_realized!
  @app.busy(window: window, &block)
end

choose_color(initial: nil, title: nil, parent: nil)

Show the native color picker dialog.

@raise NotRealizedError if called before #realize

View source ▼

def choose_color(initial: nil, title: nil, parent: nil)
  raise_unless_realized!
  @app.choose_color(initial: initial, title: title, parent: parent)
end

choose_dir(initialdir: nil, mustexist: false, title: nil, parent: nil)

Show the native “choose directory” dialog.

@raise NotRealizedError if called before #realize

View source ▼

def choose_dir(initialdir: nil, mustexist: false, title: nil, parent: nil)
  raise_unless_realized!
  @app.choose_dir(initialdir: initialdir, mustexist: mustexist, title: title, parent: parent)
end

clipboard

Returns Teek::Clipboard — .set(text)/.get/.clear - text widgets don't need this at all for their own copy/cut/paste (Tk wires that to the platform's expected keys already); this is for reading/writing the clipboard directly from app code.

@raise NotRealizedError if called before #realize

View source ▼

def clipboard
  raise_unless_realized!
  @app.clipboard
end

debug_info

A live snapshot of currently-registered callbacks, grouped by what registered them - “is my app leaking callbacks, and where.” A tag absent from the result means nothing of that kind is currently registered (not a zero entry). Safe to call any time after realize; see run/run_async’s debug: for printing this automatically instead of calling it yourself.

Returns Hash{Symbol => Integer} — :event_bindings, :menu_entries, :canvas_item_binds, :tag_binds, :widget_option_callbacks (-command/-textvariable/etc.), :window_close_handlers

@raise NotRealizedError if called before #realize

View source ▼

def debug_info
  raise_unless_realized!
  counts = @app.callback_registry.counts_by_tag
  {
    event_bindings: counts[:bind],
    menu_entries: counts[:menu],
    canvas_item_binds: counts[:canvas_bind],
    tag_binds: counts[:tag_bind],
    widget_option_callbacks: counts[:widget_option],
    window_close_handlers: counts[:wm_protocol],
  }.reject { |_, count| count.zero? }
end

emit(event, *args, **kwargs)

Returns void

View source ▼

def emit(event, *args, **kwargs)
  @bus.emit(event, *args, **kwargs)
end

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

Same queue-then-wire shape as an on_* event binding: called inside the build block, it queues and registers once the tree realizes; called after, it registers immediately - same method, correct behavior either way, so a tick loop can be declared right alongside the UI it drives instead of being forced out to a separate post-run_async step.

Returns Object, nil — the live timer object (`.cancel`-able) once realized; `nil` if queued - there's no live timer to hand back yet, since nothing has registered with Tcl at that point

View source ▼

def every(ms, on_error: :raise, &block)
  if @app
    @app.every(ms, on_error: on_error, &block)
  else
    @timers << Timer.new(kind: :every, ms: ms, on_error: on_error, block: block)
    nil
  end
end

find_by_path(path)

Reverse lookup: given a real Tk path (from an error message, a winfo query, or poking around in a REPL), find which widget it belongs to - the counterpart to the name-based ui[:name]. See Document#find_by_path for exactly what counts as a match.

Parameters

• path String — e.g. ".toolbar.save"

Returns Handle, nil

@raise NotRealizedError if called before #realize

View source ▼

def find_by_path(path)
  raise_unless_realized!
  node = @document.find_by_path(path)
  node && Handle.new(node)
end

initialize(title: nil, scroll: nil, app_opts: {})

Returns Session — a new instance of Session

@api private

View source ▼

def initialize(title: nil, scroll: nil, app_opts: {})
  @title = title
  @scroll = scroll
  @app_opts = app_opts
  @document = Document.new
  @stack = [@document.root]
  @scope_stack = [Scope::TOP_LEVEL]
  @vars = []
  @images = []
  @app = nil
  @in_add = false
  @bus = EventBus.new
  @timers = []
  @toast_path = nil
  @toast_timer_id = nil
end

message(message:, title: nil, detail: nil, icon: :info, type: :ok, default: nil, parent: nil)

Show a message box with one or more buttons.

@raise NotRealizedError if called before #realize

View source ▼

def message(message:, title: nil, detail: nil, icon: :info, type: :ok, default: nil, parent: nil)
  raise_unless_realized!
  @app.message_box(message: message, title: title, detail: detail, icon: icon,
                    type: type, default: default, parent: parent)
end

off(event, block)

Returns void

View source ▼

def off(event, block)
  @bus.off(event, block)
end

on(event, &block)

Returns Proc — the block, to pass to a later #off

View source ▼

def on(event, &block)
  @bus.on(event, &block)
end

open_file(filetypes: nil, initialdir: nil, initialfile: nil, title: nil, multiple: false, parent: nil)

Show the native “choose file to open” dialog.

@raise NotRealizedError if called before #realize

View source ▼

def open_file(filetypes: nil, initialdir: nil, initialfile: nil, title: nil, multiple: false, parent: nil)
  raise_unless_realized!
  @app.choose_open_file(filetypes: filetypes, initialdir: initialdir, initialfile: initialfile,
                         title: title, multiple: multiple, parent: parent)
end

realize(strict: false)

Validate the build tree, then create the underlying Teek::App and realize the tree into it, if that hasn’t happened yet. Idempotent - calling it again after the first time just returns the same app.

Atomic in two senses: a validation failure means no interpreter is ever constructed at all, and even once realizing starts, the app’s root window stays withdrawn until the whole tree is realized, so a mid-realize error never leaves a half-built window visible either way. On failure the session is left exactly as if #realize had never been called - it isn’t left half-realized (or half-validated).

Parameters

• strict Boolean — see Validator.validate!

Returns Teek::App

@raise ValidationError if the build tree has problems

View source ▼

def realize(strict: false)
  return @app if @app

  Validator.validate!(@document, strict: strict)

  app = Teek::App.new(title: @title, **@app_opts)
  begin
    # vars/images realize first, so a widget bound/pointed to one
    # displays correctly (a value, a loaded image) from the moment
    # it's created instead of starting blank/broken.
    @vars.each { |v| v.realize(app) }
    @images.each { |img| img.realize(app) }
    Realizer.new(app, @document, default_scroll: @scroll).realize
    flush_timers!(app)
  rescue
    app.destroy
    raise
  end
  @app = app
end

run(strict: false, debug: false)

Realize, show the window, and enter the Tk event loop. Blocks until the app exits.

Parameters

• strict Boolean — see Validator.validate!
• debug Boolean — print #debug_info's summary to stderr, once right before entering the event loop and once after it returns - eyeball whether the app leaked any callbacks over its run without writing any diagnostic code yourself.

Returns void

View source ▼

def run(strict: false, debug: false)
  realize(strict: strict)
  @app.show
  print_debug_info if debug
  @app.mainloop
  print_debug_info if debug
end

run_async(strict: false, debug: false)

Realize and show the window without entering the event loop. Returns immediately - the caller is responsible for servicing the event loop from then on (e.g. its own timer/callback-driven flow).

Parameters

• strict Boolean — see Validator.validate!
• debug Boolean — print #debug_info's summary to stderr right after realize

Returns self

@note Not a substitute for #run in an interactive REPL (IRB/Pry): nothing services the event loop while the REPL blocks waiting for your next line, so the window beachballs between commands on macOS no matter how often you call `ui.app.update` by hand - see Teek::App#mainloop's own REPL warning. Driving a session interactively from IRB/Pry isn't a supported workflow.

View source ▼

def run_async(strict: false, debug: false)
  realize(strict: strict)
  @app.show
  print_debug_info if debug
  self
end

save_file(filetypes: nil, initialdir: nil, initialfile: nil, title: nil, defaultextension: nil, confirmoverwrite: true, parent: nil)

Show the native “choose file to save” dialog.

@raise NotRealizedError if called before #realize

View source ▼

def save_file(filetypes: nil, initialdir: nil, initialfile: nil, title: nil,
               defaultextension: nil, confirmoverwrite: true, parent: nil)
  raise_unless_realized!
  @app.choose_save_file(filetypes: filetypes, initialdir: initialdir, initialfile: initialfile, title: title,
                         defaultextension: defaultextension, confirmoverwrite: confirmoverwrite, parent: parent)
end

toast(message, duration: DEFAULT_TOAST_DURATION_MS)

Briefly flash a message near the bottom of the window - “Saved” after a save action, “Settings” when a modal gains focus, that kind of transient feedback, not a persistent status. Reuses one widget across every call rather than building a new one each time: calling this again while a toast is already showing replaces it (new text, restarted timer) instead of stacking a second one, and the earlier toast’s own pending auto-dismiss is cancelled so it can never fire late and hide the replacement.

Parameters

• message String
• duration Integer — milliseconds before it auto-dismisses

Returns void

@raise NotRealizedError if called before #realize

View source ▼

def toast(message, duration: DEFAULT_TOAST_DURATION_MS)
  raise_unless_realized!
  ensure_toast_widget
  @app.command(@toast_path, :configure, text: message)
  @app.command(:place, @toast_path, in: '.', relx: 0.5, rely: 1.0, anchor: 's', y: -12)
  @app.after_cancel(@toast_timer_id) if @toast_timer_id
  @toast_timer_id = @app.after(duration) { @app.command(:place, :forget, @toast_path) }
end