PhotoImage

A photo is an image whose pixels can display any color or be transparent. At present, only GIF and PPM/PGM formats are supported, but an interface exists to allow additional image file formats to be added easily.

This class documentation is a copy from the original Tcl/Tk at www.tcl.tk/man/tcl8.5/TkCmd/photo.htm with some rewritten parts.

Constants

NullArgOptionKeys

Public Class Methods

new(*args) click to toggle source

Create a new image with the given options.

Examples of use :¶ ↑

Create an empty image of 300x200 pixels¶ ↑

image = TkPhotoImage.new(:height => 200, :width => 300)

Create an image from a file¶ ↑

image = TkPhotoImage.new(:file: => 'my_image.gif')

Options¶ ↑

Photos support the following options:

:data Specifies the contents of the image as a string.
:format Specifies the name of the file format for the data.
:file Gives the name of a file that is to be read to supply data for the image.
:gamma Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value.
height Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it.
palette Specifies the resolution of the color cube to be allocated for displaying this image.
width Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it.

 
               # File tk/lib/tk/image.rb, line 190
def initialize(*args)
  @type = 'photo'
  super(*args)
end

Public Instance Methods

blank() click to toggle source

Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through.

 
               # File tk/lib/tk/image.rb, line 198
def blank
  tk_send_without_enc('blank')
  self
end

cget(option) click to toggle source

Returns the current value of the configuration option given by option. Example, display name of the file from which image was created:

puts image.cget :file

 
               # File tk/lib/tk/image.rb, line 215
def cget(option)
  unless TkConfigMethod.__IGNORE_UNKNOWN_CONFIGURE_OPTION__
    cget_strict(option)
  else
    begin
      cget_strict(option)
    rescue => e
      if current_configinfo.has_key?(option.to_s)
        # error on known option
        fail e
      else
        # unknown option
        nil
      end
    end
  end
end

cget_strict(option) click to toggle source

 
               # File tk/lib/tk/image.rb, line 203
def cget_strict(option)
  case option.to_s
  when 'data', 'file'
    tk_send 'cget', '-' << option.to_s
  else
    tk_tcl2ruby(tk_send('cget', '-' << option.to_s))
  end
end

copy(src, *opts) click to toggle source

Copies a region from the image called source to the image called destination, possibly with pixel zooming and/or subsampling. If no options are specified, this method copies the whole of source into destination, starting at coordinates (0,0) in destination. The following options may be specified:

:from [x1, y1, x2, y2] Specifies a rectangular sub-region of the source image to be copied. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the :from option is not given, the default is the whole source image.
:to [x1, y1, x2, y2] Specifies a rectangular sub-region of the destination image to be affected. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is (x1,y1) plus the size of the source region (after subsampling and zooming, if specified). If x2 and y2 are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion.
:shrink Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the :width or :height configuration option, respectively.
:zoom [x, y] Specifies that the source region should be magnified by a factor of x in the X direction and y in the Y direction. If y is not given, the default value is the same as x. With this option, each pixel in the source image will be expanded into a block of x x y pixels in the destination image, all the same color. x and y must be greater than 0.
:subsample [x, y] Specifies that the source image should be reduced in size by using only every xth pixel in the X direction and yth pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If y is not given, the default value is the same as x.
:compositingrule rule Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of overlay is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of set is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is overlay.

 
               # File tk/lib/tk/image.rb, line 278
def copy(src, *opts)
  if opts.size == 0
    tk_send('copy', src)
  elsif opts.size == 1 && opts[0].kind_of?(Hash)
    tk_send('copy', src, *_photo_hash_kv(opts[0]))
  else
    # for backward compatibility
    args = opts.collect{|term|
      if term.kind_of?(String) && term.include?(?\s)
        term.split
      else
        term
      end
    }.flatten
    tk_send('copy', src, *args)
  end
  self
end

data(keys={}) click to toggle source

Returns image data in the form of a string. The following options may be specified:

:background color If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color.
:format format-name Specifies the name of the image file format handler to be used. Specifically, this subcommand searches for the first handler whose name matches an initial substring of format-name and which has the capability to read this image data. If this option is not given, this subcommand uses the first handler that has the capability to read the image data.
:from [x1, y1, x2, y2] Specifies a rectangular region of imageName to be returned. If only x1 and y1 are specified, the region extends from (x1,y1) to the bottom-right corner of imageName. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region, including x1,y1 and excluding x2,y2. The default, if this option is not given, is the whole image.
:grayscale If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale.

 
               # File tk/lib/tk/image.rb, line 319
def data(keys={})
  tk_split_list(tk_send('data', *_photo_hash_kv(keys)))
end

get(x, y) click to toggle source

Returns the color of the pixel at coordinates (x,y) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively.

 
               # File tk/lib/tk/image.rb, line 326
def get(x, y)
  tk_send('get', x, y).split.collect{|n| n.to_i}
end

get_transparency(x, y) click to toggle source

Returns a boolean indicating if the pixel at (x,y) is transparent.

 
               # File tk/lib/tk/image.rb, line 367
def get_transparency(x, y)
  bool(tk_send('transparency', 'get', x, y))
end

put(data, *opts) click to toggle source

 
               # File tk/lib/tk/image.rb, line 330
def put(data, *opts)
  if opts.empty?
    tk_send('put', data)
  elsif opts.size == 1 && opts[0].kind_of?(Hash)
    tk_send('put', data, *_photo_hash_kv(opts[0]))
  else
    # for backward compatibility
    tk_send('put', data, '-to', *opts)
  end
  self
end

read(file, *opts) click to toggle source

 
               # File tk/lib/tk/image.rb, line 342
def read(file, *opts)
  if opts.size == 0
    tk_send('read', file)
  elsif opts.size == 1 && opts[0].kind_of?(Hash)
    tk_send('read', file, *_photo_hash_kv(opts[0]))
  else
    # for backward compatibility
    args = opts.collect{|term|
      if term.kind_of?(String) && term.include?(?\s)
        term.split
      else
        term
      end
    }.flatten
    tk_send('read', file, *args)
  end
  self
end

redither() click to toggle source

 
               # File tk/lib/tk/image.rb, line 361
def redither
  tk_send 'redither'
  self
end

set_transparency(x, y, state) click to toggle source

Makes the pixel at (x,y) transparent if state is true, and makes that pixel opaque otherwise.

 
               # File tk/lib/tk/image.rb, line 373
def set_transparency(x, y, state)
  tk_send('transparency', 'set', x, y, state)
  self
end

write(file, *opts) click to toggle source

 
               # File tk/lib/tk/image.rb, line 378
def write(file, *opts)
  if opts.size == 0
    tk_send('write', file)
  elsif opts.size == 1 && opts[0].kind_of?(Hash)
    tk_send('write', file, *_photo_hash_kv(opts[0]))
  else
    # for backward compatibility
    args = opts.collect{|term|
      if term.kind_of?(String) && term.include?(?\s)
        term.split
      else
        term
      end
    }.flatten
    tk_send('write', file, *args)
  end
  self
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Class/Module Index