Text fields

AutoSuggestBox

A search input with local or asynchronous suggestions, loading, pagination and retry.

Example

Usage

Suggestions and query submit

Suggestions, selection, and query submission are surfaced as separate signals.

#include <FluentQt/TextFields.h>
using namespace fluent::textfields;

auto* box = new AutoSuggestBox(this);
box->setHeader("Fruit");
box->setPlaceholderText("Type a fruit name");
box->setSuggestions({"Apple", "Apricot", "Banana", "Blueberry"});

connect(box, &AutoSuggestBox::textChangedWithReason,
        statusLabel, [statusLabel](const QString& text,
                        AutoSuggestBox::TextChangeReason reason) {
            statusLabel->setText(QStringLiteral("Text: %1, reason: %2")
                .arg(text, textChangeReasonName(reason)));
        });
connect(box, &AutoSuggestBox::suggestionChosen,
        statusLabel, [statusLabel](const QVariant& item) {
            statusLabel->setText(QStringLiteral("Chosen: %1").arg(item.toString()));
        });
connect(box, &AutoSuggestBox::querySubmitted,
        statusLabel, [statusLabel](const QString& query, const QVariant& chosen) {
            statusLabel->setText(QStringLiteral("Submitted: %1 (%2)")
                .arg(query, chosen.toString()));
        });

import fluentqt

box = fluentqt.AutoSuggestBox()
box.setHeader('Fruit')
box.setPlaceholderText('Type a fruit name')
box.setSuggestions(
    [
    "Apple",
    "Apricot",
    "Banana",
    "Blueberry",
    "Cherry",
    "Grape",
    "Orange",
    "Strawberry",
    ]
)
def reason_name(reason):
    name = reason.name
    return name.decode('ascii') if isinstance(name, bytes) else str(name)
box.textChangedWithReason.connect(
    lambda text, reason: status.setText(
        f"Text: {text}, reason: {reason_name(reason)}"
    )
)
box.suggestionChosen.connect(lambda item: status.setText(f'Chosen: {item}'))
box.querySubmitted.connect(
    lambda query, chosen: status.setText(f"Submitted: {query} ({chosen})")
)

API

Declaration

`fluent::textfields::AutoSuggestBox`

Inherits LineEdit

LineEdit-based input box with query affordance and suggestion flyout.

Constructors

explicit AutoSuggestBox(QWidget* parent = nullptr)

Properties

QStringList suggestions: Suggestion strings displayed by the suggestion popup.
Read suggestions()Write setSuggestions()Notify suggestionsChanged()
QString header: Optional label text displayed above the input row.
Read header()Write setHeader()Notify headerChanged()
QString queryIconGlyph: Icon glyph used by the query/search affordance.
Read queryIconGlyph()Write setQueryIconGlyph()Notify queryIconGlyphChanged()
bool queryIconVisible: Whether the query icon is visible.
Read isQueryIconVisible()Write setQueryIconVisible()Notify queryIconVisibleChanged()
bool clearButtonEnabled: Controls the inline clear action independently of the query button.
Read isClearButtonEnabled()Write setClearButtonEnabled()Notify clearButtonEnabledChanged()
QueryButtonPlacement queryButtonPlacement: Placement of the query action button.
Read queryButtonPlacement()Write setQueryButtonPlacement()Notify queryButtonPlacementChanged()
int inputHeight: Preferred height of the input surface.
Read inputHeight()Write setInputHeight()Notify inputHeightChanged()
int queryButtonSize: Size of the query action button.
Read queryButtonSize()Write setQueryButtonSize()Notify queryButtonSizeChanged()
int clearButtonSize: Size of the clear button.
Read clearButtonSize()Write setClearButtonSize()Notify clearButtonSizeChanged()
Typography::FontRole suggestionFontRole: Typography role used by suggestion rows.
Read suggestionFontRole()Write setSuggestionFontRole()Notify suggestionFontRoleChanged()
int suggestionItemHeight: Height of each suggestion row.
Read suggestionItemHeight()Write setSuggestionItemHeight()Notify suggestionItemHeightChanged()
bool isSuggestionListOpen: Whether the suggestion popup is open.
Read isSuggestionListOpen()Notify suggestionListOpenChanged()
QAbstractItemModel* suggestionModel: Read suggestionModel()Write setSuggestionModel()Notify suggestionModelChanged()
int suggestionCount: Read suggestionCount()Notify suggestionCountChanged()
bool asyncSuggestionsEnabled: Read isAsyncSuggestionsEnabled()Write setAsyncSuggestionsEnabled()Notify asyncSuggestionsEnabledChanged()
int debounceInterval: Read debounceInterval()Write setDebounceInterval()Notify debounceIntervalChanged()
LoadState loadState: Read loadState()Notify loadStateChanged()
bool hasMoreSuggestions: Read hasMoreSuggestions()Notify hasMoreSuggestionsChanged()
QString loadingText: Read loadingText()Write setLoadingText()Notify loadingTextChanged()
QString emptyText: Read emptyText()Write setEmptyText()Notify emptyTextChanged()
QString emptyDescription: Read emptyDescription()Write setEmptyDescription()Notify emptyDescriptionChanged()
QString loadingMoreText: Text shown while another result page is loading.
Read loadingMoreText()Write setLoadingMoreText()Notify loadingMoreTextChanged()
QString moreResultsText: Text accompanying the action for another result page.
Read moreResultsText()Write setMoreResultsText()Notify moreResultsTextChanged()
QString retryText: Caption of the retry action after a failed request.
Read retryText()Write setRetryText()Notify retryTextChanged()
QString loadMoreText: Caption of the action that requests another result page.
Read loadMoreText()Write setLoadMoreText()Notify loadMoreTextChanged()

