Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: MapToolProxy

require(["esri/opsdashboard/MapToolProxy"], function(MapToolProxy) { /* code goes here */ });

Description

(Added at v3.14)
MapToolProxy is a class used to define an operations dashboard extension map tool. MapToolProxy can be directly instantiated to communicate with the host operations dashboard application or used as a mixin in a Dojo or Dijit class, see declare. When the proxy is instantiated, it will automatically start an initialization process with the the host operations dashboard. If the initialization is successful, the event host-ready will be fired, or if using as a mixin, the function hostReady will be called. It's only when the initialization is finished that configuration properties, functions to communicate with the host will be available, and host's events will be fired. If an error occured during the initialization process, the event initialization-error is fired, or for mixin the function hostInitializationError is called, passing the error as argument.

A map tool has two parts a) a tool placed on a map widget default toolbar b) when activated a user experience on the map widget. The icon for a) can be defined in the extension manifest. MapToolProxy is used to define b). For optimization purpose, a map tool extension is loaded when the corresponding tool has been activated and unloaded when the tool is deactivated. If a state has to be preserved in between to activation/deactivation, an object containing state properties can be passed to the function deactivateMapTool. For an extension MapTool, configuration properties can be captured automatically by using manifest configuration properties and additional properties can be captured if a MapTool configuration user experience is provided.

Example 1: Used as a mixin in dijit class
require([
  "dojo/_base/declare",
  "dijit/_WidgetBase",
  "dijit/_TemplatedMixin",
  "esri/opsdashboard/MapToolProxy"
], function(declare, _WidgetBase, _TemplatedMixin, MapToolProxy){
  return declare("MyMapToolExtension", [_WidgetBase, _TemplatedMixin, MapToolProxy], {
    templateString: "<div>hello operation dashboard</div>",
    hostReady: function(){
      this.setDisplaySize({
        width: 200,
        height: 200
      });
      var configProperty = this.propertyIWantoSave;
    },
    onDeactivateButtonClick: function(){
      this.deactivateMapTool();
    }
  });
});


Example 2: Used as plain proxy object
require([
  "esri/opsdashboard/MapToolProxy"
], function(MapToolProxy){
  var proxy = new MapToolProxy();
  proxy.on("host-ready", function(){
    this.setDisplaySize({
      width: 200,
      height: 200
    });
    var configProperty = this.propertyIWantoSave;
  });
  closeButton.on("click", function(){
    proxy.deactivateMapTool();
  });
});
An extension is defined by the json manifest file. Some configuration properties could or could not be available based on the manifest properties. The same is applicable to functions and callbacks exposed by the mixin (see the manifest documentation).

See also

Samples

Search for samples that use this class.

Properties

NameTypeSummary
availableDisplaySizeNumberRead-only: The available size for the map tool user experience on the host map widget.
displaySizeObjectRead-only: The map tool user experience size in pixels.
mapWidgetProxyMapWidgetProxyRead-only: The map widget that is hosting the map tool user experience.
previousStateObjectRead-only: The previous map tool user experience state that was passed the last time the map tool was deactivated.

Methods

NameReturn typeSummary
activateMapDrawing(options)NoneActivates a drawing activity on the host map widget. Note: if this function was called, the deactivateMapDrawing() function should also be called before deactivating the map tool user experience.
availableDisplaySizeChanged(availableSize)NoneCalled by the host application when the available size for the map tool user experience has changed (user resizes the application or the map widget).
deactivateMapDrawing()NoneDeactivates the drawing activity on the host map widget.
deactivateMapTool(state)NoneDeactivate the map tool user experience.
mapDrawComplete(geometry)NoneCalled by the host application when the user has completed the drawing activity on the map.
setDisplaySize(size)PromiseChange the size of the user experience area in the host application for this map tool user experience.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
available-display-size-changed
{
  size: <Object>
}
Event indicating that the available display size for the map tool user experience has changed.
draw-complete
{
  geometry: <Geometry>
}
Event indicating that a previously activate drawing activity has been completed by the user.
Property Details

<Number> availableDisplaySize

Read-only: The available size for the map tool user experience on the host map widget. If the user resizes the host map widget this property will be updated and the function availableDisplaySize Changed.

<Object> displaySize

Read-only: The map tool user experience size in pixels. Use setDisplaySize() to change this value.

<MapWidgetProxy> mapWidgetProxy

Read-only: The map widget that is hosting the map tool user experience.

<Object> previousState

Read-only: The previous map tool user experience state that was passed the last time the map tool was deactivated.
Method Details

activateMapDrawing(options)

Activates a drawing activity on the host map widget. Note: if this function was called, the deactivateMapDrawing() function should also be called before deactivating the map tool user experience.
Parameters:
<Object> options Required Drawing options.
Object Specifications:
<drawingOptions>
<drawingType> geometryType Required The geometry to draw.

availableDisplaySizeChanged(availableSize)

Called by the host application when the available size for the map tool user experience has changed (user resizes the application or the map widget).
Parameters:
<Object> availableSize Required The size available on the host map widget for the map tool user experience.
Object Specifications:
<displaySize>
<Number> height Required The height (in pixels) of the displaySize.
<Number> width Required The width (in pixels) of the displaySize.

deactivateMapDrawing()

Deactivates the drawing activity on the host map widget.

deactivateMapTool(state)

Deactivate the map tool user experience. The extension will be unloaded. If necessary a state can be saved in the host. The state will be set on the map tool mixin next time the map tool is activated. The state must be a json compatible object.
Parameters:
<Object> state Required A JSON object that needs to be persisted in the host until the next activation of the map tool user experience.

mapDrawComplete(geometry)

Called by the host application when the user has completed the drawing activity on the map.
Parameters:
<Geometry> geometry Required The geometry captured by the user during the drawing activity.

setDisplaySize(size)

Change the size of the user experience area in the host application for this map tool user experience.
Return type: Promise
Parameters:
<Object> size Required The new size for the user experience.
Object Specifications:
<displaySize>
<Number> height Required The height (in pixels) of the displaySize.
<Number> width Required The width (in pixels) of the displaySize.
Event Details
[ On Style Events | Connect Style Event ]

available-display-size-changed

Event indicating that the available display size for the map tool user experience has changed. Can be used to decide if the display size for the map tool user experience should also be changed.
Event Object Properties:
<Object> size The new available display size.

draw-complete

Event indicating that a previously activate drawing activity has been completed by the user.
Event Object Properties:
<Geometry> geometry The result form the drawing activity.