diff --git a/ext/tk/lib/tk/image.rb b/ext/tk/lib/tk/image.rb index 39d63478a64d28..4d768e31491187 100644 --- a/ext/tk/lib/tk/image.rb +++ b/ext/tk/lib/tk/image.rb @@ -72,7 +72,6 @@ def initialize(keys=nil) end unless @path Tk_Image_ID.mutex.synchronize{ - # @path = Tk_Image_ID.join('') @path = Tk_Image_ID.join(TkCore::INTERP._ip_id_) Tk_Image_ID[1].succ! } @@ -128,6 +127,12 @@ def initialize(*args) end end +# 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 +# http://www.tcl.tk/man/tcl8.5/TkCmd/photo.htm with some rewrited parts. class TkPhotoImage 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. def initialize(*args) @type = 'photo' super(*args) end + # 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. def blank tk_send_without_enc('blank') self @@ -164,6 +207,10 @@ def cget_strict(option) tk_tcl2ruby(tk_send('cget', '-' << option.to_s)) end end + + # 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 def cget(option) unless TkConfigMethod.__IGNORE_UNKNOWN_CONFIGURE_OPTION__ cget_strict(option) @@ -182,6 +229,50 @@ def cget(option) end end + # 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. def copy(src, *opts) if opts.size == 0 tk_send('copy', src) @@ -201,11 +292,31 @@ def copy(src, *opts) self end + # 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. def data(keys={}) - #tk_send('data', *_photo_hash_kv(keys)) tk_split_list(tk_send('data', *_photo_hash_kv(keys))) end + # 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. def get(x, y) tk_send('get', x, y).split.collect{|n| n.to_i} end @@ -246,11 +357,14 @@ def redither self end + # Returns a boolean indicating if the pixel at (x,y) is transparent. def get_transparency(x, y) bool(tk_send('transparency', 'get', x, y)) end - def set_transparency(x, y, st) - tk_send('transparency', 'set', x, y, st) + + # Makes the pixel at (x,y) transparent if state is true, and makes that pixel opaque otherwise. + def set_transparency(x, y, state) + tk_send('transparency', 'set', x, y, state) self end