#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>

Include dependency graph for SDL_notification.h:

This graph shows which files directly or indirectly include this file:

Data Structures
union	SDL_NotificationAction

Macros
#define	SDL_PROP_GLOBAL_NOTIFICATION_HEADER_ICON_STRING "SDL.notification.header_icon"
#define	SDL_PROP_NOTIFICATION_ACTIONS_POINTER "SDL.notification.actions"
#define	SDL_PROP_NOTIFICATION_ACTION_COUNT_NUMBER "SDL.notification.action_count"
#define	SDL_PROP_NOTIFICATION_IMAGE_POINTER "SDL.notification.image"
#define	SDL_PROP_NOTIFICATION_MESSAGE_STRING "SDL.notification.message"
#define	SDL_PROP_NOTIFICATION_PRIORITY_NUMBER "SDL.notification.priority"
#define	SDL_PROP_NOTIFICATION_REPLACES_NUMBER "SDL.notification.replaces"
#define	SDL_PROP_NOTIFICATION_SOUND_STRING "SDL.notification.sound"
#define	SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN "SDL.notification.transient"
#define	SDL_PROP_NOTIFICATION_TITLE_STRING "SDL.notification.title"

Typedefs
typedef Uint32	SDL_NotificationID

Enumerations
enum	SDL_NotificationPriority { SDL_NOTIFICATION_PRIORITY_LOW = -1 , SDL_NOTIFICATION_PRIORITY_NORMAL = 0 , SDL_NOTIFICATION_PRIORITY_HIGH = 1 , SDL_NOTIFICATION_PRIORITY_CRITICAL = 2 }
enum	SDL_NotificationActionType { SDL_NOTIFICATION_ACTION_TYPE_BUTTON = 1 }

Functions
bool	SDL_RequestNotificationPermission (void)
SDL_NotificationID	SDL_ShowNotificationWithProperties (SDL_PropertiesID props)
SDL_NotificationID	SDL_ShowNotification (const char title, const char message, SDL_Surface image, SDL_NotificationAction actions, int num_actions)
bool	SDL_RemoveNotification (SDL_NotificationID notification)

Macro Definition Documentation

◆ SDL_PROP_GLOBAL_NOTIFICATION_HEADER_ICON_STRING

#define SDL_PROP_GLOBAL_NOTIFICATION_HEADER_ICON_STRING "SDL.notification.header_icon"

CategoryNotifications

Notifications are temporary popup dialogs that passively present information to the user, or prompt user action. They are managed and presented by the system, and can present simple options for user feedback, usually in the form of buttons.

The capabilities of notifications, and how they are displayed, vary between systems, but they generally allow for a title, message body, an associated image, and buttons to allow the user to provide feedback.

How notifications are presented and handled are subject to system policy, and it should not be assumed that showing a notification means that the user will see it immediately, if at all. The user may disable notifications for certain applications, they may be suppressed based on the current activity, and most systems provide a "do not disturb" mode that universally silences notifications when activated.

There is both a customizable function SDL_ShowNotificationWithProperties() that offers many options for what is displayed, and also a much-simplified version SDL_ShowSimpleNotification(), which simply takes a header (required), body (optional), and image (optional). The path to an image to be used as the header icon for system notifications on some platforms.

This is required on: - Windows - *nix when not running in a container, and no .desktop entry is available

Image types supported depend on the platform, but .png generally offers the best compatability.

On *nix platforms, this can also be the name of a system icon, as specified by the Icon Naming Specification.

Can be set before calling SDL_ShowNotification() or SDL_ShowSimpleNotification() for the first time.

Since: This macro is available since SDL 3.6.0.

Definition at line 80 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_ACTION_COUNT_NUMBER

#define SDL_PROP_NOTIFICATION_ACTION_COUNT_NUMBER "SDL.notification.action_count"

Definition at line 127 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_ACTIONS_POINTER

#define SDL_PROP_NOTIFICATION_ACTIONS_POINTER "SDL.notification.actions"

Definition at line 126 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_IMAGE_POINTER

#define SDL_PROP_NOTIFICATION_IMAGE_POINTER "SDL.notification.image"

Definition at line 128 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_MESSAGE_STRING

