Updated 2015-05-22 02:18:44 by RLE
wm iconbitmap window ?bitmap?
wm iconbitmap window ?-default? ?image?

If bitmap is specified, then it names a bitmap in the standard forms accepted by Tk (see the Tk_GetBitmap manual entry [1] for details). This bitmap is passed to the window manager to be displayed in window 's icon, and the command returns an empty string.

If an empty string is specified for bitmap, then any current icon bitmap is cancelled for window. If bitmap is specified then the command returns an empty string. Otherwise it returns the name of the current icon bitmap associated with window, or an empty string if window has no icon bitmap.

On the Windows operating system, an additional flag is supported: wm iconbitmap window ?-default? ?image?. If the -default flag is given, the icon is applied to all toplevel windows (existing and future) to which no other specific icon has yet been applied.

In addition to bitmap image types, any (name of a) file which contains a valid Windows icon is also accepted (usually .ico or .icr files). Tcl will first test if the files contains an icon, and if that fails, test for a bitmap. (Tcl Help, bold addition by RS)

[Eric Brunel] writes, on news:comp.lang.tcl ,

Since I just spent half an hour to figure out how this works, I thought someone might be interested. The exact syntax is:
 wm iconbitmap <window> <icoFileName>

and not:
 wm iconbitmap <window> @<icoFileName>

(the "regular" bitmap files required the "@" in front of them and the manual is a tad unclear on this point...).

HolgerJ: 2004-03-11 The above is _not_ true, neither for Tk8.3.2/Windows nor for Tk8.3.2/Linux. In both cases, leaving out the @ before the file name results in an error. On _both_ platforms, @filename.xbm sets the image and can be retrieved later by calling "wm iconbitmap ." without a new icon definition. Using .ico files results in an error, on _both_ platforms!

But it is also true that on _both_ platforms (MS Windows 2000 and Linux with IceWM) the icon does _not_ show. On Windows, the icon remains to be the Tk logo; on IceWM, the icons remains to be an X logo. Bad luck, no cigar! The changing of the icon does work with Tk8.4 on KDE3.1 (yes!), but not on IceWM.

Since other apps (like Mozilla and xterm) have no problem setting their individual icons on IceWM, the fault has to be Tk's. Tk8.4.2 on Windows is also funny. Using an .ico file with the leading @ works fine, using an .xbm file gives wrong colors, but works. Leaving out the @ in front of the filename works with almost all kinds of files and uses the icon of the associated file type.
 wm iconbitmap . whateverfile.pdf

shows the PDF icon in your Tk app. Is this of much use? Maybe, but is it the expected behavior?

KD: Yes, it is the expected behaviour. When the file itself is not an icon, Tk asks Windows which icon is associated with the file.

MiHa: That even works with empty files: Create a new textfile, rename it to x.pdf or x.mp3, and
  wm iconbitmap . x.mp3

will set the icon at the top of the window to the icon registered for that filetype.

KD: I also tried to create a bitmap using "image create bitmap bm1 -file filename.xbm" and use this later in a "wm iconbitmap . bm1", but the result is an error message 'bitmap bm1 not defined'. What to do next?

DKF: It sounds like IceWM is ignoring the ICCCM specification for icon bitmaps and using something else (probably one of the Free Desktop things, which I can't remember the URL for.) That's legal, but not very useful here.

Therefore, typing
 wm iconbitmap . myicon.ico

(where myicon.ico can be either this relative name, or even a full pathname) results in Tk reading the file to determine whether it is an icon or a bitmap file.

Recently tclguy mentioned on comp.lang.tcl that a) the @ isn't required for Windows, but is for Unix and that b) windows requires .ico for the format of the file, while Unix requires .xbm formatted files.

While these differences do mean that you have to code different lines for Windows vs Unix, considering that wm is pretty platform/desktop specific that is going to have to be something one deals with.

Question 1 : what does one do if they want to use on Windows a .bmp file for an icon?

Vince I think in Tcl 8.4, some uses with a Tk bitmap do work.

Question 2 : what does one do if one wants to make the icon in Tcl itself, e.g. use a string as input for the icon ?

RS: Oh yes - if we had a "gateway" to photo images, we could use base64 encoded data, or strimjes (see strimj - string image routines), or files - a grand unification.

So another weekend project is born? RS: Hmm.. no promises - I have no ways of fiddling with the core at home. Fun projects are about sitting in the balcony, scribbling a few lines of Tcl, and late in the evening they all prove to work ;-)

MiHa 2015-05-20: Has anybody done an example of use a string as input to iconbitmap yet ?

[Boltar] I'm using Tcl/Tk on a Windows2000 system. On Windows many applications store their icon inside the executable file. So typing:
 wm iconbitmap . test.exe

will return an error. But if you type:
 wm iconbitmap . [wm iconbitmap .]

 wm iconbitmap . test.exe

 wm iconbitmap . [wm iconbitmap .]

 wm iconbitmap . -default test.exe

you'll see the icon of the executable.

Frank Keijzers

I am using Tcl/Tk statically compiled in a C/C++ program with MinGW for Microsoft Windows systems. I used windres within MinGW to compile the Windows resources. The above works for me, but I have to give some additional notes based on my own experience running my program on Windows XP.

The location of the executable needs to be defined when the program is started from another location then the directory where the executable is located in: (KD: [info nameofexecutable] will also do)
 set location [file join [getDirectoryOfInstalledExecutableForInstanceReadingTheRegistry] "test.exe"]
 wm iconbitmap . [wm iconbitmap .]
 wm iconbitmap . -default "$location"

I also experienced that the line
 wm iconbitmap . [wm iconbitmap .]

is not necessary for the icon to show up using merely the line
 wm iconbitmap . -default "$location"

This line above does throw the error 'bitmap $location not defined' but it does work correctly and it sets the icon for all windows of the application. Just put a catch around the line and it'll work fine (KD: this doesn't work for me). Another strange thing I noticed, using '-default' will make the icon disappear from the applications entry on the taskbar (KD: I don't have this problem).

To me, the ultimate solution to get the icon in every window of the application is to have these lines in every toplevel window:
 set location [file join [getDirectoryOfInstalledExecutableForInstanceReadingTheRegistry] "test.exe"]
 wm iconbitmap $localToplevel "$location"

In stead of using the binary 'test.exe' for the icon, you can also use an actual icon 'test.ico' file which will show up a better looking icon in the ALT-TAB taskwindow than using the binary as icon file. Using a binary as icon file has the advantage that it will force Windows to update the icon in desktop and menu links right away as it does not always using an icon actual file.

Ok, nuff said.


When I give a plain .ico file as argument to iconbitmap, it works as expected. When I use the following in wish:
 wm iconbitmap . -default [info nameofexecutable]

it also works as expected (the Tk icon is replaced by the Wish icon). However, when I use the line above in my own compiled Tk application, it gives an error. The reason is probably that Tk is not yet fully initialized when the iconbitmap command is issued. One (strange) workaround is indeed to use 2 iconbitmap commands:
 wm iconbitmap . ""
 wm iconbitmap . -default [info nameofexecutable]

Another workaround is to postpone the iconbitmap command using after. For some reason, I need a double after however:
 after idle {after 0 {wm iconbitmap . -default [info nameofexecutable]}}

See also edit