Daylight | References | ArcGIS Maps SDK for JavaScript

import Daylight from "@arcgis/core/widgets/Daylight.js";

Inheritance:: Daylight→Widget<DaylightProperties>→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.14

The Daylight widget can be used to manipulate the lighting conditions of a SceneView. For this, the widget modifies the lighting property of SceneView.environment. To illuminate the scene, one can either use a configuration of date and time to position the sun or switch to the virtual mode, where the light source is relative to the camera.

When lighting the scene with the sun and adjusting the time and date, the position of the sun and the stars get updated accordingly, changing the light and the shadows in the scene. This sets the date and directShadowsEnabled properties of SceneView.environment.lighting.

The daytime slider has an option to select the timezone. When the user makes any adjustments here, a new time in the chosen timezone is calculated and displayed in the slider. The timezone selector can be disabled by setting timezone to false in the visibleElements property.

By default a calendar is displayed where the user can select the day, month and year. With the dateOrSeason property, the calendar can be replaced with a dropdown menu where a season can be selected instead:

const daylight = new Daylight({
  view: view,
  dateOrSeason: "season"
});

daylight-seasons

There are two play buttons, one corresponds to the daytime slider and it animates the time as it cycles through the minutes of the day. The second button corresponds to the date picker and it animates the time as it cycles through the months of the year. The speed of the animation can be set using the playSpeedMultiplier property.

const daylight = new Daylight({
  view: view,
  playSpeedMultiplier: 2
});

daylight-animation

Except for the daytime slider, all the elements in the daylight widget can be hidden by using the visibleElements property:

const daylight = new Daylight({
  view: view,
  visibleElements: {
    timezone: false,
    datePicker: false,
    playButtons: false,
    sunLightingToggle: false,
    shadowsToggle: false
  }
});

With these settings, the widget looks like this:

daylight-no-elements

Whenever the sun position option is unchecked, the scene applies the virtual light source relative to the camera. With this, the widget's time slider and date picker get automatically disabled:

daylight-virtual

Known limitations:

The Daylight widget uses UTC time and does not account for the daylight savings times in different countries and regions of the world.

When the SceneView.environment.lighting is of the type virtual, setting the time and date does not have an influence on the lighting conditions of the scene.

See also

Example

// basic usage of the daylight widget using the default settings
const daylight = new Daylight({
  view: view
});
view.ui.add(daylight, "top-right");

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`DaylightProperties`

See the properties table for a list of all the properties that may be passed into the constructor.

Example

// Typical usage
const daylightWidget = new Daylight({
  view: view
});

view.ui.add(daylightWidget, "top-right");

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`container` inherited	`HTMLElement \| null \| undefined`	Widget
`dateOrSeason`	`DateOrSeason`
`declaredClass` readonly inherited	`string`	Accessor
`destroyed` readonly inherited	`boolean`	Widget
`headingLevel`	`HeadingLevel`
`icon`	`Icon["icon"]`
`id` inherited	`string`	Widget
`label`	`string`
`playSpeedMultiplier`	`number`
`timeSliderSteps`	`number \| number[]`
`view`	`SceneView \| null \| undefined`
`viewModel`	`DaylightViewModel`
`visible` inherited	`boolean`	Widget
`visibleElements`	`VisibleElements`

container

autocast inherited Property

Type: HTMLElement | null | undefined

Inherited from: Widget

The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.

Examples

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

dateOrSeason

Property

Type: DateOrSeason

Controls whether the widget displays a date or a season picker. When the date picker is set, the user selects the date from a calendar. The season picker allows the user to choose a season from a drop-down list. Each season uses a fixed date corresponding to the equinoxes and solstices of 2014.

Default value: "date"

Example

// set the season picker
daylightWidget.dateOrSeason = "season";

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

destroyed

readonlyinherited Property

Type: boolean

Inherited from: Widget

When true, this property indicates whether the widget has been destroyed.

headingLevel

Property

Type: HeadingLevel

Since: ArcGIS Maps SDK for JavaScript 4.20

Indicates the heading level to use for the widget title. By default, the title is rendered as a level 3 heading (e.g. <h3>Daylight</h3>). Depending on the widget's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also

Heading Elements

Default value: 3

Example

daylight.headingLevel = 2;

icon

autocast Property

Type: Icon["icon"]

Since: ArcGIS Maps SDK for JavaScript 4.27

Icon which represents the widget. It is typically used when the widget is controlled by another one (e.g. in the Expand widget).

See also

Default value: "brightness"

id

inherited Property

Type: string

Inherited from: Widget

The unique ID assigned to the widget when the widget is created. If not set by the developer, it will default to the container ID, or if that is not present then it will be automatically generated.

label

autocast Property

Type: string

The widget's default label. This label displays when it is used within another widget, such as the Expand or LayerList widgets.

playSpeedMultiplier

Property

Type: number

Controls the speed of the daytime animation.

Default value: 1.0

Example

// Plays the daylight animation at half of the default speed
daylightWidget.playSpeedMultiplier = 0.5;

timeSliderSteps

Property

Type: number | number[]

Since: ArcGIS Maps SDK for JavaScript 4.16

Sets steps, or intervals, on the time slider to restrict the times of the day that can be selected when dragging the thumb. All values are in minutes, where 0 is midnight and 23 * 60 + 59 is just before midnight the following day.

If an array of numbers is passed to this property, the slider thumbs may only be moved to the times specified in the array.

If a single number is set, then steps are set for the entire day at an interval of timeSliderSteps minutes. For example, if a value of 60 is set here, dragging the slider will allow selecting each of 24 hours of the day.

Default value: 5

Examples

// set steps at an interval of 60. So the
// slider thumb snaps at each hour of the day.
daylightWidget.timeSliderSteps = 60;

