Class ApplicationV2<Configuration, RenderOptions>

The Application class is responsible for rendering an HTMLElement into the Foundry Virtual Tabletop user interface.

Alias

ApplicationV2

Type Parameters

Configuration
RenderOptions

Hierarchy (view full)

__type<ObjectConstructor, this> & Object
- ApplicationV2

Index

Constructors

constructor

new ApplicationV2<Configuration, RenderOptions>(options?): ApplicationV2<Configuration, RenderOptions>
Applications are constructed by providing an object of configuration options.
Type Parameters
- Configuration extends applications.types.ApplicationConfiguration
- RenderOptions extends ApplicationRenderOptions
Parameters
- Optional options: Partial<Configuration> = {}
  Options used to configure the Application instance
Returns ApplicationV2<Configuration, RenderOptions>
Overrides EventEmitterMixin(Object).constructor

Properties

options

options: Configuration

Application instance configuration options.

tabGroups

tabGroups: Record<string, string> = {}

If this Application uses tabbed navigation groups, this mapping is updated whenever the changeTab method is called. Reports the active tab for each group. Subclasses may override this property to define default tabs for each group.

position

position: ApplicationPosition = ...

The current position of the application with respect to the window.document.body.

`Private` #id

#id: string

`Private` #renderable

#renderable: boolean = true

Flag that this Application instance is renderable. Applications are not renderable unless a subclass defines the _renderHTML and _replaceHTML methods.

`Private` #element

#element: HTMLDivElement

The outermost HTMLElement of this rendered Application. For window applications this is ApplicationV2##frame. For non-window applications this ApplicationV2##content.

`Private` #content

#content: HTMLElement

The HTMLElement within which inner HTML is rendered. For non-window applications this is the same as ApplicationV2##element.

`Private` #minimization

#minimization: {
active: boolean;
} = ...

Data pertaining to the minimization status of the Application.

Type declaration

active: boolean

`Private` #position

#position: ApplicationPosition = ...

The rendered position of the Application.

`Private` #state

#state: Readonly<{
    ERROR: -3;
    CLOSING: -2;
    CLOSED: -1;
    NONE: 0;
    RENDERING: 1;
    RENDERED: 2;
}> = ApplicationV2.RENDER_STATES.NONE

Type declaration

ERROR: -3
CLOSING: -2
CLOSED: -1
NONE: 0
RENDERING: 1
RENDERED: 2

`Private` #semaphore

#semaphore: Semaphore = ...

A Semaphore used to enqueue asynchronous operations.

`Private` #controlsExpanded

#controlsExpanded: boolean = false

Is the window control buttons menu currently expanded?

`Private` #events

#events: Record<string, Map<EmittedEventListener, {
fn: EmittedEventListener;
once: boolean;
}>> = {}

A mapping of registered events.

`Static` BASE_APPLICATION

BASE_APPLICATION: typeof ApplicationV2 = ApplicationV2

Designates which upstream Application class in this class' inheritance chain is the base application. Any DEFAULT_OPTIONS of super-classes further upstream of the BASE_APPLICATION are ignored. Hook events for super-classes further upstream of the BASE_APPLICATION are not dispatched.

`Static` DEFAULT_OPTIONS

DEFAULT_OPTIONS: Configuration = ...

The default configuration options which are assigned to every instance of this Application class.

`Static` RENDER_STATES

RENDER_STATES: Readonly<{
    ERROR: -3;
    CLOSING: -2;
    CLOSED: -1;
    NONE: 0;
    RENDERING: 1;
    RENDERED: 2;
}> = ...

The sequence of rendering states that describe the Application life-cycle.

Type declaration

ERROR: -3
CLOSING: -2
CLOSED: -1
NONE: 0
RENDERING: 1
RENDERED: 2

`Static` emittedEvents

emittedEvents: readonly string[] = ...

`Static` `Private` #frontApp

#frontApp: ApplicationV2<any, any>

Which application is currently "in front" with the maximum z-index

Accessors

window

