Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// A rotary knob for device / instrument parameters (style guide, spec 038): a 270° arc,
// 2.4 wide with round ends, on the knob track; the value in orange inside a device (grey
// for a knob off the audio path); a small centre cap; a thin ink-1 pointer from the centre
// to the arc. A bipolar knob fills from 12 o'clock; a `Marker` puts a short ink-2 tick across
// the track at a live reading (Dynamic EQ-8's band level on its threshold). A Flat knob is the one used outside
// device cards (sends): no cap, the value in ink 3, orange only while live. Drag vertically to change
// (up = increase; Ctrl/⌘/Shift = fine). Double-click resets and ⌥-click types a value
// (ValueEntry, attached by KnobCell once `Format` is set). Same public API as
// MiniFader (Value / max / Accent / ValueChanged / GestureBegin / GestureEnd) so it
// drops into the plugin editors.
//
// A device knob exists in three sizes — 34 secondary · 36 regular · 44 main. Width and
// Height are coerced onto that scale, so a call site asking for 30 or 40 gets 34 or 44.
// The exceptions are an `Inline` knob (24) that sits inside a table row (the Consort /
// Pentad / Monolith oscillator rows and ADSR strips) and a Flat knob outside a device (28).
using System;
using Avalonia;
using Avalonia.Controls;
using Avalonia.Input;
using Avalonia.Media;
namespace Nota.App;
public sealed class Knob : Control
{
private static readonly IBrush Track = NotaPalette.KnobTrack;
private static readonly IBrush DeviceArc = NotaPalette.Accent; // a device value, at rest and live
private static readonly IBrush GreyArc = NotaPalette.TextTertiary; // off the audio path, or a flat knob at rest
private static readonly IBrush OffArc = NotaPalette.TextDisabled; // disabled or inactive
private static readonly IBrush LiveArc = NotaPalette.Accent; // a flat knob while it is being set
private static readonly IBrush Cap = NotaPalette.KnobCap;
private static readonly IBrush CapEdge = NotaPalette.Seam; // the guide's cap edge: Sunken in dark, Seam in light — within a step
private static readonly IBrush TickInk = NotaPalette.TextTertiary; // a second value of the param (OtherValue)
private static readonly IBrush PointerOn = NotaPalette.TextPrimary;
private static readonly IBrush PointerOff = NotaPalette.TextDisabled;
private static readonly IBrush MarkerInk = NotaPalette.TextSecondary; // a live reading on the track
private const double StartDeg = 135.0; // down-left
private const double SweepDeg = 270.0; // clockwise to down-right
private const double Stroke = 2.4, PointerW = 1.6;
// The modulation mark: the value arc in short dashes (in stroke widths).
private static readonly DashStyle ModDash = new(new double[] { 1.1, 0.7 }, 0);
public const double SizeSecondary = NotaSize.KnobSecondary, SizeRegular = NotaSize.KnobRegular, SizeMain = NotaSize.KnobMain,
SizeInline = NotaSize.KnobInline, SizeFlat = NotaSize.KnobFlat;
static Knob()
{
WidthProperty.OverrideMetadata<Knob>(new StyledPropertyMetadata<double>(double.NaN, coerce: (o, v) => ((Knob)o).Fixed(v)));
HeightProperty.OverrideMetadata<Knob>(new StyledPropertyMetadata<double>(double.NaN, coerce: (o, v) => ((Knob)o).Fixed(v)));
}
/// <summary>Onto the three-size scale: up to 34 is secondary, under 40 regular, else main.</summary>
public static double Snap(double v) => double.IsNaN(v) ? v : v <= SizeSecondary ? SizeSecondary : v < 40 ? SizeRegular : SizeMain;
private double Fixed(double v) => double.IsNaN(v) ? v : _inline ? SizeInline : _flat ? SizeFlat : Snap(v);
/// <summary>The 24 px table-row knob, outside the three-size scale (see the header).</summary>
public bool Inline { get => _inline; init { _inline = value; CoerceValue(WidthProperty); CoerceValue(HeightProperty); } }
private readonly bool _inline;
/// <summary>The 28 px knob outside a device card: no cap, a grey value, orange while live.</summary>
public bool Flat { get => _flat; init { _flat = value; CoerceValue(WidthProperty); CoerceValue(HeightProperty); } }
private readonly bool _flat;
/// <summary>On the audio path: inside a device its value is orange; a knob off the audio
/// path draws its value in ink 3.</summary>
public bool Accent { get; init; }
/// <summary>The value fills from 12 o'clock (pan, detune, a ± amount).</summary>
public bool Bipolar { get; init; }
/// <summary>Marks a modulation depth (a knob 0.57 drew in teal: an env or LFO amount, a fine
/// tune, a rack macro in mapping mode); may change live (a knob that turns into a modulation
/// depth when its mode switches). Inside a device every value arc is orange, so a marked
/// knob keeps orange but draws its value arc dashed — the modulation mark (DESIGN.md
/// § Modulation), the same dash the graphs use for a modulated curve.</summary>
public IBrush? ArcColor { get => _arc; set { if (ReferenceEquals(_arc, value)) return; _arc = value; InvalidateVisual(); } }
private IBrush? _arc;
/// <summary>Drawn as inactive (no brass) while still taking input — see Inactive.</summary>
public bool IsDim { get => _dim; set { if (_dim == value) return; _dim = value; InvalidateVisual(); DimChanged?.Invoke(); } }
private bool _dim;
/// <summary>After <see cref="IsDim"/> changes, so a cell can repaint its label and value.</summary>
public event Action? DimChanged;
/// <summary>A live reading marked on the track as a short tick, as a 0..max position (NaN = none).</summary>
public double Marker { get => _marker; set { if (_marker.Equals(value)) return; _marker = value; InvalidateVisual(); } }
private double _marker = double.NaN;
/// <summary>A second value of the same parameter shown as a tick outside the groove — Nota
/// Twin's other morph side (0..max; NaN = none).</summary>
public double OtherValue { get => _other; set { if (_other.Equals(value)) return; _other = value; InvalidateVisual(); } }
private double _other = double.NaN;
/// <summary>The value the sound is at right now, when that differs from the knob's own —
/// Nota Twin's morphed value — drawn as a dot on the groove (0..max; NaN = none).</summary>
public double SoundingValue { get => _sounding; set { if (_sounding.Equals(value)) return; _sounding = value; InvalidateVisual(); } }
private double _sounding = double.NaN;
/// <summary>Value restored on double-click (NaN = no reset).</summary>
public double Default { get; set; } = double.NaN;
/// <summary>The read-out text at a value (0..max) — what the knob's value line shows. Pure:
/// it formats, it never writes. Set it and the knob takes typed values (ValueEntry).</summary>
public Func<double, string>? Format { get; set; }
private readonly double _max;
private double _value;
private bool _drag;
private double _lastY;
public event Action<double>? ValueChanged;
public event Action? GestureBegin;
public event Action? GestureEnd;
/// <summary>True while the user is dragging — live-follow refreshers skip it then.</summary>
public bool Dragging => _drag;
public double Value
{
get => _value;
set { _value = Math.Clamp(value, 0, _max); InvalidateVisual(); ValueSet?.Invoke(); }
}
/// <summary>Raised whenever the value moves — by hand, by reset or by live follow — so
/// a cell can re-evaluate <see cref="IsModified"/>.</summary>
public event Action? ValueSet;
/// <summary>The value differs from the parameter's default.</summary>
public bool IsModified => !double.IsNaN(Default) && Math.Abs(_value - Math.Clamp(Default, 0, _max)) > 1e-4 * _max;
/// <summary>The knob as a typeable value: a typed value or a reset runs the same
/// GestureBegin / ValueChanged / GestureEnd a drag does. Null without a Format.</summary>
internal ValueField? EntryField(string name)
=> Format is not { } fmt ? null : new ValueField(name, () => _value / _max, n => fmt(n * _max), n => SetByHand(n * _max),
() => GestureBegin?.Invoke(), () => GestureEnd?.Invoke(), NormDefault()) { DefaultNow = NormDefault };
/// <summary>A probing field for a knob without a Format: each probe sets the knob (running its
/// ValueChanged handlers) and reads <paramref name="text"/> back.</summary>
internal ValueField ProbingField(string name, Func<string> text)
=> ValueEntry.Probing(name, () => _value / _max, n => SetByHand(n * _max), text,
() => GestureBegin?.Invoke(), () => GestureEnd?.Invoke()) with
{ Default = NormDefault(), DefaultNow = NormDefault };
// The reset position as 0..1, read when a reset happens: a call site may move Default later.
private double? NormDefault() => double.IsNaN(Default) ? null : Math.Clamp(Default, 0, _max) / _max;
// A value set by the user other than by dragging (typed, reset): repaint and notify.
private void SetByHand(double v)
{
v = Math.Clamp(v, 0, _max);
if (Math.Abs(v - _value) < 1e-9) return;
_value = v;
InvalidateVisual();
ValueChanged?.Invoke(_value);
ValueSet?.Invoke();
}
public Knob(double value = 1.0, double max = 1.0)
{
_max = max <= 0 ? 1.0 : max;
_value = Math.Clamp(value, 0, _max);
Width = SizeRegular;
Height = SizeRegular;
Cursor = new Cursor(StandardCursorType.SizeNorthSouth);
}
protected override void OnPointerPressed(PointerPressedEventArgs e)
{
// Left button only — let right-click bubble to a context menu (e.g. CV modulate).
if (!e.GetCurrentPoint(this).Properties.IsLeftButtonPressed) return;
// Double-click (or ⌥-click) restores the default — ValueEntry handles it first on an
// attached knob (⌥ types there); this keeps reset on a knob built without one.
if ((e.ClickCount == 2 || (e.KeyModifiers & KeyModifiers.Alt) != 0) && !double.IsNaN(Default))
{
GestureBegin?.Invoke();
SetByHand(Default);
GestureEnd?.Invoke();
e.Handled = true;
return;
}
_drag = true;
_lastY = e.GetPosition(this).Y;
e.Pointer.Capture(this);
GestureBegin?.Invoke();
e.Handled = true;
}
protected override void OnPointerMoved(PointerEventArgs e)
{
if (!_drag) return;
double y = e.GetPosition(this).Y;
double dy = _lastY - y; // up = increase
_lastY = y;
if (dy == 0) return;
// Fine adjust: hold Ctrl (Windows/Linux), ⌘ or Shift — 10× finer (macOS turns
// Ctrl+click into a right-click, so Cmd/Shift cover it there).
bool fine = (e.KeyModifiers & (KeyModifiers.Control | KeyModifiers.Meta | KeyModifiers.Shift)) != 0;
double v = Math.Clamp(_value + dy / (fine ? 1400.0 : 140.0) * _max, 0, _max);
if (Math.Abs(v - _value) < 1e-6) return;
_value = v;
InvalidateVisual();
ValueChanged?.Invoke(_value);
ValueSet?.Invoke();
}
protected override void OnPointerReleased(PointerReleasedEventArgs e)
{
if (_drag) GestureEnd?.Invoke();
_drag = false;
e.Pointer.Capture(null);
InvalidateVisual();
}
protected override void OnPointerCaptureLost(PointerCaptureLostEventArgs e)
{
// Capture taken away mid-drag (the window deactivates): end the gesture and drop the accent.
if (_drag) { _drag = false; GestureEnd?.Invoke(); InvalidateVisual(); }
base.OnPointerCaptureLost(e);
}
// Under the pointer the knob is live: its arc takes the accent (120ms is the button
// fade; a dial repaints on the spot, which reads the same at this size).
private bool _hover;
protected override void OnPointerEntered(PointerEventArgs e) { base.OnPointerEntered(e); _hover = true; InvalidateVisual(); }
protected override void OnPointerExited(PointerEventArgs e) { base.OnPointerExited(e); _hover = false; InvalidateVisual(); }
protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
{
base.OnPropertyChanged(change);
if (change.Property == IsEffectivelyEnabledProperty) InvalidateVisual();
}
public override void Render(DrawingContext ctx)
{
double w = Bounds.Width, h = Bounds.Height;
if (w <= 0 || h <= 0) return;
// Transparent fill makes the whole knob area hit-testable (not just the arc).
ctx.FillRectangle(Brushes.Transparent, new Rect(0, 0, w, h));
double d = Math.Min(w, h), cx = w / 2, cy = h / 2;
double frac = _max > 0 ? _value / _max : 0;
bool on = IsEffectivelyEnabled && !_dim;
bool live = on && (_drag || _hover);
var arcBrush = !on ? OffArc
: _flat ? (live ? LiveArc : GreyArc) : Accent || live || ArcColor is not null ? DeviceArc : GreyArc;
var pointer = !on ? PointerOff : PointerOn;
// The track, then the value arc over it — round ends. A bipolar value grows from the top.
double r = d / 2 - 3;
ctx.DrawGeometry(null, new Pen(Track, Stroke, lineCap: PenLineCap.Round), Arc(cx, cy, r, 0, 1));
double from = Bipolar ? 0.5 : 0;
if (Math.Abs(frac - from) > 0.001)
ctx.DrawGeometry(null, ArcColor is not null && !_flat && on
? new Pen(arcBrush, Stroke, ModDash, lineCap: PenLineCap.Flat)
: new Pen(arcBrush, Stroke, lineCap: PenLineCap.Round),
Arc(cx, cy, r, Math.Min(from, frac), Math.Max(from, frac)));
// Nota Twin's other morph side: a tick just outside the track.
if (!double.IsNaN(_other) && _max > 0 && Math.Abs(_other - _value) > 0.002 * _max)
{
double ao = (StartDeg + Math.Clamp(_other / _max, 0, 1) * SweepDeg) * Math.PI / 180.0;
double r0 = r + Stroke * 0.6, r1 = d / 2 - 0.5;
ctx.DrawLine(new Pen(on ? TickInk : PointerOff, 1.1, lineCap: PenLineCap.Round),
new Point(cx + Math.Cos(ao) * r0, cy + Math.Sin(ao) * r0), new Point(cx + Math.Cos(ao) * r1, cy + Math.Sin(ao) * r1));
}
// Where the sound is now (Twin's morphed value): a dot riding the track, in ink so it reads on the orange arc too.
if (!double.IsNaN(_sounding) && _max > 0 && on)
{
double asd = (StartDeg + Math.Clamp(_sounding / _max, 0, 1) * SweepDeg) * Math.PI / 180.0;
ctx.DrawEllipse(PointerOn, null, new Point(cx + Math.Cos(asd) * r, cy + Math.Sin(asd) * r), Stroke * 0.55, Stroke * 0.55);
}
// A live reading: a short tick across the track.
if (on && !double.IsNaN(_marker) && _max > 0)
{
double m = (StartDeg + Math.Clamp(_marker / _max, 0, 1) * SweepDeg) * Math.PI / 180.0;
ctx.DrawLine(new Pen(MarkerInk, 1.4, lineCap: PenLineCap.Round),
new Point(cx + Math.Cos(m) * (r - 2.5), cy + Math.Sin(m) * (r - 2.5)), new Point(cx + Math.Cos(m) * (r + 2.5), cy + Math.Sin(m) * (r + 2.5)));
}
// The centre cap, devices only.
if (!_flat) ctx.DrawEllipse(Cap, new Pen(CapEdge, 1), new Point(cx, cy), d / 2 - 5, d / 2 - 5);
// Pointer from the centre to the arc.
double a = (StartDeg + frac * SweepDeg) * Math.PI / 180.0;
ctx.DrawLine(new Pen(pointer, PointerW, lineCap: PenLineCap.Round),
new Point(cx, cy), new Point(cx + Math.Cos(a) * r, cy + Math.Sin(a) * r));
}
// The sweep from fraction t0..t1 as a true arc.
private static StreamGeometry Arc(double cx, double cy, double r, double t0, double t1)
{
double a0 = (StartDeg + t0 * SweepDeg) * Math.PI / 180.0;
double a1 = (StartDeg + t1 * SweepDeg) * Math.PI / 180.0;
var g = new StreamGeometry();
using (var c = g.Open())
{
c.BeginFigure(new Point(cx + Math.Cos(a0) * r, cy + Math.Sin(a0) * r), false);
c.ArcTo(new Point(cx + Math.Cos(a1) * r, cy + Math.Sin(a1) * r), new Size(r, r), 0,
(t1 - t0) * SweepDeg > 180, SweepDirection.Clockwise);
c.EndFigure(false);
}
return g;
}
}