leaflet/dist/types/layer/tile/GridLayer.d.ts

JavaScript library for mobile-friendly interactive maps

import { Layer } from '../Layer.js';
import { Point } from '../../geometry/Point.js';
import { Bounds } from '../../geometry/Bounds.js';
import { LatLngBounds } from '../../geo/LatLngBounds.js';
import type { Defaults, GridLayerDefaults, GridLayerEventMap, GridLayerOptions, LatLngBoundsExpression, LeafletEvent, MapListeners, TileErrorEvent, TileEvent, ViewPreResetEvent, WorldCopyJumpEvent, ZoomAnimEvent } from '../../types.js';
import type { LatLng } from '../../geo/LatLng.js';
import type { LeafletMap } from '../../map/Map.js';
/** @import {Defaults, GridLayerDefaults, GridLayerEventMap, GridLayerOptions, LatLngBoundsExpression, LeafletEvent,
 *    MapListeners, TileErrorEvent, TileEvent, ViewPreResetEvent, WorldCopyJumpEvent, ZoomAnimEvent}
 *    from '../../types.js' */
/** @import {LatLng} from '../../geo/LatLng.js' */
/** @import {LeafletMap} from '../../map/Map.js' */
declare const defaultOptions: {
    /**
     * Width and height of tiles in the grid. Use a number if width
     * and height are equal, or `Point(width, height)` otherwise.
     * @type {number | Point}
     */
    tileSize: number | Point;
    /** Opacity of the tiles. Can be used in the `createTile()` function. */
    opacity: number;
    /** Load new tiles only when panning ends. */
    updateWhenIdle: boolean;
    /**
     * By default, a smooth zoom animation (during a [pinch zoom](#map-pinchzoom) or a [`flyTo()`](#map-flyto))
     * will update grid layers every integer zoom level. Setting this option to `false` will
     * update the grid layer only when the smooth animation ends.
     */
    updateWhenZooming: boolean;
    /** Tiles will not update more than once every `updateInterval` milliseconds when panning. */
    updateInterval: number;
    /** The explicit zIndex of the tile layer. */
    zIndex: number;
    /**
     * If set, tiles will only be loaded inside the set `LatLngBounds`.
     * @type {LatLngBoundsExpression | null}
     */
    bounds: LatLngBoundsExpression | null;
    /** The minimum zoom level down to which this layer will be displayed (inclusive). */
    minZoom: number;
    /**
     * The maximum zoom level up to which this layer will be displayed (inclusive).
     * @type {number | undefined}
     */
    maxZoom: number | undefined;
    /**
     * Maximum zoom number the tile source has available. If it is specified, the tiles on all zoom levels
     * higher than `maxNativeZoom` will be loaded from `maxNativeZoom` level and auto-scaled.
     * @type {number | undefined}
     */
    maxNativeZoom: number | undefined;
    /**
     * Minimum zoom number the tile source has available. If it is specified, the tiles on all zoom levels
     * lower than `minNativeZoom` will be loaded from `minNativeZoom` level and auto-scaled.
     * @type {number | undefined}
     */
    minNativeZoom: number | undefined;
    /**
     * Whether the layer is wrapped around the antimeridian. If `true`, the GridLayer will only be displayed once
     * at low zoom levels. Has no effect when the [map CRS](#map-crs) doesn't wrap around. Can be used in combination
     * with [`bounds`](#gridlayer-bounds) to prevent requesting tiles outside the CRS limits.
     */
    noWrap: boolean;
    /** `Map pane` where the grid layer will be added. */
    pane: string;
    /** A custom class name to assign to the tile layer. Empty by default. */
    className: string;
    /** When panning the map, keep this many rows and columns of tiles before unloading them. */
    keepBuffer: number;
};
export type GridLayerDefaultsValues = typeof defaultOptions;
export type GridLayerEvents = {
    /**
     * Fired when the grid layer starts loading tiles.
     */
    loading: LeafletEvent;
    /**
     * Fired when a tile is removed (e.g. when a tile goes off the screen).
     */
    tileunload: TileEvent;
    /**
     * Fired when a tile is requested and starts loading.
     */
    tileloadstart: TileEvent;
    /**
     * Fired when there is an error loading a tile.
     */
    tileerror: TileErrorEvent;
    /**
     * Fired when a tile loads.
     */
    tileload: TileEvent;
    /**
     * Fired when the grid layer loaded all visible tiles.
     */
    load: LeafletEvent;
};
export type GridTile = {
    el: HTMLElement;
    coords: Coords;
    current: boolean;
    retain?: boolean;
    active?: boolean;
    loaded?: boolean;
};
export type GridLevel = {
    el: HTMLElement;
    origin: Point;
    zoom: number;
};
export type Coords = Point & {
    z: number;
};
export type DoneCallback = (error?: unknown, tile?: HTMLElement) => void;
export type TileEventProps = {
    /**
     * The tile element (image).
     */
    tile: HTMLElement;
    /**
     * Point object with the tile's `x`, `y`, and `z` (zoom level) coordinates.
     */
    coords: Coords;
};
export type TileErrorEventProps = {
    /**
     * Error passed to the tile's `done()` callback.
     */
    error: unknown;
};
/** @typedef {typeof defaultOptions} GridLayerDefaultsValues */
/**
 * @typedef {Object} GridLayerEvents
 * @property {LeafletEvent} loading Fired when the grid layer starts loading tiles.
 * @property {TileEvent} tileunload Fired when a tile is removed (e.g. when a tile goes off the screen).
 * @property {TileEvent} tileloadstart Fired when a tile is requested and starts loading.
 * @property {TileErrorEvent} tileerror Fired when there is an error loading a tile.
 * @property {TileEvent} tileload Fired when a tile loads.
 * @property {LeafletEvent} load Fired when the grid layer loaded all visible tiles.
 */
