class Taskbar extends Object
The badge and progress bar a desktop shell draws on a taskbar button.
Called on the class, it decorates the application's own button, with the same result on every platform:
Taskbar.SetProgress(40)
This is one application-wide setting: each call replaces the last on every window, including windows opened afterwards, so it can be set before any window exists. A per-window call overrides it for that window until the next application-wide one.
Constructed with a window handle, it decorates that one window's button — a distinction only Windows makes, see IsPerWindow:
Taskbar(MyGui.Hwnd).SetProgress(40)
The button's own icon is the window's icon, set with Gui.SetIcon or TraySetIcon.
The class is exported by the KS module:
#Import "Ks" { Taskbar }
Constructs a Taskbar for the window with the given handle, this script's own or any other's.
TaskbarObj := Taskbar(Hwnd)
Type: Integer
The window handle whose taskbar button is decorated. A handle of 0 raises a ValueError.
The decoration belongs to the window, not to the Taskbar object, and remains until it is removed or the window is destroyed.
Draws a badge over the window's taskbar button.
TaskbarObj.SetBadge(Source, IconNumber, Text) Taskbar.SetBadge(Source, IconNumber, Text)
Type: String
If omitted or blank, the badge is removed. Otherwise the path to an icon or image file, a module holding icon resources such as "shell32.dll", or a handle such as "HICON:" handle. Platforms which cannot draw an icon badge ignore this and show Text instead; see IsBadgeIconSupported.
Type: Integer
If omitted, it defaults to 1 (the first icon group in the file). If negative, the absolute value is assumed to be the resource ID of an icon within an executable file, as in Gui.SetIcon.
Type: String
What the badge means, which Windows exposes to a screen reader. On Linux and macOS this is what the badge shows: a number on Linux (text which is not a number shows as 1), a short string on macOS.
Fills the window's taskbar button with a progress bar.
TaskbarObj.SetProgress(Value, Maximum) Taskbar.SetProgress(Value, Maximum)
Type: Integer
If omitted or blank, the bar is removed. Otherwise how far along the work is, from 0 through Maximum. A value outside that range throws a ValueError.
Type: Integer
If omitted, it defaults to 100, so Value reads as a percentage. Zero or less removes the bar, as a blank Value does.
Sets the kind of progress the bar shows, which is what makes it amber, red or a marquee.
TaskbarObj.SetProgressState(State) Taskbar.SetProgressState(State)
Type: String
One of the following, matched without regard to case. Anything else raises a ValueError.
| State | Meaning |
|---|---|
| None | Removes the bar. |
| Normal | An ordinary bar, green on Windows. |
| Indeterminate | A marquee; the value is ignored. |
| Paused | Amber on Windows. |
| Error | Red on Windows. |
Whether this platform can draw an icon as the badge.
Boolean := Taskbar.IsBadgeIconSupported
False on Linux and macOS.
Whether the badge and progress belong to one window.
Boolean := Taskbar.IsPerWindow
False on Linux and macOS, where they decorate the whole application, so two windows setting them there overwrite one another.
Only Windows has all of this.
| Platform | Badge | Progress | Scope |
|---|---|---|---|
| Windows | The icon, drawn over the button | A bar inside the button, in the colour the state names | One window |
| Linux | Text read as a number | A fraction on the launcher icon; Error also raises the urgent hint | The whole application |
| macOS | Text as dock tile badge text | A bar drawn on the dock tile | The whole application |
Note: On macOS, the dock icon bounces when progress completes or fails, until the application is activated.
Linux uses the Unity LauncherEntry protocol, which carries a number and a progress fraction rather than an icon. Plasma's task manager, Ubuntu Dock, Dash to Dock, Plank and Latte consume it directly. The keysharp-desktop extension maps the same signal onto GNOME's stock overview dash and Cinnamon's grouped-window-list. A shell or dock which does not implement it ignores the request silently.
The launcher icon a Linux shell decorates is selected by the DESKTOP_ENTRY environment variable, then #App DesktopEntry, then Keysharp's own entry. An application which installs its own .desktop file should normally declare the same name in its script:
#App { DesktopEntry: "com.acme.MyApp" }
The suffix is optional. The selected name also becomes each Wayland window's application ID, so the window, installed icon and Taskbar state use one identity. A launcher or packager may instead set DESKTOP_ENTRY; that override must exist before the first window is shown and the first Taskbar call.
Reports the progress of a long job on the taskbar, and badges the button while the work runs.
#Import "Ks" { Taskbar }
MyGui := Gui(, "Downloading")
MyGui.Show("w300 h100")
Taskbar.SetBadge("shell32.dll", 46, "Downloading")
Loop 100
{
Taskbar.SetProgress(A_Index)
Sleep 30
}
Taskbar.SetProgress("") ; Remove the bar.
Taskbar.SetBadge("") ; Remove the badge.
Turns the bar red when the work fails.
#Import "Ks" { Taskbar }
MyGui := Gui()
MyGui.Show()
try
Download("https://example.com/missing.zip", A_Temp "\missing.zip")
catch
{
Taskbar.SetProgress(100)
Taskbar.SetProgressState("Error")
}
Badges a window belonging to another process.
#Import "Ks" { Taskbar }
Taskbar(WinExist("ahk_exe notepad.exe")).SetBadge("shell32.dll", 174, "Watched")