Imaging#

Two kinds of image reach a widget’s image option. PhotoImage is Tk’s own image primitive — load a PNG or GIF from a file or base-64 data, or draw one pixel by pixel, then pass it to a Button, Label, or any widget that takes an image. The icon engine renders a named Bootstrap Icons glyph as a theme-colored image, so you can put a crisp, recolorable icon on a widget without shipping image files. The Icons guide shows the icon engine in use.

Photo images#

class PhotoImage(name=None, cnf={}, master=None, *, data=None, file=None, format=None, width=0, height=0)

A full-color image you can display on a widget. Create an empty canvas by giving width/height, or load one from file (a PNG or GIF path) or data (the image bytes, or base-64 text). Hold a reference to the object for as long as the widget shows it — Tk does not, and a garbage-collected PhotoImage blanks the widget.

Parameters:

file – path to a PNG or GIF image to load.
data – the image as bytes or a base-64 string (an alternative to file).
format – the image format, when it can’t be inferred (e.g. "gif").
width – the width in pixels of a blank image.
height – the height in pixels of a blank image.

width(): Return the image width in pixels.

height(): Return the image height in pixels.

get(x, y): Return the color of the pixel at (x, y) as an (r, g, b) tuple.

put(data, to=None)

Write colors into the image. data is a color string or a nested sequence of color rows; to is the (x, y) corner (or an (x1, y1, x2, y2) box) to write into.

Parameters:

data – a color, or rows of colors, to write.
to – where to write — a corner or a bounding box.

blank(): Clear the image to transparent, keeping its size.

copy()

Return a new PhotoImage with the same contents.

Return type:: PhotoImage

zoom(x, y=None)

Return a copy magnified by integer factor x horizontally and y vertically (y defaults to x).

Return type:: PhotoImage

subsample(x, y=None)

Return a copy reduced by integer factor x horizontally and y vertically (y defaults to x).

Return type:: PhotoImage

write(filename, format=None, from_coords=None)

Save the image to filename.

Parameters:

filename – the path to write to.
format – the output format (e.g. "png").
from_coords – an optional region of the image to save.

configure(**options): Get or set image options (width, height, data, file, …). Alias: config.

cget(option): Return the value of one image option.

One related method lives on the widget, not on PhotoImage:

image_types()

The image types this Tk build can create — ('photo', 'bitmap'). Call it on any widget.

Returns:: the available image type names.
Return type:: tuple

Icons#

Icon(name, size=16, color=None)#

Render a Bootstrap Icons glyph as a cached Tk image.

Returns the Tcl image name (a string), usable directly as a widget’s image= – the engine’s content-addressed cache holds a strong reference, so the image stays alive and identical (name, size, color) calls dedupe.

gear = ttk.Icon("gear-fill", size=20, color="primary")
ttk.Button(app, text="Settings", image=gear, compound="left").pack()

Parameters:

name (str) – A Bootstrap Icons glyph name (e.g. “gear-fill”, “check-square-fill”). An unknown name raises ValueError.
size (int | tuple[int, int]) – The logical UI size. It is converted once by the root-bound service; final dimensions may be odd.
color (str | None) – A bootstyle keyword (“primary”, “success”, “fg”, …) resolved against the active theme, or a hex string passed through. None (the default) resolves to the theme foreground.

apply_icon(widget, name, *, size=None, states=None, compound=None, icon_only=False)#

Put a theme-aware Bootstrap Icons glyph on widget.

Unlike a bare Icon(...) used as image=, this tracks the active theme and the widget’s states: the glyph color follows the widget’s style foreground, so it inverts on outline/toggle buttons, mutes when disabled, and re-colors on a theme switch. It does so by giving the widget a derived, content-hashed style that augments (inherits) its current style/ bootstyle.

Parameters:

widget – A ttk Button (incl. Toolbutton/Outline/link/ghost variants), Label, Menubutton, Checkbutton, or Radiobutton. Any other class raises TypeError (it has no image-bearing label element; use a per-item image API for Treeview/Notebook).
name (str | None) – A Bootstrap Icons glyph name (e.g. "gear-fill"). None/"" removes the icon and restores the base style.
size (int | tuple[int, int]) – The logical UI size (converted by the root-bound scaling service).
states (dict[str, str] | None) – Optional {state_string: glyph_name} to show a different glyph per state (e.g. {"selected": "check-square-fill"}). The color still follows the foreground. State strings are ttk state specs ("disabled", "pressed !disabled", …).
compound (str | None) – The ttk -compound option (icon/text arrangement). Defaults to LEFT when the widget has text, else icon-only. Ignored (forced to IMAGE) when icon_only is set.
icon_only (bool) – Render the widget as an icon-only control: hide any text (compound=IMAGE) and give it a symmetric padding that makes it a square the same height as a normal widget. The default glyph is a touch larger; an explicit size (and a widget padding= option, which wins over the style) still take precedence.

Returns the derived ttk style name, or None when the icon was cleared.

icon_element(style, name, *, size, default, states=None, **options)#

Create a ttk image element whose per-state image is a Bootstrap Icons glyph.

The Style.map-aligned analog of image_element, with the icon as the asset source: each per-state spec is rendered via Icon/Assets.icon and assembled into one validated, first-match-wins image element.

name is the element name and must be "<ttkstyle>.<element>" (e.g. "Favorite.TCheckbutton.indicator"); the foreground a color-less spec follows is looked up on the <ttkstyle> prefix (name minus its last component).

Per-state spec grammar (default and each states value):

A bare string is the icon name; its color follows the foreground configured for that state.
A dict with optional name and color keys: name omitted uses the default icon; color omitted follows the foreground. color is a bootstyle keyword or a hex value, resolved once against the active theme.

state_map(style, "Favorite.TCheckbutton", foreground={"disabled": "#888"})
icon_element(style, "Favorite.TCheckbutton.indicator", size=20,
    default={"name": "star-fill", "color": "warning"},  # selected -> accent
    states={"!selected": "star"},                       # off -> follows fg
    border=4, sticky="w")

states is an ordered dict; ttk matches its specs first-match-wins, so the insertion order is the match order. Numeric border, padding, width, and height options are logical UI units and convert with the image frame; other options pass through to element_create.

Imaging#

Photo images#

Icons#

See also#