TK.Ranged

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 Ranged 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.

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 integer | function <optional>
"linear"

The type of the scale. Either one of "linear", "decibel", "log2", "frequency" or "frequency-reverse"; 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>
0

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

Minimum value of the range

options.max number

Maximum value of the range

options.log_factor number <optional>
1

Used to range logarithmic curves.

options.snap number | Array.<number> <optional>
0

This option defines the 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 base <optional>
0

Base point.

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, options, inverse) → {number}

Parameters:
Name Type Description
value number

The value to be transformed.

options Object

The options of the corresponding Ranged object.

inverse boolean

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

Source:
Returns:

The transformed value.

Type
number

Methods

based2val(value, basis) → {number}

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

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

coef2val(value) → {number}

Calls based2val with basis = 1.

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

perc2val(value) → {number}

Calls based2val with basis = 100.

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

real2val(value) → {number}

Calls based2val with basis = options.basis.

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, basis) → {number}

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

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

val2coef(value) → {number}

Calls based2val with basis = 1.

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

val2perc(value) → {number}

Calls based2val with basis = 100.

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

val2px(value) → {number}

This is an alias for TK.Ranged#val2real.

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

val2real(value) → {number}

Calls based2val with basis = options.basis.

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