marketally/toucheffect.maui
2
0
Fork 0
Code Issues Packages Releases Wiki
Files
2b003b7970c9466121f4184dd01609f530d04f65
toucheffect.maui/API_Reference.md

26 KiB
Raw Blame History

MarketAlly.TouchEffect.Maui API Reference

Complete API documentation for MarketAlly.TouchEffect.Maui v2.0.0.

Table of Contents

TouchEffect Class

The core class that provides touch and hover visual feedback for any VisualElement.

Namespace: MarketAlly.TouchEffect.Maui

Inheritance: RoutingEffect

Attached Properties

State Properties

Property Type Default Description
IsAvailable bool true Enables or disables the touch effect. When false, no touch feedback occurs.
ShouldMakeChildrenInputTransparent bool true When true, child elements become input-transparent to allow touch to pass through.
Status TouchStatus Completed Read-only. Current touch status (Started, Completed, Canceled).
State TouchState Normal Read-only. Current touch state (Normal, Pressed).
InteractionStatus TouchInteractionStatus Completed Read-only. Current interaction status.
HoverStatus HoverStatus Exited Read-only. Current hover status (Entered, Exited).
HoverState HoverState Normal Read-only. Current hover state (Normal, Hovered).

Usage:

<Frame touch:TouchEffect.IsAvailable="{Binding CanInteract}"
       touch:TouchEffect.ShouldMakeChildrenInputTransparent="True">
    <Label Text="Interactive Content" />
</Frame>

Command Properties

Property Type Default Description
Command ICommand null Command executed when touch completes successfully.
CommandParameter object null Parameter passed to the Command.
LongPressCommand ICommand null Command executed after long press duration elapses.
LongPressCommandParameter object null Parameter for the LongPressCommand. Falls back to CommandParameter if null.
LongPressDuration int 500 Duration in milliseconds before LongPressCommand executes.

Usage:

<Frame touch:TouchEffect.Command="{Binding TapCommand}"
       touch:TouchEffect.CommandParameter="{Binding Item}"
       touch:TouchEffect.LongPressCommand="{Binding ContextMenuCommand}"
       touch:TouchEffect.LongPressDuration="800">
    <Label Text="Tap or Long Press" />
</Frame>

Background Color Properties

Property Type Default Description
NormalBackgroundColor Color Default Background color in normal state.
HoveredBackgroundColor Color Default Background color when hovered (desktop platforms).
PressedBackgroundColor Color Default Background color when pressed.

Usage:

<Frame touch:TouchEffect.NormalBackgroundColor="White"
       touch:TouchEffect.HoveredBackgroundColor="LightGray"
       touch:TouchEffect.PressedBackgroundColor="Gray">
    <Label Text="Color Feedback" />
</Frame>

Opacity Properties

Property Type Default Description
NormalOpacity double 1.0 Opacity in normal state.
HoveredOpacity double 1.0 Opacity when hovered.
PressedOpacity double 1.0 Opacity when pressed.

Usage:

<Frame touch:TouchEffect.NormalOpacity="1.0"
       touch:TouchEffect.HoveredOpacity="0.9"
       touch:TouchEffect.PressedOpacity="0.7">
    <Label Text="Opacity Feedback" />
</Frame>

Scale Properties

Property Type Default Description
NormalScale double 1.0 Scale in normal state.
HoveredScale double 1.0 Scale when hovered.
PressedScale double 1.0 Scale when pressed.

Usage:

<Frame touch:TouchEffect.NormalScale="1.0"
       touch:TouchEffect.HoveredScale="1.02"
       touch:TouchEffect.PressedScale="0.95">
    <Label Text="Scale Feedback" />
</Frame>

Translation Properties

Property Type Default Description
NormalTranslationX double 0.0 X translation in normal state.
HoveredTranslationX double 0.0 X translation when hovered.
PressedTranslationX double 0.0 X translation when pressed.
NormalTranslationY double 0.0 Y translation in normal state.
HoveredTranslationY double 0.0 Y translation when hovered.
PressedTranslationY double 0.0 Y translation when pressed.

Usage:

<Frame touch:TouchEffect.PressedTranslationY="2">
    <Label Text="Moves down when pressed" />
</Frame>

Rotation Properties

