dat-gui creates an interface that you can use to modify variables with very little code.
Basic Usage • Limits • @@ -25,72 +26,64 @@ Saving
Download the minified library and include it in your html.
-<script src="gui.js"></script>
-<script src="gui.js"></script>Create controllers by adding objects and their properties. dat-gui chooses a controller based on the variable's initial value.
-var gui = new Gui();
-gui.add( object, 'numberProperty', 0, 1 ); // Slider
-gui.add( object, 'stringProperty' ); // Text box
-gui.add( object, 'booleanProperty' ); // Check box
-gui.add( object, 'functionProperty' ); // Button
-var gui = new Gui();
+gui.add( object, 'numberProperty', 0, 1 ); // Slider
+gui.add( object, 'stringProperty' ); // Text box
+gui.add( object, 'booleanProperty' ); // Check box
+gui.add( object, 'functionProperty' ); // ButtonYou can specify limits on numbers. A number with a min and max value becomes a slider.
-gui.add( text, 'growthSpeed', -5, 5 ); // Min and max
-gui.add( text, 'noiseStrength' ).step( 5 ); // Increment amount
-gui.add( text, 'maxSize' ).min( 0 ).step( 0.25 ); // Mix and match
-gui.add( text, 'growthSpeed', -5, 5 ); // Min and max
+gui.add( text, 'noiseStrength' ).step( 5 ); // Increment amount
+gui.add( text, 'maxSize' ).min( 0 ).step( 0.25 ); // Mix and matchYou can also provide a list of accepted values for a dropdown.
-// Choose from accepted values
-gui.add( text, 'message', [ 'pizza', 'chrome', 'hooray' ] );
+// Choose from accepted values
+gui.add( text, 'message', [ 'pizza', 'chrome', 'hooray' ] );
-// Choose from named values
-gui.add( text, 'speed', { Stopped: 0, Slow: 0.1, Fast: 5 } );
-
+// Choose from named values
+gui.add( text, 'speed', { Stopped: 0, Slow: 0.1, Fast: 5 } );dat-gui has a color selector and understands many different representations of color. The following creates color controllers for color variables of different formats.
-text.color0 = "#ffae23"; // CSS string
-text.color1 = [ 0, 128, 255 ]; // RGB array
-text.color2 = [ 0, 128, 255, 0.3 ]; // RGB with alpha
-text.color3 = { h: 350, s: 0.9, v: 0.3 }; // Hue, saturation, value
+text.color0 = "#ffae23"; // CSS string
+text.color1 = [ 0, 128, 255 ]; // RGB array
+text.color2 = [ 0, 128, 255, 0.3 ]; // RGB with alpha
+text.color3 = { h: 350, s: 0.9, v: 0.3 }; // Hue, saturation, value
var gui = new Gui();
-gui.addColor(text, 'color0');
-gui.addColor(text, 'color1');
-gui.addColor(text, 'color2');
-gui.addColor(text, 'color3');
-
+gui.addColor(text, 'color0');
+gui.addColor(text, 'color1');
+gui.addColor(text, 'color2');
+gui.addColor(text, 'color3');You can listen for events on individual controllers using an event listener syntax.
-var controller = gui.add(fizzyText, 'maxSize', 0, 10);
+var controller = gui.add(fizzyText, 'maxSize', 0, 10);
-controller.onChange(function(value) {
- // Fires on every change, drag, keypress, etc.
+controller.onChange(function(value) {
+ // Fires on every change, drag, keypress, etc.
});
-controller.onFinishChange(function(value) {
- // Fires when a controller loses focus.
- alert("The new value is " + value);
-});
-
+controller.onFinishChange(function(value) {
+ // Fires when a controller loses focus.
+ alert("The new value is " + value);
+});You can nest as many dat-gui as you want. Nested dat-gui act as collapsible folders.
-var gui = new Gui();
+var gui = new Gui();
-var f1 = gui.addFolder('Flow Field');
-f1.add(text, 'speed');
-f1.add(text, 'noiseStrength');
+var f1 = gui.addFolder('Flow Field');
+f1.add(text, 'speed');
+f1.add(text, 'noiseStrength');
-var f2 = gui.addFolder('Letters');
-f2.add(text, 'growthSpeed');
-f2.add(text, 'maxSize');
+var f2 = gui.addFolder('Letters');
+f2.add(text, 'growthSpeed');
+f2.add(text, 'maxSize');
-f2.open();
-
+f2.open();The comment method adds a tooltip to a controller.
-f2.add(text, 'message').comment( 'This is the comment.' );
-f2.add(text, 'message').comment( 'This is the comment.' );Add a save menu to the interface by calling gui.remember on all the objects you've added to the Gui.
var fizzyText = new FizzyText();
@@ -98,59 +91,52 @@ var gui = new Gui();
gui.remember(fizzyText);
-// Add controllers ...
-Click the gear icon to change your save settings. You can either save your dat-gui values to localStorage, or by copying and pasting a JSON object into your source code as follows:
var fizzyText = new FizzyText();
var gui = new Gui( { load: JSON } );
gui.remember( fizzyText );
-// Add controllers ...
-The save menu also allows you to save all of your settings as presets. Click Save to modify the current preset, or New to create a new preset from existing settings. Clicking Revert will clear all unsaved changes to the current preset.
Switch between presets using the dropdown in the save menu. You can specify the default like this:
-var gui = new Gui({
- load: JSON,
- preset: 'Flow'
-});
-var gui = new Gui({
+ load: JSON,
+ preset: 'Flow'
+});A word of caution about localStorage:
Paste the JSON save object into your source frequently. Using localStorage to save presets can make you faster, but its easy to lose your settings by clearing browsing data, changing browsers, or even by changing the URL of the page you're working on.
dat-gui comes with a node server that saves your settings to disk. This way you don't have to worry about losing your values to local storage or copying and pasting a JSON string.
First, run the node script:
-$ node gui-server
-$ node gui-serverNext, instantiate your Gui with a path to a JSON file to store settings. dat-gui will read from this file on load and write to this file on change.
-var gui = new Gui( { load: 'path/to/file.json' } );
-var gui = new Gui( { load: 'path/to/file.json' } );By default, Gui panels are created with fixed position, and are automatically appended to the body. You can change this behavior by setting the autoPlace parameter to false.
var gui = new Gui( { autoPlace: false } );
+var gui = new Gui( { autoPlace: false } );
-var customContainer = document.getElementById('my-gui-container');
-customContainer.appendChild(gui.domElement);
-
+var customContainer = document.getElementById('my-gui-container');
+customContainer.appendChild(gui.domElement);Since dat-gui is built using Web Components, you can also use HTML syntax to add controllers to the page.
-<body>
+<body>
-<dat-gui-number min="-2" max="2" step="1" value="0"></dat-gui-number>
+<dat-gui-number min="-2" max="2" step="1" value="0"></dat-gui-number>
-<script>
+<script>
-var controller = document.querySelector( 'dat-gui-number' );
-controller.onChange( function() {
+var controller = document.querySelector( 'dat-gui-number' );
+controller.onChange( function() {
- // react to UI changes ...
+ // react to UI changes ...
} );
-</script>
+</script>
-</body>
-
+</body>dat-gui uses Polymer under the hood to define custom elements. A dat-gui controller is just a Polymer element with two important requirements:
Take for example this (simplified) source for dat-gui's <dat-gui-number>:
Polymer( 'dat-gui-number', {
+Polymer( 'dat-gui-number', {
- // Define element ...
+ // Define element ...
} );
-Gui.register( 'dat-gui-number', function( value ) {
+Gui.register( 'dat-gui-number', function( value ) {
- return typeof value == 'number';
+ return typeof value == 'number';
-} );
-
+} );Gui.register takes an element name and a test function. The test function tells dat-gui to add a <dat-gui-number> to the panel when the user adds a variable whose type is 'number'.
A test function determines if a controller is appropriate for a given value. This example registers <vector-controller> for values that have properties x, y and z.
Gui.register( 'vector-controller', function( value ) {
+Gui.register( 'vector-controller', function( value ) {
- return value.hasOwnProperty( 'x' ) &&
- value.hasOwnProperty( 'y' ) &&
- value.hasOwnProperty( 'z' );
+ return value.hasOwnProperty( 'x' ) &&
+ value.hasOwnProperty( 'y' ) &&
+ value.hasOwnProperty( 'z' );
-} );
-
+} );You should use Bower and format your plugin all nice and it should have a certain prefix yada yada.
Installing third-party controllers ...
-$ bower install gui-three
-$ bower install gui-threeInclude the source for the third-party controllers after dat-gui.
-<script src="gui.js"></script>
-<script src="gui-three.js"></script>
-<script src="gui.js"></script>
+<script src="gui-three.js"></script>