Table of Contents

Class ValueControl

Namespace
PluginUI
Assembly
PluginUI.dll

Control editing a normalized value [0, 1], optionally bound to an IParameter. Provides the gesture protocol, quantization, default value, fine adjustment and the value bubble.

public abstract class ValueControl : Control
Inheritance
ValueControl
Derived
Inherited Members

Examples

Unbound use (UI state that is not a plug-in parameter):

var mix = new Slider(Orientation.Horizontal) { Label = "MIX", Value = 0.5 };
var readout = new Label("50 %");
mix.ValueChanged += (_, _) => readout.Text = InvariantNumber.Format(mix.Value * 100, "0") + " %";

Remarks

Bound (Parameter set): the parameter is the source of truth; user edits go through BeginEdit() / PerformEdit(double) / EndEdit() and parameter changes (host automation, presets) repaint the control.

Unbound: the value is stored locally and ValueChanged notifies the application.

Properties

AcceptsModulation

Accepts ModulationSource drops from a ModulationSourceButton: the control lights up while a source hovers it and raises ModulationDropped on drop.

public bool AcceptsModulation { get; set; }

Property Value

bool

DefaultValue

Default normalized value (double-click / Ctrl+click reset).

public double DefaultValue { get; set; }

Property Value

double

DragSensitivity

Pixels of mouse travel for the full range (drag controls).

public float DragSensitivity { get; set; }

Property Value

float

FineFactor

Sensitivity multiplier while Shift is held.

public float FineFactor { get; set; }

Property Value

float

Formatter

Custom value formatter (normalized → text). Defaults to the parameter's text, or a percentage.

[Browsable(false)]
public Func<double, string>? Formatter { get; set; }

Property Value

Func<double, string>

IsEditing

true during a user gesture.

public bool IsEditing { get; }

Property Value

bool

IsMidiLearning

true while the bound parameter waits for a MIDI controller (MidiLearn).

[Browsable(false)]
public bool IsMidiLearning { get; }

Property Value

bool

IsModulationDropTarget

true while a modulation source is dragged over this control.

[Browsable(false)]
public bool IsModulationDropTarget { get; }

Property Value

bool

Parameter

Bound parameter (null = local value).

public IParameter? Parameter { get; set; }

Property Value

IParameter

ResetOnControlClick

Ctrl+click resets to DefaultValue.

public bool ResetOnControlClick { get; set; }

Property Value

bool

ResetOnDoubleClick

Double-click resets to DefaultValue (default true). On controls that accept typed values, a double-click on the value text opens the text box instead (see TextEntryTriggers).

public bool ResetOnDoubleClick { get; set; }

Property Value

bool

ShowValueBubble

Shows a bubble with the value while the user edits it.

public bool ShowValueBubble { get; set; }

Property Value

bool

StateIndex

Index of the current discrete state.

public int StateIndex { get; }

Property Value

int

StepCount

