Add notification framework with test and dummy driver

src/SDL.c

@@ -44,9 +44,12 @@
 #include "camera/SDL_camera_c.h"
 #include "cpuinfo/SDL_cpuinfo_c.h"
 #include "events/SDL_events_c.h"
+#include "filesystem/SDL_filesystem_c.h"
 #include "haptic/SDL_haptic_c.h"
+#include "io/SDL_asyncio_c.h"
 #include "joystick/SDL_gamepad_c.h"
 #include "joystick/SDL_joystick_c.h"
+#include "notification/SDL_notification_c.h"
 #include "render/SDL_sysrender.h"
 #include "sensor/SDL_sensor_c.h"
 #include "stdlib/SDL_getenv_c.h"
@@ -55,8 +58,6 @@
 #include "video/SDL_pixels_c.h"
 #include "video/SDL_surface_c.h"
 #include "video/SDL_video_c.h"
-#include "filesystem/SDL_filesystem_c.h"
-#include "io/SDL_asyncio_c.h"
 #ifdef SDL_PLATFORM_ANDROID
 #include "core/android/SDL_android.h"
 #endif
@@ -710,6 +711,7 @@ void SDL_Quit(void)
 #endif
     SDL_QuitSubSystem(SDL_ALL_SUBSYSTEM_FLAGS);
     SDL_CleanupTrays();
+    SDL_CleanupNotifications();
 
 #ifdef SDL_USE_LIBDBUS
     SDL_DBus_Quit();

src/dynapi/SDL_dynapi.exports

@@ -1294,3 +1294,7 @@ _SDL_aligned_alloc_zero
 _SDL_wcstoul
 _SDL_wcstoll
 _SDL_wcstoull
+_SDL_RequestNotificationPermission
+_SDL_ShowNotificationWithProperties
+_SDL_ShowNotification
+_SDL_RemoveNotification

src/dynapi/SDL_dynapi.sym

@@ -1295,6 +1295,10 @@ SDL3_0.0.0 {
     SDL_wcstoul;
     SDL_wcstoll;
     SDL_wcstoull;
+    SDL_RequestNotificationPermission;
+    SDL_ShowNotificationWithProperties;
+    SDL_ShowNotification;
+    SDL_RemoveNotification;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -1321,3 +1321,7 @@
 #define SDL_wcstoul SDL_wcstoul_REAL
 #define SDL_wcstoll SDL_wcstoll_REAL
 #define SDL_wcstoull SDL_wcstoull_REAL
+#define SDL_RequestNotificationPermission SDL_RequestNotificationPermission_REAL
+#define SDL_ShowNotificationWithProperties SDL_ShowNotificationWithProperties_REAL
+#define SDL_ShowNotification SDL_ShowNotification_REAL
+#define SDL_RemoveNotification SDL_RemoveNotification_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -1329,3 +1329,7 @@ SDL_DYNAPI_PROC(void*,SDL_aligned_alloc_zero,(size_t a,size_t b),(a,b),return)
 SDL_DYNAPI_PROC(unsigned long,SDL_wcstoul,(const wchar_t *a,wchar_t **b,int c),(a,b,c),return)
 SDL_DYNAPI_PROC(long long,SDL_wcstoll,(const wchar_t *a,wchar_t **b,int c),(a,b,c),return)
 SDL_DYNAPI_PROC(unsigned long long,SDL_wcstoull,(const wchar_t *a,wchar_t **b,int c),(a,b,c),return)
+SDL_DYNAPI_PROC(bool,SDL_RequestNotificationPermission,(void),(),return)
+SDL_DYNAPI_PROC(SDL_NotificationID,SDL_ShowNotificationWithProperties,(SDL_PropertiesID a),(a),return)
+SDL_DYNAPI_PROC(SDL_NotificationID,SDL_ShowNotification,(const char *a,const char *b,SDL_Surface *c,SDL_NotificationAction *d,int e),(a,b,c,d,e),return)
+SDL_DYNAPI_PROC(bool,SDL_RemoveNotification,(SDL_NotificationID a),(a),return)

src/events/SDL_categories.c

@@ -185,6 +185,9 @@ SDL_EventCategory SDL_GetEventCategory(Uint32 type)
     case SDL_EVENT_CAMERA_DEVICE_APPROVED:
     case SDL_EVENT_CAMERA_DEVICE_DENIED:
         return SDL_EVENTCATEGORY_CDEVICE;
+
+    case SDL_EVENT_NOTIFICATION_ACTION_INVOKED:
+        return SDL_EVENTCATEGORY_NOTIFICATION;
     }
 }
 

