Toast++v1.17

Welcome to Toast++, a set of C++ classes which provide an encapsulation of Toast Notifications for Desktop Win32 applications. These are the popups you see from Windows normally in the bottom right of the screen which accumulate into Action Center. These toast notification APIs are exposed as Windows Runtime interfaces but can be used from standard Desktop Win32 applications with some work. The Toast++ classes ease this integration process.

 

The classes provided are as follows:

CManager provides a class based encapsulation of an IToastNotifier Windows Runtime interface as well as helper functionality for integrating Win32 applications with Toast Notifications.

CToast provides a class based encapsulation of an IToastNotification Windows Runtime interface as well as support for callback notification through this interface. It also provides a method to setup the toast UI via an XML string parameter.

CContent provides a class which allows you to create the XML for toasts using C++ classes and member variables. For more information on the detailed Toast schema, please see https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/toast-xml-schema.

CActions, CActionsSnoozeAndDismiss, CAdaptiveGroup, CAdaptiveImage, CAdaptiveSubgroup, CAdaptiveText, CAppLogo, CAttributionText, CAudio, CButton, CButtonDismiss, CButtonSnooze, CContextMenuItem, CGenericBinding, CGenericImage, CGenericText, CHeroImage, CProgressBar, CSelectionBox, CSelectionBoxItem, CTextBox, CVisual & CWin81Binding are all the sub classes used by CContent.

 

An example of the demo app running along with a couple of popped toasts is shown below:

Toast++ demo app

 

 
Features
Usage
Copyright
Class Framework Reference
History
Contacting the Author

 

 

 

Features

 

 

 

Usage

 

 

 

Copyright

 

 

 

Class Framework Reference

The framework consists of the following enums / interface / classes:

Enums
INotifier

CManager
CToast

CActions
CActionsSnoozeAndDismiss
CAdaptiveGroup
CAdaptiveImage
CAdaptiveSubgroup
CAdaptiveText
CAppLogo
CAttributionText
CAudio
CButton
CButtonDismiss
CButtonSnooze
CContent
CContextMenuItem
CGenericBinding
CGenericImage
CGenericText
CHeroImage
CProgressBar
CSelectionBox
CSelectionBoxItem
CTextBox
CVisual

CWin81Binding

 

 

Enums

enum class TemplateType
{
 Generic,
 ToastText01,
 ToastImageAndText01,
 ToastText02,
 ToastImageAndText02,
 ToastText03,
 ToastImageAndText03,
 ToastText04,
 ToastImageAndText04
};

enum class Scenario
{
 Default = 0,
 Alarm = 1,
 Reminder = 2,
 IncomingCall = 3
};

enum class Duration
{
 Default = 0,
 Short = 1,
 Long = 2
};

enum class ImageCrop
{
 Default = 0,
 None = 1,
 Circle = 2
};

enum class ImagePlacement
{
 Default = 0,
 Inline = 1,
};

enum class AdaptiveImageAlign
{
 Default = 0,
 Stretch = 1,
 Left = 2,
 Center = 3,
 Right = 4
};

enum class AdaptiveImageCrop
{
 Default = 0,
 None = 1,
 Circle = 2
};

enum class SubgroupTextStacking
{
 Default = 0,
 Top = 1,
 Center = 2,
 Bottom = 3
};

enum class AdaptiveTextAlign
{
 Default = 0,
 Auto = 1,
 Left = 2,
 Center = 3,
 Right = 4
};

enum class AdaptiveTextStyle
{
 Default = 0,
 Caption = 1,
 CaptionSubtle = 2,
 Body = 3,
 BodySubtle = 4,
 Base = 5,
 BaseSubtle = 6,
 Subtitle = 7,
 SubtitleSubtle = 8,
 Title = 9,
 TitleSubtle = 10,
 TitleNumeral = 11,
 Subheader = 12,
 SubheaderSubtle = 13,
 SubheaderNumeral = 14,
 Header = 15,
 HeaderSubtle = 16,
 HeaderNumeral = 17
};

 

 

