GridControlsViewModel | API Reference | ArcGIS Maps SDK for JavaScript

Provides the logic for the GridControls.

GridControls is integrated into the Editor and Sketch widgets via the SnappingControls widget. Display of the GridControls widget in those contexts can be controlled through each widget's respective visibleElements property.

See also

GridControls - Deprecated since 4.33. Use the Grid Controls component instead.
SnappingOptions
SnappingControls
Programming patterns: Widget viewModel pattern

Constructors

GridControlsViewModel Constructor new GridControlsViewModel(properties)

Parameter

properties Object

optional

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

Property Overview

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

Show inherited properties

Hide inherited properties

Type	Summary	Class
String	The name of the class.	Accessor
Boolean	Returns `true` if the grid is enabled for display.	GridControlsViewModel
Boolean	Returns `true` if the grid is set to scale dynamically.	GridControlsViewModel
Number\|null\|undefined	Returns the effective spacing of grid lines after applying the dynamicScaling setting at the current view scale.	GridControlsViewModel
Color\|null\|undefined	Sets the color used for grid display.	GridControlsViewModel
Boolean	Returns `true` if the grid is in a valid state for manually setting grid properties or starting an interactive placement.	GridControlsViewModel
Boolean	True if the grid is currently not displayed (and therefore also not a valid snap target), because dynamicScaling is off and the grid cells are too small to render at the current scale.	GridControlsViewModel
String\|null\|undefined	Sets the interactive placement state, either starting or ending a draw operation that implicitly adjusts the grid.	GridControlsViewModel
Number	Controls the number of grid lines shown at 50% opacity between opaque grid lines when using dynamicScaling.	GridControlsViewModel
Boolean	True if the spacing input should be shown for the current view.	GridControlsViewModel
Boolean	If true, interactive placement tools should be disabled.	GridControlsViewModel
Boolean	Determines the behavior of the grid when the map's viewpoint is rotated.	GridControlsViewModel
Number	The grid's rotation in radians.	GridControlsViewModel
Boolean	Controls snapping behavior if snappingOptions has been defined.	GridControlsViewModel
SnappingOptions\|null\|undefined	This is the snapping options object that will be configured by the 'enable snapping' property.	GridControlsViewModel
Number	Length of a grid cell.	GridControlsViewModel
LengthUnit\|null\|undefined	Unit of measure (foot, meter, etc) used when defining the spacing grid cell.	GridControlsViewModel
MapView\|null\|undefined	The view from which the widget will operate.	GridControlsViewModel

Property Details

declaredClass Inherited Property declaredClass Stringreadonly Inherited from Accessor

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

displayEnabled Property displayEnabled Booleanreadonly

Returns true if the grid is enabled for display. Use trySetDisplayEnabled to enable or disable grid display.

dynamicScaling Property dynamicScaling Boolean

Returns true if the grid is set to scale dynamically. When dynamic scaling is enabled, grid cells are added or removed to ensure that grid cells are a reasonable size on screen as the user zooms. The way additional grid lines are shown is controlled by the majorLineInterval property.

effectiveSpacingAfterDynamicScaling Property effectiveSpacingAfterDynamicScaling Number |null |undefinedreadonly

Returns the effective spacing of grid lines after applying the dynamicScaling setting at the current view scale.

gridColor Property gridColor Color |null |undefinedautocast

Sets the color used for grid display. When major/minor lines are shown majorLineInterval is between 2 and 15. The minor line will be shown at the provided color with 50% opacity.

gridControlsEnabled Property gridControlsEnabled Booleanreadonly

Returns true if the grid is in a valid state for manually setting grid properties or starting an interactive placement.

gridOutOfScale Property gridOutOfScale Booleanreadonly

True if the grid is currently not displayed (and therefore also not a valid snap target), because dynamicScaling is off and the grid cells are too small to render at the current scale.

interactivePlacementState Property interactivePlacementState String |null |undefined

