Ranged

Ranged

Source:
Properties:
Name Type Attributes Default Description
options.scale String | Array.<Number> | function <optional>
 "linear"

The type of the scale. Either one of linear, decibel, log2, frequency or frequency-reverse; or an array containing a piece-wise linear scale; or a callback function of type Ranged~scale_cb.
options.reverse Boolean <optional>
 false

Reverse the scale of the range.
options.basis Number <optional>
 1

The size of the linear scale. Set to pixel width or height if used for drawing purposes or to 100 for percentages.
options.clip Boolean <optional>
 true

If true, snap() will clip values into the interval between min and max.
options.min Number <optional>
 0

Minimum value of the range.
options.max Number <optional>
 1

Maximum value of the range.
options.log_factor Number <optional>
 1

Used to overexpand logarithmic curves. 1 keeps the natural curve while values above 1 will overbend.
options.snap Number | Array.<number> <optional>
 0

Defines a virtual grid. If options.snap is a positive number, it is interpreted as the distance of grid points. Then, inside of the interval options.min ... options.max the grid points are options.base + n * options.snap where n is any integer. Any values outside of that interval are rounded to the biggest or smallest grid point, respectively. In order to define grids with non-uniform spacing, set options.snap to an Array of grid points.
options.base Number <optional>
 0

Base point. Used e.g. to mark 0dB on a fader from -96dB to 12dB.
options.step Number <optional>
 0

Step size. Used for instance by ScrollValue as the step size.
options.shift_up Number <optional>
 4

Multiplier for increased stepping speed, e.g. used by ScrollValue when simultaneously pressing 'shift'.
options.shift_down Number <optional>
 0.25

Multiplier for decreased stepping speed, e.g. used by ScrollValue when simultaneously pressing 'shift' and 'ctrl'.

Ranged combines functionality for two distinct purposes. Firstly, Ranged can be used to snap values to a virtual grid. This grid is defined by the options snap, step, min, max and base. The second feature of anged is that it allows transforming values between coordinate systems. This can be used to transform values from and to linear scales in which they are displayed on the screen. It is used inside of AUX to translate values (e.g. in Hz or dB) to pixel positions or percentages, for instance in widgets such as Scale, Meter or Graph.

Ranged features several types of coordinate systems which are often used in audio applications. They can be configured using the options.scale option, possible values are:

  • linear for linear coordinates,
  • decibel for linear coordinates,
  • log2 for linear coordinates,
  • frequency for linear coordinates or
  • frequency-reverse" for linear coordinates.
If options.scale is a function, it is used as the coordinate transformation. Its signature is Ranged~scale_cb. This allows the definition of custom coordinate transformations, which go beyond the standard types.

Methods

basedToValue(value, basisopt) → {number}

Source:

Transforms a value from the interval 0...basis to the coordinate system.

Parameters:
Name Type Attributes Default Description
value number
basis number <optional>
 1
Returns:
Type
number

coefToValue(value) → {number}

Source:

Calls basedToValue with basis = 1.

Parameters:
Name Type Description
value number
Returns:
Type
number

pixelToValue(value) → {number}

Source:

This is an alias for Ranged#pixelToValue.

Parameters:
Name Type Description
value number
Returns:
Type
number

snap(value) → {number}

Source:

Returns the nearest value on the grid. Its rounding behavior is similar to that of Math.round.

Parameters:
Name Type Description
value number

The value to snap.
Returns:

The snapped value.

Type
number

snapDown(value) → {number}

Source:

Returns the nearest value on the grid which is smaller than value.

Parameters:
Name Type Description
value number

The value to snap.
Returns:

The snapped value.

Type
number

snapUp(value) → {number}

Source:

Returns the nearest value on the grid which is bigger than value.

Parameters:
Name Type Description
value number

The value to snap.
Returns:

The snapped value.

Type
number

valueToBased(value, basisopt) → {number}

Source:

Transforms a value from the coordinate system to the interval 0...basis.

Parameters:
Name Type Attributes Default Description
value number
basis number <optional>
 1
Returns:
Type
number

valueToCoef(value) → {number}

Source:

Calls basedToValue with basis = 1.

Parameters:
Name Type Description
value number
Returns:
Type
number

valueToPixel(value) → {number}

Source:

This is an alias for Ranged#valueToPixel.

Parameters:
Name Type Description
value number
Returns:
Type
number

Type Definitions

scale_cb(value, optionsopt, inverseopt) → {number}

Source:
Parameters:
Name Type Attributes Default Description
value number

The coordinate value to be transformed.
options Object <optional>
 { }

The options of the corresponding Ranged object.
inverse boolean <optional>
 false

If true, the function should return the inverse transform.
Returns:

The transformed value.

Type
number