dat.gui/API.md
2020-04-22 11:03:00 +02:00

18 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.add(object, property, values) ⇒ Controller

Adds a new Controller to the GUI. The type of controller created is a <select> dropdown.

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
values Array Object

Example

// Add a dropdown controller.
var person = {name: 'Sam'};
gui.add(person, 'name', ['Sam', 'Alex', 'Ray']);
gui.add(person, 'name', {'Sam': 'Sammy', 'Alex': 'Alexis', 'Ray': 'Riley'});

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