get window(): {
    header: HTMLElement;
    resize: HTMLElement;
    title: HTMLHeadingElement;
    icon: HTMLElement;
    close: HTMLButtonElement;
    controls: HTMLButtonElement;
    controlsDropdown: HTMLDivElement;
    onDrag: Function;
    onResize: Function;
    pointerStartPosition: ApplicationPosition;
    pointerMoveThrottle: boolean;
}
Convenience references to window header elements.

Returns {
    header: HTMLElement;
    resize: HTMLElement;
    title: HTMLHeadingElement;
    icon: HTMLElement;
    close: HTMLButtonElement;
    controls: HTMLButtonElement;
    controlsDropdown: HTMLDivElement;
    onDrag: Function;
    onResize: Function;
    pointerStartPosition: ApplicationPosition;
    pointerMoveThrottle: boolean;
}
- header: HTMLElement
- resize: HTMLElement
- title: HTMLHeadingElement
- icon: HTMLElement
- close: HTMLButtonElement
- controls: HTMLButtonElement
- controlsDropdown: HTMLDivElement
- onDrag: Function
- onResize: Function
- pointerStartPosition: ApplicationPosition
- pointerMoveThrottle: boolean

classList

get classList(): DOMTokenList
The CSS class list of this Application instance

Returns DOMTokenList

id

get id(): string
The HTML element ID of this Application instance.

Returns string

title

get title(): string
A convenience reference to the title of the Application window.

Returns string

element

get element(): HTMLElement
The HTMLElement which renders this Application into the DOM.

Returns HTMLElement

minimized

get minimized(): boolean
Is this Application instance currently minimized?

Returns boolean

rendered

get rendered(): boolean
Is this Application instance currently rendered?

Returns boolean

state

get state(): Readonly<{
    ERROR: -3;
    CLOSING: -2;
    CLOSED: -1;
    NONE: 0;
    RENDERING: 1;
    RENDERED: 2;
}>
The current render state of the Application.

Returns Readonly<{
    ERROR: -3;
    CLOSING: -2;
    CLOSED: -1;
    NONE: 0;
    RENDERING: 1;
    RENDERED: 2;
}>

hasFrame

get hasFrame(): boolean
Does this Application instance render within an outer window frame?

Returns boolean

Methods

render

render(options?, _options?): Promise<ApplicationV2<any, any>>
Render the Application, creating its HTMLElement and replacing its innerHTML. Add it to the DOM if it is not currently rendered and rendering is forced. Otherwise, re-render its contents.
Parameters
- Optional options: boolean | RenderOptions = {}
  Options which configure application rendering behavior. A boolean is interpreted as the "force" option.
- Optional _options: RenderOptions = {}
  Legacy options for backwards-compatibility with the original ApplicationV1#render signature.
Returns Promise<ApplicationV2<any, any>>
A Promise which resolves to the rendered Application instance

_renderHTML

_renderHTML(context, options): Promise<any>
Render an HTMLElement for the Application. An Application subclass must implement this method in order for the Application to be renderable.
Parameters
- context: Object
  Context data for the render operation
- options: RenderOptions
  Options which configure application rendering behavior
Returns Promise<any>
The result of HTML rendering may be implementation specific. Whatever value is returned here is passed to _replaceHTML

Abstract

close

close(options?): Promise<ApplicationV2<any, any>>
Close the Application, removing it from the DOM.
Parameters
- Optional options: ApplicationClosingOptions = {}
  Options which modify how the application is closed.
Returns Promise<ApplicationV2<any, any>>
A Promise which resolves to the closed Application instance

setPosition

setPosition(position?): ApplicationPosition
Update the Application element position using provided data which is merged with the prior position.
Parameters
- Optional position: Partial<ApplicationPosition>
  New Application positioning data
Returns ApplicationPosition
The updated application position

toggleControls

toggleControls(expanded?): void
Toggle display of the Application controls menu. Only applicable to window Applications.
Parameters
- Optional expanded: boolean
  Set the controls visibility to a specific state. Otherwise, the visible state is toggled from its current value
Returns void

minimize

minimize(): Promise<void>
Minimize the Application, collapsing it to a minimal header.

Returns Promise<void>

maximize

maximize(): Promise<void>
Restore the Application to its original dimensions.

Returns Promise<void>

bringToFront

