mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-06-14 07:34:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source 
[ci skip]
This commit is contained in:
SDL Wiki Bot
2026-06-10 17:29:25 +00:00
parent 595eb8d0d1
commit 3e588d5bcc
2 changed files with 104 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
include/SDL3/SDL_events.h
View File

@@ -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.
*/

191
include/SDL3/SDL_notification.h
View File

@@ -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.
*
* \returns True on success or false on failure; call
* SDL_GetError() for more information.
* 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.
*
* \since This function is available since SDL 3.6.0
* \returns True on success or false on failure; call SDL_GetError() for more
* information.
*
* \sa SDL_ShowNotification
* \sa SDL_ShowNotificationWithProperties
* \sa SDL_NotificationAction
* \since This function is available since SDL 3.6.0.
*
* \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);