Property Type Default Description
NormalRotation double 0.0 Z-axis rotation in normal state (degrees).
HoveredRotation double 0.0 Z-axis rotation when hovered.
PressedRotation double 0.0 Z-axis rotation when pressed.
NormalRotationX double 0.0 X-axis rotation in normal state.
HoveredRotationX double 0.0 X-axis rotation when hovered.
PressedRotationX double 0.0 X-axis rotation when pressed.
NormalRotationY double 0.0 Y-axis rotation in normal state.
HoveredRotationY double 0.0 Y-axis rotation when hovered.
PressedRotationY double 0.0 Y-axis rotation when pressed.

Usage:

<Frame touch:TouchEffect.PressedRotation="5">
    <Label Text="Tilts when pressed" />
</Frame>

Animation Properties

Property Type Default Description
AnimationDuration int 0 Default animation duration in milliseconds.
AnimationEasing Easing null Default easing function for animations.
PressedAnimationDuration int 0 Animation duration for pressed state transitions.
PressedAnimationEasing Easing null Easing for pressed state transitions.
NormalAnimationDuration int 0 Animation duration for returning to normal state.
NormalAnimationEasing Easing null Easing for normal state transitions.
HoveredAnimationDuration int 0 Animation duration for hover state transitions.
HoveredAnimationEasing Easing null Easing for hover state transitions.
PulseCount int 0 Number of pulse repetitions. Use -1 for infinite.

Usage:

<Frame touch:TouchEffect.AnimationDuration="150"
       touch:TouchEffect.AnimationEasing="{x:Static Easing.CubicOut}"
       touch:TouchEffect.PressedScale="0.95">
    <Label Text="Animated Feedback" />
</Frame>

Toggle Properties

Property Type Default Description
IsToggled bool? null Toggle state. null disables toggle behavior. Supports two-way binding.
DisallowTouchThreshold int 0 Movement threshold in pixels before touch is canceled.

Usage:

<Frame touch:TouchEffect.IsToggled="{Binding IsSelected, Mode=TwoWay}"
       touch:TouchEffect.PressedBackgroundColor="Blue"
       touch:TouchEffect.NormalBackgroundColor="Gray">
    <Label Text="Toggle Button" />
</Frame>

Native Animation Properties

Property Type Default Description
NativeAnimation bool false Enables platform-specific animations (Android ripple, iOS highlight).
NativeAnimationColor Color Default Color for native animation effects.
NativeAnimationRadius int -1 Radius for native ripple effect. -1 uses default.
NativeAnimationShadowRadius int -1 Shadow radius for native effects.
NativeAnimationBorderless bool false When true, ripple extends beyond view bounds.

Usage:

<Frame touch:TouchEffect.NativeAnimation="True"
       touch:TouchEffect.NativeAnimationColor="Blue"
       touch:TouchEffect.NativeAnimationRadius="100">
    <Label Text="Native Ripple Effect" />
</Frame>

Background Image Properties

Property Type Default Description
NormalBackgroundImageSource ImageSource null Background image in normal state.
HoveredBackgroundImageSource ImageSource null Background image when hovered.
PressedBackgroundImageSource ImageSource null Background image when pressed.
BackgroundImageAspect Aspect AspectFill Default aspect ratio for background images.
NormalBackgroundImageAspect Aspect AspectFill Aspect ratio for normal state image.
HoveredBackgroundImageAspect Aspect AspectFill Aspect ratio for hovered state image.
PressedBackgroundImageAspect Aspect AspectFill Aspect ratio for pressed state image.
ShouldSetImageOnAnimationEnd bool false When true, image changes occur after animation completes.

Events

Event EventArgs Description
StatusChanged TouchStatusChangedEventArgs Fired when touch status changes.
StateChanged TouchStateChangedEventArgs Fired when touch state changes.
InteractionStatusChanged TouchInteractionStatusChangedEventArgs Fired when interaction status changes.
HoverStatusChanged HoverStatusChangedEventArgs Fired when hover status changes.
HoverStateChanged HoverStateChangedEventArgs Fired when hover state changes.
Completed TouchCompletedEventArgs Fired when touch completes successfully.
LongPressCompleted LongPressCompletedEventArgs Fired when long press completes.

Usage in Code-Behind:

public partial class MyPage : ContentPage
{
    protected override void OnAppearing()
    {
        base.OnAppearing();

        // Get the effect instance
        var effect = MyView.Effects.OfType<TouchEffect>().FirstOrDefault();
        if (effect != null)
        {
            effect.Completed += OnTouchCompleted;
            effect.StateChanged += OnStateChanged;
        }
    }

