Merge branch 'main' into alvinashcraft/main-cambrian-files-and-folders

Author: alvinashcraft

hub/apps/design/globalizing/loc-international-fonts.md

@@ -32,7 +32,7 @@ In the following table, the "Language tag" column lists the [BCP-47 language tag
 | Central Kurdish (Arabic) | ku-ARAB-IQ | Segoe UI |
 | Cherokee (Cherokee) | chr-CHER-US | Gadugi |
 | Chinese Simplified | zh-CN | Microsoft YaHei UI |
-| Chinese Traditional (Hong Kong) | zh-HK | Microsoft JhengHei UI |
+| Chinese Traditional (Hong Kong Special Administrative Region) | zh-HK | Microsoft JhengHei UI |
 | Chinese Traditional (Taiwan) | zh-TW | Microsoft JhengHei UI |
 | Croatian | hr-HR | Segoe UI |
 | Czech | cs-CZ | Segoe UI |

hub/apps/design/globalizing/use-utf8-code-page.md

@@ -1,7 +1,7 @@
 ---
-description: How to use UTF code pages in Windows apps.
 title: Use UTF-8 code pages in Windows apps
-ms.date: 01/11/2022
+description: How to use UTF code pages in Windows apps.
+ms.date: 06/21/2023
 ms.topic: article
 ms.custom: seo-windows-dev
 ---
@@ -16,7 +16,10 @@ UTF-8 is the universal code page for internationalization and is able to encode
 
 As of Windows Version 1903 (May 2019 Update), you can use the ActiveCodePage property in the appxmanifest for packaged apps, or the fusion manifest for unpackaged apps, to force a process to use UTF-8 as the process code page.
 
-You can declare this property and target/run on earlier Windows builds, but you must handle legacy code page detection and conversion as usual. With a minimum target version of Windows Version 1903, the process code page will always be UTF-8 so legacy code page detection and conversion can be avoided.
+> [!NOTE]
+> GDI doesn't currently support setting the ActiveCodePage property per process. Instead, GDI defaults to the active system codepage. To configure your app to render UTF-8 text via GDI, go to Windows **Settings** > **Time \& language** > **Language \& region** > **Administrative language settings** > **Change system locale**, and check **Beta: Use Unicode UTF-8 for worldwide language support**. Then reboot the PC for the change to take effect.
+
+You can declare the ActiveCodePage property, and target/run on earlier Windows builds, but you must handle legacy code page detection and conversion as usual. With a minimum target version of Windows Version 1903, the process code page will always be UTF-8, so legacy code page detection and conversion can be avoided.
 
 > [!NOTE]
 > An encoded character takes between 1 and 4 bytes. UTF-8 encoding supports longer byte sequences, up to 6 bytes, but the biggest code point of Unicode 6.0 (U+10FFFF) only takes 4 bytes.
@@ -59,22 +62,23 @@ You can declare this property and target/run on earlier Windows builds, but you
 ```
 
 > [!NOTE]
-> Add a manifest to an existing executable from the command line with `mt.exe -manifest <MANIFEST> -outputresource:<EXE>;#1`
+> Add a manifest to an existing executable from the command line with `mt.exe -manifest <MANIFEST> -outputresource:<EXE>;#1`.
 
 ## -A vs. -W APIs
 
 Win32 APIs often support both -A and -W variants.
 
 -A variants recognize the ANSI code page configured on the system and support `char*`, while -W variants operate in UTF-16 and support `WCHAR`.
 
-Until recently, Windows has emphasized "Unicode" -W variants over -A APIs. However, recent releases have used the ANSI code page and -A APIs as a means to introduce UTF-8 support to apps. If the ANSI code page is configured for UTF-8, -A APIs typically operate in UTF-8. This model has the benefit of supporting existing code built with -A APIs without any code changes.
+Until recently, Windows has emphasized "Unicode" -W variants over -A APIs. However, recent releases have used the ANSI code page and -A APIs as a means to introduce UTF-8 support to apps. If the ANSI code page is configured for UTF-8, then -A APIs typically operate in UTF-8. This model has the benefit of supporting existing code built with -A APIs without any code changes.
 
 ## Code page conversion
 
-As Windows operates natively in UTF-16 (`WCHAR`), you might need to convert UTF-8 data to UTF-16 (or vice versa) to interoperate with Windows APIs.
+Because Windows operates natively in UTF-16 (`WCHAR`), you might need to convert UTF-8 data to UTF-16 (or vice versa) to interoperate with Windows APIs.
 
 [MultiByteToWideChar](/windows/desktop/api/stringapiset/nf-stringapiset-multibytetowidechar) and [WideCharToMultiByte](/windows/desktop/api/stringapiset/nf-stringapiset-widechartomultibyte) let you convert between UTF-8 and UTF-16 (`WCHAR`) (and other code pages). This is particularly useful when a legacy Win32 API might only understand `WCHAR`. These functions allow you to convert UTF-8 input to `WCHAR` to pass into a -W API and then convert any results back if necessary.
-When using these functions with `CodePage` set to `CP_UTF8`, use `dwFlags` of either `0` or `MB_ERR_INVALID_CHARS`, otherwise an `ERROR_INVALID_FLAGS` occurs.
+
+Use `dwFlags` of either `0` or `MB_ERR_INVALID_CHARS` when using these functions with `CodePage` set to `CP_UTF8` (otherwise an `ERROR_INVALID_FLAGS` occurs).
 
 > [!NOTE]
 > `CP_ACP` equates to `CP_UTF8` only if running on Windows Version 1903 (May 2019 Update) or above and the ActiveCodePage property described above is set to UTF-8. Otherwise, it honors the legacy system code page. We recommend using `CP_UTF8` explicitly.

hub/apps/develop/windows-app-restore.md

@@ -57,3 +57,11 @@ For more info about the best practices of storing app data, see [Store and retri
 ## Write user-generated content to Known Folders
 
 Windows introduced [known folders](/windows/win32/shell/known-folders) with Windows Vista. Since that time, users have come to expect that they can find the content they create with their apps in those locations. Writing user-generated content to those locations has the added benefit that OneDrive will back up those folders, if enabled, to ensure they're available to the user on their new PC (see [Back up your folders with OneDrive](https://support.microsoft.com/office/back-up-your-folders-with-onedrive-d61a7930-a6fb-4b95-b28a-6552e77c3057)). By using standard Windows APIs to write your user-generated content to the known folders, you're improving the user experience, and decreasing friction in adopting your app.
+
+## Best practices for unpackaged apps
+
+If you can't package your app, then be sure that your installer implements the recommendations below. That will ensure that it's possible to backup and restore the **Start** menu shortcuts that enable installing on a new machine that's restored from backup.
+
+* Make sure that your installer specifies an `InstallLocation` value in its uninstall registry key. When using [Windows Installer](/windows/win32/msi/windows-installer-portal) specify this using [ARPINSTALLLOCATION](/windows/win32/msi/arpinstalllocation). That's needed in order to enable the mapping of the **Start** menu shortcuts to the product.
+* Make sure that that location is specific to the product; usually the sub-directory under `C:\Program Files\<Publisher>\<Application>`.
+* Make sure that your **Start** menu shortcuts have machine-independent `System.AppUserModel.ID` (AMUID) values. That's best done by specifying them explicitly in the shortcut metadata. For more info, see [Where to Assign an AppUserModelID](/windows/win32/shell/appids#where-to-assign-an-appusermodelid).

hub/apps/get-started/images/uno/screenshot1.png

@@ -2,7 +2,7 @@
 description: Learn how to get started building new apps for Windows desktop and modernizing existing apps.
 title: Writing apps for Windows
 ms.topic: article
-ms.date: 1/26/2023
+ms.date: 6/23/2023
 keywords: windows win32, desktop development
 ms.localizationpriority: medium
 ---
@@ -15,17 +15,25 @@ This article contains the information you need to get started building apps for
 
 Windows offers a wide range of options for building apps, including [C++](/windows/uwp/cpp-and-winrt-apis/), [.NET](/dotnet/), and other emerging technologies such as [open source tools on WSL](/windows/wsl/) and [Rust](../../dev-environment/rust/index.yml). With so many choices, it can be difficult to know where to begin.
 
+## IDE 
+
 [Visual Studio](/visualstudio) is the go-to development environment for most Windows developers, providing various starting points for different types of apps, each with their own strengths and project types ([here's a quick C# tutorial](/visualstudio/get-started/csharp/tutorial-console?view=vs-2022)). Every app type includes an app model that defines the app's lifecycle, a default UI framework, and access to a comprehensive set of APIs for using Windows features.
 
-If your app will only run on Windows, we recommend using the [Windows App SDK](../windows-app-sdk/index.md) and [WinUI 3](../winui/winui3/index.md). If you need your app to be cross-platform, consider [.NET MAUI](/dotnet/maui/what-is-maui), a [Progressive Web App (PWA)](/microsoft-edge/progressive-web-apps-chromium/), or [React Native for Windows](../../dev-environment/javascript/react-native-for-windows.md). There are many other options available as well ([here's a list of popular options](../../dev-environment/index.md)), but the above are some good starting points.
+[Visual Studio Code](https://code.visualstudio.com) is another popular tool, with extensions and support for a large number of development languages and tools. For languages other than C# and C++, it's a great place to start.
+
+## Languages and frameworks
+
+Many apps for Windows are written using [WPF](/dotnet/desktop/wpf/get-started/create-app-visual-studio?view=netdesktop-7.0) or [Windows Forms](/dotnet/desktop/winforms/getting-started-with-windows-forms?view=netframeworkdesktop-4.8), and they remain viable tools today.
+
+Looking to the future, if your app will only run on Windows we recommend investigating the [Windows App SDK](../windows-app-sdk/index.md) and [WinUI 3](../winui/winui3/index.md). If you need your app to be cross-platform, consider [.NET MAUI](/dotnet/maui/what-is-maui), a [Progressive Web App (PWA)](/microsoft-edge/progressive-web-apps-chromium/), or [React Native for Windows](../../dev-environment/javascript/react-native-for-windows.md). There are many other options available ([here's a list of popular options](../../dev-environment/index.md)), but the above are some good starting points.
 
 > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWQwHD]
 
 ## Create a WinUI 3 app
 
-The Windows UI Library (WinUI) 3 is the latest and recommended user interface (UI) framework for Windows desktop apps, including managed apps that use C# and .NET and native apps that use C++ with the Win32 API. By incorporating the [Fluent Design System](https://www.microsoft.com/design/fluent/#/) into all experiences, controls, and styles, WinUI provides consistent, intuitive, and accessible experiences using the latest UI patterns.
+The Windows UI Library (WinUI) 3 is the latest user interface (UI) framework for Windows desktop apps, including managed apps that use C# and .NET, and native apps that use C++ with the Win32 API. It is still under very active development, so while it might not be able to meet all your needs today it's maturing with [every release](/windows/apps/windows-app-sdk/stable-channel).
 
-WinUI 3 is available as part of the **[Windows App SDK](../windows-app-sdk/index.md)**. The Windows App SDK provides a unified set of APIs and tools that can be used in a consistent way by any C++ Win32 or C# .NET app on a broad set of target Windows OS versions.
+By incorporating the [Fluent Design System](https://www.microsoft.com/design/fluent/#/) into all experiences, controls, and styles, WinUI provides consistent, intuitive, and accessible experiences using the latest UI patterns. WinUI 3 is available as part of the **[Windows App SDK](../windows-app-sdk/index.md)**. The Windows App SDK provides a unified set of APIs and tools that can be used in a consistent way by any C++ Win32 or C# .NET app on a broad set of target Windows OS versions.
 
 > [!div class="button"]
 > [Install tools for the Windows App SDK](../windows-app-sdk/set-up-your-development-environment.md)

hub/apps/get-started/images/uno/screenshot2.png

@@ -497,7 +497,7 @@ In this section we'll add a new property to the **MainWindow** class. The proper
         }
     }
     ```
-    
+
 1. While we're editing the **MainWindow** class, go ahead and remove the **MyProperty** property from the `MainWindow.idl` (it's already been removed in the listing above), and from `MainWindow.h`, and from `MainWindow.cpp`.
 
 1. The code to populate the new collection property with images is shown in the **GetItemsAsync** and **LoadImageInfoAsync** methods below. Paste the include, the `using namespace` directives, and the two method declarations and definitions, into `MainWindow.xaml.h` and `MainWindow.xaml.cpp`.
@@ -912,7 +912,7 @@ In this section we'll use one-time data-bindings. A one-time binding is great fo
 1. In the data template, find the first **TextBlock** element (the one with its **Text** currently set to *ImageTitle*). Replace its **Text** value as shown below.
 
     > [!TIP]
-    > You can either copy and paste the markup below, or you can use IntelliSense in Visual Studio. To do that, select the current value that's inside the quotation marks, and type `{`. IntelliSense automatically adds the closing brace, and displays a code-completion list. You *could* scroll down to `x:Bind`, and double-click it. But it might be more efficient to type `x:` (note how `x:Bind` is then filtered to the of completion list), and press the TAB key. Now press the SPACE key, and type `ImageT` (as much of the property name `ImageTitle` as necessary to get it to the top of the completion list), and TAB.
+    > You can either copy and paste the markup below, or you can use IntelliSense in Visual Studio. To do that, select the current value that's inside the quotation marks, and type `{`. IntelliSense automatically adds the closing brace, and displays a code-completion list. You *could* scroll down to `x:Bind`, and double-click it. But it might be more efficient to type `x:` (note how `x:Bind` is then filtered to the top of the completion list), and press the TAB key. Now press the SPACE key, and type `ImageT` (as much of the property name `ImageTitle` as necessary to get it to the top of the completion list), and TAB.
 
     ```xaml
     <TextBlock Text="{x:Bind ImageTitle}"

hub/apps/get-started/images/uno/screenshot3.png

@@ -65,6 +65,7 @@ The Uno Platform App template comes with two preset options that allow you to qu
 To keep things simple, select the **Blank** preset. Then, click the **Create** button. Wait for the projects to be created and their dependencies to be restored.
 
 A banner at the top of the editor may ask to reload projects, click **Reload projects**:
+
 :::image type="content" source="../images/visual-studio-2022-project-reload.png" alt-text="Screenshot of the Visual Studio banner offering to reload your projects to complete changes.":::
 
 You should see the following default file structure in your **Solution Explorer**: