diff --git a/docs/fundamentals/windows.md b/docs/fundamentals/windows.md index a61281bc2f..3b4d0e16ac 100644 --- a/docs/fundamentals/windows.md +++ b/docs/fundamentals/windows.md @@ -1,14 +1,14 @@ --- title: ".NET MAUI windows" description: "Learn how to use the .NET MAUI Window class to create, configure, show, and manage multi-window apps." -ms.date: 10/10/2022 +ms.date: 10/24/2023 --- # .NET MAUI windows -The .NET Multi-platform App UI (.NET MAUI) `Window` class provides the ability to create, configure, show, and manage multiple windows. +The .NET Multi-platform App UI (.NET MAUI) class provides the ability to create, configure, show, and manage multiple windows. -`Window` defines the following properties: + defines the following properties: - `FlowDirection`, of type `FlowDirection`, defines the direction in which the UI element of the window are laid out. - `Height`, of type `double`, specifies the height of the window on Windows. @@ -17,7 +17,7 @@ The .NET Multi-platform App UI (.NET MAUI) `Window` class provides the ability t - `MinimumHeight`, of type `double`, represents the minimum height of the window on desktop platforms. Valid values are between 0 and `double.PositiveInfinity`. - `MinimumWidth`, of type `double`, represents the minimum width of the window on desktop platforms. Valid values are between 0 and `double.PositiveInfinity`. - `Overlays`, of type `IReadOnlyCollection`, represents the collection of window overlays. -- , of type , indicates the page being displayed by the window. This property is the content property of the `Window` class, and therefore does not need to be explicitly set. +- , of type , indicates the page being displayed by the window. This property is the content property of the class, and therefore does not need to be explicitly set. - `Title`, of type `string`, represents the title of the window. - `Width`, of type `double`, specifies the width of the window on Windows. - `X`, of type `double`, specifies the X coordinate of the window on Windows. @@ -27,7 +27,7 @@ These properties, with the exception of the `Overlays` property, are backed by < -The `Window` class defines the following events: +The class defines the following events: - `Created`, which is raised when the window is created. - `Resumed`, which is raised when the window is resumed from a sleeping state. @@ -41,7 +41,7 @@ The `Window` class defines the following events: For more information about the lifecycle events, and their associated overrides, see [App lifecycle](app-lifecycle.md). -The `Window` class also defines the following modal navigation events: +The class also defines the following modal navigation events: - `ModalPopped`, with `ModalPoppedEventArgs`, which is raised when a view has been popped modally. - `ModalPopping`, with `ModalPoppingEventArgs`, which is raised when a view is modally popped. @@ -49,11 +49,11 @@ The `Window` class also defines the following modal navigation events: - `ModalPushing`, with `ModalPushingEventArgs`, which is raised when a view is modally pushed. - `PopCanceled`, which is raised when a modal pop is cancelled. -The class has a `Window` property that exposes the parent `Window` object. This property can be accessed from any page, layout, or view, to manipulate `Window` objects. +The class has a `Window` property that exposes the parent object. This property can be accessed from any page, layout, or view, to manipulate objects. ## Create a Window -By default, .NET MAUI creates a `Window` object when you set the `MainPage` property to a object in your `App` class. However, you can also override the `CreateWindow` method in your `App` class to create a `Window` object: +By default, .NET MAUI creates a object when you set the `MainPage` property to a object in your `App` class. However, you can also override the `CreateWindow` method in your `App` class to create a object: ```csharp namespace MyMauiApp @@ -79,9 +79,9 @@ namespace MyMauiApp } ``` -While the `Window` class has a default constructor and a constructor that accepts a argument, which represents the root page of the app, you can also call the base `CreateWindow` method to return the .NET MAUI created `Window` object. +While the class has a default constructor and a constructor that accepts a argument, which represents the root page of the app, you can also call the base `CreateWindow` method to return the .NET MAUI created object. -In addition, you can also create your own `Window`-derived object: +In addition, you can also create your own -derived object: ```csharp namespace MyMauiApp @@ -101,20 +101,20 @@ namespace MyMauiApp } ``` -The `Window`-derived class can then be consumed by creating a `MyWindow` object in the `CreateWindow` override in your `App` class. +The -derived class can then be consumed by creating a `MyWindow` object in the `CreateWindow` override in your `App` class. -Regardless of how your `Window` object is created, it will be the parent of the root page in your app. +Regardless of how your object is created, it will be the parent of the root page in your app. ## Multi-window support -Multiple windows can be simultaneously opened on Android, iOS on iPad (iPadOS), Mac Catalyst, and Windows. This can be achieved by creating a `Window` object and opening it using the `OpenWindow` method on the `Application` object: +Multiple windows can be simultaneously opened on Android, iOS on iPad (iPadOS), Mac Catalyst, and Windows. This can be achieved by creating a object and opening it using the `OpenWindow` method on the `Application` object: ```csharp Window secondWindow = new Window(new MyPage()); Application.Current.OpenWindow(secondWindow); ``` -The `Application.Current.Windows` collection, of type `IReadOnlyList` maintains references to all `Window` objects that are registered with the `Application` object. +The `Application.Current.Windows` collection, of type `IReadOnlyList` maintains references to all objects that are registered with the `Application` object. Windows can be closed with the `Application.Current.CloseWindow` method: @@ -173,12 +173,12 @@ Then, in the XML editor, open the **Platforms > iOS > Info.plist** file and the ## Position and size a Window -The position and size of a window can be programmatically defined for a .NET MAUI app on Windows by setting the `X`, `Y`, `Width`, and `Height` properties on a `Window` object. +The position and size of a window can be programmatically defined for a .NET MAUI app on Windows by setting the `X`, `Y`, `Width`, and `Height` properties on a object. > [!WARNING] > Mac Catalyst doesn't support resizing or repositioning windows programmatically by setting the `X`, `Y`, `Width`, and `Height` properties. -For example, to set the window position and size on launch you should override the `CreateWindow` method in your `App` class and set the `X`, `Y`, `Width`, and `Height` properties on a `Window` object: +For example, to set the window position and size on launch you should override the `CreateWindow` method in your `App` class and set the `X`, `Y`, `Width`, and `Height` properties on a object: ```csharp public partial class App : Application @@ -231,3 +231,57 @@ Dispatcher.Dispatch(() => Window.MaximumHeight = double.PositiveInfinity; }); ``` + +::: moniker range=">=net-maui-8.0" + +## Decouple window management from the App class + +Window management can be decoupled from the `App` class by creating a class that implements the `IWindowCreator` interface, and adding your window management code in the `CreateWindow` method: + +```csharp +public class WindowCreator : IWindowCreator +{ + public Window CreateWindow(Application app, IActivationState activationState) + { + var window = new Window(new ContentPage + { + Content = new Grid + { + new Label + { + Text = "Hello from IWindowCreator", + HorizontalOptions = LayoutOptions.Center, + VerticalOptions = LayoutOptions.Center + } + } + }); + + return window; + } +} +``` + +Then, in the `MauiProgram` class you should register your window management type as a dependency in the app's service container: + +```csharp +builder.Services.AddSingleton(); +``` + +> [!IMPORTANT] +> Ensure that your registration code specifies the `IWindowCreator` interface as well as its implementing type. + +Then, ensure that your `App` class doesn't set the `MainPage` property: + +```csharp +public partial class App : Application +{ + public App() + { + InitializeComponent(); + } +} +``` + +Provided that the `IWindowCreator` interface and its implementing type have been registered with the app's service container, and that the property of the class isn't set, your registered type will be used to create the . + +::: moniker-end diff --git a/docs/whats-new/dotnet-8.md b/docs/whats-new/dotnet-8.md index a91967d734..4e73509535 100644 --- a/docs/whats-new/dotnet-8.md +++ b/docs/whats-new/dotnet-8.md @@ -1,7 +1,7 @@ --- title: What's new in .NET MAUI for .NET 8 description: Learn about the new features introduced in .NET MAUI for .NET 8. -ms.date: 10/10/2023 +ms.date: 10/24/2023 --- # What's new in .NET MAUI for .NET 8 @@ -40,6 +40,7 @@ For information about what's new in .NET 8, see [What's new in .NET 8](/dotnet/c - The class gains the `NearbyWifiDevices` permission, which is an Android 13 permission for accessing nearby WiFi devices. For more information, see [Permissions](~/platform-integration/appmodel/permissions.md). - Several system fonts can be easily consumed in Android apps. For more information, see [Consume fonts](~/user-interface/fonts.md#consume-fonts). - Shell navigation gains a `GoToAsync` overload that enables you to pass single use navigation data, that's cleared after navigation has occurred, as a `ShellNavigationQueryParameters` object. For more information, see [Pass data](~/fundamentals/shell/navigation.md#pass-data). +- Window management can be decoupled from the `App` class. For more information, see [Decouple window management from the App class](~/fundamentals/windows.md#decouple-window-management-from-the-app-class). The following types or members have been deprecated: