[UIKit] Fix a few UITraitCollection bindings. Fixes #21377.

The methods 'GetTraitCollectionWithTraits' and
'GetTraitCollectionByModifyingTraits' takes a callback, but the callback had
the wrong signature.

So introduce a new overload for each of these methods, using a delegate with
the correct signature.

Also deprecate 'FromTraitsFromCollections' according to both headers and
documentation.

Fixes #21377.

src/UIKit/UITraitCollection.cs

@@ -8,24 +8,31 @@
 //
 
 using System;
+using System.ComponentModel;
+
 using ObjCRuntime;
 using Foundation;
 
 // Disable until we get around to enable + fix any issues.
 #nullable disable
 
 namespace UIKit {
-#if !WATCH
 	public partial class UITraitCollection {
-
-#if !NET
-		[Obsolete ("Please use the static 'Create' method instead.")]
-		public UITraitCollection FromPreferredContentSizeCategory (UIContentSizeCategory category)
-			=> Create (category);
-#endif
-
 		public static UITraitCollection Create (UIContentSizeCategory category)
 			=> FromPreferredContentSizeCategory (category.GetConstant ());
-	}
+
+#if !XAMCORE_5_0
+		[Obsolete ("Use the overload that takes a 'UITraitMutations' parameter instead.", false)]
+		[EditorBrowsable (EditorBrowsableState.Never)]
+		[SupportedOSPlatform ("tvos17.0")]
+		[SupportedOSPlatform ("ios17.0")]
+		[SupportedOSPlatform ("maccatalyst17.0")]
+		[BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)]
+		public virtual UITraitCollection GetTraitCollectionByModifyingTraits (Func<IUIMutableTraits> mutations)
+		{
+			// there's nothing useful this method can do.
+			throw new NotSupportedException ($"Use the overload that takes a 'UITraitMutations' parameter instead.");
+		}
 #endif
+	}
 }

src/uikit.cs

@@ -18635,6 +18635,8 @@ partial interface UITraitEnvironment {
 		void TraitCollectionDidChange ([NullAllowed] UITraitCollection previousTraitCollection);
 	}
 
+	delegate void UITraitMutations (IUIMutableTraits mutableTraits);
+
 	[NoWatch]
 	[MacCatalyst (13, 1)]
 	[BaseType (typeof (NSObject))]
@@ -18664,6 +18666,9 @@ partial interface UITraitCollection : NSCopying, NSSecureCoding {
 		[Export ("containsTraitsInCollection:")]
 		bool Contains (UITraitCollection trait);
 
+		[Deprecated (PlatformName.iOS, 17, 0, message: "Use 'GetTraitCollectionWithTraits(UITraitMutations)' and 'GetTraitCollectionByModifyingTraits(UITraitMutations)' instead.")]
+		[Deprecated (PlatformName.MacCatalyst, 17, 0, message: "Use 'GetTraitCollectionWithTraits(UITraitMutations)' and 'GetTraitCollectionByModifyingTraits(UITraitMutations)' instead.")]
+		[Deprecated (PlatformName.TvOS, 17, 0, message: "Use 'GetTraitCollectionWithTraits(UITraitMutations)' and 'GetTraitCollectionByModifyingTraits(UITraitMutations)' instead.")]
 		[Static, Export ("traitCollectionWithTraitsFromCollections:")]
 		UITraitCollection FromTraitsFromCollections (UITraitCollection [] traitCollections);
 
@@ -18812,14 +18817,23 @@ partial interface UITraitCollection : NSCopying, NSSecureCoding {
 		[Export ("toolbarItemPresentationSize")]
 		UINSToolbarItemPresentationSize ToolbarItemPresentationSize { get; }
 
+#if !XAMCORE_5_0
+		[Obsolete ("Use the overload that takes a 'UITraitMutations' parameter instead.")]
+		[EditorBrowsable (EditorBrowsableState.Never)]
 		[Watch (10, 0), TV (17, 0), iOS (17, 0), MacCatalyst (17, 0)]
 		[Static]
 		[Export ("traitCollectionWithTraits:")]
 		UITraitCollection GetTraitCollectionWithTraits (Func<IUIMutableTraits> mutations);
+#endif
+
+		[Watch (10, 0), TV (17, 0), iOS (17, 0), MacCatalyst (17, 0)]
+		[Static]
+		[Export ("traitCollectionWithTraits:")]
+		UITraitCollection GetTraitCollectionWithTraits (UITraitMutations mutations);
 
 		[Watch (10, 0), TV (17, 0), iOS (17, 0), MacCatalyst (17, 0)]
 		[Export ("traitCollectionByModifyingTraits:")]
-		UITraitCollection GetTraitCollectionByModifyingTraits (Func<IUIMutableTraits> mutations);
+		UITraitCollection GetTraitCollectionByModifyingTraits (UITraitMutations mutations);
 
 		[Watch (10, 0), TV (17, 0), iOS (17, 0), MacCatalyst (17, 0)]
 		[Static]

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -86759,6 +86759,7 @@ T:UIKit.UITouchProperties
 T:UIKit.UITouchType
 T:UIKit.UITraitEnvironment
 T:UIKit.UITraitEnvironmentLayoutDirection
+T:UIKit.UITraitMutations
 T:UIKit.UITransitionContext
 T:UIKit.UITransitionViewControllerKind
 T:UIKit.UIUpdateLinkCallback