473 lines (351 loc) · 16.4 KB

dat.GUI API

Details about the classes, methods, and properties provided by dat.GUI. For more hands-on examples, see the dat.GUI tutorial.

Classes

GUI: A lightweight controller library for JavaScript. It allows you to easily manipulate variables and fire functions on the fly.
Controller: An "abstract" class that represents a given property of an object.
NumberController ⇐ dat.controllers.Controller: Represents a given property of an object that is a number.

GUI

A lightweight controller library for JavaScript. It allows you to easily manipulate variables and fire functions on the fly.

Kind: global class

GUI
- new GUI([params])
- .domElement : DOMElement
- .parent : dat.gui.GUI
- .autoPlace : Boolean
- .closeOnTop : Boolean
- .preset : String
- .width : Number
- .name : String
- .closed : Boolean
- .load : Object
- .useLocalStorage : Boolean
- .add(object, property, [min], [max], [step]) ⇒ Controller
- .addColor(object, property) ⇒ Controller
- .remove(controller)
- .destroy()
- .addFolder(name) ⇒ dat.gui.GUI
- .removeFolder(folder)
- .open()
- .close()
- .getRoot() ⇒ dat.gui.GUI
- .getSaveObject() ⇒ Object

new GUI([params])

Param	Type	Default	Description
[params]	`Object`
[params.name]	`String`		The name of this GUI.
[params.load]	`Object`		JSON object representing the saved state of this GUI.
[params.parent]	`dat.gui.GUI`		The GUI I'm nested in.
[params.autoPlace]	`Boolean`	`true`
[params.hideable]	`Boolean`	`true`	If true, GUI is closed by the `h` keypress.
[params.closed]	`Boolean`	`false`	If true, starts closed
[params.closeOnTop]	`Boolean`	`false`	If true, close/open button shows on top of the GUI

Example

// Creating a GUI with options.
var gui = new dat.GUI({name: 'My GUI'});

Example

// Creating a GUI and a subfolder.
var gui = new dat.GUI();
var folder1 = gui.addFolder('Flow Field');

gui.domElement : `DOMElement`

Outermost DOM Element

Kind: instance property of GUI

gui.parent : `dat.gui.GUI`

The parent GUI

Kind: instance property of GUI

gui.autoPlace : `Boolean`

Handles GUI's element placement for you

Kind: instance property of GUI

gui.closeOnTop : `Boolean`

Handles GUI's position of open/close button

Kind: instance property of GUI

gui.preset : `String`

The identifier for a set of saved values

Kind: instance property of GUI

gui.width : `Number`

The width of GUI element

Kind: instance property of GUI

gui.name : `String`

The name of GUI. Used for folders. i.e a folder's name

Kind: instance property of GUI

gui.closed : `Boolean`

Whether the GUI is collapsed or not

Kind: instance property of GUI

gui.load : `Object`

Contains all presets

Kind: instance property of GUI

gui.useLocalStorage : `Boolean`

Determines whether or not to use localStorage as the means for remembering

Kind: instance property of GUI

gui.add(object, property, [min], [max], [step]) ⇒ `Controller`

Adds a new Controller to the GUI. The type of controller created is inferred from the initial value of object[property]. For color properties, see addColor.

Kind: instance method of GUI
Returns: Controller - The controller that was added to the GUI.

Param	Type	Description
object	`Object`	The object to be manipulated
property	`String`	The name of the property to be manipulated
[min]	`Number`	Minimum allowed value
[max]	`Number`	Maximum allowed value
[step]	`Number`	Increment by which to change value

Example

// Add a string controller.
var person = {name: 'Sam'};
gui.add(person, 'name');

Example

// Add a number controller slider.
var person = {age: 45};
gui.add(person, 'age', 0, 100);

gui.addColor(object, property) ⇒ `Controller`

Adds a new color controller to the GUI.

Kind: instance method of GUI
Returns: Controller - The controller that was added to the GUI.

Param
object
property

Example

var palette = {
  color1: '#FF0000', // CSS string
  color2: [ 0, 128, 255 ], // RGB array
  color3: [ 0, 128, 255, 0.3 ], // RGB with alpha
  color4: { h: 350, s: 0.9, v: 0.3 } // Hue, saturation, value
};
gui.addColor(palette, 'color1');
gui.addColor(palette, 'color2');
gui.addColor(palette, 'color3');
gui.addColor(palette, 'color4');

gui.remove(controller)

Removes the given controller from the GUI.

Kind: instance method of GUI

Param	Type
controller	`Controller`

gui.destroy()

Removes the root GUI from the document and unbinds all event listeners. For subfolders, use gui.removeFolder(folder) instead.

Kind: instance method of GUI

gui.addFolder(name) ⇒ `dat.gui.GUI`

Creates a new subfolder GUI instance.

Kind: instance method of GUI
Returns: dat.gui.GUI - The new folder.
Throws:

Error if this GUI already has a folder by the specified name

Param
name

gui.removeFolder(folder)

