diff --git a/active/Win32/Window_and_Application_API_Spec.md b/active/Win32/Window_and_Application_API_Spec.md index f78817980..d876ed717 100644 --- a/active/Win32/Window_and_Application_API_Spec.md +++ b/active/Win32/Window_and_Application_API_Spec.md @@ -1,63 +1,70 @@ -# Window and Application API Spec +# Window and Application API updates -This spec describes updates to the XAML Window and Application APIs to accommodate this move to support Desktop (win32) apps. +This spec describes updates to the XAML Window and Application APIs to enable them to support Desktop apps in addition to UWP. -## Spec Status -In review. No scheduled yet for reviewing by the API Board. +# Background +Xaml in UWP has a [Window](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window) class which wraps a [CoreWindow](https://docs.microsoft.com/uwp/api/Windows.UI.Core.CoreWindow), and an [Application](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Application) class which wraps a [CoreApplication](https://docs.microsoft.com/uwp/api/Windows.ApplicationModel.Core.CoreApplication). For WinUI 3 this is being expanded to not require a CoreWindow or CoreApplication; Window can use an hwnd and Application can run a message pump. This spec has the API additions to Application and Window to support this. -## Execution Notes +Note that some existing APIs will also behave differently when running as a Desktop app. For example, the static Window.Current property today returns the Window for the current (calling) thread, but in a non-UWP app it will return null. Similarly the Window.CoreWindow property will be null when not running as UWP. -This API spec contains the the APIs under the following criteria: -1. Already exists in Window.UI.Xaml.Window. -2. Are part of the Mininum Viable Product +There is also one API not (yet) present in WinUI: [Window.SetTitleBar](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window.SetTitleBar). That API relies on a Composition feature that only exists for system Visuals and is not yet supported for WinUI Visuals. -There are other proposed APIs proposed that will be part of the future phases. -> A Phase doesn't correspond with a product version, it's just a set of Sprints with allocated resources to execute this work. -## Design Agreement -- The new Window implementation reuses the current Windows.UI.XAML.Window class and it will be placed under Microsoft.UI.XAML.Window. -- Current methods, events, and properties should still work for UWP and add the new Win32 support. -- These APIs use different code paths depending on whether WinUI 3 is running on Win32 or UWP. -- There are some APIs that don’t work on Win32 or UWP yet in this phase. Those APIs could return **null** or **throw** an exception depending on the case. +# Examples and API Notes -This agreement applies to the Application class too. +## Window class -## Window Class -Namespace: Microsoft.UI.Xaml +Window represents a WinUI application window. It can be used in a [UWP](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) app or a Desktop app. When run in a UWP app there can only be one instance on a thread. + +### Examples + +> Spec note: The only new API in this set of examples is the Window constructor. Shown here is the general description for the class, so that we can see it in full context. But none of the behavior for UWP apps is changed. + +Set the content of a given window and give it keyboard focus. ```CS -public class Window : IClosable +void InitializeAndActivateWindow(Window window) +{ + window.Content = new TextBlock() { Text = "Hello" }; + window.Activate(); +} ``` -### **Window management, appearance, and behaviors** +In a UWP app the read-only [Window.Current](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window.Current) property returns the Window for the current thread. (A thread has at most one Window and it's created automatically on each UI thread.) This property returns null on a non UI thread or in a Desktop app. -### Window() constructor **[NEW]** -The constructor initializes the Window object. Windows are created in the same thread where they are instantiated. Frequently, this thread is the UI Thread. +The following sets the content of the calling thread's Window in a UWP app and gives it keyboard focus. ```CS -public Window(); +Window.Current.Content = new TextBlock() { Text = "Hello" }; +Window.Current.Activate(); ``` -#### Samples -##### Code Sample + +In a Desktop app you create each Window, and you can create more than one Window on a thread. + ```CS Window window = new Window(); window.Content = new TextBlock() { Text = "Hello" }; window.Activate(); ``` -##### Markup Sample + +You can also define a new Window in markup: + +| Spec note: no tag is required because Window.Content is updating to become the [ContentPropertyAttribute](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Markup.ContentPropertyAttribute). ```XML -