Teek::UI::CanvasItem Class

[](opt)

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

Parameters

• opt Symbol, String — e.g. :fill

Returns String

View source ▼

def [](opt)
  @app.command(@canvas_path, :itemcget, @tag_or_id, "-#{opt}")
end

[]=(opt, value)

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

Parameters

• opt Symbol, String — e.g. :fill
• value Object

Returns Object — value

View source ▼

def []=(opt, value)
  configure(opt => value)
  value
end

bounds

Returns Array<Float>, nil — [x1, y1, x2, y2] bounding box, or nil if nothing currently matches #tag_or_id

View source ▼

def bounds
  result = @app.command(@canvas_path, :bbox, @tag_or_id)
  result.empty? ? nil : @app.split_list(result).map(&:to_f)
end

bring_to_front(above nil)

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.

Parameters

• above CanvasItem, String, nil

Returns self

View source ▼

def bring_to_front(above = nil)
  args = above ? [resolve(above)] : []
  @app.command(@canvas_path, :raise, @tag_or_id, *args)
  self
end

configure(**opts)

Mutate several item options at once.

Parameters

• opts Hash — item options, e.g. fill: 'red'

Returns self

View source ▼

def configure(**opts)
  @app.command(@canvas_path, :itemconfigure, @tag_or_id, **opts)
  self
end

delete

Remove the item(s) from the canvas.

Returns nil

View source ▼

def delete
  @app.command(@canvas_path, :delete, @tag_or_id)
  nil
end

draggable(&block)

Makes this item movable by mouse drag, with zero coordinate math of your own - press and drag it around the canvas, it follows the pointer. Binds <Button-1> (to capture the starting position) and <B1-Motion> (to shift #move by the delta each tick) on this item/tag, replacing any #on_click/#on_drag binding already set on it, the same way any two binds on the same item/event replace each other in Tk.

Returns self

@yield x, y optional - the item's new pointer-relative position (same Integer canvasx/canvasy coordinates #on_drag delivers) after each move, e.g. to react to where it's been dragged to

View source ▼

def draggable(&block)
  last = nil

  press = lambda do |raw_x, raw_y|
    last = canvas_xy(raw_x, raw_y)
  end
  bind_item_event('<Button-1>', press, subs: %i[x y])

  drag = lambda do |raw_x, raw_y|
    x, y = canvas_xy(raw_x, raw_y)
    move(x - last[0], y - last[1])
    last = [x, y]
    block.call(x, y) if block
  end
  bind_item_event('<B1-Motion>', drag, subs: %i[x y])

  self
end

exists?

Returns Boolean — whether any item currently matches #tag_or_id - always true for a single-item handle from a creation method (the item exists until #deleted), meaningful for a Handle#tagged group that may currently match zero items

View source ▼

def exists?
  !@app.command(@canvas_path, :find, :withtag, @tag_or_id).empty?
end

initialize(app, canvas_path, tag_or_id)

Returns CanvasItem — a new instance of CanvasItem

@api private

View source ▼

def initialize(app, canvas_path, tag_or_id)
  @app = app
  @canvas_path = canvas_path
  @tag_or_id = tag_or_id.to_s
end

move(dx, dy)

Move relative to the current position.

Parameters

• dx Numeric
• dy Numeric

Returns self

View source ▼

def move(dx, dy)
  @app.command(@canvas_path, :move, @tag_or_id, dx, dy)
  self
end

on_click(&block)

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.

Returns self

@yield called with no arguments

View source ▼

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

on_drag(&block)

Fires while dragging this item (left button held down and moving). Delivers Integer x/y already converted through the canvas’s own canvasx/canvasy, same as Handle#on_drag does when bound to a canvas - callers never have to remember to do that themselves.

Returns self

@yield x, y Integer coordinates

View source ▼

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

on_right_click(menu nil, &block)

Fires on a right click, however the platform spells it - see MouseEvents::RIGHT_CLICK_EVENTS. 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 MouseEvents::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|
      @app.popup_menu(menu.path, x: root_x, y: root_y)
    end
    MouseEvents::RIGHT_CLICK_EVENTS.each { |event| bind_item_event(event, popup, subs: %i[root_x root_y]) }
  elsif block
    MouseEvents::RIGHT_CLICK_EVENTS.each { |event| bind_item_event(event, block) }
  else
    raise ArgumentError, "on_right_click needs either a menu handle or a block"
  end
  self
end

points

Returns Array<Float> — the current coordinate list

View source ▼

def points
  result = @app.command(@canvas_path, :coords, @tag_or_id)
  @app.split_list(result).map(&:to_f)
end

points=(new_coords)

Replace the coordinate list outright (as opposed to #move’s relative shift).

Parameters

• new_coords Array<Numeric> — flat or nested (e.g. [[x1, y1], [x2, y2]]) - flattened either way

Returns void

View source ▼

def points=(new_coords)
  @app.command(@canvas_path, :coords, @tag_or_id, *new_coords.flatten)
end

scale(ox, oy, sx, sy)

Scale coordinates relative to a fixed point.

Parameters

• ox Numeric — x origin scaling is relative to
• oy Numeric — y origin scaling is relative to
• sx Numeric — x scale factor
• sy Numeric — y scale factor

Returns self

View source ▼

def scale(ox, oy, sx, sy)
  @app.command(@canvas_path, :scale, @tag_or_id, ox, oy, sx, sy)
  self
end

send_to_back(below nil)

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.

Parameters

• below CanvasItem, String, nil

Returns self

View source ▼

def send_to_back(below = nil)
  args = below ? [resolve(below)] : []
  @app.command(@canvas_path, :lower, @tag_or_id, *args)
  self
end

virtual_path

Returns String — 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.

View source ▼

def virtual_path
  "#{@canvas_path}!#{@tag_or_id}"
end