Sets the interactive placement state, either starting or ending a draw operation that implicitly adjusts the grid. Interactive placement allows the user to define the center of the grid, then the scale and rotation of the grid by drawing a second point. Setting this to "place" allows the user to move the grid center only. Setting this to "rotate" keeps the scale and center of the grid constant while rotating the grid by defining a second point.

Possible Values:"interactive" |"place" |"rotate"

majorLineInterval Property majorLineInterval Number

Controls the number of grid lines shown at 50% opacity between opaque grid lines when using dynamicScaling.

Default Value:10

numericSpacingInputShouldBeVisible Property numericSpacingInputShouldBeVisible Booleanreadonly

True if the spacing input should be shown for the current view.

Common spatial references, like Web Mercator and WGS84, will show a significant mismatch between the spacing defined for the grid and the actual length of grid cells. This mismatch varies with position on the map and with direction (the mismatch is different depending on line angle).

Because the spacing input is inappropriate and misleading in common web mapping use cases, it should be hidden from the user to avoid conveying a false sense of precision.

For specialized planar spatial references, it is more likely that the user is an experience GIS professional with an understanding of projections and the consequent distortions. To enable these users to complete their work, users of maps with these spatial references can be given direct access to specify grid length.

placementDisabled Property placementDisabled Boolean Since: ArcGIS Maps SDK for JavaScript 4.33 GridControlsViewModel since 4.31, placementDisabled added at 4.33.

If true, interactive placement tools should be disabled.

rotateWithMap Property rotateWithMap Boolean

Determines the behavior of the grid when the map's viewpoint is rotated. When true, rotating the map also rotates the grid on screen. When false, rotating the viewpoint does not rotate the grid.

Note that rotation is applied independently and can be configured regardless of how this setting is configured.

Default Value:true

rotation Property rotation Number

The grid's rotation in radians.

snappingEnabled Property snappingEnabled Boolean

Controls snapping behavior if snappingOptions has been defined. If snappingOptions have been defined, disabling or enabling grid snapping will also disable or enable grid display.

Default Value:false

snappingOptions Property snappingOptions SnappingOptions |null |undefinedautocast

This is the snapping options object that will be configured by the 'enable snapping' property.

spacing Property spacing Number

Length of a grid cell. Grid cells are always square. Defined in unit.

Default Value:1

unit Property unit LengthUnit |null |undefined

Unit of measure (foot, meter, etc) used when defining the spacing grid cell. Note that units are defined relatively to the map's spatial reference length unit, which will not correspond to geographic distance unless using a special-purpose basemap within a supported target area.

When using Web Mercator, the projection defines the length of a meter in projection system units; this length is equal to a geographic meter only at the equator. On screen, the size of the grid cells is constant from the equator to the poles, but the real-world size of the grid cell is much larger further from the equator.

The length of the grid cells can usefully correspond to a geographic length when the Grid is used with an appropriate spatial reference (for example a local system or a State Plane system) within the reference's area of interst.

view Property view MapView |null |undefined

The view from which the widget will operate.

Method Overview

Show inherited methods

Hide inherited methods

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
Boolean	Returns true if a named group of handles exist.	Accessor
	Removes a group of handles owned by the object.	Accessor
	Try to enable or disable grid display.	GridControlsViewModel

Method Details

addHandles Inherited Method addHandles(handleOrHandles, groupKey) Inherited from Accessor

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the object is destroyed.

groupKey *

optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

hasHandles Inherited Method hasHandles(groupKey){Boolean} Inherited from Accessor

Returns true if a named group of handles exist.

Parameter

groupKey *

optional

A group key.

Returns

Type	Description
Boolean	Returns `true` if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

removeHandles Inherited Method removeHandles(groupKey) Inherited from Accessor

Removes a group of handles owned by the object.

Parameter

groupKey *

optional

A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

trySetDisplayEnabled Method trySetDisplayEnabled(visible)

Try to enable or disable grid display. Will fail if the view is not yet ready to display a grid.

Parameter

visible Boolean

Controls whether to try to enable or disable grid display.