API Docs Class: GlobalActions

new GlobalActions()

Provides access to application-wide actions whilst offering some isolation between model classes and the reactive front-end UI framework being used.

This class provides the actions and mutations required to modify global state and keep the UI up-to-date. It is used throughout the PD and BIM model classes and provides action handlers that front-end frameworks such as React, Preact, Vue, Angular, Enyo, Ember, Knockout or any other can use to observe and act upon changes.

As this code seeks to be framework-agnostic, it cannot use ready-made stores such as Vuex or Flux. However, it still needs to appropriately support whatever framework and/or dynamic UI that is used to manage it.

Using Proxy Objects

In order to ensure the isolation of PD.GlobalState and PD.GlobalView from any reactivity or observability that might leak into them from the UI framework, any mutations to either that occur within the methods of this class must only be applied to the PD.GlobalStateProxy and PD.GlobalViewProxy objects rather than PD.GlobalState or PD.GlobalView directly. This provides front-end frameworks with an opportunity to do whatever they need to with the proxy objects to observe and/or intercept state changes and update the UI, whilst leaving PD.GlobalState and PD.GlobalView as plain old JavaScript objects (POJO).

Depending on the UI framework, any reactivity/observability added to the proxy objects may add unnecessary and quantifiable overhead, even when getting values. Thus, it is still perfectly fine to READ properties from PD.GlobalState and PD.GlobalView, but any and all CHANGES to properties must only be made via PD.GlobalStateProxy and PD.GlobalViewProxy.

DON'T USE this

Another important caveat with this object is that its methods should never use this internally to obtain data or call other methods. They should instead always use the global reference PD.GlobalActions. This is because it is not always possible to predict exactly how these methods will be invoked if/when used as callbacks for elements within the UI framework, and it is entirely possible that this may point to something entirely different with each call. If all methods use PD.GlobalActions instead of this, then everyone will know what your intention is and everything should work as safely as possible.

Author:

drajmarsh

Members

:function debouncedCursorInfoUpdate <static>

A debounced cursor info updater.

This is used to show/hide the cursor information dialog and set its position. It is not necessary for this dialog to exactly track the cursor when it moves, so a debounced version is used to ensure it is not done too frequently.

Type

function

:function debouncedLocationUpdate <static>

A debounced site location updater.

Type

function

:function debouncedSunPathUpdate <static>

A debounced fit-view to sun-path updater.

This is used when the main 3D Sun-path diagram is being interactively resized by the user within the main model canvas. It is not necessary for the model view to be resized exactly as the user is resizing the diagram, so a debounced version is used to ensure it is not done too frequently.

Type

function

:DOMElement|null editorElement <static>

The HTML element that owns the primary work area of render canvas.

Type

DOMElement | null

:PD.HUDController|null hudController <static>

The HUD controller created by the main scene manager.

Type

PD.HUDController | null

:PD.ModelManager|null modelManager <static>

The manager of the geometry of the building model.

This is set within the PD.GlobalActions.createModel method and is used to manage the model geometry, including the creation of new structures, levels, spaces and elements. It also provides methods for searching for elements by UUID, updating the model, and rebuilding the model when changes are made.

Type

PD.ModelManager | null

:PD.SceneManager|null sceneManager <static>

The 3D view/scene manager that controls the WebGL canvas.

This is set within the PD.GlobalActions.createModel method and is used to manage the 3D scene, including the camera, lighting, and rendering of the model. It also provides methods for updating the scene, checking the pixel ratio, and fitting the view to the model.

Type

PD.SceneManager | null

:PD.SelectionManager|null selectionManager <static>

The interactive selection manager within the model.

This is set within the PD.GlobalActions.createModel method and is used to manage user interactions with the model, including selection of elements, updating the cursor position, and managing the selection highlight. It also provides methods for updating the selection, clearing the selection, and updating the displayed dimensions.

Type

PD.SelectionManager | null

:PD.SkyDome|null skyDome <static>

The global sky dome for skylight and daylight calculations.

This is set when the application first creates either a 3D Sun-path diagram or a 2D SVG Sun-path diagram. Both of these share a single sky dome instance that is used to display the sky luminance distribution and shading. On creation, these call either the PD.GlobalActions.setSunPathDiagram3D or PD.GlobalActions.setSunPathDiagram2D methods to set the global Sun-path and this sky dome instance.

Type

PD.SkyDome | null

:PD.SolarPosition|null solarPosition <static>

The global solar position calculator for shadows and sky analysis.

Type

PD.SolarPosition | null

:PD.SVG.SkyDome|null sunPathDiagram2D <static>

The 2D Sun-path diagram that shows the current sky distribution.

This is set when the application first creates a 2D SVG Sun-path diagram. On creation, this calls the PD.GlobalActions.setSunPathDiagram2D method set this global 2D Sun-path instance.

Type

PD.SVG.SkyDome | null

:PD.SolarPosition|null sunPathDiagram3D <static>

The Sun-path diagram that matches the current solar position.

This is set when the application first creates a 3D WebGL Sun-path diagram. On creation, this calls PD.GlobalActions.setSunPathDiagram3D, or uses the PD.GlobalActions.getOrCreateSunPathDiagram3D method, to set this global 3D Sun-path instance.

Type

PD.SolarPosition | null

:PD.Text|null textHelper <static>

A shared text helper for rendering labels and space names in the model.

This is set within the PD.GlobalActions.createModel method, and is used to render text labels in the model, such as space names, dimensions, and other annotations. It is used throughout the application to ensure consistent text rendering. It can also be used to create text labels for elements in the model, as well as for displaying textual information within the head-up display (HUD).

Type

PD.Text | null

Methods

_pasteApertureFromText(text, offset) <static>

Pastes a new aperture from given JSON string.

Parameters:

Name	Type	Description
`text`	string	The textual data to paste the aperture from.
`offset`	boolean	Whether aperture is pasted in a different position to the original, defaults to false.

Returns:

Returns the new aperture, or null if paste failed.

Type: BIM.Aperture

_pasteDrawingViewFromText(text) <static>

Pastes the view from textural JSON data into the project.

Parameters:

Name	Type	Description
`text`	string	The textual data to paste the view from.

Returns:

Returns the new view, or null if paste failed.

Type: BIM.DrawingView

_pasteLevelFromText(text) <static>

Pastes the level from textural JSON data into the current structure.

Parameters:

Name	Type	Description
`text`	string	The textual data to paste the level from.

Returns:

Returns the new level, or null if paste failed.

Type: BIM.Level

addDrawingView( [drawing]) <static>

Adds a new view to the current project.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to add, defaults to a new view.

Returns:

Returns the newly added view, or null if it failed.

Type: BIM.DrawingView

addLevel( [level]) <static>

Adds a new level to the current structure.

Parameters:

Name	Type	Argument	Description
`level`	BIM.Level	<optional>	The level to add, defaults to a new level.

Returns:

Returns the newly added level.

Type: BIM.Level

addStaticGeometry(geometry [, animations]) <static>

Creates a new element containing THREE geometry.

Parameters:

Name	Type	Argument	Description
`geometry`	THREE.Object3D		The geometry to add.
`animations`	THREE.AnimationMixer	<optional>	Any animations to add, defaults to `undefined`.

ambientOcclusionSetAsDefault() <static>

Stores the current ambient occlusion settings as startup default.

ambientOcclusionUpdate() <static>

Updates the screen-space ambient occlusion shader.

animateSunPos() <static>

A callback for animating the sun position.

canCopySelection() <static>

Check to see if there is a valid selection for copying.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if there is a copyable selection.

Type: boolean

canPasteSelection() <static>

Checks that the clipboard contains valid data for pasting.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns tue if clipboard has copied data.

Type: boolean

cancelAction() <static>

Cancels the current user mode action.

If the current action is adding a new element, the action will be cancelled and the new element will NOT be added.

cancelNudgeMode() <static>

Cancel the current nudge mode, if active.

cancelProgressAction() <static>

Cancels the current progress action.

This can occur when the user clicks the Cancel button in the application footer or presses the Escape key when the PD.GlobalState.progressBarValue is greater than zero.

canvasColorReset() <static>

Resets the main canvas color to default light/dark background.

checkLevelForSpatialOverlap() <static>

Checks the current level for overlapping spaces.

checkToResizeSidePanels() <static>

Resizes the work area if side panels are pinned, a side panel is active and the window has been resized.

clearAppStatusMessage() <static>

Clears the application status message by returning it to 'Idle'.

clearDynamicStateMessage() <static>

Clears the dynamic state message to an empty string.

clearProgressBar() <static>

Sets calculation progress to zero and removes progress bar from the UI.

clearSelection() <static>

When called, whatever is currently selected in the model is de-selected.

clearUserModeActionMessage() <static>

Sets the user mode action message to an empty string.

closeMenu(id) <static>

Attempts to close a bootstrap menu associated with the DOM element.

This method uses document.getElementById(id) to find the parent DOM element, then uses Bootstrap methods to find and hide any menu that is associated with it.

Parameters:

Name	Type	Description
`id`	string	The `id` of the DOM element.

completeAction() <static>

Completes the current user mode action.

If the current action is adding a new element, action will end and the new element will be added to the model.

computeCurrentModelExtents() <static>

Computes the extents of all visible entities in the current model.

This method is used by the PD.SceneManager#updateExtents method, This is typically called in response to the UI or the framework calling the PD.GlobalActions.fitViewToModel method.

Element extents are calculated and updated automatically during editing. Thus, this method simply iterates over all visible structures, levels and elements to determine the maximum bounds. It also includes the current background image if it is visible, and updates any visible annotations.

Returns:

Returns the computed extents of the visible model.

Type: THREE.Box3

computeScaledHeight(height) <static>

Calculates the relative level height considering the current scale.

Parameters:

Name	Type	Description
`height`	number	The level height value to change.

Returns:

Returns the scaled height.

Type: number

computeScreenSpaceScale(pos) <static>

Computes the multiplier required to maintain the same screen-space size.

If PD.GlobalState.cursorDynamicResize is true, this method calculates the distance from the point to the camera and returns the scale factor required to ensure something at that point remains roughly the same size in screen coordinates. If not set, a one-to-one scale is returned.

This is primarily used by the PD.Cursor and PD.Dimensions classes to dynamically resize their arrows and text when the view is zoomed.

Parameters:

Name	Type	Description
`pos`	THREE.Vector3	A point in model space.

Returns:

Returns the screen-space scaling.

Type: number

computeShadingForSunPath(sunPath [, ignoreOctrees]) <static>

Calculates the shading value(s) for the given sun-path element.

This method first checks that the model's ray-tracing octrees are all up to date, and then computes the shading mask for the given sun-path element. It then updates the sun-path element's local mesh with the shared global sky distribution and new shading.