Removes a subfolder GUI instance.

Kind: instance method of GUI

Param	Type	Description
folder	`dat.gui.GUI`	The folder to remove.

gui.open()

Opens the GUI.

Kind: instance method of GUI

gui.close()

Closes the GUI.

Kind: instance method of GUI

gui.getRoot() ⇒ `dat.gui.GUI`

Kind: instance method of GUI
Returns: dat.gui.GUI - the topmost parent GUI of a nested GUI.

gui.getSaveObject() ⇒ `Object`

Kind: instance method of GUI
Returns: Object - a JSON object representing the current state of this GUI as well as its remembered properties.

Controller

An "abstract" class that represents a given property of an object.

Kind: global class

Controller
- new Controller(object, property)
- .domElement : DOMElement
- .object : Object
- .property : String
- .options(options) ⇒ Controller
- .name(name) ⇒ Controller
- .listen() ⇒ Controller
- .remove() ⇒ Controller
- .onChange(fnc) ⇒ Controller
- .onFinishChange(fnc) ⇒ Controller
- .setValue(newValue)
- .getValue() ⇒ Object
- .updateDisplay() ⇒ Controller
- .isModified() ⇒ Boolean

new Controller(object, property)

Param	Type	Description
object	`Object`	The object to be manipulated
property	`string`	The name of the property to be manipulated

controller.domElement : `DOMElement`

Those who extend this class will put their DOM elements in here.

Kind: instance property of Controller

controller.object : `Object`

The object to manipulate

Kind: instance property of Controller

controller.property : `String`

The name of the property to manipulate

Kind: instance property of Controller

controller.options(options) ⇒ `Controller`

Kind: instance method of Controller

Param	Type
options	`Array` \| `Object`

controller.name(name) ⇒ `Controller`

Sets the name of the controller.

Kind: instance method of Controller

Param	Type
name	`string`

controller.listen() ⇒ `Controller`

Sets controller to listen for changes on its underlying object.

Kind: instance method of Controller

controller.remove() ⇒ `Controller`

Removes the controller from its parent GUI.

Kind: instance method of Controller

controller.onChange(fnc) ⇒ `Controller`

Specify that a function fire every time someone changes the value with this Controller.

Kind: instance method of Controller
Returns: Controller - this

Param	Type	Description
fnc	`function`	This function will be called whenever the value is modified via this Controller.

controller.onFinishChange(fnc) ⇒ `Controller`

Specify that a function fire every time someone "finishes" changing the value wih this Controller. Useful for values that change incrementally like numbers or strings.

Kind: instance method of Controller
Returns: Controller - this

Param	Type	Description
fnc	`function`	This function will be called whenever someone "finishes" changing the value via this Controller.

controller.setValue(newValue)

Change the value of object[property]

Kind: instance method of Controller

Param	Type	Description
newValue	`Object`	The new value of `object[property]`

controller.getValue() ⇒ `Object`

Gets the value of object[property]

Kind: instance method of Controller
Returns: Object - The current value of object[property]

controller.updateDisplay() ⇒ `Controller`

Refreshes the visual display of a Controller in order to keep sync with the object's current value.

Kind: instance method of Controller
Returns: Controller - this

controller.isModified() ⇒ `Boolean`

Kind: instance method of Controller
Returns: Boolean - true if the value has deviated from initialValue

NumberController ⇐ `dat.controllers.Controller`

Represents a given property of an object that is a number.

Kind: global class
Extends: dat.controllers.Controller

NumberController ⇐ dat.controllers.Controller
- new NumberController(object, property, [params])
- .min(minValue) ⇒ dat.controllers.NumberController
- .max(maxValue) ⇒ dat.controllers.NumberController
- .step(stepValue) ⇒ dat.controllers.NumberController

new NumberController(object, property, [params])

Param	Type	Description
object	`Object`	The object to be manipulated
property	`string`	The name of the property to be manipulated
[params]	`Object`	Optional parameters
[params.min]	`Number`	Minimum allowed value
[params.max]	`Number`	Maximum allowed value
[params.step]	`Number`	Increment by which to change value

numberController.min(minValue) ⇒ `dat.controllers.NumberController`

Specify a minimum value for object[property].

Kind: instance method of NumberController
Returns: dat.controllers.NumberController - this

Param	Type	Description
minValue	`Number`	The minimum value for `object[property]`

numberController.max(maxValue) ⇒ `dat.controllers.NumberController`

Specify a maximum value for object[property].

Kind: instance method of NumberController
Returns: dat.controllers.NumberController - this

Param	Type	Description
maxValue	`Number`	The maximum value for `object[property]`

numberController.step(stepValue) ⇒ `dat.controllers.NumberController`

Specify a step value that dat.controllers.NumberController increments by.

Kind: instance method of NumberController
Default: if minimum and maximum specified increment is 1% of the difference otherwise stepValue is 1
Returns: dat.controllers.NumberController - this

Param	Type	Description
stepValue	`Number`	The step value for dat.controllers.NumberController