Add SDL notifications

include/SDL3/SDL.h

@@ -58,6 +58,7 @@
 #include <SDL3/SDL_misc.h>
 #include <SDL3/SDL_mouse.h>
 #include <SDL3/SDL_mutex.h>
+#include <SDL3/SDL_notification.h>
 #include <SDL3/SDL_pixels.h>
 #include <SDL3/SDL_platform.h>
 #include <SDL3/SDL_power.h>

include/SDL3/SDL_notification.h

@@ -0,0 +1,113 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2023 Sam Lantinga <[email protected]>
+
+  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.
+*/
+
+/**
+ *  \file SDL_notification.h
+ *
+ *  \brief Header file for notification API
+ */
+
+#ifndef SDL_notification_h_
+#define SDL_notification_h_
+
+#include <SDL3/SDL_stdinc.h>
+
+#include <SDL3/SDL_begin_code.h>
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief SDL_Notification flags.
+ */
+typedef enum
+{
+    SDL_NOTIFICATION_PRIORITY_LOW        = 0x00000010,   /**< lowest */
+    SDL_NOTIFICATION_PRIORITY_NORMAL     = 0x00000020,   /**< normal/medium */
+    SDL_NOTIFICATION_PRIORITY_HIGH       = 0x00000040    /**< high/important/critical */
+} SDL_NotificationFlags;
+
+/**
+ * \brief SDL_Icon flags.
+ */
+typedef enum
+{
+    SDL_ICON_TYPE_SINGLE_FILE    = 0x00000010,   /**< A single icon file. */
+    SDL_ICON_TYPE_SURFACE        = 0x00000020,   /**< Icon inside an SDL surface. */
+    SDL_ICON_TYPE_WINDOW         = 0x00000040    /**< Icon is same as SDL window. */
+} SDL_IconFlags;
+
+/**
+ * Notification structure containing title, text, window, etc.
+ */
+typedef struct
+{
+    Uint32 flags;                       /**< ::SDL_NotificationFlags */
+    const char *title;                  /**< UTF-8 title */
+    const char *message;                /**< UTF-8 message text */
+
+    struct
+    {
+        Uint32 flags;                       /**< ::SDL_IconFlags */
+        union {
+            const char *path;
+            SDL_Surface *surface;
+            SDL_Window *window;
+        } data;
+    } icon;
+
+} SDL_NotificationData;
+
+/**
+ *  \brief Create a system notification.
+ *
+ *  \param notificationdata the SDL_NotificationData structure with title, text and other options
+ *  \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ *  \sa SDL_ShowSimpleNotification
+ *  \sa SDL_NotificationData
+ */
+extern DECLSPEC int SDLCALL SDL_ShowNotification(const SDL_NotificationData *notificationdata);
+
+/**
+ *  \brief Create a simple system notification.
+ *
+ *  \param title    UTF-8 title text
+ *  \param message  UTF-8 message text
+ *  \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ *  \sa SDL_ShowNotification
+ *  \sa SDL_NotificationData
+ */
+extern DECLSPEC int SDLCALL SDL_ShowSimpleNotification(const char *title, const char *message);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include <SDL3/SDL_close_code.h>
+
+
+#endif /* SDL_notification_h_ */
+

src/core/linux/SDL_dbus.c

@@ -561,4 +561,54 @@ char *SDL_DBus_GetLocalMachineId(void)
 
     return NULL;
 }
