@arcgis/core/webscene/Slide.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type Basemap from "../Basemap.js";
import type Viewpoint from "../Viewpoint.js";
import type Collection from "../core/Collection.js";
import type TimeExtent from "../time/TimeExtent.js";
import type SceneView from "../views/SceneView.js";
import type SlideThumbnail from "../webdoc/support/SlideThumbnail.js";
import type Description from "./support/Description.js";
import type SlideElements from "./support/SlideElements.js";
import type SlideEnvironment from "./support/SlideEnvironment.js";
import type SlideGround from "./support/SlideGround.js";
import type SlideVisibleLayer from "./support/SlideVisibleLayer.js";
import type Title from "./support/Title.js";
import type { BasemapProperties } from "../Basemap.js";
import type { ClonableMixin } from "../core/Clonable.js";
import type { EventedMixin } from "../core/Evented.js";
import type { JSONSupport } from "../core/JSONSupport.js";
import type { GoToOptions3D, UserSettings as ScreenshotUserSettings } from "../views/types.js";
import type { SlideThumbnailProperties } from "../webdoc/support/SlideThumbnail.js";
import type { DescriptionProperties } from "./support/Description.js";
import type { SlideVisibleLayerProperties } from "./support/SlideVisibleLayer.js";
import type { TitleProperties } from "./support/Title.js";
import type { ViewpointProperties } from "../Viewpoint.js";
import type { SlideGroundProperties } from "./support/SlideGround.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { SlideEnvironmentProperties } from "./support/SlideEnvironment.js";
import type { TimeExtentProperties } from "../time/TimeExtent.js";
import type { SlideElementsProperties } from "./support/SlideElements.js";

export interface SlideProperties extends Partial<Pick<Slide, "hidden" | "id" | "layout">> {
  /**
   * The basemap of the scene. Only the [base](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#baseLayers)
   * and [reference](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#referenceLayers) layers of the basemap
   * are stored in a slide.
   *
   * This value can be an instance of [Basemap](https://developers.arcgis.com/javascript/latest/references/core/Basemap/) or a value listed in these [basemap id tables](https://developers.arcgis.com/javascript/latest/references/core/Map/#basemap-id).
   */
  basemap?: BasemapProperties | string | null;
  /** The description of the slide. */
  description?: DescriptionProperties | DescriptionProperties | string;
  /**
   * The elements object contains configurations for components set in a slide.
   *
   * @since 4.32
   */
  elements?: SlideElementsProperties;
  /**
   * The enabled focus areas of the scene.
   *
   * This is a collection of strings, storing references (by ID) to the [focus areas](https://developers.arcgis.com/javascript/latest/references/core/Map/#focusAreas)
   * that are enabled when the slide is applied to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   *
   * @example
   * // Update the slide to only enable the first focus area in the map.
   * slide.enabledFocusAreas = [ view.map.focusAreas.areas.at(0).id ];
   */
  enabledFocusAreas?: ReadonlyArrayOrCollection<string> | null;
  /** Represents settings that affect the environment in which the WebScene is displayed (such as lighting). */
  environment?: SlideEnvironmentProperties;
  /** Ground properties for this slide. */
  ground?: SlideGroundProperties | null;
  /** A data URI encoded thumbnail. */
  thumbnail?: SlideThumbnailProperties | SlideThumbnailProperties | string;
  /**
   * The time extent of the scene.
   *
   * @since 4.30
   */
  timeExtent?: TimeExtentProperties | null;
  /** The title of the slide. */
  title?: TitleProperties | TitleProperties | string;
  /**
   * The viewpoint of the slide. This acts like a bookmark, saving a predefined
   * location or point of view from which to view the scene.
   */
  viewpoint?: ViewpointProperties;
  /**
   * The visible layers of the scene.
   *
   * This is a collection of objects that stores references (by ID) to the
   * [scene layers](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#layers) and [ground layers](https://developers.arcgis.com/javascript/latest/references/core/Ground/#layers) that are set
   * as `visible` when a slide is applied to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   *
   * When assigning visible layers, the following types of values will be automatically casted:
   *
   * - Array (or [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/)) of [Layer instances](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/): `[layerInstance, layerInstance]`
   * - Array (or [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/)) of [Layer IDs](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#id): `["layer-1", "layer-2"]`
   *
   * The specification for each object in the collection is outlined in the table below.
   *
   * @example
   * // Update the visible layers to the second layer in the scene, and the
   * // first elevation layer in the ground.
   * slide.visibleLayers = [
   *   { id: scene.layers.at(1).id }
   *   { id: scene.ground.layers.at(0).id }
   * ];
   *
   * // Equivalent using convenience autocasting
   * slide.visibleLayers = [scene.layers.at(0), scene.ground.layers.at(0)];
   */
  visibleLayers?: ReadonlyArrayOrCollection<SlideVisibleLayerProperties>;
}

export type SlideLayout = "caption" | "cover" | "none";