INotifier

This is the callback interface which is used by CManager::Show. It is defined as follows:

 

class INotifier
{
public:
  virtual void OnToastActivated(IToastNotification* pSender, IInspectable* pArgs) = 0;
  virtual void OnToastDismissed(IToastNotification* pSender, ToastDismissalReason reason) = 0;
  virtual void OnToastFailed(IToastNotification* pSender, HRESULT errorCode) = 0;
};

 

 

CManager

This provides a class based encapsulation of an IToastNotifier Windows Runtime interface as well as helper functionality for integrating Win32 applications with Toast Notifications.

 

Functions this class provides include:

GetExecutablePath

RegisterForNotificationSupport

CreateStartMenuShortcut

Create

Show

SetupEventHandlers

 

CManager::GetExecutablePath

static HRESULT GetExecutablePath(std::wstring& sModuleName);

Remarks

A simple helper method to return the full path of the current process.

Return Value

A standard HRESULT value.

Parameters

sModuleName Upon successful return from this method, this will contain the full path of the current process.

 

CManager::RegisterForNotificationSupport

HRESULT RegisterForNotificationSupport(LPCWSTR pszAppName, LPCWSTR pszApplicationPath, LPCWSTR pszAppUserModelID, GUID ClsidToastActivator = GUID_NULL, LPCWSTR pszArguments = nullptr, LPCWSTR pszWorkingDirectory = nullptr, LPCWSTR pszDescription = nullptr, LPCWSTR pszIconPath = nullptr, int nIcon = 0);

Remarks

Win32 applications have a special requirement of needing a shortcut to be added to the Start menu for Toast Notifications to work. This is because a Win32 application does not have a well known "Application Identity" like a Store app does. This method creates the specified shortcut in the current user's Start Menu folder if it does not already exist. To create the shortcut, internally this method will call CreateStartMenuShortcut. This along with the CLSID for you Action Center callback is embedded into the shortcut created by this method.

Return Value

A standard HRESULT value.

Parameters

pszAppName The filename part of the shortcut which will be created

pszApplicationPath The value to pass to IShellLink::SetPath.

pszAppUserModelID The AppUserModelID value to embed in the shortcut. This parameter provides the identify which Windows need to allow Win32 applications to work with Toast Notifications. The value used by the demo app is "Naughter.ToastPPDemoApp".

ClsidToastActivator The CLSID of the COM class to be used for Action Center callbacks. Again this value will be embedded in the shortcut. Passing GUID_NULL will not embed a CLSID in the shortcut.

pszArguments The value to pass to IShellLink::SetArguments. Passing nullptr will not call SetArguments for the shortcut.

pszWorkingDirectory The value to pass to IShellLink::SetWorkingDirectory. Passing nullptr will not call SetWorkingDirectory for the shortcut.

pszDescription The value to pass to IShellLink::SetDescription. Passing nullptr will not call SetDescription for the shortcut.

pszDescription and nIcon The values to pass to IShellLink::SetIconLocation. Passing nullptr for pszIconPath will not call SetIconLocation for the shortcut.

See Also

CreateStartMenuShortcut

 

CManager::CreateStartMenuShortcut

HRESULT CreateStartMenuShortcut(LPCWSTR pszShortcutPath, LPCWSTR pszApplicationPath, LPCWSTR pszAppUserModelID, GUID ClsidToastActivator = GUID_NULL, LPCWSTR pszArguments = nullptr, LPCWSTR pszWorkingDirectory = nullptr, LPCWSTR pszDescription = nullptr, LPWSTR pszIconPath = nullptr, int nIcon = 0);

Remarks

This method creates the shortcut required for Toast Notifications to work for Win32 applications.

Return Value

A standard HRESULT value.

Parameters

pszAppName The full path where the shortcut file will be created.

pszApplicationPath The value to pass to IShellLink::SetPath.

pszAppUserModelID The AppUserModelID to embed in the shortcut. This parameter provides the identify which Windows need to allow Win32 applications to work with Toast Notifications. The value used by the demo app is "Naughter.ToastPPDemoApp".

