diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml index 412a1689..c361797b 100644 --- a/docs/maui/TOC.yml +++ b/docs/maui/TOC.yml @@ -233,7 +233,7 @@ items: href: views/Expander.md - name: "LazyView" href: views/LazyView.md - - name: "Map (Windows) (Deprecated)" + - name: "Map (Removed)" href: views/Map.md - name: "MediaElement" href: views/MediaElement.md diff --git a/docs/maui/behaviors/event-to-command-behavior.md b/docs/maui/behaviors/event-to-command-behavior.md index c6c9843e..554ddab2 100644 --- a/docs/maui/behaviors/event-to-command-behavior.md +++ b/docs/maui/behaviors/event-to-command-behavior.md @@ -2,7 +2,7 @@ title: EventToCommandBehavior - .NET MAUI Community Toolkit author: cliffagius description: "The EventToCommandBehavior is a behavior that allows the user to invoke a Command through an event. It is designed to associate Commands to events exposed by controls that were not designed to support Commands. It allows you to map any arbitrary event on a control to a Command." -ms.date: 04/23/2022 +ms.date: 11/10/2026 --- # EventToCommandBehavior @@ -121,6 +121,25 @@ When using this `behavior` with selection or tap events exposed by `ListView` an * [ItemTappedEventArgsConverter](../converters/item-tapped-eventargs-converter.md) * [SelectedItemEventArgsConverter](../converters/selected-item-eventargs-converter.md) +## Set the culture of the EventArgsConverter + +By default, the `EventToCommandBehavior` passes `CultureInfo.InvariantCulture` to the `EventArgsConverter`. A binding passes `CultureInfo.CurrentUICulture` instead, so this default differs from a binding. Set `EventArgsConverterCulture` to pass a different culture. + +The following example passes the `de-DE` culture to `MyTextChangedEventArgsConverter`. This converter is your own `IValueConverter`. The toolkit doesn't include it. + +```xaml + + + + + +``` + ## Properties |Property |Type |Description | @@ -129,6 +148,7 @@ When using this `behavior` with selection or tap events exposed by `ListView` an | Command | [ICommand](xref:System.Windows.Input.ICommand) | The `Command` that should be executed. | | CommandParameter | object | An optional parameter to forward to the `Command`. | | EventArgsConverter | IValueConverter | An optional `IValueConverter` that can be used to convert `EventArgs` values to values passed into the `Command`. | +| EventArgsConverterCulture | [CultureInfo](xref:System.Globalization.CultureInfo)? | The culture passed to the `EventArgsConverter`. The default is `null`, which means `CultureInfo.InvariantCulture`. | ## Examples diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index cea7ba1c..f27630c5 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -2,7 +2,7 @@ title: StatusBarBehavior - .NET MAUI Community Toolkit author: pictos description: "The StatusBarBehavior provides the ability to customize the color and style of a device's status bar." -ms.date: 11/07/2026 +ms.date: 11/10/2026 --- # StatusBarBehavior @@ -92,16 +92,11 @@ class MyPage : ContentPage No changes needed. -> [!IMPORTANT] -> Requires Android 6.0 (API 23) or later; on Android 5.0-5.1 (API 21-22) it does nothing. An app that supports those versions still runs on them, but its status bar keeps the default color and style there. -> -> In C#, an app whose minimum Android version is below 23 gets warning CA1416 for code that uses `StatusBarBehavior` or `StatusBar`, and a project that treats warnings as errors doesn't build. Raise the minimum Android version of the app to 23, or put that code inside `if (OperatingSystem.IsIOS() || OperatingSystem.IsAndroidVersionAtLeast(23))`. Don't check `OperatingSystem.IsAndroidVersionAtLeast(23)` alone in code that also runs on iOS: it's `false` on iOS, so the status bar wouldn't change there. XAML doesn't get the warning. - To apply the status bar color and style of the activity to modal pages as well, see [Dialog Fragment Service](../platform-specific/DialogFragment-customization.md). That page also describes how the content of a modal page extends behind the status bar, and how to keep it clear of the status bar. # [iOS](#tab/ios) -No changes needed. UIKit takes the style of the status bar from the view controllers of your app, and the toolkit makes them return the style that you set. This works as long as the _Platforms/iOS/Info.plist_ file doesn't turn view controller-based status bar appearance off. +No changes needed. UIKit takes the style of the status bar from the view controllers of your app, and the view controllers of .NET MAUI return the style of the window. This works as long as the _Platforms/iOS/Info.plist_ file doesn't turn view controller-based status bar appearance off. If your _Platforms/iOS/Info.plist_ file contains the following entry, which earlier versions of this page told you to add, remove it: @@ -111,9 +106,9 @@ If your _Platforms/iOS/Info.plist_ file contains the following entry, which earl ``` > [!IMPORTANT] -> In an app that is built with the iOS 27 SDK (Xcode 27) or later, UIKit ignores `UIApplication.SetStatusBarStyle`. With the key set to `false` the style of the status bar then doesn't change, and the toolkit writes the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false: remove the key from Info.plist_ to the trace output. An app that is built with an earlier SDK still applies the style while the key is `false`, but the key isn't needed there either. +> In an app that is built with the iOS 27 SDK (Xcode 27) or later, UIKit ignores `UIApplication.SetStatusBarStyle`. With the key set to `false` the style of the status bar then doesn't change, and the toolkit writes the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false: remove the key from Info.plist_ to the trace output. An app that is built with an earlier SDK, such as a .NET 10 app, still applies the style while the key is `false`, but the key isn't needed there either. -On .NET 10, the style belongs to the whole app: the status bar of every window shows it. The first `LightContent` or `DarkContent` that you set makes the view controllers that don't choose a style of their own return the one you set. `Default` gives every view controller its own style back. A view controller that overrides `preferredStatusBarStyle` keeps its own style, and so does `SFSafariViewController`. +The style belongs to a window: `StatusBarBehavior` sets the `Window.StatusBarTheme` of its page's window (`LightContent` sets `StatusBarTheme.Dark`, `DarkContent` sets `StatusBarTheme.Light`, `Default` sets `StatusBarTheme.Default`), and the view controllers of .NET MAUI return the matching style. The other windows keep their theme, and a style that changes while the behavior isn't attached to a page changes no status bar. `StatusBar.SetStyle` sets the theme of every window that is open at the time of the call; a window that opens later keeps its own. `StatusBar.SetStyle` needs `UseMauiCommunityToolkit()` in _MauiProgram.cs_. A view controller that isn't one of .NET MAUI's, such as a system view controller that your app presents, keeps its own style. Before .NET 11, the style belonged to the whole app. ----- @@ -129,7 +124,7 @@ On .NET 10, the style belongs to the whole app: the status bar of every window s ### Why doesn't the status bar style change on iOS? -Look for the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false_ in the trace output. If it's there, remove the `UIViewControllerBasedStatusBarAppearance` key from the _Platforms/iOS/Info.plist_ file, as described in [Configuration](#configuration). If it isn't, check whether a view controller that overrides `preferredStatusBarStyle` is on screen: it keeps its own style. +Look for the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false_ in the trace output. If it's there, remove the `UIViewControllerBasedStatusBarAppearance` key from the _Platforms/iOS/Info.plist_ file, as described in [Configuration](#configuration). If it isn't, check whether a view controller that isn't one of .NET MAUI's is on screen: it keeps its own style. The style also doesn't change when it was set on another window, or when it changed while the behavior wasn't attached to a page. ### Why is a pressed navigation bar button cut off at the status bar on iOS 26 and later? diff --git a/docs/maui/behaviors/text-validation-behavior.md b/docs/maui/behaviors/text-validation-behavior.md index 781dae3f..a26e2eae 100644 --- a/docs/maui/behaviors/text-validation-behavior.md +++ b/docs/maui/behaviors/text-validation-behavior.md @@ -2,7 +2,7 @@ title: TextValidationBehavior - .NET MAUI Community Toolkit author: bijington description: "The TextValidationBehavior is a Behavior that allows the user to validate a given text depending on specified parameters." -ms.date: 04/20/2022 +ms.date: 11/10/2026 --- # TextValidationBehavior @@ -134,6 +134,9 @@ The following screenshot shows the resulting TextValidationBehavior on Android: [!INCLUDE [common validation properties](../includes/validation-behavior.md)] +> [!TIP] +> `RegexOptions.IgnoreCase` follows the current culture. In Turkish, for example, `^[a-z]+$` doesn't match `TITLE`, because the capital `I` isn't the uppercase of `i`. For patterns that aren't linguistic, use `RegexOptions.IgnoreCase | RegexOptions.CultureInvariant`. + ## Examples You can find an example of this behavior in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Behaviors/TextValidationBehaviorPage.xaml). diff --git a/docs/maui/converters/color-to-cmyk-string-converter.md b/docs/maui/converters/color-to-cmyk-string-converter.md index 8c917f1c..25f089b3 100644 --- a/docs/maui/converters/color-to-cmyk-string-converter.md +++ b/docs/maui/converters/color-to-cmyk-string-converter.md @@ -2,7 +2,7 @@ title: ColorToCmykStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToCmykStringConverter is a one way converter that allows users to convert a Color value binding to its CMYK string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToCmykStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages with the binding's culture. For example, `de-DE` writes `100 %` with a space before the `%` sign, and `tr-TR` writes `%100`. + ## Syntax The following examples will show how to use the `ColorToCmykStringConverter` to display the CMYK equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-cmyka-string-converter.md b/docs/maui/converters/color-to-cmyka-string-converter.md index 633fa929..23a63800 100644 --- a/docs/maui/converters/color-to-cmyka-string-converter.md +++ b/docs/maui/converters/color-to-cmyka-string-converter.md @@ -2,7 +2,7 @@ title: ColorToCmykaStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToCmykaStringConverter is a one way converter that allows users to convert a Color value binding to its CMYKA string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToCmykaStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages and the alpha value with the binding's culture. For example, `de-DE` writes `100 %` with a space before the `%` sign, and `tr-TR` writes `%100`. The alpha value `0.5` is `0,5` in `de-DE`. + ## Syntax The following examples will show how to use the `ColorToCmykaStringConverter` to display the CMYKA equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-hsl-string-converter.md b/docs/maui/converters/color-to-hsl-string-converter.md index 30a01263..f56ee72a 100644 --- a/docs/maui/converters/color-to-hsl-string-converter.md +++ b/docs/maui/converters/color-to-hsl-string-converter.md @@ -2,12 +2,12 @@ title: ColorToHslStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToHslStringConverter is a one way converter that allows users to convert a Color value binding to its HSL string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToHslStringConverter -The `ColorToHslStringConverter` is a one way converter that allows users to convert a `Color` value binding to its HSL `string` equivalent in the format: **HSL(hue,saturation,lightness)** where **hue** will be a value between 0 and 360, and **saturation** and **lightness** will be a value between 0% and 100% (e.g. **HSL(0,100%,50%)** for `Colors.Red`. +The `ColorToHslStringConverter` is a one way converter that allows users to convert a `Color` value binding to its HSL `string` equivalent in the format: **HSL(hue,saturation,lightness)** where **hue** will be a value between 0 and 360, and **saturation** and **lightness** will be a value between 0% and 100% (e.g. **HSL(360,100%,50%)** for `Colors.Red`. The `Convert` method returns the supplied `Color` `value` converted to its HSL `string` equivalent. @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages with the binding's culture. For example, `de-DE` writes `100 %` with a space before the `%` sign, and `tr-TR` writes `%100`. + ## Syntax The following examples will show how to use the `ColorToHslStringConverter` to display the HSL equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-hsla-string-converter.md b/docs/maui/converters/color-to-hsla-string-converter.md index ea188edf..f5ad84e2 100644 --- a/docs/maui/converters/color-to-hsla-string-converter.md +++ b/docs/maui/converters/color-to-hsla-string-converter.md @@ -2,12 +2,12 @@ title: ColorToHslaStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToHslaStringConverter is a one way converter that allows users to convert a Color value binding to its HSLA string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToHslaStringConverter -The `ColorToHslaStringConverter` is a one way converter that allows users to convert a `Color` value binding to its HSLA `string` equivalent in the format: **HSLA(hue,saturation,lightness,alpha)** where **hue** will be a value between 0 and 360, **saturation** and **lightness** will be a value between 0% and 100%, and **alpha** will be a value between 0 and 1 (e.g. **HSLA(0,100%,50%,1)** for `Colors.Red`. +The `ColorToHslaStringConverter` is a one way converter that allows users to convert a `Color` value binding to its HSLA `string` equivalent in the format: **HSLA(hue,saturation,lightness,alpha)** where **hue** will be a value between 0 and 360, **saturation** and **lightness** will be a value between 0% and 100%, and **alpha** will be a value between 0 and 1 (e.g. **HSLA(360,100%,50%,1)** for `Colors.Red`. The `Convert` method returns the supplied `Color` `value` converted to its HSLA `string` equivalent. @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages and the alpha value with the binding's culture. For example, `de-DE` writes `100 %` with a space before the `%` sign, and `tr-TR` writes `%100`. The alpha value `0.5` is `0,5` in `de-DE`. + ## Syntax The following examples will show how to use the `ColorToHslaStringConverter` to display the HSLA equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-rgba-string-converter.md b/docs/maui/converters/color-to-rgba-string-converter.md index 35528442..9cb59abe 100644 --- a/docs/maui/converters/color-to-rgba-string-converter.md +++ b/docs/maui/converters/color-to-rgba-string-converter.md @@ -2,7 +2,7 @@ title: ColorToRgbaStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToRgbaStringConverter is a converter that allows users to convert a Color value binding to its RGBA string equivalent." -ms.date: 02/15/2024 +ms.date: 11/10/2026 --- # ColorToRgbaStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method returns the RGB `string` `value` converted to a `Color` [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the alpha value with the binding's culture. In a culture that uses a comma as the decimal separator, such as `de-DE`, the alpha value of 0.5 is written as `0,5`. When it converts back, the converter reads the string that it formats itself, using the same culture. + ## Syntax The following examples will show how to use the `ColorToRgbaStringConverter` to display the RGBA equivalent string of a specific `Color`. diff --git a/docs/maui/converters/compare-converter.md b/docs/maui/converters/compare-converter.md index 42f9fea7..6f2b538b 100644 --- a/docs/maui/converters/compare-converter.md +++ b/docs/maui/converters/compare-converter.md @@ -2,7 +2,7 @@ title: CompareConverter - .NET MAUI Community Toolkit author: bijington description: "The CompareConverter is a one way converter that takes an incoming value implementing IComparable, compares to a specified value, and returns the comparison result." -ms.date: 05/17/2022 +ms.date: 11/10/2026 --- # CompareConverter @@ -16,6 +16,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter compares `string` values with the collation of the binding's culture. It compares values of other types without regard to culture. + ## Syntax ### XAML diff --git a/docs/maui/converters/datetimeoffsetconverter.md b/docs/maui/converters/datetimeoffsetconverter.md index 7dfa5cce..57ed3ce4 100644 --- a/docs/maui/converters/datetimeoffsetconverter.md +++ b/docs/maui/converters/datetimeoffsetconverter.md @@ -2,7 +2,7 @@ title: DateTimeOffsetConverter - .NET MAUI Community Toolkit author: cliffagius description: "The DateTimeOffsetConverter is a converter that allows users to convert a DateTimeOffset to a DateTime " -ms.date: 03/22/2022 +ms.date: 11/10/2026 --- # DateTimeOffsetConverter @@ -11,6 +11,10 @@ The `DateTimeOffsetConverter` is a converter that allows users to convert a `Dat [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter doesn't use the culture, because the components of a `DateTime` are always Gregorian. Earlier versions applied the calendar of the culture when they converted a `DateTime` back to a `DateTimeOffset`. + ## Syntax ### XAML diff --git a/docs/maui/converters/double-to-int-converter.md b/docs/maui/converters/double-to-int-converter.md index aa677e3d..23d98a5a 100644 --- a/docs/maui/converters/double-to-int-converter.md +++ b/docs/maui/converters/double-to-int-converter.md @@ -2,7 +2,7 @@ title: DoubleToIntConverter - .NET MAUI Community Toolkit author: bijington description: "The DoubleToIntConverter is a converter that allows users to convert an incoming double value to an int and vice-versa." -ms.date: 03/09/2022 +ms.date: 11/10/2026 --- # DoubleToIntConverter @@ -22,6 +22,10 @@ The `ConvertBack` method returns the supplied `value` converted to a `double` an [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +When the `ConverterParameter` is a `string`, the converter parses it with the invariant culture first, so `2.5` in XAML means the same number for every user. If that fails, it parses the string with the binding's culture, so `2,5` works in `de-DE`. + ## Syntax ### XAML diff --git a/docs/maui/converters/enum-to-bool-converter.md b/docs/maui/converters/enum-to-bool-converter.md index 7d2b31e0..290e9f8b 100644 --- a/docs/maui/converters/enum-to-bool-converter.md +++ b/docs/maui/converters/enum-to-bool-converter.md @@ -2,7 +2,7 @@ title: EnumToBoolConverter - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The EnumToBoolConverter is a one way converter that allows you to convert an Enum to a corresponding bool based on whether it is equal to a set of supplied enum values." -ms.date: 05/04/2022 +ms.date: 11/10/2026 --- # EnumToBoolConverter @@ -34,7 +34,6 @@ public enum MyDevicePlatform Android, iOS, macOS, - Tizen, Windows } ``` @@ -91,8 +90,8 @@ It is also possible to pass the converter parameter: - ``` @@ -112,7 +111,7 @@ class EnumToBoolConverterPage : ContentPage var label = new Label { - Text = "I am visible when the Picker value is Tizen." + Text = "I am visible when the Picker value is Windows." }; label.SetBinding( @@ -120,7 +119,7 @@ class EnumToBoolConverterPage : ContentPage new Binding( static (ViewModel vm) => vm.SelectedPlatform, converter: new EnumToBoolConverter(), - converterParameter: MyDevicePlatform.Tizen)); + converterParameter: MyDevicePlatform.Windows)); Content = new VerticalStackLayout { @@ -154,12 +153,12 @@ class EnumToBoolConverterPage : ContentPage static (ViewModel vm) => vm.SelectedPlatform), new Label() - .Text("I am visible when the Picker value is Tizen.") + .Text("I am visible when the Picker value is Windows.") .Bind( Label.IsVisibleProperty, static (ViewModel vm) => vm.SelectedPlatform, converter: new EnumToBoolConverter(), - converterParameter: MyDevicePlatform.Tizen) + converterParameter: MyDevicePlatform.Windows) } }; } diff --git a/docs/maui/converters/index.md b/docs/maui/converters/index.md index 4954c948..b9dc0da9 100644 --- a/docs/maui/converters/index.md +++ b/docs/maui/converters/index.md @@ -2,7 +2,7 @@ title: Converters - .NET MAUI Community Toolkit author: bijington description: The .NET MAUI Community Toolkit provides a collection of pre-built, reusable converters to make developers lives easier. -ms.date: 02/15/2024 +ms.date: 11/10/2026 --- # .NET MAUI Converters @@ -11,6 +11,18 @@ ms.date: 02/15/2024 For further information on Converters please refer to the [.NET MAUI documentation](/dotnet/maui/fundamentals/data-binding/converters). +## Converter culture + +A binding passes a culture to its converter. The culture is the `ConverterCulture` of the binding, or `CultureInfo.CurrentUICulture` when `ConverterCulture` isn't set. In .NET MAUI 11, `Binding` and `MultiBinding` both have a `ConverterCulture` property. + +The following example passes the `de-DE` culture to a converter: + +```xaml +