Knob

Introduction

A knob button based on circular progress shape.

  • Author: Rex
  • Game object

Live demos

Usage

Sample code

Install plugin

Load minify file

  • Load plugin (minify file) in preload stage
    scene.load.scenePlugin('rexuiplugin', 'https://raw.githubusercontent.com/rexrainbow/phaser3-rex-notes/master/dist/rexuiplugin.min.js', 'rexUI', 'rexUI');
    
  • Add knob object
    var knob = scene.rexUI.add.knob(config);
    

Import plugin

  • Install rex plugins from npm
    npm i phaser3-rex-plugins
    
  • Install plugin in configuration of game
    import UIPlugin from 'phaser3-rex-plugins/templates/ui/ui-plugin.js';
    var config = {
        // ...
        plugins: {
            scene: [{
                key: 'rexUI',
                plugin: UIPlugin,
                mapping: 'rexUI'
            },
            // ...
            ]
        }
        // ...
    };
    var game = new Phaser.Game(config);
    
  • Add knob object
    var knob = scene.rexUI.add.knob(config);
    

Import class

  • Install rex plugins from npm
    npm i phaser3-rex-plugins
    
  • Import class
    import { Knob } from 'phaser3-rex-plugins/templates/ui/ui-components.js';
    
  • Add knob object
    var knob = new Knob(scene, config);
    sscene.add.existing(knob);
    

Add knob object

var knob = scene.rexUI.add.knob({
    // x: 0,
    // y: 0,
    // anchor: undefined,
    // width: undefined,
    // height: undefined,

    background: backgroundGameObject,

    color: undefined,
    trackColor: undefined,
    centerColor: undefined,
    thickness: 0.2,
    startAngle: Phaser.Math.DegToRad(270),
    anticlockwise: false,
    knobDepth: 0,

    text: undefined,
    textColor: undefined,
    textStrokeColor: undefined,
    textStrokeThickness: undefined,
    textSize: '16px',
    textFamily: 'Courier',
    textStyle: '',
    textFormatCallback: undefined,
    textFormatCallbackScope: undefined,

    input: 'pan',

    value: 0,
    gap: undefined,
    easeValue: {
        duration: 0,
        ease: 'Linear'
    },
    valuechangeCallback: function(newValue, oldValue, knob) {
    },

    space: {
        left: 0,
        right: 0,
        top: 0,
        bottom: 0,
    },

    enable: true,

    // name: '',
    // draggable: false
});
  • x, y : Position of this object, it is valid when this object is the top object.
  • anchor : See anchor.
    • left, right, centerX, x, top, bottom, centerY, y : Position based on visible window, which composed of
      • Percentage of visible width/height : 'p%', p: 0 ~ 100.
        • 'left'(=0%), 'center'(=50%), 'right'(=100%)
        • 'top'(=0%), 'center'(=50%), 'bottom'(=100%)
      • Offset : '+n', or '-n'.
  • width, height : Minimum width, minimum height.
  • background : Game object of background, optional. This background game object will be resized to fit the size of knob.
  • color : Color of circular bar, in number or css string value.
  • trackColor : Color of circular track, in number or css string value.
  • centerColor : Color of center circle, in number or css string value.
  • thickness : 0 ~ 1, thickness of circular bar. Default value is 0.2 (0.2*radius)
  • startAngle : Start angle of circular bar, in radians. Default value is 270 degrees.
  • anticlockwise : Set true to put anticlockwise circular bar. Default value is false.
  • knobDepth : Depth of knob (circular progress). Default value is 0.
  • text : Label, Text, BBCodeText, or TagText, which has setText(text) method, optional.
    • Don't set textColor, textStrokeColor if text parameter is provided.
    • Depth of text object ought to larger than knob (circular progress), to put text object in front of knob.
  • Display text :
    • textColor : Color of display text. Default is undefined.
    • textStrokeColor, textStrokeThickness : Stroke color, stroke line width of display text. Default is undefined.
    • textSize, textFamily, textStyle : Size, family, style of display text.
  • textFormatCallback, textFormatCallbackScope : Formating callback of display text. ex:
    function(value) {
        return Math.floor(value * 100).toString();
    }
    
    Default value is undefined.
  • input :
    • 'pan', or 0 : Control knob by panning circular progress. Default setting.
    • 'click', or 1 : Control knob by touching circular progress.
    • 'none', or -1 : Disable knob controlling.
  • value : Initial value (0 ~ 1).
  • gap : Snap a value to nearest grid slice, using rounding.
    • undefined : Disalbe this feature.
  • easeValue : Easing value when input is 'click'.
    • easeValue.duration : Duration of value easing, default is 0 (no easing).
    • easeValue.ease : Ease function, default is 'Linear'.
  • valuechangeCallback : callback function when value changed.
  • space : Pads spaces
    • space.left, space.right, space.top, space.bottom : Space of bounds.
  • enable : Set false to disable controlling.
  • name : Set name of this knob.

Custom class

  • Define class
    class MyKnob extends RexPlugins.UI.Knob {
        constructor(scene, config) {
            super(scene, config);
            // ...
            scene.add.existing(this);
        }
        // ...
    }
    
  • Create instance
    var knob = new MyKnob(scene, config);
    

Layout children

Arrange position of all elements.

knob.layout();

See also - dirty

Get element

  • Get element
    • Background game object
      var background = knob.getElement('background');
      
    • Circular progress game object
      var circularProgress = knob.getElement('knob');
      
    • Text game object
      var text = knob.getElement('text');
      
  • Get by name
    var gameObject = knob.getElement('#' + name);
    // var gameObject = knob.getElement('#' + name, recursive);
    
    or
    var gameObject = knob.getByName('#' + name);
    // var gameObject = knob.getByName('#' + name, recursive);
    
    • recursive : Set true to search all children recursively.

Value

Change value will also change the position of knob thumb and width of knob indicator.

  • Get value
    var value = knob.getValue(min, max); // value : min ~ max
    
    or
    var value = knob.getValue(); // value: 0 ~ 1
    
    or
    var value = knob.value; // value: 0 ~ 1
    
  • Set value
    knob.setValue(value, min, max); // value: min ~ max
    
    or
    knob.setValue(value); // value: 0 ~ 1
    
    or
    knob.value = value; // value: 0 ~ 1
    
  • Increase value
    knob.addValue(inc, min, max); // inc: min ~ max
    
    or
    knob.addValue(inc); // inc: 0 ~ 1
    
    or
    knob.value += inc; // inc: 0 ~ 1
    

Ease value

  • Ease value to
    knob.easeValueTo(value, min, max);  // value: min ~ max
    
    or
    knob.easeValueTo(value);  // value: 0 ~ 1
    
  • Stop ease
    knob.stopEaseValue();
    
  • Set ease duration
    knob.setEaseValueDuration(duration);
    
  • Set ease function
    knob.setEaseValueFunction(ease);
    

Other properties

See overlap sizer object, base sizer object.

Events

  • On value changed
    knob.on('valuechange', function(newValue, oldValue, knob){
        //
    }, scope);