Aquila.ComboBox.F10 1.0.2

Aquila.ComboBox User Guide

Library: Aquila.ComboBox Control: AquilaComboBox Author: Aswin Sadhasivam Company: Aquila Innovations

Table of Contents

1. Introduction

2. Installation

3. Basic Usage

   • XAML
   • C#

4. Core Features

   • SelectedIndex / SelectedItem / SelectedText
   • ItemsSource / ObservableCollection
   • Placeholder
   • MaxDropDownHeight
   • Tap outside to close

5. Styling & Appearance

   • BorderColor
   • BackgroundColor
   • Font, TextColor, CornerRadius

6. Search Functionality

   • IsSearchEnabled
   • Filtering behavior

7. Animations

   • Open/Close smooth animation

8. Events

   • SelectionChanged

9. MVVM Binding

10. Advanced Tips

11. Sample Full Implementation

12. Troubleshooting

1. Introduction

Aquila.ComboBox is a cross-platform MAUI ComboBox control designed to work seamlessly on Android, iOS, Windows, Mac Catalyst. It is:

• Lightweight, reusable, and MVVM-friendly
• Supports search, animations, and touch-safe overlays
• Fully customizable through BindableProperties

2. Installation

Install via NuGet:

dotnet add package Aquila.ComboBox --version 1.0.0

Or via Visual Studio:

• Right-click Dependencies → Manage NuGet Packages → Search Aquila.ComboBox → Install

3. Basic Usage

3.1 XAML

<ContentPage xmlns:aquila="clr-namespace:Aquila.UiTools.Controls;assembly=Aquila.UiTools">
    <StackLayout Padding="20">
        <aquila:AquilaComboBox
            x:Name="Combo"
            Placeholder="Select fruit"
            IsSearchEnabled="True"
            BorderColor="DarkGray"
            MaxDropDownHeight="250"/>
    </StackLayout>
</ContentPage>

3.2 C#

Combo.ItemsSource = new ObservableCollection<AquilaComboItem>
{
    new() { Id = 1, Text = "Apple" },
    new() { Id = 2, Text = "Banana" },
    new() { Id = 3, Text = "Mango" },
    new() { Id = 4, Text = "Orange" }
};

4. Core Features

5. Styling & Appearance

Bindable Properties for Styling

Example:

<aquila:AquilaComboBox
    BorderColor="Blue"
    BackgroundColor="LightYellow"
    Placeholder="Choose an item"
    MaxDropDownHeight="300"/>

6. Search Functionality

• Enable search via IsSearchEnabled="True"
• Typing filters items in real-time, case-insensitive
• Clears filter if search box is empty

<aquila:AquilaComboBox
    IsSearchEnabled="True"
    Placeholder="Search fruits"/>

C# Filtering Behavior:

// Typing in SearchBox automatically filters the list

7. Animations

• Open animation: fades in + scales from 85% → 100%
• Close animation: fades out + scales 100% → 85%
• Smooth transitions enhance UX and prevent click-through bugs

No extra setup required; handled internally.

8. Events

SelectionChanged Event

Subscribe in XAML:

<aquila:AquilaComboBox SelectionChanged="Combo_SelectionChanged"/>

Or C#:

Combo.SelectionChanged += Combo_SelectionChanged;

Event Handler Example

private async void Combo_SelectionChanged(object sender, EventArgs e)
{
    var combo = (AquilaComboBox)sender;
    var selected = combo.SelectedItem as AquilaComboItem;

    await DisplayAlert("Selected",
        $"Id: {selected.Id}\nText: {selected.Text}\nIndex: {combo.SelectedIndex}",
        "OK");
}

9. MVVM Binding

Supports two-way binding with SelectedItem and SelectedIndex.

public class MainViewModel : INotifyPropertyChanged
{
    public ObservableCollection<AquilaComboItem> Fruits { get; set; }
    private AquilaComboItem _selectedFruit;
    public AquilaComboItem SelectedFruit
    {
        get => _selectedFruit;
        set { _selectedFruit = value; OnPropertyChanged(); }
    }

    public MainViewModel()
    {
        Fruits = new ObservableCollection<AquilaComboItem>
        {
            new() { Id = 1, Text = "Apple" },
            new() { Id = 2, Text = "Banana" }
        };
    }
}

<aquila:AquilaComboBox
    ItemsSource="{Binding Fruits}"
    SelectedItem="{Binding SelectedFruit, Mode=TwoWay}"
    Placeholder="Pick a fruit"/>

10. Advanced Tips

• Overlay Layer: Prevents accidental clicks behind dropdown
• Safe Open Delay: Ensures animation works correctly across platforms
• ObservableCollection: Auto-refreshes UI when items are added/removed
• MaxDropDownHeight: Useful for small screens to prevent overflow
• Search: Always restores full dataset after clearing search

11. Full Example

<StackLayout Padding="20">
    <aquila:AquilaComboBox
        x:Name="Combo"
        Placeholder="Select fruit"
        BorderColor="DarkBlue"
        MaxDropDownHeight="250"
        IsSearchEnabled="True"
        SelectionChanged="Combo_SelectionChanged"/>
</StackLayout>

Combo.ItemsSource = new ObservableCollection<AquilaComboItem>
{
    new() { Id=1, Text="Apple" },
    new() { Id=2, Text="Banana" },
    new() { Id=3, Text="Mango" }
};

private async void Combo_SelectionChanged(object sender, EventArgs e)
{
    var combo = (AquilaComboBox)sender;
    var item = combo.SelectedItem as AquilaComboItem;

    await DisplayAlert("Selected", $"Id: {item.Id}\nText: {item.Text}", "OK");
}

12. Troubleshooting