Skip to content

API.md

Latest commit

 

History

History
733 lines (482 loc) · 17.6 KB

API.md

File metadata and controls

733 lines (482 loc) · 17.6 KB

GUI API

GUI

GUI folder that holds other folders and controllers.

Constructor

Parameter Type Default Description
parameters GUIParams {}
[parameters.parent] GUI Add the GUI as a child in another GUI.
[parameters.autoPlace] boolean Add the GUI to document.body and fix it to the top right of the page.
[parameters.container] HTMLElement Add the GUI to this DOM element (overrides autoPlace).
[parameters.width] number Width of the GUI in pixels.
[parameters.title] string 'Controls' Name to display in the title bar.
[parameters.closeFolders] boolean false Close all folders in the GUI by default.
[parameters.touchStyles] boolean true Make controllers larger on touch devices.

Properties

root

The top level GUI containing the GUI, or this if it is the root GUI.

GUI.root: readonly GUI;
parent

The GUI containing this GUI, or undefined if it is the root GUI.

GUI.parent?: readonly GUI;
children

The list of folders and controllers contained by the GUI.

GUI.children: readonly Array<GUI | Controller>;
folders

The list of folders contained by the GUI.

GUI.folders: readonly GUI[];
controllers

The list of controllers contained by the GUI.

GUI.controllers: readonly Controller[];
domElement

The outermost container element.

GUI.domElement: readonly HTMLElement;
$title

The DOM element that contains the title.

GUI.$title: readonly HTMLElement;
$children

The DOM element that contains children.

GUI.$children: readonly HTMLElement;

Methods

title(title)

Change the title of the GUI.

  • title: The title of the GUI.
GUI.title(title: string) => this;
add(object, property)

Add a controller to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
  • [$1] [$2] [$3]: Parameters depending on the controller's type. See controllers types for more details.
GUI.add(object: object, property: string, $1?: any, $2?: number, $3?: number): void;
addColor(object, property)

Add a controller to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
GUI.addColor(object: object, property: string): ColorController;
addCoords(object, property)

Add a 2D coords controller to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
  • [min]: Minimum value.
  • [max]: Maximum value.
  • [step]: Step value.
GUI.addCoords(object: object, property: string, min?: number, max?: number, step?: number): CoordsController
addAngle(object, property)

Add an angle controller to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
  • [step]: Step value.
GUI.addAngle(object: object, property: string, step?: number): AngleController;
addFile(object, property)

Add a file controller to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
  • [accept]: MIME type the file input should accept.
GUI.addFile(object: object, property: string, accept?: string): FileController;
addFolder(title)

Add a folder to the GUI.

  • title: Title to display in the folder's title bar.
GUI.addFolder(title: string): GUI;
addVector(object, property)

Add a vector folder to the GUI.

  • object: The object the controller will modify.
  • property: Name of the property to control.
  • [min]: Minimum value.
  • [max]: Maximum value.
  • [step]: Step value.
GUI.addVector(object: object, property: string, min?: number, max?: number, step?: number): GUI
show()

Show the GUI after it's been hidden.

  • [show=true]
GUI.show(show?: boolean): this;
hide()

Hide the GUI.

  • [hide=true]
GUI.hide(hide?: boolean): this;
open()

Open the GUI.

  • [open=true]
GUI.open(open?: boolean): this;
close()

Close the GUI.

  • [close=true]
GUI.close(close?: boolean): this;
openAnimated()

Animate the GUI opening/closing.

  • [open=true]
GUI.openAnimated(open?: boolean): this;
reset()

Reset all controllers to their initial values.

  • [recursive=true]: Pass false to exclude folders descending from the GUI.
GUI.reset(recursive?: boolean): this;
onChange(callback)

Pass a function to be called whenever a controller in the GUI changes.

  • callback: Function to call.
GUI.onChange(callback: Function): this;
onFinishChange(callback)

Pass a function to be called whenever a controller in the GUI has finished changing.

  • callback: Function to call.
GUI.onFinishChange(callback: Function): this;
onOpenClose(callback)

Pass a function to be called when the GUI or its descendants are opened or closed.

  • callback: Function to call.
GUI.onOpenClose(callback: Function): this;
load(data)

Re-call values that were saved with save().

  • data: Object to load values from.
  • [recursive=true]: Pass false to exclude folders descending from the GUI.
GUI.load(data: object, recursive?: boolean): this;
save()

Return an object mapping controller names to values. The object can be passed to load() to recall these values.

  • [recursive=true]: Pass false to exclude folders descending from the GUI.
GUI.save(recursive?: boolean): object;
foldersRecursive()

Return an Array of folders contained by the GUI and its descendents.

GUI.foldersRecursive(): GUI[];
controllersRecursive()

Return an Array of controllers contained by the GUI and its descendents.

