TK.Ranged

TK.Ranged combines functionality for two distinct purposes. Firstly, TK.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 TK.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 Toolkit to translate values (e.g. in Hz or dB) to pixel positions or percentages, for instance in widgets such as TK.Scale, TK.MeterBase or TK.Graph.

TK.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 TK.Ranged~scale_cb. This allows the definition of custom coordinate transformations, which go beyond the standard types.

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 TK.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.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 snapped 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 TK.ScrollValue as the step size.
options.shift_up Number <optional>
 4

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

Multiplier for descresed stepping speed, e.g. used by TK.ScrollValue when simultaneously pressing 'shift' and 'ctrl'.
Source:

Type Definitions

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

Parameters:
Name Type Attributes Default Description
value number

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

An object containing initial options. - The options of the corresponding TK.Ranged object.
inverse boolean <optional>
 false

Determines if the value is to be transformed from or to the coordinate system.
Source:
Returns:

The transformed value.

Type
number

Methods

based2val(value, basisopt) → {number}

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

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

coef2val(value) → {number}

Calls based2val with basis = 1.

Parameters:
Name Type Description
value number
Source:
Returns:
Type
number

px2val(value) → {number}

This is an alias for TK.Ranged#px2val.

Parameters:
Name Type Description
value number
Source:
Returns:
Type
number

snap(value) → {number}

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.
Source:
Returns:

The snapped value.

Type
number

snap_down(value) → {number}

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

Parameters:
Name Type Description
value number

The value to snap.
Source:
Returns:

The snapped value.

Type
number

snap_up(value) → {number}

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

Parameters:
Name Type Description
value number

The value to snap.
Source:
Returns:

The snapped value.

Type
number

val2based(value, basisopt) → {number}

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

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

val2coef(value) → {number}

Calls based2val with basis = 1.

Parameters:
Name Type Description
value number
Source:
Returns:
Type
number

val2px(value) → {number}

This is an alias for TK.Ranged#val2px.

Parameters:
Name Type Description
value number
Source:
Returns:
Type
number