diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index bdb1128ded..b2dbdd5252 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 a18e44fbc0..3e7e5d5265 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. * - * \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);