Methods

QStringList suggestions() const: Suggestion strings displayed by the suggestion popup.
QString header() const: Optional label text displayed above the input row.
QString queryIconGlyph() const: Icon glyph used by the query/search affordance.
bool isQueryIconVisible() const: Whether the query icon is visible.
bool isClearButtonEnabled() const: Controls the inline clear action independently of the query button.
void setClearButtonEnabled(bool enabled): Controls the inline clear action independently of the query button.
QueryButtonPlacement queryButtonPlacement() const: Placement of the query action button.
int inputHeight() const: Preferred height of the input surface.
int queryButtonSize() const: Size of the query action button.
int clearButtonSize() const: Size of the clear button.
Typography::FontRole suggestionFontRole() const: Typography role used by suggestion rows.
int suggestionItemHeight() const: Height of each suggestion row.
bool isSuggestionListOpen() const: Whether the suggestion popup is open.
void setSuggestionModel(QAbstractItemModel* model): Borrows a flat model using column zero, DisplayRole and optional UserRole payloads.
QAbstractItemModel* suggestionModel() const
int suggestionCount() const
bool isAsyncSuggestionsEnabled() const
void setAsyncSuggestionsEnabled(bool enabled)
int debounceInterval() const
void setDebounceInterval(int milliseconds)
LoadState loadState() const
bool hasMoreSuggestions() const
QString loadingText() const
void setLoadingText(const QString& text)
QString emptyText() const
void setEmptyText(const QString& text)
QString emptyDescription() const
void setEmptyDescription(const QString& text)
QString loadingMoreText() const: Text shown while another result page is loading.
void setLoadingMoreText(const QString& text): Text shown while another result page is loading.
QString moreResultsText() const: Text accompanying the action for another result page.
void setMoreResultsText(const QString& text): Text accompanying the action for another result page.
QString retryText() const: Caption of the retry action after a failed request.
void setRetryText(const QString& text): Caption of the retry action after a failed request.
QString loadMoreText() const: Caption of the action that requests another result page.
void setLoadMoreText(const QString& text): Caption of the action that requests another result page.
bool isSuggestionRequestCurrent(quint64 requestId) const: Tests a request token before the application changes its borrowed model.
bool completeSuggestionRequest(quint64 requestId, bool hasMore = false): Finishes a current request after guarded application model updates.
bool setSuggestionsForRequest(quint64 requestId, const QStringList& suggestions, bool hasMore = false): Accepts current string results, appending only for a load-more request.
bool failSuggestionRequest(quint64 requestId, const QString& message, const QString& details = QString()): Shows a current request failure; pagination failures retain existing rows.
void setHeader(const QString& header): Optional label text displayed above the input row.
void setQueryIconGlyph(const QString& glyph): Icon glyph used by the query/search affordance.
void setQueryIconVisible(bool visible): Whether the query icon is visible.
void setQueryButtonPlacement(QueryButtonPlacement placement): Placement of the query action button.
void setInputHeight(int height): Preferred height of the input surface.
void setQueryButtonSize(int size): Size of the query action button.
void setClearButtonSize(int size): Size of the clear button.
void setSuggestionFontRole(Typography::FontRole role): Typography role used by suggestion rows.
void setSuggestionItemHeight(int height): Height of each suggestion row.
QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override
void setSuggestions(const QStringList& suggestions): Suggestion strings displayed by the suggestion popup.
void clearSuggestions()
void requestSuggestions(): Immediately requests the current query when asynchronous suggestions are enabled.
void loadMoreSuggestions()
void retrySuggestions()
void cancelSuggestions()

