The Tkinter Widget Overview is Copyright © Fredrik Lundh, 1997. All rights reserved. Portions of this document might be included in my forthcoming book on rapid application development with Python, to be published by O'Reilly and Associates later this year.


Tkinter PhotoImage

The Tkinter PhotoImage class is used to represent a true color image (24 bits per pixel). It can be displayed everywhere an image can be used, and is dithered if necessary.

When you create an image, it is registered in an image manager. Any widget displaying the image also registers with the manager, so changes to the image are automatically reflected everywhere it is displayed. However, unlike ordinary widgets, Tkinter doesn't know if the image is displayed or not, so if you destroy the PhotoImage instance, Tkinter will tell the image manager to blank the image. To avoid unpleasant surprises, you might wish to assign the image instance to an attribute in every widget instance displaying the image. This way, the image will not be deleted before the widget.

If you're using PIL, consider using the PhotoImage class in the ImageTk module instead of this class. The constructor for this class takes a PIL Image object as its argument, and creates a photo image object that you can use as usual in Tkinter, but also update using the paste method. Changes to the image are automatically reflected everywhere the image is displayed.

Options

You can specify options when creating the image, and through the dictionary interface. The cget, configure, and keys methods are not available.

channel. Not in Tkinter 1.63.

data (string). Specifies the image data as a string. In standard Tk, this can only be used with GIF files stored in base64 encoding (Tk 4.2 or later).

file (string). Specifies the filename for an image file. In standard Tk, the file may contain image data stored as either GIF or PGM/PPM. If neither file nor data options are given, a transparent image is created. If both options are used, file is used.

gamma (float). Specifies the linearity of the display device. Unless you know the gamma of both the image and the display, use the default value (which is 1.0, or linear gamma).

height, width (integer). Specifies the size of the image. If used with file or data, the image data will be cropped or expanded to the given size. Regions outside the provided image data will be transparent.

name (string). Specifies the name of the image. If not given, Tkinter assigns a name. This option can not be queried; use str(instance) to get the image name.

palette (integer or string). Specifies the resolution of the color cube used to display the image. If you give a single value, the image is displayed in greyscale with the given number of levels. If you give a string containing three numbers separated by slashes, the image will be displayed in color with that number of levels of red, green, and blue, respectively. This attribute is ignored on a true color display. In most cases, you should use the default value, where the number of levels is chosen based on the display type. For example, on an 8-bit display, Tk tries to allocate 198 distinct colors.

Methods

blank(). Make the image transparent. If the size is not set, set the height and width to 0.

cget(), config(), configure(). Not in Tkinter 1.63.

copy(). Create a new Photoimage instance, and copy the contents of this image into the new image.

get( x, y ). Get the pixel value at position (x, y), where (0, 0) is in the upper left corner of the image.

height(). Returns the height of the image, in pixels.

put( data, to ).

read(). Not in Tkinter 1.63.

subsample( x, y ).

type(). Returns the type of the image (the string "photo").

width(). Returns the width of the image, in pixels.

write( filename, format, from ). Write the image to a file, using the given format. If the format is not given, Tk chooses the first format handler that's willing to write the image (usually PPM). If from is given, it specifies which region to save, as a 4-tuple specifying (left, upper, right, lower) where (0, 0) is the upper left corner of the image. If from is not given, the whole image is saved.

zoom( x, y ). Create a new Photoimage instance, and copy the contents of this image into the new image. The image is expanded so that each input pixel covers x times y pixels in the output image. If y is omitted, it defaults to x.