/** @typedef {{el: HTMLElement, coords: Coords, current: boolean, retain?: boolean, active?: boolean, loaded?: boolean}} GridTile */
/** @typedef {{el: HTMLElement, origin: Point, zoom: number}} GridLevel */
/**
 * A `Point` with the tile's zoom level as `z`, as `createTile` and `getTileUrl` get it.
 * @typedef {Point & {z: number}} Coords
 */
/**
 * The callback `createTile` gets: call it once the tile is ready, with an error if it failed to load.
 * @typedef {(error?: unknown, tile?: HTMLElement) => void} DoneCallback
 */
/**
 * @typedef {Object} TileEventProps
 * @property {HTMLElement} tile The tile element (image).
 * @property {Coords} coords Point object with the tile's `x`, `y`, and `z` (zoom level) coordinates.
 */
/**
 * @typedef {Object} TileErrorEventProps
 * @property {unknown} error Error passed to the tile's `done()` callback.
 */
/**
 * Generic class for handling a tiled grid of HTML elements. This is the base class for all tile layers and
 * replaces `TileLayer.Canvas`. GridLayer can be extended to create a tiled grid of HTML elements like
 * `<canvas>`, `<img>` or `<div>`. GridLayer will handle creating and animating these DOM elements for you.
 * @example <caption>Synchronous usage</caption>
 * To create a custom layer, extend GridLayer and implement the `createTile()` method, which will be passed a `Point` object with the `x`, `y`, and `z` (zoom level) coordinates to draw your tile.
 *
 * ```js
 * class CanvasLayer extends GridLayer {
 *     createTile(coords) {
 *         // create a <canvas> element for drawing
 *         const tile = DomUtil.create('canvas', 'leaflet-tile');
 *
 *         // setup tile width and height according to the options
 *         const size = this.getTileSize();
 *         tile.width = size.x;
 *         tile.height = size.y;
 *
 *         // get a canvas context and draw something on it using coords.x, coords.y and coords.z
 *         const ctx = tile.getContext('2d');
 *
 *         // return the tile so it can be rendered on screen
 *         return tile;
 *     }
 * }
 * ```
 * @example <caption>Asynchronous usage</caption>
 * Tile creation can also be asynchronous, this is useful when using a third-party drawing library. Once the tile is finished drawing it can be passed to the `done()` callback.
 *
 * ```js
 * class CanvasLayer extends GridLayer {
 *     createTile(coords, done) {
 *         const error;
 *
 *         // create a <canvas> element for drawing
 *         const tile = DomUtil.create('canvas', 'leaflet-tile');
 *
 *         // setup tile width and height according to the options
 *         const size = this.getTileSize();
 *         tile.width = size.x;
 *         tile.height = size.y;
 *
 *         // draw something asynchronously and pass the tile to the done() callback
 *         setTimeout(function() {
 *             done(error, tile);
 *         }, 1000);
 *
 *         return tile;
 *     }
 * }
 * ```
 * @categoryDescription Extension methods
 * Layers extending `GridLayer` shall reimplement the following method.
 * @template {GridLayerOptions} [O=GridLayerOptions]
 * @template {GridLayerEventMap} [E=GridLayerEventMap]
 * @extends {Layer<O & GridLayerDefaults, E>}
 */