Signals

void textChangedWithReason(const QString& text, AutoSuggestBox::TextChangeReason reason)
void suggestionChosen(const QVariant& item)
void querySubmitted(const QString& queryText, const QVariant& chosenSuggestion)
void suggestionsChanged(): Suggestion strings displayed by the suggestion popup.
void headerChanged(): Optional label text displayed above the input row.
void queryIconGlyphChanged(): Icon glyph used by the query/search affordance.
void queryIconVisibleChanged(): Whether the query icon is visible.
void queryButtonPlacementChanged(): Placement of the query action button.
void inputHeightChanged(): Preferred height of the input surface.
void queryButtonSizeChanged(): Size of the query action button.
void suggestionFontRoleChanged(): Typography role used by suggestion rows.
void suggestionItemHeightChanged(): Height of each suggestion row.
void suggestionListOpenChanged(bool open): Whether the suggestion popup is open.
void suggestionModelChanged(QAbstractItemModel* model)
void suggestionCountChanged(int count)
void asyncSuggestionsEnabledChanged(bool enabled)
void debounceIntervalChanged(int milliseconds)
void loadStateChanged(LoadState state)
void hasMoreSuggestionsChanged(bool hasMore)
void loadingTextChanged()
void emptyTextChanged()
void emptyDescriptionChanged()
void loadingMoreTextChanged(): Text shown while another result page is loading.
void moreResultsTextChanged(): Text accompanying the action for another result page.
void retryTextChanged(): Caption of the retry action after a failed request.
void loadMoreTextChanged(): Caption of the action that requests another result page.
void suggestionsRequested(const QString& query, quint64 requestId, bool append): Requests application data; append is true only for pagination or its retry.
void suggestionRequestCanceled(quint64 requestId): Asks the application to cancel transport work for an invalidated token.

Enumerations

enum class TextChangeReason: UserInput
ProgrammaticChange
SuggestionChosen
enum class QueryButtonPlacement: Right
Left
Leading
Trailing
enum class LoadState: State of the current asynchronous query; Ready may contain no rows.
Idle
Loading
Ready
Failed

Destructors

~AutoSuggestBox() override

Subclass interfaces

Methods

