| Version: 3.3.1

Public Types | Public Member Functions | Static Public Member Functions | List of all members
wxNotificationMessage Class Reference
Class List by Category » Miscellaneous

`#include <wx/notifmsg.h>`

Inheritance diagram for wxNotificationMessage:
[legend]

## Detailed Description

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 `wxGenericNotificationMessage` 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 wxWindow.

# 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 wxTaskBarIcon 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

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCommandEvent& event)

Event macros for events emitted by this class:

- EVT_NOTIFICATION_MESSAGE_CLICK(id, func):
  Process a `wxEVT_NOTIFICATION_MESSAGE_CLICK` event, when a notification is clicked.
- EVT_NOTIFICATION_MESSAGE_DISMISSED(id, func):
  Process a `wxEVT_NOTIFICATION_MESSAGE_DISMISSED` event, when a notification is dismissed by the user or times out. Since wxWidgets 3.3.0, on platforms supporting it, the reason for dismissal can be obtained from wxCommandEvent::GetInt(), with values corresponding to those of wxNotificationMessage::DismissalReason.
- EVT_NOTIFICATION_MESSAGE_ACTION(id, func):
  Process a `wxEVT_NOTIFICATION_MESSAGE_ACTION` event, when the user selects on of the actions added by AddAction()

Since
  2.9.0

  ##

Library: wxCore
Category: Miscellaneous

## Public Types
enum | { Timeout_Auto = -1 , Timeout_Never = 0 }
| Possible values for Show() timeout. More...
enum class | DismissalReason { Unknown , ByUser , ByApp , TimedOut }
| Reasons for dismissal, posted with wxEVT_NOTIFICATION_MESSAGE_DISMISSED events. More...