ClsidToastActivator The CLSID of the COM class to be used for Action Center callbacks. Again this value will be embedded in the shortcut. Passing GUID_NULL will not embed a CLSID in the shortcut.

pszArguments The value to pass to IShellLink::SetArguments. Passing nullptr will not call SetArguments for the shortcut.

pszWorkingDirectory The value to pass to IShellLink::SetWorkingDirectory. Passing nullptr will not call SetWorkingDirectory for the shortcut.

pszDescription The value to pass to IShellLink::SetDescription. Passing nullptr will not call SetDescription for the shortcut.

pszDescription and nIcon The values to pass to IShellLink::SetIconLocation. Passing nullptr for pszIconPath will not call SetIconLocation for the shortcut.

See Also

RegisterForNotificationSupport

 

CManager::Create

HRESULT Create(LPCWSTR pszAppUserModelID);

Remarks

This methods creates the actual IToastNotifier instance which the CManager class encapsulates. Internally this method will use the IToastNotificationManagerStatics Windows Runtime interface and its CreateToastNotifierWithId method to do this.

Return Value

A standard HRESULT value.

 

CManager::Show

HRESULT Show(CToast& toast, INotifier* eventHandler = nullptr);

Remarks

This method setups an optional callback interface for the toast and then shows the toast via IToastNotification::Show.

Return Value

A standard HRESULT value.

Parameters

toast The toast to show

eventHandler The optional callback interface to call for the toast. If this value is nullptr, then no callback is setup.

See Also

INotifier

 

CManager::SetupEventHandlers

HRESULT SetupEventHandlers(INotifier* eventHandler);

Remarks

This method setups the callback interface for the toast.

Return Value

A standard HRESULT value.

Parameters

eventHandler The callback interface to call for the toast. This is setup via the IToastNotification::add_Activated, IToastNotification::add_Dismissed and IToastNotification::add_Failed API methods.

See Also

INotifier

 

 

CToast

This provides a class based encapsulation of an IToastNotification Windows Runtime interface as well as support for callback notification through this interface. It also provides a method to setup the toast UI via an XML string parameter.

 

Functions this class provides include:

CToast

~CToast

Reset

Create

RemoveEventHandlers

 

CToast::CToast

CToast();

Remarks

This is the standard constructor for the class which initializes all the internal variables to a safe state.

 

CToast::~CToast

~CToast();

Remarks

This is the standard destructor for the class. It internally calls the Reset method.

See Also

CToast

 

CToast::Reset

void Reset()

Remarks

This method internally calls RemoveEventHandlers and then calls the parent classes Reset method.

 

CToast::Create

HRESULT Create(LPCWSTR pszContent)

Remarks

This methods creates the actual IToastNotification instance which the CToast class encapsulates. Internally this method parses the pszContent into an XML document and then creates the IToastNotification Windows Runtime interface. For more information on the XML schema of the toast notifications please see https://docs.microsoft.com/en-us/uwp/schemas/tiles/toastschema/schema-root and https://msdn.microsoft.com/library/windows/apps/hh761494. The later link defines the Windows 8 / Windows 8.1 style schema while the former defines the updated Windows 10 schema. For a good introduction to the added functionality in Windows 10 toasts, please see https://blogs.msdn.microsoft.com/tiles_and_toasts/2015/07/08/toast-notification-and-action-center-overview-for-windows-10/.

Return Value

A standard HRESULTvalue.

Parameters

pszContent The toast XML to use for this instance

 

CToast::RemoveEventHandlers

HRESULT RemoveEventHandlers()

Remarks

This method removes the event handler callback which was setup in CManager::SetupEventHandlers.

Return Value

A standard HRESULT value.

 

 

CActions

This provides encapsulates the "Actions" node of the Toast XML.

Member variables which this class provides are:

std::vector<IContextMenuItem*> m_ContextMenuItems. This represents the

vector<IInput*> m_Inputs

vector<IButton*> m_Buttons

 

