Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ui

Source of release 0.19.4

0.19.4 / src / widgets / number_field.lucb

## The NumberField widget and the number formatting it uses.
from luce_gpu import gpu
import interop
from luce_std import math
import ownership
import strings
import layout
import result
from layout import Widget, Layout, Size, Constraints, Event
from painter import Painter
from text.line_input import LineInput
from luce_window import input
from font import Font, selected_font
import measures
from measures import Unit
import widgets.parameter_text

## A number field after eleusis's scrubber: drag horizontally to change the value
## (a step per two pixels; Shift ten times as fast), click without dragging to
## type it, Enter commits, Escape cancels, arrows step when focused, and a
## cmd/ctrl-click puts the default back. The value is clamped to
## `minimum..maximum`, snapped to `step` and shown with `decimals` places and an
## optional `suffix`. `on_change` fires on every change; `on_begin`/`on_end`
## bracket one drag so a caller can make it a single undo step. With an
## `on_submit` listener, Enter on a field not being typed in submits instead of
## starting to type: the first Enter commits a typed value, the second submits,
## as Photoshop's option bar applies a transform. `edit` opens the field ready
## to type, as Fusion's heads-up value box: there one Enter commits and submits,
## and Escape throws the text away and calls `on_cancel`.
##
## With `units` (see measures.Unit), the value, bounds, step and decimals stay
## in the stored unit and the field shows them in those units, the unit's suffix
## after the number: the step rounded to 1, 2 or 5 there, the decimals as many
## more as the unit is larger. What is typed may carry any length unit ("1 in",
## "2.5cm", "10 + 5 mm", arithmetic as a parameter panel reads it).
pub struct NumberField: Widget:
    let box: interop.Reference[Layout]
    let font: interop.Reference[Font]
    var input: LineInput
    var suffix: interop.Owned[str]
    ## The unit shown, its suffix kept in `suffix`.
    var shown_in: Unit
    var minimum: f64
    var maximum: f64
    var step: f64
    var decimals: i64
    var fallback: f64
    var current: f64
    var cells: f64
    var editing: bool
    var pressed: bool
    var scrubbing: bool
    var press_x: f64
    var press_value: f64
    let changed: interop.Signal[f64]
    let began: interop.Signal[unit]
    let ended: interop.Signal[unit]
    let submitted: interop.Signal[unit]
    let cancelled: interop.Signal[unit]
    var submits: bool
    ## Typing began with `edit`: Enter submits as well as commits.
    var one_shot: bool

    pub func init(value: f64 = 0.0, minimum: f64 = -1.0e9, maximum: f64 = 1.0e9, step: f64 = 1.0, decimals: i64 = 0,
                  suffix: str = "", font: interop.Reference[Font]? = none, cells: f64 = 7.0, units: Unit = Unit()) -> !:
        if not math.is_finite(minimum) or not math.is_finite(maximum) or maximum <= minimum or not math.is_finite(value) or not math.is_finite(step) or step < 0.0:
            error(result.invalid, "a number field needs finite bounds with maximum above minimum, a finite value and a nonnegative step")
        if decimals < 0 or decimals > 9:
            error(result.invalid, "number field decimals must be 0..9")
        if not measures.valid(units):
            error(result.invalid, "a unit needs a finite, positive scale and nonnegative lengths")
        var selected = try selected_font(font)
        errdefer selected.release()
        let box = try layout.make_layout()
        errdefer box.release()
        try box.value().set_shrink(vertical = 0.0)
        box.value().set_focusable(true)
        box.value().set_text_input(true)
        box.value().set_cursor(input.Cursor.resize_horizontal)
        var line = try LineInput()
        errdefer line.close()
        let changed = try interop.Signal[f64]()
        errdefer changed.release()
        let began = try interop.Signal[unit]()
        errdefer began.release()
        let ended = try interop.Signal[unit]()
        errdefer ended.release()
        let submitted = try interop.Signal[unit]()
        errdefer submitted.release()
        let cancelled = try interop.Signal[unit]()
        errdefer cancelled.release()
        self.suffix = try interop.copy_text(units.suffix if units.suffix.length > 0 else suffix)
        self.shown_in = Unit(scale = units.scale, millimeter = units.millimeter, pixel = units.pixel)
        self.box = box
        self.font = selected
        self.input = line
        self.minimum = minimum
        self.maximum = maximum
        self.step = step
        self.decimals = decimals
        let clamped = math.clamp(value, minimum, maximum)
        self.fallback = clamped
        self.current = clamped
        self.cells = math.clamp(cells, 3.0, 40.0)
        self.editing = false
        self.pressed = false
        self.scrubbing = false
        self.press_x = 0.0
        self.press_value = 0.0
        self.changed = changed
        self.began = began
        self.ended = ended
        self.submitted = submitted
        self.cancelled = cancelled
        self.submits = false
        self.one_shot = false

    pub func layout() -> interop.Reference[Layout]:
        return self.box.clone()

    pub func value() -> f64:
        return self.current

    ## Set the value from code, clamped and kept to the shown decimals; no signal.
    pub func set_value(value: f64) -> !:
        if not math.is_finite(value):
            error(result.invalid, "number field values must be finite")
        self.current = self.precise(value)
        self.editing = false
        self.box.value().invalidate()

    ## What a cmd/ctrl-click puts back.
    pub func set_default(value: f64) -> !:
        if not math.is_finite(value):
            error(result.invalid, "number field defaults must be finite")
        self.fallback = self.snap(value)

    ## Show `decimals` places (0..9) from now on, including CAD tolerances.
    pub func set_decimals(decimals: i64) -> !:
        if decimals < 0 or decimals > 9:
            error(result.invalid, "number field decimals must be 0..9")
        self.decimals = decimals
        self.box.value().invalidate()

    ## Snap to multiples of `step` from the minimum (0 turns snapping off).
    pub func set_step(step: f64) -> !:
        if not math.is_finite(step) or step < 0.0:
            error(result.invalid, "a number field step must be finite and nonnegative")
        self.step = step
        self.current = self.snap(self.current)
        self.box.value().invalidate()

    ## Show and read the value in `units` from now on (its suffix replacing the
    ## field's); the stored value stays as it is. `Unit()` shows it as stored.
    pub func set_units(units: Unit) -> !:
        if not measures.valid(units):
            error(result.invalid, "a unit needs a finite, positive scale and nonnegative lengths")
        try self.set_suffix(units.suffix)
        self.shown_in = Unit(scale = units.scale, millimeter = units.millimeter, pixel = units.pixel)
        self.editing = false

    ## The unit the field shows, as `set_units` took it.
    pub func shown_units() -> Unit:
        var shown = self.shown_in
        shown.suffix = self.suffix.value
        return shown

    ## The value in the shown unit, rounded to the decimals the field shows.
    pub func shown_value() -> f64:
        let decimals = measures.shown_decimals(self.decimals, self.shown_in)
        let scale = math.pow(10.0, (f64)decimals)
        return math.floor(self.shown_in.shown(self.current) * scale + 0.5) / scale

    ## The unit shown after the value, muted.
    pub func set_suffix(suffix: str) -> !:
        let replacement = try interop.copy_text(suffix)
        let previous_suffix = self.suffix
        self.suffix = replacement
        previous_suffix.release()
        self.box.value().invalidate()

    ## Change the bounds and re-clamp and re-snap the value; no signal.
    pub func set_range(minimum: f64, maximum: f64) -> !:
        if not math.is_finite(minimum) or not math.is_finite(maximum) or maximum <= minimum:
            error(result.invalid, "a number field needs finite bounds with maximum above minimum")
        self.minimum = minimum
        self.maximum = maximum
        self.current = self.snap(self.current)
        self.box.value().invalidate()

    ## Called with the new value after each user change: a scrub step, an arrow
    ## key, a committed edit or a cmd/ctrl-click reset. `set_value` does not call it.
    pub func on_change(callback: interop.Callback[f64, unit]) -> interop.Reference[interop.Connection]!:
        return try self.changed.connect(callback)

    ## Called when a drag starts scrubbing, before its first change.
    pub func on_begin(callback: interop.Callback[unit, unit]) -> interop.Reference[interop.Connection]!:
        return try self.began.connect(callback)

    ## Called when a scrub ends, on release or cancellation.
    pub func on_end(callback: interop.Callback[unit, unit]) -> interop.Reference[interop.Connection]!:
        return try self.ended.connect(callback)

    ## Enter pressed while the field is focused but not being typed in, or
    ## while typing that `edit` began.
    pub func on_submit(callback: interop.Callback[unit, unit]) -> interop.Reference[interop.Connection]!:
        self.submits = true
        return try self.submitted.connect(callback)

    ## Escape pressed while typing: the typed text was thrown away.
    pub func on_cancel(callback: interop.Callback[unit, unit]) -> interop.Reference[interop.Connection]!:
        return try self.cancelled.connect(callback)

    ## Take focus and start typing with the whole shown value selected, so the
    ## first keystroke replaces it. Enter commits what was typed and then calls
    ## `on_submit`; Escape cancels and calls `on_cancel`; leaving the field
    ## commits, as it does after a click.
    pub func edit() -> !:
        try self.begin_editing()
        self.one_shot = true
        self.box.value().request_focus()

    ## `value` in whole steps, as a drag or an arrow moves it; whole steps from zero,
    ## not from the minimum, so a field from 0.5 in steps of 1 lands on 4, not 4.5.
    func snap(value: f64) -> f64:
        return self.snap_to(value, self.grid())

    ## The step in stored units, as the shown unit rounds it.
    func grid() -> f64:
        return self.shown_in.stored(measures.shown_step(self.step, self.shown_in))

    ## `value` as shown: to the field's decimals where they are finer than the step.
    ## What is typed or set from code stays what it is, as far as the field shows it;
    ## a field without a step takes any value. In a unit that converts it stays
    ## exactly what it is: "25 mm" typed under an inch display is 25 mm.
    func precise(value: f64) -> f64:
        if self.shown_in.converts():
            return self.snap_to(value, 0.0)
        return self.snap_to(value, math.min(self.grid(), self.shown_in.stored(math.pow(10.0, -(f64)measures.shown_decimals(self.decimals, self.shown_in)))))

    func snap_to(value: f64, grid: f64) -> f64:
        var snapped = value
        if grid > 0.0:
            snapped = math.floor(value / grid + 0.5) * grid
        return math.clamp(snapped, self.minimum, self.maximum)

    func change(value: f64, exact: bool = false) -> interop.Outcome[unit]:
        let snapped = self.precise(value) if exact else self.snap(value)
        if snapped == self.current:
            return result.success[unit](())
        self.current = snapped
        self.box.value().invalidate()
        return self.changed.emit(snapped)

    ## One increment for arrows and scrubbing: the step, or a two-hundredth of the range.
    func increment() -> f64:
        return self.grid() if self.step > 0.0 else (self.maximum - self.minimum) / 200.0

    func begin_editing() -> !:
        var digits: u8[48]
        let shown = try format_number(digits, self.shown_in.shown(self.current), measures.shown_decimals(self.decimals, self.shown_in))
        try self.input.set_text(shown)
        try self.input.select_all()
        self.editing = true
        self.one_shot = false
        self.box.value().set_cursor(input.Cursor.text)
        self.box.value().invalidate()

    func finish_editing(keep: bool) -> interop.Outcome[unit]:
        self.editing = false
        self.one_shot = false
        self.box.value().set_cursor(input.Cursor.resize_horizontal)
        self.box.value().invalidate()
        if not keep:
            return result.success[unit](())
        let typed = self.input.text() catch failure:
            return result.failure[unit](failure.code, failure.message)
        defer typed.release()
        if self.shown_in.converts() or self.shown_in.is_length():
            let measured = parameter_text.evaluate(typed.value, self.current, self.shown_units()) else return result.success[unit](())
            return self.change(measured, exact = true)
        let parsed = strings.parse_f64(trimmed(typed.value)) catch _:
            recover self.current
        if not math.is_finite(parsed):
            return result.success[unit](())
        return self.change(parsed, exact = true)

    pub func measure(available: Constraints) -> interop.Outcome[Size]:
        return result.success[Size](Size(self.font.value().advance() * self.cells, self.box.value().theme().row_height(self.font)))

    pub func draw(target: interop.View[gpu.RenderTarget]) -> interop.Outcome[unit]:
        self.paint(target) catch failure:
            return result.failure[unit](failure.code, failure.message)
        return result.success[unit](())

    func paint(target: interop.View[gpu.RenderTarget]) -> !:
        var painter = try Painter(target)
        defer painter.close()
        let size = try target.get().size()
        let theme = self.box.value().theme()
        let enabled = self.box.value().is_enabled()
        let focused = self.box.value().is_focused()
        let radius = theme.control_radius
        let border = theme.active_border if focused else (theme.hover_border() if self.box.value().contains_pointer() else theme.border)
        let thickness = 2.0 if focused else 1.0
        try painter.rounded_rectangle(gpu.Rect(width = size.width, height = size.height), border, radius)
        try painter.rounded_rectangle(gpu.Rect(thickness, thickness, size.width - thickness * 2.0, size.height - thickness * 2.0), theme.sunken, math.max(0.0, radius - thickness))
        let inset = self.font.value().advance() * 0.75
        let text_y = math.max(0.0, (size.height - self.font.value().height()) * 0.5)
        if self.editing:
            try self.input.paint(&painter, self.font, theme, inset, text_y, size.width - inset * 2.0)
            return
        var digits: u8[48]
        let shown = try format_number(digits, self.shown_in.shown(self.current), measures.shown_decimals(self.decimals, self.shown_in))
        # Right-aligned value, then the suffix in the muted color.
        let suffix_width = try self.font.value().measure(self.suffix.value)
        let value_width = try self.font.value().measure(shown)
        var x = size.width - inset - suffix_width - value_width
        if x < inset:
            x = inset
        try painter.text(shown, x, text_y, color = theme.foreground if enabled else theme.muted, font = self.font)
        if self.suffix.value.length > 0:
            try painter.text(self.suffix.value, x + value_width, text_y, color = theme.muted, font = self.font)

    pub func event(event: Event) -> interop.Outcome[unit]:
        if event.cancelled:
            self.pressed = false
            if self.scrubbing:
                self.scrubbing = false
                return self.ended.emit(())
            # Focus taken elsewhere (a click on OK, another field): what was typed
            # stands, as a field left does everywhere; only Escape throws it away.
            if self.editing:
                return self.finish_editing(true)
            return result.success[unit](())
        if not self.box.value().is_enabled():
            return result.success[unit](())
        let bounds = self.box.value().bounds()
        let inset = self.font.value().advance() * 0.75
        if self.editing:
            if event.kind == input.EventKind.pointer_down or event.kind == input.EventKind.pointer_moved or event.kind == input.EventKind.pointer_up:
                if event.kind == input.EventKind.pointer_down and not event.inside:
                    return self.finish_editing(true)
                self.input.pointer(event, self.font, inset, 0.0, bounds.width - inset * 2.0, bounds.height) catch failure:
                    return result.failure[unit](failure.code, failure.message)
                self.box.value().invalidate()
                return result.success[unit](())
            if event.kind == input.EventKind.focus_lost:
                return self.finish_editing(true)
            if event.kind == input.EventKind.key_down and event.key == input.Key.escape:
                let dropped = self.finish_editing(false)
                if not dropped.is_success():
                    return dropped
                return self.cancelled.emit(())
            if event.kind == input.EventKind.key_down and event.key == input.Key.enter and not event.repeated:
                let submits = self.one_shot and self.submits
                let committed = self.finish_editing(true)
                if not submits or not committed.is_success():
                    return committed
                return self.submitted.emit(())
            if event.kind == input.EventKind.key_down or event.kind == input.EventKind.text_input:
                let mutated = self.input.event(event) catch failure:
                    return result.failure[unit](failure.code, failure.message)
                if mutated:
                    self.box.value().invalidate()
            return result.success[unit](())
        if event.kind == input.EventKind.pointer_down and event.button == 0 and event.inside:
            self.box.value().request_focus()
            if event.control or event.meta:
                return self.change(self.fallback)
            self.pressed = true
            self.scrubbing = false
            self.press_x = event.x
            self.press_value = self.current
            return result.success[unit](())
        if event.kind == input.EventKind.pointer_moved:
            if self.pressed:
                let travelled = event.x - self.press_x
                if not self.scrubbing and math.abs(travelled) >= 2.0:
                    self.scrubbing = true
                    let outcome = self.began.emit(())
                    if not outcome.is_success():
                        return outcome
                if self.scrubbing:
                    let per_pixel = self.increment() * 0.5 * (10.0 if event.shift else 1.0)
                    return self.change(self.press_value + travelled * per_pixel)
            else:
                self.box.value().invalidate()
            return result.success[unit](())
        if event.kind == input.EventKind.pointer_up and event.button == 0:
            let was_pressed = self.pressed
            self.pressed = false
            if self.scrubbing:
                self.scrubbing = false
                return self.ended.emit(())
            if was_pressed and event.inside:
                self.begin_editing() catch failure:
                    return result.failure[unit](failure.code, failure.message)
            return result.success[unit](())
        if event.kind == input.EventKind.key_down:
            let amount = self.increment() * (10.0 if event.shift else 1.0)
            if event.key == input.Key.up or event.key == input.Key.right:
                return self.change(self.current + amount)
            if event.key == input.Key.down or event.key == input.Key.left:
                return self.change(self.current - amount)
            if event.key == input.Key.enter and not event.repeated and self.submits:
                return self.submitted.emit(())
            if event.key == input.Key.enter and not event.repeated:
                self.begin_editing() catch failure:
                    return result.failure[unit](failure.code, failure.message)
        return result.success[unit](())

    pub func close():
        self.font.release()
        self.input.close()
        self.changed.close()
        self.changed.release()
        self.began.close()
        self.began.release()
        self.ended.close()
        self.submitted.close()
        self.ended.release()
        self.submitted.release()
        self.cancelled.close()
        self.cancelled.release()
        self.suffix.release()
        self.box.release()

    func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        self.font.trace(visit, context)
        self.box.trace(visit, context)
        self.changed.trace(visit, context)
        self.began.trace(visit, context)
        self.ended.trace(visit, context)
        self.submitted.trace(visit, context)
        self.cancelled.trace(visit, context)
        self.suffix.trace(visit, context)

