DOCSEARCHbyAlgolia
Submit Docs

MauiEx

repository·main·Indexed 42 days ago

https://github.com/dotmorten/mauiex

A collection of extended .NET MAUI controls providing additional UI functionality not present in the standard MAUI library, including the AutoSuggestBox control for providing user suggestions during text entry.

Tokens
1.7K
Snippets
6
Records
7
Agent score
3%

What's inside MauiEx

  1. How AutoSuggestBox works

    main

    The AutoSuggestBox is a text control that provides suggestions to users as they type. It is modeled after WinUI's AutoSuggestBox behavior but adapted for a native look on each platform (iOS, Android, etc.).

    To implement a functional search or suggestion experience, you must handle three primary user actions:

    1. Text changed: Triggered when the user enters text. You use this to update the ItemsSource with filtered data.
    2. Suggestion chosen: Triggered when a user selects an item from the list. You use this to update the text box with the selected item's value.
    3. Query submitted: Triggered when a user commits a query (e.g., pressing Enter or clicking the query icon). You use this to perform the final search or action.

    Key Properties

    • ItemsSource: The collection of data items to display in the suggestion list.
    • DisplayMemberPath: The name of the property on your data object to show in the suggestion list.
    • TextMemberPath: The name of the property on your data object to automatically populate into the text box when a suggestion is chosen. Usually, this should match DisplayMemberPath.
    <AutoSuggestBox 
    PlaceholderText="Search" 
    WidthRequest="200"
    TextChanged="AutoSuggestBox_TextChanged"
    QuerySubmitted="AutoSuggestBox_QuerySubmitted"
    SuggestionChosen="AutoSuggestBox_SuggestionChosen"/>

  2. Register MauiEx controls in MauiProgram

    main

    To enable the library's controls, you must call .UseMauiEx() on the MauiAppBuilder within your MauiProgram.CreateMauiApp method. Ensure you include the using MauiEx; namespace to access the extension method.

    using MauiEx; // Include using to get extension method

namespace SampleApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
          .UseMauiApp<App>()
          .ConfigureFonts(fonts =>
          {
              fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
              fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
          })
          .UseMauiEx(); // Register control library
        return builder.Build();
    }
}

  4. Handle AutoSuggestBox SuggestionChosen event

    main

    The SuggestionChosen event occurs when a user selects an item from the suggestion list.

    • If you have set TextMemberPath, the text box is updated automatically.
    • If you need to display custom text that isn't a simple property of the object, use the args.SelectedItem to manually populate sender.Text.
    private void AutoSuggestBox_SuggestionChosen(AutoSuggestBox sender, AutoSuggestBoxSuggestionChosenEventArgs args)
{
    // Set sender.Text. You can use args.SelectedItem to build your text string.
}

  5. Handle AutoSuggestBox QuerySubmitted event

    main

    The QuerySubmitted event occurs when a user commits a query. You can determine how the query was submitted by checking the ChosenSuggestion property in the event arguments:

    • If args.ChosenSuggestion is NOT null: The user selected a specific item from the suggestion list. You can take action based on that specific object.
    • If args.ChosenSuggestion IS null: The user committed the query directly (e.g., by pressing Enter while the focus was in the text box). Use args.QueryText to perform the search.

    In both cases, args.QueryText contains the current string in the text box.

    private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
{
    if (args.ChosenSuggestion != null)
    {
        // User selected an item from the suggestion list, take an action on it here.
    }
    else
    {
        // User hit Enter from the search box. Use args.QueryText to determine what to do.
    }
}

  6. Handle AutoSuggestBox TextChanged event

    main

    The TextChanged event occurs whenever the text box content changes. To avoid infinite loops or unnecessary processing when the text is updated programmatically (e.g., via TextMemberPath), check the Reason property of the event arguments.

    Only update the ItemsSource if args.Reason is AutoSuggestionBoxTextChangeReason.UserInput.

    private void AutoSuggestBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
{
    // Only get results when it was a user typing, 
    // otherwise assume the value got filled in by TextMemberPath 
    // or the handler for SuggestionChosen.
    if (args.Reason == AutoSuggestionBoxTextChangeReason.UserInput)
    {
        // Set the ItemsSource to your filtered dataset
        // sender.ItemsSource = dataset;
    }
}

  7. Use the AutoSuggestBox control

    main
    The AutoSuggestBox is a text control that provides suggestions to users as they type. The application is responsible for listening to text change notifications and providing the relevant list of suggestions for the control to display.