    private void OnTouchCompleted(object sender, TouchCompletedEventArgs e)
    {
        Debug.WriteLine($"Touch completed with parameter: {e.Parameter}");
    }

    private void OnStateChanged(object sender, TouchStateChangedEventArgs e)
    {
        Debug.WriteLine($"State changed to: {e.State}");
    }
}

Static Methods

SetLogger

public static void SetLogger(ITouchEffectLogger? logger)

Sets the logger instance for all TouchEffect operations.

Parameters:

  • logger: The logger implementation. Pass null to disable logging.

Usage:

// Enable default console logging
TouchEffect.SetLogger(new DefaultTouchEffectLogger());

// Disable logging
TouchEffect.SetLogger(null);

// Custom logging
TouchEffect.SetLogger(new MyCustomLogger());

TouchBehavior Class

NEW in v2.0.0

A Behavior-based alternative to TouchEffect for attaching touch feedback to elements. MAUI is moving toward Behaviors over Effects, making this the preferred modern API.

Namespace: MarketAlly.TouchEffect.Maui

Inheritance: Behavior<VisualElement>

Properties

Property Type Default Description
Command ICommand null Command executed on tap.
CommandParameter object null Parameter for the command.
LongPressCommand ICommand null Command for long press.
LongPressCommandParameter object null Parameter for long press command.
LongPressDuration int 500 Long press duration in ms.
PressedScale double 1.0 Scale when pressed.
PressedOpacity double 1.0 Opacity when pressed.
PressedBackgroundColor Color null Background color when pressed.
HoveredScale double 1.0 Scale when hovered.
HoveredOpacity double 1.0 Opacity when hovered.
HoveredBackgroundColor Color null Background color when hovered.
NormalScale double 1.0 Scale in normal state.
NormalOpacity double 1.0 Opacity in normal state.
NormalBackgroundColor Color null Background color in normal state.
AnimationDuration int 100 Animation duration in ms.
AnimationEasing Easing null Animation easing function.
NativeAnimation bool false Enable native platform animations.
NativeAnimationColor Color null Color for native animations.
IsToggled bool? null Toggle state (two-way bindable).
IsAvailable bool true Enable/disable the behavior.

Usage

XAML:

<Button Text="Click Me">
    <Button.Behaviors>
        <touch:TouchBehavior
            PressedScale="0.95"
            PressedOpacity="0.8"
            AnimationDuration="100"
            AnimationEasing="{x:Static Easing.CubicOut}"
            Command="{Binding TapCommand}" />
    </Button.Behaviors>
</Button>

C#:

var button = new Button { Text = "Click Me" };
button.Behaviors.Add(new TouchBehavior
{
    PressedScale = 0.95,
    PressedOpacity = 0.8,
    AnimationDuration = 100,
    Command = viewModel.TapCommand
});

TouchEffectBuilder Class

Fluent builder for configuring TouchEffect with a clean, chainable API.

Namespace: MarketAlly.TouchEffect.Maui

Static Methods

For

public static TouchEffectBuilder For(VisualElement element)

Creates a builder for the specified element.

Instance Methods

Command Configuration

Method Description
WithCommand(ICommand command, object? parameter = null) Sets the tap command.
WithLongPressCommand(ICommand command, object? parameter = null) Sets the long press command.
WithLongPressDuration(int milliseconds) Sets long press duration.

Visual Configuration

Method Description
WithPressedState(double? opacity, double? scale, Color? backgroundColor) Configures pressed state.
WithHoveredState(double? opacity, double? scale, Color? backgroundColor) Configures hovered state.
WithNormalState(double? opacity, double? scale, Color? backgroundColor) Configures normal state.
WithPressedOpacity(double opacity) Sets pressed opacity.
WithPressedScale(double scale) Sets pressed scale.
WithPressedBackgroundColor(Color color) Sets pressed background color.
WithHoveredScale(double scale) Sets hovered scale.

Animation Configuration

Method Description
WithAnimation(int duration, Easing? easing = null) Sets animation duration and easing.
WithPressedAnimation(int duration, Easing? easing = null) Sets pressed state animation.
WithHoveredAnimation(int duration, Easing? easing = null) Sets hovered state animation.
WithPulse(int count) Sets pulse count.
WithInfinitePulse() Enables infinite pulsing.

Native Animation Configuration

Method Description
WithNativeAnimation(Color? color = null, int radius = -1) Enables native platform animations.

Toggle Configuration