QRect trailingContentBounds() const override
void trailingContentGeometryChanged() override
::fluent::basicinput::Button* clearActionButton() const override
void setQueryIconDecorative(bool decorative): Composed selectors keep the query slot as decoration and own one input target.
void paintEvent(QPaintEvent* event) override
void resizeEvent(QResizeEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void inputMethodEvent(QInputMethodEvent* event) override
bool isInputMethodComposing() const
void focusInEvent(QFocusEvent* event) override
void focusOutEvent(QFocusEvent* event) override
void moveEvent(QMoveEvent* event) override
void enterEvent(FluentEnterEvent* event) override
void leaveEvent(QEvent* event) override
void changeEvent(QEvent* event) override
void hideEvent(QHideEvent* event) override
bool focusNextPrevChild(bool next) override

Inherited from fluent::textfields::LineEdit

Properties

QMargins contentMargins: Content margins whose horizontal values include Qt's internal text inset.
Read contentMargins()Write setContentMargins()Notify contentMarginsChanged()
Typography::FontRole fontRole: Fluent typography role used for text rendering.
Read fontRole()Write setFontRole()Notify fontRoleChanged()
bool clearButtonEnabled: Whether the trailing clear button is enabled.
Read isClearButtonEnabled()Write setClearButtonEnabled()Notify clearButtonEnabledChanged()
int clearButtonSize: Size of the clear button, defaulting to 24 logical pixels.
Read clearButtonSize()Write setClearButtonSize()Notify clearButtonSizeChanged()
QPoint clearButtonOffset: Pixel offset applied to the clear button.
Read clearButtonOffset()Write setClearButtonOffset()Notify clearButtonOffsetChanged()
int focusedBorderWidth: Bottom border width while focused.
Read focusedBorderWidth()Write setFocusedBorderWidth()Notify focusedBorderWidthChanged()
int unfocusedBorderWidth: Bottom border width while not focused.
Read unfocusedBorderWidth()Write setUnfocusedBorderWidth()Notify unfocusedBorderWidthChanged()
bool frameVisible: Whether LineEdit paints its input frame and focus underline.
Read isFrameVisible()Write setFrameVisible()Notify frameVisibleChanged()
QString trailingText: Read trailingText()Write setTrailingText()Notify trailingTextChanged()
QWidget* trailingWidget: Read trailingWidget()Notify trailingWidgetChanged()
fluent::WidgetOwnership trailingWidgetOwnership: Read trailingWidgetOwnership()Notify trailingWidgetOwnershipChanged()
QString clearButtonAccessibleName: Read clearButtonAccessibleName()Write setClearButtonAccessibleName()Notify clearButtonAccessibleNameChanged()
Qt::FocusPolicy clearButtonFocusPolicy: Read clearButtonFocusPolicy()Write setClearButtonFocusPolicy()Notify clearButtonFocusPolicyChanged()

Methods

QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override
QMargins contentMargins() const: Content margins whose horizontal values include Qt's internal text inset.
void setContentMargins(const QMargins& margins): Content margins whose horizontal values include Qt's internal text inset.
Typography::FontRole fontRole() const: Fluent typography role used for text rendering.
void setFontRole(Typography::FontRole role): Fluent typography role used for text rendering.
bool isClearButtonEnabled() const: Whether the trailing clear button is enabled.
void setClearButtonEnabled(bool enabled): Whether the trailing clear button is enabled.
int clearButtonSize() const: Size of the clear button, defaulting to 24 logical pixels.
void setClearButtonSize(int size): Size of the clear button, defaulting to 24 logical pixels.
QPoint clearButtonOffset() const: Pixel offset applied to the clear button.
void setClearButtonOffset(const QPoint& offset): Pixel offset applied to the clear button.
int focusedBorderWidth() const: Bottom border width while focused.
void setFocusedBorderWidth(int width): Bottom border width while focused.
int unfocusedBorderWidth() const: Bottom border width while not focused.
void setUnfocusedBorderWidth(int width): Bottom border width while not focused.
bool isFrameVisible() const: Whether LineEdit paints its input frame and focus underline.
void setFrameVisible(bool visible): Whether LineEdit paints its input frame and focus underline.
QString trailingText() const
void setTrailingText(const QString& text): Displays a plain-text suffix without changing the editable value; replaces hosted content.
QWidget* trailingWidget() const
WidgetOwnership trailingWidgetOwnership() const
bool setTrailingWidget(QWidget* widget, WidgetOwnership ownership): Hosts one trailing widget using explicit ownership; rejects the host and its ancestors.
QWidget* takeTrailingWidget(): Detaches the custom trailing widget and transfers it to the caller.
void releaseTrailingWidget(): Releases custom trailing content according to its recorded ownership policy.
QString clearButtonAccessibleName() const
void setClearButtonAccessibleName(const QString& name)
Qt::FocusPolicy clearButtonFocusPolicy() const
void setClearButtonFocusPolicy(Qt::FocusPolicy policy)

Signals

void contentMarginsChanged(): Content margins whose horizontal values include Qt's internal text inset.
void fontRoleChanged(): Fluent typography role used for text rendering.
void clearButtonEnabledChanged(): Whether the trailing clear button is enabled.
void clearButtonSizeChanged(): Size of the clear button, defaulting to 24 logical pixels.
void clearButtonOffsetChanged(): Pixel offset applied to the clear button.
void focusedBorderWidthChanged(): Bottom border width while focused.
void unfocusedBorderWidthChanged(): Bottom border width while not focused.
void frameVisibleChanged(): Whether LineEdit paints its input frame and focus underline.
void trailingTextChanged()
void trailingWidgetChanged()
void trailingWidgetOwnershipChanged()
void clearButtonAccessibleNameChanged()
void clearButtonFocusPolicyChanged()

Inherited from fluent::FluentElement

Methods

static void setTheme(Theme theme): Updates the global theme and notifies active FluentElement instances.
static void setThemeDeferred(Theme theme): Schedules a visible-first batched theme refresh without blocking the current interaction.
static Theme currentTheme(): Returns the currently active global theme.
static bool themeUsesDarkAppearance(Theme theme): Returns whether a theme uses dark-backed chrome and material tokens.
static void refreshTheme(): Re-broadcasts the current theme to repaint after a design-token change.
static int themeGeneration(): Monotonic counter bumped on every theme change, for staleness checks.
Theme effectiveTheme() const: Resolves the theme used by this element, honoring an inherited QWidget override.
bool effectiveThemeUsesDarkAppearance() const: Returns whether this element's effective theme uses dark-backed chrome.
bool setThemeOverrides(const QJsonObject& overrides): Component-facing token accessors.
QJsonObject themeOverrides() const: Returns this element's authored overrides.
void clearThemeOverrides(): Restores all token fields to global theme defaults.
Colors themeColors() const
const Colors& themeColorsRef() const: Non-copying access to the active color set (for hot paint paths).
FontStyle themeFont(Typography::FontRole role = Typography::FontRole::Body) const
Radius themeRadius() const
Spacing themeSpacing() const
Animation themeAnimation() const
Material::AcrylicToken themeAcrylic() const: Material, elevation, and adaptive layout tokens.
Material::MicaToken themeMica() const
Material::SmokeToken themeSmoke() const
Elevation::ShadowParams themeShadow(Elevation::Level level) const
int themeBreakpoint(Breakpoints::Breakpoint breakpoint = Breakpoints::Breakpoint::Medium) const
QColor themeBackdrop(bool active) const: Window-chrome backdrop color for the given activation state.
virtual void onThemeUpdated(): Called after the global theme changes.

Enumerations

enum Theme: Global visual theme used when resolving design tokens.
Light = 0
Dark = 1
HighContrast = 2

Types and aliases

struct Colors: Design token snapshots returned to components.
struct FontStyle
struct Radius
struct Spacing
struct Animation

Inherited from fluent::QMLPlus

Methods

AnchorLayout::Anchors* anchors(): Returns mutable anchors for the QWidget host.
void setState(const QString& name): Applies a named state, or clears state when name is empty.
QString state() const
void addState(const QMLState& state): Registers or replaces a named state definition.
void evaluateStates(): Reevaluates conditions; the first registered true condition wins.
QMLPlusRuntime* runtime(): Returns the lazy host-owned state observation object.
void setAnchors(const AnchorLayout::Anchors& anchors): Replaces all host anchors and invalidates the parent layout.
void resetAnchors(): Clears all host anchors and invalidates the parent layout.
void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay): Binds a source property to a property on the QWidget host.
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {}): Installs a managed direct binding on this QWidget host.
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {}): Installs an explicit-dependency C++ expression on this QWidget host.
void addTransition(const StateTransition& transition): Registers a state transition in precedence order.
void setBehavior(const char* propertyName, const PropertyAnimation& animation): Sets the default animation for this host's managed property writes.
void clearBehavior(const char* propertyName): Removes the default animation for future managed writes.
bool writeProperty(const char* propertyName, const QVariant& value): Writes a host property through Behavior without removing its binding.

All inherited Qt members：QLineEdit