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
Abstract
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.
Design
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.
Example
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:
https://imgur.com/gallery/mTqhgMl
Implementation
See tk_badges branch.
Copyright
This document has been placed in the public domain.