class

Tryst::UI::CanvasItem

Inherits Reference < Object

A handle onto one or more canvas items, addressed by Tk's own tagOrId - either the numeric id a create call returns (a single item) or an arbitrary tag string (every item currently carrying it, zero or more). Every method here is exactly that uniform - Tk's own canvas command already treats a tag and an id identically for move/coords/itemconfigure/delete/stacking/scale, so a shared tag is addressable as a group with no separate "group handle" type: get one via a shape-creation method (see Handle#line and friends, a single-item handle) or Handle#tagged (an existing tag, whatever it currently matches).

Not ported: #on_drag/#draggable - Handle's own on_drag is still deferred too (see handle.cr's own doc comment), and neither is exercised anywhere in this port's own scope (goldberg_engine.rb only ever uses #on_click/#on_right_click on a CanvasItem, and Handle#on_click/#on_right_click directly on the canvas itself for whole-canvas clicks). Add both back alongside Handle's own on_drag, together, if a future port genuinely needs them.

Constructors

new(app : AppContract, canvas_path : String, tag_or_id)
Source

Instance methods

[](opt : Symbol | String) : String

Read back a single item option - item[:fill].

Source
[]=(opt : Symbol | String, value : TclArgValue) : TclArgValue

Set a single item option - item[:fill] = "red". Shorthand for configure(opt => value) when there's only one to change.

Source
bbox
Source
bounds

[x1, y1, x2, y2] bounding box, or nil if nothing currently matches #tag_or_id.

Source
bring_to_front(above : CanvasItem | String | Symbol | Int32 | Nil = nil) : self

Bring to the front of the stacking order (drawn last, on top of everything), or - given above - just in front of that one item/tag instead of all the way to the front.

Source
configure

Mutate several item options at once, e.g. configure(fill: "red").

Source
coords
Source
coords=(new_coords) : Nil
Source
delete

Remove the item(s) from the canvas.

Source
exists?

Whether any item currently matches #tag_or_id - always true for a single-item handle from a creation method (the item exists until #delete'd), meaningful for a Handle#tagged group that may currently match zero items.

Source
lower(below : CanvasItem | String | Symbol | Int32 | Nil = nil) : self
Source
move(dx : Int32 | Float64, dy : Int32 | Float64) : self

Move relative to the current position.

Source
on_click

Fires on a left click, only when the click lands on this specific item/tag - other items on the same canvas are untouched. Wired immediately, via the canvas's own bind subcommand (Tk has no per-item widget path to bind a plain bind against) - unlike Handle, a CanvasItem only ever exists post-realize, so there's no queue-before-realize phase to worry about here.

Source
on_right_click

Fires on a right click, however the platform spells it (see MouseEvents::RIGHT_CLICK_EVENTS). Handle it yourself with a block, or use the overload below to pop up a menu instead.

Source
on_right_click(menu : Handle) : self

Pops menu up at the click's screen position. Raises ArgumentError unless menu is a :menu or :context_menu handle - a Handle's node type isn't part of its static type, so that one stays a runtime check.

Source
points

The current coordinate list.

Source
points=(new_coords) : Nil

Replace the coordinate list outright (as opposed to #move's relative shift). Flat or nested (e.g. [[x1, y1], [x2, y2]]) - flattened either way, same as a shape-creation method's own coords.

Source
scale(ox : Int32 | Float64, oy : Int32 | Float64, sx : Int32 | Float64, sy : Int32 | Float64) : self

Scale coordinates relative to a fixed point (ox, oy origin; sx, sy scale factors).

Source
send_to_back(below : CanvasItem | String | Symbol | Int32 | Nil = nil) : self

Send to the back of the stacking order (drawn first, under everything), or - given below - just behind that one item/tag instead of all the way to the back.

Source
tag_or_id
Source
tk_raise(above : CanvasItem | String | Symbol | Int32 | Nil = nil) : self

Tk's own name for #bring_to_front.

Source
virtual_path

The canvas's own path, marked past the point a real Tk path stops applying - an item/tag has no independent Tk path of its own, only the canvas does. ! is illegal in a Tk path segment, so handing this to a raw Tk command fails loudly (an "invalid command name" Tcl error) instead of silently misbehaving - the same marked-address shape MenuEntryAddressing#virtual_path uses for a menu entry, the other kind of thing with no Tk path of its own.

Source