## `text` without leading and trailing spaces.
func trimmed(text: str) -> str:
    var start: usize = 0
    var end = text.length
    while start < end and text.bytes[start] == ' ':
        start += 1
    while end > start and text.bytes[end - 1] == ' ':
        end -= 1
    return (str)text.bytes[start..<end]

## `value` rounded to `decimals` places, written right-aligned into `digits`;
## the result is a view of `digits`.
pub func format_number(digits: u8[], value: f64, decimals: i64) -> str!:
    var scale = 1.0
    for _ in 0..<decimals:
        scale *= 10.0
    let scaled = (i64)math.floor(math.abs(value) * scale + 0.5)
    var whole = scaled
    var fraction: i64 = 0
    if decimals > 0:
        let divisor = (i64)scale
        whole = scaled // divisor
        fraction = scaled % divisor
    var end = digits.length
    if decimals > 0:
        var remaining = fraction
        for _ in 0..<decimals:
            end -= 1
            digits[end] = (u8)('0' + (u8)(remaining % 10))
            remaining //= 10
        end -= 1
        digits[end] = '.'
    if whole == 0:
        end -= 1
        digits[end] = '0'
    while whole > 0 and end > 0:
        end -= 1
        digits[end] = (u8)('0' + (u8)(whole % 10))
        whole //= 10
    if value < 0.0 and scaled != 0 and end > 0:
        end -= 1
        digits[end] = '-'
    return (str)digits[end..]

