# class 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.

Calls superclass method TkImage.new

    # File 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 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 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 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 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 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 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 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 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 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 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 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 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

### Private Instance Methods

_photo_hash_kv(keys) click to toggle source

    # File lib/tk/image.rb, line 140
    def _photo_hash_kv(keys)
      keys = _symbolkey2str(keys)
      NullArgOptionKeys.collect{|opt|
        if keys[opt]
          keys[opt] = None
        else
          keys.delete(opt)
        end
      }
      keys.collect{|k,v|
        ['-' << k, v]
      }.flatten
    end