bringToFront(): void
Bring this Application window to the front of the rendering stack by increasing its z-index. Once ApplicationV1 is deprecated we should switch from _maxZ to ApplicationV2#maxZ We should also eliminate ui.activeWindow in favor of only ApplicationV2#frontApp

Returns void

changeTab

changeTab(tab, group, options?): void
Change the active tab within a tab group in this Application instance.
Parameters
- tab: string
  The name of the tab which should become active
- group: string
  The name of the tab group which defines the set of tabs
- Optional options: {
      event: Event;
      navElement: HTMLElement;
      force: boolean;
      updatePosition: boolean;
  } = {}
  Additional options which affect tab navigation
  - event: Event
    An interaction event which caused the tab change, if any
  - navElement: HTMLElement
    An explicit navigation element being modified
  - force: boolean
    Force changing the tab even if the new tab is already active
  - updatePosition: boolean
    Update application position after changing the tab?
Returns void

_onChangeForm

_onChangeForm(formConfig, event): void
Handle changes to an input element within the form.
Parameters
- formConfig: ApplicationFormConfiguration
  The form configuration for which this handler is bound
- event: Event
  An input change event within the form
Returns void

_awaitTransition

_awaitTransition(element, timeout): Promise<void>
Internal
Wait for a CSS transition to complete for an element.
Parameters
- element: HTMLElement
  The element which is transitioning
- timeout: number
  A timeout in milliseconds in case the transitionend event does not occur
Returns Promise<void>

addEventListener

addEventListener(type, listener, options?): void
Add a new event listener for a certain type of event.
Parameters
- type: string
  The type of event being registered for
- listener: EmittedEventListener
  The listener function called when the event occurs
- Optional options: {
  once: boolean;
  } = {}
  Options which configure the event listener
  - once: boolean
    Should the event only be responded to once and then removed
Returns void
See
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

Inherited from EventEmitterMixin(Object).addEventListener

removeEventListener

removeEventListener(type, listener): void
Remove an event listener for a certain type of event.
Parameters
- type: string
  The type of event being removed
- listener: EmittedEventListener
  The listener function being removed
Returns void
See
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener

Inherited from EventEmitterMixin(Object).removeEventListener

dispatchEvent

dispatchEvent(event): boolean
Dispatch an event on this target.
Parameters
- event: Event
  The Event to dispatch
Returns boolean
Was default behavior for the event prevented?

See
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent

Inherited from EventEmitterMixin(Object).dispatchEvent

`Protected` _initializeApplicationOptions

_initializeApplicationOptions(options): applications.types.ApplicationConfiguration
Protected
Initialize configuration options for the Application instance. The default behavior of this method is to intelligently merge options for each class with those of their parents.
- Array-based options are concatenated
- Inner objects are merged
- Otherwise, properties in the subclass replace those defined by a parent
Parameters
- options: Partial<applications.types.ApplicationConfiguration>
  Options provided directly to the constructor
Returns applications.types.ApplicationConfiguration
Configured options for the application instance

`Protected` _configureRenderOptions

_configureRenderOptions(options): void
Protected
Modify the provided options passed to a render request.
Parameters
- options: RenderOptions
  Options which configure application rendering behavior
Returns void

`Protected` _prepareContext

_prepareContext(options): Promise<Object>
Protected
Prepare application rendering context data for a given render request.
Parameters
- options: RenderOptions
  Options which configure application rendering behavior
Returns Promise<Object>
Context data for the render operation

`Protected` _getHeaderControls

_getHeaderControls(): ApplicationHeaderControlsEntry[]
Protected
Configure the array of header control menu options

Returns ApplicationHeaderControlsEntry[]

`Protected` _headerControlButtons

_headerControlButtons(): Generator<ApplicationHeaderControlsEntry, any, any>
Protected
Iterate over header control buttons, filtering for controls which are visible for the current client.

Returns Generator<ApplicationHeaderControlsEntry, any, any>
Yields

`Protected` _replaceHTML

_replaceHTML(result, content, options): void
Protected
Replace the HTML of the application with the result provided by the rendering backend. An Application subclass should implement this method in order for the Application to be renderable.
Parameters
- result: any
  The result returned by the application rendering backend
- content: HTMLElement
  The content element into which the rendered result must be inserted
- options: RenderOptions
  Options which configure application rendering behavior
Returns void

`Protected` _renderFrame

_renderFrame(options): Promise<HTMLElement>
Protected
Render the outer framing HTMLElement which wraps the inner HTML of the Application.
Parameters
- options: RenderOptions
  Options which configure application rendering behavior
Returns Promise<HTMLElement>

`Protected` _renderHeaderControl

_renderHeaderControl(control): HTMLLIElement
Protected
Render a header control button.
Parameters
- control: ApplicationHeaderControlsEntry
Returns HTMLLIElement

`Protected` _updateFrame

_updateFrame(options): void
Protected
When the Application is rendered, optionally update aspects of the window frame.
Parameters
- options: RenderOptions
  Options provided at render-time
Returns void

`Protected` _insertElement

_insertElement(element): void
Protected
Insert the application HTML element into the DOM. Subclasses may override this method to customize how the application is inserted.
Parameters
- element: HTMLElement
  The element to insert
Returns void

`Protected` _removeElement

_removeElement(element): void
Protected
Remove the application HTML element from the DOM. Subclasses may override this method to customize how the application element is removed.
Parameters
- element: HTMLElement
  The element to be removed
Returns void

`Protected` _updatePosition

_updatePosition(position): ApplicationPosition
Protected
Translate a requested application position updated into a resolved allowed position for the Application. Subclasses may override this method to implement more advanced positioning behavior.
Parameters
- position: ApplicationPosition
  Requested Application positioning data
Returns ApplicationPosition
Resolved Application positioning data

`Protected` _canRender

_canRender(options): false | void
Protected
Test whether this Application is allowed to be rendered.
Parameters
- options: RenderOptions
  Provided render options
Returns false | void
Return false to prevent rendering

Throws
An Error to display a warning message

`Protected` _preFirstRender

_preFirstRender(context, options): Promise<void>
Protected
Actions performed before a first render of the Application.
Parameters
- context: Object
  Prepared context data
- options: RenderOptions
  Provided render options
Returns Promise<void>

`Protected` _onFirstRender

_onFirstRender(context, options): void
Protected
Actions performed after a first render of the Application. Post-render steps are not awaited by the render process.
Parameters
- context: Object
  Prepared context data
- options: RenderOptions
  Provided render options
Returns void

`Protected` _preRender

_preRender(context, options): Promise<void>
Protected
Actions performed before any render of the Application. Pre-render steps are awaited by the render process.
Parameters
- context: Object
  Prepared context data
- options: RenderOptions
  Provided render options
Returns Promise<void>

`Protected` _onRender

_onRender(context, options): void
Protected
Actions performed after any render of the Application. Post-render steps are not awaited by the render process.
Parameters
- context: Object
  Prepared context data
- options: RenderOptions
  Provided render options
Returns void

`Protected` _preClose

_preClose(options): Promise<void>
Protected
Actions performed before closing the Application. Pre-close steps are awaited by the close process.
Parameters
- options: RenderOptions
  Provided render options
Returns Promise<void>

`Protected` _onClose

_onClose(options): void
Protected
Actions performed after closing the Application. Post-close steps are not awaited by the close process.
Parameters
- options: RenderOptions
  Provided render options
Returns void

`Protected` _prePosition

_prePosition(position): void
Protected
Actions performed before the Application is re-positioned. Pre-position steps are not awaited because setPosition is synchronous.
Parameters
- position: ApplicationPosition
  The requested application position
Returns void

`Protected` _onPosition

_onPosition(position): void
Protected
Actions performed after the Application is re-positioned.
Parameters
- position: ApplicationPosition
  The requested application position
Returns void

`Protected` _attachFrameListeners

_attachFrameListeners(): void
Protected
Attach event listeners to the Application frame.

Returns void

`Protected` _onClickAction

_onClickAction(event, target): void
Protected
A generic event handler for action clicks which can be extended by subclasses. Action handlers defined in DEFAULT_OPTIONS are called first. This method is only called for actions which have no defined handler.
Parameters
- event: PointerEvent
  The originating click event
