Text fields

TagInput

Choose several values as compact tags with asynchronous suggestions and native text input.

Example

Usage

Select and remove tags

Choose a suggestion, then remove its tag with the mouse or keyboard.

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

auto* input = new fluent::textfields::TagInput(this);
input->setAccessibleName("Technologies");
input->setPlaceholderText("Choose a technology");
input->setSuggestions({"Qt", "C++", "Python"});
input->addItem("Qt", "Qt");
input->setMaximumWidth(360);

import fluentqt

input = fluentqt.TagInput()
input.setAccessibleName("Technologies")
input.setObjectName("basicTagInput")
input.setPlaceholderText("Choose a technology")
input.setSuggestions(["Qt", "C++", "Python"])
input.addItem("Qt", "Qt")
input.setMaximumWidth(360)

API

Declaration

`fluent::textfields::TagInput`

Inherits AutoSuggestBox

Compact selected tags around AutoSuggestBox's native text editor.

Constructors

explicit TagInput(QWidget* parent = nullptr)

Properties

QVariantList selectedItems: Read selectedItems()Write setSelectedItems()Notify selectionChanged()
int selectedCount: Read selectedCount()Notify selectionChanged()

Methods

QVariantList selectedItems() const
int selectedCount() const
QStringList selectedKeys() const
QStringList selectedTexts() const
bool containsKey(const QString& key) const
void setSelectedItems(const QVariantList& items): Restores value snapshots; ignores malformed items and duplicate keys, preserving first occurrence.
bool addItem(const QString& key, const QString& text): Adds a value snapshot; returns false for empty or already-selected keys.
bool removeItem(const QString& key)
void clearSelection()
void onThemeUpdated() override

Signals

void selectionChanged()
void tokensSubmitted(const QStringList& tokens): Asks the application to resolve submitted text or delimited pasted values.

Destructors

~TagInput() override

Subclass interfaces

Methods

void trailingContentGeometryChanged() override
void resizeEvent(QResizeEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void inputMethodEvent(QInputMethodEvent* event) override
void changeEvent(QEvent* event) override
bool eventFilter(QObject* watched, QEvent* event) override
bool focusNextPrevChild(bool next) override

Inherited from fluent::textfields::AutoSuggestBox

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

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