VistaBox Class

The VistaBox class is an abstract base class for all content types in VistaView. Extend this class to create custom content types like videos, maps, or interactive elements.

Overview

VistaBox handles:

• Image sizing and scaling
• Zoom and pan transformations
• Lifecycle management (init, load, destroy)
• State management for width, height, and transformations

Use Case: Create custom content extensions by extending VistaBox. See Extensions for examples.

Public Properties

element

abstract element: HTMLImageElement | HTMLDivElement

The DOM element containing the content. Must be implemented by subclasses.

state

state: VistaImageState;

Current state of the image including dimensions and transformations. Contains internal properties prefixed with _ (e.g., _width, _height, _transform).

pos

pos: number;

Position relative to the current image (0 = center, -1 = left, 1 = right).

index

index: number;

Zero-based index in the gallery.

config

config: VistaImgConfig;

Image configuration containing src, alt, and srcSet.

origin

origin: VistaImgOrigin | undefined;

Information about the origin element (thumbnail) in the DOM.

isReady

isReady: boolean;

Whether the content has finished loading.

thumb

thumb: HTMLDivElement | null;

Thumbnail element used during transitions.

Public Methods

constructor()

constructor(par: VistaImageParams)

Creates a new VistaBox instance. Called by VistaView during initialization.

init()

async init(): Promise<void>

Initializes the content. Override this to implement custom loading logic.

setSizes()

setSizes(par?: { stableSize?: boolean; initDimension?: boolean }): void

Calculates and sets dimensions based on viewport and content size.

Parameters:

• par.stableSize - Use cached dimensions without recalculation
• par.initDimension - Calculate initial dimensions from origin element

prepareClose()

prepareClose(): void

Prepares the element for closing transition. Called before the lightbox closes.

cancelPendingLoad()

cancelPendingLoad(): void

Cancels any in-progress image loading operations.

destroy()

destroy(): void

Cleans up resources and removes event listeners. Called when the element is no longer needed.

cloneStyleFrom()

cloneStyleFrom(img: VistaBox, state?: VistaHiresTransitionOpt): void

Copies style and state from another VistaBox instance. Used during transitions to maintain visual continuity.

toObject()

toObject(): VistaImageClone

Returns a serializable representation of the current state. Used for the onContentChange event.

setInitialCenter()

setInitialCenter(center: { x: number; y: number }): void

Sets the center point for zoom and pan operations.

onImageReady()

onImageReady(): void

Override this method to perform actions when the content is ready.

animateZoom()

animateZoom(scaleFactor: number, center?: { x: number; y: number }): void

Override to implement custom zoom animation logic.

scaleMove()

scaleMove(scaleFactor: number, center?: { x: number; y: number }, animate?: boolean): void

Override to implement custom scale and movement logic.

momentumThrow()

momentumThrow(par: { x: number; y: number }): () => void

Override to implement momentum scrolling after a swipe gesture.

Protected Properties

The following protected properties are available when extending VistaBox:

initH

protected initH: number = 0

Initial height of the content based on thumbnail dimensions.

initW

protected initW: number = 0

Initial width of the content based on thumbnail dimensions.

fullH

protected fullH: number = 0

Full height of the content when displayed in the lightbox.

fullW

protected fullW: number = 0

Full width of the content when displayed in the lightbox.

maxW

protected maxW: number = 0

Maximum allowed width for the content.

minW

protected minW: number = 0

Minimum allowed width for the content.

defaultWH

protected defaultWH: number = 200

Default width/height fallback value.

isZoomedIn

protected isZoomedIn: boolean = false

Whether the content is currently zoomed in.

isCancelled

protected isCancelled: boolean = false

Whether the loading operation has been cancelled.

isLoadedResolved

protected isLoadedResolved: ((val: boolean | PromiseLike<boolean>) => void) | null = null

Resolver function for the isLoaded promise.

isLoadedRejected

protected isLoadedRejected: ((reason?: any) => void) | null = null

Rejection function for the isLoaded promise.

isLoaded

protected isLoaded: Promise<boolean>

Promise that resolves when the content has finished loading.

replacement

protected replacement: HTMLImageElement | null = null

Placeholder element that replaces the original thumbnail in the DOM.

originalParent

protected originalParent: HTMLElement | null = null

Reference to the original parent element of the thumbnail.

originalNextSibling

protected originalNextSibling: ChildNode | null = null

Reference to the next sibling of the original thumbnail for proper reinsertion.

originalStyle

protected originalStyle = ''

Original CSS text of the thumbnail element.

thumbImage

protected thumbImage: HTMLImageElement | null = null

Reference to the original thumbnail image element.

originRect

protected originRect: { width: number; height: number; top: number; left: number }

Bounding rectangle of the origin element.

fittedSize

protected fittedSize: { width: number; height: number } | null = null

Calculated fitted size of the thumbnail image.

maxZoomLevel

protected maxZoomLevel: number

Maximum zoom level allowed for this content.

vistaView

protected vistaView: VistaView

Reference to the parent VistaView instance.

transitionState

protected transitionState: VistaHiresTransitionOpt | null = null

State object for high-resolution transitions.

transitionShouldWait

protected transitionShouldWait: () => boolean = () => false

Function that determines if transition should wait before starting.

initPointerCenter

protected initPointerCenter = { x: 0, y: 0 }

Initial center point for pointer interactions.

onScale

protected onScale: (par: {
  vistaImage: VistaBox;
  scale: number;
  isMax: boolean;
  isMin: boolean;
}) => void

Callback function invoked when content is scaled.

Protected Methods

The following protected methods are available when extending VistaBox:

createState()

protected createState(): VistaImageState

Creates and returns a new state object with getters/setters that trigger DOM updates. Called in the constructor.

onLessThanMinWidthChange()

protected onLessThanMinWidthChange(value: boolean): void

Called when content width falls below minimum. Sets opacity to 0.5 when true.

onTranslateChange()

protected onTranslateChange(value: { x: number; y: number }): void

Updates the CSS translate property when state.translate changes.

onTransformChange()

protected onTransformChange(value: { x: number; y: number; scale: number }): void

Updates the CSS transform property when state.transform changes.

onWidthChange()

protected onWidthChange(value: number): void

Updates the CSS width property when state.width changes.

onHeightChange()

protected onHeightChange(value: number): void

Updates the CSS height property when state.height changes.

getFullSizeDim()

protected getFullSizeDim(): { width: number; height: number }

Calculates the full size dimensions based on thumbnail aspect ratio and viewport size.

Returns: Object containing calculated width and height.

normalize()

protected normalize(): void

Resets content to its default state with no zoom or translation. Sets transform and translate to zero, and dimensions to full size.

getFromParsedSrcSet()

protected getFromParsedSrcSet(targetWidth: number): string | null

Selects the most appropriate source from the parsed srcSet based on target width and device pixel ratio.

Parameters:

• targetWidth - The desired width in pixels

Returns: The selected source URL, or null if no srcSet is available.

setFinalTransform()

setFinalTransform(par?: { propagateEvent?: boolean }): { close: boolean; cancel: () => void }

Finalizes the current transform state by converting temporary transforms into permanent translate and size values. Called at the end of pan/zoom operations.

Parameters:

• par.propagateEvent - Whether to trigger onContentChange events (default: true)

Returns: Object with close flag and cancel function.

Related

• VistaImage - Image implementation extending VistaBox
• Extensions - Creating custom content types
• VistaImageParams - Constructor parameters