On the one hand, one has to understand that this is '''NOT''' possible to do successfully across all platforms and [window manager]s.

There are just too many variations.

However, here is something to attempt.  
Note that out of the box, Tk accepts only three image file formats - [GIF], [PGM], and [PPM].

If you want to use something other than that, take a look at [Img],
which adds additional photo image types.

----
 # Sample created by Larry W. Virden, with the kind assistance of
 #    Donal K. Fellows
 # Date: Nov 6, 2002

 package require Tcl
 package require Tk
 
 if { $argc != 1 } {
        puts stderr "$argv0 gif_pathname"
        exit
 }
 set icon_pathname [lindex $argv 0]
 
 set i [image create photo .i1 -format gif -file $icon_pathname ]
 
 set b [button .b1 -text hello]
 
 pack $b
 toplevel .icon;pack [label .icon.l -image $i]
 wm iconwindow . .icon
----
You may need to add the following to this code:

  wm withdraw .
  wm state . normal

to force the window manager to recognize the change in icon.

----
[Geoff Battye] mentions on [comp.lang.tcl] that the above code results in
a color icon showing up on the desktop with [window manager]s like fvwm
(and lv did the above work under cde).  
However, it didn't result in KDE showing a color icon in its title bar, 
alt-switching panel or its taskbar.  
So, [MGS] developed the code documented in [KDE window icons] to solve that need.

----
[GWM] the above code crashes tcl/tk8.4.11

However... from ask and it shall be given page:

[GWM] I have changed the icon on my toplevel window to an xbm file using
  wm iconbitmap . @folder.xbm
and the icon is restricted to the 2 colours used by the wish feather icon. How can I change the colours to red & green or some other horrible colour scheme?

[MG] If you're using Windows XP, you should be using a Windows .ico icon file, not a .xbm. Taking a Windows Bitmap and just renaming it from "foo.bmp" to "foo.ico" will usually (always?) give you a valid icon file, and the Img package can also write photo images in the ico format. There are also various free programs mentioned on the Wiki (though I don't have links to hand) which can create icons in many different sizes/color depths/etc. A Wiki search for "Windows Icons" will probably find some of those.

[GWM] Thanks - you don't need the @ needed for xbm:

 wm iconbitmap . /tcl/examples/tk8.4.5/win/rc/wish.ico
works nicely if you have the examples installed.

----
See also:

   * [wm iconwindow]
   * http://www.equi4.com/267 - "Custom icons for Win32 starpacks"
   * [Custom Icons For Win32 Starpacks - The Real Story]

----
[[
[Category Graphics] |
[GSoC2007 Tcl/Tk Application] |
[Category Porting]
]]