[Proposal] AvatarView

AvatarView

• Proposed
• Prototype: Not Started
• Implementation
  • iOS Support
  • Android Support
  • macOS Support
  • Windows Support
• Unit Tests
• Sample
• Documentation

Summary

Allows the user to display an avatar or the user’s initials if no avatar is available

Detailed Design

AvatarView.shared.cs

public class AvatarView : BaseTemplatedView<Frame>
{
  public static readonly BindableProperty AspectProperty;
  public static readonly BindableProperty SizeProperty;
  public static readonly BindableProperty CornerRadiusProperty;
  public static readonly BindableProperty BorderColorProperty;
  public static readonly BindableProperty ColorProperty;
  public static readonly BindableProperty SourceProperty;
  public static readonly BindableProperty TextProperty;
  public static readonly BindableProperty TextColorProperty;
  public static readonly BindableProperty FontFamilyProperty;
  public static readonly BindableProperty FontSizeProperty;
  public static readonly BindableProperty FontAttributesProperty;
  public static readonly BindableProperty ColorThemeProperty;
  
  public Aspect Aspect { get; set; }
  public double Size { get; set; }
  public double CornerRadius { get; set; }
  public Color BorderColor { get; set; }
  public Color Color { get; set; }
  public ImageSource? Source { get; set; }
  public string? Text { get; set; }
  public Color { get; set; }
  public string? FontFamily { get; set; }
  [TypeConverter(typeof(FontSizeConverter))]
  public double FontSize { get; set; }
  public FontAttributes FontAttributes { get; set; }
  public IColorTheme ColorTheme { get; set; }
}

Usage Syntax

XAML Usage

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:xct="http://xamarin.com/schemas/2020/toolkit"
             x:Class="MyLittleApp.MainPage">

     <StackLayout>

        <xct:AvatarView Text="{Binding Initials}" Source="{Binding AvatarSource}" />

    </StackLayout>

</ContentPage>

C# Usage

class MyPage : ContentPage
{
  public MyPage()
  {
    Content = ContentPage
    {
      new AvatarView()
        .Bind(AvatarView.InitialsProperty, nameof(ViewModel.Initials))
        .Bind(AvatarView.AvatarSourceProperty, nameof(ViewModel.AvatarSource))
    }
  }
}

[GeorgeLeithead]

@GeorgeLeithead thanks for the contribution and the write up of your objectives to help us. I have a couple of questions/points:

1. Do we need the Clicked/Pressed events? We could achieve most of the behaviour through the use of GestureRecognizers, the only part it wouldn’t offer is the Released event but I can’t think of a use case for needing that. Did you have one?
2. IsOpaque could probably be controlled through an Opacity property which you may just get from the control you use to implement.
3. You mention IsAnimationPlaying, are you thinking of providing some level of animation to show loading?

@bijington In answer to your questions/points, some of which MAY be answered by the ‘draft’ pull I made as suggested by @brminnick . However, I think more questions will be raised as we look at the porpoal WIP code.

1. When looking at this and the Microsoft.Maui repository, I initially looked at the Button control and the interfaces it used. Things have since evolved as I worked thru a few options. I have included in the Samples an example that demonstrates using the OOTB GestureRecognizers. Where possible, I think it’s best to keep everything as close to standard/OOTB as possible.
2. You are correct, and I’ll try to use standard OOTB features and properties where possible.
3. When the imagesource is local, there is no (visible) delay in the image loading. However, when using a URL source (such as the ‘campus’ in my samples), there is a noticible delay between the control rendering and the image appearing. It MAY be prudent to display some kind of loading/animation, to keep the end-user informed as to what is happening.

[GeorgeLeithead]

I have created a fork, and appropriately named branch, to work on some options for this proposal.

See 104-AvatarView for the work-in-progress code branch.

I am incredibly open to suggestions, comments, raised issues, and looking for some guidance from the community veterans.

Ideally, I’d like to achieve the following, to make the control as extensible and customisable by the end user as possible, using known and standard control properties. These are my personal objectives for the control, and open to discussion/review:

• The control must allow options for a text or image avatar.
• The control must by default display the text option and have a default value.
• The control must display the image option if provided, hiding any text option.
• The control must display the text avatar within the centre of the control and be clipped as appropriate (within any border, stroke, corner radius, etc.)
• The control must display the image avatar within the control and have an aspect to fill the bounds of the control but also be clipped as appropriate (within any border, stroke, corner radius, etc.)
• The control should provide Font element fields (e.g. Attributes, family, size, and auto scaling), which are applied to the text option.
• The control should provide text element fields (e.g. Colour, character spacing, transformation), which are applied to the text option.
• The control should provide image element fields (e.g. Source, Is Opaque, Is Loading, Is Animation Playing), which are applied to the image option. (Note, the ‘aspect’ field is defined elsewhere)
• The control should provide border element fields (e.g. Border Colour, Corner Radius, Background Colour, Background, Border Width), which are applied to the avatar control.
• The control should provide padding element fields (e.g. Thickness), which are applied to the avatar control.
• The control should provide MAUI.Layout element fields (e.g. Clips To Bounds), which are applied to the avatar control.
• The control should provide view element fields (e.g. Is Focused, Z-Index, Desired Size, Margin, Maximum Heigh, Minimum Height, Height, Maximum Width, Minimum Width, Width, Frame, Background, Opacity, Visibility, Is Enabled, Shadow, Clip, Semantics, Vertical Layout Alignment, Horizontal Layout Alignment, Flow Direction, Automation Id, Handler, etc.), which are applied to the avatar control.
• The control could provide clicked, pressed, and released events for consumption by the control implementor. (e.g. The click event could be used to navigate to a profile page).