Skip to content

SearchComponent

Since 2.2.1

SearchComponent<T> is a generic search-and-select widget. It shows a preview of the currently selected value and, when clicked, opens a floating dialog with a text field and a list of matching candidates. Candidates are produced by an ISearchUI<T> implementation that can run on the client or be delegated to the server.

SearchComponent extends BindableUIElement<T>, so the selected value integrates with the data-binding system.

Everything documented on UIElement (layout, styles, events, data bindings, etc.) applies here too.

Usage

var search = new SearchComponent<String>();
search.setSearchUI(new SearchComponent.ISearchUI<>() {
    @Override
    public String resultText(String value) { return value; }
    @Override
    public void onResultSelected(String value) { }
    @Override
    public void search(String word, IResultHandler<String> find) {
        List.of("Alpha", "Beta", "Gamma").stream()
            .filter(s -> s.toLowerCase().contains(word.toLowerCase()))
            .forEach(find::handle);
    }
});
search.setOnValueChanged(v -> System.out.println("Selected: " + v));
parent.addChild(search);

searchComponent<String>({
    searchUI {
        resultText { it }
        onSelected { v -> println("Selected: $v") }
        search { word, find ->
            listOf("Alpha", "Beta", "Gamma")
                .filter { it.lowercase().contains(word.lowercase()) }
                .forEach(find::handle)
        }
    }
}) { }

let search = new SearchComponent();
// ISearchUI must be provided programmatically.
parent.addChild(search);

Internal Structure

CSS class Description
.__search-component_preview__ Preview area showing the selected value.
.__search-component_text-field__ Text input shown when the component is open.
.__search-component_dialog__ Floating overlay dialog containing the candidate list.
.__search-component_list-view__ Plain list (used when candidates ≤ max-item).
.__search-component_scroller-view__ Scrollable list (used when candidates > max-item).

Search Style

focus-overlay

Texture drawn over the component when it is hovered or focused.

Default: Sprites.RECT_RD_T_SOLID

search.searchStyle(style -> style.focusOverlay(myTexture));

search-component {
    focus-overlay: rect(#FFFFFF22, 2);
}

max-item

Maximum number of results shown in the flat listView before switching to a scrollerView.

Default: 5

search.searchStyle(style -> style.maxItemCount(10));

search-component {
    max-item: 10;
}

view-height

Height of the scrollerView when the candidate count exceeds max-item.

Default: 50

search.searchStyle(style -> style.scrollerViewHeight(80f));

search-component {
    view-height: 80;
}

show-overlay

Whether to highlight the hovered and selected candidate rows.

Default: true

search.searchStyle(style -> style.showOverlay(false));

search-component {
    show-overlay: false;
}

close-after-select

Whether the dialog closes automatically after a candidate is selected.

Default: true

search.searchStyle(style -> style.closeAfterSelect(false));

search-component {
    close-after-select: false;
}

ISearchUI<T> Interface

Implement this interface to provide search logic:

public interface ISearchUI<T> extends ISearch<T> {
    /** Convert a result value to its text representation. */
    String resultText(T value);

    /** Called when the user selects a candidate. */
    void onResultSelected(@Nullable T value);

    /** Perform the search; call find.handle(result) for each match. */
    void search(String word, IResultHandler<T> find);
}

Fields

Name Type Access Description
textField TextField public final The text input for entering search words.
preview UIElement public final Container showing the selected value's UI.
dialog UIElement public final The floating candidate dialog (attached to the root).
listView UIElement public final Flat list container (visible when ≤ max-item results).
scrollerView ScrollerView public final Scrollable list (visible when > max-item results).
searchStyle SearchStyle private (getter) Current style.
value T (nullable) private (getter) The currently selected value.
searchOnServer boolean private (getter) true when search is delegated to the server.

Methods

Method Returns Description
setSearchUI(ISearchUI<T>) SearchComponent<T> Sets the search logic provider.
setCandidateUIProvider(UIElementProvider<T>) SearchComponent<T> Sets the factory that builds the UI for each candidate.
setSearchOnServer(Class<T[]>) SearchComponent<T> Enables server-side search (RPC).
setSelected(T) SearchComponent<T> Selects a value and notifies listeners.
setSelected(T, boolean) SearchComponent<T> Selects a value; second param controls notification.
setOnValueChanged(Consumer<T>) SearchComponent<T> Registers a listener for value changes.
searchStyle(Consumer<SearchStyle>) SearchComponent<T> Configures style fluently.
show() void Opens the candidate dialog.
hide() void Closes the candidate dialog.
isOpen() boolean Returns true when the dialog is visible.