Method Description
AsToggle(bool initialState = false) Enables toggle behavior.

Other Configuration

Method Description
WithDisallowThreshold(int pixels) Sets movement cancellation threshold.
Disable() Disables the effect.

Preset Methods

Method Description
AsButton() Applies standard button preset.
AsCard() Applies card preset with scale effect.
AsListItem() Applies list item preset with background color.
AsFloatingActionButton() Applies FAB preset with native animation.

Build Methods

Method Returns Description
Build() VisualElement Applies configuration and returns the element.
Apply() TouchEffectBuilder Applies configuration and returns builder for chaining.

Usage

// Basic usage
var button = TouchEffectBuilder.For(myFrame)
    .WithPressedScale(0.95)
    .WithPressedOpacity(0.8)
    .WithAnimation(100, Easing.CubicOut)
    .WithCommand(tapCommand)
    .Build();

// Using presets
var card = TouchEffectBuilder.For(myCard)
    .AsCard()
    .WithCommand(selectCommand)
    .Build();

// Complex configuration
var interactive = TouchEffectBuilder.For(element)
    .WithPressedState(opacity: 0.7, scale: 0.95, backgroundColor: Colors.LightGray)
    .WithHoveredState(opacity: 1.0, scale: 1.02, backgroundColor: Colors.White)
    .WithAnimation(150, Easing.CubicInOut)
    .WithLongPressCommand(contextMenuCommand)
    .WithLongPressDuration(800)
    .AsToggle()
    .Build();

Extension Methods

// Create a builder for any VisualElement
public static TouchEffectBuilder ConfigureTouchEffect(this VisualElement element)

// Quick presets
public static VisualElement WithButtonEffect(this VisualElement element, ICommand? command = null)
public static VisualElement WithCardEffect(this VisualElement element, ICommand? command = null)

TouchEffectPresets Class

Predefined TouchEffect configurations for common UI patterns.

Namespace: MarketAlly.TouchEffect.Maui

Button Presets

Method Description
Button.Apply(element) Standard button with opacity feedback (0.7 pressed).
Button.ApplyPrimary(element) Primary button with scale (0.95) and opacity (0.8).
Button.ApplySecondary(element) Secondary button with subtle opacity (0.6).
Button.ApplyText(element) Text button with minimal feedback (0.5 opacity, instant).

Card Presets

Method Description
Card.Apply(element) Standard card with subtle scale (0.97).
Card.ApplyElevated(element) Elevated card with scale (0.95), opacity (0.9), hover scale (1.02).
Card.ApplyInteractive(element) Interactive card with hover background highlight.

ListItem Presets

Method Description
ListItem.Apply(element) Standard list item with background highlight.
ListItem.ApplySelectable(element) Selectable item with toggle behavior.
ListItem.ApplySwipeable(element) Swipeable item with scale feedback.

IconButton Presets

Method Description
IconButton.Apply(element) Standard icon button with scale (0.85), spring animation.
IconButton.ApplyFloatingAction(element) FAB with scale (0.9), native animation.
IconButton.ApplyToolbar(element) Toolbar icon with subtle opacity (0.5).

Toggle Presets

Method Description
Toggle.Apply(element) Standard toggle with scale effect.
Toggle.ApplyCheckbox(element) Checkbox-style with bounce animation.

Image Presets

Method Description
Image.ApplyThumbnail(element) Thumbnail with scale (0.95 pressed, 1.05 hover).
Image.ApplyGallery(element) Gallery image with zoom effect (1.1 hover).
Image.ApplyAvatar(element) Avatar with subtle feedback.

Native Presets

Method Description
Native.ApplyRipple(element, color?) Android ripple effect.
Native.ApplyHaptic(element) iOS-style haptic feedback.

Special Presets

Method Description
Special.ApplyPulse(element, count) Pulse effect with repeating animation.
Special.ApplyBounce(element) Bounce effect with spring animation.
Special.ApplyShake(element) Shake effect with rotation.
Special.ApplyDisabled(element) Disabled state with no interaction.

Extension Methods

element.WithButtonPreset();
element.WithCardPreset();
element.WithListItemPreset();
element.WithIconButtonPreset();
element.WithNativeEffect(color?);

Enumerations

TouchStatus

Namespace: MarketAlly.TouchEffect.Maui.Enums

Value Description
Started Touch has started.
Completed Touch completed successfully.
Canceled Touch was canceled (moved outside, interrupted).

TouchState