export interface SlideEvents {
  /**
   * Emitted just before starting to apply the slide to the view.
   *
   * @see [applyTo()](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#applyTo)
   * @since 5.0
   */
  "apply-slide-start": void;
  /**
   * Emitted just after applying the slide has successfully completed. If applying the slide is interrupted then the
   * [apply-slide-cancel](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#event-apply-slide-cancel) event is emitted instead.
   *
   * @see [applyTo()](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#applyTo)
   * @since 5.0
   */
  "apply-slide-complete": void;
  /**
   * Emitted just after applying the slide was interrupted. In this case the
   * [apply-slide-complete](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#event-apply-slide-complete) event is not emitted.
   *
   * @see [applyTo()](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#applyTo)
   * @since 5.0
   */
  "apply-slide-cancel": void;
}

/**
 * A slide stores a snapshot of several pre-set properties of the
 * [WebScene](https://developers.arcgis.com/javascript/latest/references/core/WebScene/) and [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/), such as
 * the [basemap](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#basemap), [viewpoint](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#viewpoint) and [visible layers](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#visibleLayers).
 * The [visible layers](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#visibleLayers) may contain references
 * (by [Layer.id](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#id)) to both operational layers from the
 * [scene](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#layers) as well as elevation layers
 * from the [Ground.layers](https://developers.arcgis.com/javascript/latest/references/core/Ground/#layers), which affect the surface
 * elevation.
 *
 * Slides contain additional metadata such as a [title](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#title),
 * [description](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#description) and [thumbnail](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#thumbnail) which may be used
 * to present the slide to the user in a user interface. Slides can be
 * [created](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#createFrom), [updated](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#updateFrom)
 * and [applied](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#applyTo) to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Additionally,
 * slides can be stored as part of the
 * [WebScene.presentation](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/).
 *
 * @since 4.0
 * @see [Presentation](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/)
 * @see [Sample - WebScene slides](https://developers.arcgis.com/javascript/latest/sample-code/webscene-slides/)
 * @example
 * // Create a slide from a view and apply it at a later time
 * Slide.createFrom(view).then(function(slide) {
 *   // Add slide to the scene presentation
 *   scene.presentation.slides.add(slide);
 * });
 *
 * // At a later time
 * let firstSlide = scene.presentation.slides.at(0);
 *
 * firstSlide.applyTo(view).then(function() {
 *   // Slide has been successfully applied to the view
 * });
 */
