Don't register an application delegate

This allows the user to override the application delegate themselves,
which opens several doors for customization that were previously closed.

src/changelog/unreleased.md

@@ -53,6 +53,8 @@ changelog entry.
 - Changed `EventLoopProxy::send_event` to `EventLoopProxy::wake_up`, it now
   only wakes up the loop.
 - On iOS, no longer act as-if the application successfully open all URLs.
+- On iOS and macOS, remove custom application delegates. You are now allowed to override the
+  application delegate yourself instead.
 
 ### Removed
 

src/platform/ios.rs

@@ -3,11 +3,14 @@
 //! Winit has an OS requirement of iOS 8 or higher, and is regularly tested on
 //! iOS 9.3.
 //!
+//! ## Window initialization
+//!
 //! iOS's main `UIApplicationMain` does some init work that's required by all
 //! UI-related code (see issue [#1705]). It is best to create your windows
-//! inside `Event::Resumed`.
+//! inside [`ApplicationHandler::resumed`].
 //!
 //! [#1705]: https://github.com/rust-windowing/winit/issues/1705
+//! [`ApplicationHandler::resumed`]: crate::application::ApplicationHandler::resumed
 //!
 //! ## Building app
 //!
@@ -63,6 +66,16 @@
 //! opengl will result in segfault.
 //!
 //! Also note that app may not receive the LoopExiting event if suspended; it might be SIGKILL'ed.
+//!
+//! ## Custom `UIApplicationDelegate`
+//!
+//! Winit usually handles everything related to the lifecycle events of the application. Sometimes,
+//! though, you might want to access some of the more niche stuff that [the application
+//! delegate][app-delegate] provides. This functionality is not exposed directly in Winit, since it
+//! would increase the API surface by quite a lot. Instead, Winit guarantees that it will not
+//! register an application delegate, so you can set up a custom one in a nib file instead.
+//!
+//! [app-delegate]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate?language=objc
 
 use std::os::raw::c_void;
 

src/platform/macos.rs

@@ -3,16 +3,86 @@
 //! Winit has an OS requirement of macOS 10.11 or higher (same as Rust
 //! itself), and is regularly tested on macOS 10.14.
 //!
+//! ## Window initialization
+//!
 //! A lot of functionality expects the application to be ready before you
 //! start doing anything; this includes creating windows, fetching monitors,
 //! drawing, and so on, see issues [#2238], [#2051] and [#2087].
 //!
 //! If you encounter problems, you should try doing your initialization inside
-//! `Event::Resumed`.
+//! [`ApplicationHandler::resumed`].
 //!
 //! [#2238]: https://github.com/rust-windowing/winit/issues/2238
 //! [#2051]: https://github.com/rust-windowing/winit/issues/2051
 //! [#2087]: https://github.com/rust-windowing/winit/issues/2087
+//! [`ApplicationHandler::resumed`]: crate::application::ApplicationHandler::resumed
+//!
+//! ## Custom `NSApplicationDelegate`
+//!
+//! Winit usually handles everything related to the lifecycle events of the application. Sometimes,
+//! though, you might want to do more niche stuff, such as [handle when the user re-activates the
+//! application][reopen]. Such functionality is not exposed directly in Winit, since it would
+//! increase the API surface by quite a lot.
+//!
+//! [reopen]: https://developer.apple.com/documentation/appkit/nsapplicationdelegate/1428638-applicationshouldhandlereopen?language=objc
+//!
+//! Instead, Winit guarantees that it will not register an application delegate, so the solution is
+//! to register your own application delegate, as outlined in the following example.
+//!
+#![cfg_attr(target_os = "macos", doc = "```")]
+#![cfg_attr(not(target_os = "macos"), doc = "```ignore")]
+//! use objc2::rc::Retained;
+//! use objc2::runtime::ProtocolObject;
+//! use objc2::{declare_class, msg_send_id, mutability, ClassType, DeclaredClass};
+//! use objc2_app_kit::{NSApplication, NSApplicationDelegate};
+//! use objc2_foundation::{NSArray, NSURL, MainThreadMarker, NSObject, NSObjectProtocol};
+//! use winit::event_loop::EventLoop;
+//!
+//! declare_class!(
+//!     struct AppDelegate;
+//!
+//!     unsafe impl ClassType for AppDelegate {
+//!         type Super = NSObject;
+//!         type Mutability = mutability::MainThreadOnly;
+//!         const NAME: &'static str = "MyAppDelegate";
+//!     }
+//!
+//!     impl DeclaredClass for AppDelegate {}
+//!
+//!     unsafe impl NSObjectProtocol for AppDelegate {}
+//!
+//!     unsafe impl NSApplicationDelegate for AppDelegate {
+//!         #[method(application:openURLs:)]
+//!         fn application_openURLs(&self, application: &NSApplication, urls: &NSArray<NSURL>) {
+//!             // Note: To specifically get `application:openURLs:` to work, you _might_
+//!             // have to bundle your application. This is not done in this example.
+//!             println!("open urls: {application:?}, {urls:?}");
+//!         }
+//!     }
+//! );
+//!
+//! impl AppDelegate {
+//!     fn new(mtm: MainThreadMarker) -> Retained<Self> {
+//!         unsafe { msg_send_id![super(mtm.alloc().set_ivars(())), init] }
+//!     }
+//! }
+//!
+//! fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let event_loop = EventLoop::new()?;
+//!
+//!     let mtm = MainThreadMarker::new().unwrap();
+//!     let delegate = AppDelegate::new(mtm);
+//!     // Important: Call `sharedApplication` after `EventLoop::new`,
+//!     // doing it before is not yet supported.
+//!     let app = NSApplication::sharedApplication(mtm);
+//!     app.setDelegate(Some(ProtocolObject::from_ref(&*delegate)));
+//!
+//!     // event_loop.run_app(&mut my_app);
+//!     Ok(())
+//! }
+//! ```
+//!
+//! See `objc2-app-kit` for more detailed information.
 
 use std::os::raw::c_void;
 

