How to work with symbols

Summary
This topic describes the classes that support symbology and how to create Marker, Line, and Fill Symbols.

In this topic

To use the code in this topic, add references to System.Drawing.dll, ESRI.ArcGISExplorer.dll, and ESRI.ArcGISExplorer.Application.dll. Add the following namespace references via using (C#) or Imports (VB .NET) statements:
  • ESRI.ArcGISExplorer.Mapping
  • ESRI.ArcGISExplorer.Data
  • ESRI.ArcGISExplorer.Geometry
    ESRI.ArcGISExplorer.Application
Objects which can be symbolized
A number of classes in the API make use of symbols as shown in the table below:
Class
Member
Description
FeatureRenderer.SetSymbol method
A FeatureLayer can display vector data and can be symbolized by setting the symbol on its associated FeatureRenderer object. This can be accessed using the
FeatureLayer.Renderer property.
GeoRssLayer.Symbol property
A GeoRssLayer displays syndicated, geographically tagged content which can be symbolized, typically with a marker symbol.
Graphic.Symbol property
A Graphic is a temporary shape with associated symbology that can be added to the map.
Set in Note constructor but actually sets the
Graphic.Symbol property
 
A Note is a type of MapItem and consists of a Graphic and Popup. Access the Graphic using the Note.Graphic property.
Types of Symbol
ArcGIS Explorer has three types of Symbol as shown below:
Symbol Type
Supported Geometry
Default Symbol
Marker
Point, Multipoint
Orange stickpin
Line
Line
2pt red solid line
Fill
Polygon, Envelope, Multipatch
red solid fill, with 2pt red outline
Creating symbols
The Symbol class consists of three, nested, static classes each representing a different symbol type. The class does not expose a public class constructor meaning that a Symbol object cannot be created using the 'new' keyword. However, static properties and methods on the Symbol class makes creating symbols both simple and flexible. There are three different approaches to creating symbols:
  • Let Explorer create a symbol for you. Each of the classes supporting symbology (listed in table above), has at least one constructor that does not require a symbol to be specified. The object will be assigned a default symbol, based on the GeometryType of the FeatureLayer or Geometry being supplied.
  • Use one of the static properties on the nested Symbol classes. Drilling down through the choices using intellisense provides a simple and convenient way to choose a symbol. For example, to create a light blue, solid, line symbol you could use the Symbol.Line.Solid.LightBlue property.
  • Use one of the static Create methods. This is the most flexible approach as the Color object supports many more predefined colors than the static properties on the Symbol class and additionally allows a custom color to be specified. The CreateMarker method also allows user-defined, marker symbols to be used.
The following sections discuss each symbol type in more detail and provide code examples to illustrate how to create them.
Layer packages and layer files provide a mechanism to include more advanced symbology  available in ArcGIS Desktop applications.
Marker Symbols
Explorer supports both pre-configured and user-defined marker symbols.  A pre-configured marker symbol is characterized by it's Category, Color and Size properties, with the latter being the height of the marker in Points (pt). For a complete list of the many pre-configured symbols, see Preconfigured Marker Symbols.
You can also specify your own marker symbol using the CreateMarker method and supplying the path/URL to an image file or an in-memory, Microsoft .NET Bitmap. For a list of supported formats, see Types of Bitmaps on the Microsoft Developer Network (MSDN) Web site.
Marker symbols for a FeatureLayer can either be billboarded or draped in the 3D display. They will be billboarded by default so that they stand up and appear perpendicular to the horizon. To change this behaviour you can set the FeatureRenderer.Billboarded property to False so that the marker symbols will be draped onto the surface and appear parallel to it. Draping in the 3D display has the disadvantage of poor scaling due to the marker symbols being rasterized at the scale at which they are added to the Map. Marker symbols are always draped in the 2D display and they will scale as the map extent changes.
The code example below assigns marker symbology to a Note, a FeatureLayer and a GeoRssLayer using the different approaches.
[C#] 
//Example 1 - Create a new Note but let Explorer assign the default symbology,
//which for points is an orange pushpin.
Note myHouseNote = new Note("My House", new ESRI.ArcGISExplorer.Geometry.Point(
                            - 117.34, 33.97));
//Example 2 - Create and manually connect a new feature layer and define its marker symbology 
//using one of the static properties (City) available on the static Marker.Civic class.
DataSourceProperties connProps = new DataSourceProperties(@
    "C:\Data\World\cities.shp");
FeatureLayer citiesLayer = new FeatureLayer(connProps, Symbol.Marker.Civic.City)
    ;
citiesLayer.Connect();
//Example 3 - Create a new marker Symbol from a file on disk, then symbolize a GeoRss Earthquake feed
//using the user-defined symbol.
Symbol quakeSymbol = Symbol.CreateMarker(@"C:\Data\WORLD\earthquake.gif");
GeoRssLayer quakeLayer = new GeoRssLayer(new Uri(@
    "http://earthquake.usgs.gov/earthquakes/catalogs/7day-M2.5.xml"),
    quakeSymbol);
quakeLayer.Connect();
//Add the MapItems to a List then add them all to the Map
List < MapItem > mapItemList = new List < MapItem > ();
mapItemList.Add(myHouseNote);
mapItemList.Add(citiesLayer);
mapItemList.Add(quakeLayer);
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add
    (mapItemList);
[VB.NET] 
'Example 1 - Create a new Note but let Explorer assign the default symbology,
'which for points is an orange pushpin.
Dim myHouseNote As Note = New Note("My House", New ESRI.ArcGISExplorer.Geometry.Point( -117.34, 33.97))
'Example 2 - Create and manually connect a new feature layer and define its marker symbology
'using one of the static properties (City) available on the static Marker.Civic class.
Dim connProps As DataSourceProperties = New DataSourceProperties("C:\Data\World\cities.shp")
Dim citiesLayer As FeatureLayer = New FeatureLayer(connProps, Symbol.Marker.Civic.City)
citiesLayer.Connect()
'Example 3 - Create a new marker Symbol from a file on disk, then symbolize a GeoRss Earthquake feed
'using the user-defined symbol.
Dim quakeSymbol As Symbol = Symbol.CreateMarker("C:\Data\WORLD\earthquake.gif")
Dim quakeLayer As GeoRssLayer = New GeoRssLayer(New Uri("http://earthquake.usgs.gov/earthquakes/catalogs/7day-M2.5.xml"), quakeSymbol)
quakeLayer.Connect()
'Add the MapItems to a List then add them all to the Map
Dim mapItemList As List(Of MapItem) = New List(Of MapItem)()
mapItemList.Add(myHouseNote)
mapItemList.Add(citiesLayer)
mapItemList.Add(quakeLayer)
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(mapItemList)
3D display - by default the marker symbols are billboarded so that they stand perpendicular to the horizon.
 
2D display - symbols are always draped on the map
Line Symbols
 
The appearance of a line Symbol is defined by its Color and Size properties, with the latter being the width of the line in Points (pt). The code example below assigns line symbology to three different feature layers using the approaches discussed above.
[C#] 
//Example 1 - Create and connect a new feature layer but let Explorer assign the layer symbology
//automatically, which for lines will be a red solid line.
FeatureLayer roadsLayer = FeatureLayer.OpenShapefile(@
    "C:\Data\USAMajorHighways\usa_major_highways.shp");
//Example 2 - Create and manually connect a new feature layer and define its line symbology 
//using one of the static properties (light blue) available on the static Line.Solid class.
DataSourceProperties connProps = new DataSourceProperties(@
    "C:\Data\TemplateData.gdb", "rivers");
FeatureLayer riversLayer = new FeatureLayer(connProps,
    Symbol.Line.Solid.LightBlue);
riversLayer.Connect();
//Example 3 - Create and manually connect a new feature layer, define its line symbology by creating a 
//new 5pt, mint-cream, line symbol which is then assigned to the FeatureRenderer object associated with the FeatureLayer.
FeatureLayer hikingLayer = FeatureLayer.OpenShapefile(@
    "C:\Data\hikingtrail.shp");
Symbol lineSymbol = Symbol.CreateLine(Color.MintCream);
lineSymbol.Size = 5;
hikingLayer.Renderer.SetSymbol(lineSymbol);
hikingLayer.Connect();
//Add the layers to a List then add them all to the Map
List < FeatureLayer > layerList = new List < FeatureLayer > ();
layerList.Add(roadsLayer);
layerList.Add(riversLayer);
layerList.Add(hikingLayer);
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add
    (layerList);
[VB.NET] 
'Example 1 - Create and connect a new feature layer but let Explorer assign the layer symbology
'automatically, which for lines will be a red solid line.
Dim roadsLayer As FeatureLayer = FeatureLayer.OpenShapefile("C:\Data\USAMajorHighways\usa_major_highways.shp")
'Example 2 - Create and manually connect a new feature layer and define its line symbology
'using one of the static properties (light blue) available on the static Line.Solid class.
Dim connProps As DataSourceProperties = New DataSourceProperties("C:\Data\TemplateData.gdb", "rivers")
Dim riversLayer As FeatureLayer = New FeatureLayer(connProps, Symbol.Line.Solid.LightBlue)
riversLayer.Connect()
'Example 3 - Create and manually connect a new feature layer, define its line symbology by creating a
'new 5pt, mint-cream, line symbol which is then assigned to the FeatureRenderer object associated with the FeatureLayer.
Dim hikingLayer As FeatureLayer = FeatureLayer.OpenShapefile("C:\Data\hikingtrail.shp")
Dim lineSymbol As Symbol = Symbol.CreateLine(Color.MintCream)
lineSymbol.Size = 5
hikingLayer.Renderer.SetSymbol(lineSymbol)
hikingLayer.Connect()
'Add the layers to a List then add them all to the Map
Dim layerList As List(Of FeatureLayer) = New List(Of FeatureLayer)()
layerList.Add(roadsLayer)
layerList.Add(riversLayer)
layerList.Add(hikingLayer)
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(layerList)
Fill Symbols
 
The appearance of a fill Symbol is defined by its Color, OutlineColor and Size properties. The Color property sets the interior color of a polygon, whereas the OutlineColor and Size properties specify the color and width of its perimeter. The code example below assigns polygon symbology to three different Graphics using the approaches discussed above.
[C#] 
//Create a new FeatureLayer and return some polygons which will be used as the 
//geometries for the created graphics.
FeatureLayer ctryLayer = FeatureLayer.OpenShapefile(@
    "C:\Data\WORLD\country.shp");
Table ctryTable = ctryLayer.Table;
Polygon usaPolygon = (Polygon)ctryTable.Search(new Filter("NAME='Sudan'"))
                      .GetFirst().Geometry;
Polygon ozPolygon = (Polygon)ctryTable.Search(new Filter("NAME='Australia'"))
                     .GetFirst().Geometry;
Polygon chinaPolygon = (Polygon)ctryTable.Search(new Filter("NAME='China'"))
                        .GetFirst().Geometry;
//Example 1 - Create a new polygon Graphic but let Explorer assign its symbology
//automatically, which for polygons will be a red solid fill.
Graphic graphic1 = new Graphic(usaPolygon);
//Example 2 - Create a new polygon Graphic which will have a 3pt, green outline and a transparent, hollow fill
//using one of the static properties on the static Fill.Outline class.
Graphic graphic2 = new Graphic(ozPolygon, Symbol.Fill.Outline.Green);
graphic2.Symbol.Size = 3;
//Example 3 - Create a new polygon Graphic, define its symbology by creating a new Symbol which has
//a misty-rose interior and a magenta, 3pt outline then set the Symbol property associated with the Graphic.
Graphic graphic3 = new Graphic(chinaPolygon);
graphic3.Symbol = Symbol.CreateFill(Color.MistyRose, Color.Magenta);
graphic3.Symbol.Size = 3;
//Add the layers to a List then add them all to the Map
List < Graphic > graphicList = new List < Graphic > ();
graphicList.Add(graphic1);
graphicList.Add(graphic2);
graphicList.Add(graphic3);
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Graphics.Add
    (graphicList);
[VB.NET] 
'Create a new FeatureLayer and return some polygons which will be used as the
'geometries for the created graphics.
Dim ctryLayer As FeatureLayer = FeatureLayer.OpenShapefile("C:\Data\WORLD\country.shp")
Dim ctryTable As Table = ctryLayer.Table
Dim usaPolygon As Polygon = DirectCast(ctryTable.Search(New Filter("NAME='Sudan'")).GetFirst().Geometry, Polygon)
Dim ozPolygon As Polygon = DirectCast(ctryTable.Search(New Filter("NAME='Australia'")).GetFirst().Geometry, Polygon)
Dim chinaPolygon As Polygon = DirectCast(ctryTable.Search(New Filter("NAME='China'")).GetFirst().Geometry, Polygon)
'Example 1 - Create a new polygon Graphic but let Explorer assign its symbology
'automatically, which for polygons will be a red solid fill.
Dim graphic1 As Graphic = New Graphic(usaPolygon)
'Example 2 - Create a new polygon Graphic which will have a 3pt, green outline and a transparent, hollow fill
'using one of the static properties on the static Fill.Outline class.
Dim graphic2 As Graphic = New Graphic(ozPolygon, Symbol.Fill.Outline.Green)
graphic2.Symbol.Size = 3
'Example 3 - Create a new polygon Graphic, define its symbology by creating a new Symbol which has
'a misty-rose interior and a magenta, 3pt outline then set the Symbol property associated with the Graphic.
Dim graphic3 As Graphic = New Graphic(chinaPolygon)
graphic3.Symbol = Symbol.CreateFill(Color.MistyRose, Color.Magenta)
graphic3.Symbol.Size = 3
'Add the layers to a List then add them all to the Map
Dim graphicList As List(Of Graphic) = New List(Of Graphic)()
graphicList.Add(graphic1)
graphicList.Add(graphic2)
graphicList.Add(graphic3)
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Graphics.Add(graphicList)