## Public Member Functions
| wxNotificationMessage ()
| Default constructor, use SetParent(), SetTitle() and SetMessage() to initialize the object before showing it. More...
| wxNotificationMessage (const wxString &title, const wxString &message=wxEmptyString, wxWindow *parent=nullptr, int flags=wxICON_INFORMATION)
| Create a notification object with the given attributes. More...
virtual | ~wxNotificationMessage ()
| Destructor does not hide the notification. More...
bool | AddAction (wxWindowID actionid, const wxString &label=wxString())
| Add an action to the notification. More...
bool | Close ()
| Hides the notification. More...
void | SetFlags (int flags)
| This parameter can be currently used to specify the icon to show in the notification. More...
void | SetIcon (const wxIcon &icon)
| Specify a custom icon to be displayed in the notification. More...
void | SetMessage (const wxString &message)
| Set the main text of the notification. More...
void | SetParent (wxWindow *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. More...
void | SetTitle (const wxString &title)
| Set the title, it must be a concise string (not more than 64 characters), use SetMessage() to give the user more details. More...
bool | Show (int timeout=Timeout_Auto)
| Show the notification to the user and hides it after timeout seconds are elapsed. More...
Public Member Functions inherited from wxEvtHandler
| wxEvtHandler ()
| Constructor. More...
virtual | ~wxEvtHandler ()
| Destructor. More...
virtual void | QueueEvent (wxEvent *event)
| Queue event for a later processing. More...
virtual void | AddPendingEvent (const wxEvent &event)
| Post an event to be processed later. More...
template<typename T , typename T1 , ... >
void | CallAfter (void(T::*method)(T1,...), T1 x1,...)
| Asynchronously call the given method. More...
template<typename T >
void | CallAfter (const T &functor)
| Asynchronously call the given functor. More...
virtual bool | ProcessEvent (wxEvent &event)
| Processes an event, searching event tables and calling zero or more suitable event handler function(s). More...
bool | ProcessEventLocally (wxEvent &event)
| Try to process the event in this handler and all those chained to it. More...
bool | SafelyProcessEvent (wxEvent &event)
| Processes an event by calling ProcessEvent() and handles any exceptions that occur in the process. More...
void | ProcessPendingEvents ()
| Processes the pending events previously queued using QueueEvent() or AddPendingEvent(); you must call this function only if you are sure there are pending events for this handler, otherwise a `wxCHECK` will fail. More...
void | DeletePendingEvents ()
| Deletes all events queued on this event handler using QueueEvent() or AddPendingEvent(). More...
void | Connect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| Connects the given function dynamically with the event handler, id and event type. More...
void | Connect (int id, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
void | Connect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
bool | Disconnect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| Disconnects the given function dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
bool | Disconnect (int id=wxID_ANY, wxEventType eventType=wxEVT_NULL, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
bool | Disconnect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
| See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
template<typename EventTag , typename Functor >
void | Bind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| Binds the given function, functor or method dynamically with the event. More...
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
void | Bind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
template<typename EventTag , typename Functor >
bool | Unbind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| Unbinds the given function, functor or method dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
bool | Unbind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
| See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
void * | GetClientData () const
| Returns user-supplied client data. More...
wxClientData * | GetClientObject () const
| Returns a pointer to the user-supplied client data object. More...
void | SetClientData (void *data)
| Sets user-supplied client data. More...
void | SetClientObject (wxClientData *data)
| Set the client data object. More...
bool | GetEvtHandlerEnabled () const
| Returns true if the event handler is enabled, false otherwise. More...
wxEvtHandler * | GetNextHandler () const
| Returns the pointer to the next handler in the chain. More...
wxEvtHandler * | GetPreviousHandler () const
| Returns the pointer to the previous handler in the chain. More...
void | SetEvtHandlerEnabled (bool enabled)
| Enables or disables the event handler. More...
virtual void | SetNextHandler (wxEvtHandler *handler)
| Sets the pointer to the next handler. More...
virtual void | SetPreviousHandler (wxEvtHandler *handler)
| Sets the pointer to the previous handler. More...
void | Unlink ()
| Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted). More...
bool | IsUnlinked () const
| Returns true if the next and the previous handler pointers of this event handler instance are nullptr. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to nullptr the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## Static Public Member Functions
static wxTaskBarIcon * | UseTaskBarIcon (wxTaskBarIcon *icon)
| If the application already uses a wxTaskBarIcon, it should be connected to notifications by using this method. More...
static bool | MSWUseToasts (const wxString &shortcutPath=wxString(), const wxString &appId=wxString())
| Enables toast notifications available since Windows 8 and suppresses the additional icon in the notification area on Windows 10. More...
Static Public Member Functions inherited from wxEvtHandler
static void | AddFilter (wxEventFilter *filter)
| Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets. More...
static void | RemoveFilter (wxEventFilter *filter)
| Remove a filter previously installed with AddFilter(). More...

## Additional Inherited Members
Protected Member Functions inherited from wxEvtHandler
virtual bool | TryBefore (wxEvent &event)
| Method called by ProcessEvent() before examining this object event tables. More...
virtual bool | TryAfter (wxEvent &event)
| Method called by ProcessEvent() as last resort. More...
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

Possible values for Show() timeout.

Enumerator
Timeout_Auto | Notification will be hidden automatically.
Timeout_Never | Notification will never time out.

## ◆ DismissalReason

enum wxNotificationMessage::DismissalReason
| strong

Reasons for dismissal, posted with wxEVT_NOTIFICATION_MESSAGE_DISMISSED events.

Since
  3.3.0

Enumerator
Unknown | Reason unknown, possibly unsupported on this platform.
ByUser | The user dismissed the notification.
ByApp | The application itself closed the notification.
TimedOut | The notification expired after reaching its timeout.

## Constructor & Destructor Documentation

## ◆ wxNotificationMessage() [1/2]

wxNotificationMessage::wxNotificationMessage | ( |  | ) |

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

## ◆ wxNotificationMessage() [2/2]

wxNotificationMessage::wxNotificationMessage | ( | const wxString & | title,
|  | const wxString & | message = `wxEmptyString`,
|  | wxWindow * | parent = `nullptr`,
|  | int | flags = `wxICON_INFORMATION`
| ) |  |

Create a notification object with the given attributes.

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

## ◆ ~wxNotificationMessage()

virtual wxNotificationMessage::~wxNotificationMessage | ( |  | ) |
| virtual

Destructor does not hide the notification.

The notification can continue to be shown even after the C++ object was destroyed, call Close() explicitly if it needs to be hidden.

## Member Function Documentation

## ◆ AddAction()

bool wxNotificationMessage::AddAction | ( | wxWindowID | actionid,
|  | const wxString & | label = `wxString()`
| ) |  |

Add an action to the notification.

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

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

Since
  3.1.0

## ◆ Close()

bool wxNotificationMessage::Close | ( |  | ) |

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

## ◆ MSWUseToasts()

static bool wxNotificationMessage::MSWUseToasts | ( | const wxString & | shortcutPath = `wxString()`,
|  | const wxString & | appId = `wxString()`
| ) |  |
| static

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

Returns
  false if toast notifications could not be enabled.

Availability: only available for the wxMSW port.

See also
  wxAppConsole::SetAppName(), wxAppConsole::SetVendorName()

Since
  3.1.0

## ◆ SetFlags()

void wxNotificationMessage::SetFlags | ( | int | flags | ) |

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

Valid values are `wxICON_INFORMATION`, `wxICON_WARNING` and `wxICON_ERROR` (notice that `wxICON_QUESTION` is not allowed here). Some implementations of this class may not support the icons.

See also
  SetIcon()

## ◆ SetIcon()

void wxNotificationMessage::SetIcon | ( | const wxIcon & | icon | ) |

Specify a custom icon to be displayed in the notification.

Some implementations of this class may not support custom icons.

See also
  SetFlags()

Since
  3.1.0

## ◆ SetMessage()

void wxNotificationMessage::SetMessage | ( | const wxString & | 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).

## ◆ SetParent()

void wxNotificationMessage::SetParent | ( | wxWindow * | 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.

## ◆ SetTitle()

void wxNotificationMessage::SetTitle | ( | const wxString & | title | ) |

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

## ◆ Show()

bool wxNotificationMessage::Show | ( | int | 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.

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

Returns
  false if an error occurred.

## ◆ UseTaskBarIcon()

static wxTaskBarIcon* wxNotificationMessage::UseTaskBarIcon | ( | wxTaskBarIcon * | icon | ) |
| static

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

This has no effect if toast notifications are used.

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

Availability: only available for the wxMSW port.