Author: Kevin Walzer <[email protected]> State: Final Type: Project Created: 21-August-2021 Keywords: Tk, desktop integration Tcl-Version: 8.7 Vote: Done Vote-Summary: Accepted 5/0/0 Votes-For: MC, SL, JN, FV, KW Votes-Against: none Votes-Present: none Keywords: Tk, desktop integration
A widely implemented UI element in desktop and mobile applications is an "icon badge," a small image laid over an application icon in a dock, panel or taskbar to indicate a change of state or provide notification of an update. The badge is typically removed when the application is brought into focus. A common example of this is a numeric image on an email program that indicates the number of new or unread messages. This TIP proposes to add a "wm iconbadge" command to Tk to provide this functionality.
Windows: ITaskbarList3 API https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-itaskbarlist3-setoverlayicon
X11: Custom implementation because Unix-like platforms do not have a standard, widely-used API
Mac: NSDockTile https://developer.apple.com/documentation/appkit/nsdocktile?language=objc
The X11 implementation will be based on the "wm iconphoto" command and incorporate additional custom badge images that will be shipped with Tk.
The Windows implementation will use the custom badge images developed for this TIP and render them via the native "ITaskbarList3::SetOverlayIcon" API.
The Mac version will be completely native and implement a Tk wrapper over the NSDockTile API.
The wm iconbadge command will present a script-level public API implementing the proposed interface, outlined below.
wm iconbadge window badge
This command sets an icon badge over a toplevel window icon as it appears in the Dock (macOS), taskbar (Windows) or application panel (X11). The "badge" argument is either a number to indicate a number of new messages or other data points, or an exclamation point to indicate a general call to attention. If the "badge" argument is set to an empty string, the badge icon is removed.
To set a badge icon with the number five over the application icon:
wm iconbadge . 5
To call for attention:
wm iconbadge . !
To remove the badge:
wm iconbadge . ""
On X11, variable ::tk::icons::base_icon($toplevelwindow) must be set to the base icon (that is: the icon without badge) before calling wm iconbadge. wm iconphoto $window ::tk::icons::base_icon($toplevelwindow) will get called under the hood.
A demonstration of this command in action has been added to the Tk widget demo under the "Miscellaneous" section, "Window icons and badges." Since the API is very simple, one can get a better understanding of the functionality by actually testing it in the demo.
Screenshot of the wm iconbadge on all three platforms:
See tk_badges branch.
This document has been placed in the public domain.