ico(3tk)

📦
version 0.9 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 ico — bestie, we're doing Windows icons today 💖

okay so before we even start: this is ico(3tk), the page all about Windows ICO handling. it lives in the tklib crew and we're on version 1.1.3. buckle up, we're reading AND writing icons. no cap. 🎀

✨ NAME ✨

ico — reading and writing windows icons 💅

🌸 SYNOPSIS 🌸

package require Tcl 8.4

package require ico ?1.1.3?

::ico::icons file ?option value...?

::ico::iconMembers file name ?option value...?

::ico::getIcon file name ?option value...?

::ico::getIconByName file name ?option value...?

::ico::getFileIcon file ?option value...?

::ico::writeIcon file name depth data ?option value...?

::ico::copyIcon file index file2 index2 ?option value...?

::ico::EXEtoICO file ?dir?

::ico::clearCache ?file?

::ico::transparentColor image color

::ico::Show file ?option value...?

🦋 DESCRIPTION 🦋

bestie. this package hands you the whole toolkit for reading and writing Windows icons out of ICO, EXE, DLL, ICL, and BMP files. ✨

and like, what even is an icon here? an icon is a visual representation of an object. that's the vibe. an icon is made of one or more images, usually at different resolutions and color depths, because one size does NOT fit all and she contains multitudes. 💅

every icon and every image has a resource identifier, which can be either a text string or a positive integer. most of these commands want that identifier so they know which icon or image you're talking about. iykyk. 👑

🎀 API 🎀

::ico::icons file ?option value...?

gives you back a list of all the icons hanging out in file, where each element is the name or numeric ID. she recognizes these options:

  • -type fileFormat

::ico::iconMembers file name ?option value...?

gives you a list of all the images that make up the icon with ID name. each element is itself a sublist shaped like {name width height bpp}. she recognizes:

  • -type fileFormat

::ico::getIcon file name ?option value...?

pulls the icon with ID name out of file. 🫶

the default -format is image, which returns the name of a Tk image holding the icon. the resolution and color depth get picked with the ?-res?, ?-bpp?, and ?-exact? options. if -exact is specified and there's no exact match, an error is thrown. you can also optionally use -image to name the Tk image being created.

if -format is colors then you get back a list of color names in the #RRGGBB format. each list element is a horizontal row, and each row is itself a list of colors for every pixel in that row, left to right. 🌈

if -format is name then you get back the resource name of the image chosen. this is the one you want when you're gonna call writeIcon or getIconByName later. she recognizes these options:

  • -type fileFormat
  • -format value
  • -image value
  • -res value
  • -bpp value
  • -exact value

::ico::getIconByName file name ?option value...?

pulls the image with ID name out of file. heads up bestie: this name has to be the name of a specific image like the ones ::ico::iconMembers returns — NOT an icon name like the ones ::ico::icons returns. they are not the same thing and confusing them is a whole situation. 😭

if there's no matching resource ID in file, an error is thrown. she recognizes:

  • -type fileFormat
  • -format value

::ico::getFileIcon file ?option value...?

⚠️ this one only works when you're running under Windows. it reads the Windows registry to figure out the display icon for file exactly how it would show up in Explorer or similar. file does not need to exist, and you can also pass it as a file extension with a leading dot. if file is a directory, or you pass the special name Folder, you get the icon that represents a folder. 🍓

this command takes the same arguments and usage as getIcon:

  • -format value
  • -image value
  • -res value
  • -bpp value
  • -exact value

::ico::writeIcon file name depth data ?option value...?

writes an image to file. name is the resource identifier of the image in file you're writing. ✍️

when writing to an EXE, DLL, or ICL file you may only overwrite existing icons with an icon of the same dimensions and color depth. no icons may be added to these file types. periodt.

when writing to BMP, the name is ignored since this type can only hold one image. which means if the file already existed, it gets completely overwritten. bye bestie. 💀

when writing to an ICO or ICODATA file, if the name you specified doesn't exist yet then an image is appended and gets named the next one in sequence (so your specified name is ignored). images in ICO and ICODATA files may be overwritten with differing dimensions or color depths. but ⚠️ note that you'll get strange results when displaying icons if you fail to change every image that makes up a given icon. every single one, bestie. no skipping.

integer depth (in) this argument must have a value of 1, 4, 8, 24, or 32. if data has more colors than the color depth allows, an error will be generated.

options data (in) this argument is either a list of colors in the format returned by ::ico::getIcon -format colors, or the name of a Tk image.

she recognizes these options:

  • -type fileFormat

::ico::copyIcon file index file2 index2 ?option value...?

copies the icon at index in file over to index2 in file2. 🦋

  • -fromtype fileFormat
  • -totype fileFormat

::ico::EXEtoICO file ?dir?

extracts all the icons from the executable file into ICO files placed in dir. if you don't pass dir, it defaults to the directory file lives in. the icon files get named in the form file-ID.ico, where ID is the icon resource identifier. ✨

  • -type fileFormat

::ico::clearCache ?file?

so the ::ico::getIconList command caches icon offsets inside EXE, DLL, ICL, and ICO files to make extraction faster. 🏃‍♀️ this command wipes that cache — either for a specific file, or for all files if you don't pass one.

::ico::transparentColor image color

if image is a single word, it's assumed to be the name of a Tk image. all pixels in the image matching color get set to transparent. alternatively, image may be a color list, in which case a modified list gets returned instead. 🫧

::ico::Show file ?option value...?

application-level command that pops open a window showing all the icons in file and their names. main character window energy, honestly. 👑

  • -type fileFormat
  • -parent pathName

🌟 EXAMPLE 🌟

button .explore -image [::ico::getIcon explorer.exe 0 -name explore -res 16 -bpp 8]

set i [lsearch -inline [::ico::iconMembers tclkit.exe 0] {* 32 32 8}]
set colorlist [::ico::getIconByName tclkit.exe [lindex $i 0] -format colors]

😭 LIMITATIONS 😭

  • icons may not be added or removed from file types other than ICO. icons in those files may only be replaced with icons of the same dimensions and color depth.
  • icons of 8bpp or lower must include black in the pallete. this means if your icon doesn't have black in it, you'll need to leave a color free so it can be included by writeIcon.
  • there is currently no way to read alpha channel information from 32bpp icons.
  • Tk images don't have an alpha channel, so the only way to write a true 32bpp icon is from a color list. writing a 32bpp icon from a Tk image is identical to writing a 24bpp icon. 💀

🫶 BUGS, IDEAS, FEEDBACK 🫶

this document, and the package it describes, will undoubtedly contain bugs and other problems. please report them in the category ico of the Tklib Trackers at [http://core.tcl.tk/tklib/reportlist]. also please report any ideas for enhancements you may have for either the package and/or the documentation — we want all of it. 🎀

💜 KEYWORDS 💜

dll, entry, exe, ico, icon

and that's the whole page, bestie!! 🎉 this was tklib version 1.1.3, the ico(3tk) page, and honestly? she ate. go forth and icon responsibly. 💅✨🌸

📦 where this page comes from