From 3e588d5bcc1d9fc223084f494b4a1c6112897ba9 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Wed, 10 Jun 2026 17:29:25 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_events.h | 7 +-
include/SDL3/SDL_notification.h | 191 +++++++++++++++++---------------
2 files changed, 104 insertions(+), 94 deletions(-)
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index bdb1128dedf79..b2dbdd5252742 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -771,9 +771,10 @@ typedef struct SDL_CameraDeviceEvent
/**
* Notification dialog event structure (event.notification.*)
*
- * An `action_id` value of 'default' for an SDL_EVENT_NOTIFICATION_ACTION_INVOKED
- * event indicates that the notification was interacted with without selecting a
- * specific action (e.g. the body of the notification was clicked on).
+ * An `action_id` value of 'default' for an
+ * SDL_EVENT_NOTIFICATION_ACTION_INVOKED event indicates that the notification
+ * was interacted with without selecting a specific action (e.g. the body of
+ * the notification was clicked on).
*
* \since This struct is available since SDL 3.6.0.
*/
diff --git a/include/SDL3/SDL_notification.h b/include/SDL3/SDL_notification.h
index a18e44fbc0fa3..3e7e5d5265d5d 100644
--- a/include/SDL3/SDL_notification.h
+++ b/include/SDL3/SDL_notification.h
@@ -60,19 +60,20 @@ extern "C" {
#endif
/**
- * 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
+ * The path to an image to be used as the header icon for system notifications
+ * on some platforms.
*
- * Image types supported depend on the platform, but .png generally offers the best
- * compatability.
+ * This is required on: - Windows - *nix when not running in a container, and
+ * no .desktop entry is available
*
- * On *nix platforms, this can also be the name of a system icon, as specified by
- * the Icon Naming Specification.
+ * Image types supported depend on the platform, but .png generally offers the
+ * best compatability.
*
- * Can be set before calling SDL_ShowNotification() or SDL_ShowSimpleNotification()
- * for the first time.
+ * 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.
*/
@@ -95,14 +96,15 @@ typedef enum SDL_NotificationActionType
/**
* Notification structure describing actions that can be used to allow users
- * to interact with notification dialogs. Exactly How they are presented depends
- * on the platform and implementation.
+ * to interact with notification dialogs.
+ *
+ * Exactly How they are presented depends on the platform and implementation.
*
* User interactions with a notification are reported via events with the type
* SDL_EVENT_NOTIFICATION_ACTION_INVOKED.
*
- * Action types:
- * - button: A button with a localized text label, which generates feedback when activated.
+ * Action types: - button: A button with a localized text label, which
+ * generates feedback when activated.
*
* \sa SDL_NotificationEvent
* \sa SDL_NotificationActionType
@@ -132,116 +134,123 @@ typedef union SDL_NotificationAction
#define SDL_PROP_NOTIFICATION_TITLE_STRING "SDL.notification.title"
/**
- * 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.
+ * 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.
+ * \returns True on success or false on failure; call SDL_GetError() for more
+ * information.
*
- * \since This function is available since SDL 3.6.0
+ * \since This function is available since SDL 3.6.0.
*
- * \sa SDL_ShowNotification
- * \sa SDL_ShowNotificationWithProperties
- * \sa SDL_NotificationAction
+ * \sa SDL_ShowNotification
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_NotificationAction
*/
extern SDL_DECLSPEC bool SDLCALL SDL_RequestNotificationPermission(void);
/**
- * Show a system notification.
+ * 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.
+ * 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:
+ * 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
+ * - `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.
+ * - `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
+ * 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
*
- * \param 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.
+ * \param 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
+ * \since This function is available since SDL 3.6.0.
*
- * \sa SDL_ShowNotification
- * \sa SDL_NotificationAction
- * \sa SDL_NotificationPriority
- * \sa SDL_NotificationEvent
+ * \sa SDL_ShowNotification
+ * \sa SDL_NotificationAction
+ * \sa SDL_NotificationPriority
+ * \sa SDL_NotificationEvent
*/
extern SDL_DECLSPEC SDL_NotificationID SDLCALL SDL_ShowNotificationWithProperties(SDL_PropertiesID props);
/**
- * Show a system notification with normal priority.
+ * Show a system notification with normal priority.
*
- * \param title UTF-8 title text, required.
- * \param message UTF-8 message text, may be NULL.
- * \param image The image associated with this notification, may be NULL.
- * \param actions An array of actions to attach to the notification, may be NULL.
- * \param 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.
+ * \param title UTF-8 title text, required.
+ * \param message UTF-8 message text, may be NULL.
+ * \param image The image associated with this notification, may be NULL.
+ * \param actions An array of actions to attach to the notification, may be
+ * NULL.
+ * \param 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
+ * \since This function is available since SDL 3.6.0.
*
- * \sa SDL_ShowNotificationWithProperties
- * \sa SDL_NotificationAction
- * \sa SDL_NotificationEvent
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_NotificationAction
+ * \sa SDL_NotificationEvent
*/
extern SDL_DECLSPEC SDL_NotificationID SDLCALL SDL_ShowNotification(const char *title, const char *message, SDL_Surface *image, SDL_NotificationAction *actions, int num_actions);
/**
- * Remove a notification.
+ * Remove a notification.
*
- * \param notification the ID of the notification to remove.
- * \returns True on success or false on failure; call
- * SDL_GetError() for more information.
+ * \param 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
+ * \since This function is available since SDL 3.6.0.
*
- * \sa SDL_ShowNotificationWithProperties
- * \sa SDL_ShowNotification
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_ShowNotification
*/
extern SDL_DECLSPEC bool SDLCALL SDL_RemoveNotification(SDL_NotificationID notification);