[iOS] Add documentation for using alternate app icons on iOS and tvOS.

docs/ios/TOC.yml

@@ -0,0 +1,9 @@
+- name: .NET for iOS, tvOS, macOS and Mac Catalyst
+  items:
+    - name: Application fundamentals
+      items:
+        - name: Images & icons
+          href: app-fundamentals/images-icons/index.md
+          items:
+            - name: Alternate app icons
+              href: app-fundamentals/images-icons/alternate-app-icons.md

docs/ios/app-fundamentals/images-icons/alternate-app-icons.md

@@ -0,0 +1,129 @@
+---
+title: "Alternate app icons in .NET for iOS and tvOS"
+description: "This document describes how to use alternate app icons. It discusses how to add these icons to a .NET for iOS or tvOS project, and how to manage the app's icon programmatically."
+ms.date: 10/29/2024
+---
+
+# Alternate app icons in .NET for iOS and tvOS
+
+Apple has several [UIApplication][uiapplication] APIs that allow an app to manage its icon:
+
+- [UIApplication.SupportsAlternateIcons][supportsalternateicons] - If `true` the app has an alternate set of icons.
+- [UIApplication.AlternateIconName][alternateiconname] - Returns the name of the alternate icon currently selected or `null` if using the primary icon.
+- [UIApplication.SetAlternateIconName][setalternateiconname] - Use this method to switch the app's icon to the given alternate icon.
+- `UNUserNotificationCenter.Current.SetBadgeCount` - Sets the badge count of the app icon in the Springboard (deprecated in iOS 16+ and tvOS 16+).
+
+![A sample alert when an app changes its icon](alternate-app-icons-images/ScreenshotGreen.png)
+
+## Adding alternate icons to a .NET project
+
+To allow an app to switch to an alternate icon, a new `.appiconset` folder with a collection of icon images will need to be included in the project's asset catalog:
+
+1. Open the project's asset catalog (**Assets.xcassets**) in Finder:
+
+    ![Open the asset catalog](alternate-app-icons-images/step1.png)
+
+2. Create a copy of the existing `AppIcon.appiconset` folder:
+
+    ![Copy appiconset folder](alternate-app-icons-images/step2.png)
+
+3. Replace each icon in the copied folder with the new icon of the matching size:
+
+    ![Create new icons](alternate-app-icons-images/step3.png)
+
+4. Add the app icon to the project file using the `AppIcon` property:
+
+    ```xml
+    <PropertyGroup>
+        <AppIcon>AppIcon</AppIcon>
+    </PropertyGroup>
+    ```
+
+    > [!NOTE]
+    Existing projects typically specifies the app icon using the
+    `XSAppIconAssets` key in the `Info.plist` file - this can still be used,
+    but it's recommended to switch to the `AppIcon` property in the project
+    file instead (which is simplier too, because its value is the name of the
+    icon, not the path to the resource).
+
+5. Add the alternative icon(s) to the project file using the `AlternativeAppIcons` item group:
+
+    ```xml
+    <ItemGroup>
+        <AlternativeAppIcon Include="AlternativeAppIcons" />
+    </ItemGroup>
+    ```
+
+## Managing the app's icon 
+
+With the icon images included in the .NET project, the developer can the following ways to control the app's icon.
+
+The [SupportsAlternateIcons][supportsalternateicons] property of the [UIApplication][uiapplication] class allows the developer to see if an app supports alternate icons. For example:
+
+```csharp
+// Can the app select a different icon?
+primaryIconButton.Enabled = UIApplication.SharedApplication.SupportsAlternateIcons;
+alternateIconButton.Enabled = UIApplication.SharedApplication.SupportsAlternateIcons;
+```
+
+The [ApplicationIconBadgeNumber][applicationiconbadgenumber] property of the [UIApplication][uiapplication] class allows the developer to get or set the current badge number of the app icon in the Springboard. The default value is zero (0). For example:
+
+```csharp
+// Set the badge number to 1
+var badgeCount = 1;
+UNUserNotificationCenter.Current.SetBadgeCount (badgeCount, (error) => {
+    Console.WriteLine ($"Set badge count to {badgeCount}: {(error is null ? "successfully" : error.ToString ())}");
+}
+```
+
+> [!NOTE]
+`UNUserNotificationCenter.SetBadgeCount` requires authorization from the user on iOS, which can be acquired by calling `UNUserNotificationCenter.Current.RequestAuthorization` before setting the badge count.
+
+The [AlternateIconName][alternateiconname] property of the [UIApplication][uiapplication] class allows the developer to get the name of the currently selected alternate app icon or it returns `null` if the app is using the Primary Icon. For example:
+
+```csharp
+// Get the name of the currently selected alternate
+// icon set
+var name = UIApplication.SharedApplication.AlternateIconName;
+
+if (name != null ) {
+    // Do something with the name
+}
+```
+
+The [SetAlternameIconName][setalternateiconname] property of the [UIApplication][uiapplication] class allows the developer to change the app icon. Pass the name of the icon to select or `null` to return to the primary icon. For example:
+
+```csharp
+void UsePrimaryIcon (Foundation.NSObject sender)
+{
+    UIApplication.SharedApplication.SetAlternateIconName (null, (error) => {
+        Console.WriteLine ($"Set Primary Icon: {(error is null ? "successfully" : error.ToString ())}");
+    });
+}
+
+void UseAlternateIcon (Foundation.NSObject sender)
+{
+    UIApplication.SharedApplication.SetAlternateIconName ("AlternateAppIcons", (error) => {
+        Console.WriteLine ($"Set Alternate Icon: {(error is null ? "successfully" : error.ToString ())}");
+    });
+}
+```
+
+When the app is run and the user selects an alternate icon, an alert like the following will be displayed:
+
+![A sample alert when an app changes its icon](alternate-app-icons-images/ScreenshotGreen.png)
+
+If the user switches back to the primary icon, an alert like the following will be displayed:
+
+![A sample alert when an app changes to the primary icon](alternate-app-icons-images/ScreenshotBlue.png)
+
+## See also
+
+- [iOS sample](https://github.com/dotnet/macios-samples/tree/main/AlternateAppIcons/iOS)
+- [tvOS sample](https://github.com/dotnet/macios-samples/tree/main/AlternateAppIcons/tvOS)
+
+[uiapplication]: xref:UIKit.UIApplication
+[applicationiconbadgenumber]: xref:UIKit.UIApplication.ApplicationIconBadgeNumber
+[supportsalternateicons]: xref:UIKit.UIApplication.SupportsAlternateIcons
+[alternateiconname]: xref:UIKit.UIApplication.AlternateIconName
+[setalternateiconname]: xref:UIKit.UIApplication.SetAlternateIconName%2A

docs/ios/app-fundamentals/images-icons/index.md

@@ -0,0 +1,48 @@
+---
+title: "Images and Icons in .NET for iOS, tvOS, macOS and Mac Catalyst"
+description: "This section includes a variety of articles that cover working with images in a Xamarin.iOS app, such as using them as icons, launch screens or including them in controls and providing icons for custom document types."
+ms.date: 11/01/2024
+---
+# Images and icons in .NET for iOS, tvOS, macOS and Mac Catalyst
+
+There are several ways that image assets are used inside an app. From simply
+displaying an image as part of an app's UI to, assigning it to a UI control
+such as a [UIButton][uibutton] or [UIImageView][uiimageview], to providing icons and launch
+screens, .NET for iOS, tvOS, macOS and Mac Catalyst makes it easy to add great
+artwork to an app in the following ways:
+
+- **Resolution Independent Images** – Use the OS's built-in support for working with images across different device resolutions and types (iPhone, iPad, etc.).
+- **Asset Catalog Image Sets** - Use **Asset Catalog Image Sets** to manage and group all version of a given image asset required by an app.
+- **Images in Code** – Use the [UIImage][uiimage] class's methods to load and work with image assets and assign them to UI controls in C# code.
+- **Application Icon** - Define the app icon required by every app. This is the icon that the user will tap from the home screen to launch the app. Additionally, this icon is used by Game Center, if applicable.
+- **Spotlight Icon** - Define the app's Spotlight icon. Whenever the user enters the name of an app in a Spotlight Search, this icon is displayed.
+- **Settings Icon** - Define the app's **Settings** icon. If the user enters the **Settings** app on their device, this icon will be displayed at the end of the Settings list for the app. 
+- **Launch Screens** - Define the app's Launch Screen. After the user taps the app icon and before the first view appears, a blank screen will be shown. Fortunately, it's possible to displaying an image in place of the blank screen by using a Storyboard. 
+- **iTunes Icon** - Provide an iTunes icon. If using the Ad-Hoc method of delivering an app (either for corporate users or for beta testing on real devices), the developer also needs to include a 512x512 and a 1024x1024 image that will be used to represent the app in iTunes.
+- **Document Icons** - Use an image as an icon for any specific document type that an app supports or creates.
+
+There are several considerations that should be taken into account when
+creating image assets for an app, as well as several places where those assets
+will be used. Each of these have an affect on not only how many image assets
+will be required, but how those assets are created. The following topics cover
+the types of images assets that will be required, how those assets are
+included in the application's bundle and how the image assets are consumed to
+provide the required functionality:
+
+## [Alternate app icons](~/ios/app-fundamentals/images-icons/alternate-app-icons.md)
+
+Apple has several [UIApplication][uiapplication] APIs that allow an app to manage its icon:
+
+- [UIApplication.SupportsAlternateIcons][supportsalternateicons] - If `true` the app has an alternate set of icons.
+- [UIApplication.AlternateIconName][alternateiconname] - Returns the name of the alternate icon currently selected or `null` if using the primary icon.
+- [UIApplication.SetAlternateIconName][setalternateiconname] - Use this method to switch the app's icon to the given alternate icon.
+- `UNUserNotificationCenter.Current.SetBadgeCount` - Sets the badge count of the app icon in the Springboard (deprecated in iOS 16+ and tvOS 16+).
+
+[uiapplication]: xref:UIKit.UIApplication
+[applicationiconbadgenumber]: xref:UIKit.UIApplication.ApplicationIconBadgeNumber
+[supportsalternateicons]: xref:UIKit.UIApplication.SupportsAlternateIcons
+[alternateiconname]: xref:UIKit.UIApplication.AlternateIconName
+[setalternateiconname]: xref:UIKit.UIApplication.SetAlternateIconName%2A
+[uibutton]: xref:UIKit.UIButton
+[uiimageview]: xref:UIKit.UIImageView
+[uiimage]: xref:UIKit.UIImage

docs/ios/index.yml

@@ -0,0 +1,45 @@
+### YamlMime:Hub
+
+#root section (Required)
+title: .NET for iOS, tvOS, macOS and Mac Catalyst documentation
+summary: >
+  .NET for iOS, tvOS, macOS and Mac Catalyst allows you to write apps for iOS, tvOS, macOS or Mac Catalyst using .NET languages.
+brand: dotnet
+
+metadata:
+  title: .NET for iOS, tvOS, macOS and Mac Catalyst
+  description: The .NET for iOS, tvOS, macOS and Mac Catalyst guide has everything you need to learn .NET for these platform.
+  ms.subservice: dotnet-ios
+  ms.topic: hub-page
+  author: rolfbjarne
+  ms.author: rokvin
+  ms.date: 11/01/2024
+
+conceptualContent:
+# itemType: reference
+  # Supports up to 3 subsections
+  sections:
+    - title: .NET for iOS, tvOS, macOS and Mac Catalyst Guides
+      items:
+        # Card
+        - title: Application fundamentals
+          links:
+            - url: ~/ios/app-fundamentals/images-icons/alternate-app-icons.md
+              itemType: reference
+              text: Alternate app icons
+
+# additionalContent section (Optional; Remove if not applicable.)
+# Card with links style
+additionalContent:
+  # Supports up to 4 subsections
+  sections:
+
+    - title: References # < 60 chars (optional)
+      items:
+        # Card
+        - title: ".NET API reference"
+          summary: API reference documentation for .NET
+          url: /dotnet/api/?view=net-9.0
+
+  # footer (Optional; Remove if not applicable.)
+  footer: "Are you interested in contributing to the .NET docs? For more information, see our [contributor guide](/contribute/dotnet/dotnet-contribute)."