dat.gui/API.md
2019-03-29 21:43:20 -07:00

17 KiB

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.

NumberControllerdat.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

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 shown/hidden by 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.hide()

Hides the GUI.

Kind: instance method of GUI

gui.show()

Shows 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

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

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