events: Emit an event when a window is destroyed

As child windows can be recursively destroyed when their parents are destroyed, emit an event to notify the application when a window is being or has been implicitly destroyed so that it can appropriately clean up any associated resources.

If the application has registered an event watch, the destroy message will be received when the window handle is still valid, so the application can retrieve and release any userdata associated with the window. If the message is processed at any time after that, the window handle is already invalid and the ID is only useful for application-side bookkeeping purposes.

include/SDL3/SDL_events.h

@@ -120,8 +120,12 @@ typedef enum
     SDL_EVENT_WINDOW_HIT_TEST,          /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL */
     SDL_EVENT_WINDOW_ICCPROF_CHANGED,   /**< The ICC profile of the window's display has changed */
     SDL_EVENT_WINDOW_DISPLAY_CHANGED,   /**< Window has been moved to display data1 */
+    SDL_EVENT_WINDOW_DESTROYED,         /**< The window with the associated ID is being or has been destroyed. If this message is being handled
+                                             in an event watcher, the window handle is still valid and can still be used to retrieve any userdata
+                                             associated with the window. Otherwise, the handle has already been destroyed and all resources
+                                             associated with it are invalid */
     SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN,
-    SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_DISPLAY_CHANGED,
+    SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_DESTROYED,
 
     /* Keyboard events */
     SDL_EVENT_KEY_DOWN        = 0x300, /**< Key pressed */

src/events/SDL_windowevents.c

@@ -46,7 +46,7 @@ int SDL_SendWindowEvent(SDL_Window *window, SDL_EventType windowevent,
     if (window == NULL) {
         return 0;
     }
-    if (window->is_destroying) {
+    if (window->is_destroying && windowevent != SDL_EVENT_WINDOW_DESTROYED) {
         return 0;
     }
     switch (windowevent) {

src/video/SDL_video.c

@@ -3410,6 +3410,8 @@ void SDL_DestroyWindow(SDL_Window *window)
         SDL_DestroyWindow(window->first_child);
     }
 
+    SDL_SendWindowEvent(window, SDL_EVENT_WINDOW_DESTROYED, 0, 0);
+
     /* If this is a child window, unlink it from its siblings */
     if (window->parent) {
         if (window->next_sibling) {