[Spec] CarouselView

[rmarinho]

CarouselView

CarouselView is a concept used in a lot of mobile applications. We already had a CarouselPage since the initial XF version, but that only supported Pages and didn't support virtualisation. Based on the new CollectionView we are introducing CarouselView that allows to create performant CarouselView's that could be snap to position, swiped and provide position and paging info.

We are looking at other existing versions try to have a full feature set to make our users happy, this will be allowing them to specify scroll direction, position, spacing between items , how the pager dot works and feels.

CarouselView will always have all items sized to fit the viewport and taking in account the visible items on each side the user specified, and all items will have the same size.

CarouselView must easily integrate with IndicatorsView #6577

Note: Nothing in this specification is guaranteed to be final; all features, implementations, and interfaces are subject to change.

Related issues

• IndicatorsView [Spec] IndicatorsView #6577
• [Enhancement] CollectionView item spacing #4681
• https://github.com/xamarin/Xamarin.Forms.CarouselView/blob/master/txt/src/carouselView/dev/Shared/CarouselView.cs

API

CarouselView

public class CarouselView :  ItemsView
{
	public const string CurrentItemVisualState = "CurrentItem";
	public const string NextItemVisualState = "NextItem";
	public const string PreviousItemVisualState = "PreviousItem";
	public const string VisibleItemVisualState = "VisibleItem";
	public const string DefaultItemVisualState = "DefaultItem";

	public static readonly BindableProperty PeekAreaInsetsProperty = BindableProperty.Create(nameof(PeekAreaInsets), typeof(Thickness), typeof(CarouselView), default(Thickness));

	public Thickness PeekAreaInsets
	{
		get { return (Thickness)GetValue(PeekAreaInsetsProperty); }
		set { SetValue(PeekAreaInsetsProperty, value); }
	}

       static readonly BindablePropertyKey IsScrollingPropertyKey = BindableProperty.CreateReadOnly(nameof(IsScrolling), typeof(bool), typeof(CarouselView), false);

	public static readonly BindableProperty IsScrollingProperty = IsScrollingPropertyKey.BindableProperty;

	public bool IsScrolling => (bool)GetValue(IsScrollingProperty);

        public static readonly BindablePropertyKey IsDraggingPropertyKey = BindableProperty.CreateReadOnly(nameof(IsDragging), typeof(bool), typeof(CarouselView), false);

	public static readonly BindableProperty IsDraggingProperty = IsDraggingPropertyKey.BindableProperty;

	public bool IsDragging => (bool)GetValue(IsDraggingProperty);

	public static readonly BindableProperty IsBounceEnabledProperty =
			BindableProperty.Create(nameof(IsBounceEnabled), typeof(bool), typeof(CarouselView), true);

	public bool IsBounceEnabled
	{
		get { return (bool)GetValue(IsBounceEnabledProperty); }
		set { SetValue(IsBounceEnabledProperty, value); }
	}

	public static readonly BindableProperty IsLoopEnabledProperty = BindableProperty.Create(nameof(IsLoopEnabled), typeof(bool), typeof(CarouselView), false);

	public bool IsLoopEnabled
	{
		get { return (bool)GetValue(IsLoopEnabledProperty); }
		set { SetValue(IsLoopEnabledProperty, value); }
	}

	public static readonly BindableProperty IsSwipeEnabledProperty = BindableProperty.Create(nameof(IsSwipeEnabled), typeof(bool), typeof(CarouselView), true);

	public bool IsSwipeEnabled
	{
		get { return (bool)GetValue(IsSwipeEnabledProperty); }
		set { SetValue(IsSwipeEnabledProperty, value); }
	}

	public static readonly BindableProperty IsScrollAnimatedProperty =
		BindableProperty.Create(nameof(IsScrollAnimated), typeof(bool), typeof(CarouselView), true);

	public bool IsScrollAnimated
	{
		get { return (bool)GetValue(IsScrollAnimatedProperty); }
		set { SetValue(IsScrollAnimatedProperty, value); }
	}

	public static readonly BindableProperty NumberOfSideItemsProperty =
			BindableProperty.Create(nameof(NumberOfSideItems), typeof(int), typeof(CarouselView), 0);