pub let number_field_type: interop.Type[NumberField] = interop.Type[NumberField]("NumberField", NumberField.close, NumberField.trace, closeable = true, main_thread = true)

test "a number field clamps, snaps, formats and parses":
    var field = try NumberField(50.0, 0.0, 100.0, 1.0, 0, "%")
    defer field.close()
    assert(field.value() == 50.0)
    try field.set_value(250.0)
    assert(field.value() == 100.0)
    try field.set_value(33.4)
    assert(field.value() == 33.0)
    var digits: u8[48]
    assert((try format_number(digits, 33.0, 0)) == "33")
    assert((try format_number(digits, 2.5, 1)) == "2.5")
    assert((try format_number(digits, -0.25, 2)) == "-0.25")
    assert((try format_number(digits, 0.000000001, 9)) == "0.000000001")
    assert((try format_number(digits, 0.000012345, 9)) == "0.000012345")
    assert(trimmed("  12 ") == "12")
    try field.set_decimals(2)
    try field.set_step(0.01)
    try field.set_value(33.456)
    assert(math.abs(field.value() - 33.46) < 0.0001)
    try field.set_suffix(" mm")
    var rejected = false
    _ = NumberField(0.0, 5.0, 5.0) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
        recover try NumberField()
    assert(rejected)