Namespace: MarketAlly.TouchEffect.Maui.Enums

Value Description
Normal Element is in normal state.
Pressed Element is being pressed.

TouchInteractionStatus

Namespace: MarketAlly.TouchEffect.Maui.Enums

Value Description
Started User interaction started.
Completed User interaction completed.

HoverStatus

Namespace: MarketAlly.TouchEffect.Maui.Enums

Value Description
Entered Pointer entered the element.
Exited Pointer exited the element.

HoverState

Namespace: MarketAlly.TouchEffect.Maui.Enums

Value Description
Normal Element is not being hovered.
Hovered Element is being hovered.

Interfaces

ITouchEffectLogger

Namespace: MarketAlly.TouchEffect.Maui.Interfaces

Interface for custom logging implementations.

public interface ITouchEffectLogger
{
    void LogError(Exception ex, string context, string? additionalInfo = null);
    void LogWarning(string message, string context);
    void LogInfo(string message, string context);
}

Built-in Implementations

DefaultTouchEffectLogger

Logs to Debug.WriteLine with formatted output.

TouchEffect.SetLogger(new DefaultTouchEffectLogger());

NullTouchEffectLogger

No-op logger that discards all messages. Used by default.

// Singleton instance
NullTouchEffectLogger.Instance

Constants

TouchEffectConstants

Namespace: MarketAlly.TouchEffect.Maui

Defaults

Constant Value Description
LongPressDuration 500 Default long press duration (ms).
Opacity 1.0 Default opacity.
Scale 1.0 Default scale.
TranslationX 0.0 Default X translation.
TranslationY 0.0 Default Y translation.
Rotation 0.0 Default rotation.
PulseCount 0 Default pulse count.
DisallowTouchThreshold 0 Default movement threshold.
NativeAnimationRadius -1 Default native animation radius.
NativeAnimationShadowRadius -1 Default shadow radius.

Animation

Constant Value Description
DefaultDuration 0 Default animation duration.
DefaultProgressDelay 10 Delay between animation frames.
TargetFrameRate 60 Target animation frame rate.

PresetDurations

Constant Value Description
Instant 0 No animation.
VeryFast 50 Very fast animations (ms).
Fast 100 Fast animations (ms).
Normal 200 Normal animations (ms).
Slow 300 Slow animations (ms).

VisualStates

Constant Value
Unpressed "Unpressed"
Pressed "Pressed"
Hovered "Hovered"

Platform.Android

Constant Value Description
DefaultRippleColor 128 Default ripple RGB value.
DefaultRippleAlpha 80 Default ripple alpha.
MinRippleRadius 48 Minimum ripple radius (dp).

Platform.iOS

Constant Value Description
HighlightAlpha 0.5f Default highlight alpha.

Event Args Classes

TouchStatusChangedEventArgs

public class TouchStatusChangedEventArgs : EventArgs
{
    public TouchStatus Status { get; }
}

TouchStateChangedEventArgs

public class TouchStateChangedEventArgs : EventArgs
{
    public TouchState State { get; }
}

TouchInteractionStatusChangedEventArgs

public class TouchInteractionStatusChangedEventArgs : EventArgs
{
    public TouchInteractionStatus InteractionStatus { get; }
}

HoverStatusChangedEventArgs

public class HoverStatusChangedEventArgs : EventArgs
{
    public HoverStatus Status { get; }
}

HoverStateChangedEventArgs

public class HoverStateChangedEventArgs : EventArgs
{
    public HoverState State { get; }
}

TouchCompletedEventArgs

public class TouchCompletedEventArgs : EventArgs
{
    public object? Parameter { get; }
}

LongPressCompletedEventArgs

public class LongPressCompletedEventArgs : EventArgs
{
    public object? Parameter { get; }
}

Migration Guide

From v1.x to v2.0

  1. Update package reference to version 2.0.0
  2. Update target framework to .NET 10 if needed
  3. Optional: Use TouchBehavior instead of attached properties for new code
  4. Optional: Configure logging using TouchEffect.SetLogger()

No breaking changes - all v1.x code continues to work.

From Xamarin TouchEffect

  1. Update namespace from Xamarin.CommunityToolkit.Effects to MarketAlly.TouchEffect.Maui
  2. Replace TouchEff with TouchEffect in XAML
  3. Update UseMauiApp<App>() to include .UseMauiTouchEffect()

Last updated: January 2025 | Version 2.0.0

Reference in New Issue View Git Blame Copy Permalink