From 3d650ce0e420de1ab8216bb46c74db450e6fc25c Mon Sep 17 00:00:00 2001 From: Steven Date: Tue, 1 Nov 2022 13:53:04 -0700 Subject: [PATCH 1/9] adding draft for locale api review --- specs/LocaleRegion.md | 92 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 specs/LocaleRegion.md diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md new file mode 100644 index 000000000..30be14ddc --- /dev/null +++ b/specs/LocaleRegion.md @@ -0,0 +1,92 @@ +LocaleRegion +=== + +# Background +Developers have requested access to programmatically choose the specific locale/region to use in WebView2. +The locale/region updates the JavaScript region (objects in the ECMA standard) which gets reflected as +variations in time and date formats. Currently, the locale is by default set to the same value as the +display language. + +You can use the `LocaleRegion` API to update the locale value individually from the display +language. + +# Description +* The intended value for `LocaleRegion` is in the format of `language[-country]` where `language` is the +2-letter code from [ISO 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the +2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). +* By default, the `LocaleRegion` will be set as the value for the Limited option in the browser. +That means that if the OS region and the display language share the same language code, +like 'en-GB' and 'en-US', the value will be set to the OS region. + +# Examples +```cpp +auto webViewEnvironment10 = m_webViewEnvironment.try_query(); +wil::com_ptr options; +HRESULT hr = webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options); +options->put_LocaleRegion(m_webviewOption.localeRegion.c_str()); +``` + +```c# +CoreWebView2Environment _webViewEnvironment; +WebViewCreationOptions _creationOptions; +public CreateWebView2Controller(IntPtr parentWindow) +{ + CoreWebView2ControllerOptions controllerOptions = new CoreWebView2ControllerOptions(); + controllerOptions.LocaleRegion = _creationOptions.localeRegion; + CoreWebView2Controller controller = null; + if (_creationOptions.entry == WebViewCreateEntry.CREATE_WITH_OPTION) + { + controller = await _webViewEnvironment.CreateCoreWebView2ControllerAsync(parentWindow, options); + } + else + { + controller = await _webViewEnvironment.CreateCoreWebView2ControllerAsync(parentWindow); + } + // update locale with value + SetAppLocale(localeRegion); +} +``` + +# API Details +```cpp +[uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] +interface ICoreWebView2ControllerOptions : IUnknown { + /// Interface for locale region that is updated through the ControllerOptions + /// API. + /// The default region for WebView. It applies to browser UI such as + /// in the time/date formats. The intended locale value is in the format of + /// `language[-country]` where `language` is the 2-letter code from [ISO + /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the + /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). + /// + /// Validation is done on the V8 engine to match on the closest locale + /// from the passed in locale region value. For example, passing in "en_gb" + /// will reflect the "en-GB" locale in V8. + /// If V8 cannot find any matching locale on the input value, it will default + /// to the display language as the locale. + /// + /// The caller must free the returned string with `CoTaskMemFree`. See + /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). + /// \snippet AppWindow.cpp RegionLocaleSetting + // MSOWNERS: stevenwei@microsoft.com + [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale); + + /// Sets the `Region` property. + // MSOWNERS: stevenwei@microsoft.com + [propput] HRESULT LocaleRegion([in] LPCWSTR locale); +} +``` + +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2ControllerOptions + { + // ... + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2ControllerOptions")] + { + + String LocaleRegion { get; set; }; + } + } +} \ No newline at end of file From e8814c1738d69b72f219f7f0b98918c557cf4612 Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 3 Nov 2022 14:24:40 -0700 Subject: [PATCH 2/9] adding the updated .idl documentation --- specs/LocaleRegion.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 30be14ddc..34cc37742 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -50,7 +50,7 @@ public CreateWebView2Controller(IntPtr parentWindow) # API Details ```cpp [uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] -interface ICoreWebView2ControllerOptions : IUnknown { +interface ICoreWebView2StagingControllerOptions : IUnknown { /// Interface for locale region that is updated through the ControllerOptions /// API. /// The default region for WebView. It applies to browser UI such as @@ -65,6 +65,21 @@ interface ICoreWebView2ControllerOptions : IUnknown { /// If V8 cannot find any matching locale on the input value, it will default /// to the display language as the locale. /// + /// The Windows API `GetLocaleInfoEx` can be used if the LocaleRegion value + /// is always set to match the OS region + /// + /// ```cpp + /// int LanguageCodeBufferSize = + /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, nullptr, 0); + /// std::unique_ptr buffer(new char[LanguageCodeBufferSize]); + /// WCHAR* w_language_code = new WCHAR[LanguageCodeBufferSize]; + /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, w_language_code, + /// LanguageCodeBufferSize); + /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); + /// delete[] w_language_code; + /// return buffer; + /// ``` + /// /// The caller must free the returned string with `CoTaskMemFree`. See /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). /// \snippet AppWindow.cpp RegionLocaleSetting From cdf93acbb0fa04edc7d1e11a6584fea57094695a Mon Sep 17 00:00:00 2001 From: Steven Date: Mon, 14 Nov 2022 13:06:37 -0800 Subject: [PATCH 3/9] addressed comments --- specs/LocaleRegion.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 34cc37742..1dface8a7 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -14,9 +14,6 @@ language. * The intended value for `LocaleRegion` is in the format of `language[-country]` where `language` is the 2-letter code from [ISO 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). -* By default, the `LocaleRegion` will be set as the value for the Limited option in the browser. -That means that if the OS region and the display language share the same language code, -like 'en-GB' and 'en-US', the value will be set to the OS region. # Examples ```cpp @@ -51,22 +48,36 @@ public CreateWebView2Controller(IntPtr parentWindow) ```cpp [uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] interface ICoreWebView2StagingControllerOptions : IUnknown { - /// Interface for locale region that is updated through the ControllerOptions - /// API. - /// The default region for WebView. It applies to browser UI such as + /// The default region for the WebView2. It applies to JavaScript API + /// Intl.DateTimeFormat() which affects string formatting like /// in the time/date formats. The intended locale value is in the format of /// `language[-country]` where `language` is the 2-letter code from [ISO /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). /// + /// This property will update the environment creation. This is global and immutable, + /// so changes will not be reflected in the existing webviews. They will need to closed + /// and reopened in order to see the changes reflected from using the new creation environment. + /// /// Validation is done on the V8 engine to match on the closest locale /// from the passed in locale region value. For example, passing in "en_gb" /// will reflect the "en-GB" locale in V8. /// If V8 cannot find any matching locale on the input value, it will default /// to the display language as the locale. /// - /// The Windows API `GetLocaleInfoEx` can be used if the LocaleRegion value - /// is always set to match the OS region + /// The default value for LocaleRegion will be depend on the WebView2 language + /// and OS region. If the language portions of the WebView2 language and OS Region + /// match, then it will use the OS region. Otherwise, it will use the WebView2 + /// language. + /// | **OS Region** | **WebView2 Language** | **Default WebView2 LocaleRegion** | + /// |-----------|-------------------|-------------------------------| + /// | en-GB | en-US | en-GB | + /// | es-MX | en-US | en-US | + /// | en-US | en-GB | en-US | + /// The default value can be reset using the empty string. + /// + /// Use OS specific APIs to determine the OS region to use with this property + /// if you want to match the OS. For example: /// /// ```cpp /// int LanguageCodeBufferSize = @@ -78,15 +89,19 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); /// delete[] w_language_code; /// return buffer; - /// ``` + /// ``` /// + /// ```c# + /// var geographicRegion = new Windows.Globalization.GeographicRegion(); + /// var regionCode = geographicRegion.CodeTwoLetter; + /// ``` /// The caller must free the returned string with `CoTaskMemFree`. See /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). /// \snippet AppWindow.cpp RegionLocaleSetting // MSOWNERS: stevenwei@microsoft.com [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale); - /// Sets the `Region` property. + /// Sets the `LocaleRegion` property. // MSOWNERS: stevenwei@microsoft.com [propput] HRESULT LocaleRegion([in] LPCWSTR locale); } From ac7843bfe9bc11671518e8eba70e17d1cc6b512c Mon Sep 17 00:00:00 2001 From: Steven Date: Mon, 14 Nov 2022 22:38:38 -0800 Subject: [PATCH 4/9] update idl comments --- specs/LocaleRegion.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 1dface8a7..3f1eeb62e 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -79,28 +79,29 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// Use OS specific APIs to determine the OS region to use with this property /// if you want to match the OS. For example: /// + /// Win32 C++: /// ```cpp - /// int LanguageCodeBufferSize = - /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, nullptr, 0); - /// std::unique_ptr buffer(new char[LanguageCodeBufferSize]); - /// WCHAR* w_language_code = new WCHAR[LanguageCodeBufferSize]; - /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, w_language_code, - /// LanguageCodeBufferSize); - /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); - /// delete[] w_language_code; - /// return buffer; - /// ``` + /// int LanguageCodeBufferSize = + /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, nullptr, 0); + /// std::unique_ptr buffer(new char[LanguageCodeBufferSize]); + /// WCHAR* w_language_code = new WCHAR[LanguageCodeBufferSize]; + /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, w_language_code, + /// LanguageCodeBufferSize); + /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); + /// delete[] w_language_code; + /// return buffer; + /// ``` /// - /// ```c# - /// var geographicRegion = new Windows.Globalization.GeographicRegion(); - /// var regionCode = geographicRegion.CodeTwoLetter; + /// .NET and WinRT C#: + /// ```cs + /// CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture; + /// return cultureInfo.Name /// ``` /// The caller must free the returned string with `CoTaskMemFree`. See /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). /// \snippet AppWindow.cpp RegionLocaleSetting // MSOWNERS: stevenwei@microsoft.com [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale); - /// Sets the `LocaleRegion` property. // MSOWNERS: stevenwei@microsoft.com [propput] HRESULT LocaleRegion([in] LPCWSTR locale); From bb757b379f632328d82080d64ca19d2d38252785 Mon Sep 17 00:00:00 2001 From: Steven Date: Tue, 29 Nov 2022 10:41:35 -0800 Subject: [PATCH 5/9] addressing comments --- specs/LocaleRegion.md | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 3f1eeb62e..4aced4511 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -24,23 +24,16 @@ options->put_LocaleRegion(m_webviewOption.localeRegion.c_str()); ``` ```c# -CoreWebView2Environment _webViewEnvironment; -WebViewCreationOptions _creationOptions; -public CreateWebView2Controller(IntPtr parentWindow) +CoreWebView2Environment environment; +CoreWebView2ControllerOptions CreateCoreWebView2ControllerOptions(CoreWebView2Environment environment) { - CoreWebView2ControllerOptions controllerOptions = new CoreWebView2ControllerOptions(); - controllerOptions.LocaleRegion = _creationOptions.localeRegion; - CoreWebView2Controller controller = null; - if (_creationOptions.entry == WebViewCreateEntry.CREATE_WITH_OPTION) + CoreWebView2ControllerOptions ControllerOptions = null; + if (LocaleRegion != null) { - controller = await _webViewEnvironment.CreateCoreWebView2ControllerAsync(parentWindow, options); + ControllerOptions = environment.CreateCoreWebView2ControllerOptions(); + ControllerOptions.LocaleRegion = LocaleRegion; } - else - { - controller = await _webViewEnvironment.CreateCoreWebView2ControllerAsync(parentWindow); - } - // update locale with value - SetAppLocale(localeRegion); + return ControllerOptions; } ``` @@ -55,14 +48,15 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). /// - /// This property will update the environment creation. This is global and immutable, - /// so changes will not be reflected in the existing webviews. They will need to closed - /// and reopened in order to see the changes reflected from using the new creation environment. + /// This property sets the region for a CoreWebView2Environment during its creation. + /// Creating a new CoreWebView2Environment object that connects to an already running + /// browser process cannot change the region previously set by an earlier CoreWebView2Environment. + /// The CoreWebView2Environment and all associated webview2 objects will need to closed. /// - /// Validation is done on the V8 engine to match on the closest locale - /// from the passed in locale region value. For example, passing in "en_gb" - /// will reflect the "en-GB" locale in V8. - /// If V8 cannot find any matching locale on the input value, it will default + /// Validation processing is done by ICU to match on the closest locale + /// from the passed in locale region value. ICU documentation can be found here + /// (https://source.chromium.org/chromium/chromium/src/+/main:third_party/icu/source/common/unicode/locid.h) + /// If ICU cannot find any matching locale on the input value, it will default /// to the display language as the locale. /// /// The default value for LocaleRegion will be depend on the WebView2 language From 3aec1fed5efa5fa8a8601fa33632e12d5514527e Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 1 Dec 2022 10:25:32 -0800 Subject: [PATCH 6/9] removing validation comments and adding - and _ to expected input --- specs/LocaleRegion.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 4aced4511..2d3e0e8a8 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -44,7 +44,7 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// The default region for the WebView2. It applies to JavaScript API /// Intl.DateTimeFormat() which affects string formatting like /// in the time/date formats. The intended locale value is in the format of - /// `language[-country]` where `language` is the 2-letter code from [ISO + /// `language-country` or `language_country` where `language` is the 2-letter code from [ISO /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). /// @@ -53,12 +53,6 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// browser process cannot change the region previously set by an earlier CoreWebView2Environment. /// The CoreWebView2Environment and all associated webview2 objects will need to closed. /// - /// Validation processing is done by ICU to match on the closest locale - /// from the passed in locale region value. ICU documentation can be found here - /// (https://source.chromium.org/chromium/chromium/src/+/main:third_party/icu/source/common/unicode/locid.h) - /// If ICU cannot find any matching locale on the input value, it will default - /// to the display language as the locale. - /// /// The default value for LocaleRegion will be depend on the WebView2 language /// and OS region. If the language portions of the WebView2 language and OS Region /// match, then it will use the OS region. Otherwise, it will use the WebView2 From 2a628072bf6cb6d1dce38cbcba9fd25409efdb5b Mon Sep 17 00:00:00 2001 From: Steven Date: Mon, 9 Jan 2023 15:33:03 -0800 Subject: [PATCH 7/9] adding ScriptLocale --- specs/ScriptLocale.md | 106 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 specs/ScriptLocale.md diff --git a/specs/ScriptLocale.md b/specs/ScriptLocale.md new file mode 100644 index 000000000..e9a02acaa --- /dev/null +++ b/specs/ScriptLocale.md @@ -0,0 +1,106 @@ +ScriptLocale +=== + +# Background +Developers have requested access to programmatically choose the specific locale/region to use in WebView2. +The locale/region updates the JavaScript region (objects in the ECMA standard) which gets reflected as +variations in time and date formats. Currently, the locale is by default set to the same value as the +display language. + +You can use the `ScriptLocale` API to update the locale value individually from the display +language. + +# Description +* The intended value for `SciptLocale` is in the format of BCP 47 Language Tags. +* More information can be found at [IETF BCP47](https://www.ietf.org/rfc/bcp/bcp47.html). +# Examples +```cpp +ControllerOptions CreateAndInitializeCoreWebView2ControllerAndOptions(std::string locale) +{ + auto webViewEnvironment10 = m_webViewEnvironment.try_query(); + if (webViewEnvironment10) { + wil::com_ptr options; + CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options)); + options->put_ScriptLocale(locale); + return options; + } +} +``` + +```c# +CoreWebView2Environment environment; +CoreWebView2ControllerOptions CreateAndInitializeCoreWebView2ControllerOptions(CoreWebView2Environment environment, string locale) +{ + CoreWebView2ControllerOptions controllerOptions = null; + controllerOptions = environment.CreateCoreWebView2ControllerOptions(); + controllerOptions.ScriptLocale = locale; + return controllerOptions; +} +``` + +# API Details +```cpp +[uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] +interface ICoreWebView2ControllerOptions : IUnknown { + /// The default locale for the WebView2. It sets the default locale for all Intl JavaScript APIs + /// and other JavaScript APIs that depend on it, namely + /// Intl.DateTimeFormat() which affects string formatting like + /// in the time/date formats. Example: `Intl.DateTimeFormat().format(new Date())` + /// The intended locale value is in the format of + /// BCP 47 Language Tags. More information can be found from + /// [IETF BCP47](https://www.ietf.org/rfc/bcp/bcp47.html). + /// + /// This property sets the locale for a CoreWebView2Environment during its creation. + /// Creating a new CoreWebView2Environment object that connects to an already running + /// browser process cannot change the locale previously set by an earlier CoreWebView2Environment. + /// The CoreWebView2Environment and all associated webview2 objects will need to closed. + /// + /// The default value for ScriptLocale will be depend on the WebView2 language + /// and OS region. If the language portions of the WebView2 language and OS region + /// match, then it will use the OS region. Otherwise, it will use the WebView2 + /// language. + /// | **OS Region** | **WebView2 Language** | **Default WebView2 ScriptLocale** | + /// |-----------|-------------------|-------------------------------| + /// | en-GB | en-US | en-GB | + /// | es-MX | en-US | en-US | + /// | en-US | en-GB | en-US | + /// You can set the ScriptLocale to the empty string to get the default ScriptLocale value. + /// + /// Use OS specific APIs to determine the OS region to use with this property + /// if you want to match the OS. For example: + /// + /// Win32 C++: + /// ```cpp + /// wchar_t osLocale[LOCALE_NAME_MAX_LENGTH] = {0}; + /// GetUserDefaultLocaleName(osLocale, LOCALE_NAME_MAX_LENGTH); + /// ``` + /// + /// .NET and WinRT C#: + /// ```cs + /// CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture; + /// return cultureInfo.Name + /// ``` + /// The caller must free the returned string with `CoTaskMemFree`. See + /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). + /// \snippet AppWindow.cpp ScriptLocaleSetting + // MSOWNERS: stevenwei@microsoft.com + [propget] HRESULT ScriptLocale([out, retval] LPWSTR* locale); + /// Sets the `ScriptLocale` property. + // MSOWNERS: stevenwei@microsoft.com + [propput] HRESULT ScriptLocale([in] LPCWSTR locale); +} +``` + +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2ControllerOptions + { + // ... + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2ControllerOptions")] + { + + String ScriptLocale { get; set; }; + } + } +} \ No newline at end of file From c9ba53b4e94deeeac84780c912dcb4432d315216 Mon Sep 17 00:00:00 2001 From: Steven Date: Mon, 9 Jan 2023 17:21:54 -0800 Subject: [PATCH 8/9] change name and address comments --- specs/LocaleRegion.md | 111 ------------------------------------------ specs/ScriptLocale.md | 13 +++-- 2 files changed, 6 insertions(+), 118 deletions(-) delete mode 100644 specs/LocaleRegion.md diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md deleted file mode 100644 index 2d3e0e8a8..000000000 --- a/specs/LocaleRegion.md +++ /dev/null @@ -1,111 +0,0 @@ -LocaleRegion -=== - -# Background -Developers have requested access to programmatically choose the specific locale/region to use in WebView2. -The locale/region updates the JavaScript region (objects in the ECMA standard) which gets reflected as -variations in time and date formats. Currently, the locale is by default set to the same value as the -display language. - -You can use the `LocaleRegion` API to update the locale value individually from the display -language. - -# Description -* The intended value for `LocaleRegion` is in the format of `language[-country]` where `language` is the -2-letter code from [ISO 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the -2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). - -# Examples -```cpp -auto webViewEnvironment10 = m_webViewEnvironment.try_query(); -wil::com_ptr options; -HRESULT hr = webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options); -options->put_LocaleRegion(m_webviewOption.localeRegion.c_str()); -``` - -```c# -CoreWebView2Environment environment; -CoreWebView2ControllerOptions CreateCoreWebView2ControllerOptions(CoreWebView2Environment environment) -{ - CoreWebView2ControllerOptions ControllerOptions = null; - if (LocaleRegion != null) - { - ControllerOptions = environment.CreateCoreWebView2ControllerOptions(); - ControllerOptions.LocaleRegion = LocaleRegion; - } - return ControllerOptions; -} -``` - -# API Details -```cpp -[uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] -interface ICoreWebView2StagingControllerOptions : IUnknown { - /// The default region for the WebView2. It applies to JavaScript API - /// Intl.DateTimeFormat() which affects string formatting like - /// in the time/date formats. The intended locale value is in the format of - /// `language-country` or `language_country` where `language` is the 2-letter code from [ISO - /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the - /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). - /// - /// This property sets the region for a CoreWebView2Environment during its creation. - /// Creating a new CoreWebView2Environment object that connects to an already running - /// browser process cannot change the region previously set by an earlier CoreWebView2Environment. - /// The CoreWebView2Environment and all associated webview2 objects will need to closed. - /// - /// The default value for LocaleRegion will be depend on the WebView2 language - /// and OS region. If the language portions of the WebView2 language and OS Region - /// match, then it will use the OS region. Otherwise, it will use the WebView2 - /// language. - /// | **OS Region** | **WebView2 Language** | **Default WebView2 LocaleRegion** | - /// |-----------|-------------------|-------------------------------| - /// | en-GB | en-US | en-GB | - /// | es-MX | en-US | en-US | - /// | en-US | en-GB | en-US | - /// The default value can be reset using the empty string. - /// - /// Use OS specific APIs to determine the OS region to use with this property - /// if you want to match the OS. For example: - /// - /// Win32 C++: - /// ```cpp - /// int LanguageCodeBufferSize = - /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, nullptr, 0); - /// std::unique_ptr buffer(new char[LanguageCodeBufferSize]); - /// WCHAR* w_language_code = new WCHAR[LanguageCodeBufferSize]; - /// ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, w_language_code, - /// LanguageCodeBufferSize); - /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); - /// delete[] w_language_code; - /// return buffer; - /// ``` - /// - /// .NET and WinRT C#: - /// ```cs - /// CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture; - /// return cultureInfo.Name - /// ``` - /// The caller must free the returned string with `CoTaskMemFree`. See - /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). - /// \snippet AppWindow.cpp RegionLocaleSetting - // MSOWNERS: stevenwei@microsoft.com - [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale); - /// Sets the `LocaleRegion` property. - // MSOWNERS: stevenwei@microsoft.com - [propput] HRESULT LocaleRegion([in] LPCWSTR locale); -} -``` - -```c# -namespace Microsoft.Web.WebView2.Core -{ - runtimeclass CoreWebView2ControllerOptions - { - // ... - [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2ControllerOptions")] - { - - String LocaleRegion { get; set; }; - } - } -} \ No newline at end of file diff --git a/specs/ScriptLocale.md b/specs/ScriptLocale.md index e9a02acaa..1e3a34afc 100644 --- a/specs/ScriptLocale.md +++ b/specs/ScriptLocale.md @@ -7,7 +7,7 @@ The locale/region updates the JavaScript region (objects in the ECMA standard) w variations in time and date formats. Currently, the locale is by default set to the same value as the display language. -You can use the `ScriptLocale` API to update the locale value individually from the display +You can use the `ScriptLocale` property to update the locale value individually from the display language. # Description @@ -18,12 +18,11 @@ language. ControllerOptions CreateAndInitializeCoreWebView2ControllerAndOptions(std::string locale) { auto webViewEnvironment10 = m_webViewEnvironment.try_query(); - if (webViewEnvironment10) { - wil::com_ptr options; - CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options)); - options->put_ScriptLocale(locale); - return options; - } + CHECK_FEATURE_RETURN(webViewEnvironment10); + wil::com_ptr options; + CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options)); + options->put_ScriptLocale(locale); + return options; } ``` From 856d76e10b1540a6310205c32f86bad192b4aff6 Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 1 Feb 2023 10:34:35 -0800 Subject: [PATCH 9/9] updates from Stable promotion --- specs/ScriptLocale.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/specs/ScriptLocale.md b/specs/ScriptLocale.md index 1e3a34afc..81fb7fcea 100644 --- a/specs/ScriptLocale.md +++ b/specs/ScriptLocale.md @@ -39,25 +39,30 @@ CoreWebView2ControllerOptions CreateAndInitializeCoreWebView2ControllerOptions(C # API Details ```cpp -[uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] -interface ICoreWebView2ControllerOptions : IUnknown { - /// The default locale for the WebView2. It sets the default locale for all Intl JavaScript APIs - /// and other JavaScript APIs that depend on it, namely - /// Intl.DateTimeFormat() which affects string formatting like +[uuid(06c991d8-9e7e-11ed-a8fc-0242ac120002), object, pointer_default(unique)] +interface ICoreWebView2ControllerOptions2 : ICoreWebView2ControllerOptions { + /// The default locale for the WebView2. It sets the default locale for all + /// Intl JavaScript APIs and other JavaScript APIs that depend on it, namely + /// `Intl.DateTimeFormat()` which affects string formatting like /// in the time/date formats. Example: `Intl.DateTimeFormat().format(new Date())` /// The intended locale value is in the format of - /// BCP 47 Language Tags. More information can be found from + /// BCP 47 Language Tags. More information can be found from /// [IETF BCP47](https://www.ietf.org/rfc/bcp/bcp47.html). /// - /// This property sets the locale for a CoreWebView2Environment during its creation. - /// Creating a new CoreWebView2Environment object that connects to an already running - /// browser process cannot change the locale previously set by an earlier CoreWebView2Environment. - /// The CoreWebView2Environment and all associated webview2 objects will need to closed. + /// This property sets the locale for a CoreWebView2Environment used to create the + /// WebView2ControllerOptions object, which is passed as a parameter in + /// `CreateCoreWebView2ControllerWithOptions`. /// - /// The default value for ScriptLocale will be depend on the WebView2 language + /// Changes to the ScriptLocale property apply to renderer processes created after + /// the change. Any existing renderer processes will continue to use the previous + /// ScriptLocale value. To ensure changes are applied to all renderer process, + /// close and restart the CoreWebView2Environment and all associated WebView2 objects. + /// + /// The default value for ScriptLocale will depend on the WebView2 language /// and OS region. If the language portions of the WebView2 language and OS region /// match, then it will use the OS region. Otherwise, it will use the WebView2 /// language. + /// /// | **OS Region** | **WebView2 Language** | **Default WebView2 ScriptLocale** | /// |-----------|-------------------|-------------------------------| /// | en-GB | en-US | en-GB | @@ -79,6 +84,7 @@ interface ICoreWebView2ControllerOptions : IUnknown { /// CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture; /// return cultureInfo.Name /// ``` + /// /// The caller must free the returned string with `CoTaskMemFree`. See /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). /// \snippet AppWindow.cpp ScriptLocaleSetting