microsoft / microsoft-ui-xaml-specs

API spec repository for the Windows UI Library (WinUI)

Windows UI Library (WinUI) Specs

This repository contains archived and in-progress spec documents for APIs in the Windows UI Library (WinUI):
https://github.com/Microsoft/microsoft-ui-xaml

Documents in this repo are used as part of Microsoft's WinUI spec review process for features in development and are not intended to be up-to-date developer documentation.

For up-to-date developer documentation on WinUI and related APIs please see:
https://docs.microsoft.com/windows/uwp

For product issues, bugs, and feature requests please use the main WinUI repo:
https://github.com/Microsoft/microsoft-ui-xaml

Contributing

This repo is maintained by the Microsoft WinUI team.

Please DO:

• provide feedback by commenting on active pull requests. Open PRs are for specs in the early feature review process
• provide feedback by opening issues regarding spec documents in the active folder. Specs in the active folder represent new features that are being implemented for a future release

Please DO NOT:

• provide feedback on spec documents in the archive folder since those features have already been released. Please contribute feedback or suggested changes to docs.microsoft.com instead.
• send us unsolicited PRs that add new specs. To propose a new feature, please follow the WinUI contribution process described here which starts with opening an issue in the WinUI repo:
  https://github.com/Microsoft/microsoft-ui-xaml
• rely on this repo for final developer documentation. Please see docs.microsoft.com.

Spec workflow

For WinUI team members, the workflow to author specs is:

1. Ensure your proposal is approved and in plan.

2. Create a new working branch: /user/<username>/<feature>

3. Create a new folder for your spec under the active folder: /active/<feature>

4. Author your spec using the spec template.
   Please use relative links for images or other assets in the folder.

5. When your spec is ready for review:

   • Open a new pull request to merge your spec to the master branch
   • Update your proposal issue with a link to the spec PR

6. Review spec in checkpoint meetings to close open issues.

7. When your spec is complete and signed off, merge the PR.

8. Use your completed spec as the basis for Microsoft Docs articles and Controls Gallery samples.

9. Once the feature is documented:

   • Close the proposal issue
   • Add the following header to your spec:

     This spec is archived and may not be up to date.
     For up-to-date developer documentation please see: <insert link>

   • Move your spec from /active to /archive/<release>

Legal Notices

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://privacy.microsoft.com.

Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.

microsoft-ui-xaml-specs's Issues

Window & CoreWindow name conflict.

I've raised this issue before, but now that you are actually rebuilding the API's it seems like a great time to bring it up again.

Take a look at these names ..

Windows.UI.Xaml.Window
Windows.UI.Core.CoreWindow

That doesn't read right to me at all. CoreWindow is a type of Window, and Window is a type of Window, but CoreWindow is not a type of Window?

Why don't you choose either a or b pattern as follows ..

a)

Windows.UI.Xaml.XamlWindow
Windows.UI.Core.CoreWindow

b)

Windows.UI.Xaml.Window
Windows.UI.Core.Window

Then you have consistency, either adopting specialized names for the respective types. Or a common conceptual name in the respective namespaces. Either option would seem more consistent and would respectively free up either Window or the CoreWindow/XamlWindow name pair for our usage.

It just seems like they were each written by different people who didn't communicate.

And it's especially strange, although I don't know the underlying code, but to me it seems like if anything - CoreWindow would be the underlying Window because it provides the base rendering surface and XamlWindow (what you call Window) would be the child type because it makes sense that you take a Window (with Core functionality) and then render a root control inside that window - the XamlWindow.

And in a future scenario that XamlWindow could be replaced with another type of specialized window model - HttpWindow, FlutterWindow, GameWindow - providing whatever logic/rendering stack you want inside that Window (the container).

Interaction Trigger does not work for NumberBox

WebView2_spec: Missing WebResourceRequested event?

After looking through the specs for the upcoming WebView2, it seems that the WebResourceRequested event is missing. Are there plans to implement this?

This API is especially handy, and the only alternative is injecting an override wrapper for fetch and Ajax requests, which catches the Javascript requests, but not the resources declared in the DOM or CSS.

Window and Application API Spec - Suggested Updates

Window Spec Review

