From 3d650ce0e420de1ab8216bb46c74db450e6fc25c Mon Sep 17 00:00:00 2001
From: Steven <stevenwei@microsoft.com>
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<ICoreWebView2Environment10>();
+wil::com_ptr<ICoreWebView2ControllerOptions> 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 <stevenwei@microsoft.com>
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<char[]> 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 <stevenwei@microsoft.com>
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 <stevenwei@microsoft.com>
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<char[]> 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<char[]> 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 <stevenwei@microsoft.com>
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 <stevenwei@microsoft.com>
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 <stevenwei@microsoft.com>
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<ICoreWebView2Environment10>();
+ if (webViewEnvironment10) {
+ wil::com_ptr<ICoreWebView2ControllerOptions> 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 <stevenwei@microsoft.com>
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<ICoreWebView2Environment10>();
-wil::com_ptr<ICoreWebView2ControllerOptions> 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<char[]> 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<ICoreWebView2Environment10>();
- if (webViewEnvironment10) {
- wil::com_ptr<ICoreWebView2ControllerOptions> options;
- CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options));
- options->put_ScriptLocale(locale);
- return options;
- }
+ CHECK_FEATURE_RETURN(webViewEnvironment10);
+ wil::com_ptr<ICoreWebView2ControllerOptions> options;
+ CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options));
+ options->put_ScriptLocale(locale);
+ return options;
}
```
From 856d76e10b1540a6310205c32f86bad192b4aff6 Mon Sep 17 00:00:00 2001
From: Steven <stevenwei@microsoft.com>
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