Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/maui/behaviors/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,25 @@ The .NET MAUI Community Toolkit provides a collection of pre-built, reusable beh
| [`TouchBehavior`](touch-behavior.md) | The `TouchBehavior` is a `Behavior` that provides the ability to interact with any `VisualElement` based on touch, mouse click and hover events. |
| [`UriValidationBehavior`](uri-validation-behavior.md) | The `UriValidationBehavior` is a `Behavior` that allows users to determine whether or not text input is a valid URI. |
| [`UserStoppedTypingBehavior`](user-stopped-typing-behavior.md) | The `UserStoppedTypingBehavior` is a behavior that allows the user to trigger an action when a user has stopped data input an `Entry`. |

## Create a .NET MAUI Community Toolkit Behavior

The .NET MAUI Community Toolkit provides the `BaseBehavior<T>` class that performs some of the boiler plate requirements around managing a `Behavior` enabling developers to focus on the purpose of the implementation. A .NET MAUI Community Toolkit behavior can be implemented by creating a class that derives from the `BaseBehavior<T>` class, and optionally overriding the `OnAttachedTo`, `OnDetachingFrom` or `OnViewPropertyChanged` methods.

The following example shows the `NumericValidationBehavior` class, which highlights the value entered by the user into an `Entry` control in red if it's not a `double`:

```csharp
public class NumericValidationBehavior : Behavior<Entry>
{
void OnViewPropertyChanged(Entry sender, PropertyChangedEventArgs e)
{
if (e.PropertyName == nameof(Entry.Text))
{
bool isValid = double.TryParse(sender.Text, out double _);
sender.TextColor = isValid ? Colors.Black : Colors.Red;
}
}
}
```

In this example, the `NumericValidationBehavior` class derives from the `BaseBehavior<T>` class, where `T` is an `Entry`. The `OnAttachedTo` and `OnDetachingFrom` methods are handled within the base implementation so the only requirement is to override the `OnViewPropertyChanged`. The `OnViewPropertyChanged` method will be called whenever a property changes on the `View` property which is of `Entry`. This `OnViewPropertyChanged` provides the core functionality of the behavior, which parses the value entered in the `Entry` and sets the `TextColor` property to red if the value isn't a `double`.
56 changes: 56 additions & 0 deletions docs/maui/converters/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,59 @@ The .NET MAUI Community Toolkit provides a collection of pre-built, reusable con
| [`StringToListConverter`](string-to-list-converter.md) | The `StringToListConverter` is a one-way converter that returns a set of substrings by splitting the input string based on one or more separators. |
| [`TextCaseConverter`](text-case-converter.md) | The `TextCaseConverter` is a one-way converter that allows users to convert the casing of an incoming `string` type binding. The `Type` property is used to define what kind of casing will be applied to the string. |
| [`VariableMultiValueConverter`](variable-multi-value-converter.md) | The `VariableMultiValueConverter` is a converter that allows users to convert `bool` values via a `MultiBinding` to a single `bool`. |

## Create a .NET MAUI Community Toolkit Converter

The .NET MAUI Community Toolkit provides type safe implementations of the `IValueConverter` interface provided by .NET MAUI, this makes it easier for developers to write more concise, type safe converters. The toolkit provides the following options

### Two way converter

The `BaseConverter` class provides developers with the ability to define the incoming value type and also the outgoing value type for an `IValueConverter` implementation that supports a two-way binding. The following example shows how to create a converter that will convert a `bool` value to `Colors.Green` if `true` and `Colors.Red` if `false`.

```csharp
public class BoolToColorConverter : BaseConverter<bool, Color>
{
public override Color DefaultConvertReturnValue { get; set; } = Colors.Orange;

public override bool DefaultConvertBackReturnValue { get; set; } = false;

public override string ConvertFrom(bool value, CultureInfo? culture)
{
return value ? Colors.Green : Colors.Red;
}

public override int ConvertBackTo(Color value, CultureInfo? culture)
{
return value == Colors.Green;
}
}
```

The `DefaultConvertReturnValue` will be used by the base implementation and returned if an exception is thrown inside the `ConvertFrom` method.

The `DefaultConvertBackReturnValue` will be used by the base implementation and returned if an exception is thrown inside the `ConvertBackTo` method.

> [!WARNING]
> The converter will throw an `ArgumentException` if either the incoming or outgoing values are not of the expected type. The throwing of exceptions can be disabled by setting [CommunityToolkit.Maui.Options](../options.md)`.ShouldSuppressExceptionsInConverters` to `false`.

### One way converter

The `BaseConverterOneWay` class provides developers with the ability to define the incoming value type and also the outgoing value type for an `IValueConverter` implementation that supports a one-way binding. The following example shows how to create a converter that will convert a `bool` value to `Colors.Green` if `true` and `Colors.Red` if `false`.

```csharp
public class BoolToColorConverter : BaseConverterOneWay<bool, Color>
{
public override Color DefaultConvertReturnValue { get; set; } = Colors.Orange

public override string ConvertFrom(bool value, CultureInfo? culture)
{
return value ? Colors.Green : Colors.Red;
}
}
```

The `DefaultConvertReturnValue` will be used by the base implementation and returned if an exception is thrown inside the `ConvertFrom` method.

> [!WARNING]
> The converter will throw an `ArgumentException` if either the incoming or outgoing values are not of the expected type. The throwing of exceptions can be disabled by setting [CommunityToolkit.Maui.Options](../options.md)`.ShouldSuppressExceptionsInConverters` to `false`.
> The converter will throw a `NotSupportedException` if used in a two-way binding.