Teek::UI::Handle | Teek API Documentation

app

Returns Teek::App — the underlying app this widget was realized into

@raise NotRealizedError before realize

View source ▼

def app
  realized.app
end

arc(*coords, **opts)

An arc/pie-slice/chord along the oval inscribed in the bounding box [x1, y1, x2, y2]. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric>
opts Hash — item options, e.g. start:/extent:/style:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def arc(*coords, **opts)
  create_canvas_item(:arc, coords, opts)
end

bitmap(*coords, **opts)

A stipple bitmap anchored at [x, y]. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric> — a single [x, y] point
opts Hash — item options, e.g. bitmap:/foreground:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def bitmap(*coords, **opts)
  create_canvas_item(:bitmap, coords, opts)
end

Mutate the live widget’s (or, for a type with none of its own, e.g. a menu entry - the entry’s own) options - delegated entirely to this node type’s WidgetType#addressing strategy, so Handle itself carries no per-type knowledge of how to reach it.

Parameters

opts Hash — e.g. text: "Go"

@raise NotRealizedError before realize

View source ▼

def configure(**opts)
  @addressing.configure(**opts)
end

destroy!(defer: nil)

Tears down this node’s live widget (and everything under it), releasing its callbacks via teek’s existing <Destroy> cleanup, and resets it so a later push of a fresh mount rebuilds it from scratch. The rebuild gets a fresh Tk path, not necessarily this same one - path segments are claimed once and never recycled (see Document#claim_path_segment), so this stays safe even if another instance sharing this same local name is still alive elsewhere under the same parent. Typically called after popping a screen you don’t want to keep warm (see Screens) - popping alone only conceals, exactly as before; this is a separate, explicit step - ui.screens.pop&.destroy!/ui.modal.pop&.destroy!.

Destroying a widget SYNCHRONOUSLY from inside the click handler of one of its own descendants (a dialog’s own “Close” button tearing down the dialog it lives in) is a real Tk hazard: ttk::button (and others) queue their own internal bindings for that SAME click, which then run against a widget that’s already gone. defer absorbs this automatically - no need to know about it or reach for ui.after yourself.

Parameters

defer Boolean, nil — nil (the default) auto-detects: defers to the next Tk idle point (Teek.in_callback? true - the hazard above) so the current click finishes first, or destroys synchronously otherwise (a script/test with no event loop running has nothing to defer TO, and wants "gone when this call returns" semantics). Pass explicitly to override either way. Calling this again on the same handle while its own deferred destroy hasn't run yet is a safe no-op. The one residual to know about: when this DOES defer, it returns before the widget is actually gone - the node still reports realized and its old Tk path still exists until the deferred teardown runs. Don't destroy! then immediately rebuild a fresh mount at that SAME name/path in the same handler expecting the old one to already be gone; either pass defer: false to force it synchronous first, or build the replacement under a genuinely distinct mount (the normal "fresh `lazy: true` component per open" pattern already does this, since Document#claim_path_segment never reuses a path segment anyway).

Returns nil

@raise NotRealizedError if this node was never realized

View source ▼

def destroy!(defer: nil)
  return nil if @node.pending_destroy?

  should_defer = defer.nil? ? Teek.in_callback? : defer
  if should_defer
    app = realized.app
    @node.pending_destroy = true
    app.after_idle { perform_destroy! }
  else
    perform_destroy!
  end
  nil
end

disable

Shorthand for configure(state: :disabled) - greyed out, not interactive/invocable.

Returns self

@raise NotRealizedError before realize

View source ▼

def disable
  configure(state: :disabled)
  self
end

ellipse(*coords, **opts)

An ellipse inscribed in the bounding box [x1, y1, x2, y2]. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric>
opts Hash — item options, e.g. fill:/outline:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def ellipse(*coords, **opts)
  create_canvas_item(:oval, coords, opts)
end

enable

Shorthand for configure(state: :normal) - Tk’s own default state, meaningful for anything with a -state option (a menu entry, a ttk widget, …).

Returns self

@raise NotRealizedError before realize

View source ▼

def enable
  configure(state: :normal)
  self
end

events

Every event binding declared on this node so far, in declaration order - on_click/on_key/on_drag/on_right_click and friends all funnel through here. Meaningful at any phase: before realize these are still queued (nothing wired to Tcl yet), after realize they’re the bindings actually in effect - covers both a binding declared in the original build block and one added later (e.g. from inside Session#add), so this stays a true live picture, not just a record of what was queued pre-realize. Each entry’s own handler is the real Proc that runs, so .source_location answers “what code does this” directly.

Returns Array<EventBinding>

View source ▼

def events
  @node.events
end

hide

Hide the window: releases any grab #show set (a no-op if it wasn’t modal - Teek::Window#grab_release is always safe to call) and withdraws it. Only valid on a ui.window handle.

Returns self

@raise ArgumentError if this handle isn't a window

@raise NotRealizedError before realize

View source ▼

def hide
  unless type == :window
    raise ArgumentError, "hide only makes sense on a window (got a :#{type})"
  end

  grab_release
  window.withdraw
  self
end

initialize(node)

Returns Handle — a new instance of Handle

@api private

View source ▼

def initialize(node)
  @node = node
  @addressing = (WidgetTypes.for_type(node.type)&.addressing || WidgetAddressing).new(node)
end

line(*coords, **opts)

A straight line through the given points - [x1, y1, x2, y2, ...], flat or nested, two or more points. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric>
opts Hash — item options, e.g. fill:/width:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def line(*coords, **opts)
  create_canvas_item(:line, coords, opts)
end

modal(global: false, &block)

Show the window modally: grabs input and sets focus on it immediately. Release it explicitly with #grab_release (typically from the window’s own dismiss/close handling) when the dialog is done - not released automatically just because this method returns, since a modal dialog stays grabbed for its whole visible lifetime, not just its setup. Released immediately if the optional setup block itself raises, or if the window is destroyed while still grabbed - see Teek::Window#modal, which this delegates to entirely (no grab/focus/destroy-safety-net logic lives here). Only valid on a ui.window handle.

Parameters

global Boolean — see Teek::Window#grab_set

Returns void

@raise ArgumentError if this handle isn't a window

@raise NotRealizedError before realize

@yield optional - runs with the grab and focus already set

View source ▼

def modal(global: false, &block)
  unless type == :window
    raise ArgumentError, "modal only makes sense on a window (got a :#{type})"
  end

  window.modal(global: global, &block)
end

name

Returns Symbol, nil — the node's explicit name

View source ▼

def name
  @node.name
end

on_click(&block)

Fires on a left click.

Returns self

@yield called with no arguments

View source ▼

def on_click(&block)
  bind_event('<Button-1>', block)
  self
end

on_close(&block)

Fires when the window’s close button (titlebar close box, Cmd-W, Alt-F4, …) is pressed. Teek’s own default (destroy the window) only applies when nothing else has claimed it - the block decides whether the window actually closes; call .destroy yourself if you want that. Only valid on a ui.window handle.

Returns self

@raise ArgumentError if this handle isn't a window

@yield called with no arguments

View source ▼

def on_close(&block)
  unless type == :window
    raise ArgumentError, "on_close only makes sense on a window (got a :#{type})"
  end

  if @node.realized
    @node.realized.app.on_close(window: @node.realized.path, &block)
  else
    @node.opts[:on_close] = block
  end
  self
end

on_drag(&block)

Fires while dragging (left button held down and moving). Delivers Integer x/y, converted through the widget’s own canvasx/canvasy when bound to a canvas so callers never have to remember to do that themselves.

Returns self

@yield x, y Integer coordinates

View source ▼

def on_drag(&block)
  drag_type = type
  wrapped = lambda do |raw_x, raw_y|
    block.call(*convert_drag_coords(drag_type, raw_x, raw_y))
  end
  bind_event('<B1-Motion>', wrapped, subs: %i[x y])
  self
end

on_key(spec, &block)

Fires on a key press. spec is either a friendly Symbol (:enter, :escape, :up, …) or a “Modifier-Modifier-Key” String ("Ctrl-s", "Ctrl-Shift-s") - see Keysyms.

Parameters

spec Symbol, String

Returns self

@yield called with no arguments

View source ▼

def on_key(spec, &block)
  modifiers, keysym = Keysyms.resolve(spec)
  Keysyms.patterns_for(modifiers, keysym).each { |event| bind_event(event, block) }
  self
end

on_right_click(menu nil, &block)

Fires on a right click, however the platform spells it (Button-3 on Linux/Windows, Button-2 or Control-Button-1 on macOS). Either handle it yourself with a block, or hand it a :menu/:context_menu handle to pop up at the click’s screen position - not both.

Parameters

menu Handle, nil — a `:menu` or `:context_menu` handle to tk_popup

Returns self

@raise ArgumentError if given neither or both, or menu isn't a menu handle

@yield called with no arguments (only when menu isn't given)

View source ▼

def on_right_click(menu = nil, &block)
  if menu && block
    raise ArgumentError, "on_right_click takes either a menu handle or a block, not both"
  elsif menu
    unless MENU_HANDLE_TYPES.include?(menu.type)
      raise ArgumentError, "on_right_click(menu) needs a :menu or :context_menu handle (got a :#{menu.type})"
    end

    popup = lambda do |root_x, root_y|
      realized.app.popup_menu(menu.path, x: root_x, y: root_y)
    end
    RIGHT_CLICK_EVENTS.each { |event| bind_event(event, popup, subs: %i[root_x root_y]) }
  elsif block
    RIGHT_CLICK_EVENTS.each { |event| bind_event(event, block) }
  else
    raise ArgumentError, "on_right_click needs either a menu handle or a block"
  end
  self
end

on_tab_changed(&block)

Fires when the selected tab changes (Tk’s «NotebookTabChanged»). The block receives the newly selected tab’s own name (the Symbol given via t.tab(label, name)) if it has one, otherwise its plain zero-based index - preferring a name over a raw Tk index, same as ui[:name] lookup does everywhere else in the DSL. Only valid on a ui.tabs handle.

Returns self

@raise ArgumentError if this handle isn't a tabs container

@yield name_or_index Symbol or Integer

View source ▼

def on_tab_changed(&block)
  unless type == :tabs
    raise ArgumentError, "on_tab_changed only makes sense on a tabs container (got a :#{type})"
  end

  wrapped = lambda {
    index = realized.app.command(realized.path, :index, :current).to_i
    tab_node = @node.children[index]
    block.call(tab_node&.name || index)
  }
  bind_event('<<NotebookTabChanged>>', wrapped)
  self
end

options

What Tk currently thinks this widget’s (or, for a type with none of its own, e.g. a menu entry - the entry’s own) options are right now, straight from a bare configure - for when a prior #configure call seems like it silently didn’t take, or just exploring what’s actually set on a live widget. Delegated to this node type’s WidgetType#addressing strategy, same as #configure.

Returns Hash{Symbol => String} — option name (no leading -) => current value

@raise NotRealizedError before realize

View source ▼

def options
  @addressing.option_dump
end

path

Returns String — this node's live address - the real Tk widget path for an ordinary widget, or (for a type with none of its own, e.g. a menu entry) its WidgetType#addressing strategy's own marked, Tk-path-shaped virtual path - see MenuEntryAddressing#virtual_path

@raise NotRealizedError before realize

View source ▼

def path
  @addressing.virtual_path
end

polygon(*coords, **opts)

A closed shape through the given points - [x1, y1, x2, y2, ...], flat or nested, three or more points. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric>
opts Hash — item options, e.g. fill:/smooth:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def polygon(*coords, **opts)
  create_canvas_item(:polygon, coords, opts)
end

rectangle(*coords, **opts)

A rectangle with corners [x1, y1, x2, y2]. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric>
opts Hash — item options, e.g. fill:/outline:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def rectangle(*coords, **opts)
  create_canvas_item(:rectangle, coords, opts)
end

release_focus

Release a grab previously set with #modal - “grab” is X11/Tk jargon for capturing all input to one window, which is what a modal dialog is doing while it’s up. Only valid on a ui.window handle. See Teek::Window#grab_release.

Returns void

@raise ArgumentError if this handle isn't a window

@raise NotRealizedError before realize

View source ▼

def release_focus
  unless type == :window
    raise ArgumentError, "release_focus only makes sense on a window (got a :#{type})"
  end

  window.grab_release
end

show

Reveal the window: positions it just to the right of the parent it’s nested under (root, or another window if this one’s nested inside it), deiconifies, raises it to the front, and - only if this window was declared modal: true - grabs input and focuses it too (via #modal). Only valid on a ui.window handle.

Returns self

@raise ArgumentError if this handle isn't a window

@raise NotRealizedError before realize

View source ▼

def show
  unless type == :window
    raise ArgumentError, "show only makes sense on a window (got a :#{type})"
  end

  position_near_parent
  window.deiconify
  realized.app.command(:raise, realized.path)
  modal if @node.opts[:modal]
  self
end

tagged(tag)

A handle onto whatever items currently carry tag - zero, one, or many (see CanvasItem, which addresses a tag and an id identically). Doesn’t create anything; a shape-creation method (e.g. #line) already returns a single-item handle for its own new item, this is for addressing a shared tags: group (or reaching an item by an id you already have) after the fact. Only valid on a ui.canvas handle.

Parameters

tag String, Symbol, Integer

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def tagged(tag)
  raise_unless_canvas!('tagged')
  CanvasItem.new(realized.app, realized.path, tag)
end

text(*coords, **opts)

Text anchored at [x, y]. Only valid on a ui.canvas handle.

Parameters

coords Array<Numeric> — a single [x, y] point
opts Hash — item options, e.g. text:/fill:/font:/anchor:/tags:

Returns CanvasItem

@raise ArgumentError if this handle isn't a canvas

@raise NotRealizedError before realize

View source ▼

def text(*coords, **opts)
  create_canvas_item(:text, coords, opts)
end

text_content

The rich text API for this widget’s content - insert/get/delete, named formats (Tk’s own “tag” concept), markers, search, and embedded images. See TextContent for the full surface. Only valid on a ui.text_area handle.

Returns TextContent

@raise ArgumentError if this handle isn't a text_area

@raise NotRealizedError before realize

View source ▼

def text_content
  raise_unless_text_area!('text_content')
  TextContent.new(realized.app, realized.path)
end

type

Returns Symbol — the node's type, e.g. :button

View source ▼

def type
  @node.type
end

Teek API Documentation

Teek::UI::Handle Class

Instance Methods ↑

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters