Class GUI

Core class for the canvasGUI library

To make use of canvasGUI the user requires a GUI controller and the global method
createGUI(id, display)
must be used to create it.

The first parameter (id) is a unique string identifier for the gui. If the string is empty then a random id will be generated GUI.

The second parameter (display) must be the one of the following :

an existing HTML canvas element
the id of an existing HTML canvas element
if using p5js it will be the value returned by the createCanvas()' method executed in the setup()' function.

Any other value will result the program being terminated with an error

Properties

`Static`VERSION

VERSION: string = '!!VERSION!!'

canvasGUI version

Accessors

canvasHeight

get canvasHeight(): number
Returns number
the display height
- Defined in index.ts:1143

canvasWidth

get canvasWidth(): number
Returns number
the display width
- Defined in index.ts:1140

colorSchemeNames

get colorSchemeNames(): string[]
Returns string[]
an array with the names of built-in color schemes
- Defined in index.ts:1129

contextType

get contextType(): any
Returns any
the canvas context type
- Defined in index.ts:1120

is3D

get is3D(): any
Returns any
true gui is over a 3D canvas
- Defined in index.ts:1123

isEnabled

get isEnabled(): boolean
Returns boolean
true if this gui can respond to mouse/key events
- Defined in index.ts:1134

isVisible

get isVisible(): boolean
Returns boolean
true if gui rendering is allowed
- Defined in index.ts:1137

mode

get mode(): string
Returns string
'p5js' if using p5.js else returns 'JS'
- Defined in index.ts:1126

mouseX

get mouseX(): number
Returns number
mouse x position relative to top-left corner of the canvas
- Defined in index.ts:1371

mouseY

get mouseY(): number
Returns number
mouse y position relative to top-left corner of the canvas
- Defined in index.ts:1373

Methods

$

$(id: string | CvsPin): CvsPin
Get the control given it's unique id.
Parameters
- id: string | CvsPin
  unique ID for the control to find
Returns CvsPin
get the associated control
- Defined in index.ts:1384

addScheme

addScheme(scheme: ColorScheme): GUI
Adds a new color scheme to those already available. It does not replace an existing scheme.
Parameters
- scheme: ColorScheme
  the color scheme
Returns GUI
this gui instance
- Defined in index.ts:1847

button

button(
    id: string,
    x: number,
    y: number,
    w: number,
    h: number,
    text?: string,
    icon?: cvsIcon,
): CvsButton
Create a button control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
- Optionaltext: string
  optional face text
- Optionalicon: cvsIcon
  optional face icon
Returns CvsButton
a button
- Defined in index.ts:891

checkbox

checkbox(
    id: string,
    x: number,
    y: number,
    w: number,
    h: number,
    text?: string,
): CvsCheckbox
Create a checkbox control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
- Optionaltext: string
  optional face text
Returns CvsCheckbox
a checkbox
- Defined in index.ts:974

corners

corners(...c: any): number[] | GUI
Get or set the default corner radii used in this GUI.

To set the radii the parameters must be one of the following
- an array of 4 numbers.
- a comma seperated list of 4 numbers.
- a single number to be used for all 4 radii.
If no parameter is passed or does not match one of the above then an array of the currently used radii values.
Parameters
- ...c: any
  valid radii combination
Returns number[] | GUI
an array of the currently used radii values
- Defined in index.ts:1645

createScheme

createScheme(userName?: string, srcName?: string): ColorScheme
This will create a new color scheme from an existing one. The returned scheme is a deep-copy of the source scheme and should be edited before adding it to the GUI with the addScheme(...) method. The name of the new scheme is specified in the first parameter and cannot be changed later.

The method will fail if -
- either parameter is not a string of length >0, or
- destination and source names are equal (case insensitve comparison), or
- the source scheme does not exist.
Parameters
- userName: string = ''
  a unique name for the user's color scheme.
- srcName: string = ''
  the name of an existing color scheme.
Returns ColorScheme
the new color scheme or null if unable to create it.
- Defined in index.ts:1828

disable

disable(): GUI
Disable mouse/key event handling for this gui

Returns GUI
this gui
- Defined in index.ts:1212

enable

enable(): GUI
Enable mouse/key event handling for this gui

Returns GUI
this gui
- Defined in index.ts:1203

getPickColor

getPickColor(x: number, y: number): number
Parameters
- x: number
- y: number
Returns number
- Defined in index.ts:1879

getPicked

getPicked(x: number, y: number): { control: any; part: number }
If the [x, y] display position is over a controls pick region then return an object containing the 'control' and the pick region ('part') number.
Parameters
- x: number
  horizontal pixel location
- y: number
  vertical pixel location
Returns { control: any; part: number }
an object containing the control hit and the control part number
- Defined in index.ts:1866

getScheme

getScheme(csName: string): ColorScheme
Get the named color scheme.
Parameters
- csName: string
  the name of the color scheme
Returns ColorScheme
the color scheme or undefined if it doesn't exist
- Defined in index.ts:1803

