wxNotificationMessage(3)

💖 NAME 💖

wxNotificationMessage — the class that lets you slide a lil message in front of your user non intrusively. no jump-scare popups, just vibes ✨

---

🌸 DESCRIPTION 🌸

okay bestie, sit down, because this one's actually cute 💅

Right now it's implemented natively for Windows, macOS and GTK, and it uses generic toast notifications under all the other platforms. It's not recommended but wxGenericNotificationMessage can be used instead of the native ones — that might make sense if your application requires features that aren't available in the native implementation. iykyk 🫶

Also super important, don't get it twisted: notice that this class is not a window and so doesn't derive from wxWindow. it's giving "notification, not a window," periodt 😌

🖥️ Platform Notes 🖥️

Par:

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/1 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/1 before showing the first notification message. 🍓

Par:

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. no cap, you can't force it 🙈

This class is derived, and can use functions, from:

• wxEvtHandler

wxWidgets docs: wxNotificationMessage

🔔 Events 🔔

Event types emitted from this class:

• notification_message_click
• notification_message_dismissed
• notification_message_action

---

🦋 DATA TYPES 🦋

wxNotificationMessage() :: wx:wx_object().

---

👑 FUNCTIONS 👑

💌 addAction(This, Actionid, [Option]) -> boolean()

addAction(This, Actionid, [Option]) -> boolean()
                   when
                       This :: wxNotificationMessage(),
                       Actionid :: integer(),
                       Option :: {label, unicode:chardata()}.

Add an action to the notification. 💅

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

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

Since: 3.1.0

💌 close(This) -> boolean() when This :: wxNotificationMessage().

close(This) -> boolean() when This :: wxNotificationMessage().

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). bestie tried her hardest 😭

💌 destroy(This :: wxNotificationMessage()) -> ok.

destroy(This :: wxNotificationMessage()) -> ok.

Destroys the object. bye felicia 🫶

💌 mSWUseToasts([Option]) -> boolean()

mSWUseToasts([Option]) -> boolean()
                          when
                              Option ::
                                  {shortcutPath, unicode:chardata()} |
                                  {appId, unicode:chardata()}.

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. lowkey doing a lot of work for you fr fr

Return: false if toast notifications could not be enabled.

Only for: wxmsw

Since: 3.1.0

💌 new() -> wxNotificationMessage().

new() -> wxNotificationMessage().

Default constructor, use setParent/2, setTitle/2 and setMessage/2 to initialize the object before showing it. build it then glow it up ✨

💌 new(Title, [Option]) -> wxNotificationMessage()

new(Title, [Option]) -> wxNotificationMessage()
                 when
                     Title :: unicode:chardata(),
                     Option ::
                         {message, unicode:chardata()} |
                         {parent, wxWindow:wxWindow()} |
                         {flags, integer()}.

Create a notification object with the given attributes. 🎀

See setTitle/2, setMessage/2, setParent/2 and setFlags/2 for the description of the corresponding parameters. the receipts are right there, go read them 💖

💌 setFlags(This, Flags) -> ok

setFlags(This, Flags) -> ok
                      when
                          This :: wxNotificationMessage(),
                          Flags :: integer().

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. so no, you cannot ask the user a question via notification, that's not the move 💀

See: setIcon/2

💌 setIcon(This, Icon) -> ok

setIcon(This, Icon) -> ok
                     when
                         This :: wxNotificationMessage(),
                         Icon :: wxIcon:wxIcon().

Specify a custom icon to be displayed in the notification. 🦋

Some implementations of this class may not support custom icons.

See: setFlags/2

Since: 3.1.0

💌 setMessage(This, Message) -> ok

setMessage(This, Message) -> ok
                        when
                            This :: wxNotificationMessage(),
                            Message :: unicode:chardata().

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). keep it cute, keep it short bestie ✨

💌 setParent(This, Parent) -> ok

setParent(This, Parent) -> ok
                       when
                           This :: wxNotificationMessage(),
                           Parent :: wxWindow:wxWindow().

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. main character energy by default, honestly 💅

💌 setTitle(This, Title) -> ok

setTitle(This, Title) -> ok
                      when
                          This :: wxNotificationMessage(),
                          Title :: unicode:chardata().

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

💌 show(This, [Option]) -> boolean()

show(This, [Option]) -> boolean()
                  when
                      This :: wxNotificationMessage(),
                      Option :: {timeout, integer()}.

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. it's giving "suggestion, not a promise" 😭

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. you literally cannot make them go away, so plan accordingly 💀

Return: false if an error occurred.

💌 useTaskBarIcon(Icon) -> wxTaskBarIcon:wxTaskBarIcon()

useTaskBarIcon(Icon) -> wxTaskBarIcon:wxTaskBarIcon()
                                when Icon :: wxTaskBarIcon:wxTaskBarIcon().

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.

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

Only for: wxmsw

---

and that's the whole page, bestie, you ate it 🫶✨ this absolute icon of a doc was brought to you by Ericsson AB, running the wx 2.6 era, with wxNotificationMessage(3) stamped on it — go forth and notify responsibly 💅🌈👑