- target: HTMLElement
  The capturing HTML element which defined a [data-action]
Returns void

`Protected` _onSubmitForm

_onSubmitForm(formConfig, event): Promise<void>
Protected
Handle submission for an Application which uses the form element.
Parameters
- formConfig: ApplicationFormConfiguration
  The form configuration for which this handler is bound
- event: Event | SubmitEvent
  The form submission event
Returns Promise<void>

`Private` #render

#render(options?): Promise<ApplicationV2<any, any>>
Manage the rendering step of the Application life-cycle. This private method delegates out to several protected methods which can be defined by the subclass.
Parameters
- Optional options: RenderOptions
  Options which configure application rendering behavior
Returns Promise<ApplicationV2<any, any>>
A Promise which resolves to the rendered Application instance

`Private` #close

#close(options?): Promise<ApplicationV2<any, any>>
Manage the closing step of the Application life-cycle. This private method delegates out to several protected methods which can be defined by the subclass.
Parameters
- Optional options: ApplicationClosingOptions
  Options which modify how the application is closed
Returns Promise<ApplicationV2<any, any>>
A Promise which resolves to the rendered Application instance

`Private` #applyPosition

#applyPosition(position): void
Apply validated position changes to the element.
Parameters
- position: ApplicationPosition
  The new position data to apply.
Returns void

`Private` #doEvent

#doEvent(handler, options?): Promise<void>
Perform an event in the application life-cycle. Await an internal life-cycle method defined by the class. Optionally dispatch an event for any registered listeners.
Parameters
- handler: Function
  A handler function to call
- options: {
      async: boolean;
      handlerArgs: any[];
      debugText: string;
      eventName: string;
      hookName: string;
      hookArgs: any[];
  } = {}
  Options which configure event handling
  - async: boolean
    Await the result of the handler function?
  - handlerArgs: any[]
    Arguments passed to the handler function
  - debugText: string
    Debugging text to log for the event
  - eventName: string
    An event name to dispatch for registered listeners
  - hookName: string
    A hook name to dispatch for this and all parent classes
  - hookArgs: any[]
    Arguments passed to the requested hook function
Returns Promise<void>
A promise which resoles once the handler is complete

`Private` #onPointerDown

#onPointerDown(event): Promise<void>
Handle initial pointerdown events inside a rendered Application.
Parameters
- event: PointerEvent
Returns Promise<void>

`Private` #onClick

#onClick(event): Promise<void>
Centralized handling of click events which occur on or within the Application frame.
Parameters
- event: PointerEvent
Returns Promise<void>

`Private` #onClickAction

#onClickAction(event, target): void
Handle a click event on an element which defines a [data-action] handler.
Parameters
- event: PointerEvent
  The originating click event
- target: HTMLElement
  The capturing HTML element which defined a [data-action]
Returns void

`Private` #onClickTab

#onClickTab(event): void
Handle click events on a tab within the Application.
Parameters
- event: PointerEvent
Returns void

`Private` #startPointerCapture

#startPointerCapture(event, callback): void
Begin capturing pointer events on the application frame.
Parameters
- event: PointerEvent
  The triggering event.
- callback: Function
  The callback to attach to pointer move events.
Returns void

`Private` #endPointerCapture

#endPointerCapture(event, callback): void
End capturing pointer events on the application frame.
Parameters
- event: PointerEvent
  The triggering event.
- callback: Function
  The callback to remove from pointer move events.
Returns void

`Private` #onPointerMove

#onPointerMove(event): void | {
dx: number;
dy: number;
}
Handle a pointer move event while dragging or resizing the window frame.
Parameters
- event: PointerEvent
Returns void | {
dx: number;
dy: number;
}
The amount the cursor has moved since the last frame, or undefined if the movement occurred between frames.

`Private` #onWindowDragStart

#onWindowDragStart(event): void
Begin dragging the Application position.
Parameters
- event: PointerEvent
Returns void

`Private` #onWindowResizeStart

#onWindowResizeStart(event): void
Begin resizing the Application.
Parameters
- event: PointerEvent
Returns void

`Private` #onWindowDragMove

#onWindowDragMove(event): void
Drag the Application position during mouse movement.
Parameters
- event: PointerEvent
Returns void

