Skip to content

Latest commit

 

History

History
141 lines (95 loc) · 9.56 KB

README.md

File metadata and controls

141 lines (95 loc) · 9.56 KB

Audials

Alternative to HTML5 range (slider) inspired by DAWs, kinda like dials. Audials.

Some very easy to achieve styles (the third is not wrong, its range is -50..60). You'll find the HTML / JavaScript required to achieve these in usage.html:

Audials Styles

Usage

There are four usage types corresponding to two functionality styles and two display styles.

Gain functionality style:

This dial goes from the range minimum to the range maximum, left to right. The range would typically be 0..100.

Balance functionality style:

This dial goes from the range minimum to the range maximum, left to right, The range would typically be -50..50.

Notch display style:

This style shows the current value as a single notch or line on the control.

Fill display style:

This style Shows the current value as a fill from left to right on a gain control or, for a balance control, a fill from the centre-top to either the left or right.

<script src="es5/tk-audials.min.js"></script>
<link rel="stylesheet" media="all" href="build/tk-audials.min.css">
...
<div id="gain-notch" class="tk-audial"></div>
<div id="balance-notch" class="tk-audial"></div>
<div id="gain-fill" class="tk-audial"></div>
<div id="balance-fill" class="tk-audial"></div>
<script>
  var gainNotch = document.querySelector('#gain-notch');
  var balanceNotch = document.querySelector('#balance-notch');
  var gainFill = document.querySelector('#gain-fill');
  var balanceFill = document.querySelector('#balance-fill');
  var gainNotchButton = new TkAudial(gainNotch);
  var balanceNotchButton = new TkAudial(balanceNotch, {type:'balance',display:'notch',min:-50,max:50,value:12});
  var gainFillButton = new TkAudial(gainFill, {type:'gain',display:'fill'});
  var balanceFillButton = new TkAudial(balanceFill, {type:'balance',display:'fill',min:-50,max:50,value:12,inputId:'unique-id'});
</script>

Will result in something like this:

Audials Layout

A working implementation is provided in usage.html.

The dials will scale to fill their container which should have the class tk-audial.

You can use the ES6 version from the build folder or the ES5 version from the build/es5 folder. Currently only the ES5 version is published.

Options

The first argument when instantiating TkAudial is its HTML container element. The second is an optional options object of optional options:

