Merge pull request #98620 from rbrundritt/master

drawing tools and accessibility doc improvements

Author: tfosmark

articles/azure-maps/drawing-tools-events.md

@@ -0,0 +1,81 @@
+---
+title: Add a drawing toolbar to Azure Maps| Microsoft Docs
+description: How to add a drawing toolbar to a map using Azure Maps Web SDK
+author: rbrundritt
+ms.author: richbrun
+ms.date: 12/05/2019
+ms.topic: conceptual
+ms.service: azure-maps
+services: azure-mapss
+manager: cpendleton
+---
+
+# Drawing tool events
+
+When using drawing tools on a map, it is often useful to react to certain events as the user draws on the map. The following table lists all of the events supported by the `DrawingManager` class.
+
+| Event | Description |
+|-------|-------------|
+| `drawingchanged` | Fired when any coordinate in a shape has been added or changed. | 
+| `drawingchanging` | Fired when any preview coordinate for a shape is being displayed. For example, will fire multiple times as a coordinate is dragged. | 
+| `drawingcomplete` | Fired when a shape has finished being drawn or taken out of edit mode. |
+| `drawingmodechanged` | Fired when the drawing mode has changed. The new drawing mode is passed into the event handler. |
+| `drawingstarted` | Fired when the user starts drawing a shape or puts a shape into edit mode.  |
+
+The following code shows how the events in the Drawing Tools module work. Draw shapes on the map and watch as the events fire.
+
+<iframe height="500" style="width: 100%;" scrolling="no" title="Drawing tools events" src="https://codepen.io/azuremaps/embed/dyPMRWo?height=500&theme-id=default&default-tab=js,result" frameborder="no" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href='https://codepen.io/azuremaps/pen/dyPMRWo'>Drawing tools events</a> by Azure Maps
+  (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
+</iframe>
+
+<br/>
+
+## Examples
+
+The following are examples of some common scenarios that use the drawing tools events.
+
+### Select points in polygon area
+
+The following code shows how to monitor the drawing of shapes that represent polygon areas (polygons, rectangles, and circles), and determine which data points on the map are within the drawn area. The `drawingcomplete` event is used to trigger the select logic. In the select logic, all data points on the map are looped through and tested for intersection with the polygon area of the drawn shape. This example makes use of the open-source [Turf.js](http://turfjs.org/) library to perform a spatial intersection calculation.
+
+<iframe height="500" style="width: 100%;" scrolling="no" title="Select data in drawn polygon area" src="https://codepen.io/azuremaps/embed/XWJdeja?height=500&theme-id=default&default-tab=result" frameborder="no" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href='https://codepen.io/azuremaps/pen/XWJdeja'>Select data in drawn polygon area</a> by Azure Maps
+  (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
+</iframe>
+
+<br/>
+
+### Draw and search in polygon area
+
+The following code shows how to perform a search for points of interests inside a shape area after the user has finished drawing the shape. The `drawingcomplete` event is used to trigger the search logic. If the user draws a rectangle or polygon, a search inside geometry is performed. If a circle is drawn, the radius and center position is used to perform a point of interest search. The `drawingmodechanged` event is used to determine when the user is switching into a drawing mode, and clears the drawing canvas.
+
+<iframe height="500" style="width: 100%;" scrolling="no" title="Draw and search in polygon area" src="https://codepen.io/azuremaps/embed/eYmZGNv?height=500&theme-id=default&default-tab=js,result" frameborder="no" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href='https://codepen.io/azuremaps/pen/eYmZGNv'>Draw and search in polygon area</a> by Azure Maps
+  (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
+</iframe>
+
+<br/>
+
+### Create a measuring tool
+
+The following code shows how the drawing events can be used to create a measuring tool. The `drawingchanging` is used to monitor the shape as it is being drawn. As the user moves the mouse, the dimensions of the shape are calculated. The `drawingcomplete` event is used to do a final calculation on the shape after it has been drawn. The `drawingmodechanged` event is used to determine when the user is switching into a drawing mode, and clears the drawing canvas and old measurement information.
+
+<iframe height="500" style="width: 100%;" scrolling="no" title="Measuring tool" src="https://codepen.io/azuremaps/embed/RwNaZXe?height=500&theme-id=default&default-tab=js,result" frameborder="no" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href='https://codepen.io/azuremaps/pen/RwNaZXe'>Measuring tool</a> by Azure Maps
+  (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
+</iframe>
+
+<br/>
+
+## Next steps
+
+Learn more about the Services module:
+
+> [!div class="nextstepaction"]
+> [Services module](how-to-use-services-module.md)
+
+Check out more code samples:
+
+> [!div class="nextstepaction"]
+> [Code sample page](https://aka.ms/AzureMapsSamples)

articles/azure-maps/drawing-tools-interactions-keyboard-shortcuts.md

@@ -0,0 +1,145 @@
+---
+title: Drawing tools interaction types and keyboard shortcuts in Azure Maps| Microsoft Docs
+description: How to draw and edit shapes using a mouse, touch screen, or keyboard in the Azure Maps Web SDK
+author: rbrundritt
+ms.author: richbrun
+ms.date: 12/05/2019
+ms.topic: conceptual
+ms.service: azure-maps
+services: azure-mapss
+manager: cpendleton
+---
+
+# Interaction types and keyboard shortcuts in the drawing tools module
+
+This article outlines all the different ways to draw and edit shapes on a map using a mouse, a touch screen, or keyboard shortcuts.
+
+The drawing manager supports three different ways of interacting with the map to draw shapes.
+
+* `click` - Coordinates are added when the mouse or touch is clicked.
+* `freehand ` - Coordinates are added when the mouse or touch is dragged on the map. 
+* `hybrid` - Coordinates are added when the mouse or touch is clicked or dragged.
+
+## How to draw shapes
+
+The following outlines all the different ways that shapes can be drawn on the map. Before any shape can be drawn, the `drawingMode` option of the drawing manager needs to be set to a supported drawing setting. This can be done programmatically, or by pressing a one of the drawing buttons on the toolbar. The drawing mode stays enabled, even after a shape has been drawn, making it easy to draw additional shapes of the same type. The drawing mode can be put into an idle state programmatically, or by clicking the current drawing modes button on the toolbar. 
+
+### How to draw a point
+
+When the drawing manager is in `draw-point` drawing mode, the following actions can be done to draw points on the map. These methods work with all interaction modes.
+
+**Start drawing**
+ - Click the left mouse button or touch the map to add a point to the map. 
+ - If the mouse is over the map, press the `F` key, and a point will be added using the coordinate of where the mouse pointer is. This will provide a higher accuracy method of adding a point to the map as there will be less movement on the mouse due to the pressing motion of the left mouse button.
+ - Keep clicking, touching, or pressing `F` to add more points to the map.
+ 
+**Finish drawing**
+ - Click on any button in the drawing toolbar. 
+ - Programmatically set the drawing mode. 
+ - Press the `C` key.
+
+**Cancel drawing**
+ - Press the `Escape` key.
+
+### How to draw a line
+
+When the drawing manager is in `draw-line` mode, the following actions can be done to draw points on the map depending on what the interaction mode is set to.
+
+**Start drawing**
+ - Click mode
+   * Click the left mouse button or touch the map to add each point of a line on the map. A coordinate is added to the line for each click/touch. 
+   * If the mouse is over the map, press the `F` key, and a point will be added using the coordinate of where the mouse pointer is. This will provide a higher accuracy method of adding a point to the map as there will be less movement on the mouse due to the pressing motion of the left mouse button.
+   * Keep clicking until all the desired points have been added to the line.
+ - Freehand mode
+   * Press down the left mouse button or touch-down on the map and drag the mouse or touch point around. Coordinates are added to the line as the mouse or touch point moves around the map. As soon as the mouse or touch-up event is triggered, the drawing is completed. The frequency at which coordinates are added is defined by the drawing managers `freehandInterval` option.
+ - Hybrid mode
+   * Alternate between click and freehand methods as desired while drawing a single line. For example, click a few points, then hold and drag the mouse to add a bunch of points, then click a few more. 
+
+**Finish drawing**
+ - Hybrid/Click mode
+   * Double-click the map at the last point. 
+   * Click on any button in the drawing toolbar. 
+   * Programmatically set the drawing mode. 
+ - Freehand mode
+   * Release the mouse button or touch point.
+ - Press the `C` key.
+
+**Cancel drawing**
+ - Press the `Escape` key.
+
+### How to draw a polygon
+
+When the drawing manager is in `draw-polygon` mode, the following actions can be done to draw points on the map depending on what the interaction mode is set to.
+
+**Start drawing**
+ - Click mode
+   * Click the left mouse button or touch the map to add each point of a polygon on the map. A coordinate is added to the polygon for each click/touch. 
+   * If the mouse is over the map, press the `F` key, and a point will be added using the coordinate of where the mouse pointer is. This will provide a higher accuracy method of adding a point to the map as there will be less movement on the mouse due to the pressing motion of the left mouse button.
+   * Keep clicking until all the desired points have been added to the polygon.
+ - Freehand mode
+   * Press down the left mouse button or touch-down on the map and drag the mouse or touch point around. Coordinates are added to the polygon as the mouse or touch point moves around the map. As soon as the mouse or touch-up event is triggered, the drawing is completed. Note that the frequency at which coordinates are added is defined by the drawing managers `freehandInterval` option.
+ - Hybrid mode
+   * Alternate between click and freehand methods as desired while drawing a single polygon. For example, click a few points, then hold and drag the mouse to add a bunch of points, then click a few more. 
+
+**Finish drawing**
+ - Hybrid/Click mode
+   * Double-click the map at the last point. 
+   * Click on the first point in the polygon.
+   * Click on any button in the drawing toolbar. 
+   * Programmatically set the drawing mode. 
+ - Freehand mode
+   * Release the mouse button or touch point.
+ - Press the `C` key.
+
+**Cancel drawing**
+ - Press the `Escape` key.
+
+### How to draw a rectangle
+
+When the drawing manager is in `draw-rectangle` mode, the following actions can be done to draw points on the map depending on what the interaction mode is set to. The generated shape will follow the [extended GeoJSON specification for rectangles](extend-geojson.md#rectangle).
+
+**Start drawing**
+ - Press down the left mouse button or touch-down on the map to add the first corner of the rectangle and drag to create the rectangle. 
+
+**Finish drawing**
+ - Release the mouse button or touch point.
+ - Programmatically set the drawing mode. 
+ - Press the `C` key.
+
+**Cancel drawing**
+ - Press the `Escape` key.
+
+### How to draw a circle
+
+When the drawing manager is in `draw-circle` mode, the following actions can be done to draw points on the map depending on what the interaction mode is set to. The generated shape will follow the [extended GeoJSON specification for circles](extend-geojson.md#circle).
+
+**Start drawing**
+ - Press down the left mouse button or touch-down on the map to add the center of the circle and drag give the circles a radius. 
+
+**Finish drawing**
+ - Release the mouse button or touch point.
+ - Programmatically set the drawing mode. 
+ - Press the `C` key.
+
+**Cancel drawing**
+ - Press the `Escape` key.
+
+## Keyboard shortcuts
+
+The drawing tools support keyboard shortcuts that make it easier to draw and edit shapes on the map. These keyboard shortcuts are functional when the map has focus.
+
+| Key      | Action                            |
+|----------|-----------------------------------|
+| `C` | Completes any drawing that is in progress and sets the drawing mode to idle. Focus will move to top-level map element.  |
+| `Escape` | Cancels any drawing that is in progress and sets the drawing mode to idle. Focus will move to top-level map element.  |
+| `F` | Adds a coordinate to a point, line, or polygon if the mouse is over the map. Equivalent action of clicking the map when in click or hybrid mode. This shortcut allows for more precise and faster drawings as you can use one hand to position the mouse and other to press the button without the mouse moving from the press gesture. |
+
+## Next steps
+
+Learn more about the classes in the drawing tools module:
+
+> [!div class="nextstepaction"]
+> [Drawing manager](https://docs.microsoft.com/javascript/api/azure-maps-drawing-tools/atlas.drawing.drawingmanager?view=azure-node-latest)
+
+> [!div class="nextstepaction"]
+> [Drawing toolbar](https://docs.microsoft.com/javascript/api/azure-maps-drawing-tools/atlas.control.drawingtoolbar?view=azure-node-latest)

articles/azure-maps/how-to-render-custom-data.md

@@ -17,6 +17,8 @@ This article explains how to use the [static image service](https://docs.microso
 
 To render custom pushpins, labels, and geometry overlays, you can use the Postman application. You can use Azure Maps [Data Service APIs](https://docs.microsoft.com/rest/api/maps/data) to store and render overlays.
 
+> [!Tip]
+> It is often much more cost effective to use the Azure Maps Web SDK to show a simple map on a web page than to use the static image service. The web SDK uses map tiles and unless the user pans and zooms the map, they will often generate only a fraction of a transaction per map load. Note that the Azure Maps web SDK has options for disabling panning and zooming. Additionally, the Azure Maps web SDK provides a richer set of data visualization options than a static map web service does.  
 
 ## Prerequisites
 

articles/azure-maps/how-to-use-map-control.md

@@ -31,7 +31,7 @@ You can embed a map in a web page by using the Map Control client-side Javascrip
 
     b. Alternatively, load the Azure Maps Web SDK source code locally using the [azure-maps-control](https://www.npmjs.com/package/azure-maps-control) NPM package and host it with your app. This package also includes TypeScript definitions.
 
-    > npm install azure-maps-control
+    > **npm install azure-maps-control**
 
     Then add references to the Azure Maps stylesheet and script source references to the `<head>` element of the file:
 

articles/azure-maps/how-to-use-services-module.md

@@ -24,14 +24,14 @@ The Azure Maps Web SDK provides a *services module*. This module is a helper lib
         <script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>
         ```
 
-    - Alternatively, load the Azure Maps Web SDK source code locally by using the [azure-maps-rest](https://www.npmjs.com/package/azure-maps-rest) npm package, and then host it with your app. This package also includes TypeScript definitions. Use this command:
+    - Alternatively, load the services module for the Azure Maps Web SDK source code locally by using the [azure-maps-rest](https://www.npmjs.com/package/azure-maps-rest) npm package, and then host it with your app. This package also includes TypeScript definitions. Use this command:
 
         > **npm install azure-maps-rest**
 
         Then, add a script reference to the `<head>` element of the file:
 
          ```html
-        <script src="node_modules/azure-maps-rest/dist/js/atlas-service.min.js"></script>
+        <script src="node_modules/azure-maps-rest/dist/atlas-service.min.js"></script>
          ```
 
 1. Create an authentication pipeline. You must create the pipeline before you can initialize a service URL client endpoint. Use your own Azure Maps account key or Azure Active Directory (Azure AD) credentials to authenticate an Azure Maps Search service client. In this example, the Search service URL client will be created.