papergui v0.2.1

PaperGUI

A clone of dat.GUI using nice Polymer (1.0) paper elements. One of the advantages is that this makes it touch and mobile friendly. The API is intentionally similar, although not all features have been ported to PaperGUI.

Install

Building requires node, gulp and bower.

npm install gulp bower
npm install
npm run-script build

The dist folder contains the build. The paper-gui.html file is the only one you need if you want to use web component-style, synchronous import. Otherwise, you'll need all 3 files in the dist folder as paperGUI.js loads the other two.

To try out the demo, run a webserver in the papergui root folder, eg:

python -m SimpleHTTPServer 8000

Then open http://localhost:8000/demo.html in a browser.

Usage

Basic usage

With very little code, PaperGUI creates an interface that you can use to modify variables, exactly like dat.GUI from which the below example is adapted.

<script type="text/javascript">
var FizzyText = function() {
  this.message = 'PaperGUI';
  this.speed = 0.8;
  this.displayOutline = false;
  this.explode = function() { ... };
  // Define render logic ...
};

/* Polymer elements are loaded asynchronously, we need to wait for
 * everything to be ready before creating the GUI. */
document.addEventListener('PaperGUIReady', function(e) {
  var text = new FizzyText();
  var gui = new PaperGUI();
  gui.add(text, 'message');
  gui.add(text, 'speed', -5, 5);
  gui.add(text, 'displayOutline');
  gui.add(text, 'explode');
};
</script>

<!-- Load the PaperGUI library and polyfills -->
<script type="text/javascript" src="dist/paperGUI.js"></script>

• The property must be public, i.e. defined by this.prop = value
• PaperGUI determines controller type based on a property's initial value
• Press H to show/hide all GUI's.

Importing PaperGUI as a web component

As shown above, the paperGUI.js script loads a polyfill and then imports the web components necessary for the PaperGUI library to work. Once it's all set, it triggers a PaperGUIReady event. This allows to delay the loading of PaperGUI as much as possible.

Alternatively, you can skip the loader script call and use a (blocking) import directly. Add this at the top of your HTML:

<link rel="import" href="dist/paper-gui.html">

Note that in this case no PaperGUIReady event will be triggered, and the import will only work on web component-ready browsers as this bypasses support detection and polyfill loading.

Constrain

You can specify limits on numbers. A number with a min and max value becomes a slider. This is exactly the same API as dat.GUI.

gui.add(text, 'noiseStrength').step(5); // Increment amount
gui.add(text, 'growthSpeed', -5, 5); // Min and max
gui.add(text, 'maxSize').min(0).step(0.25); // Mix and match

You can also choose to select from a dropdown of values for both numbers and strings.

// 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 } );

Events

You can listen for events on individual controllers using an event listener syntax.

var controller = gui.add(fizzyText, 'maxSize', 0, 10);


controller.onChange(function(value) {
  // Fires on every change, drag, keypress, etc.
});

Note: the onFinishChange handler from dat.GUI is currently not supported.

Styling & positioning

PaperGUI exposes custom CSS properties and mixins (see Polymer documentation) through which you can change the colors and style of the UI.

Custom properties

Properties below can be used to modify the default colors of the PaperGUI interface and components:

Example

In your main html file, declare the following custom-style to override default colors:

<style is="custom-style">
  paper-gui {
    --paper-gui-text-color: #808080;
    --paper-gui-background-color: white;
    --paper-gui-accent-color: #1976d2;
    --paper-gui-ui-color: #bbb;
    --paper-gui-ui-secondary-color: #f1f1f1;
  }
</style>

Mixins

If you need to further customize the edit button or the dialog, ie change their positioning or size, you can use dedicated custom mixins.

Example

In your main html file:

<style is="custom-style">
  paper-gui {
    --paper-gui-edit-button: {
      position: relative;
      top: 0;
      left: 0;
    };
    --paper-gui-dialog: {
      position: absolute;
      top: auto;
      right: auto;
      bottom: 0;
      left: 0;
      width: 50%;
    };
  }
</style>

Reference

PaperGUI constructor parameters

The PaperGUI constructor can accept an object containing various options (eg. var gui = new PaperGUI({autoPlace: false});)

PaperGUI methods

PaperGUI has several methods.

Controller types

Here's a summary of the controller types PaperGUI currently supports:

Controller methods

All controller methods return themselves, allowing to chain method calls. Here is a list of methods.

TODO

• Add live demos
• Add folders/tabs structure capability and other features from the original dat.GUI

Known issues

• Select box change callback fires on controller creation (intended?)