Text fields

NumberBox

A numeric input with spin buttons and inline expression support.

Example

Usage

Drag to adjust a value

Drag the handle for a live preview. Shift makes fine changes; Escape restores the starting value.

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

auto* number = new NumberBox(this);
number->setObjectName("scrubNumber");
number->setAccessibleName("Rotation angle");
number->setHeader("Rotation angle");
number->setRange(-180, 180);
number->setValue(30);
number->setScrubbingEnabled(true);
number->setScrubSensitivity(0.5);
number->setDisplayPrecision(1);
number->setFixedWidth(260);

import fluentqt

number = fluentqt.NumberBox()
number.setObjectName("scrubNumber")
number.setAccessibleName("Rotation angle")
number.setHeader("Rotation angle")
number.setRange(-180, 180)
number.setValue(30)
number.setScrubbingEnabled(True)
number.setScrubSensitivity(0.5)
number.setDisplayPrecision(1)
number.setFixedWidth(260)

API

Declaration

`fluent::textfields::NumberBox`

Inherits LineEdit

Numeric LineEdit with value bounds, expression input, and spin buttons.

Constructors

explicit NumberBox(QWidget* parent = nullptr)

Properties

double value: Current numeric value committed by the input.
Read value()Write setValue()Notify valueChanged()
double minimum: Lower bound used to clamp typed and stepped values.
Read minimum()Write setMinimum()Notify minimumChanged()
double maximum: Upper bound used to clamp typed and stepped values.
Read maximum()Write setMaximum()Notify maximumChanged()
double smallChange: Increment used by one spin-button click or small keyboard step.
Read smallChange()Write setSmallChange()Notify smallChangeChanged()
double largeChange: Increment used by large-step keyboard actions.
Read largeChange()Write setLargeChange()Notify largeChangeChanged()
QString header: Optional label text displayed above the numeric input row.
Read header()Write setHeader()Notify headerChanged()
bool acceptsExpression: Whether typed arithmetic expressions are evaluated before commit.
Read acceptsExpression()Write setAcceptsExpression()Notify acceptsExpressionChanged()
SpinButtonPlacementMode spinButtonPlacementMode: Placement mode for hidden, compact, or inline spin buttons.
Read spinButtonPlacementMode()Write setSpinButtonPlacementMode()Notify spinButtonPlacementModeChanged()
QSize spinButtonSize: Size of external spin buttons.
Read spinButtonSize()Write setSpinButtonSize()Notify spinButtonSizeChanged()
QSize inlineSpinButtonSize: Size of inline spin buttons.
Read inlineSpinButtonSize()Write setInlineSpinButtonSize()Notify inlineSpinButtonSizeChanged()
int spinButtonRightMargin: Right-side inset reserved between inline spin buttons and the frame.
Read spinButtonRightMargin()Write setSpinButtonRightMargin()Notify spinButtonRightMarginChanged()
int compactSpinButtonReservedWidth: Width reserved for compact spin buttons inside the input surface.
Read compactSpinButtonReservedWidth()Write setCompactSpinButtonReservedWidth()Notify compactSpinButtonReservedWidthChanged()
int spinButtonSpacing: Spacing between adjacent spin buttons.
Read spinButtonSpacing()Write setSpinButtonSpacing()Notify spinButtonSpacingChanged()
int spinButtonTextGap: Gap between text content and inline spin-button chrome.
Read spinButtonTextGap()Write setSpinButtonTextGap()Notify spinButtonTextGapChanged()
int spinButtonIconSize: Icon glyph size used by spin-button chevrons.
Read spinButtonIconSize()Write setSpinButtonIconSize()Notify spinButtonIconSizeChanged()
int displayPrecision: Number of fractional digits used when formatting the value.
Read displayPrecision()Write setDisplayPrecision()Notify displayPrecisionChanged()
double formatStep: Step used to normalize display rounding after value changes.
Read formatStep()Write setFormatStep()Notify formatStepChanged()
bool scrubbingEnabled: Enables the separate horizontal drag handle; text selection stays unchanged.
Read isScrubbingEnabled()Write setScrubbingEnabled()Notify scrubbingEnabledChanged()
double scrubSensitivity: Value units per logical pixel; must be finite and positive.
Read scrubSensitivity()Write setScrubSensitivity()Notify scrubSensitivityChanged()
bool scrubbing: Whether a drag transaction is active.
Read isScrubbing()Notify scrubbingChanged()

Methods

