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:
Features |
Usage |
Copyright |
Class Framework Reference |
History |
Contacting the Author |
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
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
};
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;
};
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:
RegisterForNotificationSupport
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
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
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.
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
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
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();
Remarks
This is the standard constructor for the class which initializes all the internal variables to a safe state.
~CToast();
Remarks
This is the standard destructor for the class. It internally calls the Reset method.
See Also
void Reset()
Remarks
This method internally calls RemoveEventHandlers and then calls the parent classes Reset method.
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
HRESULT RemoveEventHandlers()
Remarks
This method removes the event handler callback which was setup in CManager::SetupEventHandlers.
Return Value
A standard HRESULT value.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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)
PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
28 May
2023