Taskbar progress, buttons and jump list
Show progress on the taskbar icon, add buttons under its Windows preview and offer actions on the icon's right-click menu.
Available since 0.4.1. Your app's icon in the taskbar (Windows) or launcher (Linux) can do more than start the app. It can show progress, offer buttons under its preview, and list actions when the user right-clicks it. These features need no window to come to the front, which is what makes them useful for background work. This page goes from the simplest, a progress bar, to the one that needs the most setup, the jump list.
Not every feature exists everywhere. Each section says what happens on each system, and the supports...() methods tell you at run time:
| Feature | Windows | Linux | Check |
|---|---|---|---|
| Progress on the icon | Yes | Best effort | window.supportsTaskbarProgress() |
| Buttons in the preview | Yes | No | window.supportsTaskbarButtons() |
| Jump list / icon menu | Tasks and categories | Tasks, best effort | app.supportsJumpList() |
When a feature is not supported the call does nothing, so you can call it without checking. Check only if your UI would otherwise promise something that cannot happen.
1. Progress on the taskbar icon
A bar along the icon shows an export, download or upload, so the user can follow it while working in another window.
window.setTaskbarProgress(TaskbarProgress.normal(done / (double) total)); // green bar, 0 to 1
window.setTaskbarProgress(TaskbarProgress.indeterminate()); // length unknown: a moving marquee
window.setTaskbarProgress(TaskbarProgress.paused(0.6)); // yellow: waiting for the user
window.setTaskbarProgress(TaskbarProgress.error(0.6)); // red: it failed
window.setTaskbarProgress(TaskbarProgress.none()); // finished: clear it- Call it from any thread, with each step, and clear it with
none()when the work ends or the bar stays. - The value is kept: you can set it before the window is shown, and it is drawn once the window has a taskbar button. It is drawn again if Explorer restarts.
- On Linux it is best effort. Jolt sends the Unity launcher signal
com.canonical.Unity.LauncherEntry, which KDE Plasma's task manager, Ubuntu's dock and Dash to Dock or Dash to Panel draw. Plain GNOME Shell, XFCE and most others ignore it. The desktop finds your icon through an installed<appId>.desktopfile, so an app run from a bare jar shows nothing. Linux has one bar per application, and red and yellow look like a normal bar.
2. Buttons in the taskbar preview (Windows)
When the pointer rests on the taskbar icon, Windows shows a preview of the window. Under it your app can show up to 7 buttons, the strip chat apps use for mute and leave call. The user acts without opening the window.
window.setTaskbarButtons(List.of(
TaskbarButton.of("Mute", muteIcon, () -> toggleMute()), // icon: PNG or ICO bytes, about 16 px
TaskbarButton.of("Leave call", hangupIcon, () -> leave()).withEnabled(inCall)));- Each button has a tooltip (up to 259 characters), an icon, an enabled state and a callback on the UI thread.
withDismissOnClick(true)closes the preview after the press. - Windows lets a program add the buttons only once. The number is fixed by the first call that has any. Later calls update icons, tooltips and enabled state and may give fewer buttons (the rest are hidden), but giving more throws
IllegalArgumentException. So plan the maximum up front. - Call it again whenever state changes: swap the mute icon when muted, disable "Leave call" when the call ends.
- The buttons appear once the window has been shown, and are added again if Explorer restarts.
- On other systems
supportsTaskbarButtons()isfalseand the call does nothing. Offer the same actions inside your window or in the tray menu too.
3. Actions on the icon's menu
Right-click the icon and the menu can offer tasks such as "New incognito window", and on Windows your own categories such as "Recent projects". This is the Windows jump list, and on Linux it becomes the launcher's desktop actions.
app.setJumpList(JumpList.builder()
.task("New incognito window", "--incognito") // starts the program with these arguments
.task(JumpItem.of("Settings", "--settings").withDescription("Open the settings"))
.category("Recent projects", List.of( // Windows only
JumpItem.of("Parsel", "--open", "42"),
JumpItem.of("Notes", "--open", "7")))
.build());
app.setJumpList(JumpList.empty()); // remove them again- Choosing an entry starts the program again with its arguments. A second copy is not what you want, so receive them in the running copy with
SingleInstance, as shown in Custom links. The new launch hands its arguments over and exits. - Call
setJumpListagain whenever the entries change, for example when the list of recent projects does. - An entry has a title (up to 200 characters, one line), its arguments, and optionally a tooltip and an icon (Windows). A list holds at most 60 entries.
On Windows
- From the first call on, the windows carry
AppOptions.appIdas their AppUserModelID. That puts the list on your application's icon and not on the icon ofjavaw.exe. An id with spaces or over 128 characters gets no list. - Categories are hidden if the user turned off "Show recently opened items" in Settings. Tasks always show.
- The command that starts the program is the process's own. For a plain Java launch Jolt rebuilds it as
-jar app.jar(or-cp ... Main); JVM options are not carried over, so putEnable-Native-Access: ALL-UNNAMEDin your jar's manifest. To control it, pass your own withbuilder().command(List.of(...)).
On Linux
- Tasks are written as freedesktop desktop actions into
~/.local/share/applications/<appId>.desktop. GNOME and KDE show them on the launcher icon when the running window is matched to that file. - Categories and icons are not used. A
.desktopfile of your own at that place is never changed. - Treat it as best effort, and make sure every task is also reachable inside the app.
4. Putting it together
A file exporter that keeps working while the window is in the background:
void export(List<Path> files) {
Thread.startVirtualThread(() -> {
for (int i = 0; i < files.size(); i++) {
convert(files.get(i));
window.setTaskbarProgress(TaskbarProgress.normal((i + 1) / (double) files.size()));
}
window.setTaskbarProgress(TaskbarProgress.none());
app.notify(Notification.of("Export finished", files.size() + " files are ready")
.withOnClick(window::focus));
});
}The bar follows the work, and when it ends a notification brings the user back. Failure is the same with TaskbarProgress.error(...).