[Enhancement] add SetFocusOnEntryCompletedBehavior

[jmegner]

Summary

Add SetFocusOnEntryCompletedBehavior, which is a compact way of getting another control to get focus when user completes an entry.

See this blog post: https://adenearnshaw.com/focus-next-element-on-enter/

Just for reference, a bit of Twitter discussion where original author approves: https://twitter.com/jacobegner/status/1357767010206298112

API Changes

Add a Xamarin.CommunityToolkit.Behaviors.SetFocusOnEntryCompletedBehavior class.

Spec

public class SetFocusOnEntryCompletedBehavior : Behavior
{
    public static readonly BindableProperty TargetElementProperty
       = BindableProperty.Create(nameof(TargetElement), typeof(VisualElement), typeof(SetFocusOnEntryCompletedBehavior));

    public VisualElement TargetElement
    {
        get => (VisualElement)GetValue(TargetElementProperty);
        set => SetValue(TargetElementProperty, value);
    }
        
    protected override void OnAttachedTo(BindableObject bindable)
    {
        base.OnAttachedTo(bindable);
        
        if (bindable is Entry entry)
            entry.Completed += Entry_Completed;
    }

    protected override void OnDetachingFrom(BindableObject bindable)
    {
        if (bindable is Entry entry)
            entry.Completed -= Entry_Completed;

        base.OnDetachingFrom(bindable);
    }

    private void Entry_Completed(object sender, EventArgs e)
    {
        TargetElement?.Focus();
    }
}

Intended Use Case

It's great for a sequence of entries where completing one entry automatically jumps the user to the next entry, but it can jump focus to any control.

<ContentPage x:Class="NextFormFieldSample.Forms.MainPage"
             xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:behaviors="clr-namespace:NextFormFieldSample.Forms.Behaviors">
    <StackLayout Margin="20">   
        
        <Entry Placeholder="Field 1">
            <Entry.Behaviors>
                <behaviors:SetFocusOnEntryCompletedBehavior TargetElement="{x:Reference Entry2}" />
            </Entry.Behaviors>
        </Entry>

        <Entry x:Name="Entry2" Placeholder="Field 2"/>  
        
    </StackLayout>
</ContentPage>

Who Will Do The Work?

• I am willing to take this on myself
• Just putting this out there for someone to pick up

[jmegner]

@adenearnshaw Just in case you're interested.

[pictos]

@jmegner can you provide a spec for this feature?

[jmegner]

Is the code in the linked blog post enough? https://adenearnshaw.com/focus-next-element-on-enter/

[pictos]

@jmegner I would say to add this here to be documented. At any time this blog post can be edited or deleted.

[jmegner]

Implementation from blog (similar to his GitHub SetFocusOnEntryCompletedBehavior):

public class SetFocusOnEntryCompletedBehavior : Behavior
{
    public static readonly BindableProperty TargetElementProperty
       = BindableProperty.Create(nameof(TargetElement), typeof(VisualElement), typeof(SetFocusOnEntryCompletedBehavior));

    public VisualElement TargetElement
    {
        get => (VisualElement)GetValue(TargetElementProperty);
        set => SetValue(TargetElementProperty, value);
    }
        
    protected override void OnAttachedTo(BindableObject bindable)
    {
        base.OnAttachedTo(bindable);
        
        if (bindable is Entry entry)
            entry.Completed += Entry_Completed;
    }

    protected override void OnDetachingFrom(BindableObject bindable)
    {
        if (bindable is Entry entry)
            entry.Completed -= Entry_Completed;

        base.OnDetachingFrom(bindable);
    }

    private void Entry_Completed(object sender, EventArgs e)
    {
        TargetElement?.Focus();
    }
}

Example use in xaml (similar to his GitHub's MainPage.xaml):

<ContentPage x:Class="NextFormFieldSample.Forms.MainPage"
             xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:behaviors="clr-namespace:NextFormFieldSample.Forms.Behaviors">
    <StackLayout Margin="20">   
        
        <Entry Placeholder="Field 1">
            <Entry.Behaviors>
                <behaviors:SetFocusOnEntryCompletedBehavior TargetElement="{x:Reference Entry2}" />
            </Entry.Behaviors>
        </Entry>

        <Entry x:Name="Entry2" Placeholder="Field 2"/>  
        
    </StackLayout>
</ContentPage>

[pictos]

@jmegner thank you. Do you if it's possible to use an Attached property instead of a behavior. That way devs will type less to use this feature, which will look like...

   
        <Entry Placeholder="Field 1"
                    xct:SetFocusOnEntryCompletedBehavior.TargetElement ="{x:Reference Entry2}" />

        <Entry x:Name="Entry2" Placeholder="Field 2"/>  
        
    </StackLayout>

[jmegner]

@pictos that seems like a great idea. I don't do much attached property stuff, so I'll have to try it out to see if there are any obstacles.

@adenearnshaw do you know off the top of your head any obstacle to SetFocusOnEntryCompletedBehavior using an attached property?

[pictos]

@jmegner Let me know what you find.

[adenearnshaw]

@pictos that seems like a great idea. I don't do much attached property stuff, so I'll have to try it out to see if there are any obstacles.

@adenearnshaw do you know off the top of your head any obstacle to SetFocusOnEntryCompletedBehavior using an attached property?

Nothing comes to mind immediately. I knocked up a very quick poc and it seems feasible.

[jmegner]

@pictos that seems like a great idea. I'll try the attached property way.

@adenearnshaw thanks for the proof-of-concept.

[jmegner]

@pictos What preference do you have for where it goes and what it is named? Existing XCT usage of attached properties seems to be mostly Effect and View stuff, and this is no longer a Behavior. Maybe it should go in the Helpers folder and simply be called SetFocusOnEntryCompleted?