Launcher (Windows)

Le module launcher-windows expose quatre parties du shell Windows depuis Kotlin : les icônes de superposition sur le bouton de la barre des tâches, les jump lists dans son menu contextuel, les boutons de la miniature de la barre des tâches, ainsi que les badges numériques ou glyphes. Chaque partie est un object distinct que vous appelez directement ; n'utilisez que celles dont vous avez besoin.

Ajouter la dépendance

dependencies {
    implementation("dev.nucleusframework:nucleus.launcher-windows:2.0.7")
}

Poser une icône de superposition

Une icône de superposition est un repère d'état de 16x16 dans le coin inférieur droit du bouton de la barre des tâches. Passez la Window AWT et une source d'icône :

import dev.nucleusframework.launcher.windows.StockIcon
import dev.nucleusframework.launcher.windows.TaskbarIconSource
import dev.nucleusframework.launcher.windows.WindowsOverlayIcon

WindowsOverlayIcon.setIcon(
    window,
    TaskbarIconSource.FromStock(StockIcon.WARNING),
    description = "1 message non lu",
)

// plus tard
WindowsOverlayIcon.clearIcon(window)

Les icônes de superposition fonctionnent avec tous les formats de packaging. Chaque appel renvoie true en cas de succès ; vérifiez d'abord WindowsOverlayIcon.isAvailable si vous supportez des plateformes autres que Windows.

Construire une jump list

Une jump list regroupe des éléments dans le menu contextuel de la barre des tâches. setJumpList remplace la liste entière de façon atomique :

import dev.nucleusframework.launcher.windows.JumpListCategory
import dev.nucleusframework.launcher.windows.JumpListItem
import dev.nucleusframework.launcher.windows.WindowsJumpListManager

WindowsJumpListManager.setJumpList(
    categories = listOf(
        JumpListCategory("Récents", items = listOf(
            JumpListItem("Projet A", arguments = "myapp://open?project=a"),
            JumpListItem("Projet B", arguments = "myapp://open?project=b"),
        )),
    ),
    tasks = listOf(
        JumpListItem("Nouvelle fenêtre", arguments = "myapp://new"),
        JumpListItem.SEPARATOR,
        JumpListItem("Préférences", arguments = "myapp://settings"),
    ),
)

Pour les apps non packagées (NSIS, MSI, distributable), appelez WindowsJumpListManager.setProcessAppId() une seule fois tout au début de main(), avant qu'aucune fenêtre ne soit créée. Les apps APPX/MSIX s'en passent : Windows utilise l'identité du package.

Ajouter des boutons de miniature

La barre d'outils de la miniature ajoute jusqu'à 7 boutons cliquables à l'aperçu de la miniature de la barre des tâches. Enregistrez-les une fois par fenêtre avec setButtons :

import dev.nucleusframework.launcher.windows.TaskbarIconSource
import dev.nucleusframework.launcher.windows.ThumbnailToolbarButton
import dev.nucleusframework.launcher.windows.WindowsThumbnailToolbar

WindowsThumbnailToolbar.setButtons(
    window,
    buttons = listOf(
        ThumbnailToolbarButton(id = 0, tooltip = "Précédent", icon = TaskbarIconSource.FromFile("icons/prev.ico")),
        ThumbnailToolbarButton(id = 1, tooltip = "Lecture",   icon = TaskbarIconSource.FromFile("icons/play.ico")),
        ThumbnailToolbarButton(id = 2, tooltip = "Suivant",   icon = TaskbarIconSource.FromFile("icons/next.ico")),
    ),
    onClick = { buttonId -> handleTransport(buttonId) },
)

Windows n'autorise pas l'ajout de boutons après le premier enregistrement. Pour modifier plus tard l'icône, l'infobulle ou l'état d'un bouton, appelez updateButtons(window, buttons) avec les mêmes id. Appelez unregister(window) à la fermeture de la fenêtre.

Afficher un badge

Les badges affichent un compte numérique ou un glyphe d'état sur le bouton de la barre des tâches et la tuile du menu Démarrer. Ils reposent sur un Application User Model ID que Windows n'accorde qu'aux apps packagées, donc l'API de badge ne fonctionne que sous APPX/MSIX. Appelez initialize() une fois avant de poser un badge :

import dev.nucleusframework.launcher.windows.BadgeGlyph
import dev.nucleusframework.launcher.windows.WindowsBadgeManager

WindowsBadgeManager.initialize()

WindowsBadgeManager.setGlyph(BadgeGlyph.NEW_MESSAGE)
// ou un compte numérique
WindowsBadgeManager.setCount(5)

// effacer
WindowsBadgeManager.clear()

setCount affiche 1 à 99 sous forme de nombre et 99+ au-delà ; setCount(0) l'efface. Appelez uninitialize() à l'arrêt.

Fonctionnement

Les icônes de superposition et la barre d'outils de miniature utilisent l'interface COM ITaskbarList3, indexée par le HWND de votre java.awt.Window. COM est initialisé paresseusement au premier appel, et les clics sur les boutons de miniature arrivent sur l'AWT event dispatch thread.

Les jump lists utilisent ICustomDestinationList. Windows possède le menu, donc les clics n'atteignent jamais votre processus en cours : l'OS démarre un nouvel exécutable avec les arguments de l'élément ajoutés à la ligne de commande. C'est pourquoi les actions de jump list transportent leurs données via arguments plutôt que par un callback.

Les badges utilisent WinRT et exigent un AUMID. Windows n'en accorde qu'aux apps packagées, donc WindowsBadgeManager se déclare indisponible en dehors d'APPX/MSIX. L'AUMID est dérivé de NucleusApp.aumid, sauf si vous passez une valeur explicite à initialize.

Référence de l'API

Icône de superposition

Jump list

Types associés :

Barre d'outils de miniature

ThumbnailToolbarButton(id, tooltip, icon, enabled, hidden, noBackground, dismissOnClick, nonInteractive) — id doit être compris entre 0 et 6, tooltip fait au plus 259 caractères. Le handler onClick est un ThumbBarClickListener qui reçoit l'id du bouton cliqué.

Badge

Valeurs de BadgeGlyph : NONE, ACTIVITY, ALARM, ALERT, ATTENTION, AVAILABLE, AWAY, BUSY, ERROR, NEW_MESSAGE, PAUSED, PLAYING, UNAVAILABLE.

Sources d'icône

Toute API qui prend une icône accepte un TaskbarIconSource :

• TaskbarIconSource.FromStock(stockIcon) — l'une des 93 valeurs de StockIcon (WARNING, ERROR, INFO, SHIELD, FOLDER, ...). Aucun fichier requis.
• TaskbarIconSource.FromFile(path) — un fichier .ico sur disque.
• TaskbarIconSource.FromResource(dllPath, index) — un index d'icône dans une DLL de ressources comme shell32.dll ou imageres.dll.

Notes

• Les éléments de jump list ont besoin d'un vrai exécutable. Ils ne se déclenchent pas sous ./gradlew run, où le processus est java.exe — testez depuis runDistributable ou un build packagé.
• Pour une barre de progression dans le bouton de la barre des tâches lui-même, plutôt qu'une icône de superposition, utilisez taskbar-progress.

Et ensuite

• Launcher (macOS) — l'équivalent du menu du dock sur macOS.
• Launcher (Linux) — entrées de launcher et quicklists sur Linux.
• Taskbar progress — barres de progression dans le bouton de la barre des tâches.
• Single instance — transférer les arguments de jump list vers une app déjà lancée.