If the sun-path element is currently selected, it will copy the new shading to the global 2D SVG sun-path diagram.

Parameters:

Name	Type	Argument	Description
`sunPath`	BIM.SunPath		The sun-path element to update.
`ignoreOctrees`	boolean	<optional>	An optional flag to not check to recalculate model octrees, defaults to false.

computeSpatialAdjacencies() <static>

Calculates areas of inter-zonal adjacency and updates the view.

computeVisibleSky() <static>

Calculates the visible sky value(s) for the currently selected element.

convertRemToPx(rem) <static>

Returns the given CSS rem value as pixels based on the root font size. obtained from the computed style of the document's root element.

Parameters:

Name	Type	Description
`rem`	number	The `rem` value to convert to pixels.

Returns:

Returns the pixel value of the given rem value.

Type: number

copyAperture( [aperture]) <static>

Copies the currently selected aperture to the clipboard.

Parameters:

Name	Type	Argument	Description
`aperture`	BIM.Aperture	<optional>	The aperture to copy, defaults to the current aperture.

Returns:

Returns true if an aperture was selected and copied.

Type: boolean

copyDrawingView( [drawing]) <static>

Copies a stored view to the clipboard.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to copy, defaults to the current view.

Returns:

Returns true if the view was successfully copied.

Type: boolean

copyElement( [element]) <static>

Copies the currently selected element to the clipboard.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element	<optional>	The element to copy, defaults to the current element.

Returns:

Returns true if an element was selected and copied.

Type: boolean

copyElementType( [element]) <static>

Copies the currently selected element type to the clipboard.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element	<optional>	The element to copy, defaults to the current element.

Returns:

Returns true if element type data was selected and copied.

Type: boolean

copyElements() <static>

Copies currently selected elements to the clipboard.

Returns:

Returns true if one or more elements were selected and cut.

Type: boolean

copyLevel( [level]) <static>

Copies a level to the clipboard.

Parameters:

Name	Type	Argument	Description
`level`	BIM.Level	<optional>	The level to copy, defaults to the current level.

Returns:

Returns true if the level was successfully copied.

Type: boolean

copySelection() <static>

Copies the current selection to the clipboard.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if current selection was copied.

Type: boolean

createModel(element [, config]) <static>

Creates global model editors and sets up main work area.

In addition to setting up default actions, this method also checks for a user-defined method PD.GlobalActions.extendModel(element, config) and, if found, calls it as part of the setup process. This provides host applications with an opportunity to customise the model creation process without having to override PD.GlobalActions or this method.

This method creates the main model editor, as well as the model manager, scene manager, selection manager, and text helper. It also sets up the debounced cursor info and Sun-path update methods. If you want to use your own custom model manager, scene manager or selection manager classes, use the config parameter to pass instances of them in. If you do not pass in your own instances, new instances of the default classes will be created.

It returns the model manager instance, which your application can use to create its initial model geometry.

Parameters:

Name Type Argument Description

element

DOMElement

The DOM container element to add the 3D model canvas to.

config

object

A configuration object containing optional instances of management objects to use.

Properties of `config`:

Name	Type	Argument	Description
`modelManager`	PD.ModelManager	<optional>	The model manager instance to use, defaults to a new `PD.ModelManager`.
`sceneManager`	PD.SceneManager	<optional>	The scene manager instance to use, defaults to a new `PD.SceneManager`.
`selectionManager`	PD.SelectionManager	<optional>	The selection manager instance to use, defaults to a new `PD.SelectionManager`.
`solarPosition`	PD.SolarPosition	<optional>	The solar position instance to use, defaults to a new `PD.SolarPosition`.

Returns:

Returns the model manager to use for the application.

Type: PD.ModelManager

createModel( [element] [, config]) <static>

Creates global model editors and sets up main work area.

Parameters:

Name	Type	Argument	Description
`element`	DOMElement	<optional>	The DOM container element for the main work area, defaults to `null`.
`config`	object	<optional>	A configuration object containing optional instances of management objects to use.

cursorShowInfo(state) <static>

Use this to show or hide any cursor tracking information.

A 3D cursor can be assigned a HTML element that will interactively track the cursor's screen position. Sometimes you may want to temporarily hide this, such as when interactively dragging a new junction or rotating the camera view.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to show cursor information.

cursorUpdate() <static>

Refreshes the current 3D cursor within the view.

cursorUpdateArrowOffset() <static>

Updates the 3D cursor when PD.GlobalState.cursorArrowOffset changes.

cursorUpdateBaseSize() <static>

Updates the 3D cursor when PD.GlobalState.cursorBaseSize changes.

cursorUpdateInfoPosition() <static>

Checks for any cursor tracking objects and updates them.

Returns:

Returns true if the cursor info position was updated.

Type: boolean

cutAperture() <static>

Copies the currently selected aperture to the clipboard and removes it.

Returns:

Returns true if an aperture was selected and cut.

Type: boolean

cutDrawingView( [drawing]) <static>

Copies a stored view to the clipboard and removes it.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to cut, defaults to the current view.

Returns:

Returns true if the view was successfully cut.

Type: boolean

cutElement( [element]) <static>

Copies the currently selected element to the clipboard and removes it.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element	<optional>	The element to cut, defaults to the current element.

Returns:

Returns true if an element was selected and cut.

Type: boolean

cutElements() <static>

Copies currently selected elements to the clipboard and removes them.

Returns:

Returns true if one or more elements were selected and cut.

Type: boolean

cutLevel( [level]) <static>

Copies a level to the clipboard and removes it.

Parameters:

Name	Type	Argument	Description
`level`	BIM.Level	<optional>	The level to cut, defaults to the current level.

Returns:

Returns true if the level was successfully cut.

Type: boolean

cutSelection() <static>

Copies the current selection to the clipboard and removes it.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if current selection was cut.

Type: boolean

dimensionsUpdate() <static>

Regenerates all the dimension geometry within the current view.

displayBrowserFileOpenDialog(id) <static>

Displays the browser's 'File Open' dialog box allowing users to select a file.

Parameters:

Name	Type	Description
`id`	string	The HTML id attribute of an `<input type="file">` DOM element.

duplicateAperture( [aperture]) <static>

Creates a copy of the currently selected aperture in its host element.

Parameters:

Name	Type	Argument	Description
`aperture`	BIM.Aperture	<optional>	The aperture to clone, defaults to the current aperture.

Returns:

Returns the new aperture if one was selected and duplicated.

Type: BIM.Aperture

duplicateDrawingView( [drawing]) <static>

Clones a view and adds to the end of the views list.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to duplicate, defaults to the current view.

Returns:

Returns the new view if one was selected and duplicated.

Type: BIM.DrawingView

duplicateElement( [element]) <static>

Creates a copy of the currently selected element in its host element.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element	<optional>	The element to clone, defaults to the current element.

Returns:

Returns the new element if one was selected and duplicated.

Type: BIM.Element

duplicateElements() <static>

Creates a copy of the currently selection set.

Returns:

Returns true if element(s) added, or false if paste failed.

Type: boolean

duplicateLevel( [level]) <static>

Clones a level and inserts the copy immediately above itself.

Parameters:

Name	Type	Argument	Description
`level`	BIM.Level	<optional>	The level to duplicate, defaults to the current level.

Returns:

Returns the new level if one was selected and duplicated.

Type: BIM.Level

duplicatePathContour( [side] [, element]) <static>

Creates a new construction line based on the path of the currently selected element.

The line will only be created if a valid path-based element is currently selected.

Parameters:

Name	Type	Argument	Description
`side`	PD.SIDE	<optional>	The side of the contour to generate, defaults to `PD.SIDE.MIDDLE`.
`element`	BIM.Element	<optional>	The element with the path being duplicated, defaults to `currentElement`.

Returns:

Returns true if new element was successfully created.

Type: boolean

duplicateSelection() <static>

Creates a copy of the currently selected element in its host element.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if an element was selected and duplicated.

Type: boolean

explodedViewSet() <static>

Sets the PD.GlobalView.explodedView flag.

explodedViewToggle() <static>

Toggles the PD.GlobalView.explodedView flag between views.

explodedViewUpdate(arg) <static>

Displays/updates an exploded level view of the model.

This method is called with a numeric argument when the exploded view scale value is edited, in which case it instantly updates the explode view.

When called directly from a UI element or with a non-numeric argument, the method will animate levels and fit the exploded view. If the argument is a string equal to "static", the method will animate levels without changing the current view.

Parameters:

Name	Type	Description
`arg`	any	The triggering event, level scale or 'static' string.

findByUUID(uuid [, currentOnly]) <static>

Searches BIM entity maps in each structure for a matching entity.

Parameters:

Name	Type	Argument	Description
`uuid`	string		The UUID of the entity to search for.
`currentOnly`	boolean	<optional>	When true, only search the current structure.

Returns:

Returns the found entity or null.

Type: PD.Base | null

fitViewToModel(instant) <static>

Animates the current view so that it fits to the visible model.

Parameters:

Name	Type	Description
`instant`	boolean	An optional flag to force an instant update rather than an animated transition.

floorGridAutoFit(state) <static>

Sets the PD.GlobalState.floorGridAutoFit flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

floorGridAutoFitToggle() <static>

Toggles the PD.GlobalState.floorGridAutoFit flag on/off.

floorGridAutoFitUpdate() <static>

Updates the scene when the PD.GlobalState.floorGridAutoFit flag changes.

floorGridEdit() <static>

Sets interactive user mode to PD.MODE.RECT to edit the current level's grid extents.

floorGridOpacityUpdate() <static>

Updates the scene when the PD.GlobalView.floorGridOpacity value changes.

floorGridSizeUpdate() <static>

Updates the scene when the PD.GlobalState.gridCellMinor and/or PD.GlobalState.gridCellMajor values change.

focusAndSelectChildInput(id [, index]) <static>

Attempts to focus and select an input element within a container.

This method uses document.getElementById(id) to find the parent DOM element, then uses container.getElementsByTagName('input') to find the first input element.

Parameters:

Name	Type	Argument	Description
`id`	string		The `id` of the container DOM element.
`index`	number	<optional>	The ordinal index of input to select, defaults to zero.

focusEditor() <static>

Sets the input focus to the active work area or model canvas.

It is sometimes useful after certain user commands to return the focus to the work area or model canvas to make using key codes easier.

getCanvasColorAsHex() <static>

Used by the scene manager to update the canvas background color when first created and when responding to global 'dark-mode' events.

This method allows the host application additional control over the main model canvas background color.

Returns:

Returns a hexadecimal color number.

Type: number

getDefaultValue(key) <static>

Retrieves any value associated with the given key in local storage.

This method modifies the given key by prefixing it with the current value of PD.appID followed by a full colon, in order to make the data specific for this app. Thus, if a key value of colorScheme is given, and the value of PD.appID is PD:SP3D, then the actual key looked up in local storage will be PD:SP3D:colorScheme.

Parameters:

Name	Type	Description
`key`	string	The key name to look for.

Returns:

Returns the stored value, or null if not found.

Type: string | null

getGeolocation( [callback]) <static>

Tries to obtain the world location of the current device.

Parameters:

Name	Type	Argument	Description
`callback`	function	<optional> <nullable>	An optional callback function when location found.

getLevelsWithSameElevation(level) <static>

Retrieves an array of levels with the same elevation in this and adjacent structures.

Parameters:

Name	Type	Description
`level`	BIM.Level	The level to get the reference elevation from.

Returns:

Returns an array of zero or more adjacent levels.

Type: Array

getModelDisplayHeight() <static>

Retrieve the current display height of model manager meshes.

Returns:

Returns a display height in model units.

Type: number

getModelDisplayOffset() <static>

Retrieve the current display offset of model manager meshes.

Returns:

Returns a display height in model units.

Type: number

getOrCreateSunPathDiagram3D( [show]) <static>

Creates the 3D sun path diagram when required.

Parameters:

Name	Type	Argument	Description
`show`	boolean	<optional>	An optional flag tp show the diagram, defaults to false.

getProjectKey( [projectName]) <static>

Retrieves a formatted local storage key name for listing, reading and saving projects.

If a project name is given, a full project-specific key is returned. If no project name is given, the overall key to the project name list is returned.

Parameters:

Name	Type	Argument	Description
`projectName`	string	<optional>	The name of a specific project.

Returns:

Returns a local storage key.

Type: string

getSceneView() <static>

Retrieve the current view object.

This is a data object that defines the camera and target positions, as well as field of view, zoom and polar angles.

Returns:

Returns the current camera view object.

Type: PD.ViewOrbital

getSceneViewAxis() <static>

Determines the cartesian axis closest to the current view.

Returns:

Returns the closest cartesian axis.

Type: THREE.Vector3

getSceneViewClosestAxis() <static>

Determine the closest cartesian axis to the current view vector.

This uses the current vector between target to camera to determine which is the closest cartesian axis.

Returns:

Returns the closest artesian axis to the view.

Type: PD.AXIS

getSelectedElement() <static>

Retrieves the currently selected element from the model.

Returns:

Returns the selected element ot null.

Type: BIM.Element | null

getSelectionExtents() <static>

Retrieves the bounding box extents of the currently selected entity.

Returns:

Returns the bounding box of the current selection, or null.

Type: THREE.Box3 | null

getSessionKey( [sessionName]) <static>

Retrieves a formatted local storage key name for listing, reading and saving session data.

If a session name is given, a full session-specific key is returned. If no session name is given, the overall key to the session name list is returned.

Parameters:

Name	Type	Argument	Description
`sessionName`	string	<optional>	The name of a specific session.

Returns:

Returns a local storage key.

Type: string

getSkyColorAsHex() <static>

Used by the scene manager to update the canvas sky color when first created and when responding to global 'dark-mode' events.

Returns:

Returns a hexadecimal color number.

Type: number

getUserConfirmation(title, message, callback) <static>

Displays a confirmation modal dialog and invokes callback if confirmed.

If the user clicks away or cancels the dialog, the callback function will not be called. If there is no listeners that handle this event, the message will be displayed in a standard window.confirm() dialog box.

Parameters:

Name	Type	Description
`title`	string	The title to display in the header.
`message`	string	The message to display in the body.
`callback`	function	The function to call when confirmed.

getVisibleDimensionElements() <static>

Retrieves a list of all currently visible dimension elements.

Returns:

Returns an array of dimension elements.

Type: Array

gotoURL(url) <static>

Opens the given URL in a new tab/window.

Parameters:

Name	Type	Description
`url`	string	The URL to go to.

handleCurrentSelectionChange(selectionType, element, junction, aperture) <static>

Invoked whenever the user selects/deselects the current item in the 3D model.

This method is typically called automatically by the active PD.SelectionManager whenever the current selection has changed.

Parameters:

Name	Type	Description
`selectionType`	PD.SELECTED	The current selection type.
`element`	BIM.Element	The currently selected element, if any.
`junction`	BIM.Junction	The currently selected junction, if any.
`aperture`	BIM.Aperture	The currently selected aperture, if any.

handleExtendedSelectionChange(selectionSet) <static>

Invoked whenever the user adds/toggle/removes items from the extended selection set..

This method is typically called automatically by the active PD.SelectionManager whenever the extended selection set changes.

Parameters:

Name	Type	Description
`selectionSet`	PD.SelectionSet	The selection set that changed.

handleKeyCommand(key, event) <static>

Processes the second key in a two-key command sequence.

Parameters:

Name	Type	Description
`key`	string	The key just pressed and released.
`event`	KeyEvent	The event that triggered this handler.

Returns:

Returns true if key was processed.

Type: boolean

handleKeyDown(event) <static>

Responds to 'onKeyDown' events in the work area or model canvas.

For this to work, the host application must invoke this method in response to user-generated events, either by calling it from their own event handler, or by assigning it as the event handler.

Parameters:

Name	Type	Description
`event`	KeyEvent	The event that triggered this handler.

handleKeyUp(event) <static>

Responds to 'onKeyUp' events in the work area or model canvas.

For this to work, the host application must invoke this method in response to user-generated events, either by calling it from their own event handler, or by assigning it as the event handler.

Parameters:

Name	Type	Description
`event`	KeyEvent	The event that triggered this handler.

handleLevelChange(level) <static>

Invoked automatically by the model manager whenever the current level changes.

Parameters:

Name	Type	Description
`level`	BIM.Level	The currently selected level, if any.

handleProjectChange( [structure] [, level]) <static>

Invoked automatically by the model manager whenever the project or current structure changes.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Structure	<optional>	The structure that changed, if any.
`level`	BIM.Level	<optional>	The level that changed, if any.

handleViewKeyDown(event) <static>

Handles a kev down event that might update the view.

Parameters:

Name	Type	Description
`event`	Event	The key event to handle.

handleViewKeyUp(event) <static>

Handles a kev up event that might update the view.

Parameters:

Name	Type	Description
`event`	Event	The key event to handle.

highlightTabPanelItem(ocName, tabName [, panelId] [, callback]) <static>

Makes a panel with the given id visible within the DOM hierarchy of a tabbed offcanvas, and displays a temporarily highlighted border around it.

The based elements have a very specific way of relating nav buttons with their appropriate tabs using naming conventions. Rather than having to know this internal information, you can just specify the names of the offcanvas and tab and this method will work it out for you.

If the panelId argument is not given, whole tab will be highlighted.

Parameters:

Name	Type	Argument	Description
`ocName`	string		The name after the 'offcanvas-' part of the id attribute of the offcanvas page, or a container id.
`tabName`	string		The name after the 'tab-' part of the id attribute of the required tab within the offcanvas.
`panelId`	string	<optional>	The `id` attribute value of the required panel within the tab.
`callback`	function	<optional>	An optional callback function invoked once the highlight has been displayed (after 500ms).

highlightUIElement(elem [, callback]) <static>

Display a highlighted outline around the given DOM element.

This method assumes that the element is already visible within the UI. If not, use the PD.GlobalActions.highlightTabPanelItem method.

It first sets the class of the element to include the highlight, and sets a timeout for 3000ms to remove the class.

If a callback function is given, it sets another callback for 500ms (to give enough time for the UI to update) and invokes the callback. This allows you to do things such as set the focus or alter its state whilst visible.

Parameters:

Name	Type	Argument	Description
`elem`	Element		The DOM element to highlight.
`callback`	function	<optional>	An optional callback function invoked once the highlight has been displayed (after 500ms).

insertControlNode() <static>

Inserts a new curve control node in the currently selected curve.

insertPathContour() <static>

Inserts a new path contour into the currently selected element.

A new contour will only be inserted if a valid path-based element is currently selected.

Returns:

Returns true if a new contour was successfully inserted.

Type: boolean

insertPathContourWithInset(inset [, element]) <static>

Inserts a new path contour inset from the boundary into the currently selected element.

A new contour will only be inserted if a valid path-based element is currently selected.

Parameters:

Name	Type	Argument	Description
`inset`	number		The inset distance to apply to the new contour.
`element`	BIM.Element	<optional>	The element to insert the contour into, defaults to the current element.

Returns:

Returns true if a new contour was successfully inserted.

Type: boolean

isPlanView(state) <static>

Sets the PD.GlobalView.isPlanView flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

isPlanViewToggle() <static>

Toggles the PD.GlobalView.isPlanView flag on/off.

isViewInWalkingMode() <static>

Check if the view is currently in first person navigation (walking) mode rather than orbiting mode.

Returns:

Returns true if the view is in walking mode.

Type: boolean

isViewInWalkingMode() <static>

Check if the 3D view is currently in first person navigation (walking) mode rather than orbiting mode.

Returns:

Returns true if the view is in walking mode.

Type: boolean

levelImageClear() <static>

Deletes the current level's trace image.

levelImageEditExtents() <static>

Sets interactive user mode to PD.MODE.RECT to edit the current level's trace image extents.

levelImageKeepAspect(state) <static>

Sets the current level's image aspect ratio flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

levelImageKeepAspectToggle() <static>

Toggles the current level's image aspect ratio flag on/off.

levelImageLoad(image_url) <static>

Loads in and displays a floor plan image for tracing.

Parameters:

Name	Type	Description
`image_url`	string	The url of the image to load.

levelImageScale() <static>

Applies the measured vs actual scaling factor to the current level's trace image.

levelImageTransparent(state) <static>

Sets the current level's image transparent background flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

levelImageTransparentToggle() <static>

Toggles the current level's image transparent background flag on/off.

levelImageVisible(state) <static>

Sets the current level's trace image visibility flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

levelImageVisibleToggle() <static>

Toggles the current level's trace image visibility flag on/off.

newProject( [prompt]) <static>

Creates a new model within the main editor.

If the prompt argument is true and there are unsaved changes in the existing model, a system confirmation dialog will be displayed to allow the user to cancel the action in order to save their changes.

When used within a script, the return value of this method must be checked and appropriate action taken if the user chooses to cancel the operation.

Parameters:

Name	Type	Argument	Description
`prompt`	boolean	<optional>	Whether or not to prompt the user to save changes, defaults to true.

Returns:

Returns true if a new project was created, or false if the user cancelled.

Type: boolean

nudgeSelection(event) <static>

Checks for keyboard-based nudging of the current selection set.

This is called by the default key down handler when nudge mode is active. It nudges the selection in the axial direction of the key pressed (X, Y or Z), with the Shift key reversing the axial direction.

You can use the Space, Enter, Escape, N or n keys to cancel out of nudge mode, or clearing the current selection set.

Parameters:

Name	Type	Description
`event`	KeyEvent	The key down event that triggered the nudge.

nudgeSelection(event) <static>

Checks for keyboard-based nudging of the current selection set.

This is called by the default key down handler when nudge mode is active. Applications should override or reassign this method to support nudging in their own particular editing environment.

You can use the Space, Enter, Escape, N or n keys to cancel out of nudge mode, or by clearing the current selection set.

Parameters:

Name	Type	Description
`event`	KeyEvent	The key down event that triggered the nudge.

offsetPathContour(offset [, contourIndex]) <static>

Inserts a new path contour inset from the boundary into the currently selected element.

A new contour will only be inserted if a valid path-based element is currently selected.

Parameters:

Name	Type	Argument	Description
`offset`	number		The inset distance to apply to the new contour.
`contourIndex`	number	<optional>	The index of the contour to offset, defaults to 0.

Returns:

Returns true if contour was successfully offset.

Type: boolean

openProject(name [, prompt]) <static>

Opens the project with the given name.

If the prompt argument is true and there are unsaved changes in the existing model, a confirmation dialog will be displayed to allow the user to cancel the action in order to save their changes.

When used within a script, the return value of this method must be checked and appropriate action taken if the user chooses to cancel the operation.

Parameters:

Name	Type	Argument	Description
`name`	string		The name of the project to open.
`prompt`	boolean	<optional>	Whether or not to prompt the user to save existing changes, defaults to true.

Returns:

Returns true if model dialog was opened, or false if user cancelled continue prompt.

Type: boolean

pasteAperture(offset) <static>

Pastes the last copied aperture from the internal clipboard into the currently selected junction.

Parameters:

Name	Type	Description
`offset`	boolean	Whether aperture is pasted in a different position to the original, defaults to false.

Returns:

Returns the new aperture, or null if paste failed.

Type: BIM.Aperture

pasteApertureFromClipboardAsync() <static>

Pastes an aperture from the system clipboard into the currently selected junction.

Returns:

Returns the new aperture, or null if paste failed.

Type: BIM.Aperture

pasteDrawingView() <static>

Pastes the last copied view from the clipboard into the current project.

Returns:

Returns the new view, or null if paste failed.

Type: BIM.DrawingView

pasteDrawingViewFromClipboardAsync() <static>

Pastes the last copied view from the clipboard into the current project.

Returns:

Returns the new drawing, or null if paste failed.

Type: BIM.DrawingView

pasteElement(offset) <static>

Pastes the last copied element from the internal clipboard into the model.

Parameters:

Name	Type	Description
`offset`	boolean	Whether element is pasted in a different position to the original, defaults to false.

Returns:

Returns the new element, or null if paste failed.

Type: BIM.Element

pasteElementFromClipboardAsync() <static>

Pastes an element from the system clipboard into the model.

Returns:

Returns the new element, or null if paste failed.

Type: BIM.Element

pasteElementType() <static>

Pastes the last copied element type data from the internal clipboard.

Returns:

Returns the type component.

Type: BIM.Element

pasteElements() <static>

Pastes the last copied element(s) from the internal clipboard into the model.

Returns:

Returns true if element(s) added, or false if paste failed.

Type: boolean

pasteElementsFromClipboardAsync() <static>

Pastes an element from the system clipboard into the model.

Returns:

Returns true if element(s) added, or false if paste failed.

Type: boolean

pasteLevel() <static>

Pastes the last copied level from the clipboard into the current structure.

Returns:

Returns the new level, or null if paste failed.

Type: BIM.Level

pasteLevelFromClipboardAsync() <static>

Pastes the last copied level from the clipboard into the current structure.

Returns:

Returns the new level, or null if paste failed.

Type: BIM.Level

pasteSelection() <static>

Pastes the last copied selection from the clipboard into the currently selected junction.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if an element was in the clipboard and pasted.

Type: boolean

pixelRatioUpdate() <static>

Allows the hots application to react immediately if/when the use changes the pixel ratio value.

progressAction() <static>

Progresses to the next stage of the user mode action.

promptToSaveChanges() <static>

Confirm with the user that continuing the action will lose unsaved changes.

To absolutely ensure that the user is able to respond before navigating away, this message is displayed in a blocking window.confirm() dialog box.

Returns:

Returns true to continue or false to abort.

Type: boolean

rebuildModel(opacities) <static>

Rebuilds the current level in the model and redraws the scene.

Parameters:

Name	Type	Description
`opacities`	boolean	Whether or not to also update colours and transparency, defaults to false.

rebuildModel() <static>

Rebuilds the current model and redraws the scene.

rebuildModelAfterDisplayChange() <static>

Rebuilds the current level in the model and redraws the scene.

rebuildModelAndClearSelection() <static>

Rebuilds the model, clears the selection and generates a redraw.

rebuildModelAndDimensions() <static>

Rebuilds the current level in the model, updates dimensions and redraws the scene.

rebuildModelAndSelectionSet() <static>

Rebuilds the current level in the model, updates selection meshes, repositions cursor and redraws the scene.

This method should be called after any change to the physical shell geometry of the currently selected element or anything that would affect its highlighted shape. This not only rebuilds the model but also regenerates the PD.SelectionManager selection highlight and dimension meshes based on the new geometry.

rebuildOctrees() <static>

Forces the recalculation of all visible level octrees.

rebuildVisibleLevels() <static>

Rebuilds the model and redraws the scene.

redo() <static>

Redoes the last undo action, if PD.GlobalUndo is active and available.

redo() <static>

Redoes the last undo action, if active and available.

redraw() <static>

Redraws the scene in the scene manager or updates the work area.

This is used after the visible meshes in a scene have all been updated and simply requests the active scene manager to perform a render the next time it checks its status.

redraw() <static>

Redraws the main work area.

redrawAndUpdateSelection() <static>

Update selection and redraw the scene.

registerKeyCommand(key, name, callback) <static>

Adds a custom two-key keyboard command to invoke a callback function.

Key commands are sequences of two keys that invoke a custom action within the application. For example, pressing V then F may fit the current model view, or P then S may save the current project. The second key must be pressed within 1.5 seconds of the first key in order to be recognised as a key command.

The callback function is called if a second key is pressed and released within 1.5 seconds of the first key, and is sent both the first and second keys, as well as the keyboard event that invoked it. The callback should return true if the second key was recognised and acted upon, otherwise false to ignore it. It is up to the callback function itself to differentiate the actions required for individual second keys.

NOTE: Key commands must be given as either a single character string or a special key code. For absolute clarity, both single character and special key codes are converted, stored and matched as all UPPER CASE strings.

Parameters:

Name	Type	Description
`key`	string	A single character string or special key code to match.
`name`	string	A human-readable single-word identifier for the command.
`callback`	function	A function or method invoked by a second key following the first.

Throws:

Throws an error if any argument is invalid.
Type Error

Returns:

Returns true if the callback is a valid function and shortcut key is valid.

Type: boolean

registerKeyShortcut(keys, callback) <static>

Adds a custom keyboard shortcut to invoke a callback function.

The callback function is called when the specified key is released and is sent the shortcut key (as an upper case character) and keyboard event that invoked it as its two arguments. The callback should return true if it acted on the shortcut or false to ignore it.

NOTE: Shortcut keys must be given as either a single character string or a special key code. For absolute clarity, both single character and special key codes are converted, stored and matched as all UPPER CASE strings.

Parameters:

Name	Type	Description
`keys`	string \| Array.<string>	A single letter key or array of single letter keys.
`callback`	function	A function or method invoked by the shortcut keys.

Returns:

Returns true if the callback is a valid function and at least one of the shortcut keys was also valid.

Type: boolean

registerKeyboardShortcutHandler(callback) <static>

Adds a keyboard shortcut handler function.

Keyboard shortcut handler functions are added by the host application or its components and are called in response to KeyUp events when the main editor element has the input focus. Registered functions are called in the order in which they were added. If a handler function recognises and processes the released key, it must return true to prevent subsequent handlers from being called. If it does not recognise or process the released key, it must return false to allow subsequent handlers to check for and process the key.

Handler functions are sent the shortcut key (as an upper case character) and the keyboard event itself.

Parameters:

Name	Type	Description
`callback`	function	A function or method invoked by KeyUp events.

Returns:

Returns true if the callback is a valid function and does not already exist in the array.

Type: boolean

reloadSelection() <static>

Resets and reloads the selection UI based on the current selection manager state.

This method clears any/all cached selection data within the UI to completely reload and refresh all dynamic parameters. This is useful when a setting or mode change results in the need to add/remove dynamic parameter groups from an element or component, or add/remove additional components.

To just force an update of changed parameters or properties within the current selection set, use the PD.GlobalActions.updateSelectionUI method.

removeAllDrawingViews() <static>

Removes all views from the project.

removeAperture( [copy]) <static>

Removes the currently selected aperture from the model.

Parameters:

Name	Type	Argument	Description
`copy`	boolean	<optional>	A flag to copy the aperture after deleting it.

Returns:

Returns true if an aperture was selected and removed.

Type: boolean

removeControlNode() <static>

Removes the selected curve control node in the currently selected curve.

removeDefaultValue(key) <static>

Remove a value with the given key in local storage.

Parameters:

Name	Type	Description
`key`	string	The key name to remove.

Returns:

Returns true if the key/value was successfully removed.

Type: boolean

removeDrawingView( [drawing]) <static>

Removes the given view, or the current view in the model.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	An optional view, defaults to the current view.

Returns:

Returns the deleted view, or null if no view found.

Type: BIM.DrawingView

removeElement( [element] [, copy]) <static>

Removes the currently selected element from the model.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element	<optional>	The element to remove, defaults to the current element.
`copy`	boolean	<optional>	A flag to copy the element after deleting it.

Returns:

Returns true if an element was selected and removed.

Type: boolean

removeLevel( [level]) <static>

Removes the given level, or the current level in the current structure.

Parameters:

Name	Type	Argument	Description
`level`	BIM.Level	<optional>	An optional level, defaults to the current level.

Returns:

Returns the deleted level.

Type: BIM.Level

removePathContour() <static>

Removes a path contour from the currently selected element.

The contour will only be removed if a valid path-based element is currently selected.

Returns:

Returns true if the contour was successfully removed.

Type: boolean

removeSelection() <static>

Deletes the current selection from the model.

Applications should override or reassign this method to support their own particular editing or selection requirements.

Returns:

Returns true if the selection was removed.

Type: boolean

removeStructure( [structure]) <static>

Removes the given structure, or the current structure in the current model.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Structure	<optional>	An optional structure, defaults to the current structure.

Returns:

Returns the deleted structure or null if user canceled operation.

Type: BIM.Structure

renameDrawingView( [drawing]) <static>

Edits the name of the given view.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to edit, defaults to the current view.

Returns:

