Teek::Photo Class

blank

Clear the image to fully transparent.

Returns self

View source ▼

def blank
  @app.interp.photo_blank(@name)
  self
end

command(*args, **kwargs)

Invoke a photo subcommand not covered by a dedicated method above (e.g. copy, read, write). Prepends the image name as the Tcl command, exactly like Widget#command does for widgets.

Parameters

• args — positional arguments
• kwargs — keyword arguments mapped to -key value pairs

Returns String — the Tcl result

# Subsample a copy of another photo
thumb = Teek::Photo.new(app)
thumb.command(:copy, source_photo, subsample: 4)

View source ▼

def command(*args, **kwargs)
  @app.command(@name, *args, **kwargs)
end

delete

Delete this photo image and free its resources.

Cancels the GC finalizer registered by #initialize - otherwise a later collection could delete an unrelated image if this name gets reused (e.g. an explicit name: passed to a later Photo).

Returns void

View source ▼

def delete
  ObjectSpace.undefine_finalizer(self)
  @app.tcl_eval("image delete #{@name}")
end

exist?

Check if this photo image still exists.

Returns Boolean

View source ▼

def exist?
  @app.tcl_eval("image type #{@name}") == 'photo'
rescue Teek::TclError
  false
end

expand(width, height)

Expand image to at least the given dimensions. Will not shrink.

Parameters

• width Integer — minimum width
• height Integer — minimum height

Returns self

@note Has no effect on photos created with explicit width: / height: options. Only works on auto-sized photos (those whose size was set by writing pixel data). This is a Tk limitation.

View source ▼

def expand(width, height)
  @app.interp.photo_expand(@name, width, height)
  self
end

get_image(x: nil, y: nil, width: nil, height: nil, unpack: false)

Read pixel data from the image.

Parameters

• x Integer — source X offset
• y Integer — source Y offset
• width Integer, nil — region width (nil for full image)
• height Integer, nil — region height (nil for full image)
• unpack Boolean — if true, return flat array of integers instead of binary string

Returns Hash — <code>data: String, width: Integer, height: Integer</code> or <code>pixels: Array&lt;Integer&gt;, width: Integer, height: Integer</code> if unpack is true

View source ▼

def get_image(x: nil, y: nil, width: nil, height: nil, unpack: false)
  opts = { unpack: unpack }
  opts[:x] = x if x
  opts[:y] = y if y
  opts[:width] = width if width
  opts[:height] = height if height
  @app.interp.photo_get_image(@name, opts)
end

get_pixel(x, y)

Read a single pixel.

Parameters

• x Integer — X coordinate
• y Integer — Y coordinate

Returns Array<Integer> — [r, g, b, a] values (0-255)

View source ▼

def get_pixel(x, y)
  @app.interp.photo_get_pixel(@name, x, y)
end

get_size

Get image dimensions.

Returns Array<Integer> — [width, height]

View source ▼

def get_size
  @app.interp.photo_get_size(@name)
end

initialize(app, name: nil, width: nil, height: nil, file: nil, data: nil, format: nil, palette: nil, gamma: nil)

Create a new photo image.

The underlying Tk image is automatically deleted once this Photo object is garbage collected and nothing else references it - keep it around (an ivar, a collection, etc.) for as long as you need the image, the same contract as File or Socket. If only the image name is kept (e.g. passed into a widget’s image:) and this wrapper is dropped, the image can be reclaimed out from under that reference; Tk shows a broken image rather than crashing, but the image won’t come back - call #delete explicitly rather than relying on GC timing if you need deterministic cleanup.

Parameters

• app Teek::App — the application instance
• name String, nil — Tcl image name (auto-generated if nil)
• width Integer, nil — image width in pixels
• height Integer, nil — image height in pixels
• file String, nil — path to an image file to load
• data String, nil — base64-encoded image data
• format String, nil — image format (e.g. "png", "gif")
• palette String, nil — palette specification
• gamma Float, nil — gamma correction value

Returns Photo — a new instance of Photo

View source ▼

def initialize(app, name: nil, width: nil, height: nil,
               file: nil, data: nil, format: nil, palette: nil, gamma: nil)
  @app = app
  @name = name || self.class.next_name

  kwargs = {}
  kwargs[:width] = width if width
  kwargs[:height] = height if height
  kwargs[:file] = file if file
  kwargs[:data] = data if data
  kwargs[:format] = format if format
  kwargs[:palette] = palette if palette
  kwargs[:gamma] = gamma if gamma

  @app.command(:image, :create, :photo, @name, **kwargs)
  ObjectSpace.define_finalizer(self, self.class.finalizer_for(@name, @app))
end

put_block(pixel_data, width, height, x: 0, y: 0, format: :rgba, composite: :set)

Write RGBA pixel data to the image.

Parameters

• pixel_data String — binary string, 4 bytes (RGBA) per pixel
• width Integer — width of the pixel block
• height Integer — height of the pixel block
• x Integer — destination X offset
• y Integer — destination Y offset
• format :rgba, :argb — pixel format
• composite :set, :overlay — compositing rule

Returns self

View source ▼

def put_block(pixel_data, width, height, x: 0, y: 0, format: :rgba, composite: :set)
  opts = { x: x, y: y, format: format, composite: composite }
  @app.interp.photo_put_block(@name, pixel_data, width, height, opts)
  self
end

put_zoomed_block(pixel_data, width, height, x: 0, y: 0, zoom_x: 1, zoom_y: 1, subsample_x: 1, subsample_y: 1, format: :rgba, composite: :set)

Write RGBA pixel data with zoom and subsample.

Zoom replicates each pixel (zoom=3 makes each source pixel 3x3). Subsample skips source pixels (subsample=2 takes every other pixel).

Parameters

• pixel_data String — binary string, 4 bytes (RGBA) per pixel
• width Integer — source width in pixels
• height Integer — source height in pixels
• x Integer — destination X offset
• y Integer — destination Y offset
• zoom_x Integer — horizontal zoom factor
• zoom_y Integer — vertical zoom factor
• subsample_x Integer — horizontal subsample factor
• subsample_y Integer — vertical subsample factor
• format :rgba, :argb — pixel format
• composite :set, :overlay — compositing rule

Returns self

View source ▼

def put_zoomed_block(pixel_data, width, height,
                     x: 0, y: 0, zoom_x: 1, zoom_y: 1,
                     subsample_x: 1, subsample_y: 1,
                     format: :rgba, composite: :set)
  opts = {
    x: x, y: y,
    zoom_x: zoom_x, zoom_y: zoom_y,
    subsample_x: subsample_x, subsample_y: subsample_y,
    format: format, composite: composite
  }
  @app.interp.photo_put_zoomed_block(@name, pixel_data, width, height, opts)
  self
end

set_size(width, height)

Set image dimensions. May crop or add transparent pixels.

Parameters

• width Integer — new width
• height Integer — new height

Returns self

View source ▼

def set_size(width, height)
  @app.interp.photo_set_size(@name, width, height)
  self
end

to_s

Returns String — the Tcl image name

View source ▼

def to_s
  @name
end