While trying to decide if I could migrate a significant amount of WPF XAML over to WinUI, I needed to understand the
Windowing model for WinUI Desktop applications. I was pointed to the Window and Application API Spec as a source
of information. Since the Windowing model is really important to the type of applications I write, I spent extra time
reading over this spec. Trust me that I never intended to provide a thorough peer review like this, the initial goal was
to mention the issues I had with the IWindowInterop class, but I ended up adding everything I came across.

Disclaimer, this text came from notes I was taking in VSCode.  The VSCode formatter kept injecting carriage 
returns which make the width of my text lines narrow.  

1. Under execution notes it mentions the namespace Window.UI.Xaml.Window .
   I think it should be Windows.UI.Xaml.Window with Windows being plural.

Already exists in Window.UI.Xaml.Window.

2. Windows Misspelled

   Multiple Widndows Sample

3. The word proposed used twice

   There are other proposed APIs proposed that will be part of the future phases.

4. Markup example does not match code example

   The code example shows how to add a TextBox to the Window, the markup example
   shows how to add a grid with a button. Typically you see these examples show
   how to achieve the same thing with code vs xaml.

5. This section
   indicates that multiple windows are supported. I understand this is just a
   spec, but I was pointed to this spec by another Microsoft developer and its
   hard for me to know what's implemented and what isn't.

6. Throughout the document the XAML and code examples use mixed quotation
   marks that cause compilation errors. For example, see this markup example
   and notice how the button's content property and Click handler are assigned
   using ” as a quotation mark instead of " .

7. The Multiple Window Example inside the click handler has a missing
   semicolon

   private void OnClick(object sender, RoutedEventArgs e)
   {
      Window w2 = new Window ();
      w2.Content = new TextBlock(){Text=”Window 2”}  //Need a ; here and fix quotes too
      w2.Activate();
   }

8. The example to create a Window in a separate thread has compilation errors and seems like a WPF copy and paste.

   Maybe this example is "how it will eventually be"? This code will
   not compile under UWP or WinUI Desktop because InvokeShutdown() is not
   defined on Dispatcher which happens to be a CoreDispatcher. The
   Dispatcher.Run() cannot be found either. This is normally in WindowsBase.dll.

   This code is perfectly valid WPF code, it compiles under WPF. If the end user
   needs to include a different NuGet package then we should let them know.

  private void Button_Click(object sender, RoutedEventArgs e)
  {
      Thread thread = new Thread(() =>
      {
          Window w = new Window();
          w.Content = new TextBlock() { Text = "Separated Thread Window" };
          w.Activate();

          // w.Dispatcher.InvokeShutdown() not found on CoreDispatcher type
          w.Closed += (sender1, e1) => w.Dispatcher.InvokeShutdown();

          //Not found.  This is usually in WindowsBase.dll
          System.Windows.Threading.Dispatcher.Run();

      });
      thread.SetApartmentState(ApartmentState.STA);
      thread.IsBackground = true;
      thread.Start();
  }

9. In This Section
   Maybe it should clarify that a developer needs to use the Win32 pinvoke APIs to
   change the window size. Also, the word specify should be specified.

   Win32: The Window is created with the default size of the Window specify by
   the Window Shell.

10. Since the Window does not have an Icon and the document says its a new
    property I will assume that its a future property and not in the current release.

    Small issues like these send developers off on a Google / Bing search mission
    wondering why its not there and how to use pinvoke calls to resolve it.

11. The code example for VisibilityChanged uses the wrong event arg type.

//Should use WindowVisibilityChangedEventArgs
private void OnVisibilityChanged(object sender, VisibilityChangedEventArgs e)
{
   if (e.Visible)
   {
      //
   }
}

12. The Remarks section for Win32 has a simple grammar error. Do should be changed to does.

Win32: This method do nothing when running in Win32.

13. The code sample for the Window.Activated event will not compile. See
    below for required changes.

window.Actived += OnActivated; // Activated is not spelled correctly

14. The sample event handler prefixes the event args with 'MUX' and this one is similar.

    None of the other examples use MUX. This can cause a newbie developer to create help posts
    on Reddit wondering what it was. I think its great to include namespaces when it is done
    consistently or it is at least defined.

15. The example using the IWindowInterop interface will not compile because the classes required cannot be found anywhere.

    This example is truly what led to me creating this document. Another
    Microsoft employee pointed me to this example as a method of obtaining the
    Window's handle. I spent quite a bit of time blaming myself for not being
    able to locate the COM interface or any potential extension methods. Both
    Google and Github return one result and it points back to the same github
    issue where I was asking how to do this. Here is the solution.

    Window w = new Window();
    //IWindowInterop is where? Where is QueryInterface?
    w.QueryInterface(IWindowInterop);
    IntPtr hwnd = w.GetInterop<IWindowInterop>().Handle;

