Class: TkPhotoImage

Inherits:

Object
TkKernel
TkObject
TkImage
TkPhotoImage

Defined in:: lib/tk/image.rb

Overview

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 rewrited parts.

Direct Known Subclasses

Tk::BWidget::Bitmap

Constant Summary collapse

NullArgOptionKeys =

[ "shrink", "grayscale" ]

Instance Method Summary collapse

#blank ⇒ Object

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.
#cget(option) ⇒ Object

Returns the current value of the configuration option given by option.
#cget_strict(option) ⇒ Object
#copy(src, *opts) ⇒ Object

Copies a region from the image called source to the image called destination, possibly with pixel zooming and/or subsampling.
#data(keys = {}) ⇒ Object

Returns image data in the form of a string.
#get(x, y) ⇒ Object

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.
#get_transparency(x, y) ⇒ Object

Returns a boolean indicating if the pixel at (x,y) is transparent.
#initialize(*args) ⇒ TkPhotoImage constructor

Create a new image with the given options.
#put(data, *opts) ⇒ Object
#read(file, *opts) ⇒ Object
#redither ⇒ Object
#set_transparency(x, y, state) ⇒ Object

Makes the pixel at (x,y) transparent if state is true, and makes that pixel opaque otherwise.
#write(file, *opts) ⇒ Object

Methods inherited from TkImage

#delete, #height, #inuse, #itemtype, names, new, types, #width

Methods included from Tk

BinaryString, EncodedString, #Grid, #Pack, #Place, UTF8_String, __create_widget_set__, __disable_toplevel_control__, __import_toplevel_aliases__, __regist_toplevel_aliases__, __remove_toplevel_aliases__, __reset_toplevel_owner__, __set_loaded_toplevel_aliases__, __set_toplevel_aliases__, __toplevel_alias_setup_proc__, add_kinsoku, bell, bell_on_display, const_missing, current_grabs, cursor_display, default_widget_set, default_widget_set=, delete_kinsoku, destroy, #encoding, #encoding=, errorCode, errorInfo, exit, focus, focus_lastfor, focus_next, focus_prev, focus_to, fromUTF8, grid, grid_forget, has_mainwindow?, load_tcllibrary, load_tclscript, load_tclscript_rsrc, load_tclscript_rsrcid, lower_window, pack, pack_forget, pkgconfig_get, pkgconfig_list, place, place_forget, raise_window, #root, show_kinsoku, sleep, strictMotif, subst_tk_backslash, subst_utf_backslash, tcl_pkgconfig_get, tcl_pkgconfig_list, thread_update, thread_update_idletasks, tk_pkgconfig_get, tk_pkgconfig_list, toUTF8, to_backslash_sequence, toplevel_aliases_on_widget_set, ungrid, unload_tcllibrary, unpack, unplace, update, #update, update_idletasks, utf_to_backslash, utf_to_backslash_sequence, wakeup, widget_set_symbols

Methods included from Tk::Encoding

#default_encoding=, #encoding=, #encoding_convertfrom, #encoding_convertto, #encoding_dirs, #encoding_dirs=, #encoding_name, #encoding_names, #encoding_obj, #encoding_objs, #encoding_system=, #encoding_system_name, #encoding_system_obj, #force_default_encoding, #force_default_encoding=, #force_default_encoding?, #tk_encoding_names

Methods included from TkCore

#_tk_call_to_list_core, #after, #after_cancel, #after_idle, #appname, #appsend, #appsend_deny, #appsend_displayof, callback, #callback_break, #callback_continue, #callback_return, #chooseColor, #chooseDirectory, #do_one_event, #event_generate, #getMultipleOpenFile, #getMultipleSaveFile, #getOpenFile, #getSaveFile, #get_eventloop_tick, #get_eventloop_weight, #get_no_event_wait, #inactive, #inactive_displayof, #info, #ip_eval, #ip_eval_with_enc, #ip_eval_without_enc, #ip_invoke, #ip_invoke_with_enc, #ip_invoke_without_enc, #is_mainloop?, #load_cmd_on_ip, #mainloop, #mainloop_exist?, #mainloop_thread?, #mainloop_watchdog, #messageBox, #rb_appsend, #rb_appsend_displayof, #reset_inactive, #reset_inactive_displayof, #restart, #scaling, #scaling_displayof, #set_eventloop_tick, #set_eventloop_weight, #set_no_event_wait, #tk_call, #tk_call_to_list, #tk_call_to_list_with_enc, #tk_call_to_list_without_enc, #tk_call_to_simplelist, #tk_call_to_simplelist_with_enc, #tk_call_to_simplelist_without_enc, #tk_call_with_enc, #tk_call_without_enc, #windowingsystem