src/platform_impl/apple/appkit/app.rs

@@ -1,10 +1,12 @@
 #![allow(clippy::unnecessary_cast)]
 
+use std::rc::Rc;
+
 use objc2::{declare_class, msg_send, mutability, ClassType, DeclaredClass};
 use objc2_app_kit::{NSApplication, NSEvent, NSEventModifierFlags, NSEventType, NSResponder};
 use objc2_foundation::{MainThreadMarker, NSObject};
 
-use super::app_state::ApplicationDelegate;
+use super::app_state::AppState;
 use super::DEVICE_ID;
 use crate::event::{DeviceEvent, ElementState};
 
@@ -38,15 +40,15 @@ declare_class!(
                     key_window.sendEvent(event);
                 }
             } else {
-                let delegate = ApplicationDelegate::get(MainThreadMarker::from(self));
-                maybe_dispatch_device_event(&delegate, event);
+                let app_state = AppState::get(MainThreadMarker::from(self));
+                maybe_dispatch_device_event(&app_state, event);
                 unsafe { msg_send![super(self), sendEvent: event] }
             }
         }
     }
 );
 
-fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent) {
+fn maybe_dispatch_device_event(app_state: &Rc<AppState>, event: &NSEvent) {
     let event_type = unsafe { event.r#type() };
     #[allow(non_upper_case_globals)]
     match event_type {
@@ -58,7 +60,7 @@ fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent)
             let delta_y = unsafe { event.deltaY() } as f64;
 
             if delta_x != 0.0 {
-                delegate.maybe_queue_with_handler(move |app, event_loop| {
+                app_state.maybe_queue_with_handler(move |app, event_loop| {
                     app.device_event(event_loop, DEVICE_ID, DeviceEvent::Motion {
                         axis: 0,
                         value: delta_x,
@@ -67,7 +69,7 @@ fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent)
             }
 
             if delta_y != 0.0 {
-                delegate.maybe_queue_with_handler(move |app, event_loop| {
+                app_state.maybe_queue_with_handler(move |app, event_loop| {
                     app.device_event(event_loop, DEVICE_ID, DeviceEvent::Motion {
                         axis: 1,
                         value: delta_y,
@@ -76,7 +78,7 @@ fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent)
             }
 
             if delta_x != 0.0 || delta_y != 0.0 {
-                delegate.maybe_queue_with_handler(move |app, event_loop| {
+                app_state.maybe_queue_with_handler(move |app, event_loop| {
                     app.device_event(event_loop, DEVICE_ID, DeviceEvent::MouseMotion {
                         delta: (delta_x, delta_y),
                     });
@@ -85,7 +87,7 @@ fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent)
         },
         NSEventType::LeftMouseDown | NSEventType::RightMouseDown | NSEventType::OtherMouseDown => {
             let button = unsafe { event.buttonNumber() } as u32;
-            delegate.maybe_queue_with_handler(move |app, event_loop| {
+            app_state.maybe_queue_with_handler(move |app, event_loop| {
                 app.device_event(event_loop, DEVICE_ID, DeviceEvent::Button {
                     button,
                     state: ElementState::Pressed,
@@ -94,7 +96,7 @@ fn maybe_dispatch_device_event(delegate: &ApplicationDelegate, event: &NSEvent)
         },
         NSEventType::LeftMouseUp | NSEventType::RightMouseUp | NSEventType::OtherMouseUp => {
             let button = unsafe { event.buttonNumber() } as u32;
-            delegate.maybe_queue_with_handler(move |app, event_loop| {
+            app_state.maybe_queue_with_handler(move |app, event_loop| {
                 app.device_event(event_loop, DEVICE_ID, DeviceEvent::Button {
                     button,
                     state: ElementState::Released,