double value() const: Current numeric value committed by the input.
void setValue(double value): Current numeric value committed by the input.
double minimum() const: Lower bound used to clamp typed and stepped values.
void setMinimum(double minimum): Lower bound used to clamp typed and stepped values.
double maximum() const: Upper bound used to clamp typed and stepped values.
void setMaximum(double maximum): Upper bound used to clamp typed and stepped values.
void setRange(double minimum, double maximum)
double smallChange() const: Increment used by one spin-button click or small keyboard step.
void setSmallChange(double change): Increment used by one spin-button click or small keyboard step.
double largeChange() const: Increment used by large-step keyboard actions.
void setLargeChange(double change): Increment used by large-step keyboard actions.
QString header() const: Optional label text displayed above the numeric input row.
void setHeader(const QString& header): Optional label text displayed above the numeric input row.
bool acceptsExpression() const: Whether typed arithmetic expressions are evaluated before commit.
void setAcceptsExpression(bool accepts): Whether typed arithmetic expressions are evaluated before commit.
SpinButtonPlacementMode spinButtonPlacementMode() const: Placement mode for hidden, compact, or inline spin buttons.
void setSpinButtonPlacementMode(SpinButtonPlacementMode mode): Placement mode for hidden, compact, or inline spin buttons.
QSize spinButtonSize() const: Size of external spin buttons.
void setSpinButtonSize(const QSize& size): Size of external spin buttons.
QSize inlineSpinButtonSize() const: Size of inline spin buttons.
void setInlineSpinButtonSize(const QSize& size): Size of inline spin buttons.
int spinButtonRightMargin() const: Right-side inset reserved between inline spin buttons and the frame.
void setSpinButtonRightMargin(int margin): Right-side inset reserved between inline spin buttons and the frame.
int compactSpinButtonReservedWidth() const: Width reserved for compact spin buttons inside the input surface.
void setCompactSpinButtonReservedWidth(int width): Width reserved for compact spin buttons inside the input surface.
int spinButtonSpacing() const: Spacing between adjacent spin buttons.
void setSpinButtonSpacing(int spacing): Spacing between adjacent spin buttons.
int spinButtonTextGap() const: Gap between text content and inline spin-button chrome.
void setSpinButtonTextGap(int gap): Gap between text content and inline spin-button chrome.
int spinButtonIconSize() const: Icon glyph size used by spin-button chevrons.
void setSpinButtonIconSize(int size): Icon glyph size used by spin-button chevrons.
int displayPrecision() const: Number of fractional digits used when formatting the value.
void setDisplayPrecision(int precision): Number of fractional digits used when formatting the value.
double formatStep() const: Step used to normalize display rounding after value changes.
void setFormatStep(double step): Step used to normalize display rounding after value changes.
bool isScrubbingEnabled() const: Enables the separate horizontal drag handle; text selection stays unchanged.
void setScrubbingEnabled(bool enabled): Enables the separate horizontal drag handle; text selection stays unchanged.
double scrubSensitivity() const: Value units per logical pixel; must be finite and positive.
void setScrubSensitivity(double sensitivity): Value units per logical pixel; must be finite and positive.
bool isScrubbing() const: Whether a drag transaction is active.
QRect scrubHandleRect() const: Logical handle geometry, empty while disabled.
void cancelScrub(): Rolls back an active drag, including an initially empty value.
void commitInput(): Commits current text using the numeric bounds and expression policy. Invalid input retains its text and sets value to NaN; unchanged formatted text preserves the original precision. No external model is modified.
QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override

Signals

void valueChanged(double value): Current numeric value committed by the input.
void minimumChanged(double minimum): Lower bound used to clamp typed and stepped values.
void maximumChanged(double maximum): Upper bound used to clamp typed and stepped values.
void smallChangeChanged(double change): Increment used by one spin-button click or small keyboard step.
void largeChangeChanged(double change): Increment used by large-step keyboard actions.
void headerChanged(): Optional label text displayed above the numeric input row.
void acceptsExpressionChanged(bool accepts): Whether typed arithmetic expressions are evaluated before commit.
void spinButtonPlacementModeChanged(SpinButtonPlacementMode mode): Placement mode for hidden, compact, or inline spin buttons.
void spinButtonSizeChanged(const QSize& size): Size of external spin buttons.
void inlineSpinButtonSizeChanged(const QSize& size): Size of inline spin buttons.
void spinButtonRightMarginChanged(int margin): Right-side inset reserved between inline spin buttons and the frame.
void compactSpinButtonReservedWidthChanged(int width): Width reserved for compact spin buttons inside the input surface.
void spinButtonSpacingChanged(int spacing): Spacing between adjacent spin buttons.
void spinButtonTextGapChanged(int gap): Gap between text content and inline spin-button chrome.
void spinButtonIconSizeChanged(int size): Icon glyph size used by spin-button chevrons.
void displayPrecisionChanged(int precision): Number of fractional digits used when formatting the value.
void formatStepChanged(double step): Step used to normalize display rounding after value changes.
void scrubbingEnabledChanged(bool enabled): Enables the separate horizontal drag handle; text selection stays unchanged.
void scrubSensitivityChanged(double sensitivity): Value units per logical pixel; must be finite and positive.
void scrubbingChanged(bool scrubbing): Whether a drag transaction is active.
void scrubStarted(double initialValue): One transaction starts; valueChanged still reports each live value.
void scrubFinished(double initialValue, double finalValue, bool canceled): Ends once; cancellation restores initialValue before this signal.

Enumerations

enum class SpinButtonPlacementMode: Hidden
Compact
Inline

Subclass interfaces

Methods

QRect trailingContentBounds() const override
void trailingContentGeometryChanged() override
bool event(QEvent* event) override
void paintEvent(QPaintEvent* event) override
void resizeEvent(QResizeEvent* event) override
void focusInEvent(QFocusEvent* event) override
void focusOutEvent(QFocusEvent* event) override
void enterEvent(FluentEnterEvent* event) override
void leaveEvent(QEvent* event) override
void mousePressEvent(QMouseEvent* event) override
void mouseMoveEvent(QMouseEvent* event) override
void mouseReleaseEvent(QMouseEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void changeEvent(QEvent* event) override
bool eventFilter(QObject* watched, QEvent* event) override
void paintFrame(QPainter& painter) 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