Returns the edited view, if any.

Type: BIM.DrawingView

resetSkyConditions() <static>

Resets the sky dome conditions to default values.

resetSkyModelConditions() <static>

Resets the sky dome conditions to default values.

returnToElementSelection() <static>

Backs out of the current selection back to element selection.

reversePathContour() <static>

Reverses the direction of a path contour in the currently selected element.

The contour will only be reversed if a valid path-based element is currently selected.

Returns:

Returns true if the contour was successfully reversed.

Type: boolean

rotateViewBy(azi, alt) <static>

Rotates the current view by the given poler increments.

Parameters:

Name	Type	Description
`azi`	number	The azimuth angle increment, in degrees.
`alt`	number	The altitude angle increment, in degrees.

Returns:

Returns this manager to support method chaining.

Type: PD.SceneManager

runScript(container) <static>

Executes the given JavaScript file contents asynchronously.

This method reads the results property of the given container object and attempts to execute the contents as JavaScript. The method is passed the container object of a file load event rather than the string contents of the results property. This is because script files can be very large and using a container avoids the duplication and additional storage associated with passing large string arguments.

If you wish to execute programmatically generated javascript, simply wrap it in a { results: script_text } container object and pass that as the argument.

Parameters:

Name	Type	Description
`container`	object	The container or file `ProgressEvent` sent to a `FileReader#load` event handler.

Returns:

Returns the results of executing the script, or null if an exception occurred.

Type: any

saveCanvasScreenshot() <static>

Save a PNG image of the model scene to the downloads folder.

saveJSONToClient(name, json) <static>

Saves the given JSON data with the given filename locally on the device.

This will typically download the data as a JSON file into the local device 'Downloads' folder. As web downloads cannot overwrite existing files an a device, the filename will be suffixed with the current date/time to make it unique and avoid the OS automatically suffixing it with bracketed indices.

Parameters:

Name	Type	Description
`name`	string	The name of item, project or file.
`json`	string	The stringified JSON data to save.

Returns:

Returns the name of the file that was created or null if save failed.

Type: string | null

saveObjectURLToClient(name, container, ext [, revokeURL]) <static>

Saves data locally on the device with the given file name prefix and extension.

This will typically download the data as a file into the local device 'Downloads' folder. As web downloads cannot overwrite existing files an a device, the filename will be generated with the current date/time as a suffix to hopefully make it unique.

NOTE: To avoid copying large strings, this method expects a container object that has a result property which contains the data URL string.

Parameters:

Name	Type	Argument	Description
`name`	string		The name of the data item.
`container`	object		The container object with a `result` property containing the data URL to save.
`ext`	string		The file extension to use (eg: '.dat').
`revokeURL`	boolean	<optional>	Whether the contained result is an object URL to be removed after use.

Returns:

Returns the name of the file that was created or null if save failed.

Type: string | null

saveProject( [name]) <static>

Attempts to save the current project.

If no project name is given, the current project name will be used. If a project name is given, it attempts to save the current project with that given name.

Parameters:

Name	Type	Argument	Description
`name`	string	<optional>	The optional name to save the project under.

Returns:

Returns true if the model was saved.

Type: boolean

saveProjectToDevice( [projectName]) <static>

Saves the project to the 'Downloads' folder on the local device.

As web downloads cannot overwrite existing files an a device, the filename will be generated with the given project name followed by the current date/time as a suffix to make it unique.

Parameters:

Name	Type	Argument	Description
`projectName`	string	<optional>	The name to save the project with.

saveProjectToLocalStorage(projectName) <static>

Stores the current project in the Projects area of local storage.

NOTE: If the project name is not given, the project will not be saved. If there is data already stored with the same name, it will be overwritten.

Parameters:

Name	Type	Description
`projectName`	string	The name of the project.

Returns:

Returns true if the project was successfully saved, or false if quota exceeded or name is not valid.

Type: boolean

selectCurrent() <static>

Returns from multi-selection to current selection.

selectElement(element) <static>

Selects the given element within the model.

If the level that owns the element is not current, it will be made the currently selected level.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element to select.

selectElementChild() <static>

If the current element has children, selects the first one.

selectElementParent() <static>

If the current element is owned by a space, selects the parent space.

selectElements(elements) <static>

Selects an array of elements within the model.

If the level that owns the element is not current, it will be made the currently selected level.

Parameters:

Name	Type	Description
`elements`	Array.<BIM.Element>	The array of elements to select.

selectExpand() <static>

Selects all junctions in the current contour or apertures in the current junction.

selectLevel(level) <static>

Parameters:

Name	Type	Description
`level`	BIM.Level	The level to make current.

selectNext(event) <static>

Selects the prev/next level/element/junction/aperture in the current model.

If the event argument is a boolean and 'true', the previous selectable item will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous junction instead.

selectNextAperture(event) <static>

Selects the next aperture in the currently selected element.

In the event argument is a boolean and 'true', the previous aperture in the element will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous aperture instead.

selectNextControlNode(event) <static>

Selects the next control node in the selected junction or element.

If the event argument is a boolean and 'true', the previous control node in the path junction/element will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous junction instead.

selectNextElement(event) <static>

Selects the next element in the currently selected space or level.

If the event argument is a boolean and 'true', then the previous element in the model will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous element instead.

selectNextJunction(event) <static>

Selects the next path junction in the currently selected element.

If the event argument is a boolean and 'true', the previous junction in the path will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous junction instead.

selectNextLevel(event) <static>

Selects the next level in the currently selected structure.

In the event argument is a boolean and 'true', the previous level in the model will be selected instead.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous level instead.

selectNextSegment(event) <static>

Selects the next path segment in the currently selected element.

If the event argument is a boolean and 'true', the previous segment in the path will be selected instead of the next.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous segment instead.

selectNextSegmentOrJunction(event) <static>

Selects the next path junction or segment in the currently selected element.

Parameters:

Name	Type	Description
`event`	Event \| boolean	The event that triggered this method, or `true` to select the previous junction instead.

selectStructure(structure, level) <static>

Selects a new structure within the project.

Parameters:

Name	Type	Description
`structure`	BIM.Structure	The structure to make the active selection.
`level`	BIM.Level	The level within the structure to actively select.

setAppStatusMessage(message) <static>

Sets the application status message to be displayed in the UI.

The framework sets the application status message whenever a significant calculation or animation is being undertaken, and then clears it when done. The application status is typically not shown as a popup but is displayed within a footer or other visible area of the main application page.

When this message is cleared or set to an empty string, it will default to 'Idle', which should be displayed when the application is waiting for and responding to user input.

Parameters:

Name	Type	Description
`message`	string	A status message to display within the user interface.

setCameraFieldOfView(fov [, immediate]) <static>

Sets just the field of view angle and sets up an animated transition.

This is used by the UI framework to allow the user to select from a range of typical field of view angles such as 'Orthographic', 'Telephoto' or 'Wide Angle'.

Parameters:

Name	Type	Argument	Description
`fov`	number		The field of view angle of the camera, in degrees (0.1 to 160).
`immediate`	boolean	<optional>	Whether or not to apply immediately rather than transition, defaults to false.

setCameraPosition(pos) <static>

Sets the new eye position of the active camera and updates the scene.

This method is called by the UI when the user directly edits the x, y or z camera position components.

Parameters:

Name	Type	Description
`pos`	THREE.Vector3	The new camera position.

setCameraTarget(pos) <static>

Sets the new target position of the active camera and updates the scene.

This method is called by the UI when the user directly edits the x, y or z camera target position components.

Parameters:

Name	Type	Description
`pos`	THREE.Vector3	The new camera target position.

setCameraToHorizontal() <static>

Adjusts the view to horizontal at default eye height.

setCameraToLookAtSelection(shift [, extents]) <static>

Adjusts the view to to look at the selection.

If the Shift key is not down or arg is given as a false boolean value, the view will be positioned based on the surface normal of the current selection.

Parameters:

Name	Type	Argument	Description
`shift`	Event \| boolean		Either the event that invoked this action or the state of the Shift key.
`extents`	THREE.Box3 \| null	<optional>	The extents to zoom to.

setCameraView(axis) <static>

Sets the camera angles based on the given axis and sets up an animated transition.

This is the primary method for changing the current model view. It passes the axis on to the active PD.SceneManager, which checks to set or animate the camera into position.

Parameters:

Name	Type	Description
`axis`	PD.AXIS	The new view axis.

setClientAreaSize(width, height) <static>

Sets the internal client area to the given size by adjusting the browser window.

NOTE: This method only works with popup windows as most browsers will not let a web page change the size of a tabbed window. Thus, you can use code in a script similar to the example below to create such a window.

Parameters:

Name	Type	Description
`width`	number	The new client area width in pixels.
`height`	number	The new client area height in pixels.

Example

window.open(
    window.location.href,
    "popupResizableWindow",
    "left=10,top=10,width=1282,height=768"
);

setColorScheme(scheme, dark) <static>

Sets the color scheme to use for the application.

This method sets the color scheme in global state and stores the value in local storage. If the new scheme changes the dark mode state, this will also generate a PD.EVENT.DARK_MODE global event.

Parameters:

Name	Type	Description
`scheme`	string	The new color scheme.
`dark`	boolean	Whether or not the scheme is a dark mode.

setCurrentDrawingView(drawing) <static>

Makes the given view or UUID the current view.

Parameters:

Name	Type	Description
`drawing`	BIM.DrawingView \| string	The view or UUID of the view to make current.

setDateTime(day, time) <static>

Sets the global site date and time.

This method first checks if the new time is at least 1 second from the current time or the new day is different to the current day before applying the change. Any less than this is no meaningful difference in the date/time.

You can alternatively us the PD.GlobalActions.setDateTime method create an undo/redo action if the date and/or time changes.

Parameters:

Name	Type	Description
`day`	number	The ordinal day of the year (0 to 365).
`time`	number	The time of day in decimal hours (0 to 24).

Returns:

Returns true if the date or time changed, otherwise false.

Type: boolean

setDayOfYear(day) <static>

Sets the current day of the year.

This method first checks if the new day of the year is at least 1 day from the current day of the year before applying the change. Any less than this is no meaningful difference in the time of day.

You can alternatively use the PD.GlobalUndo.setDayOfYear method to create an undo/redo action if the time changes.

Parameters:

Name	Type	Description
`day`	number	The ordinal day of the year (0 to 365).

Returns:

Returns true if the day changed, otherwise false.

Type: boolean

setDefaultModelExtents(extents) <static>

Sets the given extents to the default ground grid width and height.

This is used as a fallback by PD.SceneManager, BIM.Project, BIM.Structure and BIM.Level when computing their own extents if they do not yet contain any geometry.

Parameters:

Name	Type	Description
`extents`	THREE.Box3	The bounding box to set to the grid size.

