{"id":13730908,"url":"https://github.com/mohabouje/WinToast","last_synced_at":"2025-05-08T03:32:16.563Z","repository":{"id":37733157,"uuid":"69401773","full_name":"mohabouje/WinToast","owner":"mohabouje","description":"WinToast is a lightly library written in C++ which brings a complete integration of the modern toast notifications of Windows 8 \u0026 Windows 10.  Toast notifications allows your app to inform the users about relevant information and timely events that they should see and take action upon inside your app, such as a new instant message, a new friend request, breaking news, or a calendar event.","archived":false,"fork":false,"pushed_at":"2024-06-19T11:13:39.000Z","size":19461,"stargazers_count":705,"open_issues_count":23,"forks_count":130,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-11-11T21:38:34.935Z","etag":null,"topics":["event-handlers","modern-features","notifications","toast-notifications","toast-templates","windows","windows-10","windows-uwp"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mohabouje.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"mohabouje","custom":"https://paypal.me/mohabouje"}},"created_at":"2016-09-27T21:51:32.000Z","updated_at":"2024-11-10T06:07:24.000Z","dependencies_parsed_at":"2024-09-18T20:00:50.785Z","dependency_job_id":"f40b0c4c-6521-4153-a44c-24d18017dcd6","html_url":"https://github.com/mohabouje/WinToast","commit_stats":{"total_commits":253,"total_committers":22,"mean_commits":11.5,"dds":"0.31225296442687744","last_synced_commit":"a78ce469b456c06103b3b30d4bd37e7bb80da30c"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohabouje%2FWinToast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohabouje%2FWinToast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohabouje%2FWinToast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohabouje%2FWinToast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mohabouje","download_url":"https://codeload.github.com/mohabouje/WinToast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224695794,"owners_count":17354482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-handlers","modern-features","notifications","toast-notifications","toast-templates","windows","windows-10","windows-uwp"],"created_at":"2024-08-03T02:01:21.270Z","updated_at":"2025-05-08T03:32:16.536Z","avatar_url":"https://github.com/mohabouje.png","language":"C++","readme":"![license](https://img.shields.io/github/license/mohabouje/WinToast?style=flat-square)\n![GitHub contributors](https://img.shields.io/github/contributors/mohabouje/WinToast?style=flat-square)\n![releases](https://img.shields.io/github/v/release/mohabouje/WinToast?style=flat-square)\n[![GitHub stars](https://img.shields.io/github/stars/mohabouje/WinToast?style=flat-square)]()\n[![GitHub forks](https://img.shields.io/github/forks/mohabouje/WinToast?style=flat-square)]()\n[![GitHub watchers](https://img.shields.io/github/watchers/mohabouje/WinToast?style=flat-square)]()\n![issues](https://img.shields.io/github/issues/mohabouje/WinToast?style=flat-square)\n\n\nWinToast\n===================\n\nWinToast is a lightly library written in C++ which brings a complete integration of the modern **toast notifications** of **Windows 8**,   **Windows 10** and **Windows 11**. \n\nToast notifications allows your app to inform the users about relevant information and timely events that they should see and take action upon inside your app, such as a new instant message, a new friend request, breaking news, or a calendar event. \n\n- [WinToast](#wintoast)\n- [Toast Templates](#toast-templates)\n- [Event Handler](#event-handler)\n- [Notification Content](#notification-content)\n- [Error Handling](#error-handling)\n- [Example of Usage](#example-of-usage)\n- [Installation](#installation)\n- [Toast configuration on Windows 10](#toast-configuration-on-windows-10)\n- [Projects using WinToast](#projects-using-wintoast)\n\n\n## Toast Templates\n\nWinToast integrates all standard templates available in the [ToastTemplateType enumeration](https://msdn.microsoft.com/en-us/library/windows/apps/br208660.aspx).\n\n| Template     | Description | Example   |\n| :------- | ----: | :---: |\n| `ImageAndText01` | A large image and a single string wrapped across three lines of text. |  ![enter image description here](assets/images/Toast_6.png)   |\n| `ImageAndText02`   | A large image, one string of bold text on the first line, one string of regular text wrapped across the second and third lines.   |  ![12](assets/images/Toast_7.png)   |\n| `ImageAndText03` | A large image, one string of bold text wrapped across the first two lines, one string of regular text on the third line. | ![enter image description here](assets/images/Toast_8.png) |\n| `ImageAndText04` |    A large image, one string of bold text on the first line, one string of regular text on the second line, one string of regular text on the third line.     | ![enter image description here](assets/images/ToastImageAndText04.png)  |\n| `Text01` | Single string wrapped across three lines of text. | ![enter image description here](assets/images/Toast_1.png)|\n| `Text02`  | One string of bold text on the first line, one string of regular text wrapped across the second and third lines.   |  ![enter image description here](assets/images/Toast_2.png) |\n| `Text03` | One string of bold text wrapped across the first two lines, one string of regular text on the third line. | ![enter image description here](assets/images/Toast_4.png)|\n| `Text04` |   One string of bold text on the first line, one string of regular text on the second line, one string of regular text on the third line.     | ![enter image description here](assets/images/Toast_5.png) |\n\nExample of a `ImageAndText02` template:\n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);\ntempl.setTextField(L\"title\", WinToastTemplate::FirstLine);\ntempl.setTextField(L\"subtitle\", WinToastTemplate::SecondLine);\ntempl.setImagePath(L\"C:/example.png\"); \n```\n**Note:** The user can use the default system sound or specify a sound to play when a toast notification is displayed. Same behavior for the toast notification image, by default Windows try to use the app icon.*\n\n\n## Event Handler\n\nWinToast handle different events:\n\n - **Activated**: Occurs when user activates a toast notification through a click or touch. Apps that are running subscribe to this event\n - **Dismissed**: Occurs when a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user. \n\t* Application Hidden:  The application hid the toast using ToastNotifier.hide.\n\t* User Canceled: The user dismissed the toast.\n\t* Timed Out: The toast has expired\n - **Failed**: Occurs when an error is caused when Windows attempts to raise a toast notification.\n\nCreate your custom handler to interact with the user actions by subclassing the interface `IWinToastHandler`:\n\n```cpp\nclass WinToastHandlerExample : public IWinToastHandler {\n public:\n\tWinToastHandlerExample(); \n\t// Public interfaces\n\tvoid toastActivated() const override;\n\tvoid toastActivated(int actionIndex) const override;\n\tvoid toastDismissed(WinToastDismissalReason state) const override;\n\tvoid toastFailed() const override;\n };\n```\n\n## Notification Content\n\nThe full documentation of the notification content [here](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/adaptive-interactive-toasts?tabs=appsdk).\n\n### Scenario\n\nTo create important notifications, alarms, reminders, and incoming call notifications, you simply use a normal app notification with a Scenario value assigned to it. The scenario adjusts a few behaviors to create a consistent and unified user experience. There are four possible Scenario values:\n\n- Reminder\n- Alarm\n- IncomingCall\n- Urgent\n\n### Expiration Time\n\nSet the time after which a toast notification is no longer considered current or valid and should not be displayed. Windows attempts to raise toast notifications immediately after you call Show, so this property is rarely used. \n\n\u003e For Windows 8.x app, this property also causes the toast notification to be removed from the\n\u003e Action Center once the specified data and time is reached.\n\n**Note:** Default Windows behavior is to hide notification automatically after time set in Windows Ease of Access Settings.\nIf you need to preserve notification in Windows Action Center for longer period of time, you have to call `WinToastTemplate::setExpiration` method. \n\n### Hint Crop\n\nMicrosoft style guidelines recommend representing profile pictures with a circular image to provide a consistent representation of people across apps and the shell. Set the HintCrop property to Circle to render the image with a circular crop.\n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);\ntempl.setTextField(L\"Matt sent you a friend request\", WinToastTemplate::FirstLine);\ntempl.setTextField(L\"Hey, wanna dress up as wizards and ride around on hoverboards?\", WinToastTemplate::SecondLine);\ntempl.setImagePath(L\"C:/example.png\");\ntempl.setHintCrop(WinToastTemplate::Circle);\n```\n\n![\"Toast with hero image\"](assets/images/hint-crop.png)\n\n\n### Hero Image\n\nThe hero image is a large image that appears at the top of a toast notification. The hero image is optional and can be used to provide additional context to the user.\n\n**Note:** The hero image is not supported on Windows 8.1 and Windows Phone 8.1.\n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);\ntempl.setTextField(L\"Mary Anne\", WinToastTemplate::FirstLine);\ntempl.setTextField(L\"Check out where we camped last night!\", WinToastTemplate::SecondLine);\ntempl.setHeroImagePath(L\"C:/example.png\");\n```\n\n![\"Toast with hero image\"](assets/images/hero-image.png)\n\nThe hero image is specified by calling the `WinToastTemplate::setHeroImagePath` method. The image path can be a local file path or a URI. \n\n\n### Inline Image\n\nThe second parameter of the method `WinToastTemplate::setHeroImagePath` is a boolean value that specifies whether the image should be inlined in the toast notification. \n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);\ntempl.setTextField(L\"Feature image of the day\", WinToastTemplate::FirstLine);\ntempl.setHeroImagePath(L\"C:/example.png\", true);\n```\n\n![\"Toast with inlined hero image\"](assets/images/inline-image.png)\n\n### Actions\n\nYou can add your own actions, this fact allow you to interact with user in a different way:\n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);\ntempl.setTextField(L\"New product in stock\", WinToastTemplate::FirstLine);\n\nstd::vector\u003cstd::wstring\u003e actions;\nactions.push_back(L\"See more details\");\nactions.push_back(L\"Remind me later\");\n// ...\n\nfor (auto const \u0026action : actions) {\n    templ.addAction(action);\n}\nWinToast::instance()-\u003eshowToast(templ, handler) \n```\n\n![\"Toast with some actions\"](assets/images/image-actions.png)\n\n\n### Attribution text\n\nNew in Anniversary Update: If you need to reference the source of your content, you can use attribution text. This text is always displayed below any text elements, but above inline images. The text uses a slightly smaller size than standard text elements to help to distinguish from regular text elements.\n\n```cpp\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::Text02);\ntempl.setTextField(L\"Mary Anne\", WinToastTemplate::FirstLine);\ntempl.setTextField(L\"Check out where we camped last night!\", WinToastTemplate::SecondLine);\ntempl.setHeroImagePath(L\"C:/example.png\");\ntempl.setAttributionText(L\"Via SMS\");\n```\n\n![\"Toast with some actions\"](assets/images/attribution-text.png)\n\n### Duration\n\nThe amount of time the toast should display. This attribute can have one of the following values: \n     - *System*: default system configuration.\n\t - *Short*: default system short time configuration.\n\t - *Long*: default system long time configuration.\n\n### Audio Properties\n\nYou can modify the different behaviors of the sound:\n\t - *Default*: plays the audio file just one time.\n\t - *Silent*: turn off the sound.\n\t - *Loop*: plays the given sound in a loop during the toast existence.\n\n\u003e WinToast allows the modification of the default audio file. Add \n\u003e the given file in to your projects resources (*must be ms-appx:// or\n\u003e ms-appdata:// path*) and define it by calling: `WinToastTemplate::setAudioPath`\n\n***By default, WinToast checks if your systems support the features, ignoring the not supported ones.***\n\n## Error Handling\nThere are several reasons WinToast can fail that's why the library notifies caller about fail reason. Those are the code for each failure:\n\n| WinToastError | Error Code | Error message |\n|--|--|--|\n| `NoError` | 0x00 | No error. The process was executed correctly |\n| `NotInitialized` | 0x01 | The library has not been initialized |\n| `SystemNotSupported` | 0x02 | The OS does not support WinToast |\n| `ShellLinkNotCreated` | 0x03 | The library was not able to create a Shell Link for the app |\n| `InvalidAppUserModelID` | 0x04 | The AUMI is not a valid one |\n| `InvalidParameters` | 0x05 | The parameters used to configure the library are not valid normally because an invalid AUMI or App Name |\n| `NotDisplayed` | 0x06 | The toast was created correctly but WinToast was not able to display the toast |\n| `UnknownError` | 0x07 | Unknown error |\n\nA common example of usage is to check while initializing the library or showing a toast notification the possible failure code:\n\n```cpp\nWinToast::WinToastError error;\nconst auto succedded = WinToast::instance()-\u003einitialize(\u0026error);\nif (!succedded) {  \n    std::wcout \u003c\u003c L\"Error, could not initialize the lib. Error number: \" \n    \u003c\u003c error \u003c\u003c std::endl;\n}\n...\n// Configure the template\n...\nconst auto toast_id = WinToast::instance()-\u003eshowToast(templ, handler, \u0026error);\nif (toast_id \u003c 0) {\n    std::wcout \u003c\u003c L\"Error: Could not launch your toast notification. Error: \"\n     \u003c\u003c error \u003c\u003c std::endl;\n}\n```\n\n\n## Example of Usage\n\n*For an easy usage,  you can just use the available singleton instance.* \n\nFirst step, Import the header file wintoastlib.h to your project. You should check if your Windows Version is supported by the library.\n\n```cpp\nusing namespace WinToastLib;\n....\nif (!WinToast::isCompatible()) {\n    std::wcout \u003c\u003c L\"Error, your system in not supported!\" \u003c\u003c std::endl;\n}\n```\n\n Configure your [App User Model Id](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459%28v=vs.85%29.aspx), this can be done by using the existing helper:\n\n```cpp        \n\nWinToast::instance()-\u003esetAppName(L\"WinToastExample\");\nconst auto aumi = WinToast::configureAUMI(L\"mohabouje\", L\"wintoast\", L\"wintoastexample\", L\"20161006\");\nWinToast::instance()-\u003esetAppUserModelId(aumi);\t\n```\n\nInitialize all the dependencies and check if WinToast has been initialized successfully in your system:\n\n```cpp\t\t\nif (!WinToast::instance()-\u003einitialize()) {\n  std::wcout \u003c\u003c L\"Error, could not initialize the lib!\" \u003c\u003c std::endl;\n}\n```\n\nImplement your own action handler by subclassing the interface `IWinToastHandler` and custom your template:\n\n```cpp\nWinToastHandlerExample* handler = new WinToastHandlerExample;\nWinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);\ntempl.setImagePath(L\"C:/example.png\");\ntempl.setTextField(L\"title\", WinToastTemplate::FirstLine);\ntempl.setTextField(L\"subtitle\", WinToastTemplate::SecondLine);\n```\n\nFinally show the results:\n\n```cpp\n\nconst auto toast_id = WinToast::instance()-\u003eshowToast(templ, handler, \u0026error);\nif (toast_id \u003c 0) {\n    std::wcout \u003c\u003c L\"Error: Could not launch your toast notification!\" \u003c\u003c std::endl;\n}\n```\n\nShao Voon Wong wrote an excellent article about the usage of WinToast. You can find it [here](https://www.codeproject.com/Articles/5286393/Cplusplus-Windows-Toast-Notification).\n\n## Installation\n\nIf you are using a package manager, there is a port for [vcpkg](https://github.com/microsoft/vcpkg/). Otherwise, the easiest way is to copy the source files as external dependencies.\n\n## Toast configuration on Windows 10\n\nWindows allows the configuration of the default behavior of a toast notification. This can be done in the *Ease of Access* configuration by modifying the *Other options* tab. \n\nThe system configuration helps you to define how long you want notifications to appear for (5 seconds to 5 minutes) as turning on visual notifications for sound.\n\n![Ease of Access configuration](https://camo.githubusercontent.com/56c8edd1a7a4a43be07ba211d9d828478fdbad39/68747470733a2f2f7777772e686f77746f6765656b2e636f6d2f77702d636f6e74656e742f75706c6f6164732f323031362f30332f656173655f6f665f6163636573732e706e67)\n\n\n## Projects using WinToast\n - [Git for Windows](https://github.com/git-for-windows/git): A fork of Git containing Windows-specific patches.\n - [Firefox](https://hg.mozilla.org/mozilla-central/file/tip/third_party/WinToast/wintoastlib.cpp): A free and open source web browser.\n - [Tor Browser](https://gitlab.torproject.org/tpo/applications/tor-browser/-/blob/tor-browser-102.2.0esr-12.0-2/third_party/WinToast/wintoastlib.h): privacy-focused web browser that enables anonymous internet browsing.\n - [Waterfox](https://github.com/WaterfoxCo/Waterfox): Fast and Private Web Browser\n - [QGIS](https://github.com/qgis/QGIS): QGIS is a free, open source, cross platform (lin/win/mac) geographical information system (GIS)\n - [Synergy Core](https://github.com/symless/synergy-core): Share one mouse and keyboard between multiple computers\n - [Siv3D](https://github.com/Siv3D/OpenSiv3D): A C++20 cross-platform library for creative coding\n - [MEGAsync](https://github.com/meganz/MEGAsync): Easy automated syncing between your computers and your MEGA Cloud Drive\n - [chatterino2](https://github.com/Chatterino/chatterino2): Chat client for twitch.tv\n - [nheko](https://github.com/Nheko-Reborn/nheko): Desktop client for the Matrix protocol.\n - [EDPathFinder](https://github.com/neotron/EDPathFinder): A program that creates an optimal route that passes through two or more systems in Elite.\n - [IW6-mod]([https://github.com/XLabsProject/iw6x-client](https://git.alterware.dev/alterware/iw6-mod)): Formerly known as IW6x, IW6-mod is a open-source \u0026 community-driven project aiming to recreate the multiplayer experience of Call of Duty: Ghosts.\n - [H1-Mod](https://github.com/auroramod/h1-mod): A client for Call of Duty: Modern Warfare Remastered.\n - [AntiExploit](https://github.com/Empier/Anti-Exploit): antiexploit utility for Windows.\n - [Zroya](https://github.com/malja/zroya): Python extension for creating native Windows notifications..\n - [PidginWinToastNotifications](https://github.com/ChristianGalla/PidginWinToastNotifications): Windows Toast Notification Plugin for Pidgin. \n - [Dnai-Editor](https://github.com/Nicolas-Constanty/Dnai.Editor): Visual Scripting, node editor.\n - [Spectral](https://gitlab.com/b0/spectral): A glossy client for Matrix, written in QtQuick Controls 2 and C++.\n","funding_links":["https://patreon.com/mohabouje","https://paypal.me/mohabouje"],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohabouje%2FWinToast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohabouje%2FWinToast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohabouje%2FWinToast/lists"}