WinToast is a lightly library written in C++ which brings a complete integration of the modern **toast notifications** of **Windows 8**&**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.
1. [Toast Templates](#id1)
2. [Event Handler](#id3)
3. [Expiration Time](#id4)
4. [Additional features available on Windows 10](#id5)
5. [Error Handling](#id2)
6. [Example of usage](#id6)
7. [Toast configuration on Windows 10](#id7)
8. [Projects using WinToast](#id8)
<divid='id1'/>
## Toast Templates
WinToast integrates all standard templates available in the [ToastTemplateType enumeration](https://msdn.microsoft.com/en-us/library/windows/apps/br208660.aspx).
| Template | Description | Example |
| :------- | ----: | :---: |
| `ImageAndText01` | A large image and a single string wrapped across three lines of text. |  |
| `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. |  |
| `ImageAndText03` | A large image, one string of bold text wrapped across the first two lines, one string of regular text on the third line. |  |
| `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. |  |
| `Text01` | Single string wrapped across three lines of text. | |
| `Text02` | One string of bold text on the first line, one string of regular text wrapped across the second and third lines. |  |
| `Text03` | One string of bold text wrapped across the first two lines, one string of regular text on the third line. | |
| `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. |  |
**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.*
<divid='id3'/>
## Event Handler
WinToast handle different events:
- **Activated**: Occurs when user activates a toast notification through a click or touch. Apps that are running subscribe to this event
- **Dismissed**: Occurs when a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user.
* Application Hidden: The application hid the toast using ToastNotifier.hide.
* User Canceled: The user dismissed the toast.
* Timed Out: The toast has expired
- **Failed**: Occurs when an error is caused when Windows attempts to raise a toast notification.
Create your custom handler to interact with the user actions by subclassing the interface `IWinToastHandler`:
```cpp
class WinToastHandlerExample : public IWinToastHandler {
Set 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.
> For Windows 8.x app, this property also causes the toast notification to be removed from the
> Action Center once the specified data and time is reached.
**Note:** Default Windows behavior is to hide notification automatically after time set in Windows Ease of Access Settings.
If you need to preserve notification in Windows Action Center for longer period of time, you have to call `WinToastTemplate::setExpiration` method.
<divid='id5'/>
## Additional features available on Windows 10
If your system supports the new modern features (Version > Windows 8.1) available in Windows 10, you can add some interesting fields as:
- **Actions**: you can add your own actions, this fact allow you to interact with user in a different way:
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:
Windows 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.
The 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.
<divid='id8'/>
## Projects using WinToast
- [Git for Windows](https://github.com/git-for-windows/git): A fork of Git containing Windows-specific patches.
- [nheko](https://github.com/mujx/nheko): Desktop client for the Matrix protocol.
- [EDPathFinder](https://github.com/neotron/EDPathFinder): A program that creates an optimal route that passes through two or more systems in Elite.
- [AntiExploit](https://github.com/Empier/Anti-Exploit): antiexploit utility for Windows.
- [Zroya](https://github.com/malja/zroya): Python extension for creating native Windows notifications..
- [PidginWinToastNotifications](https://github.com/ChristianGalla/PidginWinToastNotifications): Windows Toast Notification Plugin for Pidgin.