Actions are supported on Windows 10 RTM or later.

 

 

CActionsSnoozeAndDismiss

This class provides system handled actions for snoozing and dismissing notifications. For more info please see https://blogs.msdn.microsoft.com/tiles_and_toasts/2015/07/02/adaptive-and-interactive-toast-notifications-for-windows-10/.

Member variables which this class provides are:

std::vector<CContextMenuItem*> m_ContextMenuItems

ActionsSnoozeAndDismiss are supported on Windows 10 RTM or later.

 

 

CAdaptiveGroup

This class encapsulates the "group" node ot the Toast XML.

Member variables which this class provides are:

vector<IAdaptiveSubgroup*> m_Children

 

Groups are supported on Windows 10 Anniversary Update or later.

 

 

CAdaptiveImage

This class encapsulates the "image" node of the Toast XML.

Member variables which this class provides are:

wstring m_sSource

wstring m_sAlternateText

bool m_bAddImageQuery

AdaptiveImageCrop m_HintCrop

bool m_bHintRemoveMargin

AdaptiveImageAlign m_HintAlign

Adaptive images are supported on Windows 10 Anniversary Update or later.

 

 

CAdaptiveSubgroup

This class encapsulates the "subgroup" node of the Toast XML.

Member variables which this class provides are:

int m_nHintWeight

SubgroupTextStacking m_HintTextStacking

vector<IAdaptiveSubgroupChild*> m_Children

Subgroups are supported on Windows 10 Annivesary Update or later.

 

 

CAdaptiveText

This class encapsulates the "text" node of the Toast XML.

Member variables which this class provides are:

wstring m_sText

AdaptiveTextStyle m_HintStyle

bool m_bHintWrap

int m_nHintMaxLines

int m_nHintMinLines

AdaptiveTextAlign m_HintAlign

wstring m_sLanguage

 

Adaptive texts are supported on Windows 10 Anniversary Update or later.

 

 

CAppLogo

This class encapsulates an "image" node of the Toast XML which overrides the application logo.

Member variables which this class provides are:

ImageCrop m_HintCrop

Application logo images are supported on Windows 10 Anniversary Update or later.

 

 

CAttributionText

This class encapsulates a "text" node of the Toast XML where has placement="attribute" set.

Member variables which this class provides are:

wstring m_sText

wstring m_sLanguage

 

Attribution text is supported on Windows 10 Anniversary Update or later.

 

 

CAudio

This class encapsulates a "audio" node of the Toast XML.

Member variables which this class provides are:

wstring m_sSrc

bool m_bLoop

bool m_bSilent

 

Audio is supported on Windows 10 Version 1511 or later.

 

 

CButton

This class encapsulates an "action" node of the Toast XML which represents a button.

Member variables which this class provides are:

wstring m_sContent

wstring m_sArguments

wstring m_sImageUri

wstring m_sHintInputId

 

Action buttons are supported on Windows 10 RTM or later.

 

 

CButtonDismiss

This class encapsulates an "action" node of the Toast XML which represents a dismiss button with activationType="system".

Member variables which this class provides are:

wstring m_sContent

wstring m_sImageUri

 

Action dismiss buttons are supported on Windows 10 RTM or later.

 

 

CButtonSnooze

This class encapsulates an "action" node of the Toast XML which represents a snooze button with activationType="system".

Member variables which this class provides are:

wstring m_sContent

wstring m_sImageUri

 

Action snooze buttons are supported on Windows 10 RTM or later.

 

 

CContent

This is the main class which allows you to create the XML for toasts using C++ classes and member variables.

Member variables which this class provides are:

CVisual m_Visual

CAudio m_Audio

CActions m_Actions

Scenario m_Scenario

Duration m_Duration

wstring m_sLaunch

SYSTEMTIME m_DisplayTimestamp

TemplateType m_Type

Functions this class provides include:

GetContent

 

CContent::GetContent

HRESULT GetContent(std::wstring& sXML)

HRESULT GetContent(ATL::CComPtr<IXMLDOMDocument>& xml)

