Maui (net8), Xamarin Forms, Native (xamarin & .net8) - iOS + Android |
---|
Wheel Picker
Definition from Apple 🍏 :
A Wheel Picker is a view that uses a spinning-wheel or slot-machine metaphor to display one or more sets of values.
This interactive UI control mimics a slot machine user interface on Android, while on iOS, it makes it easy to use multi-wheel pickers.
Enterprise support available: contact sales
Source code available: contact sales
UI controls
- Maui net8 / Xamarin Forms / Android+iOS:
WheelPicker
(hot reload & trimming enabled) - net8-android & Xamarin Android:
vapolia.WheelPicker
(can be used in layout .xml files) - net8-ios & Xamarin iOS:
UIPickerViewModel
(can be used in storyboards)
Video presentations
Quick start
Install the nuget package
dotnet add package Vapolia.WheelPicker
MAUI Specific
If using Maui, register the control in the CreateMauiApp()
function:
...
using Vapolia.WheelPickers;
...
builder
.UseMauiApp<App>()
.UseWheelPicker();
Add a WheelPicker to your xaml UI
- Add
xmlns:wp="https://vapolia.eu/WheelPicker"
to the root tag - Add a minimal wheel:
<wp:WheelPicker ItemsSourceSimple="{Binding MyListProperty}">
<wp:WheelDefinition Width="Auto" HorizontalOptions="Left" Alignment="Center" />
</wp:WheelPicker>
Anatomy of the control
The WheelPicker is made of 2 parts:
- the container
<wp:WheelPicker> ... </wp:WheelPicker>
which contains 1 or more wheels and present them like a Horizontal StackLayout does. - a list of 1 or more
wp:WheelDefinition
, each representing a vertical interactive wheel.
Trick:wp:WheelDefinition
has a customizable template to display each item of the wheel.
The WheelPicker is bound to a single data source through ItemsSource="{Binding SomeProperty}"
.
The type of SomeProperty
can be:
For 1 wheel:
- a list of items
IReadOnlyCollection<T>
. Ex:List<string>
- a list of items
For more than 1 wheel:
- a list of list of items
IReadOnlyCollection<IReadOnlyCollection<T>>
. Ex:List<List<MyItemModel>>
- Each inner list is bound to a wheel.
The outer list must have a number of items equal to the number ofwp:WheelDefinition
.
- a list of list of items
Full example
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:wp="clr-namespace:Vapolia.WheelPickers;assembly=Vapolia.WheelPicker"
x:Class="WheelPickerDemo.Forms.MainPage">
<VerticalStackLayout>
<wp:WheelPicker HorizontalOptions="Fill" SelectedItemsIndex="0"
ItemsSource="{Binding Days}"
Command="{Binding ItemSelectedCommand}">
<wp:WheelDefinition Width="Auto" HorizontalOptions="Left" Alignment="Center" />
</wp:WheelPicker>
</VerticalStackLayout>
</ContentPage>
In the code behind, set the binding context to your view model containing the items to display.
For the example below ItemsSource
is bound to a list of strings.
public partial class MainPage : ContentPage
{
public MainPage()
{
InitializeComponent();
BindingContext = new MainPageModel();
}
}
public class MainPageModel
{
public List<string> Days { get; } = new () { "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" };
public Command ItemSelectedCommand { get; }
public MainPageModel()
{
//Component is the index of the wheel triggering the command.
//Row is the index of the currently displayed item at the center of the wheel for this Component.
//ItemIndexes are the current indexes of all wheels of the WheelPicker control
ItemSelectedCommand = new Command<(int Component, int Row, IList<int> ItemIndexes)>(tuple =>
{
var selectedValue = Days[tuple.Row];
//...
});
}
}
Using custom templates
You can customize how each item is rendered by using custom templates.
By default, the control converts all items to strings and renders those strings with the specified style.
You can fully customize the style and content of the items. However, there is a constraint: there is only one template per wheel, which renders all items of that wheel. If you have multiple wheels in the same WheelPicker, you can set one template per wheel.
For example, below is a templated picker with 3 wheels. All properties are bindable and can be dynamically changed.
Note how SelectedItemsIndex
is used to initialize the position of the 3 wheels to the specified item indexes.
<wp:WheelPicker x:Name="SlotPicker" ItemsSource="{Binding Slot.ItemsSource}"
SelectedItemsIndex="1 10 7"
Command="{Binding Slot.ItemSelectedCommand}"
ItemTextSelectedColor="Lime"
ItemTextFont="Italic"
HorizontalOptions="Fill"
SelectionLinesColor="Aquamarine">
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True">
<DataTemplate>
<Label Text="{Binding .}" TextColor="Black" FontSize="30" />
</DataTemplate>
</wp:WheelDefinition>
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="100">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="100" Aspect="AspectFit" />
</DataTemplate>
</wp:WheelDefinition>
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="100">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="100" Aspect="AspectFit" />
</DataTemplate>
</wp:WheelDefinition>
</wp:WheelPicker>
Some examples
Those examples are extracted from the demo projects in this repository.
A simple picker with one wheel:
<wp:WheelPicker ItemsSource="{Binding DayPicker.ItemsSource}">
<wp:WheelDefinition Width="Auto" HorizontalOptions="Left" Alignment="Center" />
</wp:WheelPicker>
A templated picker with one wheel:
<wp:WheelPicker ItemsSource="{Binding DayPicker.ItemsSource}">
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="48">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="48" Aspect="AspectFill" />
</DataTemplate>
</wp:WheelDefinition>
</wp:WheelPicker>
A picker with 3 wheels:
The width of the center wheel is computed automatically, and items are aligned differently inside each wheel.
<wp:WheelPicker SelectionLinesColor="Navy"
HorizontalSpaceBetweenWheels="40"
ItemsSource="{Binding DatePicker.ItemsSource}"
SelectedItemsIndex="0,0,0"
Command="{Binding DatePicker.ItemSelectedCommand}"
HorizontalOptions="Fill">
<wp:WheelDefinition Width="*" HorizontalOptions="Right" />
<wp:WheelDefinition Width="Auto" HorizontalOptions="Left" />
<wp:WheelDefinition Width="*" HorizontalOptions="Left" />
</wp:WheelPicker>
A templated picker with 3 wheels:
All properties are bindable and can be dynamically changed.
<wp:WheelPicker x:Name="SlotPicker" ItemsSource="{Binding Slot.ItemsSource}"
SelectedItemsIndex="0 0 0"
Command="{Binding Slot.ItemSelectedCommand}"
ItemTextSelectedColor="Lime"
ItemTextFont="Italic"
HorizontalOptions="Fill"
SelectionLinesColor="Aquamarine">
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="100">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="100" Aspect="AspectFit" />
</DataTemplate>
</wp:WheelDefinition>
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="100">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="100" Aspect="AspectFit" />
</DataTemplate>
</wp:WheelDefinition>
<wp:WheelDefinition Width="*" HorizontalOptions="Left" Alignment="Center" IsCircular="True" RowHeight="100">
<DataTemplate>
<Image Source="{Binding .}" HeightRequest="100" Aspect="AspectFit" />
</DataTemplate>
</wp:WheelDefinition>
</wp:WheelPicker>
Reference (Maui & Xamarin Forms)
Click to expand
WheelPicker
Definition
IList<WheelDefinition>
WheelDefinitions
Default Contentobject
ItemsSource
Accepts bothIReadOnlyCollection<T>
andIReadOnlyCollection<IReadOnlyCollection<T>>
Appearance
double
HorizontalSpaceBetweenWheels
Color
SelectionLinesColor
Item appearance (used by the default item template, when no custom item template is specified)
Font
ItemTextFont
Color
ItemTextColor
Color
ItemTextSelectedColor
Selection
IList<int>
SelectedItemsIndex
One index per wheel.ICommand
Command
Triggered when any of the wheel's index has changedEventHandler<WheelChangedEventArgs>
SelectedItemIndexChanged
Triggered when any of the wheel's index has changedvoid
Spin
(int items, int wheelIndex = 0)
items: the number of item to spin
SelectedItemsIndex
is a list of integers, where each integer represents the selected index within a wheel. In XAML, you can use a space- or comma-separated string of integers.
WheelDefinition
GridLength
Width
WheelItemAlign
HorizontalOptions
WheelItemAlign
Alignment
bool
IsCircular
DataTemplate
ImageItemTemplate
double
RowHeight
When a wheel's Width
is set to Auto
, the control computes the max width of all strings in the data source (if object are strings). When set to *
(star), the width of the wheel will be proportional to the remaining space. See the Grid
control for more information about GridLength
.
HorizontalOptions
is used to align a wheel inside the available width of the WheelPicker, if it is larger than the width of the wheel.
Alignment
is used to align the items within a wheel.
Reference (net8-android & Xamarin.Android)
Click to expand
Sample usage in axml:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<vapolia.WheelPicker
android:id="@+id/wheelView"
app:itemWidths="* Auto *"
app:itemAligns="Right Left Left"
app:itemHeights="15dp 15dp 15dp"
app:selectedItemTextColor="#ff228b22"
app:wp_itemTextColor="#ffffb6c1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="#FFFFFF" />
</LinearLayout>
var wheelView = FindViewById<WheelPicker>(Resource.Id.wheelView);
wheelView.SelectedItemIndexChanged += (sender, args) =>
{
var text = $"Wheel {args.WheelIndex} selection changed to item index {args.SelectedItemIndex}";
};
wheelView.ItemsSource = new List<string> { "Monday", "Tuesday", "Wednesday" };
wheelView.SelectedItemsIndex = new [] { 0 };
vapolia.WheelPicker
Definition
- object ItemsSource (either IReadOnlyCollection<T> or IReadOnlyCollection<IReadOnlyCollection<T>>)
- IReadOnlyCollection<T> ItemsSourceSimple (shortcut for ItemsSourceMulti with one wheel)
- IReadOnlyCollection<IReadOnlyCollection<T>> ItemsSourceMulti
- int VisibleItemCount
WheelPicker Appearance
- float HorizontalSpaceBetweenWheels
- float VerticalSpaceBetweenItems
- float ItemTextSize
- Typeface ItemTextTypeface
- Color ItemTextColor
- Color ItemTextSelectedColor
- bool ShowSelectionLines
- float SelectionLinesThickness
- Color SelectionLinesColor
- bool HasFadingItems
- bool IsCurved
Appearance of a wheel (a picker can have multiple wheels)
- string ItemWidths (width of each wheel, see ItemWidths chapter below)
- IList<GravityFlags> Gravities
- GravityFlags Gravity (shortcut for Gravities[0], used only when ItemWidths is set)
- IList
ItemHeights
Appearance of items inside a wheel
- IList
Alignments (same as gravities. Uses WheelItemAlign instead of GravityFlags) - WheelItemAlign ItemAlign (shortcut for ItemAligns[0])
- IList
ItemAligns
Selection
- ICommand SelectedItemIndexChangedCommand
- EventHandler<WheelChangedEventArgs> SelectedItemIndexChanged
- int SelectedItemIndex (shortcut for SelectedItemsIndex[0])
- IList<int> SelectedItemsIndex
Templating
- ItemsSimpleTemplates (currently reserved, used by the renderer)
SelectedItemsIndex
is a list of integers. Each integer represents the selected index within a wheel.
ItemWidths
: see chapter below
Alignments
or Gravities
is used to align a wheel inside the available WheelPicker's width, if it is larger than the width of the wheel.
ItemAligns
is used to align the items within a wheel.
Reference (net8-ios & Xamarin.iOS)
Click to expand
On iOS, this library utilizes the native UIPickerView along with a custom UIPickerViewModel to significantly simplify the use of this control.
Sample usage:
var picker = new UIPickerView {ShowSelectionIndicator = true, BackgroundColor = UIColor.White};
var pickerViewModel = new WheelPickerModel(picker);
picker.Model = pickerViewModel;
pickerViewModel.ItemsSource = new [] { "Monday", "Tuesday", "Wednesday" };
pickerViewModel.SelectedItemsIndex = new [] { 0 };
pickerViewModel.ItemAligns = new List<WheelItemAlign> { WheelItemAlign.Left };
Vapolia.WheelPickerIos.WheelPickerModel
Definition
- object ItemsSource (either IReadOnlyCollection<T> or IReadOnlyCollection<IReadOnlyCollection<T>>)
- IReadOnlyCollection<T> ItemsSourceSimple (shortcut for ItemsSourceMulti with one wheel)
- IReadOnlyCollection<IReadOnlyCollection<T>> ItemsSourceMulti
Appearance
- nfloat HorizontalSpaceBetweenWheels
Item appearance
- string ItemWidths
- UIFont ItemFont
- UIColor ItemTextColor
- IList
Alignments - IList
ItemAligns
Selection
- ICommand SelectedItemIndexChangedCommand
- int SelectedItemIndex (shortcut for SelectedItemsIndex[0])
- IEnumerable
SelectedItemsIndex
Templating
- ItemsSimpleTemplates (currently reserved, used by the renderer)
SelectedItemsIndex
is a list of integer. Each integer represents the selected index inside a wheel.
ItemWidths
: see chapter below
Alignments
is used to align a wheel inside the available WheelPicker's width, if it is larger than the wheel's width.
ItemAligns
is used to align the items inside a wheel.
ItemWidths (net8-android and net8-ios only, excluding Maui & Xamarn Forms)
Click to expand
ItemWidths
is used to choose the width of each wheel. It is a space separated string consisting of a combination of float numbers, stars (optionally prepended with a float number), or the "Auto" string.
The total width of the WheelPicker is distributed between the wheels by respecting either :
- float number: the exact width
- Auto: the width of the largest string in ItemsSource for a given wheel (if ItemsSource contains strings)
- star: the remaining space not assigned by the above rules, distributed among the other wheels using the optional float number as a weight
Examples of ItemWidths:
"*"
: one wheel having the full width of WheelPicker"* *"
: two wheels, each of the same width, exactly half of the width of the Wheel Picker"* * *"
: three wheels, each of the same width, exactly one third of the width of the Wheel Picker"100 2* *"
: three wheels, first has a100
device pixel width, second is twice the size of the third, and3*-100=width
of the WheelPicker, which resolves to*=WheelPickerWidth-100
"* Auto *"
: three wheels, the middle wheel's width is computed from the largest string in its items source (if items source contains strings).
Supported Platforms
- Maui, net8-iOS, net8-Android, Xamarin Forms
- Android api level 15+ (Android 4.0.3+)
- iOS 8+
Mvvm friendly
The Wheel Picker provides an event and a Command when the selection changes, making it easy to use with or without mvvm frameworks.
It also implements INotifyPropertyChanged
.
Live Preview
This control supports hot reload and live preview.
Commercial Support
Enterprise support is available: contact sales
Source code is available: contact sales
Licensing
Read all about licensing here This product is distributed through a nuget server and can be used in a continuous integration pipeline.Use the chat on this website to get the purchase link. Prepare the number of licenses you want, your business name (if any) and your country (for VAT).
Source code is available for purchase too.