+
+#define NOTIFICATION_NODE "org.freedesktop.portal.Desktop"
+#define NOTIFICATION_PATH "/org/freedesktop/portal/desktop"
+#define NOTIFICATION_IF "org.freedesktop.portal.Notification"
+
+int SDL_DBus_ShowNotification(const SDL_NotificationData *notificationdata)
+{
+    DBusConnection *conn = dbus.session_conn;
+    DBusMessage *msg = NULL;
+    DBusMessageIter iter;
+    const char *id = "SomeId";
+
+    /* Call Notification.AddNotification() */
+    msg = dbus.message_new_method_call(NOTIFICATION_NODE, NOTIFICATION_PATH, NOTIFICATION_IF, "AddNotification");
+    if (msg == NULL) {
+        goto failure;
+    }
+
+    dbus.message_iter_init_append(msg, &iter);
+    /* Id */
+    dbus.message_iter_append_basic(&iter, DBUS_TYPE_STRING, &id);
+
+    /* a{sv} */
+    {
+        const char *keys[2];
+        const char *values[2];
+        keys[0] = "title";
+        values[0] = notificationdata->title;
+        keys[1] = "body";
+        values[1] = notificationdata->message;
+        SDL_DBus_AppendDictWithKeysValues(&iter, keys, values, 2);
+    }
+
+    if (!dbus.connection_send(conn, msg, NULL)) {
+        goto failure;
+    }
+
+    dbus.connection_flush(conn);
+
+    dbus.message_unref(msg);
+
+    return 0;
+
+failure:
+    if (msg) {
+        dbus.message_unref(msg);
+    }
+    return -1;
+}
+
 #endif

src/core/linux/SDL_dbus.h