0 = continuous; otherwise number of discrete steps (parameter's when bound).

public int StepCount { get; set; }

Property Value

int

SupportsTextEntry

true if this control can open a text box to type its value (see BeginTextEntry()).

protected virtual bool SupportsTextEntry { get; }

Property Value

bool

TextEntryTriggers

Actions that open the in-place text box to type a value (default Default). Only used by controls that support typed values (SupportsTextEntry), such as Knob and Slider.

public TextEntryTriggers TextEntryTriggers { get; set; }

Property Value

TextEntryTriggers

Value

Current normalized value. Setting it on a bound control performs a complete single-step edit gesture.

public double Value { get; set; }

Property Value

double

ValueText

Text drawn in the value area (null = no value area).

public override string? ValueText { get; }

Property Value

string

WheelStep

Value change per wheel notch (continuous values).

public double WheelStep { get; set; }

Property Value

double

Methods

BeginGesture()

Starts a user edit gesture.

protected void BeginGesture()

BeginTextEntry()

Opens the in-place text box to type a value. Does nothing on controls that do not support typed values (SupportsTextEntry is false) or when the control is not attached to a host.

public virtual void BeginTextEntry()

EndGesture()

Ends the user edit gesture.

protected void EndGesture()

FormatValue(double)

Formats a normalized value for display (with units).

public string FormatValue(double normalized)

Parameters

normalized double

Returns

string

GetSkinState(Rect)

State passed to skins.

protected override SkinState GetSkinState(Rect widgetBounds)

Parameters

widgetBounds Rect

Returns

SkinState

GetToolTipText()

Tooltip actually shown: ToolTip by default. Override to supply a computed or localized text (for example from Strings) when ToolTip is not set.

protected override string? GetToolTipText()

Returns

string

The text to show, or null / empty for no tooltip.

Remarks

While MIDI learning, shows MidiLearnWaiting.

IsOverValueText(Point)

true if position is over the value text drawn by the control (the value area of LayoutParts(VectorStyle, out Rect, out Rect, out Rect)). Override for controls that draw their value elsewhere.

protected virtual bool IsOverValueText(Point position)

Parameters

position Point

A point in host coordinates (DIP).

Returns

bool

true if the point is over the value text.

OnAttached()

Called when the element joins a host (subscribe to external events here).

protected override void OnAttached()

OnCaptureLost()

The mouse capture was lost without a button release.

protected override void OnCaptureLost()

OnDetached()

Called when the element leaves its host (unsubscribe here).

protected override void OnDetached()

OnDragLeave()

Internal drag left this element.

protected override void OnDragLeave()

OnDragOver(DragEventArgs)

Internal drag over this element: set Accept to accept.

protected override void OnDragOver(DragEventArgs e)

Parameters

e DragEventArgs

OnDrop(DragEventArgs)

Internal drop on this element.

protected override void OnDrop(DragEventArgs e)

Parameters

e DragEventArgs

OnKeyDown(KeyEventArgs)

Key pressed while focused (bubbles to parents).

protected override void OnKeyDown(KeyEventArgs e)

Parameters

e KeyEventArgs

OnMouseWheel(MouseEventArgs)

Mouse wheel over the element.

protected override void OnMouseWheel(MouseEventArgs e)

Parameters

e MouseEventArgs

OnRenderOverlay(DrawingContext)

Draws the keyboard focus ring.

protected override void OnRenderOverlay(DrawingContext dc)

Parameters

dc DrawingContext

Remarks

Adds the modulation drop highlight and the MIDI learn outline.

OnValueChanged()

Called after every value change; raises ValueChanged and repaints.

protected virtual void OnValueChanged()

Quantize(double)

Rounds to the nearest step for discrete values.

public double Quantize(double normalized)

Parameters

normalized double

Returns

double

ResetToDefault()

Resets to DefaultValue as a user gesture.

public void ResetToDefault()

SetValueByUser(double)

Complete single-step gesture (click, wheel, keyboard, reset).

protected void SetValueByUser(double normalized)

Parameters

normalized double

TryHandleReset(MouseEventArgs)

Handles the reset shortcuts (double-click, Ctrl+click). Returns true if the press was consumed. Call from OnMouseDown(MouseEventArgs) overrides before starting a drag.

protected bool TryHandleReset(MouseEventArgs e)

Parameters

e MouseEventArgs

Returns

bool

TryHandleTextEntry(MouseEventArgs)

Handles the text-entry shortcuts selected by TextEntryTriggers (double-click on the value text, Alt+click, right double-click…). Returns true if the press opened the text box. Call from OnMouseDown(MouseEventArgs) overrides before TryHandleReset(MouseEventArgs).

protected bool TryHandleTextEntry(MouseEventArgs e)

Parameters

e MouseEventArgs

The mouse-down event.

Returns

bool

true if the event was consumed.

UpdateGesture(double)

Changes the value during a gesture (quantized, clamped).

protected void UpdateGesture(double normalized)

Parameters

normalized double

Events

GestureEnded

Raised when a user gesture ends.

public event Action<ValueControl>? GestureEnded

Event Type

Action<ValueControl>

GestureStarted

Raised when a user gesture starts.

public event Action<ValueControl>? GestureStarted

Event Type

Action<ValueControl>

ModulationDropped

Raised when a modulation source is dropped on this control (AcceptsModulation).

public event Action<ValueControl, ModulationSource>? ModulationDropped

Event Type

Action<ValueControl, ModulationSource>

ValueChanged

Raised when the value changes (user, code, or bound parameter).

public event Action<ValueControl, double>? ValueChanged

Event Type

Action<ValueControl, double>
Edit this page