Author: Kevin Walzer 
State: Final
Type: Project 
Tcl-Version: 9.1 
Created: 2025-12-13
Vote: Done
Vote-Summary:       Accepted 5/0/0
  Votes-For:          AN, JN, HO, KW, SL 
  Votes-Against:      none
  Votes-Present:      none

Abstract

This TIP proposes to add the tk fileicon command, which will display platform-native file icons on Window, X11 and macOS.

Rationale

Similar to using platform-native dialogs where available, using native file icons as images when displaying file data will enhance Tk's integration with that system, providing a smoother user experience.

Platform Notes

The tk fileicon command uses the following implementations:

X11: Linux/Unix do not provide a native API for accessing file images/icons, but we are including icons from the Tango project, which has been the longtime default icon theme for the Gnome desktop. Additionally, the base icons are public-domain, so there are no licensing issues to address.
Windows: This TIP adapts code initially developed by Mark Janssen and posted to the Tcl wiki and later updated for Tk 9 by Paul Obermeier. This code utilizes the Windows shell API to retrieve native icons.
macOS: The command wraps the nsimage command added by Marc Culler in TIP 639.

Specification

tk fileicon file size

The command takes an absolute file path as an argument, and size as the second parameter. On Windows, the size will be mapped to the closest of 16, 32, 48 or 256 pixels wide; on Linux and macOS, any size can be supported.

Testing

The code is demonstrated in the "simple image viewer" and "simple file browser" modules of the widget demo. The function has also been added to the Tk test suite for compatibility.

Reference Implementation

This TIP is implemented in the file_icons branch of the Tk fossil repository.

Copyright

This document has been placed in the public domain.