search

mohabouje / WinToast

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.
MIT License
700 stars 130 forks source link
event-handlers modern-features notifications toast-notifications toast-templates windows windows-10 windows-uwp

readme

license GitHub contributors releases [GitHub stars]() [GitHub forks]() [GitHub watchers]() issues

WinToast

WinToast 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.

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.

Toast Templates

WinToast integrates all standard templates available in the ToastTemplateType enumeration.

Template Description Example
ImageAndText01 A large image and a single string wrapped across three lines of text. enter image description here
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
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
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
Text01 Single string wrapped across three lines of text. enter image description here
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
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
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

Example of a ImageAndText02 template:

WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField(L"title", WinToastTemplate::FirstLine);
templ.setTextField(L"subtitle", WinToastTemplate::SecondLine);
templ.setImagePath(L"C:/example.png");

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.*

Event Handler

WinToast handle different events:

Create your custom handler to interact with the user actions by subclassing the 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;
 };

Notification Content

The full documentation of the notification content here.

Scenario

To 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:

Expiration Time

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.

Hint Crop

Microsoft 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.

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);

"Toast with hero image"

Hero Image

The 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.

Note: The hero image is not supported on Windows 8.1 and 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");

"Toast with hero image"

The hero image is specified by calling the WinToastTemplate::setHeroImagePath method. The image path can be a local file path or a URI.

Inline Image

The second parameter of the method WinToastTemplate::setHeroImagePath is a boolean value that specifies whether the image should be inlined in the toast notification. 

WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField(L"Feature image of the day", WinToastTemplate::FirstLine);
templ.setHeroImagePath(L"C:/example.png", true);

"Toast with inlined hero image"

Actions

You can add your own actions, this fact allow you to interact with user in a different way:

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)

"Toast with some actions"

Attribution text

New 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.

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");

"Toast with some actions"

Duration

The amount of time the toast should display. This attribute can have one of the following values:

Audio Properties

You can modify the different behaviors of the sound:

WinToast allows the modification of the default audio file. Add the given file in to your projects resources (must be ms-appx:// or ms-appdata:// path) and define it by calling: WinToastTemplate::setAudioPath

By default, WinToast checks if your systems support the features, ignoring the not supported ones.

Error Handling

There are several reasons WinToast can fail that's why the library notifies caller about fail reason. Those are the code for each failure:

WinToastError Error Code Error message
NoError 0x00 No error. The process was executed correctly
NotInitialized 0x01 The library has not been initialized
SystemNotSupported 0x02 The OS does not support WinToast
ShellLinkNotCreated 0x03 The library was not able to create a Shell Link for the app
InvalidAppUserModelID 0x04 The AUMI is not a valid one
InvalidParameters 0x05 The parameters used to configure the library are not valid normally because an invalid AUMI or App Name
NotDisplayed 0x06 The toast was created correctly but WinToast was not able to display the toast
UnknownError 0x07 Unknown error

A common example of usage is to check while initializing the library or showing a toast notification the possible failure code:

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;
}

Example of Usage

For an easy usage, you can just use the available singleton instance.

First step, Import the header file wintoastlib.h to your project. You should check if your Windows Version is supported by the library.

using namespace WinToastLib;
....
if (!WinToast::isCompatible()) {
    std::wcout << L"Error, your system in not supported!" << std::endl;
}

Configure your App User Model Id, this can be done by using the existing helper:


WinToast::instance()->setAppName(L"WinToastExample");
const auto aumi = WinToast::configureAUMI(L"mohabouje", L"wintoast", L"wintoastexample", L"20161006");
WinToast::instance()->setAppUserModelId(aumi);

Initialize all the dependencies and check if WinToast has been initialized successfully in your system:

if (!WinToast::instance()->initialize()) {
  std::wcout << L"Error, could not initialize the lib!" << std::endl;
}

Implement your own action handler by subclassing the interface IWinToastHandler and custom your template:

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);

Finally show the results:


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 wrote an excellent article about the usage of WinToast. You can find it here.

Installation

If you are using a package manager, there is a port for vcpkg. Otherwise, the easiest way is to copy the source files as external dependencies.

Toast configuration on Windows 10

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.

Ease of Access configuration

Projects using WinToast