Allow the user to register the application delegate on macOS and iOS (#…

…3758)

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

To do this, we use notifications instead of top-level application delegate
methods.

One effect of not providing an application delegate on iOS is that we no
longer act as-if the application successfully open all URLs there.

This is a breaking change, although unlikely to matter in practice, since the
return value of `application:didFinishLaunchingWithOptions:` is seldom used by
the system (and is likely the preferred behaviour anyhow).

Cargo.toml

@@ -105,12 +105,12 @@ ndk = { version = "0.9.0", default-features = false }
 
 # AppKit or UIKit
 [target.'cfg(target_vendor = "apple")'.dependencies]
+block2 = "0.5.1"
 core-foundation = "0.9.3"
 objc2 = "0.5.2"
 
 # AppKit
 [target.'cfg(target_os = "macos")'.dependencies]
-block2 = "0.5.1"
 core-graphics = "0.23.1"
 objc2-app-kit = { version = "0.2.2", features = [
     "NSAppearance",
@@ -152,6 +152,7 @@ objc2-foundation = { version = "0.2.2", features = [
     "NSKeyValueObserving",
     "NSNotification",
     "NSObjCRuntime",
+    "NSOperation",
     "NSPathUtilities",
     "NSProcessInfo",
     "NSRunLoop",
@@ -163,11 +164,13 @@ objc2-foundation = { version = "0.2.2", features = [
 # UIKit
 [target.'cfg(all(target_vendor = "apple", not(target_os = "macos")))'.dependencies]
 objc2-foundation = { version = "0.2.2", features = [
+    "block2",
     "dispatch",
     "NSArray",
     "NSEnumerator",
     "NSGeometry",
     "NSObjCRuntime",
+    "NSOperation",
     "NSString",
     "NSProcessInfo",
     "NSThread",

src/changelog/unreleased.md

@@ -94,6 +94,10 @@ changelog entry.
 - Changed how `ModifiersState` is serialized by Serde.
 - `VideoModeHandle::refresh_rate_millihertz()` and `bit_depth()` now return a `Option<NonZero*>`.
 - `MonitorHandle::position()` now returns an `Option`.
+- On iOS and macOS, remove custom application delegates. You are now allowed to override the
+  application delegate yourself.
+- On iOS, no longer act as-if the application successfully open all URLs. Override
+  `application:didFinishLaunchingWithOptions:` and provide the desired behaviour yourself.
 
 ### 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,84 @@
 //! 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 (see
+//! `objc2-app-kit` for more detailed information).
+#![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(())
+//! }
+//! ```
 
 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 || 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),
                     });
@@ -67,7 +69,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,
@@ -76,7 +78,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,