grid

grid(x: number, y: number, w: number, h: number): GridLayout
Get a grid layout for a given pixel position and size in the display area. Initially the grid repreents a single cell but the number and size of horizontal and vertical cells should be set before creating the controls.
Parameters
- x: number
  left edge position
- y: number
  top edge position
- w: number
  grid width
- h: number
  grid height
Returns GridLayout
the grid layout
- Defined in index.ts:1155

hide

hide(): GUI
Hides all the controls for this gui

Returns GUI
this gui
- Defined in index.ts:1194

hidePanes

hidePanes(): void
Hide all side panes. This will also close any pane that is open.

Returns void
- Defined in index.ts:1676

iconSize

iconSize(size: number): number | GUI
Sets the global default icon for checkboxes and option buttons.
Parameters
- size: number
  iscon size (pixels)
Returns number | GUI
- Defined in index.ts:1536

id

id(): string
Returns the unique id for this GUI.

Returns string
GUI id
- Defined in index.ts:1164

image

image(
    id: string,
    x: number,
    y: number,
    images: cvsIcon | cvsIcon[],
    mask: cvsIcon,
): CvsImage
Create an image button control.

The button size is determined by the size of the off-button image. If a second image is provided (optional) then it will be used for the over-button state. In the absence of the second image otherwise a border highlight is used.

The button hit-zone is any non-transparent pixel if the off-button image of the mask image if provided. Any pixel with an alpha value ≥128 is considered non-transparent.
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- images: cvsIcon | cvsIcon[]
  array of images for off-button and over-button states
- mask: cvsIcon
  hit zone image
Returns CvsImage
image button control
- Defined in index.ts:917

joystick

joystick(id: string, x: number, y: number, w: number, h: number): CvsJoystick
Create a joystick control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsJoystick
a joystick control
- Defined in index.ts:1044

knob

knob(id: string, x: number, y: number, w: number, h: number): CvsKnob
Create a knob control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsKnob
a knob control
- Defined in index.ts:1057

label

label(
    id: string,
    x: number,
    y: number,
    w: number,
    h: number,
    text?: string,
    icon?: cvsIcon,
): CvsLabel
Create a label control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
- Optionaltext: string
  optional face text
- Optionalicon: cvsIcon
  optional face icon
Returns CvsLabel
a label
- Defined in index.ts:873

option

option(
    id: string,
    x: number,
    y: number,
    w: number,
    h: number,
    text?: string,
): CvsOption
Create an option (radio button) control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
- Optionaltext: string
  optional face text
Returns CvsOption
an option button
- Defined in index.ts:990

pane

pane(
    id: string,
    location: string,
    depth: number,
    text?: string,
    icon?: cvsIcon,
): CvsPane
Create a side pane. The pane location is either 'north', 'south', 'east' or 'west'.

The pane will fill the whole width/height of the canvas depending on its position. The user controls how far the pane extends into the canvas when open.
Parameters
- id: string
  unique id for this control
- location: string
  the pane position ('north', 'south', 'east' or 'west')
- depth: number
  the maximum depth the pane expands into the canvas
- Optionaltext: string
  optional text for the tab button
- Optionalicon: cvsIcon
  optional icon for the tab button
Returns CvsPane
a side pane
- Defined in index.ts:1099

panel

panel(id: string, x: number, y: number, w: number, h: number): CvsPanel
Create a label control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsPanel
a label
- Defined in index.ts:1018

pin(id: string, x: number, y: number): CvsPin
Create a pin control.

The Pin control is a simple place holder for containing child controls relative to each other.
Parameters
- id: string
- x: number
- y: number
Returns CvsPin
- Defined in index.ts:858

poster

poster(id: string, x: number, y: number, w: number, h: number): CvsPoster
Create a poster control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsPoster
a label
- Defined in index.ts:1005

ranger

ranger(id: string, x: number, y: number, w: number, h: number): CvsRanger
Create a ranger control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsRanger
ranger control
- Defined in index.ts:945

registerID

registerID(control: CvsPin): CvsPin
Parameters
- control: CvsPin
Returns CvsPin
- Defined in index.ts:1388

registerPickable

registerPickable(control: CvsControl): void
Register a control so it is pickable.

If the control has already been registered it will be unchanged.
Parameters
- control: CvsControl
  the control to make pickable
Returns void
- Defined in index.ts:1406

scheme

scheme(csName?: string): any
Set or get the existing global color scheme.
Parameters
- OptionalcsName: string
  name of the color scheme to set
Returns any
this gui instance
- Defined in index.ts:1782

show

show(): GUI
Render any controls for this gui

Returns GUI
this gui
- Defined in index.ts:1185

showBuffer

showBuffer(cvsID: string, buffer?: OffscreenCanvas): void
Display a 2D buffer in a canvas element with the specified ID.

An existing HTML element with this ID that is not a canvas element this will be ignored and the buffer will not be displayed.

An exising HTML canvas element with this ID will be used to display the buffer, if not it will be created and appended to the body section.
Parameters
- cvsID: string
  the ID (string) of the HTML canvas element to use.