src/events/SDL_categories_c.h

@@ -64,6 +64,7 @@ typedef enum SDL_EventCategory
     SDL_EVENTCATEGORY_DROP,
     SDL_EVENTCATEGORY_CLIPBOARD,
     SDL_EVENTCATEGORY_RENDER,
+    SDL_EVENTCATEGORY_NOTIFICATION,
 } SDL_EventCategory;
 
 extern SDL_EventCategory SDL_GetEventCategory(Uint32 type);

src/events/SDL_events.c

@@ -911,6 +911,11 @@ int SDL_GetEventDescription(const SDL_Event *event, char *buf, int buflen)
         break;
 #undef PRINT_CAMERADEV_EVENT
 
+        SDL_EVENT_CASE(SDL_EVENT_NOTIFICATION_ACTION_INVOKED)
+        (void)SDL_snprintf(details, sizeof(details), " (timestamp=%" SDL_PRIu64 " which=%d button_id='%s')",
+                           event->notification.timestamp, (uint)event->notification.which, event->notification.action_id);
+        break;
+
         SDL_EVENT_CASE(SDL_EVENT_SENSOR_UPDATE)
         (void)SDL_snprintf(details, sizeof(details), " (timestamp=%" SDL_PRIu64 " which=%d data[0]=%f data[1]=%f data[2]=%f data[3]=%f data[4]=%f data[5]=%f)",
                            event->sensor.timestamp, (int)event->sensor.which,

src/events/SDL_notificationevents.c

@@ -0,0 +1,41 @@
+
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+#include "SDL_internal.h"
+
+#include "SDL_events_c.h"
+#include "SDL_notificationevents_c.h"
+
+bool SDL_SendNotificationAction(SDL_NotificationID notification_id, const char *action_id)
+{
+    if (SDL_EventEnabled(SDL_EVENT_NOTIFICATION_ACTION_INVOKED)) {
+        SDL_Event event;
+        event.type = SDL_EVENT_NOTIFICATION_ACTION_INVOKED;
+
+        SDL_NotificationEvent *nevent = &event.notification;
+        nevent->timestamp = 0;
+        nevent->which = notification_id;
+        nevent->action_id = SDL_CreateTemporaryString(action_id);
+        return SDL_PushEvent(&event);
+    }
+
+    return false;
+}

src/events/SDL_notificationevents_c.h

@@ -0,0 +1,30 @@
+
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+#include "SDL_internal.h"
+
+#ifndef SDL_notificationevents_c_h_
+#define SDL_notificationevents_c_h_
+
+extern bool SDL_SendNotificationAction(SDL_NotificationID notification_id, const char *action_id);
+
+#endif // SDL_notificationevents_c_h_
+

src/notification/SDL_notification.c

@@ -0,0 +1,85 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+#include "SDL_internal.h"
+
+#include "SDL_notification_c.h"
+#include <SDL3/SDL_properties.h>
+
+SDL_NotificationID SDL_ShowNotificationWithProperties(SDL_PropertiesID props)
+{
+    if (!props) {
+        SDL_InvalidParamError("props");
+        return 0;
+    }
+
+    // The title property is required.
+    CHECK_PARAM (true) {
+        const char *title = SDL_GetStringProperty(props, SDL_PROP_NOTIFICATION_TITLE_STRING, NULL);
+        if (!title) {
+            SDL_SetError("Notifications must have a title");
+            return 0;
+        }
+    }
+
+    return SDL_SYS_ShowNotification(props);
+}
+
+SDL_NotificationID SDL_ShowNotification(const char *title, const char *message, SDL_Surface *image, SDL_NotificationAction *actions, int num_actions)
+{
+    SDL_NotificationID id = 0;
+    SDL_PropertiesID props = SDL_CreateProperties();
+    if (!props) {
+        return 0;
+    }
+
+    if (title) {
+        if (!SDL_SetStringProperty(props, SDL_PROP_NOTIFICATION_TITLE_STRING, title)) {
+            goto cleanup;
+        }
+    } else {
+        SDL_SetError("Notifications must have a title");
+        goto cleanup;
+    }
+    if (message) {
+        if (!SDL_SetStringProperty(props, SDL_PROP_NOTIFICATION_MESSAGE_STRING, message)) {
+            goto cleanup;
+        }
+    }
+    if (image) {
+        if (!SDL_SetPointerProperty(props, SDL_PROP_NOTIFICATION_IMAGE_POINTER, image)) {
+            goto cleanup;
+        }
+    }
+    if (actions && num_actions) {
+        if (!SDL_SetPointerProperty(props, SDL_PROP_NOTIFICATION_ACTIONS_POINTER, actions)) {
+            goto cleanup;
+        }
+        if (!SDL_SetNumberProperty(props, SDL_PROP_NOTIFICATION_ACTION_COUNT_NUMBER, num_actions)) {
+            goto cleanup;
+        }
+    }
+
+    id = SDL_ShowNotificationWithProperties(props);
+
+cleanup:
+    SDL_DestroyProperties(props);
+    return id;
+}

src/notification/SDL_notification_c.h

@@ -0,0 +1,34 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+#ifndef SDL_NOTIFICATION_C_H
+#define SDL_NOTIFICATION_C_H
+
+#include <SDL3/SDL_notification.h>
+
+extern SDL_NotificationID SDL_SYS_ShowNotification(SDL_PropertiesID props);
+extern void SDL_CleanupNotifications();
+
+#ifdef SDL_VIDEO_DRIVER_WAYLAND
+extern const char *SDL_GetNotificationActivationToken();
+#endif
+
+#endif // SDL_NOTIFICATION_C_H

src/notification/dummy/SDL_dummynotification.c

@@ -0,0 +1,51 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+#include "SDL_internal.h"
+#include "../SDL_notification_c.h"
+
+bool SDL_RequestNotificationPermission(void)
+{
+    return SDL_Unsupported();
+}
+
+SDL_NotificationID SDL_SYS_ShowNotification(SDL_PropertiesID props)
+{
+    SDL_Unsupported();
+    return 0;
+}
+
+bool SDL_RemoveNotification(SDL_NotificationID notification)
+{
+    return SDL_Unsupported();
+}
+
+void SDL_CleanupNotifications()
+{
+    // Nothing to do.
+}
+
+#ifdef SDL_VIDEO_DRIVER_WAYLAND
+const char *SDL_GetNotificationActivationToken()
+{
+    return NULL;
+}
+#endif

src/test/SDL_test_common.c

@@ -2012,6 +2012,10 @@ void SDLTest_PrintEvent(const SDL_Event *event)
         SDL_Log("SDL EVENT: Camera device %" SDL_PRIu32 " permission denied",
                 event->cdevice.which);
         break;
+    case SDL_EVENT_NOTIFICATION_ACTION_INVOKED:
+        SDL_Log("SDL EVENT: Notification action for %" SDL_PRIu32 " button_id=%s",
+                event->notification.which, event->notification.action_id);
+        break;
     case SDL_EVENT_SENSOR_UPDATE:
         SDL_Log("SDL EVENT: Sensor update for %" SDL_PRIu32,
                 event->sensor.which);