Why in the world does Python's Tkinter break using canvas.create_image?

Question

I've got a python GUI app in the workings, which I intend to use on both Windows and Mac. The documentation on Tkinter isn't the greatest, and google-fu has failed me.

In short, I'm doing:

c = Canvas(
    master=frame,
    width=settings.WINDOW_SIZE[0],
    height=settings.WINDOW_SIZE[1],
    background=settings.CANVAS_COLOUR
)
file = PhotoImage(file=os.path.join('path', 'to', 'gif'))
c.create_bitmap(position, image=file)
c.pack()
root.mainloop()

If I comment out the create_bitmap line, the app draws fine. If I comment it back in, I get the following error:

_tkinter.TclError: unknown option "-image"

Which is odd. Tkinter is fine, according to the python tests (ie, importing _tkinter, Tkinter, and doing Tk()). I've since installed PIL against my windows setup (XP SP3, Python 2.6) imagining that it was doing some of the heavy lifting at a low level. It doesn't seem to be; I still get the aforementioned error.

The full stacktrace, excluding the code I've already pasted, is:

File "C:\Python26\lib\lib-tk\Tkinter.py", line 2153, in create_bitmap
return self._create('bitmap', args, kw)
File "C:\Python26\lib\lib-tk\Tkinter.py", line 2147, in _create
*(args + self._options(cnf, kw))))

Anyone able to shed any light?

Answer 1

Short answer: Don't use create_bitmap when you mean to use create_image.

Answer 2

Tk has two types of graphics, bitmap and image. Images come in two flavours, bitmap and photo. Bitmaps and Images of type bitmap are not the same thing, which leads to confusion in docs. PhotoImage creates an image of type photo, and needs an image object in the canvas, so the solution is, as you already concluded, to use create_image.

Answer 3

The create_bitmap() method does not have an image argument; it has a bitmap argument instead.

The error you get comes from the fact that in Tkinter, a Tcl interpreter is running embedded in the Python process, and all GUI interaction goes back and forth between Python and Tcl; so, the error you get comes from the fact that Tcl replies "I don't know any -image option in the .create_bitmap call".

In any case, like Jeff said, you probably want the create_image method.