Methods included from TkComm

_at, _callback_entry?, _callback_entry_class?, _curr_cmd_id, _fromUTF8, _genobj_for_tkwidget, _next_cmd_id, _toUTF8, array2tk_list, #bind, #bind_all, #bind_append, #bind_append_all, #bind_remove, #bind_remove_all, #bindinfo, #bindinfo_all, bool, image_obj, #install_cmd, install_cmd, list, num_or_nil, num_or_str, number, procedure, simplelist, slice_ary, string, #subst, tk_split_escstr, tk_split_list, tk_split_simplelist, tk_split_sublist, tk_tcl2ruby, uninstall_cmd, #uninstall_cmd, window

Methods included from TkEvent

#install_bind, #install_bind_for_event_class

Methods included from TkUtil

#_conv_args, _conv_args, #_fromUTF8, #_get_eval_enc_str, _get_eval_enc_str, #_get_eval_string, _get_eval_string, _symbolkey2str, #_symbolkey2str, #_toUTF8, #bool, bool, callback, eval_cmd, #hash_kv, hash_kv, install_cmd, #num_or_nil, num_or_nil, num_or_str, #num_or_str, number, #number, string, #string, uninstall_cmd, untrust

Methods inherited from TkObject

#destroy, #epath, #event_generate, #method_missing, #path, #tk_send, #tk_send_to_list, #tk_send_to_list_with_enc, #tk_send_to_list_without_enc, #tk_send_to_simplelist, #tk_send_to_simplelist_with_enc, #tk_send_to_simplelist_without_enc, #tk_send_with_enc, #tk_send_without_enc, #to_eval

Methods included from TkBindCore

#bind, #bind_append, #bind_remove, #bindinfo

Methods included from TkConfigMethod

#[], #[]=, __IGNORE_UNKNOWN_CONFIGURE_OPTION__, #__check_available_configure_options, __set_IGNORE_UNKNOWN_CONFIGURE_OPTION__!, #cget_tkstring, #config_hash_kv, #configinfo, #configure, #configure_cmd, #current_configinfo

Methods included from TkTreatFont

#font_configinfo, #font_configure, #font_copy, #kanjifont_configure, #kanjifont_copy, #latinfont_configure, #latinfont_copy

Methods inherited from TkKernel

new

Constructor Details

#initialize(*args) ⇒ `TkPhotoImage`

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 'lib/tk/image.rb', line 189

def initialize(*args)
  @type = 'photo'
  super(*args)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class TkObject

Instance Method Details

#blank ⇒ `Object`

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 197

def blank
  tk_send_without_enc('blank')
  self
end

#cget(option) ⇒ `Object`

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 214

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) ⇒ `Object`

# File 'lib/tk/image.rb', line 202

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) ⇒ `Object`

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 277

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 = {}) ⇒ `Object`

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.



318
319
320

# File 'lib/tk/image.rb', line 318

def data(keys={})
  tk_split_list(tk_send('data', *_photo_hash_kv(keys)))
end

#get(x, y) ⇒ `Object`

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.



325
326
327

# File 'lib/tk/image.rb', line 325

def get(x, y)
  tk_send('get', x, y).split.collect{|n| n.to_i}
end

#get_transparency(x, y) ⇒ `Object`

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



366
367
368

# File 'lib/tk/image.rb', line 366

def get_transparency(x, y)
  bool(tk_send('transparency', 'get', x, y))
end

#put(data, *opts) ⇒ `Object`

# File 'lib/tk/image.rb', line 329

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) ⇒ `Object`

# File 'lib/tk/image.rb', line 341

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 ⇒ `Object`

# File 'lib/tk/image.rb', line 360

def redither
  tk_send 'redither'
  self
end

#set_transparency(x, y, state) ⇒ `Object`

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

# File 'lib/tk/image.rb', line 372

def set_transparency(x, y, state)
  tk_send('transparency', 'set', x, y, state)
  self
end

#write(file, *opts) ⇒ `Object`

# File 'lib/tk/image.rb', line 377

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

Class: TkPhotoImage

Overview

Direct Known Subclasses

Constant Summary collapse

Constants inherited from TkImage

Constants included from Tk

Constants included from Tk::Encoding

Constants included from TkCore

Constants included from TkComm

Constants included from TkUtil