diff --git a/.bowerrc b/.bowerrc index 12c76c5..603834e 100644 --- a/.bowerrc +++ b/.bowerrc @@ -1,3 +1,3 @@ { - "directory": "../components" + "directory": "../" } diff --git a/README.md b/README.md index 44cb127..28fad05 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # dat-gui -With very little code, dat gui creates an interface that you can use to modify variables. +dat-gui creates an interface that you can use to modify variables with very little code. -## Basic Usage +### Basic Usage Download the [minified library]( todo ) and include it in your html. @@ -10,23 +10,17 @@ Download the [minified library]( todo ) and include it in your html. ``` -The following code makes a number box for the variable `object.someNumber`. - -```javascript -var gui = new Gui(); -gui.add( object, 'someNumber' ); -``` - -dat-gui decides what type of controller to use based on the variable's initial value. +Create controllers by adding objects and their properties. dat-gui chooses a controller based on the variable's initial value. ```javascript 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 ``` -## Constraining Input +### Limiting Input You can specify limits on numbers. A number with a min and max value becomes a slider. @@ -46,37 +40,27 @@ gui.add( text, 'message', [ 'pizza', 'chrome', 'hooray' ] ); gui.add( text, 'speed', { Stopped: 0, Slow: 0.1, Fast: 5 } ); ``` -## Color Controllers +### Color Controllers dat-gui has a color selector and understands many different representations of color. The following creates color controllers for color variables of different formats. ```javascript -var FizzyText = function() { +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 - this.color0 = "#ffae23"; // CSS string - this.color1 = [ 0, 128, 255 ]; // RGB array - this.color2 = [ 0, 128, 255, 0.3 ]; // RGB with alpha - this.color3 = { h: 350, s: 0.9, v: 0.3 }; // Hue, saturation, value +var gui = new Gui(); - // Define render logic ... +gui.addColor(text, 'color0'); +gui.addColor(text, 'color1'); +gui.addColor(text, 'color2'); +gui.addColor(text, 'color3'); -}; - -window.onload = function() { - - var text = new FizzyText(); - var gui = new Gui(); - - gui.addColor(text, 'color0'); - gui.addColor(text, 'color1'); - gui.addColor(text, 'color2'); - gui.addColor(text, 'color3'); - -}; ``` -## Events +### Events You can listen for events on individual controllers using an event listener syntax. @@ -93,9 +77,9 @@ controller.onFinishChange(function(value) { }); ``` -## Folders +### Folders & Comments -You can nest as many Gui's as you want. Nested Gui's act as collapsible folders. +You can nest as many dat-gui as you want. Nested dat-gui act as collapsible folders. ```javascript var gui = new Gui(); @@ -107,13 +91,17 @@ f1.add(text, 'noiseStrength'); var f2 = gui.addFolder('Letters'); f2.add(text, 'growthSpeed'); f2.add(text, 'maxSize'); -f2.add(text, 'message'); f2.open(); ``` +The comment method adds a tooltip to a controller. -## Saving Values +```javascript +f2.add(text, 'message').comment( 'This is the comment.' ); +``` + +### Saving Values Add a save menu to the interface by calling `gui.remember` on all the objects you've added to the Gui. @@ -126,20 +114,37 @@ gui.remember(fizzyText); // Add controllers ... ``` -Click the gear icon to change your save settings. You can either save your Gui's values to localStorage, or by copying and pasting a JSON object into your source code as follows: +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: ```javascript var fizzyText = new FizzyText(); -var gui = new Gui({ load: JSON }); +var gui = new Gui( { load: JSON } ); -gui.remember(fizzyText); +gui.remember( fizzyText ); // Add controllers ... ``` -## Save to disk +### Presets -dat-gui comes with a node server that listens for changes to your Gui and saves them to disk. This way you don't have to worry about losing your local storage or copying and pasting a JSON string. +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: + +```javascript +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. + +### Save to Disk + +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: @@ -147,20 +152,15 @@ First, run the node script: $ node gui-server ``` -Next, instantiate your Gui with a path to a JSON file to store settings. +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. ```javascript -var gui = new Gui( { save: 'path/to/file.json' } ); -gui.remember( fizzyText ); - -// Add controllers ... +var gui = new Gui( { load: 'path/to/file.json' } ); ``` -## Custom Placement +### Custom Placement -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`. +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`. ```javascript var gui = new Gui( { autoPlace: false } ); @@ -169,18 +169,16 @@ var customContainer = document.getElementById('my-gui-container'); customContainer.appendChild(gui.domElement); ``` -## HTML Elements - -Since dat-gui is built using [Web Components]( todo ), you can use HTML syntax to add controllers to the page. +Since dat-gui is built using [Web Components]( todo ), you can also use HTML syntax to add controllers to the page. ```html - + + +``` diff --git a/TODO b/TODO new file mode 100644 index 0000000..6766aa8 --- /dev/null +++ b/TODO @@ -0,0 +1,10 @@ +- [ ] can gui-row be baked into base-controller somehow? + + +- [ ] folders + +- [ ] string controller +- [ ] boolean controller +- [ ] function controller +- [ ] color controller + diff --git a/bower.json b/bower.json index ad1094d..012af5c 100644 --- a/bower.json +++ b/bower.json @@ -1,7 +1,7 @@ { "name": "polymer-gui", "version": "0.0.0", - "description": "Attempt at revamping dat.gui with Polymyer.", + "description": "Attempt at revamping dat.gui with Polymer.", "keywords": [ "gui" ], @@ -19,5 +19,8 @@ ], "dependencies": { "polymer": "Polymer/polymer#~0.3.5" + }, + "devDependencies": { + "underscore": "~1.6.0" } } diff --git a/build/gui.html b/build/gui.html index 5b1a5bc..fd13350 100644 --- a/build/gui.html +++ b/build/gui.html @@ -1,4 +1,3 @@ - - - - - + - - el = elements[ i ]; - el.top = el.offsetTop; - - el.spacer = el.cloneNode( true ); - el.spacer.id = ''; - el.spacer.style.position = 'fixed'; - el.spacer.style.visibility = 'hidden'; - el.spacer.style.zIndex = i; - el.spacer.classList.add( 'sticky' ); - - el.parentElement.insertBefore( el.spacer, el ); - el.spacer.height = el.spacer.offsetHeight; - - if ( i > 0 ) { - elements[ i - 1 ].next = el; - } - - } - - function onScroll() { - - for ( var el, i = 0, l = elements.length; i < l; i++ ) { - - el = elements[ i ]; - - var sticky = window.scrollY > el.top && window.scrollY <= el.next.top; - el.spacer.style.visibility = sticky ? 'visible' : 'hidden'; - - if ( el.next && sticky ) { - - var bottom = window.scrollY + el.spacer.height; - var marginTop = Math.round( Math.min( 0, el.next.top - bottom ) ); - el.spacer.style.marginTop = marginTop + 'px'; - el.spacer.classList.toggle( -marginTop ); - - } - - } - } - - document.addEventListener( 'scroll', onScroll ); - -})(); - + + \ No newline at end of file diff --git a/test/runner.html b/test/runner.html new file mode 100644 index 0000000..f520875 --- /dev/null +++ b/test/runner.html @@ -0,0 +1,35 @@ + + + + dat-gui Test Runner (Mocha) + + + + + +
+ + + + + + + + + + + + + + + + + + + \ No newline at end of file