Skip to content
This repository has been archived by the owner before Nov 9, 2022. It is now read-only.

google/paper-gui

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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:

Custom Property Description
--paper-gui-accent-color Accent used in the floating action button, toggle buttons, sliders, etc.
--paper-gui-accent-contrast-color Applied to fonts and icons where the background uses accent color (buttons)
--paper-gui-background-color Background color of the main dialog
--paper-gui-text-color Main color for text inputs, labels, dropdown values, etc.
--paper-gui-ui-color Used in components (borders, sliders, input placeholders, etc.)
--paper-gui-ui-secondary-color Lighter shade of the above color, used in scrollbars and dividers
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.

Custom Mixin Description
--paper-gui-edit-button Use this to customize the edit button
--paper-gui-dialog Use this to override the size and positioning of the dialog (eg to place it in a different corner)
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});)

Property name Type Description
autoPlace Boolean Whether to automatically append the PaperGUI element to the DOM as soon as at least one controller has been added. Default is true.

PaperGUI methods

PaperGUI has several methods.

Method name Description
add() Creates and returns a new UI controller (controller type varies depending on the arguments, see next section).
el() Returns the main Element for this PaperGUI (ie a paper-gui component). Useful for attaching it to the DOM manually when autoPlace is disabled.
open() Opens the dialog containing the controllers. Equivalent to clicking the edit button.
close() Closes the dialog containing the controllers. Equivalent to clicking the close button in the dialog.
hide() Hides all PaperGUI elements (edit button, dialog with controllers). Equivalent to pressing the 'H' key.
show() Shows all previously hidden PaperGUI elements.

Controller types

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

PaperGUI Controller type Property type Extra parameters
Button Function N/A
Toggle Boolean N/A
Text input String N/A
Select box String [String value] An array of accepted values for the property, required to create a select box instead of a text input)
Slider Number Number minValue (optional, default 0), Number maxValue (optional, default 100)
Select box Number {String label: Number value} An object whose property names will be used as labels and corresponding values will be set on the property when selected. Required to create a select box instead of a slider.

Controller methods

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

Method Description Controller types
name(labelString) Defines the label or placeholder text for the controller All
onChange(callbackFunction) Calls the function when the value changes All except Button
min(minNumber) Sets the minimum authorized value Slider
max(minNumber) Sets the maximum authorized value Slider
step(stepNumber) Sets the step size Slider

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?)

About

A clone of dat.GUI using nice Polymer paper elements.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published