{
  type: (String) Either 'gain' or 'balance'. Default is gain,
  display: (String) Either 'notch' or 'fill'. Default is notch,
  min: (Number) Range start. Default is 0,
  max: (Number) Range end. Default is 100,
  step: (Number) Legal interval. 0.01..n (values are rounded to two decimal places) Default is 1,
  sensitivityMultiplier: (Number) A global modifier unique to the individual control. Intended to make dials with very large or very small ranges more user friendly. Default is 1,
  alwaysMultiply: (Boolean) If false the sensitivityMultiplier will only be applied if the user has activated a key or touch modifier. Default is true,
  value: (Number) Initial value. Default is 50,
  borderColour: (String) Style value (EG white, #, rgb, rgba). Default is null,
  borderWidth: (Number) Default is 8,
  indicatorBackgroundColour: (String) Style value (EG white, #, rgb, rgba). Default is null,
  indicatorColour: (String) Style value (EG white, #, rgb, rgba). Default is null,
  indicatorWidth: (Number) Default is 15,
  valueBackgroundColour:  (String) Style value (EG white, #, rgb, rgba). Default is null,
  valueColour: (String) Style value (EG white, #, rgb, rgba). Default is null,
  valueFontSize: (String) Style value (EG 1.2em, 22px, 12pt, 90%). Default is 1em,
  inputId: (String) used for name and id of a hidden form input. Input is not generated if this option is omitted,
  zeroModifiers: (Boolean) Set touch modifier count to zero when releasing a dial. Default is false,
  enableClipboard: (Boolean) Add the control value to the clipboard when releasing a dial. Default is false
}

See Known Issues for details regarding the zeroModifiers option.

Dial element colours are null by default to allow them to be defined in CSS. Any styles specified in the options object will become inline styles.

If the hoverHTML options is non-null then this HTML will display when hovering and modifying the dial. Use $value within the HTML to inject the dials value. On touch devices the hoverHTML will display once modification of the dial occurs.

Number type options are generally rounded to two decimal places. The initial value option is rounded to the nearest valid step (and also the same number of decimal places as the step provided). If your minimum and maximum values don't match the step the final step will be reduced.

Everything in the TkAudial object is public. Your application can read and write values for options at runtime to manipulate behavior if you wish. Note that this is untested territory and you need to make sure you supply valid values. Using dial.setValue(value) is preferable to setting dial.value as it will be rounded according to the current value for step for you. On that note, know that the value supplied when instantiating TkAudial is not saved to dial.options.value but to dial.options.

Events

When the value is changed the changed event is emitted by the container (that is passed as he first argument to TkAudial). A changed event is also emitted by the TkAudial class itself and can be subscribed to. The addEventListener method of the TkAudial object uses only the event name and callback parameters (useCapture is not required nor is it used if specified). These events are not triggered by setValue.

The changed event on the DOM container object may be removed in the future.

Methods

All methods are in the prototype so you can take a look and call anything you need to. The only methods that would typically be needed though are setValue(value) where value is a number (which will be rounded to the same number of decimal places as the step option) and getValue() which returns a number whose precision will also match that of the step option.

Modifiers

For large ranges it may be useful to use the alt and shift modifiers which double and treble the sensitivity of the dial. They are also cumulative so using both would sextuple the sensitivity. Using the modifiers will reduce accuracy but they can be triggered mid-drag so you can use them to quickly get close to where you need to be then release them to achieve the precise value you need.

Touch modifiers are slightly different. The sensitivity of the dial is multiplied by the number of touches detected. Modifier touches can be added while moving the dial by using your other hand for example. Touch modifiers are detected anywhere on the screen.

The sensitivityMultiplier option is applied by default. For large ranges this will result in a loss of precision. If this is deemed an issue then the alwaysMultiply option can be set to false in which case the sensitivityMultiplier is applied only when a key or touch modifier is active.

Use a sensitivityMultiplier of 0<n<1 for small ranges (EG 0.5; zero will effectively disable the control). This will increase the distance required to send the dial from its minimum to its maximum value. A sensitivityMultiplier greater than 1 will similarly decrease the distance required to send a small range dial from its minimum to its maximum value.

Pipeline

Looking into an intuitive way to copy and paste values between dials. Copy is done by the inclusion of clipboard.js. An intuitive way to indicate you want to paste a value to a control is required. Particularly on touch, a key modifier will be easy enough for desktop. UPDATE: Double click has been implemented for paste-to-dial. This will be considered complete when tested on touch devices. setValue currently adheres to the min and max options however, when pasting, this may be better if setValue aborts for invalid values. Maybe. Dunno.

Known issues

Selection of the control value as text when the control is not in use proved flaky. Especially in Safari. To select the text value of the control, start the selection outside the control. This works well enough on desktop. On iOS text selection causes a slight issue. Just touch and hold to select the text, this is fine. Starting the dial manipulation from the text though doesn't seem to set the text as non-selectable as well as desktop does. In this case the dial needs to be manipulated by its edges. Text selection is probably not particularly useful and this may soon all be avoided by have the control non-selectable at all times.

Safari on both desktop and iOS doesn't seem to completely get along with the modifiers. It's not fatal but it seems to get jumpy when triggering them sometimes.

For touch devices, touch mashing, or perhaps a cpu struggling device, can result in the touch count getting out of sync. This seems to be rare though. This may be dealt with by setting the touch count for a dial to zero when it is released. The zeroModifiers options has been added for this purpose. If this option is set to true, modifiers would have to be re-applied before or during manipulation of a dial. If you suspect modifier count sync is proving to be an issue, this can be applied.

The clipboard library is clipboard.js. Safari is not supported.

enabling the clipboard causes zoom issues for iOS. Hover display on dial modification doesn't follow the gesture well either. Fix is in progress.