16. This section on Window.UIContext talks about removing that property. I
    might be mistaken but I think it is already gone and could be yanked from
    the document.

17. The wrong type is listed for WindowActivationState

    //The proper type is Microsoft.UI.Xaml.WindowActivatedEventArgs
    public CoreWindowActivationState WindowActivationState { get; }

18. Similar to above, The VisibilityChangedArgs should be
    Microsoft.UI.Xaml.WindowVisibilityChangedEventArgs

19. The example code for override of OnLaunched has multiple compilation
    errors.

    The line window.FileName = arguments[0] is missing a semicolon but this
    code snippet would only be meaningful in the context of an additional class
    'MainWindow' that had a property on it called FileName. Without knowing
    that the reader could be led to believe that the Window class has a FileName
    property because the entire document is about the Window.

    Out of curiosity I tried to create a UWP WinUI app, declared a window and
    called Activate just as was done below. This led to an access violation.
    Considering I am new to UWP and this was outside the scope of what I wanted
    to do today, I didn't dig in to see if this code snippet could be logically
    used in UWP or not, maybe the author should double check that.

    Note that the section about the event arg type LaunchActivatedEventArgs is out
    of order from the section that lists the event. Maybe the LaunchActivatedEventArgs
    section should be right next to the OnLaunched section.

    //Note that this also includes the MUX namespace
    protected override void OnLaunched(MUX.LaunchActivatedEventArgs e)
    {
         MainWindow window = new MainWindow();

         if(e.Arguments != null)
         {
            string[] arguments = e.Arguments.Split(' ');
     window.FileName = arguments[0]
         }

         window.Activate();

    }

21. Application APIs that are no called on Win32 uses the word "no" but I think the author
    intended to use "not" or "now". I am guessing "not" but there is a big difference between the two.

WebView2_spec: Missing PermissionRequested

Forgive me if this is the wrong place to add this. Just pulled down the latest WinUI 3.0 Alpha (February 2020) bits to start kicking the tires with WebView2. I noticed PermissionRequested is not available. Not sure if this is still the proper way to handle permission granting for things like UserMedia access?

Is this currently scoped, or is there a different way to handle granting permissions?

NumberBox does not respect ThemeManager theme

I implemented NumberBox in my application that is set up to work in Dark Mode. However, NumberBox did not respect the theme.

Specifying ThemeManager.RequestedTheme on the control itself can be used as a workaround.

<ui:NumberBox Header="Clients to start" Value="{Binding NumberOfClientsToStart, Mode=TwoWay}" InputScope="Number" SpinButtonPlacementMode="Compact" Text="Clients to start"/>

<ui:NumberBox Header="Clients to start" Value="{Binding NumberOfClientsToStart, Mode=TwoWay}" InputScope="Number" SpinButtonPlacementMode="Compact" Text="Clients to start" ui:ThemeManager.RequestedTheme="Dark"/>

Provide guidance in README about how to provide feedback on the spec

If it's in PR great, but if it's in the Active folder, is opening an issue the best practice? It'd be great for the readme to elaborate on how to contribute a bit more clearly. Thanks!

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Rename default branch to main

Hey,

Just wanted to know if you were planning on renaming the default branch from "master" to "main" like the microsoft-ui-xaml repo ?

I was recently changing the links in the WPF repo that were still pointing to "master" branch and the only repo left was this one.

I left it out of my PR for now but it would be great if you would like to change this repo's default branch name.

Thank you!

Win32 Xaml.Window WindowSizeChangedEventArgs.Visible is incorrect property.

Sorry if this is not the proper place for this issue, I don't see how to open an issue for a specific branch. Meant for @marb2000

Branch: Win32
Document:
https://github.com/microsoft/microsoft-ui-xaml-specs/blob/Win32/active/Win32/Window_and_Application_API_Spec.md

"WindowSizeChangedEventArgs.Visible: Gets the new size of the window in units of effective (view) pixels.

public Size Visible { get; } "

This mentions 'Visible' but I suspect it should say 'Bounds' or 'Size'