test "sub-micron numerical fields preserve typed and programmatic precision":
    var field = try NumberField(0.0, 0.0, 1.0, 0.00001, 9)
    defer field.close()
    try field.set_value(0.000000001)
    assert(math.abs(field.value() - 0.000000001) < 1e-20)
    try field.begin_editing()
    try field.input.set_text("0.000015856")
    let committed = field.finish_editing(true)
    defer committed.release()
    try committed.get()
    assert(math.abs(field.value() - 0.000015856) < 1e-18)
    var rejected = false
    field.set_decimals(10) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
        recover ()
    assert(rejected)

test "a number field in units shows, steps and reads the stored value in them":
    var field = try NumberField(25.4, 0.0, 1000.0, 1.0, 2, units = measures.millimeters())
    defer field.close()
    assert(field.value() == 25.4 and field.shown_value() == 25.4 and field.suffix.value == " mm")
    # A switch to inches keeps the stored value; the step and decimals follow the unit.
    try field.set_units(measures.inches())
    assert(field.value() == 25.4 and field.shown_value() == 1.0 and field.suffix.value == " in")
    assert(math.abs(field.increment() - 1.27) < 1.0e-12)
    try field.begin_editing()
    let shown = try field.input.text()
    assert(shown.value == "1.000")
    shown.release()
    # Typed lengths in any unit; a bare number is inches; the hard range holds.
    for (typed, stored) in [("2.5cm", 25.0), ("1", 25.4), ("0.1 in", 2.54), ("25.4 mm", 25.4), ("1\"", 25.4), ("50 in", 1000.0), ("10 + 5 mm", 259.0)]:
        try field.begin_editing()
        try field.input.set_text(typed)
        let outcome = field.finish_editing(true)
        try outcome.get()
        outcome.release()
        assert(math.abs(field.value() - stored) < 1.0e-9)
    # An unknown unit leaves the value.
    try field.begin_editing()
    try field.input.set_text("3 parsecs")
    let kept = field.finish_editing(true)
    try kept.get()
    kept.release()
    assert(math.abs(field.value() - 259.0) < 1.0e-9)
    # A tenth of an inch shows as one, not 0.0999999.
    try field.set_value(2.54)
    try field.begin_editing()
    let tenth = try field.input.text()
    assert(tenth.value == "0.100")
    tenth.release()
    # Stepping moves in whole shown steps: 0.05 in.
    try field.set_value(25.4)
    let stepped = field.change(field.value() + field.increment())
    stepped.release()
    assert(math.abs(field.value() - 26.67) < 1.0e-9 and math.abs(field.shown_value() - 1.05) < 1.0e-12)
    var rejected = false
    field.set_units(measures.Unit(scale = 0.0)) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
        recover ()
    assert(rejected)