`Private` #onWindowResizeMove

#onWindowResizeMove(event): void
Resize the Application during mouse movement.
Parameters
- event: PointerEvent
Returns void

`Private` #onWindowDoubleClick

#onWindowDoubleClick(event): void
Double-click events on the window title are used to minimize or maximize the application.
Parameters
- event: PointerEvent
Returns void

`Static` inheritanceChain

inheritanceChain(): Generator<typeof ApplicationV2, void, unknown>
Iterate over the inheritance chain of this Application. The chain includes this Application itself and all parents until the base application is encountered.

Returns Generator<typeof ApplicationV2, void, unknown>
See
ApplicationV2.BASE_APPLICATION

Generator
Yields

`Static` parseCSSDimension

parseCSSDimension(style, parentDimension): number
Parse a CSS style rule into a number of pixels which apply to that dimension.
Parameters
- style: string
  The CSS style rule
- parentDimension: number
  The relevant dimension of the parent element
Returns number
The parsed style dimension in pixels

Class ApplicationV2<Configuration, RenderOptions>

Alias

Type Parameters

Hierarchy (view full)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns ApplicationV2<Configuration, RenderOptions>

Properties

options

tabGroups

position

Private #id

Private #renderable

Private #element

Private #content

Private #minimization

Type declaration

active: boolean

Private #position

Private #state

Type declaration

ERROR: -3

CLOSING: -2

CLOSED: -1

NONE: 0

RENDERING: 1

RENDERED: 2

Private #semaphore

Private #controlsExpanded

Private #events

Static BASE_APPLICATION

Static DEFAULT_OPTIONS

Static RENDER_STATES

Type declaration

ERROR: -3

CLOSING: -2

CLOSED: -1

NONE: 0

RENDERING: 1

RENDERED: 2

Static emittedEvents

Static Private #frontApp

Accessors

window

Returns { header: HTMLElement; resize: HTMLElement; title: HTMLHeadingElement; icon: HTMLElement; close: HTMLButtonElement; controls: HTMLButtonElement; controlsDropdown: HTMLDivElement; onDrag: Function; onResize: Function; pointerStartPosition: ApplicationPosition; pointerMoveThrottle: boolean; }

header: HTMLElement

resize: HTMLElement

title: HTMLHeadingElement

icon: HTMLElement

close: HTMLButtonElement

controls: HTMLButtonElement

controlsDropdown: HTMLDivElement

onDrag: Function

onResize: Function

pointerStartPosition: ApplicationPosition

pointerMoveThrottle: boolean

classList

Returns DOMTokenList

id

Returns string

title

Returns string

element

Returns HTMLElement

minimized

Returns boolean

rendered

Returns boolean

state

Returns Readonly<{ ERROR: -3; CLOSING: -2; CLOSED: -1; NONE: 0; RENDERING: 1; RENDERED: 2; }>

hasFrame

Returns boolean

Methods

`Private` #id

`Private` #renderable

`Private` #element

`Private` #content

`Private` #minimization

`Private` #position

`Private` #state

`Private` #semaphore

`Private` #controlsExpanded

`Private` #events

`Static` BASE_APPLICATION

`Static` DEFAULT_OPTIONS

`Static` RENDER_STATES

`Static` emittedEvents

`Static` `Private` #frontApp

Returns {
header: HTMLElement;
resize: HTMLElement;
title: HTMLHeadingElement;
icon: HTMLElement;
close: HTMLButtonElement;
controls: HTMLButtonElement;
controlsDropdown: HTMLDivElement;
onDrag: Function;
onResize: Function;
pointerStartPosition: ApplicationPosition;
pointerMoveThrottle: boolean;
}

Returns Readonly<{
ERROR: -3;
CLOSING: -2;
CLOSED: -1;
NONE: 0;
RENDERING: 1;
RENDERED: 2;
}>

`Protected` _initializeApplicationOptions

`Protected` _configureRenderOptions

`Protected` _prepareContext

`Protected` _getHeaderControls

`Protected` _headerControlButtons

`Protected` _replaceHTML

`Protected` _renderFrame

`Protected` _renderHeaderControl