export default class Slide extends SlideSuperclass {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": SlideEvents;
  /**
   * Creates a slide from a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/), which may be added to the
   * [Presentation.slides](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/#slides) in the WebScene's
   * [WebScene.presentation](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#presentation). Updating the slide
   * is asynchronous and a snapshot of the view is only complete once the
   * returned promise has resolved.
   *
   *
   * Default screenshot settings are { quality: 80, width: 120, height: 75, format: "png" }
   *
   * @param view - The SceneView from which the slide should be created.
   * @param options - Creation options. See properties below for object specifications.
   * @returns When resolved, returns the created slide.
   * @example
   * // Creates a slide from the view and
   * // adds it to the webscene
   * Slide.createFrom(view).then(function(slide){
   *   webscene.presentation.slides.add(slide);
   * });
   * @example
   * // Create multiple slides from multiple viewpoints.
   * view.goTo({ heading: 0 }, { animate: false })
   *   .then(function() {
   *     // Create first slide at heading 0 (looking north)
   *     return Slide.createFrom(view);
   *   })
   *   .then(function(slide){
   *     // Slide has been captured, add to presentation
   *     webscene.presentation.slides.add(slide);
   *
   *     // Change viewpoint to look east
   *     return view.goTo({ heading: 90 }, { animate: false });
   *   })
   *   .then(function() {
   *     // Capture second slide
   *     return Slide.createFrom(view);
   *   })
   *   .then(function(slide) {
   *     // Add second slide to presentation
   *     webscene.presentation.slides.add(slide);
   *   });
   */
  static createFrom(view: SceneView, options?: SlideCreateFromOptions): Promise<Slide>;
  /**
   * Create a new slide instance. Usually [createFrom()](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/#createFrom) is
   * used instead to create a new slide which stores a snapshot of the view.
   */
  constructor(properties?: SlideProperties);
  /**
   * The basemap of the scene. Only the [base](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#baseLayers)
   * and [reference](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#referenceLayers) layers of the basemap
   * are stored in a slide.
   *
   * This value can be an instance of [Basemap](https://developers.arcgis.com/javascript/latest/references/core/Basemap/) or a value listed in these [basemap id tables](https://developers.arcgis.com/javascript/latest/references/core/Map/#basemap-id).
   */
  get basemap(): Basemap | null | undefined;
  set basemap(value: BasemapProperties | string | null | undefined);
  /** The description of the slide. */
  get description(): Description;
  set description(value: DescriptionProperties | DescriptionProperties | string);
  /**
   * The elements object contains configurations for components set in a slide.
   *
   * @since 4.32
   */
  get elements(): SlideElements;
  set elements(value: SlideElementsProperties);
  /**
   * The enabled focus areas of the scene.
   *
   * This is a collection of strings, storing references (by ID) to the [focus areas](https://developers.arcgis.com/javascript/latest/references/core/Map/#focusAreas)
   * that are enabled when the slide is applied to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   *
   * @example
   * // Update the slide to only enable the first focus area in the map.
   * slide.enabledFocusAreas = [ view.map.focusAreas.areas.at(0).id ];
   */
  get enabledFocusAreas(): Collection<string> | null | undefined;
  set enabledFocusAreas(value: ReadonlyArrayOrCollection<string> | null | undefined);
  /** Represents settings that affect the environment in which the WebScene is displayed (such as lighting). */
  get environment(): SlideEnvironment;
  set environment(value: SlideEnvironmentProperties);
  /** Ground properties for this slide. */
  get ground(): SlideGround | null | undefined;
  set ground(value: SlideGroundProperties | null | undefined);
  /**
   * The visibility of a slide in a presentation. A hidden slide should not show up when an application goes
   * into presentation mode.
   *
   * @default false
   * @since 4.28
   */
  accessor hidden: boolean;
  /**
   * The unique id of a slide within the
   * [slides property](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/#slides) of a
   * [Presentation](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/).
   */
  accessor id: string;
  /**
   * Layout of the slide.
   *
   * @default "caption"
   * @since 4.31
   */
  accessor layout: SlideLayout;
  /** A data URI encoded thumbnail. */
  get thumbnail(): SlideThumbnail;
  set thumbnail(value: SlideThumbnailProperties | SlideThumbnailProperties | string);
  /**
   * The time extent of the scene.
   *
   * @since 4.30
   */
  get timeExtent(): TimeExtent | null | undefined;
  set timeExtent(value: TimeExtentProperties | null | undefined);
  /** The title of the slide. */
  get title(): Title;
  set title(value: TitleProperties | TitleProperties | string);
  /**
   * The viewpoint of the slide. This acts like a bookmark, saving a predefined
   * location or point of view from which to view the scene.
   */
  get viewpoint(): Viewpoint;
  set viewpoint(value: ViewpointProperties);
  /**
   * The visible layers of the scene.
   *
   * This is a collection of objects that stores references (by ID) to the
   * [scene layers](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#layers) and [ground layers](https://developers.arcgis.com/javascript/latest/references/core/Ground/#layers) that are set
   * as `visible` when a slide is applied to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   *
   * When assigning visible layers, the following types of values will be automatically casted:
   *
   * - Array (or [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/)) of [Layer instances](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/): `[layerInstance, layerInstance]`
   * - Array (or [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/)) of [Layer IDs](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#id): `["layer-1", "layer-2"]`
   *
   * The specification for each object in the collection is outlined in the table below.
   *
   * @example
   * // Update the visible layers to the second layer in the scene, and the
   * // first elevation layer in the ground.
   * slide.visibleLayers = [
   *   { id: scene.layers.at(1).id }
   *   { id: scene.ground.layers.at(0).id }
   * ];
   *
   * // Equivalent using convenience autocasting
   * slide.visibleLayers = [scene.layers.at(0), scene.ground.layers.at(0)];
   */
  get visibleLayers(): Collection<SlideVisibleLayer>;
  set visibleLayers(value: ReadonlyArrayOrCollection<SlideVisibleLayerProperties>);
  /**
   * Applies a slide's settings to a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   *
   * @param view - The SceneView the slide should be applied to.
   * @param options - Animation options. See properties below for object specifications.
   * @returns When resolved, returns the updated slide.
   * @example
   * // Applies the slide's settings to the view, but does
   * // not use animation when updating the viewpoint
   * slide.applyTo(view, {
   *   animate: false
   * });
   * @example
   * // Applies the slide's settings to the view, animates with a maximum
   * // duration of 2 seconds.
   * slide.applyTo(view, {
   *   maxDuration: 2000
   * });
   * @example
   * slide.applyTo(view, {
   *   maxDuration: 2000
   * }).then(function(){
   *  //do something after applying the slide's settings to the view
   * });
   */
  applyTo(view: SceneView, options?: GoToOptions3D): Promise<Slide>;
  /**
   * Creates a deep clone of this object. Note that the basemap instance is cloned, but the
   * layers within the basemap are copied.
   *
   * @returns A new [Slide](https://developers.arcgis.com/javascript/latest/references/core/webscene/Slide/) instance.
   */
  clone(): this;
  /**
   * Updates a slide from a [WebScene's slides](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/#slides).
   * Updating the slide is asynchronous and a snapshot of the view is only complete once the
   * returned promise has resolved.
   *
   *
   * Default screenshot settings are { quality: 80, width: 120, height: 75, format: "png" }
   *
   * @param view - The SceneView from which the slide should update.
   * @param options - Update options. See properties below for object specifications.
   * @returns When resolved, returns the updated slide.
   */
  updateFrom(view: SceneView, options?: SlideUpdateFromOptions): Promise<Slide>;
}
declare const SlideSuperclass: typeof JSONSupport & typeof EventedMixin & typeof ClonableMixin

export interface SlideUpdateFromOptions {
  /** Screenshot options to use. See properties below for object specifications. */
  screenshot: Partial<ScreenshotUserSettings>;
}

export interface SlideCreateFromOptions {
  /** Screenshot options to use. See properties below for object specifications. */
  screenshot: Partial<ScreenshotUserSettings>;
}