Class: TkPhotoImage

Inherits:
TkImage show all
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 rewritten parts.

Direct Known Subclasses

Tk::BWidget::Bitmap

Constant Summary collapse

NullArgOptionKeys =
[ "shrink", "grayscale" ]

Constants inherited from TkImage

TkImage::TkCommandNames, TkImage::Tk_IMGTBL

Constants included from Tk

Tk::AUTO_PATH, Tk::Fontchooser, Tk::INTERP, Tk::JAPANIZED_TK, Tk::LIBRARY_PATH, Tk::MAINLOOP, Tk::PACKAGE_PATH, Tk::RELEASE_DATE, Tk::TCL_LIBRARY_PATH, Tk::TCL_MAJOR_VERSION, Tk::TCL_MINOR_VERSION, Tk::TCL_PACKAGE_PATH, Tk::TCL_PATCHLEVEL, Tk::TCL_PRECISION, Tk::TCL_VERSION, Tk::TK_MAJOR_VERSION, Tk::TK_MINOR_VERSION, Tk::TK_PATCHLEVEL, Tk::TK_VERSION, Tk::Tkextlib_RELEASE_DATE, Tk::TreeCtrl_Widget, Tk::X_Scrollable, Tk::Y_Scrollable

Constants included from Tk::Encoding

Tk::Encoding::BINARY, Tk::Encoding::BINARY_NAME, Tk::Encoding::DEFAULT_EXTERNAL_NAME, Tk::Encoding::DEFAULT_INTERNAL_NAME, Tk::Encoding::ENCODING_TABLE, Tk::Encoding::RubyEncoding, Tk::Encoding::TkCommandNames, Tk::Encoding::UNKNOWN, Tk::Encoding::UTF8_NAME

Constants included from TkCore

TkCore::EventFlag, TkCore::INTERP, TkCore::INTERP_MUTEX, TkCore::INTERP_ROOT_CHECK, TkCore::INTERP_THREAD, TkCore::INTERP_THREAD_STATUS, TkCore::RUN_EVENTLOOP_ON_MAIN_THREAD, TkCore::WIDGET_DESTROY_HOOK, TkCore::WITH_ENCODING, TkCore::WITH_RUBY_VM

Constants included from TkComm

TkComm::GET_CONFIGINFO_AS_ARRAY, TkComm::GET_CONFIGINFOwoRES_AS_ARRAY, TkComm::TkExtlibAutoloadModule, TkComm::Tk_CMDTBL, TkComm::Tk_IDs, TkComm::Tk_WINDOWS, TkComm::USE_TCLs_LIST_FUNCTIONS, TkComm::WidgetClassNames

Constants included from TkUtil

TkUtil::None, TkUtil::RELEASE_DATE

Instance Method Summary collapse

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__, _replace_toplevel_aliases, add_kinsoku, backup_current_topdef, bell, bell_on_display, const_missing, current_grabs, cursor_display, default_widget_set, default_widget_set=, define_topalias, define_topobj, 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, regist_sym_for_loaded_file, replace_topalias, replace_topobj, #root, set_topalias, 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, topalias_defined?, toplevel_aliases_on_widget_set, topobj_defined?, 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_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.


190
191
192
193
# File 'lib/tk/image.rb', line 190

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

#blankObject

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.


198
199
200
201
# File 'lib/tk/image.rb', line 198

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


215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
# 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) ⇒ Object


203
204
205
206
207
208
209
210
# 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) ⇒ 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.


278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
# 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 = {}) ⇒ 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.


319
320
321
# File 'lib/tk/image.rb', line 319

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.


326
327
328
# 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) ⇒ Object

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


367
368
369
# File 'lib/tk/image.rb', line 367

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

#put(data, *opts) ⇒ Object


330
331
332
333
334
335
336
337
338
339
340
# 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) ⇒ Object


342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
# 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

#reditherObject


361
362
363
364
# File 'lib/tk/image.rb', line 361

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.


373
374
375
376
# 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) ⇒ Object


378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
# 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