- buffer: OffscreenCanvas = ...
  the 2D canvas to display.
Returns void
- Defined in index.ts:1479

showPanes

showPanes(): void
Show all pane tabs. All panes will be shown closed.

Returns void
- Defined in index.ts:1687

slider

slider(id: string, x: number, y: number, w: number, h: number): CvsSlider
Create a slider control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsSlider
slider control
- Defined in index.ts:932

tabHeight

tabHeight(th: number): number | GUI
Gets or sets the global minimum height for pane tabs.
Parameters
- th: number
  the minimum tab height (must be ≥10)
Returns number | GUI
this gui instance
- Defined in index.ts:1173

textfield

textfield(id: string, x: number, y: number, w: number, h: number): CvsTextField
Create a single line text input control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsTextField
a textfield
- Defined in index.ts:959

textFont

textFont(font?: string | object): GUI
If no parameter is passed then the global font family name will be returned.

If a parameter is provided it will be accepted if it is one of the following :-
- The font family name of a TTF system font e.g. 'arial', 'courier new', 'times new roman' ...
- The name of a logical font e.g. 'serif', 'sans-serif', 'monospace' ...
- A font loaded in p5js with the loadFont() function.
Any other parameter value will display a warning and be ignored leaving the font unchanged.
Parameters
- Optionalfont: string | object
  system or logical font, a FontFace object or a p5js font object.
Returns GUI
this control
- Defined in index.ts:1580

textSize(tsize?: number): number | GUI
Sets or gets the global text size.

If no parameter is passed then the global text size is returned otherwise it returns this gui.
Parameters
- Optionaltsize: number
  new global text size
Returns number | GUI
the global text size or this gui
- Defined in index.ts:1552

textStyle

textStyle(style?: string): string | GUI
Sets or gets the global text style.

The following strings are recognised as valid styles :-
```
'normal'  'bold'  'thin'  'italic'  
'bold italic'  'thin italic'  'oblique'
```
It will also accept the 4 p5js constants :-
```
NORMAL    BOLD   ITALIC   BOLDITALIC
```
Unrecognized styles are ignored and the global style left unchanged.

If no parameter is passed then the current global style is returned.
Parameters
- Optionalstyle: string
  the font style to use.
Returns string | GUI
this control
- Defined in index.ts:1608

tipTextSize

tipTextSize(gtts?: number): number | GUI
Sets or gets the global tip text size. If no parameter is passed then the global tip text size is returned otherwise it returns this control
Parameters
- Optionalgtts: number
  new global tip text size
Returns number | GUI
the global tip text size or this control
- Defined in index.ts:1623

tooltipTimes

tooltipTimes(show?: number, repeat?: number): GUI
Controls how long a tooltip is shown and how long to wait before it can be shown again. This helps avoid the tip flicking on and off as the mouse moves over the control.
Parameters
- show: number = TT_SHOW_TIME
  show duration (ms)
- repeat: number = TT_REPEAT_TIME
  duration before the tip can be shown again
Returns GUI
this gui
- Defined in index.ts:1226

viewer

viewer(id: string, x: number, y: number, w: number, h: number): CvsViewer
Create a viewer control
Parameters
- id: string
  unique id for this control
- x: number
  left-hand pixel position
- y: number
  top pixel position
- w: number
  width
- h: number
  height
Returns CvsViewer
an image viewer
- Defined in index.ts:1031

`Static`$$

$$(id: string): GUI
Get the GUI with the given id. If no such GUI exists then the function returns undefined.

The global function getGUI(...) is an alternative method that accepts the same parameters performs exactly the same task.
Parameters
- id: string
  the GUI id
Returns GUI
the matching GUI controller or undefined if not found.
- Defined in index.ts:1905

Class GUI

Core class for the canvasGUI library

Index

Properties

Accessors

Methods

Properties

StaticVERSION

Accessors

canvasHeight

Returns number

canvasWidth

Returns number

colorSchemeNames

Returns string[]

contextType

Returns any

is3D

Returns any

isEnabled

Returns boolean

isVisible

Returns boolean

mode

Returns string

mouseX

Returns number

mouseY

Returns number

Methods

$

Parameters

Returns CvsPin

addScheme

Parameters

Returns GUI

button

Parameters

Returns CvsButton

checkbox

Parameters

Returns CvsCheckbox

corners

Parameters

Returns number[] | GUI

createScheme

Parameters

Returns ColorScheme

disable

Returns GUI

enable

Returns GUI

getPickColor

Parameters

Returns number

getPicked

Parameters

Returns { control: any; part: number }

getScheme

Parameters

Returns ColorScheme

grid

Parameters

Returns GridLayout

hide

Returns GUI

hidePanes

Returns void

iconSize

Parameters

Returns number | GUI

id

Returns string

image

Parameters

Returns CvsImage

joystick

Parameters

Returns CvsJoystick

knob

`Static`VERSION

`Static`$$