WinToast
v1.3.0
Wintoast est une bibliothèque légèrement écrite en C ++ qui apporte une intégration complète des notifications de toast modernes de Windows 8 , Windows 10 et Windows 11 .
Les notifications sur le toast permettent à votre application d'informer les utilisateurs des informations pertinentes et des événements opportuns qu'ils devraient voir et prendre des mesures dans votre application, comme un nouveau message instantané, une nouvelle demande d'ami, des nouvelles de rupture ou un événement de calendrier.
Wintoast intègre tous les modèles standard disponibles dans l'énumération ToastTemplateype.
| Modèle | Description | Exemple |
|---|---|---|
ImageAndText01 | Une grande image et une seule chaîne enveloppée sur trois lignes de texte. |  |
ImageAndText02 | Une grande image, une chaîne de texte en gras sur la première ligne, une chaîne de texte ordinaire enveloppé des deuxième et troisième lignes. |  |
ImageAndText03 | Une grande image, une chaîne de texte en gras enveloppé sur les deux premières lignes, une chaîne de texte ordinaire sur la troisième ligne. |  |
ImageAndText04 | Une grande image, une chaîne de texte en gras sur la première ligne, une chaîne de texte régulier sur la deuxième ligne, une chaîne de texte régulier sur la troisième ligne. |  |
Text01 | Une seule chaîne enveloppée sur trois lignes de texte. |  |
Text02 | Une chaîne de texte en gras sur la première ligne, une chaîne de texte régulier enveloppé sur les deuxième et troisième lignes. |  |
Text03 | Une chaîne de texte en gras enveloppé sur les deux premières lignes, une chaîne de texte régulier sur la troisième ligne. |  |
Text04 | Une chaîne de texte en gras sur la première ligne, une chaîne de texte régulier sur la deuxième ligne, une chaîne de texte régulier sur la troisième ligne. |  |
Exemple de modèle ImageAndText02 :
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " ); Remarque: L'utilisateur peut utiliser le son système par défaut ou spécifier un son à lire lorsqu'une notification de toast s'affiche. Même comportement pour l'image de notification de toast, par défaut, Windows essaie d'utiliser l'icône de l'application. *
Wintoast gère les différents événements:
Créez votre gestionnaire personnalisé pour interagir avec les actions de l'utilisateur en sous-classes l'interface IWinToastHandler :
class WinToastHandlerExample : public IWinToastHandler {
public:
WinToastHandlerExample ();
// Public interfaces
void toastActivated () const override ;
void toastActivated ( int actionIndex) const override ;
void toastDismissed (WinToastDismissalReason state) const override ;
void toastFailed () const override ;
};La documentation complète du contenu de notification ici.
Pour créer des notifications importantes, des alarmes, des rappels et des notifications d'appels entrantes, vous utilisez simplement une notification d'application normale avec une valeur de scénario qui lui est attribuée. Le scénario ajuste quelques comportements pour créer une expérience utilisateur cohérente et unifiée. Il y a quatre valeurs de scénario possibles:
Définissez le temps après quoi une notification de toast n'est plus considérée comme le courant ou le valide et ne doit pas être affichée. Windows tente de soulever des notifications de toast immédiatement après avoir appelé Show, de sorte que cette propriété est rarement utilisée.
Pour l'application Windows 8.x, cette propriété provoque également la suppression de la notification de toast du centre d'action une fois les données et le temps spécifiés atteints.
Remarque: le comportement de Windows par défaut est de masquer automatiquement la notification après le temps défini dans les paramètres de facilité d'accès Windows. Si vous devez préserver la notification dans Windows Action Center pendant une période plus longue, vous devez appeler WinToastTemplate::setExpiration Method.
Les directives de style Microsoft recommandent de représenter des images de profil avec une image circulaire pour fournir une représentation cohérente des personnes à travers les applications et le shell. Réglez la propriété Hintcrop sur cercle pour rendre l'image avec une culture circulaire.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Matt sent you a friend request " , WinToastTemplate::FirstLine);
templ.setTextField( L" Hey, wanna dress up as wizards and ride around on hoverboards? " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " );
templ.setHintCrop(WinToastTemplate::Circle);
L'image du héros est une grande image qui apparaît en haut d'une notification de toast. L'image du héros est facultative et peut être utilisée pour fournir un contexte supplémentaire à l'utilisateur.
Remarque: L'image du héros n'est pas prise en charge sur Windows 8.1 et Windows Phone 8.1.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
L'image du héros est spécifiée en appelant la méthode WinToastTemplate::setHeroImagePath . Le chemin d'image peut être un chemin de fichier local ou un URI.
Le deuxième paramètre de la méthode WinToastTemplate::setHeroImagePath est une valeur booléenne qui spécifie si l'image doit être inclinée dans la notification de toast.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" Feature image of the day " , WinToastTemplate::FirstLine);
templ.setHeroImagePath( L" C:/example.png " , true );
Vous pouvez ajouter vos propres actions, ce fait vous permet d'interagir avec l'utilisateur d'une manière différente:
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" New product in stock " , WinToastTemplate::FirstLine);
std::vector<std::wstring> actions;
actions.push_back( L" See more details " );
actions.push_back( L" Remind me later " );
// ...
for ( auto const &action : actions) {
templ. addAction (action);
}
WinToast::instance ()->showToast(templ, handler) 
Nouvelle mise à jour de l'anniversaire: si vous devez référencer la source de votre contenu, vous pouvez utiliser le texte d'attribution. Ce texte est toujours affiché sous tous les éléments de texte, mais au-dessus des images en ligne. Le texte utilise une taille légèrement plus petite que les éléments de texte standard pour aider à distinguer des éléments de texte réguliers.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::Text02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
templ.setAttributionText( L" Via SMS " );
La durée du toast doit afficher. Cet attribut peut avoir l'une des valeurs suivantes: - Système : configuration du système par défaut. - Court : configuration du système par défaut à court terme. - Long : configuration de longue date du système par défaut.
Vous pouvez modifier les différents comportements du son: - par défaut : joue le fichier audio une seule fois. - Silencieux : éteignez le son. - Loop : joue le son donné dans une boucle pendant l'existence de toast.
Wintoast permet la modification du fichier audio par défaut. Ajoutez le fichier donné dans vos ressources de projets ( doit être ms-appx: // ou ms-appdata: // chemin ) et définissez-le en appelant:
WinToastTemplate::setAudioPath
Par défaut, Wintoast vérifie si vos systèmes prennent en charge les fonctionnalités, ignorant les fonctionnalités non prises en charge.
Il y a plusieurs raisons pour lesquelles Wintoast peut échouer, c'est pourquoi la bibliothèque informe l'appelant de l'échec de la raison. Ce sont le code pour chaque échec:
| Wintoasterror | Code d'erreur | Message d'erreur |
|---|---|---|
NoError | 0x00 | Aucune erreur. Le processus a été exécuté correctement |
NotInitialized | 0x01 | La bibliothèque n'a pas été initialisée |
SystemNotSupported | 0x02 | Le système d'exploitation ne prend pas en charge Wintoast |
ShellLinkNotCreated | 0x03 | La bibliothèque n'a pas pu créer de lien de shell pour l'application |
InvalidAppUserModelID | 0x04 | L'Aumi n'est pas valide |
InvalidParameters | 0x05 | Les paramètres utilisés pour configurer la bibliothèque ne sont pas valables normalement parce qu'un Aumi ou un nom d'application non valide |
NotDisplayed | 0x06 | Le toast a été créé correctement mais Wintoast n'a pas pu afficher le toast |
UnknownError | 0x07 | Erreur inconnue |
Un exemple courant d'utilisation consiste à vérifier lors de l'initialisation de la bibliothèque ou de l'affichage d'une notification de toast le code d'échec possible:
WinToast::WinToastError error;
const auto succedded = WinToast::instance()-> initialize (&error);
if (!succedded) {
std::wcout << L" Error, could not initialize the lib. Error number: "
<< error << std::endl;
}
...
// Configure the template
...
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification. Error: "
<< error << std::endl;
}Pour une utilisation facile, vous pouvez simplement utiliser l'instance Singleton disponible.
Première étape, importez le fichier d'en-tête wintoastlib.h dans votre projet. Vous devez vérifier si votre version Windows est prise en charge par la bibliothèque.
using namespace WinToastLib ;
....
if (!WinToast::isCompatible()) {
std::wcout << L" Error, your system in not supported! " << std::endl;
}Configurez l'ID de modèle d'utilisateur de votre application, cela peut être fait en utilisant l'assistance existante:
WinToast::instance ()->setAppName( L" WinToastExample " );
const auto aumi = WinToast::configureAUMI( L" mohabouje " , L" wintoast " , L" wintoastexample " , L" 20161006 " );
WinToast::instance ()->setAppUserModelId(aumi); Initialisez toutes les dépendances et vérifiez si Wintoast a été initialisé avec succès dans votre système:
if (!WinToast::instance()-> initialize ()) {
std::wcout << L" Error, could not initialize the lib! " << std::endl;
} Implémentez votre propre gestionnaire d'action en sous-classant l'interface IWinToastHandler et personnalisez votre modèle:
WinToastHandlerExample* handler = new WinToastHandlerExample;
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setImagePath( L" C:/example.png " );
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);Affichez enfin les résultats:
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification! " << std::endl;
}Shao Voon Wong a écrit un excellent article sur l'utilisation de Wintoast. Vous pouvez le trouver ici.
Si vous utilisez un gestionnaire de packages, il existe un port pour VCPKG. Sinon, le moyen le plus simple est de copier les fichiers source en tant que dépendances externes.
Windows permet la configuration du comportement par défaut d'une notification de toast. Cela peut être fait dans la configuration de facilité d'accès en modifiant l'onglet Other Options .
La configuration du système vous aide à définir la durée des notifications à apparaître (5 secondes à 5 minutes) comme activant des notifications visuelles pour le son.