Remarks

Converts the contents of this CContent instance to a MSXML DOM or string representation of the XML for the toast.

Return Value

A standard HRESULT value.

Parameters

sXML Upon successful return from this method, this will contain the XML.

xml Upon successful return from this method, this will contain the XML.

 

 

CContextMenuItem

This class encapsulates an "action" node of the Toast XML which represents a context menu which appears for the toast in Action Center. The action will have placement="contextMenu".

Member variables which this class provides are:

wstring m_sContent

wstring m_sArguments;

 

Context menu items are supported on Windows 10 Anniversary Update or later.

 

 

CGenericBinding

This class encapsulates a "binding" node of the Toast XML with template="ToastGeneric".

Member variables which this class provides are:

wstring m_sContent

 

ToastGeneric templates are supported on Windows 10 RTM or later.

 

 

CGenericImage

This class encapsulates an "image" node of the Toast XML.

Member variables which this class provides are:

wstring m_sSource

wstring m_sAlternateText

bool m_bAddImageQuery

ImagePlacement m_Placement

ImageCrop m_HintCrop

 

Image nodes are supported on Windows 10 RTM or later.

 

 

CGenericText

This class encapsulates a "text" node of the Toast XML.

Member variables which this class provides are:

wstring m_sText

wstring m_sLanguage

 

Text nodes are supported on Windows 10 RTM or later.

 

 

CHeroImage

This class encapsulates the "image" node of the Toast XML with placement="appLogoOverride".

Member variables which this class provides are:

wstring m_sSource

wstring m_sAlternateText

bool m_bAddImageQuery

 

Hero images are supported on Windows 10 Anniversary Update or later.

 

 

CProgressBar

This class encapsulates a "progress" node of the Toast XML.

Member variables which this class provides are:

wstring m_sTitle

wstring m_sStatus

wstring m_sValue

wstring m_sValueStringOverride

 

Progress bars are supported on Windows 10 Creators Update or later.

 

 

CSelectionBox

This class encapsulates a "input" node of the Toast XML with type="selection". This corresponds to a selection menu / combo box UI element on the toast.

Member variables which this class provides are:

wstring m_sId

wstring m_sTitle

wstring m_sDefaultSelectionBoxItemId

vector<CSelectionBoxItem*> m_Items

 

Selection menus are supported on Windows 10 RTM or later.

 

 

CSelectionBoxItem

This class encapsulates a "selection" node of the Toast XML. This corresponds to a an individual item in a selection menu / combo box UI element on the toast.

Member variables which this class provides are:

wstring m_sId

wstring m_sContent

 

Selection menus are supported on Windows 10 RTM or later.

 

 

CTextBox

This class encapsulates a "input" node of the Toast XML with type="text". This corresponds to a text box UI element on the toast.

Member variables which this class provides are:

wstring m_sId

wstring m_sTitle

wstring m_sPlaceholderContent

wstring m_sDefaultInput

 

Text boxes are supported on Windows 10 RTM or later.

 

 

CVisual

This class encapsulates the "visual" node of the Toast XML.

Member variables which this class provides are:

wstring m_sLanguage

wstring m_sBaseUri

bool m_bAddImageQuery

CGenericBinding m_BindingGeneric

CWin81Binding m_BindingWin81

 

 

CWin81Binding

This class encapsulates a "binding" node of the Toast XML with template different than ToastGeneric". The template="ToastGeneric" type was introduced with Windows 10 and is supported by the CGenericBinding class.

Member variables which this class provides are:

IImageWin81 m_Image

wstring m_sText1

wstring m_sText2

wstring m_sText3

 

These template types support toasts on Windows 8.1 or later.

 

 

 

History

v1.17 (28 May 2023)

v1.16 (2 May 2022)

v1.15 (11 December 2021)

v1.14 (4 April 2020)

v1.13 (16 September 2019)

v1.12 (22 April 2019)

v1.11 (2 December 2018)

v1.1 (24 June 2017)

v1.0 (3 June 2017)

 

 

 

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
28 May 2023