WinUI3 Window and Application API updates #71
Conversation
Adding draft of Window and Application API Specs to support Win32
|
You Also it's not clear to me whether Also I'd use the IsVisible property to determine whether I can close it or not, but if it's minimized that wouldn't work. |
* Update Window_and_Application_API_Spec.md I don't know what the property should be called there, but definitely not Visible. :-) * Update Window_and_Application_API_Spec.md Change WindowSize to just Size
Updating to align more with the API spec template
|
|
||
| ### Remarks | ||
|
|
||
| If this was the last window to be closed for the app, the Suspending event will be raised. For a Desktop app, the application will end. |
There was a problem hiding this comment.
Which comes first, Closed or Suspending? Doesn't Suspending also get raised in Desktop apps?
| // AS is an extension method in the WinRT.CastExtensions class. | ||
| // The WinRT namespace is needed to use the extension method. | ||
| var windowNative = m_window.As<IWindowNative>(); | ||
| IntPtr HWND = windowNative.WindowHandle; |
There was a problem hiding this comment.
The type should be HWND rather than IntPtr
|
|
||
| ### Properties | ||
|
|
||
| - Handled: Gets or sets whether the event was handled. **true** if the event has been handled by the appropriate delegate; **false** if it has not. |
There was a problem hiding this comment.
What does it mean to set this to true? What is the implication?
| } | ||
| ``` | ||
|
|
||
| Title bars should be have background and foreground colors based on |
There was a problem hiding this comment.
"Title bars should have background"... the be is not needed
|
|
||
| ## Window.ExtendsContentIntoTitleBar | ||
|
|
||
| Gets or sets a value that specifies whether the default window title bar should be removed, creating more space for content. |
There was a problem hiding this comment.
Rather than saying it makes more space, might it not be better and more accurate to say something like it allows the App's UI to extend to the top of the window's frame, where the titlebar would usually be.
There was a problem hiding this comment.
Should also clarify that the (0,0) point for the Window.Content is now the upper left corner of the title bar area. (If true.)
There was a problem hiding this comment.
Recommend: yes, update wording and clarify like this.
| However, even when the default system title bar is not hidden, SetTitleBar can be used to make | ||
| additional regions in your app behave like the title bar. | ||
|
|
||
| The following shows a Window with a no built-in title bar. |
There was a problem hiding this comment.
"The following shows a Window with a no built-in title bar." remove a
|
|
||
| The following shows a Window with a no built-in title bar. | ||
| Instead it uses the whole window as its content area. To enable features such as window dragging, | ||
| it designates a TextBlock as the title bar. |
There was a problem hiding this comment.
Do you want the example to use the TextBlock as the titlebar, or the <Grid> containing the TextBlock? If so, the Grid should also use a background color of Transparent for hit testing.
There was a problem hiding this comment.
Discussion: It should be the TextBlock. The other parts of the Grid could be e.g. buttons that you want to interact with.
Recommend: Add some buttons or some such to make this more clear.
|
Will there be support for WinUI 3 Windows which can hide the Minimise and Maximise buttons, much like the modal dialogs seen commonly in win32 apps - as well as MessageBoxes etc? I know these will probably be ignored by UWP app windows.
|
| In a UWP app you must create a new | ||
| [CoreApplicationView](https://docs.microsoft.com/uwp/api/Windows.ApplicationModel.Core.CoreApplicationView), | ||
| which will automatically create a new thread and a Window on it. | ||
| See the 'Create new Window in UWP application' example. |
There was a problem hiding this comment.
What if I new a Window while on the Dispatcher for a CoreWindow? Could that create me a new AppWindow instead?
There was a problem hiding this comment.
Discussion: If you 'new' a Window it will fail, just like today (in UWP apps). AppWindow is not being supported at this time.
| object for the Window when called from a UWP app. Returns null when called from a Desktop app. | ||
|
|
||
| ```CS | ||
| public CoreDispatcher Dispatcher { get; } |
There was a problem hiding this comment.
So we end up with both Dispatcher and DispatcherQueue as aliases of each other? Should this property be insta-deprecated to help developers move to the preferred one instead?
|
|
||
| ### Remarks | ||
|
|
||
| The following events and virtual methods are not invoked when running in a Desktop app: |
There was a problem hiding this comment.
Maybe link over to the Project Reunion issue thread on Win32-facing activation events so folks know they're not out of luck?
There was a problem hiding this comment.
Discussion: You can also use Win32 (hwnd) APIs for some of this.
Recommend: Reference Project Reunion issue thread.
| which are always created on a new thread, and which automatically create the following for the new thread: | ||
| [ApplicationView](https://docs.microsoft.com/uwp/api/Windows.UI.ViewManagement.ApplicationView), | ||
| [CoreWindow](https://docs.microsoft.com/uwp/api/Windows.UI.Core.CoreWindow), | ||
| and the Xaml [Window](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window). |
There was a problem hiding this comment.
Need to mention that Window.Current does not work for Desktop apps and always returns null.
There was a problem hiding this comment.
Recommend: It's in the description, but add here too is good.
| var syncContext = new DispatcherQueueSyncronizationContext(); | ||
| SynchronizationContext.SetSynchronizationContext(syncContext); | ||
|
|
||
| this.ProcessEvents(); // Message pump |
There was a problem hiding this comment.
What class does this refer to? The only class/interface with an arity-0 ProcessEvents() that I can find is INativeWindow, but that's part of OpenTK for iOS, so probably not what we are referring to. So what is it?
There was a problem hiding this comment.
Discussion: this is app code.
Recommend: Show the enclosing class context.
| window.Activate(); | ||
| window.Closed += (_, __) => w.DispatcherQueue.InvokeShutdown(); | ||
|
|
||
| var syncContext = new DispatcherQueueSyncronizationContext(); |
There was a problem hiding this comment.
| var syncContext = new DispatcherQueueSyncronizationContext(); | |
| var syncContext = new DispatcherQueueSynchronizationContext(); |
| thread.Start(); | ||
| ``` | ||
|
|
||
| > Spec note: The DispatcherQueueSyncronizationContext is a new API |
There was a problem hiding this comment.
| > Spec note: The DispatcherQueueSyncronizationContext is a new API | |
| > Spec note: The DispatcherQueueSynchronizationContext is a new API |
|
|
||
| Gets or sets a value that specifies whether the default window title bar should be removed, creating more space for content. | ||
|
|
||
| Setting this property to true causes the built-in title bar to be removed. |
There was a problem hiding this comment.
Misleading. The title bar isn't removed. (As evidenced that you can still do title-bar things, like dragging.) It just lets the app draw in the title bar area, and the system no longer draws the title bar.
There was a problem hiding this comment.
Discussion: If you just call Extends, the input behavior of the title bar is still there.
Recommend: Clarify
|
|
||
| **Handled** | ||
|
|
||
| Gets or sets whether the window activation changed event was handled. **true** |
There was a problem hiding this comment.
copy/pasta. (Also, same question about what "Handled" means here.)
There was a problem hiding this comment.
Recommend: specify Handled behavior.
|
|
||
| **Visible** | ||
|
|
||
| Gets whether the window is visible or not. **true** if the window is visible; otherwise is **false**. |
There was a problem hiding this comment.
"is" or "was"? This is an "-ed" event, so the property presumably refers to whether the window was made visible or not, rather than referring to the window's current visibility state (which you can obtain from the Window.Visible property.)
There was a problem hiding this comment.
Discussion: This tells you the current state (what it changed too).
Recommend: Does this get updated when the window is minimized?
| **Arguments** | ||
|
|
||
| Gets the arguments that are passed to the app during its launch. | ||
| In a UWP app, this is equivalent to LaunchActivatedEventArgs.Arguments. |
There was a problem hiding this comment.
I assume that for a Desktop app, the Arguments is the raw command line that comes after the program name (leading spaces preserved)? I.e., we don't try to parse it in any way with CommandLineToArgvW or anything like that?
There was a problem hiding this comment.
Recommend: yes, specify exactly what it is here (for example does it have the process name as the first argument).
|
|
||
| // These APIs match the system Xaml versions, except the event args are now from the Xaml namespace | ||
| event Windows.Foundation.TypedEventHandler<Object,Microsoft.UI.Xaml.XamlWindowActivatedEventArgs> Activated; | ||
| event Windows.Foundation.TypedEventHandler<Object,Microsoft.UI.Xaml.XamlWindowClosedEventArgs> Closed; |
There was a problem hiding this comment.
Missing from spec. Did we intend to keep this? Or did we forget to delete it from the IDL?
There was a problem hiding this comment.
Discussion: in UWP this only raises on secondary windows, not the primary window.
Recommend: add full description. Are there differences between UWP and Desktop?
| with this Window. In a Desktop app this is always null. | ||
|
|
||
| ```CS | ||
| public CoreWindow CoreWindow { get; } |
There was a problem hiding this comment.
There's no reason to expose CoreWindow and CoreDispatcher. If UWP apps really need these, just use the existing static methods on those types. (i.e. CoreWindow.GetForCurrentThread)
| Window window = new Window(); | ||
| window.Content = new TextBlock() { Text = "Hello" }; | ||
| window.Activate(); | ||
| window.Closed += (_, __) => w.DispatcherQueue.InvokeShutdown(); |
There was a problem hiding this comment.
Sample feedback. Please use real variable names, not "_".
| the Window's underlying HWND. | ||
|
|
||
| ```CS | ||
| protected override void OnLaunched(Microsoft.UI.Xaml.XamlLaunchActivatedEventArgs e) |
There was a problem hiding this comment.
I don't understand this sample. Is it in C#, which wouldn't have the IWindowNative interface definition, or in C++, which wouldn't have this language syntax.
There was a problem hiding this comment.
Discussion: We usually do interop samples in C++, but as it is here there's a lot of context that's not given.
Recommend: either write in C++ or provide more context for C#.
|
|
||
| > Spec note: Application is not new to this spec, what is new are the following remarks | ||
|
|
||
| ### Remarks |
There was a problem hiding this comment.
Should we do some refactoring here, such as creating a DesktopApplication and UwpApplication? It gets confusing if we have a lot of things that never work for Win32, and this is becoming a front and center scenario?
| ```cs | ||
| [webhosthidden] | ||
| [contentproperty("Content")] | ||
| unsealed runtimeclass Window |
There was a problem hiding this comment.
Important to specify event order. Does VisibilityChanged get fired before or after SizeChanged? Does VisibilityChanged get fired when minimized?
There was a problem hiding this comment.
Discussion: this is specified in detail today. When exactly do events raise or not raise (what modes), and in what order?
Recommend: define and specify event ordering.
There was a problem hiding this comment.
If visibility maps to ShowWindow(SW_HIDE/SW_SHOW) and IsWindowVisible, I don't think it should fire, since a minimized app is still "visible".
| which are always created on a new thread, and which automatically create the following for the new thread: | ||
| [ApplicationView](https://docs.microsoft.com/uwp/api/Windows.UI.ViewManagement.ApplicationView), | ||
| [CoreWindow](https://docs.microsoft.com/uwp/api/Windows.UI.Core.CoreWindow), | ||
| and the Xaml [Window](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Window). |
There was a problem hiding this comment.
Recommend: It's in the description, but add here too is good.
| var syncContext = new DispatcherQueueSyncronizationContext(); | ||
| SynchronizationContext.SetSynchronizationContext(syncContext); | ||
|
|
||
| this.ProcessEvents(); // Message pump |
There was a problem hiding this comment.
Discussion: this is app code.
Recommend: Show the enclosing class context.
| In a UWP app you must create a new | ||
| [CoreApplicationView](https://docs.microsoft.com/uwp/api/Windows.ApplicationModel.Core.CoreApplicationView), | ||
| which will automatically create a new thread and a Window on it. | ||
| See the 'Create new Window in UWP application' example. |
There was a problem hiding this comment.
Discussion: If you 'new' a Window it will fail, just like today (in UWP apps). AppWindow is not being supported at this time.
|
|
||
| ## Window.ExtendsContentIntoTitleBar | ||
|
|
||
| Gets or sets a value that specifies whether the default window title bar should be removed, creating more space for content. |
There was a problem hiding this comment.
Recommend: yes, update wording and clarify like this.
|
|
||
| Creating a new Window in a Desktop app creates a new top level HWND. | ||
|
|
||
| ## Window.ExtendsContentIntoTitleBar |
There was a problem hiding this comment.
Is there some kind of AppWindowTitleBar.GetTitleBarOcclusions support?
|
|
||
| **Visible** | ||
|
|
||
| Gets whether the window is visible or not. **true** if the window is visible; otherwise is **false**. |
There was a problem hiding this comment.
Discussion: This tells you the current state (what it changed too).
Recommend: Does this get updated when the window is minimized?
| **Arguments** | ||
|
|
||
| Gets the arguments that are passed to the app during its launch. | ||
| In a UWP app, this is equivalent to LaunchActivatedEventArgs.Arguments. |
There was a problem hiding this comment.
Recommend: yes, specify exactly what it is here (for example does it have the process name as the first argument).
|
|
||
| // These APIs match the system Xaml versions, except the event args are now from the Xaml namespace | ||
| event Windows.Foundation.TypedEventHandler<Object,Microsoft.UI.Xaml.XamlWindowActivatedEventArgs> Activated; | ||
| event Windows.Foundation.TypedEventHandler<Object,Microsoft.UI.Xaml.XamlWindowClosedEventArgs> Closed; |
There was a problem hiding this comment.
Discussion: in UWP this only raises on secondary windows, not the primary window.
Recommend: add full description. Are there differences between UWP and Desktop?
|
|
||
| Gets whether the window is visible or not. **true** if the window is visible; otherwise is **false**. | ||
|
|
||
| ## XamlWindowSizeChangedEventArgs class |
There was a problem hiding this comment.
Recommend: specify the units
Adding draft of Window and Application API Specs to support Win32