setDefaultValue(key, value) <static>

Sets a value to be associated with the given key in local storage.

The method is meant to only handle data primitives and reasonably sized value strings. If you need to store very large strings, please use the PD.GlobalActions.saveJSONToLocalStorage method instead as it uses a container to pass the string data in order to avoid large string copies.

Parameters:

Name	Type	Description
`key`	string	The key name to set.
`value`	any	The value to set.

Returns:

Returns true if the value was successfully set.

Type: boolean

setDragAction(state [, action]) <static>

Enters view walking mode.

Parameters:

Name	Type	Argument	Description
`state`	boolean		The new walking mode state.
`action`	number \| string	<optional>	The new primary button action.

setGlobalViewAxis(axis) <static>

Sets the global camera view axis state property.

This just changes the viewAxis and isPlanView properties. To actually change the model view and update the current canvas, use the PD.GlobalActions.setCameraView() method which, in turn, calls this method after it has set the camera angles.

Parameters:

Name	Type	Description
`axis`	PD.AXIS	The new view axis.

setKeyDate(type [, undo]) <static>

Sets the day of the year to one of the key solar events.

The supported events are Summer solstice (0), Autumn equinox (1), Winter solstice (2) and Spring equinox (3).

Parameters:

Name	Type	Argument	Description
`type`	number		The time type (0 to 3).
`undo`	boolean	<optional>	Whether to create an undo/redo entry if the time changes, defaults to false.

Returns:

Returns true if the time of day changed, otherwise false.

Type: boolean

setKeyTime(type [, undo]) <static>

Sets the time of day to one of the key solar events.

The supported events are civil dawn (-2), sunrise (-1), solar noon (0), sunset (1) and civil dusk (2).

Parameters:

Name	Type	Argument	Description
`type`	number		The time type (-2 to 2).
`undo`	boolean	<optional>	Whether to create an undo/redo entry if the time changes, defaults to false.

Returns:

Returns true if the time of day changed, otherwise false.

Type: boolean

setLatitude(latitude) <static>

Sets the location latitude angle and creates an undo/redo entry.

