dymokomi/luce-ui
Source of release 0.19.0
0.19.0 / src / widgets / parameters / module.lucb
#==============================================================================================
#
# widgets/parameters/module - The ParameterPanel: specs, stored rows, lifetime and type
#
#==============================================================================================
#
# DESCRIPTION:
# A parameter editor after Houdini's parameter pane and Maya's Attribute
# Editor: one compact row per parameter, a right-aligned label in a
# resizable column, then the control. A panel is built from ParameterSpecs
# (a name, label, kind, default, ranges, flags, conditions, doc) and draws
# every row itself, so only the rows that show do any work and a hundred
# parameters stay cheap. One spec makes a standalone row. The methods are
# split by concern across the fragments, each under `extend ParameterPanel:`.
# In ORDER:
#
# module.lucb the kinds, the spec, the stored row, the panel's state and lifetime
# values.lucb the public API: values by index or name, visibility, conditions, signals
# arrange.lucb placing rows into lines, the label column, and the parts of a row
# paint.lucb drawing the rows: labels, fields, sliders, toggles, menus, swatches
# input.lucb pointer gestures: scrubbing, the value ladder, clicks, the context menu
# editing.lucb typing into a field, keys, Tab between fields, and polled popups
# popups.lucb the value ladder and the tooltip, the panel's two small popups
#
#==============================================================================================
from luce_gpu import gpu
from luce_window import input
import interop
from luce_std import math
import memory
import ownership
import strings
import time
from luce_color import transfer
import layout
import result
import text.cells as cell_widths
import widgets.parameter_text
from layout import Widget, Layout, Size, Constraints, Event, Rect
from painter import Painter
from theme import Theme, srgb_decoded
from geometry import Point
from font import Font, selected_font
from command import Command, command_type
from text.line_input import LineInput
from widgets.action_popup import ActionPopup, action_popup_type
from widgets.color_editor import ColorEditor, color_editor_type
from widgets.number_field import format_number
import icons
## What a parameter row edits and how it shows. Houdini's parameter types,
## less animation: `number` a float and `integer` a whole number (a field and
## an optional slider), `vector` 2–4 floats on one row, `toggle` a checkbox,
## `menu` a choice of `items`, `text` a line of text, `path` a file path with a
## browse button, `color` an RGB swatch with three fields, `button` an action,
## `separator` a rule, `folder` a collapsible heading over the rows after it,
## `info` read-only text, and `swatches` a row of color chips choosing one of
## `items` (`label=#RRGGBB` each; the value is the chip's index).
pub enum ParameterKind as u8:
number = 0
integer = 1
vector = 2
toggle = 3
menu = 4
text = 5
path = 6
color = 7
button = 8
separator = 9
folder = 10
info = 11
swatches = 12
## One parameter as the host describes it. Only `name` and `kind` are needed;
## every other field has a default. Texts are copied when the panel takes it.
pub struct ParameterSpec:
## The key the host finds it by, and what conditions name.
pub var name: str = ""
## What the row shows; a button's caption, a folder's heading.
pub var label: str = ""
pub var kind: ParameterKind = ParameterKind.number
## A vector's components, 2..4; 0 picks the kind's own (3 for vectors and colors).
pub var components: i64 = 0
## The default: the first component, a toggle's 0 or 1, a menu item's value.
pub var value: f64 = 0.0
## The other components' defaults, for vectors and colors.
pub var y: f64 = 0.0
pub var z: f64 = 0.0
pub var w: f64 = 0.0
## The hard range: nothing typed, dragged or set goes past it.
pub var minimum: f64 = -1.0e9
pub var maximum: f64 = 1.0e9
## The slider's range, which typing may exceed; equal ends use the hard range.
pub var soft_minimum: f64 = 0.0
pub var soft_maximum: f64 = 0.0
## How far a drag, an arrow or a ladder rung moves; 0 picks one from the kind and decimals.
pub var step: f64 = 0.0
pub var decimals: i64 = 3
## A unit shown after the number, muted: "°", " px", "%".
pub var suffix: str = ""
## A slider beside the field (numbers and integers).
pub var slider: bool = false
## The slider's track as a gradient instead of a fill: sRGB stops, `|`
## between them, spread evenly from the low end ("#3B7DD8|#FFFFFF|#E7A03F"
## for a white balance's temperature); at most eight.
pub var gradient: str = ""
## A menu's items, `|` between them, each `label` or `label=value`.
pub var items: str = ""
## A text or path's default, an info row's text.
pub var text: str = ""
## The tooltip, shown when the pointer rests on the row.
pub var doc: str = ""
## Houdini conditions, `{ shape != 2 }`: the row hides, or dims and ignores
## input, while one holds.
pub var hide_when: str = ""
pub var disable_when: str = ""
## Share this row's line with the next parameter, as Houdini's "join to next".
pub var join: bool = false
## A folder starts open.
pub var open: bool = true
## A color's components are linear light rather than sRGB-encoded.
pub var linear: bool = false
## The host's own number for the parameter (a slot), returned by `tag`.
pub var tag: i64 = 0
## Whether the row has a default to mark changes from and revert to; a
## layer's name or a page chooser has none.
pub var resettable: bool = true
## A parameter as the panel keeps it: owned texts, values and where it was placed.
struct Row:
var kind: ParameterKind
var name: interop.Owned[str]
var label: interop.Owned[str]
var suffix: interop.Owned[str]
var items: interop.Owned[str]
var doc: interop.Owned[str]
## The current text of a text, path or info row; a button's caption is its label.
var text: interop.Owned[str]
var fallback: interop.Owned[str]
var hide_when: interop.Owned[str]
var disable_when: interop.Owned[str]
var components: i64
## The slider's gradient stops (linear light) and how many there are.
var stops: gpu.Color[8]
var stop_count: usize
var values: f64[4]
var defaults: f64[4]
var minimum: f64
var maximum: f64
var soft_minimum: f64
var soft_maximum: f64
var step: f64
var decimals: i64
var slider: bool
var join: bool
var linear: bool
var tag: i64
var resettable: bool
## Hidden or disabled by the host, and by the row's conditions.
var hidden: bool
var disabled: bool
var hidden_when: bool
var disabled_when: bool
## The folder row the row sits under, or -1; a folder's own open state.
var folder: i64
var open: bool
## Placed by `arrange`: shown, its top, height and the control's span; a
## joined row after the first shows its label inline at `label_x`.
var shown: bool
var y: f64
var height: f64
var control_x: f64
var control_width: f64
var label_x: f64
## What part of a row a point is over.
let part_none: i64 = 0
let part_label: i64 = 1
let part_field: i64 = 2
let part_slider: i64 = 3
let part_toggle: i64 = 4
let part_menu: i64 = 5
let part_browse: i64 = 6
let part_swatch: i64 = 7
let part_button: i64 = 8
let part_folder: i64 = 9
let part_divider: i64 = 10
let part_chip: i64 = 11
## Which popup is open for which row: none, a menu parameter's items, the context menu.
let popup_none: i64 = 0
let popup_items: i64 = 1
let popup_context: i64 = 2
## A tooltip shows after the pointer rests this long on a row (nanoseconds), unless set.
let tip_wait: u64 = 600000000
## Room between lines, and between parts of a line.
let line_gap: f64 = 2.0
let part_gap: f64 = 4.0
## The value last copied from any panel, for Paste Value (Houdini's Copy Parameter).
var copied: f64[4]
var copied_count: i64 = 0
## A column of parameter rows. `on_change` hears every value change, live while
## a drag goes on (coalesced to one per frame); `on_begin` and `on_commit`
## bracket each user edit, a drag or a typed value or a click, so a host makes
## it one undo step; `on_action` hears buttons and browse buttons. Setting
## values from code reports nothing.
pub struct ParameterPanel: Widget:
let box: interop.Reference[Layout]
let font: interop.Reference[Font]
var rows: Row[]
var total: usize
let changed: interop.Signal[i64]
let began: interop.Signal[i64]
let committed: interop.Signal[i64]
let activated: interop.Signal[i64]
let items_popup: interop.Reference[ActionPopup]
let color_popup: interop.Reference[ColorEditor]
let tip: interop.Reference[ParameterTip]
let ladder: interop.Reference[ValueLadder]
var input: LineInput
## The label column's width when the host or a drag set it; 0 fits the labels.
var fixed_label: f64
## Room left and right of the rows, and half of it above and below.
var margin: f64
## Folders the user closed, by name, as `|name|name|`: remembered across `set_specs`.
var closed: interop.Owned[str]
## The width rows were placed for, and whether placing is due.
var placed_width: f64
var stale: bool
## Under the pointer.
var hot_row: i64
var hot_part: i64
var hot_component: i64
## A press under way: where, what it pressed, and the values it started from.
var press_row: i64
var press_part: i64
var press_component: i64
var press_x: f64
var press_y: f64
var press_values: f64[4]
var press_label: f64
## The rate a scrub moves at; a modifier pressed mid-drag changes it from where the pointer is.
var press_rate: f64
var scrubbing: bool
## The middle-button value ladder: its rung and where the rung was taken.
var laddering: bool
var rung: i64
var rung_x: f64
var rung_values: f64[4]
## The field being typed in, or -1; its component.
var edit_row: i64
var edit_component: i64
## The row an edit began on (`on_begin` sent, `on_commit` due), a change
## waiting for the frame, and the row the keyboard acts on.
var gesture: i64
var pending: i64
var current: i64
## Which popup is open, for which row.
var popup_mode: i64
var popup_row: i64
var color_row: i64
var color_shown: (i64, i64, i64)
## The row whose tooltip is due, and since when the pointer rests there.
var tip_row: i64
var tip_since: u64
var tip_delay: u64
## A panel of `specs` in `font`; `label_width` fixes the label column (0 fits it to the labels).
pub func init(specs: const ParameterSpec[], font: interop.Reference[Font]? = none, label_width: f64 = 0.0) -> !:
if not math.is_finite(label_width) or label_width < 0.0 or label_width > 4096.0:
error(result.invalid, "a label column is 0..4096 points")
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_interactive(true)
box.value().set_context_menu(true)
let changed = try interop.Signal[i64]()
errdefer changed.release()
let began = try interop.Signal[i64]()
errdefer began.release()
let committed = try interop.Signal[i64]()
errdefer committed.release()
let activated = try interop.Signal[i64]()
errdefer activated.release()
let placeholder = try interop.Reference[Command].adopt(new Command("-") in memory.heap, command_type, memory.heap)
defer placeholder.release()
let items_popup = try interop.Reference[ActionPopup].adopt(new ActionPopup([placeholder], selected) in memory.heap, action_popup_type, memory.heap)
errdefer items_popup.release()
let color_popup = try interop.Reference[ColorEditor].adopt(new ColorEditor(selected) in memory.heap, color_editor_type, memory.heap)
errdefer color_popup.release()
let tip = try interop.Reference[ParameterTip].adopt(new ParameterTip(selected) in memory.heap, parameter_tip_type, memory.heap)
errdefer tip.release()
let ladder = try interop.Reference[ValueLadder].adopt(new ValueLadder(selected) in memory.heap, value_ladder_type, memory.heap)
errdefer ladder.release()
let children: interop.Interface[Widget][4] = [items_popup.as_interface[Widget](items_popup.value()), color_popup.as_interface[Widget](color_popup.value()),
tip.as_interface[Widget](tip.value()), ladder.as_interface[Widget](ladder.value())]
box.value().set_children(children) catch failure:
for child in children:
child.release()
error(failure.code, failure.message)
# The layout retained its children; these carriers were ours to drop.
for child in children:
child.release()
var line = try LineInput()
errdefer line.close()
var empty: Row[]
self.box = box
self.font = selected
self.rows = empty
self.total = 0
self.changed = changed
self.began = began
self.committed = committed
self.activated = activated
self.items_popup = items_popup
self.color_popup = color_popup
self.tip = tip
self.ladder = ladder
self.input = line
self.fixed_label = label_width
self.margin = 8.0
self.closed = interop.Owned[str]("")
self.placed_width = -1.0
self.stale = true
self.hot_row = -1
self.hot_part = part_none
self.hot_component = 0
self.press_row = -1
self.press_part = part_none
self.press_component = 0
self.press_x = 0.0
self.press_y = 0.0
self.press_values = [0.0, 0.0, 0.0, 0.0]
self.press_label = 0.0
self.press_rate = 0.0
self.scrubbing = false
self.laddering = false
self.rung = 0
self.rung_x = 0.0
self.rung_values = [0.0, 0.0, 0.0, 0.0]
self.edit_row = -1
self.edit_component = 0
self.gesture = -1
self.pending = -1
self.current = -1
self.popup_mode = popup_none
self.popup_row = -1
self.color_row = -1
self.color_shown = (0, 0, 0)
self.tip_row = -1
self.tip_since = 0
self.tip_delay = tip_wait
try self.set_specs(specs)
pub func layout() -> interop.Reference[Layout]:
return self.box.clone()
## As tall as its shown rows; as wide as the labels and three fields need,
## less when less is given.
pub func measure(available: Constraints) -> interop.Outcome[Size]:
let natural = self.controls_left(480.0) + self.font.value().advance() * 30.0 + self.margin
return result.success[Size](Size(math.min(available.width, natural), self.content_height()))
pub func draw(target: interop.View[gpu.RenderTarget]) -> interop.Outcome[unit]:
self.frame(target) catch failure:
return result.failure[unit](failure.code, failure.message)
return result.success[unit](())
## Each frame: take what the popups chose, send the change a drag left
## waiting (one per frame however fast the pointer), show a tooltip that is
## due, then draw the rows that show.
func frame(target: interop.View[gpu.RenderTarget]) -> !:
try self.poll_popups()
try self.flush()
try self.show_due_tip()
try self.paint(target)
pub func event(event: Event) -> interop.Outcome[unit]:
self.handle(event) catch failure:
return result.failure[unit](failure.code, failure.message)
return result.success[unit](())
pub func close():
release_rows(self.rows, self.total)
self.total = 0
self.input.close()
self.closed.release()
self.changed.close()
self.changed.release()
self.began.close()
self.began.release()
self.committed.close()
self.committed.release()
self.activated.close()
self.activated.release()
self.items_popup.release()
self.color_popup.release()
self.tip.release()
self.ladder.release()
self.font.release()
self.box.release()
func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
self.box.trace(visit, context)
self.font.trace(visit, context)
self.changed.trace(visit, context)
self.began.trace(visit, context)
self.committed.trace(visit, context)
self.activated.trace(visit, context)
self.items_popup.trace(visit, context)
self.color_popup.trace(visit, context)
self.tip.trace(visit, context)
self.ladder.trace(visit, context)
self.closed.trace(visit, context)
for index in 0..<self.total:
trace_row(self.rows[index], visit, context)
pub let parameter_panel_type: interop.Type[ParameterPanel] = interop.Type[ParameterPanel]("ParameterPanel", ParameterPanel.close, ParameterPanel.trace, closeable = true, main_thread = true)
## A stored row from `spec`, its texts copied; defaults filled in for the kind.
func make_row(spec: ParameterSpec) -> Row!:
var components = spec.components
if spec.kind == ParameterKind.vector:
components = between(components if components > 0 else 3, 2, 4)
elif spec.kind == ParameterKind.color:
components = 3
else:
components = 1
if not math.is_finite(spec.minimum) or not math.is_finite(spec.maximum) or spec.maximum < spec.minimum:
error(result.invalid, "a parameter needs finite bounds with its maximum at or above its minimum")
if spec.decimals < 0 or spec.decimals > 9:
error(result.invalid, "parameter decimals must be 0..9")
if not math.is_finite(spec.step) or spec.step < 0.0:
error(result.invalid, "a parameter step must be finite and nonnegative")
var minimum = spec.minimum
var maximum = spec.maximum
if spec.kind == ParameterKind.color:
minimum = math.max(minimum, 0.0)
maximum = maximum if spec.maximum != 1.0e9 else 1.0
var defaults: f64[4] = [spec.value, spec.y, spec.z, spec.w]
var row = Row(kind = spec.kind, name = try interop.copy_text(spec.name), label = interop.Owned[str](""), suffix = interop.Owned[str](""),
items = interop.Owned[str](""), doc = interop.Owned[str](""), text = interop.Owned[str](""), fallback = interop.Owned[str](""),
hide_when = interop.Owned[str](""), disable_when = interop.Owned[str](""), components = components,
values = defaults, defaults = defaults, minimum = minimum, maximum = maximum,
soft_minimum = spec.soft_minimum, soft_maximum = spec.soft_maximum, step = spec.step,
decimals = 0 if spec.kind == ParameterKind.integer else spec.decimals,
slider = spec.slider, join = spec.join, linear = spec.linear, tag = spec.tag, resettable = spec.resettable,
hidden = false, disabled = false, hidden_when = false, disabled_when = false,
folder = -1, open = spec.open, shown = false, y = 0.0, height = 0.0, control_x = 0.0, control_width = 0.0, label_x = -1.0,
stops = gradient_stops(spec.gradient), stop_count = stop_count(spec.gradient))
errdefer release_row(row)
row.label = try interop.copy_text(spec.label if spec.label.length > 0 else spec.name)
row.suffix = try interop.copy_text(spec.suffix)
row.items = try interop.copy_text(spec.items)
row.doc = try interop.copy_text(spec.doc)
row.text = try interop.copy_text(spec.text)
row.fallback = try interop.copy_text(spec.text)
row.hide_when = try interop.copy_text(spec.hide_when)
row.disable_when = try interop.copy_text(spec.disable_when)
for component in 0..<4:
row.defaults[component] = row_clamp(row, row.defaults[component])
row.values = row.defaults
return row
## The color of `#RRGGBB` (linear light), or none.
pub func color_of_hex(text: str) -> gpu.Color?:
let bytes = text.bytes
if bytes.length != 7 or bytes[0] != '#':
return none
var channels: f64[3]
for channel in 0..<(usize)3:
var value: i64 = 0
for at in 0..<(usize)2:
let c = bytes[1 + channel * 2 + at]
let digit = (i64)(c - '0') if c >= '0' and c <= '9' else ((i64)(c - 'a') + 10 if c >= 'a' and c <= 'f' else ((i64)(c - 'A') + 10 if c >= 'A' and c <= 'F' else -1))
if digit < 0:
return none
value = value * 16 + digit
channels[channel] = transfer.srgb_decode((f64)value / 255.0)
return gpu.Color(channels[0], channels[1], channels[2])
## The stops of a gradient spec, `|` between them, at most eight; malformed ones left out.
func gradient_stops(text: str) -> gpu.Color[8]:
var out: gpu.Color[8] = ---
for at in 0..<(usize)8:
out[at] = gpu.Color()
var count: usize = 0
var first: usize = 0
let bytes = text.bytes
while first < bytes.length and count < 8:
var end = first
while end < bytes.length and bytes[end] != '|':
end += 1
if let color = color_of_hex((str)bytes[first..<end]):
out[count] = color
count += 1
first = end + 1
return out
func stop_count(text: str) -> usize:
var count: usize = 0
var first: usize = 0
let bytes = text.bytes
while first < bytes.length and count < 8:
var end = first
while end < bytes.length and bytes[end] != '|':
end += 1
if color_of_hex((str)bytes[first..<end]) != none:
count += 1
first = end + 1
return count
## `value` as row `row` keeps it: inside the hard range, whole for integers,
## 0 or 1 for toggles.
func row_clamp(row: Row, value: f64) -> f64:
if not math.is_finite(value):
return row.minimum if row.minimum > 0.0 else math.min(0.0, row.maximum)
var kept = math.clamp(value, row.minimum, row.maximum)
if row.kind == ParameterKind.integer:
kept = math.floor(kept + 0.5)
elif row.kind == ParameterKind.toggle:
kept = 1.0 if value != 0.0 else 0.0
return kept
func release_row(row: Row):
row.name.release()
row.label.release()
row.suffix.release()
row.items.release()
row.doc.release()
row.text.release()
row.fallback.release()
row.hide_when.release()
row.disable_when.release()
func release_rows(rows: Row[], count: usize):
for index in 0..<count:
release_row(rows[index])
if rows.length > 0:
free(rows) in memory.heap
func trace_row(row: Row, visit: func(ownership.Object*, void*) -> unit, context: void*):
row.name.trace(visit, context)
row.label.trace(visit, context)
row.suffix.trace(visit, context)
row.items.trace(visit, context)
row.doc.trace(visit, context)
row.text.trace(visit, context)
row.fallback.trace(visit, context)
row.hide_when.trace(visit, context)
row.disable_when.trace(visit, context)
## Replace owned text `slot` with a copy of `text`.
func replace_text(slot: interop.Owned[str]*, text: str) -> !:
if slot.value == text:
return
let copy = try interop.copy_text(text)
let previous = *slot
*slot = copy
previous.release()
## `value` held inside `low..high`, for whole numbers.
func between(value: i64, low: i64, high: i64) -> i64:
if value < low:
return low
if value > high:
return high
return value
test "gradient stops and swatch colors read #RRGGBB":
let white = color_of_hex("#FFFFFF") else trap("white did not parse")
assert(white.red > 0.999 and white.green > 0.999 and white.blue > 0.999)
let middle = color_of_hex("#808080") else trap("grey did not parse")
assert(math.abs(middle.red - transfer.srgb_decode(128.0 / 255.0)) < 1.0e-9)
assert(color_of_hex("808080") == none and color_of_hex("#80808") == none and color_of_hex("#80Z080") == none)
assert(stop_count("#4A7FD6|#F0F0F0|#E8A93C") == 3 and stop_count("") == 0 and stop_count("#4A7FD6|nope|#E8A93C") == 2)