Share via

Reusable EffectBehavior

  • Article

Behaviors are a useful approach for adding an effect to a control, removing boiler-plate effect handling code from code-behind files. This article demonstrates creating and consuming a Xamarin.Forms behavior to add an effect to a control.

Overview

The EffectBehavior class is a reusable Xamarin.Forms custom behavior that adds an Effect instance to a control when the behavior is attached to the control, and removes the Effect instance when the behavior is detached from the control.

The following behavior properties must be set to use the behavior:

For more information about effects, see Effects.

Note

The EffectBehavior is a custom class that can be located in the sample, and is not part of Xamarin.Forms.

Creating the Behavior

The EffectBehavior class derives from the Behavior<T> class, where T is a View. This means that the EffectBehavior class can be attached to any Xamarin.Forms control.

Implementing Bindable Properties

The EffectBehavior class defines two BindableProperty instances, which are used to add an Effect to a control when the behavior is attached to the control. These properties are shown in the following code example:

public class EffectBehavior : Behavior<View>
{
  public static readonly BindableProperty GroupProperty =
    BindableProperty.Create ("Group", typeof(string), typeof(EffectBehavior), null);
  public static readonly BindableProperty NameProperty =
    BindableProperty.Create ("Name", typeof(string), typeof(EffectBehavior), null);

  public string Group {
    get { return (string)GetValue (GroupProperty); }
    set { SetValue (GroupProperty, value); }
  }

  public string Name {
    get { return(string)GetValue (NameProperty); }
    set { SetValue (NameProperty, value); }
  }
  ...
}

When the EffectBehavior is consumed, the Group property should be set to the value of the ResolutionGroupName attribute for the effect. In addition, the Name property should be set to the value of the ExportEffect attribute for the effect class.

Implementing the Overrides

The EffectBehavior class overrides the OnAttachedTo and OnDetachingFrom methods of the Behavior<T> class, as shown in the following code example:

public class EffectBehavior : Behavior<View>
{
  ...
  protected override void OnAttachedTo (BindableObject bindable)
  {
    base.OnAttachedTo (bindable);
    AddEffect (bindable as View);
  }

  protected override void OnDetachingFrom (BindableObject bindable)
  {
    RemoveEffect (bindable as View);
    base.OnDetachingFrom (bindable);
  }
  ...
}

The OnAttachedTo method performs setup by calling the AddEffect method, passing in the attached control as a parameter. The OnDetachingFrom method performs cleanup by calling the RemoveEffect method, passing in the attached control as a parameter.

Implementing the Behavior Functionality

The purpose of the behavior is to add the Effect defined in the Group and Name properties to a control when the behavior is attached to the control, and remove the Effect when the behavior is detached from the control. The core behavior functionality is shown in the following code example:

public class EffectBehavior : Behavior<View>
{
  ...
  void AddEffect (View view)
  {
    var effect = GetEffect ();
    if (effect != null) {
      view.Effects.Add (GetEffect ());
    }
  }

  void RemoveEffect (View view)
  {
    var effect = GetEffect ();
    if (effect != null) {
      view.Effects.Remove (GetEffect ());
    }
  }

  Effect GetEffect ()
  {
    if (!string.IsNullOrWhiteSpace (Group) && !string.IsNullOrWhiteSpace (Name)) {
      return Effect.Resolve (string.Format ("{0}.{1}", Group, Name));
    }
    return null;
  }
}

The AddEffect method is executed in response to the EffectBehavior being attached to a control, and it receives the attached control as a parameter. The method then adds the retrieved effect to the control's Effects collection. The RemoveEffect method is executed in response to the EffectBehavior being detached from a control, and it receives the attached control as a parameter. The method then removes the effect from the control's Effects collection.

The GetEffect method uses the Effect.Resolve method to retrieve the Effect. The effect is located through a concatenation of the Group and Name property values. If a platform doesn't provide the effect, the Effect.Resolve method will return a non-null value.

Consuming the Behavior

The EffectBehavior class can be attached to the Behaviors collection of a control, as demonstrated in the following XAML code example:

<Label Text="Label Shadow Effect" ...>
  <Label.Behaviors>
    <local:EffectBehavior Group="Xamarin" Name="LabelShadowEffect" />
  </Label.Behaviors>
</Label>

The equivalent C# code is shown in the following code example:

var label = new Label {
  Text = "Label Shadow Effect",
  ...
};
label.Behaviors.Add (new EffectBehavior {
  Group = "Xamarin",
  Name = "LabelShadowEffect"
});

The Group and Name properties of the behavior are set to the values of the ResolutionGroupName and ExportEffect attributes for the effect class in each platform-specific project.

At runtime, when the behavior is attached to the Label control, the Xamarin.LabelShadowEffect will be added to the control's Effects collection. This results in a shadow being added to the text displayed by the Label control, as shown in the following screenshots:

Sample Application with EffectsBehavior

The advantage of using this behavior to add and remove effects from controls is that boiler-plate effect-handling code can be removed from code-behind files.

Summary

This article demonstrated using a behavior to add an effect to a control. The EffectBehavior class is a reusable Xamarin.Forms custom behavior that adds an Effect instance to a control when the behavior is attached to the control, and removes the Effect instance when the behavior is detached from the control.