	public int NumberOfSideItems
	{
		get { return (int)GetValue(NumberOfSideItemsProperty); }
		set { SetValue(NumberOfSideItemsProperty, value); }
	}

	public static readonly BindableProperty PositionProperty =
		BindableProperty.Create(nameof(Position), typeof(int), typeof(CarouselView), default(int), BindingMode.TwoWay,
			propertyChanged: PositionPropertyChanged);

	public static readonly BindableProperty PositionChangedCommandProperty =
			BindableProperty.Create(nameof(PositionChangedCommand), typeof(ICommand), typeof(CarouselView));

	public static readonly BindableProperty PositionChangedCommandParameterProperty =
			BindableProperty.Create(nameof(PositionChangedCommandParameter), typeof(object),
				typeof(CarouselView));

	public int Position
	{
		get => (int)GetValue(PositionProperty);
		set => SetValue(PositionProperty, value);
	}

	public ICommand PositionChangedCommand
	{
		get => (ICommand)GetValue(PositionChangedCommandProperty);
		set => SetValue(PositionChangedCommandProperty, value);
	}

	public object PositionChangedCommandParameter
	{
		get => GetValue(PositionChangedCommandParameterProperty);
		set => SetValue(PositionChangedCommandParameterProperty, value);
	}
        
        public static readonly BindableProperty CurrentItemProperty =
		BindableProperty.Create(nameof(CurrentItem), typeof(object), typeof(CarouselView),  default(object), BindingMode.TwoWay, propertyChanged: CurrentItemPropertyChanged);

	public static readonly BindableProperty CurrentItemChangedCommandProperty =
			BindableProperty.Create(nameof(CurrentItemChangedCommand), typeof(ICommand), typeof(CarouselView));

	public static readonly BindableProperty CurrentItemChangedCommandParameterProperty =
			BindableProperty.Create(nameof(CurrentItemChangedCommandParameter), typeof(object), typeof(CarouselView));

	public object CurrentItem
	{
		get => GetValue(CurrentItemProperty);
		set => SetValue(CurrentItemProperty, value);
	}

	public ICommand CurrentItemChangedCommand
	{
		get => (ICommand)GetValue(CurrentItemChangedCommandProperty);
		set => SetValue(CurrentItemChangedCommandProperty, value);
	}

	public object CurrentItemChangedCommandParameter
	{
		get => GetValue(CurrentItemChangedCommandParameterProperty);
		set => SetValue(CurrentItemChangedCommandParameterProperty, value);
	}

	public event EventHandler<CurrentItemChangedEventArgs> CurrentItemChanged;
	public event EventHandler<PositionChangedEventArgs> PositionChanged;
        public event EventHandler<ScrolledEventArgs> Scrolled;

        //Methods to be called by the platforms
        void SendScrolled(double value, ScrollDirection direction);
	void SetCurrentItem(object item);
	void SetIsScrolling(bool value);
	void SetIsDragging(bool value);
}

Properties

API	Description
CurrentItem	Current item visible and centered on the CarouselView
Position	Current position of the current item in the collection, when changed raises PositionChanged should also sync with CurrentItem
IsLoopEnabled	Specify if when arriving to last source position we should show next the first position
IsScrollAnimated	Specify if should see animation when changing position or selected item
IsSwipeEnabled	If swipe left and right are enable to switch times
NumberOfSideItems	Number of visible items on each side of the current item , defaults to 0
IsBounceEnabled	If the CarouselView bounces when reaching the end of the list
IsDragging	Readonly that is True when the user is interacting and dragging the carousel
IsScrolling	Readonly that is True when the CarouselView is being scrolled by changing the position value
PeakAreaInsets	Set the viewport insets, this will allow to "peek" items

VisualStateManager States	Description
CurrentItemVisualState	VisualState set for when a view is set as CurrentItem and visible on screen
NextItemVisualState	VisualState set for when a view is visible on screen and next the current item
PreviousItemVisualState	VisualState when a view is on screen and before the current item
VisibleItemVisualState	VisualState when a view is visible on screen but not Next,Previous or Current state
DefaultItemVisualState	VisualState default when a view is created initially

Events

API	Description
Scrolled	Fires when the carousel is scrolling
PositionChanged	[API documentation/description]
CurrentItemChanged	[API documentation/description]

CurrentItemChangedEventArgs