// Set steps at specific times.
daylightWidget.timeSliderSteps = [60, 100, 120, 160];

view

Property

Type: SceneView | null | undefined

A reference to the SceneView. Set this to link the widget to a specific view.

viewModel

autocast Property

Type: DaylightViewModel

The view model for the Daylight widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the DaylightViewModel class.

visible

inherited Property

Type: boolean

Inherited from: Widget

Indicates whether the widget is visible.

If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is the first of three widgets associated to the upper right hand corner of the DefaultUI, then the other widgets will reposition when this widget is made invisible. For more information, refer to the css display value of "none".

Default value: true

Example

// Hides the widget in the view
widget.visible = false;

visibleElements

autocast Property

Type: VisibleElements

This property provides the ability to display or hide the individual elements of the widget. Play buttons, sun lighting toggle, shadow toggle button, date picker, and timezone selector can be displayed or hidden by setting their corresponding properties to true or false. By default, all the elements are displayed.

Example

// display all elements, except the shadow toggle button
daylightWidget.visibleElements.shadowsToggle = false;

// disable all elements
daylightWidget.visibleElements = {
  header: false,
  playButtons: false,
  datePicker: false,
  timezone: false,
  sunLightingToggle: false,
  shadowsToggle: false
};

Methods

Method	Signature	Class
`classes` inherited	`classes(...classNames: ((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]): string`	Widget
`destroy` inherited	`destroy(): void`	Widget
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`isFulfilled` inherited	`isFulfilled(): boolean`	EsriPromiseMixin
`isRejected` inherited	`isRejected(): boolean`	EsriPromiseMixin
`isResolved` inherited	`isResolved(): boolean`	EsriPromiseMixin
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin
`postInitialize` inherited	`postInitialize(): void`	Widget
`render` inherited	`render(): any \| null`	Widget
`renderNow` inherited	`renderNow(): void`	Widget
`scheduleRender` inherited	`scheduleRender(): void`	Widget
`when` inherited	`when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> \| null \| undefined, onRejected?: OnRejectedCallback<TResult2> \| null \| undefined): Promise<TResult1 \| TResult2>`	EsriPromiseMixin

classes

inherited Method

Signature: classes (...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string

Inherited from: Widget

A utility method used for building the value for a widget's class property. This aids in simplifying css class setup.

Parameters

Parameter	Type	Description	Required
classNames	`((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]`	The class names.

Returns: string
The computed class name.

Example

// .tsx syntax showing how to set css classes while rendering the widget

render() {
  const dynamicClasses = {
    [css.flip]: this.flip,
    [css.primary]: this.primary
  };

  return (
    <div class={classes(css.root, css.mixin, dynamicClasses)} />
  );
}

destroy

inherited Method

Signature: destroy (): void

Inherited from: Widget

Destroys the widget instance.

Returns: void

emit

inherited Method

Signature: emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

hasEventListener

inherited Method

Signature: hasEventListener <Type extends EventNames<this>>(type: Type): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

isFulfilled

inherited Method

Signature: isFulfilled (): boolean

Inherited from: EsriPromiseMixin

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).

isRejected

inherited Method

Signature: isRejected (): boolean

Inherited from: EsriPromiseMixin

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been rejected.

isResolved

inherited Method

Signature: isResolved (): boolean

Inherited from: EsriPromiseMixin

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been resolved.

on

inherited Method

Signature: on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

Parameter	Type	Description	Required
type	`Type`	An event or an array of events to listen for.
listener	`EventedCallback<this["@eventTypes"][Type]>`	The function to call when the event fires.

Returns

ResourceHandle

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

Property	Type	Description
remove	Function	When called, removes the listener from the event.

Example

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

postInitialize

inherited Method

Signature: postInitialize (): void

Inherited from: Widget

Executes after widget is ready for rendering.

Returns: void

render

inherited Method

Signature: render (): any | null

Inherited from: Widget

This method is implemented by subclasses for rendering.

Returns: any | null
The rendered virtual node.

renderNow

inherited Method

Signature: renderNow (): void

Inherited from: Widget

Renders widget to the DOM immediately.

Returns: void

scheduleRender

inherited Method

Signature: scheduleRender (): void

Inherited from: Widget

Schedules widget rendering. This method is useful for changes affecting the UI.

Returns: void

when

inherited Method

Signature: when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>

Type parameters: <TResult1 = this, TResult2 = never>

Inherited from: EsriPromiseMixin

when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function. The onFulfilled executes when the instance of the class loads. The onRejected executes if the instance of the class fails to load.

Parameters

Parameter	Type	Description	Required
onFulfilled	`OnFulfilledCallback<this, TResult1> \| null \| undefined`	The function to call when the promise resolves.
onRejected	`OnRejectedCallback \| null \| undefined`	The function to execute when the promise fails.

Returns: Promise<TResult1 | TResult2>
Returns a new promise for the result of onFulfilled that may be used to chain additional functions.

Example

// Although this example uses MapView, any class instance that is a promise may use when() in the same way
let view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

Events

Name	Type
`user-date-time-change` inherited	CustomEvent<Record<never, never>>

user-date-time-change

inherited Event

user-date-time-change: CustomEvent<Record<never, never>>

Inherited from: DaylightViewModelEvents

Since: ArcGIS Maps SDK for JavaScript 4.33

Fires when the user changes the date or time in the widget by interacting with the slider, the date picker, the season selector or the play buttons.

Example

Constructors

Parameters

Example

Properties

Examples

Example

Example

Example

Examples

Example

Example

Methods

Parameters

Example

Parameters

Parameters

Parameters

Example

Parameters

Example

Events

Type definitions