export declare class GridLayer<O extends GridLayerOptions = GridLayerOptions, E extends GridLayerEventMap = GridLayerEventMap> extends Layer<O & GridLayerDefaults, E> {
    /** @type {{[zoom: string]: GridLevel}} */
    _levels: {
        [zoom: string]: GridLevel;
    };
    /** @type {{[key: string]: GridTile}} */
    _tiles: {
        [key: string]: GridTile;
    };
    _container: HTMLElement;
    _tileZoom: number | undefined;
    /** @type {number} */
    _fadePruneFrame: number;
    _onMove: (() => void) | undefined;
    /** @type {GridLevel} */
    _level: GridLevel;
    /** @type {boolean} */
    _noPrune: boolean;
    _tileSize: Point | undefined;
    /** @type {Bounds} */
    _globalTileRange: Bounds;
    _wrapX: false | number[] | undefined;
    _wrapY: false | number[] | undefined;
    /** @type {boolean} */
    _loading: boolean;
    /** @type {number | undefined} */
    _pruneTimeout: number | undefined;
    static initHooks: boolean;
    /** @type {Defaults<GridLayerOptions>} */
    static defaultOptions: Defaults<GridLayerOptions>;
    /**
     * Creates a new instance of GridLayer with the supplied options.
     * @param {NoInfer<Partial<O>>} [options]
     */
    constructor(options?: NoInfer<Partial<O>>);
    /** @param {LeafletMap} map */
    onAdd(map: LeafletMap): void;
    /** @param {LeafletMap} map */
    beforeAdd(map: LeafletMap): void;
    /** @param {LeafletMap} map */
    onRemove(map: LeafletMap): void;
    /** Brings the tile layer to the top of all tile layers. */
    bringToFront(): this;
    /** Brings the tile layer to the bottom of all tile layers. */
    bringToBack(): this;
    /**
     * Returns the HTML element that contains the tiles for this layer, or `null` once the layer is removed.
     * @returns {HTMLElement | null}
     */
    getContainer(): HTMLElement | null;
    /**
     * Changes the [opacity](#gridlayer-opacity) of the grid layer.
     * @param {number} opacity
     */
    setOpacity(opacity: number): this;
    /**
     * Changes the [zIndex](#gridlayer-zindex) of the grid layer.
     * @param {number} zIndex
     */
    setZIndex(zIndex: number): this;
    /** Returns `true` if any tile in the grid layer has not finished loading. */
    isLoading(): boolean;
    /** Causes the layer to clear all the tiles and request them again. */
    redraw(): this;
    getEvents(): MapListeners;
    /**
     * Called only internally, must be overridden by classes extending `GridLayer`. Returns
     * the `HTMLElement` corresponding to the given `coords`. If the `done` callback is specified,
     * it must be called when the tile has finished loading and drawing.
     * @category Extension methods
     * @overload
     * @param {Coords} coords
     * @param {DoneCallback} done
     * @returns {HTMLElement}
     */
    createTile(coords: Coords, done: DoneCallback): HTMLElement;
    /** Normalizes the [tileSize option](#gridlayer-tilesize) into a point. Used by the `createTile()` method. */
    getTileSize(): Point;
    _updateZIndex(): void;
    /** @param {(a: number, b: number) => number} compare */
    _setAutoZIndex(compare: (a: number, b: number) => number): void;
    _updateOpacity(): void;
    /** @param {GridTile} tile */
    _onOpaqueTile(tile: GridTile): void;
    _initContainer(): void;
    _updateLevels(): GridLevel | undefined;
    /** @param {number} z */
    _onUpdateLevel(z: number): void;
    /** @param {number} z */
    _onRemoveLevel(z: number): void;
    /** @param {GridLevel} level */
    _onCreateLevel(level: GridLevel): void;
    _pruneTiles(): void;
    /** @param {number} zoom */
    _removeTilesAtZoom(zoom: number): void;
    _removeAllTiles(): void;
    /** @param {ViewPreResetEvent} [e] */
    _invalidateAll(e?: ViewPreResetEvent): void;
    /**
     * @param {number} x
     * @param {number} y
     * @param {number} z
     * @param {number} minZoom
     */
    _retainParent(x: number, y: number, z: number, minZoom: number): boolean;
    /**
     * @param {number} x
     * @param {number} y
     * @param {number} z
     * @param {number} maxZoom
     */
    _retainChildren(x: number, y: number, z: number, maxZoom: number): void;
    /**
     * @param {number} x
     * @param {number} y
     * @param {number} z
     */
    _retain(x: number, y: number, z: number): boolean | undefined;
    /** @param {LeafletEvent & {pinch?: boolean, flyTo?: boolean}} [e] */
    _resetView(e?: LeafletEvent & {
        pinch?: boolean;
        flyTo?: boolean;
    }): void;
    /** @param {ZoomAnimEvent} e */
    _animateZoom(e: ZoomAnimEvent): void;
    /** @param {number} zoom */
    _clampZoom(zoom: number): number;
    /**
     * @param {LatLng} center
     * @param {number} zoom
     * @param {boolean} [noPrune]
     * @param {boolean} [noUpdate]
     */
    _setView(center: LatLng, zoom: number, noPrune?: boolean, noUpdate?: boolean): void;
    /**
     * @param {LatLng} center
     * @param {number} zoom
     */
    _setZoomTransforms(center: LatLng, zoom: number): void;
    /**
     * @param {GridLevel} level
     * @param {LatLng} center
     * @param {number} zoom
     */
    _setZoomTransform(level: GridLevel, center: LatLng, zoom: number): void;
    _resetGrid(): void;
    _onMoveEnd(): void;
    /** @param {WorldCopyJumpEvent} e */
    _onWorldCopyJump({ worlds }: WorldCopyJumpEvent): void;
    /** @param {LatLng} center */
    _getTiledPixelBounds(center: LatLng): Bounds;
    /** @param {LatLng} [center] */
    _update(center?: LatLng): void;
    /** @param {Coords} coords */
    _isValidTile(coords: Coords): boolean;
    /**
     * @param {Coords} coords
     * @returns {[LatLng, LatLng]}
     */
    _tileCoordsToNwSe(coords: Coords): [LatLng, LatLng];
    /** @param {Coords} coords */
    _tileCoordsToBounds(coords: Coords): LatLngBounds;
    /** @param {{x: number, y: number, z: number}} coords */
    _tileCoordsToKey(coords: {
        x: number;
        y: number;
        z: number;
    }): string;
    /** @param {string} key */
    _removeTile(key: string): void;
    /** @param {HTMLElement} tile */
    _initTile(tile: HTMLElement): void;
    /**
     * @param {Coords} coords
     * @param {DocumentFragment} container
     */
    _addTile(coords: Coords, container: DocumentFragment): void;
    /**
     * @param {Coords} coords
     * @param {unknown} [err]
     * @param {HTMLElement} [el]
     */
    _tileReady(coords: Coords, err?: unknown, el?: HTMLElement): void;
    /** @param {GridTile} tile */
    _onTileFaded(tile: GridTile): void;
    /** @param {Point} coords */
    _getTilePos(coords: Point): Point;
    /** @param {Coords} coords */
    _wrapCoords(coords: Coords): Coords;
    /** @param {Bounds} bounds */
    _pxBoundsToTileRange(bounds: Bounds): Bounds;
    _noTilesToLoad(): boolean;
}
export {};