How to add graphics

Summary

This topic describes what graphics are, when to use graphics, and how to add graphics to a map.

In this topic

Defining graphics
Adding a graphic to a map
Describing optional graphic properties
Adding multiple graphics to a map

To use the code in this topic, add references to ESRI.ArcGISExplorer.dll and ESRI.ArcGISExplorer.Application.dll. Add the following namespace references via using (C#) or Imports (VB .NET) statements:

ESRI.ArcGISExplorer.Geometry
ESRI.ArcGISExplorer.Mapping
ESRI.ArcGISExplorer.Application

Defining graphics

A graphic consists of a geometry and a symbol that can be added to the map. Graphics are temporary and are cannot be saved in a map document. Graphics are commonly used for the following:

Record a user's interaction with the map, for example, to display all clicked locations. For more information, see the Track shapes sample.
Highlight the results of a query, for example, to show all countries from a countries layer that have a population greater than 100 million. The Layer attributes sample uses graphics to highlight mountains that have been selected in an attribute table.
Represent moving objects, for example, the Vehicle tracker sample moves graphics, each of which represents the current position of an emergency response vehicle.

In the ArcGIS Explorer application programming interface (API), a graphic is represented by the Graphic class. The collection of all user added graphics, as opposed to application added graphics, such as a Find result, are managed by the GraphicCollection class that can be accessed using the MapDisplay.Graphics property.

If you need to persist graphical information on the map, use "Notes" as they are saved in a map document.

Graphics are always drawn on top of all layers on the map.

Adding a graphic to a map

Do the following to add a graphic to a map:

Create a graphic object.
Specify the geometry (optionally, define a symbol).
Use the Add method to add the graphic to the GraphicCollection.

See the following code example:

[C#]


        //Example 1—Create a graphic using a geometry. A default symbol for points is assigned.
Graphic pointGraphic1 = new Graphic(new ESRI.ArcGISExplorer.Geometry.Point(56, 
                                    - 3.2));
//Add the graphic to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(pointGraphic1);
//Example 2—Create a graphic using a geometry and symbol.
Graphic pointGraphic2 = new Graphic(new ESRI.ArcGISExplorer.Geometry.Point(147,
                                    - 42), Symbol.Marker.Flag.Green);
//Add the graphic to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(pointGraphic2);

[VB.NET]


        'Example 1—Create a graphic using a geometry. A default symbol for points is assigned.
Dim pointGraphic1 As Graphic = New Graphic(New ESRI.ArcGISExplorer.Geometry.Point(56, -3.2))
'Add the graphic to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(pointGraphic1)
'Example 2—Create a graphic using a geometry and symbol.
Dim pointGraphic2 As Graphic = New Graphic(New ESRI.ArcGISExplorer.Geometry.Point(147, -42), Symbol.Marker.Flag.Green)
'Add the graphic to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(pointGraphic2)

A graphic cannot be created using a multipatch, envelope, or multipoint geometry.

You can create a graphic without specifying a symbol because each supported geometry type has an associated default symbol. For a list of default symbols, see Mapping namespace overview.

Describing optional graphic properties

The following table describes other optional properties on the Graphic class:

Property	Description
HighlightOnMouseOver	A boolean value which determines whether the graphic should highlight when the mouse moves over it.
Label	A string that appears as a ToolTip when hovering over the graphic.
LabelVisibility	One of the LabelVisibility values that determines whether the label should be permanently visible, not visible or only visible when the mouse moves over the graphic.
Placement3D	One of the Placement3D values that determines if the graphic is clamped to the surface (default), or if the elevation z-values from the geometry is recognized (if present).
Tag	An object that can be anything you want to tag to the graphic. It usually contains a name or ID so the graphic can be located in the GraphicCollection.
Visible	A boolean value that determines if the graphic is visible.

Adding multiple graphics to a map

Adding a graphic causes the map to refresh; therefore, it is inefficient to add multiple graphics one after the other using the previously described method. Instead, use the Add method overload, which takes a generic enumerable set of Graphic objects, namely IEnumerable<Graphic> (IEnumerable(Of Graphic) in Visual Basic) as it suspends the display until all graphics have been added to the map. See the following code example:

[C#]


        //Create some graphics...
Graphic graphic1 = new Graphic(new ESRI.ArcGISExplorer.Geometry.Point(86.925,
                               27.985), Symbol.Marker.Flag.Red, "Mt.Everest");
Graphic graphic2 = new Graphic(new ESRI.ArcGISExplorer.Geometry.Point( - 3, 56))
                               ;
Polyline line = new Polyline(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(5, 5), new
                                   ESRI.ArcGISExplorer.Geometry.Point(7, 7), new
                                   ESRI.ArcGISExplorer.Geometry.Point(10, 10)
}

);
Graphic graphic3 = new Graphic(line);
//Add graphics to a generic list. 
System.Collections.Generic.List < Graphic > myGraphicsList = new List < Graphic
    > ();
myGraphicsList.Add(graphic1);
myGraphicsList.Add(graphic2);
myGraphicsList.Add(graphic3);
//Add all graphics in the list to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(myGraphicsList);

[VB.NET]


        'Create some graphics...
Dim graphic1 As Graphic = New Graphic(New ESRI.ArcGISExplorer.Geometry.Point(86.925, 27.985), Symbol.Marker.Flag.Red, "Mt.Everest")
Dim graphic2 As Graphic = New Graphic(New ESRI.ArcGISExplorer.Geometry.Point( -3, 56))
Dim Line As Polyline = New Polyline(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(5, 5), New ESRI.ArcGISExplorer.Geometry.Point(7, 7), New ESRI.ArcGISExplorer.Geometry.Point(10, 10)})
Dim graphic3 As Graphic = New Graphic(Line)
'Add graphics to a list.
Dim myGraphicsList As System.Collections.Generic.List(Of Graphic) = New List(Of Graphic)()
myGraphicsList.Add(graphic1)
myGraphicsList.Add(graphic2)
myGraphicsList.Add(graphic3)
'Add all graphics in the list to the GraphicCollection.
Application.ActiveMapDisplay.Graphics.Add(myGraphicsList)

Internally, this Add method overload uses the MapDisplay.SuspendDisplay method to prevent map refreshes while the graphics are being added. For more information, see the snippet, Suspend display using statement.