2014-08-27 00:01:15 +00:00
<!doctype html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > dat-gui< / title >
2014-09-10 22:51:48 +00:00
< script src = "build/dat-gui.js" > < / script >
2014-08-27 00:01:15 +00:00
< link rel = "stylesheet" href = "docs/style.css" >
< / style >
< / head >
< body >
2014-09-01 03:54:59 +00:00
<!-- Copied from README.md -->
2014-09-15 02:48:00 +00:00
< div id = "readme" >
< h1 id = "dat-gui" > dat-gui< / h1 >
2014-08-27 00:01:15 +00:00
< p > dat-gui creates an interface that you can use to modify variables with very little code. < / p >
2014-09-03 16:16:11 +00:00
< p > < a href = "#basic-usage" > Basic Usage < / a > •
< a href = "#limits" > Limits < / a > •
< a href = "#colors" > Colors < / a > •
< a href = "#events" > Events < / a > •
< a href = "#folders" > Folders < / a > •
< a href = "#saving" > Saving < / a > < / p >
2014-08-27 00:01:15 +00:00
< h3 id = "basic-usage" > Basic Usage< / h3 >
< p > Download the < a href = "todo" > minified library< / a > and include it in your html.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-html" > < span class = "hljs-tag" > < < span class = "hljs-title" > script< / span > < span class = "hljs-attribute" > src< / span > =< span class = "hljs-value" > "gui.js"< / span > > < / span > < span class = "javascript" > < / span > < span class = "hljs-tag" > < /< span class = "hljs-title" > script< / span > > < / span > < / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > Create controllers by adding objects and their properties. dat-gui chooses a controller based on the variable' s initial value.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > var< / span > gui = < span class = "hljs-keyword" > new< / span > Gui();
gui.< span class = "hljs-keyword" > add< / span > ( object, < span class = "hljs-string" > 'numberProperty'< / span > , < span class = "hljs-number" > 0< / span > , < span class = "hljs-number" > 1< / span > ); < span class = "hljs-comment" > // Slider< / span >
gui.< span class = "hljs-keyword" > add< / span > ( object, < span class = "hljs-string" > 'stringProperty'< / span > ); < span class = "hljs-comment" > // Text box< / span >
gui.< span class = "hljs-keyword" > add< / span > ( object, < span class = "hljs-string" > 'booleanProperty'< / span > ); < span class = "hljs-comment" > // Check box< / span >
gui.< span class = "hljs-keyword" > add< / span > ( object, < span class = "hljs-string" > 'functionProperty'< / span > ); < span class = "hljs-comment" > // Button< / span > < / code > < / pre >
2014-09-03 16:16:11 +00:00
< h3 id = "limits" > Limits< / h3 >
2014-08-27 00:01:15 +00:00
< p > You can specify limits on numbers. A number with a min and max value becomes a slider.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > gui< / span > .< span class = "hljs-built_in" > add< / span > ( text, < span class = "hljs-string" > 'growthSpeed'< / span > , -< span class = "hljs-number" > 5< / span > , < span class = "hljs-number" > 5< / span > ); // Min < span class = "hljs-built_in" > and< / span > < span class = "hljs-built_in" > max< / span >
< span class = "hljs-keyword" > gui< / span > .< span class = "hljs-built_in" > add< / span > ( text, < span class = "hljs-string" > 'noiseStrength'< / span > ).step( < span class = "hljs-number" > 5< / span > ); // Increment amount
< span class = "hljs-keyword" > gui< / span > .< span class = "hljs-built_in" > add< / span > ( text, < span class = "hljs-string" > 'maxSize'< / span > ).< span class = "hljs-built_in" > min< / span > ( < span class = "hljs-number" > 0< / span > ).step( < span class = "hljs-number" > 0.25< / span > ); // Mix < span class = "hljs-built_in" > and< / span > < span class = "hljs-built_in" > match< / span > < / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > You can also provide a list of accepted values for a dropdown.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-comment" > // Choose from accepted values< / span >
gui.add( text, < span class = "hljs-string" > 'message'< / span > , [ < span class = "hljs-string" > 'pizza'< / span > , < span class = "hljs-string" > 'chrome'< / span > , < span class = "hljs-string" > 'hooray'< / span > ] );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-comment" > // Choose from named values< / span >
gui.add( text, < span class = "hljs-string" > 'speed'< / span > , { < span class = "hljs-string" > Stopped:< / span > < span class = "hljs-number" > 0< / span > , < span class = "hljs-string" > Slow:< / span > < span class = "hljs-number" > 0.1< / span > , < span class = "hljs-string" > Fast:< / span > < span class = "hljs-number" > 5< / span > } );< / code > < / pre >
2014-09-03 16:16:11 +00:00
< h3 id = "colors" > Colors< / h3 >
2014-08-27 00:01:15 +00:00
< p > dat-gui has a color selector and understands many different representations of color. The following creates color controllers for color variables of different formats.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > text< / span > .color0 = < span class = "hljs-string" > "#ffae23"< / span > ; < span class = "hljs-comment" > // CSS string< / span >
< span class = "hljs-keyword" > text< / span > .color1 = [ < span class = "hljs-number" > 0< / span > , < span class = "hljs-number" > 128< / span > , < span class = "hljs-number" > 255< / span > ]; < span class = "hljs-comment" > // RGB array< / span >
< span class = "hljs-keyword" > text< / span > .color2 = [ < span class = "hljs-number" > 0< / span > , < span class = "hljs-number" > 128< / span > , < span class = "hljs-number" > 255< / span > , < span class = "hljs-number" > 0.3< / span > ]; < span class = "hljs-comment" > // RGB with alpha< / span >
< span class = "hljs-keyword" > text< / span > .color3 = { h: < span class = "hljs-number" > 350< / span > , s: < span class = "hljs-number" > 0.9< / span > , v: < span class = "hljs-number" > 0.3< / span > }; < span class = "hljs-comment" > // Hue, saturation, value< / span >
2014-08-27 00:01:15 +00:00
var gui = new Gui();
2014-09-15 02:48:00 +00:00
gui.addColor(< span class = "hljs-keyword" > text< / span > , < span class = "hljs-string" > 'color0'< / span > );
gui.addColor(< span class = "hljs-keyword" > text< / span > , < span class = "hljs-string" > 'color1'< / span > );
gui.addColor(< span class = "hljs-keyword" > text< / span > , < span class = "hljs-string" > 'color2'< / span > );
gui.addColor(< span class = "hljs-keyword" > text< / span > , < span class = "hljs-string" > 'color3'< / span > );< / code > < / pre >
2014-08-27 00:01:15 +00:00
< h3 id = "events" > Events< / h3 >
< p > You can listen for events on individual controllers using an event listener syntax.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > var< / span > controller = gui.add(fizzyText, < span class = "hljs-string" > 'maxSize'< / span > , < span class = "hljs-number" > 0< / span > , < span class = "hljs-number" > 10< / span > );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
controller.onChange(< span class = "hljs-function" > < span class = "hljs-keyword" > function< / span > < span class = "hljs-params" > (value)< / span > < / span > {
< span class = "hljs-comment" > // Fires on every change, drag, keypress, etc.< / span >
2014-08-27 00:01:15 +00:00
});
2014-09-15 02:48:00 +00:00
controller.onFinishChange(< span class = "hljs-function" > < span class = "hljs-keyword" > function< / span > < span class = "hljs-params" > (value)< / span > < / span > {
< span class = "hljs-comment" > // Fires when a controller loses focus.< / span >
alert(< span class = "hljs-string" > "The new value is "< / span > + value);
});< / code > < / pre >
2014-09-03 16:16:11 +00:00
< h3 id = "folders" > Folders< / h3 >
2014-08-27 00:01:15 +00:00
< p > You can nest as many dat-gui as you want. Nested dat-gui act as collapsible folders.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > var < span class = "hljs-keyword" > gui< / span > = < span class = "hljs-keyword" > new< / span > Gui();
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
var f1 = < span class = "hljs-keyword" > gui< / span > .addFolder(< span class = "hljs-string" > 'Flow Field'< / span > );
f1.< span class = "hljs-built_in" > add< / span > (text, < span class = "hljs-string" > 'speed'< / span > );
f1.< span class = "hljs-built_in" > add< / span > (text, < span class = "hljs-string" > 'noiseStrength'< / span > );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
var f2 = < span class = "hljs-keyword" > gui< / span > .addFolder(< span class = "hljs-string" > 'Letters'< / span > );
f2.< span class = "hljs-built_in" > add< / span > (text, < span class = "hljs-string" > 'growthSpeed'< / span > );
f2.< span class = "hljs-built_in" > add< / span > (text, < span class = "hljs-string" > 'maxSize'< / span > );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
f2.< span class = "hljs-keyword" > open< / span > ();< / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > The comment method adds a tooltip to a controller.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > f2.add(text, < span class = "hljs-attribute" > 'message< / span > ').comment( < span class = "hljs-attribute" > 'This< / span > < span class = "hljs-keyword" > is< / span > the comment.' );< / code > < / pre >
2014-09-03 16:16:11 +00:00
< h3 id = "saving" > Saving< / h3 >
2014-08-27 00:01:15 +00:00
< p > Add a save menu to the interface by calling < code > gui.remember< / code > on all the objects you' ve added to the Gui.< / p >
< pre > < code class = "lang-javascript" > var fizzyText = new FizzyText();
var gui = new Gui();
gui.remember(fizzyText);
2014-09-15 02:48:00 +00:00
// Add controllers < span class = "hljs-keyword" > ...< / span > < / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > 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:< / p >
< pre > < code class = "lang-javascript" > var fizzyText = new FizzyText();
var gui = new Gui( { load: JSON } );
gui.remember( fizzyText );
2014-09-15 02:48:00 +00:00
// Add controllers < span class = "hljs-keyword" > ...< / span > < / code > < / pre >
2014-08-27 00:01:15 +00:00
< h3 id = "presets" > Presets< / h3 >
< p > 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.< / p >
< p > Switch between presets using the dropdown in the save menu. You can specify the default like this:< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > var< / span > gui = < span class = "hljs-keyword" > new< / span > Gui({
load: < span class = "hljs-built_in" > JSON< / span > ,
preset: < span class = "hljs-string" > 'Flow'< / span >
});< / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > A word of caution about localStorage:< / p >
< p > 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.< / p >
< h3 id = "save-to-disk" > Save to Disk< / h3 >
< p > 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.< / p >
< p > First, run the node script:< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-sh" > < span class = "hljs-variable" > $ < / span > node gui-server< / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > Next, 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.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-keyword" > var< / span > gui = < span class = "hljs-keyword" > new< / span > Gui( { load: < span class = "hljs-string" > 'path/to/file.json'< / span > } );< / code > < / pre >
2014-08-27 00:01:15 +00:00
< h3 id = "custom-placement" > Custom Placement< / h3 >
< p > By default, Gui panels are created with fixed position, and are automatically appended to the body. You can change this behavior by setting the < code > autoPlace< / code > parameter to < code > false< / code > .< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > < span class = "hljs-reserved" > var< / span > gui = < span class = "hljs-keyword" > new< / span > Gui( { < span class = "hljs-attribute" > autoPlace< / span > : < span class = "hljs-literal" > false< / span > } );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-reserved" > var< / span > customContainer = < span class = "hljs-built_in" > document< / span > .getElementById(< span class = "hljs-string" > 'my-gui-container'< / span > );
customContainer.appendChild(gui.domElement);< / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > Since dat-gui is built using < a href = "todo" > Web Components< / a > , you can also use HTML syntax to add controllers to the page.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-html" > < span class = "hljs-tag" > < < span class = "hljs-title" > body< / span > > < / span >
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-tag" > < < span class = "hljs-title" > dat-gui-number< / span > < span class = "hljs-attribute" > min< / span > =< span class = "hljs-value" > "-2"< / span > < span class = "hljs-attribute" > max< / span > =< span class = "hljs-value" > "2"< / span > < span class = "hljs-attribute" > step< / span > =< span class = "hljs-value" > "1"< / span > < span class = "hljs-attribute" > value< / span > =< span class = "hljs-value" > "0"< / span > > < / span > < span class = "hljs-tag" > < /< span class = "hljs-title" > dat-gui-number< / span > > < / span >
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-tag" > < < span class = "hljs-title" > script< / span > > < / span > < span class = "javascript" >
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-keyword" > var< / span > controller = < span class = "hljs-built_in" > document< / span > .querySelector( < span class = "hljs-string" > 'dat-gui-number'< / span > );
controller.onChange( < span class = "hljs-function" > < span class = "hljs-keyword" > function< / span > < span class = "hljs-params" > ()< / span > < / span > {
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-comment" > // react to UI changes ...< / span >
2014-08-27 00:01:15 +00:00
} );
2014-09-15 02:48:00 +00:00
< / span > < span class = "hljs-tag" > < /< span class = "hljs-title" > script< / span > > < / span >
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-tag" > < /< span class = "hljs-title" > body< / span > > < / span > < / code > < / pre >
2014-08-27 00:01:15 +00:00
< h3 id = "defining-custom-controllers" > Defining Custom Controllers< / h3 >
< p > dat-gui uses < a href = "todo" > Polymer< / a > under the hood to define custom elements. A dat-gui controller is just a < a href = "todo" > Polymer element< / a > with two important requirements:< / p >
< ul >
2014-09-09 19:53:30 +00:00
< li > Controllers must extend < code > < dat-gui-base> < / code > .< / li >
2014-08-27 00:01:15 +00:00
< li > Controllers must be associated with a data type.< / li >
< / ul >
2014-09-09 19:53:30 +00:00
< p > Take for example this (simplified) source for dat-gui' s < code > < dat-gui-number> < / code > :< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > Polymer( < span class = "hljs-string" > 'dat-gui-number'< / span > , {
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
// Define element < span class = "hljs-keyword" > ...< / span >
2014-08-27 00:01:15 +00:00
} );
2014-09-15 02:48:00 +00:00
Gui.register( < span class = "hljs-string" > 'dat-gui-number'< / span > , < span class = "hljs-keyword" > function< / span > ( value ) {
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-keyword" > return< / span > typeof value == < span class = "hljs-string" > 'number'< / span > ;
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
} );< / code > < / pre >
2014-09-09 19:53:30 +00:00
< p > < code > Gui.register< / code > takes an element name and a test function. The test function tells dat-gui to add a < code > < dat-gui-number> < / code > to the panel when the user adds a variable whose type is < code > ' number' < / code > .< / p >
2014-08-27 00:01:15 +00:00
< p > A test function determines if a controller is appropriate for a given value. This example registers < code > < vector-controller> < / code > for values that have properties < code > x< / code > , < code > y< / code > and < code > z< / code > .< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-javascript" > Gui.register( < span class = "hljs-string" > 'vector-controller'< / span > , function( < span class = "hljs-keyword" > value< / span > ) {
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
< span class = "hljs-keyword" > return< / span > < span class = "hljs-keyword" > value< / span > .hasOwnProperty( < span class = "hljs-string" > 'x'< / span > ) & &
< span class = "hljs-keyword" > value< / span > .hasOwnProperty( < span class = "hljs-string" > 'y'< / span > ) & &
< span class = "hljs-keyword" > value< / span > .hasOwnProperty( < span class = "hljs-string" > 'z'< / span > );
2014-08-27 00:01:15 +00:00
2014-09-15 02:48:00 +00:00
} );< / code > < / pre >
2014-08-27 00:01:15 +00:00
< h3 id = "publishing-custom-controllers" > Publishing Custom Controllers< / h3 >
< p > You should use < a href = "todo" > Bower< / a > and format your plugin all nice and it should have a certain prefix yada yada.< / p >
< p > Installing third-party controllers ... < / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-sh" > < span class = "hljs-variable" > $ < / span > bower install gui-three< / code > < / pre >
2014-08-27 00:01:15 +00:00
< p > Include the source for the third-party controllers after dat-gui.< / p >
2014-09-15 02:48:00 +00:00
< pre > < code class = "lang-html" > < span class = "hljs-tag" > < < span class = "hljs-title" > script< / span > < span class = "hljs-attribute" > src< / span > =< span class = "hljs-value" > "gui.js"< / span > > < / span > < span class = "javascript" > < / span > < span class = "hljs-tag" > < /< span class = "hljs-title" > script< / span > > < / span >
< span class = "hljs-tag" > < < span class = "hljs-title" > script< / span > < span class = "hljs-attribute" > src< / span > =< span class = "hljs-value" > "gui-three.js"< / span > > < / span > < span class = "javascript" > < / span > < span class = "hljs-tag" > < /< span class = "hljs-title" > script< / span > > < / span > < / code > < / pre >
2014-09-01 03:54:59 +00:00
< / div >
2014-08-27 00:01:15 +00:00
< script src = "docs/main.js" > < / script >
< script src = "docs/examples.js" > < / script >
< / body >
2014-09-10 22:51:48 +00:00
< / html >