#define SDL_PROP_NOTIFICATION_MESSAGE_STRING "SDL.notification.message"

Definition at line 129 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_PRIORITY_NUMBER

#define SDL_PROP_NOTIFICATION_PRIORITY_NUMBER "SDL.notification.priority"

Definition at line 130 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_REPLACES_NUMBER

#define SDL_PROP_NOTIFICATION_REPLACES_NUMBER "SDL.notification.replaces"

Definition at line 131 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_SOUND_STRING

#define SDL_PROP_NOTIFICATION_SOUND_STRING "SDL.notification.sound"

Definition at line 132 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_TITLE_STRING

#define SDL_PROP_NOTIFICATION_TITLE_STRING "SDL.notification.title"

Definition at line 134 of file SDL_notification.h.

◆ SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN

#define SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN "SDL.notification.transient"

Definition at line 133 of file SDL_notification.h.

Typedef Documentation

◆ SDL_NotificationID

typedef Uint32 SDL_NotificationID

The identifier for a system notification.

Definition at line 82 of file SDL_notification.h.

Enumeration Type Documentation

◆ SDL_NotificationActionType

enum SDL_NotificationActionType

Enumerator
SDL_NOTIFICATION_ACTION_TYPE_BUTTON	Adds a button to the notification that generates feedback when activated.

Definition at line 92 of file SDL_notification.h.

{
    SDL_NOTIFICATION_ACTION_TYPE_BUTTON = 1 /**< Adds a button to the notification that generates feedback when activated. */
} SDL_NotificationActionType;

◆ SDL_NotificationPriority

enum SDL_NotificationPriority

Enumerator
SDL_NOTIFICATION_PRIORITY_LOW	Lowest priority.
SDL_NOTIFICATION_PRIORITY_NORMAL	Normal/medium priority.
SDL_NOTIFICATION_PRIORITY_HIGH	High/important priority.
SDL_NOTIFICATION_PRIORITY_CRITICAL	Highest/critical priority. Note that this may override any "Do Not Disturb" settings and wake the screen.

Definition at line 84 of file SDL_notification.h.

{
    SDL_NOTIFICATION_PRIORITY_LOW = -1,    /**< Lowest priority. */
    SDL_NOTIFICATION_PRIORITY_NORMAL = 0,  /**< Normal/medium priority. */
    SDL_NOTIFICATION_PRIORITY_HIGH = 1,    /**< High/important priority. */
    SDL_NOTIFICATION_PRIORITY_CRITICAL = 2 /**< Highest/critical priority. Note that this may override any "Do Not Disturb" settings and wake the screen. */
} SDL_NotificationPriority;

Function Documentation

◆ SDL_RemoveNotification()

bool SDL_RemoveNotification ( SDL_NotificationID notification )

extern

Remove a notification.

Parameters

notification the ID of the notification to remove.

Returns: True on success or false on failure; call SDL_GetError() for more information.

Since: This function is available since SDL 3.6.0.

See also: SDL_ShowNotificationWithProperties; SDL_ShowNotification

◆ SDL_RequestNotificationPermission()

bool SDL_RequestNotificationPermission ( void )

extern

Requests permission from the system to display notifications.

A return value of true only means that the system supports notifications, and that the request for permission was successfully issued. It does not reflect any user settings to allow or deny notifications.

Returns: True on success or false on failure; call SDL_GetError() for more information.

Since: This function is available since SDL 3.6.0.

See also: SDL_ShowNotification; SDL_ShowNotificationWithProperties; SDL_NotificationAction

◆ SDL_ShowNotification()

SDL_NotificationID SDL_ShowNotification	(	const char *	title,
		const char *	message,
		SDL_Surface *	image,
		SDL_NotificationAction *	actions,
		int	num_actions )

extern

Show a system notification with normal priority.

Parameters

title	UTF-8 title text, required.
message	UTF-8 message text, may be NULL.
image	The image associated with this notification, may be NULL.
actions	An array of actions to attach to the notification, may be NULL.
num_actions	The number of actions in the actions array.

Returns: A non-zero SDL_NotificationID on success or 0 on failure; call SDL_GetError() for more information.

Since: This function is available since SDL 3.6.0.

See also: SDL_ShowNotificationWithProperties; SDL_NotificationAction; SDL_NotificationEvent

