wx.adv.NotificationMessage

This class allows showing the user a message non intrusively.

Currently it is implemented natively for Windows, macOS, GTK and uses generic toast notifications under the other platforms. It’s not recommended but GenericNotificationMessage can be used instead of the native ones. This might make sense if your application requires features not available in the native implementation.

Notice that this class is not a window and so doesn’t derive from wx.Window.

Platform Notes

Windows

Up to Windows 8 balloon notifications are displayed from an icon in the notification area of the taskbar. If your application uses a wx.adv.TaskBarIcon you should call UseTaskBarIcon to ensure that only one icon is shown in the notification area. Windows 10 displays all notifications as popup toasts. To suppress the additional icon in the notification area on Windows 10 and for toast notification support on Windows 8 it is recommended to call MSWUseToasts before showing the first notification message.

macOS

The macOS implementation uses Notification Center to display native notifications. In order to use actions your notifications must use the alert style. This can be enabled by the user in system settings or by setting the NSUserNotificationAlertStyle value in Info.plist to alert . Please note that the user always has the option to change the notification style.

Events Emitted by this Class

Handlers bound for the following event types will receive one of the wx.CommandEvent parameters.

• EVT_NOTIFICATION_MESSAGE_CLICK: Process a wxEVT_NOTIFICATION_MESSAGE_CLICK event, when a notification is clicked.

• EVT_NOTIFICATION_MESSAGE_DISMISSED: Process a wxEVT_NOTIFICATION_MESSAGE_DISMISSED event, when a notification is dismissed by the user or times out.

• EVT_NOTIFICATION_MESSAGE_ACTION: Process a wxEVT_NOTIFICATION_MESSAGE_ACTION event, when the user selects on of the actions added by AddAction

Core

Added in version 2.9.0.

Class Hierarchy

Inheritance diagram for class NotificationMessage:

Control Appearance

wxMSW

wxGTK

wxMAC

Methods Summary

__init__	Default constructor, use SetParent , SetTitle and SetMessage to initialize the object before showing it.
AddAction	Add an action to the notification.
Close	Hides the notification.
MSWUseToasts	Enables toast notifications available since Windows 8 and suppresses the additional icon in the notification area on Windows 10.
SetFlags	This parameter can be currently used to specify the icon to show in the notification.
SetIcon	Specify a custom icon to be displayed in the notification.
SetMessage	Set the main text of the notification.
SetParent	Set the parent for this notification: the notification will be associated with the top level parent of this window or, if this method is not called, with the main application window by default.
SetTitle	Set the title, it must be a concise string (not more than 64 characters), use SetMessage to give the user more details.
Show	Show the notification to the user and hides it after timeout seconds are elapsed.
UseTaskBarIcon	If the application already uses a wx.adv.TaskBarIcon, it should be connected to notifications by using this method.

Class API

class wx.adv.NotificationMessage(EvtHandler)

Possible constructors:

NotificationMessage() -> None

NotificationMessage(title, message='', parent=None,
                    flags=ICON_INFORMATION) -> None

This class allows showing the user a message non intrusively.

Methods

__init__(self, *args, **kw)

Overloaded Implementations:

---

__init__ (self)

Default constructor, use SetParent , SetTitle and SetMessage to initialize the object before showing it.

Return type:

None

---

__init__ (self, title, message=’’, parent=None, flags=ICON_INFORMATION)

Create a notification object with the given attributes.

See SetTitle , SetMessage , SetParent and SetFlags for the description of the corresponding parameters.

Parameters:

• title (string)

• message (string)

• parent (wx.Window)

• flags (int)

Return type:

None

---

---

AddAction(self, actionid, label='')

Add an action to the notification.

If supported by the implementation this are usually buttons in the notification selectable by the user.

Parameters:

• actionid (wx.WindowID)

• label (string)

Return type:

bool

Returns:

False if the current implementation or OS version does not support actions in notifications.

Added in version 4.1/wxWidgets-3.1.0.

---

Close(self)

Hides the notification.

Returns True if it was hidden or False if it couldn’t be done (e.g. on some systems automatically hidden notifications can’t be hidden manually).

Return type:

bool

---

static MSWUseToasts(shortcutPath='', appId='')

Enables toast notifications available since Windows 8 and suppresses the additional icon in the notification area on Windows 10.

Toast notifications require a shortcut to the application in the start menu. The start menu shortcut needs to contain an Application User Model ID. It is recommended that the applications setup creates the shortcut and the application specifies the setup created shortcut in shortcutPath . A call to this method will verify (and if necessary modify) the shortcut before enabling toast notifications.

Parameters:

• shortcutPath (string) – Path to a shortcut file referencing the applications executable. If the string is empty the applications display name will be used. If not fully qualified, it will be used as a path relative to the users start menu directory. The file extension .lnk is optional.

• appId (string) – The applications Application User Model ID. If empty it will be extracted from the shortcut. If the shortcut does not contain an id an id will be automatically created from the applications vendor and app name.

Return type:

bool

Returns:

False if toast notifications could not be enabled.

Added in version 4.1/wxWidgets-3.1.0.

Availability

Only available for MSW.

See also

wx.AppConsole.SetAppName , wx.AppConsole.SetVendorName

---

SetFlags(self, flags)

This parameter can be currently used to specify the icon to show in the notification.

Valid values are ICON_INFORMATION , ICON_WARNING and ICON_ERROR (notice that ICON_QUESTION is not allowed here). Some implementations of this class may not support the icons.

Parameters:

flags (int)

Return type:

None

See also

SetIcon

---

SetIcon(self, icon)

Specify a custom icon to be displayed in the notification.

Some implementations of this class may not support custom icons.

Parameters:

icon (wx.Icon)

Return type:

None

Added in version 4.1/wxWidgets-3.1.0.

See also

SetFlags

---

SetMessage(self, message)

Set the main text of the notification.

This should be a more detailed description than the title but still limited to reasonable length (not more than 256 characters).

Parameters:

message (string)

Return type:

None

---

SetParent(self, parent)

Set the parent for this notification: the notification will be associated with the top level parent of this window or, if this method is not called, with the main application window by default.

Parameters:

parent (wx.Window)

Return type:

None

---

SetTitle(self, title)

Set the title, it must be a concise string (not more than 64 characters), use SetMessage to give the user more details.

Parameters:

title (string)

Return type:

None

---

Show(self, timeout=Timeout_Auto)

Show the notification to the user and hides it after timeout seconds are elapsed.

Special values Timeout_Auto and Timeout_Never can be used here, notice that you shouldn’t rely on timeout being exactly respected because the current platform may only support default timeout value and also because the user may be able to close the notification.

Parameters:

timeout (int)

Return type:

bool

Returns:

False if an error occurred.

Note

When using native notifications in wxGTK, the timeout is ignored for the notifications with ICON_WARNING or ICON_ERROR flags, they always remain shown unless they’re explicitly hidden by the user, i.e. behave as if Timeout_Auto were given.

---

static UseTaskBarIcon(icon)

If the application already uses a wx.adv.TaskBarIcon, it should be connected to notifications by using this method.

This has no effect if toast notifications are used.

Parameters:

icon (wx.adv.TaskBarIcon)

Return type:

wx.adv.TaskBarIcon

Returns:

the task bar icon which was used previously (may be NULL )

Availability

Only available for MSW.