Skip to content

Add an API and backends for system notifications#15351

Open
Kontrabant wants to merge 7 commits into
libsdl-org:mainfrom
Kontrabant:notifications2
Open

Add an API and backends for system notifications#15351
Kontrabant wants to merge 7 commits into
libsdl-org:mainfrom
Kontrabant:notifications2

Conversation

@Kontrabant
Copy link
Copy Markdown
Contributor

@Kontrabant Kontrabant commented Apr 9, 2026

Notifications are asynchronous, passive popups that convey some information to the user. This adds support for various native system notifications and an associated SDL API.

Tested and supported platforms:

  • *nix via D-Bus interfaces (both the "core" interface and a portal for use within containers is supported)
  • macOS (10.14+, only supported when used within app bundles due to internal OS requirements)
  • Windows (Win10+, technically Win8 supported notifications, but some newer interfaces that require Win10 are used, and Win8 usage is basically zero at this point)

Needs testing:

  • iOS (builds, but currently untested. My old MacBook can't run a new enough XCode to target my phone)

Possible future backends:

  • Android (this is certainly doable, but I have zero experience with Android and no devices to test it on.)
  • Emscripten (browsers support notification functionality, so this is probably doable?)

All implementations currently support some basic features in addition to header and body text:

  • An attached image
  • Actions for user feedback (presentation is system dependent, but usually buttons or menu items)
  • Custom sounds (some platforms restrict where the sound files can be located, with Windows being particularly restrictive)

Feedback from actions comes in the form of a new event, which returns the invoked action string specified when the notification was dispatched. It can also return a "default" action, if the notification is interacted with in a non-specific way (e.g. tapping or clicking on the body instead of a button).

New capabilities can be easily added by adding additional properties. A simple interface that just takes a title, body, and image, is included as well.

The Windows implementation also provides a situation where SDL_wcstoul() is needed, so that was added in a separate commit, along with associated tests.

Closes #7857 (supersedes)
Closes #1932

@Kontrabant Kontrabant marked this pull request as draft April 9, 2026 17:14
@Kontrabant Kontrabant force-pushed the notifications2 branch 2 times, most recently from d53972e to ef3fe10 Compare April 9, 2026 17:36
@Kontrabant Kontrabant added this to the 3.6.0 milestone Apr 9, 2026
Comment thread include/SDL3/SDL_notification.h Outdated
Comment thread src/events/SDL_notificationevents.c Outdated
@Kontrabant Kontrabant force-pushed the notifications2 branch 4 times, most recently from ea0bf0e to c752640 Compare April 14, 2026 15:53
@Kontrabant Kontrabant force-pushed the notifications2 branch 2 times, most recently from 391c8dc to 0d56d7b Compare April 19, 2026 15:30
@Kontrabant
Copy link
Copy Markdown
Contributor Author

Fixed a few memory leaks, and revamped the data structure used to add "actions" to notifications, so it can be easily extended in the future to support additional types.

The basic design here is complete, so I'm removing draft status.

@Kontrabant Kontrabant marked this pull request as ready for review April 19, 2026 15:38
Comment thread include/SDL3/SDL_notification.h Outdated
Comment thread include/SDL3/SDL_notification.h
Comment thread include/SDL3/SDL_notification.h Outdated
Comment thread include/SDL3/SDL_notification.h Outdated
Comment thread include/SDL3/SDL_notification.h Outdated
Comment thread src/notification/windows/SDL_windowsnotification.c
Comment thread src/notification/cocoa/SDL_cocoanotification.m Outdated
Comment thread include/SDL3/SDL_notification.h
@slouken
Copy link
Copy Markdown
Collaborator

slouken commented Apr 23, 2026

I haven't done a thorough review, but in general this looks good to me. @icculus, thoughts?

@slouken slouken requested a review from icculus April 23, 2026 18:56
Comment thread src/dynapi/SDL_dynapi.sym
@Kontrabant Kontrabant force-pushed the notifications2 branch 2 times, most recently from 1c1db86 to 2804d6a Compare May 9, 2026 21:53
Kontrabant added 5 commits May 9, 2026 19:01
Use the core and portal notification implementations to dispatch system notifications.
Notifications are supported on Win10 and above.
Supported on macOS 10.14+ and iOS.
@slouken
Copy link
Copy Markdown
Collaborator

slouken commented May 12, 2026

@icculus, any idea what needs to be done for Emscripten? This seems like a useful API to add.

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented May 12, 2026

So there is an API for this, but:

  • You can't use it unless you previously requested access to send notifications.
  • You can only ask for permission in a Javascript event handler where the user has clicked on something on the page.
  • You wait for the async response that permission was granted (which requires the user to approve it, so the response can come hours later).

If those things happen, the API is actually pretty usable.

I see we have an API to request permission, but no way to find out if permission was denied; is this running on the idea that even if approved, notifications can be blocked?

I guess on Emscripten, if the app asks for permission, we'll hold it until the next time the user clicks on something, which can weird if the user triggered this by clicking on an "enable notifications" button...but otherwise they'll need to have an SDL event watcher to catch it in time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add System Notification Support

4 participants