◆ SDL_ShowNotificationWithProperties()

SDL_NotificationID SDL_ShowNotificationWithProperties ( SDL_PropertiesID props )

extern

Show a system notification.

System notifications are small, asynchronous popup windows that notify the user of some information. How they are displayed is system dependent.

These are the supported properties:

SDL_PROP_NOTIFICATION_TITLE_STRING: the title of the notification, in UTF-8 encoding. This property is required.
SDL_PROP_NOTIFICATION_ACTIONS_POINTER: An array of pointers to SDL_NotificationAction structs that will add actions to the notification, usually in the form of buttons or menu items. Note that systems may have a limit on the maximum number of actions that a notification can have.
SDL_PROP_NOTIFICATIONS_ACTION_COUNT_NUMBER: the number of actions in the array of actions, if it exists.
SDL_PROP_NOTIFICATION_IMAGE_POINTER: a pointer to an SDL_Surface containing an image that will be attached to the notification. In most cases, the image is displayed in the form of a large icon or thumbnail alongside the message body. Notifications on Apple platforms can be expanded to show a larger format image.
SDL_PROP_NOTIFICATION_MESSAGE_STRING: the message body of the notification, in UTF-8 encoding.
SDL_PROP_NOTIFICATION_PRIORITY_NUMBER: an SDL_NotificationPriority value representing the notification priority.
SDL_PROP_NOTIFICATION_REPLACES_NUMBER: the SDL_NotificationID of a previously shown notification that this notification should replace.
SDL_PROP_NOTIFICATION_SOUND_STRING: sets a sound to play when the notification is shown. This can have the value "default", to play the system default notification sound, "silent", to play no sound, or contain the path to a file with a custom sound. The paths and formats that can be used for custom sounds are system-specific, and can have some restrictions, depending on the platform:
Apple platforms require that the sound file is contained within the app bundle. Supported formats are: Linear PCM, MA4 (IMA/ADPCM), uLaw, or aLaw, in an .aiff, .wav, or .caf file.
Windows can only play custom notification sounds when the app is packaged inside an MSIX installer. Playback from arbitrary file paths is not supported. Supported formats are: .aac, .flac, .m4a, .mp3, .wav, and .wma.
Unix platforms can generally load sounds from any arbitrary path, as long as the read permissions are correct. Supported formats are: ogg/opus, ogg/vorbis, and wav/pcm. If this property is not set, the system default sound will be used.
SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN: true if the notification should not persist in the system notification center after initially being shown.

Not all properties are supported by all platforms.

Notifications are available on: - Windows 10 or higher - macOS 10.14 or higher - iOS 11 or higher - *nix platforms that support the org.freedesktop.Notifications, or org.freedesktop.portal.Notification interfaces

Parameters

props the properties to be used when creating this notification.

Returns: A non-zero SDL_NotificationID on success or 0 on failure; call SDL_GetError() for more information.

Since: This function is available since SDL 3.6.0.

See also: SDL_ShowNotification; SDL_NotificationAction; SDL_NotificationPriority; SDL_NotificationEvent

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ SDL_PROP_GLOBAL_NOTIFICATION_HEADER_ICON_STRING

CategoryNotifications

◆ SDL_PROP_NOTIFICATION_ACTION_COUNT_NUMBER

◆ SDL_PROP_NOTIFICATION_ACTIONS_POINTER

◆ SDL_PROP_NOTIFICATION_IMAGE_POINTER

◆ SDL_PROP_NOTIFICATION_MESSAGE_STRING

◆ SDL_PROP_NOTIFICATION_PRIORITY_NUMBER

◆ SDL_PROP_NOTIFICATION_REPLACES_NUMBER

◆ SDL_PROP_NOTIFICATION_SOUND_STRING

◆ SDL_PROP_NOTIFICATION_TITLE_STRING

◆ SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN

Typedef Documentation

◆ SDL_NotificationID

Enumeration Type Documentation

◆ SDL_NotificationActionType

◆ SDL_NotificationPriority

Function Documentation

◆ SDL_RemoveNotification()

◆ SDL_RequestNotificationPermission()

◆ SDL_ShowNotification()

◆ SDL_ShowNotificationWithProperties()