public class CurrentItemChangedEventArgs : EventArgs
{
	public object PreviousItem { get; }
	public object CurrentItem { get; }

	internal CurrentItemChangedEventArgs(object previousItem, object currentItem)
	{
		PreviousItem = previousItem;
		CurrentItem = currentItem;
	}
}

Properties

API	Description
PreviousItem	Get's the previous item.
CurrentItem	Get's the current item.

Extend ScrolledEventArgs

//extend existing ScrolledEvent args with new Ctor and DeltaX and DeltaY properties 
public class ScrolledEventArgs : EventArgs
{
	public ScrolledEventArgs(double scrollX, double scrollY, double deltaX, double  deltaY)
	{
		ScrollX = scrollX;
		ScrollY = scrollY;
		DeltaX = deltaX;
		DeltaY = deltaY;
	}
	public double ScrollX { get; private set; }
	public double ScrollY { get; private set; }
        public double DeltaX { get; private set; }
	public double DeltaY { get; private set; }
}

Properties

API	Description
ScrollX	Get's the current scroll x offset
DeltaX	Get's the current delta x from the last scroll event
ScrollY	Get's the current scroll y offset
DeltaY	Get's the current delta y from the last scroll event

PositionChangedEventArgs

public class PositionChangedEventArgs : EventArgs
{
	public int PreviousPosition { get; }
	public int CurrentPosition { get; }
}

Properties

API	Description
PreviousPosition	Gets the previous position before the position changed.
CurrentPosition	Gets the current position

3D and Custom layouts

Users can achieve other layouts in the future we can provide a CoverFlowItemsLayout and a StackedItemsLayout

public class CoverFlowItemsLayout : ItemsLayout
{
	public CoverFlowItemsLayout(ItemsLayoutOrientation orientation) : base(orientation)
	{
	}
	public static readonly BindableProperty ViewPointOffSetProperty =
		BindableProperty.Create(nameof(SnapPointsAlignment), typeof(double), typeof(CoverFlowItemsLayout), 2.2);

	public double ViewPointOffSet
	{
		get => (double)GetValue(ViewPointOffSetProperty);
		set => SetValue(ViewPointOffSetProperty, value);
	}

	public static readonly IItemsLayout Vertical = new CoverFlowItemsLayout(ItemsLayoutOrientation.Vertical);
	public static readonly IItemsLayout Horizontal = new CoverFlowItemsLayout(ItemsLayoutOrientation.Horizontal);
}

public class StackedItemsLayout : ItemsLayout
{
	public StackedItemsLayout(ItemsLayoutOrientation orientation) : base(orientation)
	{
	}

	public static readonly IItemsLayout Vertical = new StackedItemsLayout(ItemsLayoutOrientation.Vertical);
	public static readonly IItemsLayout Horizontal = new StackedItemsLayout(ItemsLayoutOrientation.Horizontal);
}

Scenarios

var carouselView = new CarouselView
{
	ItemsSource = itemsSource,
	ItemsLayout = itemsLayout,
	ItemTemplate = itemTemplate,
	Position = 2,
	NumberofSideItems = 1
};

Backward Compatibility

We should make sure there's no conflicts with old versions of CarouselView created by us or other.

Difficulty :

High

[andreinitescu]

Just a thought, once CollectionView is released and fully stabilized, couldn't it be used to create a carousel view easily?

Except the pager, CollectionView has all the features for displaying a carousel (item virtualization, snapping, swiping, item template, etc.).
To add and create the pager, one can put have a Grid with a CollectionView and a bindable layout as a pager. The pager can be a linear StackLayout with ItemsSource of a collection of booleans and a DataTemplateSelector to show some images to be filled or empty.

