dat.gui is a lightweight controller library for JavaScript. It allows you to easily manipulate variables and fire functions on the fly.
+
+
- -
-
- Download the minified source [11kb] +
- Contribute on GitHub! -
dat.gui is a lightweight controller library for JavaScript. + It allows you to easily manipulate variables and fire functions on the fly. +
--
+
- Download the minified source + [11kb] + + -
- Contribute on GitHub! +
Basic Usage
+Basic Usage
<script type="text/javascript" src="gui.min.js"></script>
<script type="text/javascript">
@@ -141,11 +147,10 @@ window.onload = function() {
gui.add(fizzyText, "message");
// Sliders with min + max
- gui.add(fizzyText, "maxSize", 0.5, 7);
- gui.add(fizzyText, "growthSpeed", 0.01, 1);
- gui.add(fizzyText, "speed", 0.1, 2);
+ gui.add(fizzyText, "maxSize").min(0.5).max(7);
+ gui.add(fizzyText, "growthSpeed").min(0.01).max(1).step(0.05);
+ gui.add(fizzyText, "speed", 0.1, 2, 0.05); // shorthand for min/max/step
- // Sliders with min, max and increment.
gui.add(fizzyText, "noiseStrength", 10, 100, 5);
// Boolean checkbox
@@ -159,37 +164,48 @@ window.onload = function() {
</script>
- -
-
- dat.gui will infer the type of the property you're trying to add
- (based on its initial value) and create the corresponding control.
+ - dat.gui will infer the type of the property you're trying
+ to add
+ (based on its initial value) and create the corresponding control. +
- - The properties must be public, i.e. defined by
this.prop = value.
- - dat.gui panels are resizeable. Drag the show/hide button. +
- Press 'H' to show/hide GUI's. - -
- dat.gui panels are resizeable. Drag the show/hide + button. + + +
- Press 'H' to show/hide GUI's. +
-
+
Saving your parameters
-The simplest way to save your parameters is via DAT.GUI.saveURL(). This method directs your browser to a URL containing the current GUI settings.
Saving your parameters
+ +The simplest way to save your parameters is via
+ DAT.GUI.saveURL(). This method directs your browser to a
+ URL containing the current GUI settings.
// Make a button for the url function gui.add(DAT.GUI, "saveURL");-
Advanced saving
-Let's say you'd like to share your settings with someone. Instead of sending a long link with lots of parameters stored in it, you can make your saved settings the defaults.
+Advanced saving
-First, add the method DAT.GUI.showSaveString() to a gui object:
Let's say you'd like to share your settings with someone. Instead of + sending a long link with lots of parameters stored in it, you can make + your saved settings the defaults.
+ +First, add the method DAT.GUI.showSaveString() to a gui
+ object:
var gui = new DAT.GUI(); // Add some stuff (and pretend I change their values); @@ -199,7 +215,9 @@ gui.add(someObject, "someOtherProperty"); // Make a save button. gui.add(DAT.GUI, "showSaveString");-
Clicking the "showSaveString" button bring up an alert with a string. Copy and paste that string into the method DAT.GUI.load() before you instantiate any gui objects.
Clicking the "showSaveString" button bring up an alert with a string.
+ Copy and paste that string into the method DAT.GUI.load()
+ before you instantiate any gui objects.
// Replace COPIED STRING with the value you got from showSaveString()
DAT.GUI.load("COPIED STRING");
@@ -210,58 +228,78 @@ var gui = new DAT.GUI();
gui.add(someObject, "someProperty");
gui.add(someObject, "someOtherProperty");
- Save strings won't work if you change the order in which you've added properties to your gui objects, or the order of the gui objects themselves.. If you want to add more parameters to your gui and use an old save string, make sure they're added after the properties whose values you've saved.
-Save strings won't work if you change the order in + which you've added properties to your gui objects, or the order of the + gui objects themselves.. If you want to add more parameters to + your gui and use an old save string, make sure they're added after the + properties whose values you've saved.
Choosing from a list of values
-Choosing from a list of values
+ +gui.add(obj, "propertyName").options(1, 2, 3, 5, 8);
// Alternatively, you can specify custom labels using object syntax
gui.add(obj, "propertyName").options({'Small': 1, 'Medium': 2, 'Large': 3});
- Listen for variable changes inside the GUI
-To fire a function whenever a user changes a variable via the GUI, use the following syntax:
+Listen for variable changes inside the GUI
+ +To fire a function whenever a user changes a variable via the GUI, use + the following syntax:
gui.add(obj, "propertyName").onChange(function(newValue) {
alert("You changed me to " + newValue);
-}); This can be slightly annoying for types like number or string. You may not want to fire a function while the user is sliding, or while they're typing. To fire a function when the user has finished making changes, use the following:
+}); +This can be slightly annoying for types like number or string. You may + not want to fire a function while the user is sliding, or while they're + typing. To fire a function when the user has finished making + changes, use the following:
gui.add(obj, "propertyName").onFinishChange(function(newValue) {
alert("You just finished changing me to " + newValue);
});
- Finally, if you'd like to do a little something extra when a function is called, use the following:
+Finally, if you'd like to do a little something extra when a function + is called, use the following:
gui.add(obj, "functionName").onFire(function() {
alert("You called a function with dat.gui");
});
- Listen for variable changes outside of the GUI
-Let's say you have a variable that changes by itself from time to time. If you'd like the DAT.GUI to reflect those changes, use the listen() method.
gui.add(obj, "changingProperty").listen();-
Listen for variable changes outside of the GUI
+ +Let's say you have a variable that changes by itself from time to time.
+ If you'd like the DAT.GUI to reflect those changes, use the listen()
+ method.
gui.add(obj, "changingProperty").listen();
Advanced listening
-By default, dat.gui will create an internal interval that checks for changes in the values you've marked with listen(). If you'd like to check for these changes in an interval of your own definition, use the following:
Advanced listening
+ +By default, dat.gui will create an internal interval
+ that checks for changes in the values you've marked with
+ listen(). If you'd like to check for these changes in an
+ interval of your own definition, use the following:
gui.autoListen = false; // disables internal interval
gui.add(obj, "changingProperty").listen();
@@ -271,7 +309,9 @@ setInterval(function() {
gui.listen(); // updates values you've marked with listen()
}, 1000 / 60);
- Alternatively, you can forego calling listen() on individual controllers, and instead choose to monitor changes in all values controlled by your gui.
Alternatively, you can forego calling listen() on
+ individual controllers, and instead choose to monitor changes in
+ all values controlled by your gui.
gui.autoListen = false; // disables internal interval
gui.add(obj, "add");
@@ -282,15 +322,17 @@ gui.add(obj, "properties");
setInterval(function() {
gui.listenAll(); // updates ALL values managed by this gui
}, 1000 / 60);
- Multiple panels and custom placement
-You can instantiate multiple DAT.GUI objects and name them however you'd like.
Multiple panels and custom placement
+ +You can instantiate multiple DAT.GUI objects and name them
+ however you'd like.
var gui1 = new DAT.GUI();
var gui2 = new DAT.GUI();
@@ -298,7 +340,10 @@ var gui2 = new DAT.GUI();
gui1.name("Utilities");
gui2.name("Camera Placement");
- By default, dat.gui panels will be automatically added to the HTML document and fixed to the top of the screen. You can disable this behavior / styling and append the gui DOM element to a container of your choosing.
+By default, dat.gui panels will be automatically added + to the HTML document and fixed to the top of the screen. You can disable + this behavior / styling and append the gui DOM element to a container of + your choosing.
// Notice this belongs to the DAT.GUI class (uppercase)
// and not an instance thereof.
@@ -312,26 +357,31 @@ gui.domElement.style.top = "20px";
gui.domElement.style.left = "20px";
document.getElementById("my-gui-container").appendChild( gui.domElement );
- Pro tips.
--
-
Pro tips.
--
+