GUI.controllersRecursive(): Controller[];
destroy()

Destroy all DOM elements and event listeners associated with the GUI.

GUI.destroy(): void;

Controller

Constructor

Parameter Type Default Description
parent GUI The GUI that contains the controller.
object object The object the controller will modify.
property string The name of the property to control.
className string '' A className to add to this controller DOM Element.
elementType string 'div' The tag name of the controller DOM Element.

Properties

id

Unique identifier of an instance of Controller.

Controller.id: readonly number;
parent

The GUI that contains the controller.

Controller.parent: readonly GUI;
object

The object this controller will modify.

Controller.object: readonly object;
property

The name of the property to control.

Controller.property: readonly string;
initialValue

The value of object[property] when the controller was created.

Controller.initialValue: readonly any;
domElement

The outermost container DOM element for the controller.

Controller.domElement: readonly HTMLElement;
$name

The DOM element that contains the controller's name.

Controller.$name: readonly HTMLElement;
$widget

The DOM element that contains the controller's widget (which differs by controller type).

Controller.$widget: readonly HTMLElement;
$disable

The DOM element that receives the disabled attribute when using disable().

Controller.$disable: readonly HTMLElement;

Methods

name(name)

Set the name of this controller and its label in the GUI.

  • name: The name of the controller.
Controller.name(name: string): this;
options()

Change the controller into a dropdown of options. Calling this method on an option controller will simply update the options.

  • options: Options object.
Controller.options(options: object): GUIController;
enable()

Enable the controller.

  • [enabled=true]
Controller.enable(enabled?: boolean): this;
disable()

Disable the controller.

  • [disabled=true]
Controller.disable(disabled?: boolean): this;
show()

Show the controller after it's been hidden.

  • [show=true]
Controller.show(show?: boolean): this;
hide()

Hide the controller.

  • [hide=true]
Controller.hide(hide?: boolean): this;
onChange()

Pass a function to be called whenever the value is modified by the controller. The function receives the new value as its first parameter and the value of this will be the controller.

  • callback: Function to call.
Controller.onChange(callback: Function): this;
onFinishChange()

Pass a function to be called after the controller has been modified and loses focus.

  • callback: Function to call.
Controller.onFinishChange(callback: Function): this;
reset()

Set the controller back to its initial value.

Controller.reset(): this;
listen()

Listen for value updates.

  • [listen=true]
Controller.listen(listen?: boolean): this;
getValue()

Return object[property] value.

Controller.getValue(): any;
setValue()

Set the value of object[property].

  • value: The controller value.
Controller.setValue(value: any): this;
updateDisplay()

Update the display to keep it in sync with the current value.

Controller.updateDisplay(): this;
load()

Set the value of object[property] and call callOnFinishChange().

  • value: The controller value.
Controller.load(value: any): this;
save()

Return controller value.

Controller.save(): any;
destroy()

Destroy the controller and remove it from the parent GUI.

Controller.destroy(): void;

Controllers types

Boolean Controller

GUI Controller for booleans.

const config = { boolean: true };

gui.add(config, 'boolean');

Number Controller

GUI Controller for numbers.

const config = { number: 1 };

gui.add(config, 'number');

// Pass min, max & step values as arguments
gui.add(config, 'number', 0, 1, 0.1);

// Set min, max & step values
gui.add(config, 'number').min(0).max(1).step(0.1);

String Controller

GUI Controller for strings.

const config = { string: 'value' };

gui.add(config, 'string');

Option Controller

GUI Controller for options.

const options = { foo: 'foo', bar: 'bar' };
const config = { option: 'foo' };

// Pass options value as an argument
gui.add(config, 'option', options);

// Set options value
gui.add(config, 'option').options(options);

Function Controller

GUI Controller for functions.

GUI.add({ doSomething: () => console.log('done') }, 'doSomething');

Angle Controller

GUI Controller for angles.

const config = { angle: Math.PI };

gui.addAngle(config, 'angle');

// Pass step value as an argument
gui.addAngle(config, 'angle', Math.PI / 8);

// Set step value
gui.addAngle(config, 'angle').step(Math.PI / 8);

Coords Controller

GUI Controller for 2D coordinates.

const config = { coords: { x: 0, y: 0 } };

gui.addCoords(config, 'coords');

// Pass min, max & step values as arguments
gui.addCoords(config, 'coords', 0, 1, 0.1);

// Set min, max & step values
gui.addCoords(config, 'coords').min(0).max(1).step(0.1);

Color Controller

GUI Controller for colors.

const config = { color: '#ff0000' };

gui.addColor(config, 'color');

File Controller

GUI Controller for files.

function onLoad(dataURL: string) {
  console.log(dataURL);
}

gui.addFile({ onLoad }, 'onLoad', 'image/*');