@@ -98,6 +98,7 @@ extern SDL_bool SDL_DBus_QueryPropertyOnConnection(DBusConnection *conn, const c
 
 extern void SDL_DBus_ScreensaverTickle(void);
 extern SDL_bool SDL_DBus_ScreensaverInhibit(SDL_bool inhibit);
+extern int SDL_DBus_ShowNotification(const SDL_NotificationData *notificationdata);
 
 extern void SDL_DBus_PumpEvents(void);
 extern char *SDL_DBus_GetLocalMachineId(void);

src/dynapi/SDL_dynapi.sym

@@ -867,6 +867,8 @@ SDL3_0.0.0 {
     SDL_HasWindowSurface;
     SDL_DestroyWindowSurface;
     SDL_GetNaturalDisplayOrientation;
+    SDL_ShowNotification;
+    SDL_ShowSimpleNotification;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -893,3 +893,5 @@
 #define SDL_HasWindowSurface SDL_HasWindowSurface_REAL
 #define SDL_DestroyWindowSurface SDL_DestroyWindowSurface_REAL
 #define SDL_GetNaturalDisplayOrientation SDL_GetNaturalDisplayOrientation_REAL
+#define SDL_ShowNotification SDL_ShowNotification_REAL
+#define SDL_ShowSimpleNotification SDL_ShowSimpleNotification_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -938,3 +938,5 @@ SDL_DYNAPI_PROC(int,SDL_hid_get_report_descriptor,(SDL_hid_device *a, unsigned c
 SDL_DYNAPI_PROC(SDL_bool,SDL_HasWindowSurface,(SDL_Window *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_DestroyWindowSurface,(SDL_Window *a),(a),return)
 SDL_DYNAPI_PROC(SDL_DisplayOrientation,SDL_GetNaturalDisplayOrientation,(SDL_DisplayID a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_ShowNotification,(const SDL_NotificationData *a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_ShowSimpleNotification,(const char *a, const char *b),(a,b),return)

src/video/SDL_sysvideo.h

@@ -350,6 +350,9 @@ struct SDL_VideoDevice
     /* Hit-testing */
     int (*SetWindowHitTest)(SDL_Window *window, SDL_bool enabled);
 
+    /* Notification */
+    int (*ShowNotification)(SDL_VideoDevice *_this, const SDL_NotificationData *notificationdata);
+
     /* Tell window that app enabled drag'n'drop events */
     void (*AcceptDragAndDrop)(SDL_Window *window, SDL_bool accept);
 

src/video/SDL_video.c

@@ -5227,3 +5227,46 @@ void *SDL_Metal_GetLayer(SDL_MetalView view)
         return NULL;
     }
 }
+
+int SDL_ShowNotification(const SDL_NotificationData *notificationdata)
+{
+    if (notificationdata == NULL) {
+        return SDL_InvalidParamError("notificationdata");
+    }
+
+    if (notificationdata->title == NULL) {
+        return SDL_InvalidParamError("notificationdata->title");
+    }
+
+    if (notificationdata->message == NULL) {
+        return SDL_InvalidParamError("notificationdata->message");
+    }
+
+    if (notificationdata->icon.flags == SDL_ICON_TYPE_SINGLE_FILE && notificationdata->icon.data.path == NULL) {
+        return SDL_InvalidParamError("notificationdata->icon.dta.path");
+    }
+
+    if (notificationdata->icon.flags == SDL_ICON_TYPE_SINGLE_FILE && notificationdata->icon.data.surface == NULL) {
+        return SDL_InvalidParamError("notificationdata->icon.data.surface");
+    }
+
+    if (notificationdata->icon.flags == SDL_ICON_TYPE_WINDOW && notificationdata->icon.data.window == NULL) {
+        return SDL_InvalidParamError("notificationdata->icon.data.window");
+    }
+
+    if (_this && _this->ShowNotification) {
+        return _this->ShowNotification(_this, notificationdata);
+    }
+
+    return SDL_Unsupported();
+}
+
+
+int SDL_ShowSimpleNotification(const char *title, const char *message)
+{
+    SDL_NotificationData notificationdata;
+    SDL_zero(notificationdata);
+    notificationdata.title = title;
+    notificationdata.message = message;
+    return SDL_ShowNotification(&notificationdata);
+}

src/video/wayland/SDL_waylandvideo.c

@@ -120,6 +120,12 @@ static void Wayland_DeleteDevice(SDL_VideoDevice *device)
     SDL_WAYLAND_UnloadSymbols();
 }
 
+#ifdef SDL_USE_LIBDBUS
+static int Wayland_ShowNotification(SDL_VideoDevice *device, const SDL_NotificationData *notificationdata) {
+    return SDL_DBus_ShowNotification(notificationdata);
+}
+#endif
+
 static SDL_VideoDevice *Wayland_CreateDevice(void)
 {
     SDL_VideoDevice *device;
@@ -229,6 +235,10 @@ static SDL_VideoDevice *Wayland_CreateDevice(void)
     device->StopTextInput = Wayland_StopTextInput;
     device->SetTextInputRect = Wayland_SetTextInputRect;
 
+#ifdef SDL_USE_LIBDBUS
+    device->ShowNotification = Wayland_ShowNotification;
+#endif
+
 #ifdef SDL_VIDEO_VULKAN
     device->Vulkan_LoadLibrary = Wayland_Vulkan_LoadLibrary;
     device->Vulkan_UnloadLibrary = Wayland_Vulkan_UnloadLibrary;

src/video/x11/SDL_x11video.c

@@ -99,6 +99,12 @@ static int X11_SafetyNetErrHandler(Display *d, XErrorEvent *e)
     return 0;
 }
 
+#ifdef SDL_USE_LIBDBUS
+static int X11_ShowNotification(SDL_VideoDevice *device, const SDL_NotificationData *notificationdata) {
+    return SDL_DBus_ShowNotification(notificationdata);
+}
+#endif
+
 static SDL_VideoDevice *X11_CreateDevice(void)
 {
     SDL_VideoDevice *device;
@@ -270,6 +276,10 @@ static SDL_VideoDevice *X11_CreateDevice(void)
     device->HideScreenKeyboard = X11_HideScreenKeyboard;
     device->IsScreenKeyboardShown = X11_IsScreenKeyboardShown;
 
+#ifdef SDL_USE_LIBDBUS
+    device->ShowNotification = X11_ShowNotification;
+#endif
+
     device->free = X11_DeleteDevice;
 
 #ifdef SDL_VIDEO_VULKAN

test/testmessage.c

@@ -216,11 +216,22 @@ int main(int argc, char *argv[])
             quit(1);
         }
 
+
+        /* Test showing a system notification message with a parent window */
+        success = SDL_ShowSimpleNotification("Simple Notification", "Hey this window needs attention!");
+        if (success == -1) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Error Presenting Notification: %s\n", SDL_GetError());
+            quit(1);
+        }
+
         while (SDL_WaitEvent(&event)) {
             if (event.type == SDL_EVENT_QUIT || event.type == SDL_EVENT_KEY_UP) {
                 break;
             }
         }
+
+
+        SDL_DestroyWindow(window);
     }
 
     SDL_Quit();