The carousels can look different, the pager can be positioned differently, some have it at the bottom, some at the top, vertical distance to the where pages slide can be different, some carousels show a text displayed for every page (which is not inside the carousel items, it's above or below the pager), or have border around the actual container where pages slide.

But if you want to provide and support this out of the box, this can very cool too.

[rmarinho]

Hi @andreinitescu yes we will be using the same core from CollectionView, this will just augment some more properties.

You are right one could have lots of ways of creating the pager etc.. Users want it to work out of the box, so the idea is to add support for the pager, styling the pager and possible some arrows to move on the side.

Thanks for your feedback.

[sdebruyn]

Typo: IndicatoraVisibilityProperty

[mattleibow]

Same with IndicatorsVisibility - probably doesn't need the s, unless there can be multiple indicators at a time? If it can have multiple, then maybe we sould think about what it would mean to show/hide individual ones?

[mattleibow]

I also see we have a selected and a deselected indicator, maybe we should merge the IndicatorShape into this? What if i want to have a small dot for the default, and a bigger one for the selected? We could have a:

public IndicatorAppearance Indicator { get; set; }
public IndicatorAppearance SelectedIndicator { get; set; }

class IndicatorAppearance {
    public Color TintColor { get; set; }
    public IndcatorShape Shape { get; set; }
}

That might be harder to write in XAML, but then we can just split the properties out so there would be 4 properties - 2 per indicator?

I see there is also the indicator template - which is probably better than just a basic shape. But, what does the shape do if I specify both? I suppose the shape is more of a quick - use dots - without having to create a full view. We just need to specify a rule that determines the order of usage: first check template, else use shape.

[mattleibow]

I think the Loop property may be confusing - maybe Wrap or AllowWrap is better? I also note that it (along with the animation property) does not have a dependency property?

[mattleibow]

ArrowsVisibility probably should not be a boolean as the words imply that there is a choice - like the indicators type. We may want to use a ArrowsVisible.

Another thing comes to mind, would we want to control the position of the arrows? If I am doing a vertically scrolling list, would i want to put the arrows at the top and bottom? How would one control the orientation of the scroll? This may not be relevant depending on the answer, but what about ArrowDirection: Horizontal, Vertical, None? (Chances are the scroll orientation dictates the position, but just checking)

I see we only have 1 arrow template, how do we support the forward/back style? What if I want a big arrow for next, but a small one for back (because we never go back in life) :).

[mattleibow]

With regards to arrows and indicators, would we want to use images out the box? I may have a simple carousel and just want to replace the images for the arrows? We do have the new font image source that will be great for many of these things. Especially for the indicators as well - there are fonts that have all the bits that we need - without resorting to embedding images or having multiple layouts just to add an image view.

this reminds me that I still need to get back to #4915 with all the changes there for something like this

[davidortinau]

Need:

• a SelectionChanged Command.
• direction of scroll (as @mattleibow mentions)
• scroll events to be able to apply transforms

• offsets and view point (offset)
• set number of elements to view on screen at once and/or a viewport to be able to achieve something with items peeking in from the sides

• IndicatorVisibility isn't enough. How do I position over the top of my content in a chosen position?

[mattleibow]

Maybe this is what @davidortinau said, but the ability to control the separator gap size asa well as scaling differences with the visible page. This control is pretty good: https://github.com/nicklockwood/iCarousel. Items may have different sizes, and may change size as they get nearer the selection. There is also this: https://www.syncfusion.com/xamarin-ios-ui-controls/carousel-view 😄

[andreinitescu]

There's also a question how to control the viewport/camera in such a way it looks good on a table in landscape. It won't look good if the currently selected item is huge.

[rmarinho]

Hi everyone thanks for the feedback I have playing a little bit with the feedback and updated the spec.

Some of the changes are:

• CarouselView shares same implementation with SelectableItemsView, when the user swipes and moves the position of the item, we change the SelectedItem, CarouselView will sync it's position by listen for SelectedItem changes.

• Moving Indicators to its own control, with BP for Position and Count one could use it to anything it wants, to link to a Carousel (or any SelectableItemsView) just use ItemsSourceBy to specify a reference, we also drop IndicatorTemplate this could be achieve it the users want with a BindableLayout.

• Added Scrolled event with Direction and NewValue and Delta.. I need to double check if this is enough

I think we need a VisibleItems int and or maybe a HintNextItems that would peek the next , still not sure, playing with some concepts to see what feels better and most common.

I also have been playing with the spec in this branch https://github.com/xamarin/Xamarin.Forms/tree/spec-carousel

@hartez I refactor some stuff to make it easy to use between platforms, please take a look give me your thoughts.

Thanks you all, keep that feedback coming.

[rmarinho]

I also am trying to figure how will handle Something like MaxItems on the IndicatorsView and how that will relate with Position