Training
Module
Create a UI in a .NET MAUI app by using XAML - Training
Learn how to design a UI for a .NET MAUI app using XAML.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
The TouchBehavior
is a Behavior
that provides the ability to interact with any VisualElement
based on touch, mouse click and hover events. The TouchBehavior
implementation makes it possible to customize many different visual properties of the VisualElement
that it is attached to such as the BackgroundColor
, Opacity
, Rotation
and Scale
, as well as many other properties.
Note
The toolkit also provides the ImageTouchBehavior
implementation that extends this TouchBehavior
by also providing the ability to customize the Source
of an Image
element.
Important
The .NET MAUI Community Toolkit Behaviors do not set the BindingContext
of a behavior, because behaviors can be shared and applied to multiple controls through styles. For more information refer to .NET MAUI Behaviors
The following examples show how to add the TouchBehavior
to a parent HorizontalStackLayout
and perform the following animations when a user touches or clicks on the HorizontalStackLayout
or any of its children:
CubicInOut
Easing
Opacity
to 0.6Scale
to 0.8In order to use the toolkit in XAML the following xmlns
needs to be added into your page or view:
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
Therefore the following:
<ContentPage
x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">
</ContentPage>
Would be modified to include the xmlns
as follows:
<ContentPage
x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">
</ContentPage>
<ContentPage
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
x:Class="CommunityToolkit.Maui.Sample.Pages.Behaviors.TouchBehaviorPage">
<HorizontalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
<HorizontalStackLayout.Behaviors>
<toolkit:TouchBehavior
DefaultAnimationDuration="250"
DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
PressedOpacity="0.6"
PressedScale="0.8" />
</HorizontalStackLayout.Behaviors>
<ContentView
HeightRequest="100"
WidthRequest="10"
BackgroundColor="Gold" />
<Label Text="The entire layout receives touches" VerticalOptions="Center" LineBreakMode="TailTruncation"/>
<ContentView
HeightRequest="100"
WidthRequest="10"
BackgroundColor="Gold" />
</HorizontalStackLayout>
</ContentPage>
The TouchBehavior
can be used as follows in C#:
class TouchBehaviorPage : ContentPage
{
public TouchBehaviorPage()
{
var firstContent = new ContentView
{
HeightRequest = 100,
WidthRequest = 10,
BackgroundColor = Colors.Gold
};
var label = new Label
{
Text = "The entire layout receives touches",
VerticalOptions = LayoutOptions.Center,
LineBreakMode = LineBreakMode.TailTruncation
};
var secondContent = new ContentView
{
HeightRequest = 100,
WidthRequest = 10,
BackgroundColor = Colors.Gold
};
var layout = new HorizontalStackLayout
{
HorizontalOptions = LayoutOptions.Center,
VerticalOptions = LayoutOptions.Center,
Children =
{
firstContent,
label,
secondContent
}
}
var touchBehavior = new TouchBehavior
{
DefaultAnimationDuration = 250,
DefaultAnimationEasing = Easing.CubicInOut,
PressedOpacity = 0.6,
PressedScale = 0.8
};
layout.Behaviors.Add(touchBehavior);
Content = layout;
}
}
Our CommunityToolkit.Maui.Markup
package provides a much more concise way to use this Behavior
in C#.
using CommunityToolkit.Maui.Markup;
class TouchBehaviorPage : ContentPage
{
public TouchBehaviorPage()
{
Content = new HorizontalStackLayout
{
HorizontalOptions = LayoutOptions.Center,
VerticalOptions = LayoutOptions.Center,
Children =
{
new ContentView()
.Size(10, 100)
.BackgroundColor(Colors.Gold),
new Label
{
LineBreakMode = LineBreakMode.TailTruncation
}
.Text("The entire layout receives touches"
.CenterVertical(),
new ContentView()
.Size(10, 100)
.BackgroundColor(Colors.Gold)
}
}
.Behaviors(new TouchBehavior
{
DefaultAnimationDuration = 250,
DefaultAnimationEasing = Easing.CubicInOut,
PressedOpacity = 0.6,
PressedScale = 0.8
});
}
}
The TouchBehavior
provides the ability to customize the properties of the attached VisualElement
based on whether the mouse it hovering over the element.
The following example shows how to attach the TouchBehavior
to a HorizontalStackLayout
and change the BackgroundColor
and Scale
of the HorizontalStackLayout
when a user hovers their mouse cursor over the layout and any child elements.
<HorizontalStackLayout
Padding="20"
Background="Black"
HorizontalOptions="Center">
<HorizontalStackLayout.Behaviors>
<toolkit:TouchBehavior
HoveredBackgroundColor="{StaticResource Gray900}"
HoveredScale="1.2" />
</HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>
The TouchBehavior
provides the ability to handle the scenario when a user presses for a long period of time. This period of time can be defined by the LongPressDuration
which is in units of milliseconds.
The following example shows how to add the TouchBehavior
to a HorizontalStackLayout
, bind the LongPressCommand
to the IncreaseLongPressCountCommand
defined in the backing view model and set the LongPressDuration
to 750 milliseconds.
<HorizontalStackLayout
Padding="20"
Background="Black"
HorizontalOptions="Center">
<HorizontalStackLayout.Behaviors>
<toolkit:TouchBehavior
LongPressDuration="750"
LongPressCommand="{Binding Source={x:Reference Page}, Path=BindingContext.IncreaseLongPressCountCommand}"/>
</HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>
Property | Type | Description |
---|---|---|
Command | ICommand |
Gets or sets the ICommand to invoke when the user has completed a touch gesture. |
CommandParameter | object |
Gets or sets the parameter to pass to the Command property. |
CurrentHoverState | HoverState |
Gets or sets the current HoverState of the behavior. |
CurrentHoverStatus | HoverStatus |
Gets or sets the current HoverStatus of the behavior. |
CurrentInteractionStatus | TouchInteractionStatus |
Gets or sets the current TouchInteractionStatus of the behavior. |
CurrentTouchState | TouchState |
Gets or sets the current TouchState of the behavior. |
CurrentTouchStatus | TouchStatus |
Gets or sets the current TouchStatus of the behavior. |
DefaultAnimationDuration | int |
Gets or sets the duration of the animation when the CurrentTouchState property is TouchState.Default . |
DefaultAnimationEasing | Easing |
Gets or sets the easing of the animation when the CurrentTouchState property is TouchState.Default . |
DefaultBackgroundColor | Color |
Gets or sets the background color of the element when the CurrentTouchState property is TouchState.Default . |
DefaultOpacity | double |
Gets or sets the opacity of the element when the CurrentTouchState property is TouchState.Default . |
DefaultRotation | double |
Gets or sets the rotation around both the X and Y axes of the element when the CurrentTouchState property is TouchState.Default . |
DefaultRotationX | double |
Gets or sets the rotation around the X axis of the element when the CurrentTouchState property is TouchState.Default . |
DefaultRotationY | double |
Gets or sets the rotation around the Y axis of the element when the CurrentTouchState property is TouchState.Default . |
DefaultScale | double |
Gets or sets the scale of the element when the CurrentTouchState property is TouchState.Default . |
DefaultTranslationX | double |
Gets or sets the X translation of the element when the CurrentTouchState property is TouchState.Default . |
DefaultTranslationY | double |
Gets or sets the Y translation of the element when the CurrentTouchState property is TouchState.Default . |
DisallowTouchThreshold | int |
Gets or sets the threshold for disallowing touch. |
HoveredAnimationDuration | int |
Gets or sets the duration of the animation when the CurrentHoverState property is HoverState.Hovered . |
HoveredAnimationEasing | Easing |
Gets or sets the easing of the animation when the CurrentHoverState property is HoverState.Hovered . |
HoveredBackgroundColor | Color |
Gets or sets the background color of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredOpacity | double |
Gets or sets the opacity of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredRotation | double |
Gets or sets the rotation around both the X and Y axes of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredRotationX | double |
Gets or sets the rotation around the X axis of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredRotationY | double |
Gets or sets the rotation around the Y axis of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredScale | double |
Gets or sets the scale of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredTranslationX | double |
Gets or sets the X translation of the element when the CurrentHoverState property is HoverState.Hovered . |
HoveredTranslationY | double |
Gets or sets the Y translation of the element when the CurrentHoverState property is HoverState.Hovered . |
IsEnabled | bool |
Gets or sets a value indicating whether the behavior is enabled. |
LongPressCommand | ICommand |
Gets or sets the ICommand to invoke when the user has completed a long press. |
LongPressCommandParameter | object |
Gets or sets the parameter to pass to the LongPressCommand property. |
LongPressDuration | int |
Gets or sets the duration in milliseconds required to trigger the long press gesture. |
PressedAnimationDuration | int |
Gets or sets the duration of the animation when the CurrentTouchState property is TouchState.Pressed . |
PressedAnimationEasing | Easing |
Gets or sets the easing of the animation when the CurrentTouchState property is TouchState.Pressed . |
PressedBackgroundColor | Color |
Gets or sets the background color of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedOpacity | double |
Gets or sets the opacity of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedRotation | double |
Gets or sets the rotation around both the X and Y axes of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedRotationX | double |
Gets or sets the rotation around the X axis of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedRotationY | double |
Gets or sets the rotation around the Y axis of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedScale | double |
Gets or sets the scale of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedTranslationX | double |
Gets or sets the X translation of the element when the CurrentTouchState property is TouchState.Pressed . |
PressedTranslationY | double |
Gets or sets the Y translation of the element when the CurrentTouchState property is TouchState.Pressed . |
ShouldMakeChildrenInputTransparent | bool |
Gets or sets a value indicating whether the children of the element should be made input transparent. |
Event | Description |
---|---|
CurrentTouchStateChanged |
Fires when CurrentTouchState changes. |
CurrentTouchStatusChanged |
Fires when CurrentTouchStatus changes. |
HoverStateChanged |
Fires when CurrentHoverState changes. |
HoverStatusChanged |
Fires when CurrentHoverStatus changes. |
InteractionStatusChanged |
Fires when CurrentInteractionStatus changes. |
LongPressCompleted |
Fires when a long press gesture has completed. |
TouchGestureCompleted |
Fires when a touch gesture has completed. |
You can find an example of this behavior in action in the .NET MAUI Community Toolkit Sample Application.
You can find the source code for TouchBehavior
over on the .NET MAUI Community Toolkit GitHub repository.
In the Xamarin Community Toolkit, there was the TouchEffect
if you are upgrading an app from Xamarin.Forms to .NET MAUI there are some breaking changes that you should be aware of:
Name In Xamarin Community Toolkit | Name In MAUI Community Toolkit |
---|---|
TouchEffect | TouchBehavior |
NormalBackgroundColor | DefaultBackgroundColor |
NormalScale | DefaultScale |
NormalOpacity | DefaultOpacity |
NormalTranslationX | DefaultTranslationX |
NormalTranslationY | DefaultTranslationY |
NormalRotation | DefaultRotation |
NormalRotationX | DefaultRotationX |
NormalRotationY | DefaultRotationY |
NormalAnimationDuration | DefaultAnimationDuration |
NormalAnimationEasing | DefaultAnimationEasing |
NormalBackgroundImageSource | DefaultImageSource (Moved to ImageTouchBehavior ) |
NormalBackgroundImageAspect | DefaultImageAspect (Moved to ImageTouchBehavior ) |
In the Xamarin Community Toolkit the TouchEffect
was implemented as an AttachedEffect
. To use the effect you would use the attached properties and apply to any VisualElement
In .NET MAUI the TouchBehavior
is implemented as a PlatformBehavior
which is now applied to the elements behavior collection, see Platform Behaviors for more information.
Note: By default in .NET MAUI
PlatformBehavior
s will not set theBindingContext
property, this is because Behaviors can be shared in styles. TheTouchBehavior
will set theBindingContext
property equal to theVisualElement
it is applied to. This means that you should not share theTouchBehavior
between elements via styles.
Below is an example of a TouchEffect
being applied to a view in Xamarin.Forms:
<StackLayout Orientation="Horizontal"
HorizontalOptions="CenterAndExpand"
xct:TouchEffect.AnimationDuration="250"
xct:TouchEffect.AnimationEasing="{x:Static Easing.CubicInOut}"
xct:TouchEffect.PressedScale="0.8"
xct:TouchEffect.PressedOpacity="0.6"
xct:TouchEffect.Command="{Binding Command}">
<BoxView Color="Gold" />
<Label Text="The entire layout receives touches" />
<BoxView Color="Gold"/>
</StackLayout>
The equivalent TouchBehavior
in .NET MAUI would look like this:
<HorizontalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
<HorizontalStackLayout.Behaviors>
<toolkit:TouchBehavior
DefaultAnimationDuration="250"
DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
PressedOpacity="0.6"
PressedScale="0.8"
Command="{Binding Command}" />
</HorizontalStackLayout.Behaviors>
<ContentView
BackgroundColor="Gold"
HeightRequest="100"
WidthRequest="10" />
<Label
LineBreakMode="TailTruncation"
Text="The entire layout receives touches"
VerticalOptions="Center" />
<ContentView
BackgroundColor="Gold"
HeightRequest="100"
WidthRequest="10" />
</HorizontalStackLayout>
.NET MAUI Community Toolkit feedback
.NET MAUI Community Toolkit is an open source project. Select a link to provide feedback:
Training
Module
Create a UI in a .NET MAUI app by using XAML - Training
Learn how to design a UI for a .NET MAUI app using XAML.