This method first checks if the new latitude is at least 1e-6 degrees from the current latitude before applying the change. This represents a threshold distance of around 100mm (4") on the Earth's surface, below which there is no meaningful difference in location.

You can alternatively use the PD.GlobalUndo.setLatitude method to create an undo/redo action if the location changes.

Parameters:

Name	Type	Description
`latitude`	number	The new geographic latitude above the equator, in decimal degrees (-90 to 90).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setLocation(latitude, longitude [, timezone]) <static>

Sets the new global site location.

This method uses the PD.Location#closeTo method to determine if the given location is sufficiently different to register a change.

You can alternatively use the PD.GlobalUndo.setLocation method to create an undo/redo action if the location changes.

Parameters:

Name	Type	Argument	Description
`latitude`	number		The new geographic latitude above the equator, in decimal degrees (-90 to 90).
`longitude`	number		The new geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
`timezone`	number	<optional>	The new timezone in decimal hours (-12 to +13), will be computed if not given.

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setLongitude(longitude) <static>

Sets the location longitude angle and creates an undo/redo entry.

This method first checks if the new longitude is at least 1e-6 degrees from the current longitude before applying the change. This represents a threshold distance of around 100mm (4") on the Earth's surface, below which there is no meaningful difference in location.

You can alternatively use the PD.GlobalUndo.setLongitude method to create an undo/redo action if the location changes.

Parameters:

Name	Type	Description
`longitude`	number	The new geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setModelView(type) <static>

Sets the display mode in the main model editor.

The display mode determines whether the model is viewed in plan-section or 3D, simple or detailed, single pr multi-level, etc. This is a shortcut for specific combinations of PD.GlobalView.modelView as well as the PD.GlobalView.show3D, PD.GlobalView.showSpatial, and PD.GlobalView.isPlanView flags (all of which can be set separately), linked with an appropriate view axis.

The display type can be given as a numeric PD.DISPLAY value or the associated view name, being 0:floorplan, 1:spaces, 2:level or 3:building.

Parameters:

Name	Type	Description
`type`	PD.DISPLAY \| string	The display mode to set.

setProgressBar(percentage) <static>

Sets the current calculation progress to be displayed in the UI.

This is called by calculations within framework sets to allow the host application to display dynamic progress within the UI. The progress bar is typically located near to the application status message within a footer or other visible area of the main application page.

Parameters:

Name	Type	Description
`percentage`	number	A numeric percentage value between 0 and 100.

setSceneView(view, animate) <static>

Sets the view angles, target position, distance and field of view.

This method is called by the UI framework to allow users fine-grained tuning of the core camera and view settings. If the values are different to those in the current view, and animated transition of the current model view occurs.

Parameters:

Name Type Description

view

PD.View

A configuration object with view parameters.

Properties of `view`:

Name	Type	Description
`azimuth`	number	The azimuth angle of the camera relative to the view target, in degrees (-180 to 180).
`altitude`	number	The altitude angle of the camera relative to the view target, in degrees (-90 to 90).
`distance`	number	The distance of the camera from the view target, in model units.
`fov`	number	The field of view angle of the camera, in degrees (0.1 to 160).
`target`	THREE.Vector3	The position of the look-at point in model space.

animate

boolean

Whether or not to animate to the new view.

setSidePanelActive(id, width) <static>

Called to (re)assign focus to the button or UI element that invoked an offcanvas page change.

Parameters:

Name	Type	Description
`id`	string	The DOM `id` of the offcanvas to make active, or an empty string.
`width`	number	The width of the side panel in pixels.

setSkyShaderType(type) <static>

Sets the sky shader type and updates the model.

Parameters:

Name	Type	Description
`type`	number	The type of sky shader to set (0:Simple, 1:Realistic).

setSkyType(type) <static>

Sets the sky type and updates the model.

Parameters:

Name	Type	Description
`type`	PD.SKY_TYPE	The sky type to set.

setSnapActive(state) <static>

Sets D.GlobalState.snapActive and updates snap indicators to reflect the change.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not snapping is to be active.

setSnapGridSize(size) <static>

Sets PD.GlobalState.snapGridSize value.

Parameters:

Name	Type	Description
`size`	number	The new snap grid size in model units.

setSnapOnHover(state) <static>

Sets PD.GlobalState.snapOnHover value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to any node immediately beneath the cursor.

setSnapOrtho(state) <static>

Sets PD.GlobalState.snapOrtho value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap movement in 45deg steps from original position.

setSnapToGrid(state) <static>

Sets PD.GlobalState.snapToGrid value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to the snap grid.

setSnapToLines(state) <static>

Sets PD.GlobalState.snapToLines value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to the mid-point of adjacent lines.

setSnapToMidPoints(state) <static>

Sets PD.GlobalState.snapToMidPoints value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to the mid-point of adjacent lines.

setSnapToNormals(state) <static>

Sets PD.GlobalState.snapToNormals value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap at 45deg angles to points.

Deprecated:

setSnapToPath(state) <static>

Sets PD.GlobalState.snapToPath value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to the element's own path.

setSnapToPoints(state) <static>

Sets PD.GlobalState.snapToPoints value.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to snap to points on adjacent lines.

setStateMeasuredDistance(dist) <static>

Sets the global last measured distance value.

Parameters:

Name	Type	Description
`dist`	number	The measured distance, in model units.

setStateTransitionSpeed(speed) <static>

Sets the global duration of dynamic view transitions in ms.

Parameters:

Name	Type	Description
`speed`	number	The duration of dynamic view transitions in mx, defaults to 600ms.

setSunPathDiagram2D(sp2d) <static>

Sets the 2D sun path diagram that shows the current sky distribution.

Parameters:

Name	Type	Description
`sp2d`	PD.SVG.SkyDome	The sun path diagram with sky distribution to use.

setSunPathDiagram3D(sp3d) <static>

Sets the 3D sun path diagram that shows the current sun position.

Parameters:

Name	Type	Description
`sp3d`	PD.SunPath3D	The 3D sun path diagram to use.

setTimeOfDay(time) <static>

Sets the current hour of the day.

This method first checks if the new time is at least 1 second from the current time before applying the change. Any less than this is no meaningful difference in the time of day.

You can alternatively use the PD.GlobalUndo.setTimeOfDay method to create an undo/redo action if the time changes.

Parameters:

Name	Type	Description
`time`	number	The time of day in decimal hours (0 to 24).

Returns:

Returns true if the time of day changed, otherwise false.

Type: boolean

setTimeZone(timezone) <static>

Sets the location timezone offset and creates an undo/redo entry.

This method first checks if the new timezone is at least 1 minute from the current timezone before applying the change. Any less than this is no meaningful difference in location.

You can alternatively use the PD.GlobalUndo.setTimeZone method to create an undo/redo action if the location changes.

Parameters:

Name	Type	Description
`timezone`	number	The new timezone in decimal hours (-12 to +13).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setTransformOrigin(pos) <static>

Sets the transform reference point position in the model.

The transform reference point is used by the UI for its interactive rotation and scaling applications.

Parameters:

Name	Type	Description
`pos`	PD.Point	The new model position.

setUnits(units) <static>

Sets the PD.GlobalState.units value.

Parameters:

Name	Type	Description
`units`	PD.DIMENSION	The new units type to set.

setUserMode(mode) <static>

Set a new interactive model edit mode.

Parameters:

Name	Type	Description
`mode`	PD.MODE	The new selection mode.

setUserModeActionMessage(message) <static>

Sets the user mode action message to be displayed in the UI.

User mode messages are used to provide step-by-step instructions to the user as they progress through stages within the currently active PD.UserModeHandler. This will typically be handled by the user mode itself, which will call this method as it progresses through any multi-stage process.

Parameters:

Name	Type	Description
`message`	string	An action message to display in the user interface.

setUserModeCanComplete(state) <static>

Sets whether or not the current multi-stage edit mode can be completed.

When adding a closed path, for example, it will not be valid until it has at least 3 junctions added. This value is typically updated automatically by the current edit mode handler and can be used to enable/disable or show/hide a button within the user interface.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not a call to `completeAction()` will succeed.

setUserModeCapture() <static>

Shortcut to set interactive user mode to PD.MODE.CAPTURE.

setUserModeDeferRebuild(state) <static>

Sets whether or not rebuilds are deferred during interactive user mode edits.

When true, full model rebuilds are only performed when the user mode action is completed or cancelled, typically in the handleDragEnd() method. This can significantly speed up interactive edits that involve many small changes to the model, such as when dragging furniture, single junctions or apertures.

When false, the model is rebuilt after each change, typically in the handleDragMove() and handleDragEnd() methods, which provides immediate visual feedback on the but can be slower for large and/or complex models.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to defer rebuilds during interactive user mode edits.

setUserModeEdit() <static>

Shortcut to set interactive user mode to PD.MODE.EDIT.

setUserModeMeasure() <static>

Shortcut to set interactive user mode to PD.MODE.MEASURE.

setUserModeMove() <static>

Shortcut to set interactive user mode to PD.MODE.MOVE.

setUserModeOrigin() <static>

Shortcut to set interactive user mode to PD.MODE.ORIGIN.

If a valid action is given, the origin is set to the current cursor position, typically the center of the current selection or a junction position. If the action is zero or invalid, the user is prompted to reposition the transform origin using the interactively 3D cursor.

setUserModeRotate() <static>

Shortcut to set interactive user mode to PD.MODE.ROTATE.

setUserModeScale() <static>

Shortcut to set interactive user mode to PD.MODE.SCALE.

setViewDirectAndDiffuseSolar(direct, diffuse) <static>

Sets the global direct and diffuse light levels.

Parameters:

Name	Type	Description
`direct`	number	The direct beam solar radiation, in Watts per metre squared (W/m2).
`diffuse`	number	The diffuse horizontal solar radiation, in Watts per metre squared (W/m2).

setViewSceneSize(view) <static>

Sets the global size of the current model in the scene.

Parameters:

Name	Type	Description
`view`	PD.View	The scene manager view whose size changed.

setViewShading(type) <static>

Set the display to standard values for various shading values.

Standard shading types affect the surface and outline opacity of the model. The available standard types are 0:transparent, 1:opaque, 2:x-ray and 3:lines.

You can also set lightness/darkness shading values using 10:default, 11:dark, 12:light or 13:none.

The type argument can be given as either the numeric value or the associated name. When given as the name, it must include at least the first three letters.

Parameters:

Name	Type	Description
`type`	string \| number	The view type identifier as a number opr string.

setViewSkylightAndSunlight() <static>

Sets surface shading and shadow darkness based on lighting conditions.

setViewSurfaceAndOutlineOpacity(surface_opacity, outline_opacity, outline_darkness) <static>

Sets the global surface and outline opacities.

Parameters:

Name	Type	Description
`surface_opacity`	number	The opacity of 3D surfaces within the model (0 to 1).
`outline_opacity`	number	The opacity of 3D outlines within the model (0 to 1).
`outline_darkness`	number	The lightness/darkness of 3D outlines within the model (0 to 1).

setWindowSize(width, height) <static>

Sets the browser window to the given size.

Parameters:

Name	Type	Description
`width`	number	The new browser window width in pixels.
`height`	number	The new browser window height in pixels.

Example

window.open(
    window.location.href,
    "popupResizableWindow",
    "left=10,top=10,width=1282,height=768"
);

setWorkAreaSize(width, height) <static>

Sets the model canvas to the given size by adjusting the browser window.

Parameters:

Name	Type	Description
`width`	number	The new model canvas width in pixels.
`height`	number	The new model canvas height in pixels.

Example

window.open(
    window.location.href,
    "popupResizableWindow",
    "left=10,top=10,width=1282,height=768"
);

show3D(state) <static>

Sets the PD.GlobalView.show3D flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

show3DToggle() <static>

Toggles the PD.GlobalView.show3D flag on/off.

showAdjacentLevelsToggle() <static>

Toggles the PD.GlobalState.showAdjacentLevels flag on/off.

showAllLevels(state) <static>

Sets the PD.GlobalView.showAll flag and updates the model.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showAllLevelsToggle() <static>

Toggles the PD.GlobalView.showAll flag on/off and updates the model.

showAmbientOcclusion(state) <static>

Sets the PD.GlobalView.showAmbientOcclusion flag and updates the model.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showAmbientOcclusionToggle() <static>

Toggles the PD.GlobalView.showAmbientOcclusion flag on/off and updates the model.

showCursorZArrows(state) <static>

Shows or hides the Z-axis manipulators in the selection manager point edit cursor.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not to show the Z axis manipulators

showCursorZArrowsToggle() <static>

Toggle the visibility of the Z-axis manipulators in the selection manager point edit cursor.

showDoubleSided(state) <static>

Sets the PD.GlobalView.showDoubleSided flag and updates the model.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showDoubleSidedToggle() <static>

Toggles the PD.GlobalView.showDoubleSided flag on/off and updates the model.

showDraftingLines(state) <static>

Sets the PD.GlobalView.showDraftingLines flag and updates the model.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showDraftingLinesToggle() <static>

Toggles the PD.GlobalView.showDraftingLines flag on/off and updates the model.

showDynamicStateMessage(message [, timeout]) <static>

Sets the dynamic state message to be displayed in the UI.

Dynamic state messages are typically used to display things such as rotation angle when dragging the cursor rotator or to notify the user of the triggered menu key when awaiting a two-step key command. They indicate that either further input is being awaited or an urgent action is required.

Parameters:

Name	Type	Argument	Description
`message`	string		A state message to display in the user interface.
`timeout`	number	<optional>	An optional timeout delay in ms, defaults to 2000ms (two seconds).

showFloorGrid(state) <static>

Sets the PD.GlobalView.showFloorGrid flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showFloorGridToggle() <static>

Toggles the PD.GlobalView.showFloorGrid flag on/off.

showGeneralMessage(message [, delay] [, useStatic]) <static>

Triggers a PD.EVENT.SHOW_MESSAGE global event allowing the front-end interface to display the given text as an informational message notification.

This method is called by the framework to display general information or notifications to the user. The UI should respond by displaying a transient info message with the given text. If there is no listeners that handle this event, the message will be logged to the console.

The first argument is obviously a string containing the message to be displayed. The second argument is the preferred duration to display the message for, which defaults to 5000ms (5 seconds) if not given.

The third argument is also optional and indicates whether the message should replace the primary general message or just be added to the general message list. If a process just needs to issue a one-off notification, then it should either not include this argument or set it to false. This is because there may be several other asynchronous processes that are all providing similar notifications and the user needs to be able to see them all.

However, if a process is likely to generate multiple sequential messages that need to supersede each other rather than being potentially stacked on top of each other, then it should include this argument and set it to true. This allows the host application to use a single static notification (such as an alert ot toast) that it can use for such messages. This also allows framework classes an opportunity to 'cancel' the static message by setting the message text to an empty string.

Parameters:

Name	Type	Argument	Description
`message`	string		The message text to display.
`delay`	number	<optional>	An optional display duration in milliseconds. defaults to 5000ms.
`useStatic`	boolean	<optional>	If true, the message will be displayed using a shared static message popup.

showGeneralWarning(warning [, useStatic]) <static>

Triggers a PD.EVENT.SHOW_WARNING global event allowing the front-end interface to display the given text in a warning notification.

This method is called by the framework to display warning messages or notifications to the user. The UI should respond by displaying some sort of eye-catching transient popup with the given text. If there is no listeners that handle this event, the message will be logged as a console warning.

The first argument is obviously a string containing the warning to be displayed.

The second argument is optional and indicates whether the warning should replace the primary warning message or just be added to the warning message list. If a process just needs to issue a one-off warning, then it should either not include this argument or set it to false. This is because there may be several other asynchronous processes that are all providing their own warnings and the user needs to be able to see them all.

However, if a process is likely to generate multiple sequential warnings that need to supersede each other rather than being potentially stacked on top of each other, then it should include this argument and set it to true. This allows the host application to use a single static notification (such as an alert ot toast) that it can use for such messages. This also allows framework classes an opportunity to 'cancel' the static warning by setting the message text to an empty string.

Parameters:

Name	Type	Argument	Description
`warning`	string		The warning text to display.
`useStatic`	boolean	<optional>	If true, the warning will be displayed using a shared static warning popup.

showLevelIndicators(state) <static>

Sets the PD.GlobalView.showLevelIndicators flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showLevelIndicatorsToggle() <static>

Toggles the PD.GlobalView.showLevelIndicators flag on/off.

showModal(id) <static>

Attempts to open/hide a bootstrap modal associated with the DOM element.

This method uses document.getElementById(id) to find the parent DOM element, then uses Bootstrap methods to find and show/hide any modal that is associated with it.

Parameters:

Name	Type	Description
`id`	string	The `id` of the DOM element.

showNorthArrow(state) <static>

Sets the PD.GlobalView.showNorthArrow flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showNorthArrowToggle() <static>

Toggles the PD.GlobalView.showNorthArrow flag on/off.

showOverlapWarning(state) <static>

Triggers a PD.EVENT.SHOW_OVERLAP_WARNING global event allowing the front-end interface to indicate that a spatial overlap exists within the current level.

Parameters:

Name	Type	Description
`state`	boolean	Whether or not a spatial overlap was detected.

showProjectOpenDialog( [prompt]) <static>

Displays the Project Open modal dialog in the main UI.

If the prompt argument is true and there are unsaved changes in the existing model, a confirmation dialog will be displayed to allow the user to cancel the action in order to save their changes.

NOTE: This method is not easy to use as part of a larger script as the display of the dialog box is non-blocking, so the script will continue running whilst the modal dialog is being displayed.

Parameters:

Name	Type	Argument	Description
`prompt`	boolean	<optional>	Whether or not to prompt the user to save existing changes, defaults to true.

Returns:

Returns true if model dialog was opened, or false if user cancelled continue prompt.

Type: boolean

showProjectSaveAsDialog() <static>

Displays the Project SaveAs modal dialog in the main UI.

This allows the user to save the current model with a name of their choice.

NOTE: This method is not easy to use as part of a larger script as the display of the dialog box is non-blocking, so the script will continue running whilst the modal dialog is being displayed.

Returns:

Returns true if model dialog was opened.

Type: boolean

showShadowPlane(state) <static>

Sets the PD.GlobalView.showShadowPlane flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showShadowPlaneToggle() <static>

Toggles the PD.GlobalView.showShadowPlane flag on/off.

showShadows(state) <static>

Sets the PD.GlobalView.showShadows flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showShadowsToggle() <static>

Toggles the PD.GlobalView.showShadows flag on/off.

showSkyDome(state) <static>

Sets the PD.GlobalView.showSkyDome flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showSkyDomeToggle() <static>

Toggles the PD.GlobalView.showSkyDome flag on/off.

showSnapLevel(above) <static>

Displays the level above/below the current level for snapping.

Parameters:

Name	Type	Description
`above`	number	If this value is greater than zero, the level above is shown.

showSpaceColors(state) <static>

Sets the PD.GlobalView.showSpaceColors flag and updates the model.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showSpaceColorsToggle() <static>

Toggles the PD.GlobalView.showSpaceColors flag on/off and updates the model.

showSpatial(state) <static>

Sets the PD.GlobalView.showSpatial flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showSpatialToggle() <static>

Toggles the PD.GlobalView.showSpatial flag on/off.

showSunPath(state) <static>

Sets the PD.GlobalView.showSunPath flag.

Parameters:

Name	Type	Description
`state`	boolean	The new state to set.

showSunPathToggle() <static>

Toggles the PD.GlobalView.showSunPath flag on/off.

showTransientDynamicStateMessage(message [, timeout]) <static>

Sets the dynamic state message to be displayed in the UI.

Parameters:

Name	Type	Argument	Description
`message`	string		A state message to display in the user interface.
`timeout`	number	<optional>	An optional timeout delay in ms, defaults to 2500ms (two seconds).

showTransientStatusMessage( [message] [, timeout]) <static>

Shows a temporary application status message then returns to 'Idle'.

If a status message is given, it will be displayed for a short period (two seconds) before defaulting back to 'Idle.'.

Parameters:

Name	Type	Argument	Description
`message`	string	<optional>	An optional message to temporarily display.
`timeout`	string	<optional>	An optional timeout delay in ms, defaults to 2000ms (two seconds).

showUI(showContainerId [, hideContainerId]) <static>

Shows the main user interface and removes any splash screen.

Call this method after the initial setup of your application and after the UI has been initialised. The aim of this method is to hide all the initial fragmentary redraws that may occur as each component of the UI is being added and hydrated.

In essence, it simply sets the opacity of the show container to 1 (allowing it to fade in if it has the Bootstrap fade class assigned) and, if a hide container is given, it is removed from the document.

Parameters:

Name	Type	Argument	Description
`showContainerId`	string		The DOM id of the main UI container to show.
`hideContainerId`	string	<optional> <nullable>	The DOM id of any splash screen container to hide.

stepInToSelection() <static>

Descends down into the current selection one step at a time.

stepOutOfSelection() <static>

Backs out of the current selection one step at a time.

If an aperture is selected, this selects the junction that owns the aperture. If a junction is selected, this selects the element that owns the junction. If an element is selected, this selects the space that owns the element. If a space is selected, everything is de-selected.

syncProjectTree() <static>

Rebuilds a simple hierarchical list of the structures, levels, spaces and elements in the current project.

toggleAccordionItems(id) <static>

Toggles the state of all collapsible accordion items in the DOM element with the given id attribute value.

Parameters:

Name	Type	Description
`id`	string	The `id` value of the DOM element to iterate.

toggleAdjacencyShowAdjacent() <static>

Toggles PD.GlobalState.adjacencyModeShowAdjacent between true and false and updates spatial view.

toggleAdjacencyShowApertures() <static>

Toggles PD.GlobalState.adjacencyModeShowApertures between true and false and updates spatial view.

toggleCollapsibleItems(id) <static>

Toggles the state of all collapsible child items in the DOM element with the given id attribute value.

Parameters:

Name	Type	Description
`id`	string	The `id` value of the DOM element to iterate.

toggleElementParentChild() <static>

If the current element is owned by a space, selects the parent space, otherwise selects the first child element.

toggleLookAtOrFitView( [event]) <static>

Checks if something is selected and adjusts the view to look at it, otherwise zooms to fit model.

Parameters:

Name	Type	Argument	Description
`event`	Event	<optional>	The UI event that triggered this action.

toggleSegmentOrJunction() <static>

Toggles the Selection Manager selection type between PD.SELECTED.JUNCTION and PD.SELECTED.SEGMENT.

toggleSidePanelsPin(width) <static>

Toggles the pinned state of the side panels.

This method toggles the state of the PD.GlobalState.sidePanelsPin flag and updates the side panels accordingly. If side panels are pinned, the canvas width is adjusted to accommodate them; otherwise, only the HUD is adjusted.

Parameters:

Name	Type	Description
`width`	number	The width of the toggled side panel in pixels.

undo() <static>

Undoes the last action, if PD.GlobalUndo is active and available.

undo() <static>

Undoes the last action, if active and available.

updateAdjacentLevels() <static>

Checks to display other levels at the same height as the current level.

Ths method first checks the value of PD.GlobalState.showAdjacentLevel before showing additional levels.

updateAnnotations() <static>

Updates the default north arrow and level markers when toggled.

updateDarkMode( [update_only]) <static>

Updates the document and model for light/dark mode.

This method applies the 'dark' or 'light' classes to the html element in the document and adds the 'data-bs-theme' attribute. It also generates a PD.EVENT.DARK_MODE global event to update the current model.

Parameters:

Name	Type	Argument	Description
`update_only`	boolean	<optional> <nullable>	An optional flag to not dispatch a global event.

updateDrawingView( [drawing]) <static>

Updates the view to match the current scene view.

Parameters:

Name	Type	Argument	Description
`drawing`	BIM.DrawingView	<optional>	The view to update, defaults to the current view.

Returns:

Returns the updated view, if any.

Type: BIM.DrawingView

updateDrawingViews() <static>

Triggers a PD.EVENT.DWG_VIEWS_CHANGED global event allowing the front-end interface to update its stored view list.

updateHUDIndicators() <static>

Updates the HUD indicator when related parameters are edited.

updateHUDLayout() <static>

Updates the HUD when its layout parameters are edited.

updateLocation( [forceUpdate]) <static>

Allows the host application to react to location changes,

This is mainly used by file import methods to update the global location as soon as it is read and prior to their own calculations.

Parameters:

Name	Type	Argument	Default	Description
`forceUpdate`	boolean	<optional>	false	Whether or not to update instantly rather than use debounced update.

updateNorthArrowAlignment() <static>

Updates the north arrow position based on a new alignment.

updateNorthArrowPos() <static>

Updates the north arrow alignment based on a new position.

updateSelection() <static>

Updates the selection UI based on the current selection manager state.

This method forces an update of dynamic parameter values using the current selection set. This is normally handled entirely automatically by the front end framework, but is sometimes needed when the application changes selection set properties programmatically, such as during an undo/redo or when dynamically adding a junction to a path inside an interactive user mode.

In order to speed things up and prevent unnecessary DOM updates, selection data in the UI is cached and only changes when existing values are updated. Thus, if the selection set itself hasn't changed, only changed parameter values and properties will be updated.

To clear the cache and force a full reload/refresh of the dynamic parameter UI components, use the PD.GlobalActions.reloadSelectionUI method.

updateSelectionMeshes() <static>

Regenerates the selection set highlight and dimension meshes.

This is typically called when the view zoom changes as dimensions and highlight lines are sized to both the model and the current view.

updateSidePanels(width) <static>

Update the <main> work area to accommodate side panels.

This method checks PD.GlobalState.sidePanelsPin to determine if the width of the <main> work area in the application needs to be adjusted to fit the currently active side panel. The width of the work area is adjusted by setting its style.right property to the given width in pixels. If no side panel is displayed, the given width will be zero.

For this to work, the <main> element must be positioned as fixed with its size governed by the top, bottom, left and right css properties. This allows the <main> element to be resized dynamically without affecting the rest of the page layout. Your application should also listen for the PD.EVENT.SIDE_PANEL_PIN event to update any sub- panels to fit the newly size work area, as shown below

Parameters:

Name	Type	Description
`width`	number	The width of the current side panel in pixels.

Examples

css
    main {
        position: fixed;
        top: 3rem; \/* Leave space for navbar header. *\/
        right: 0;
        bottom: 1.85rem; \/* Leave space for footer. *\/
        left: 0;
    }

javascript
    /// Resize 3D model canvas to fit pinned side panel.
    PD.GlobalEvents.addEventListener(PD.EVENT.SIDE_PANEL_PIN, () => {
       const scene = PD.GlobalActions.sceneManager;
       if (scene) scene.handleResize();
    });

javascript
    /// Resize split panels to fit pinned side panel.
    PD.GlobalEvents.addEventListener(PD.EVENT.SIDE_PANEL_PIN, () => {
        this.handleSplitPaneResize();
    });

    /// ...

   ///
   /// Invoked whenever a pane resizer is dragged
   /// or the main work area changed size.
   ///
   handlePaneResize(element) {

       const scene = PD.GlobalActions.sceneManager;
       if (scene) scene.handleResize();

       if (this.$refs.worldMap) {
           this.$refs.worldMap.resize();
       }

       if (this.chartDayLength) {
           this.chartDayLength.rescale(true);
       }

   },

updateSkyConditions() <static>

Updates the sky dome conditions based on the current solar position and weather data.

updateSkySubDivParameters() <static>

Updates the sky dome subdivision parameters.

updateSkyType() <static>

Updates the sky type and sets appropriate sky parameters.

updateSnapUnits() <static>

Allows the host application to control snap settings when units change.

NOTE: This is called when the dimension units are changed between imperial/metric. It is called when the PD.DIMENSION.units value changes as this is when/where PD.DIMENSION.useImperial is set, on which this method is based.

updateSunPathDiagram( [forceUpdate]) <static>

Updates the 3D Sun-path diagram when display properties changes.

Parameters:

Name	Type	Argument	Description
`forceUpdate`	boolean	<optional>	An optional flag to force an instant update rather than an animated transition.

updateSunPathProjection() <static>

Updates the sun path altitude projection method.

updateSunPosition() <static>

Updates the sun position and shadows when the date, time or location changes.

updateUnits() <static>

Update the model and UI when the units type changes.

This method is called whenever the user changes the units type in the application settings. It updates the PD.GlobalStateProxy.units value, dispatches a PD.EVENT.DIMENSION_UNITS event and rebuilds the scene to update areas, dimensions and annotations.

updateUnits() <static>

Update the model and UI when the units type changes.

updateUserMode() <static>

Updates the interactive model edit mode to match selection manager.

This method provides the host application an opportunity to respond immediately to interactive user mode changes.

updateViewOpacity() <static>

Updates model surfaces and outlines when view type display settings change.

updateViewShading() <static>

Updates light and shade based on lighting conditions.

videoCapture(action) <static>

This is a convenience method to allow applications to control video capture without having to directly access the screen capture dialog.

You can can call this method to start, pause, stop or abort recordings. The action argument can be record, pause, stop or abort.

Parameters:

Name	Type	Description
`action`	string	An action string of `record`, `pause`, `stop` or `abort`.

viewDampingFactorUpdate() <static>

Updates the main view controller when PD.GlobalState.viewDampingFactor changes.

viewNavigationSpeed(value) <static>

Sets the PD.GlobalState.viewNavigationSpeed value.

Parameters:

Name	Type	Description
`value`	number	The new navigation speed to set (0 to 10).

viewNavigationSpeedUpdate() <static>

Updates the main view controller when PD.GlobalState.viewNavigationSpeed changes.

zoomIn( [event]) <static>

Zooms the current model view in.

Parameters:

Name	Type	Argument	Description
`event`	Event	<optional>	The UI event that triggered this action.

zoomOut( [event]) <static>

Zooms the current model view out.

Parameters:

Name	Type	Argument	Description
`event`	Event	<optional>	The UI event that triggered this action.