Working with graphics

Drawing graphics on a Web ADF map can be accomplished using techniques available in each tier of a Web ADF application: client, Web, and server. Each tier is associated with a different development environment and thus a different means for rendering graphic elements on a map is utilized. Since the Web ADF is designed to consolidate multiple data sources in a single application, it offers a rich Web-tier and client-tier solutions for generating and managing graphic content. However, it is important to understand how the Web ADF utilizes graphics. The diagram below illustrates where graphics layers can be created and rendered in each tier. The Web ADF includes a public JavaScript library which provides the components to create graphics that reside solely on the client browser. The Web ADF also manages a set of map resources on te Web-tier, including the types Web ADF graphics, ArcGIS Server and ArcIMS. ADF Graphics map resources are used to manage Web-tier graphics layers and render them in the Web-tier as a map image or render on the client using ADF JavaScript graphic features. Both the ArcGIS Server and ArcIMS map resources use their respective service capabilities in the server-tier to create a graphics layer and merge it other map data layers in a single map image. Assuming browser blending is enabled for the Web ADF Map control, each map image will be overlayed in the browser in the order of the Web ADF resources. The sections below cover different options available in each tier and how they apply to the Web ADF in more detail.

Client tier

For a Web application, the client is almost always a browser. In general, browsers work with a number of Web standards for display and interaction with a Web page, such as HTML, CSS, JavaScript, etc. The tools available in this development environment are limited by what the browser supports. CSS can be used to place elements, such as images, over other elements on a page. Vector graphic support is variable, but SVG (Scalable Vector Graphics) and VML (Vector Markup Language) can be used to draw vector graphics on or over other elements on a page.

The Web ADF includes a public JavaScript Library which enables the management and rendering of pure client graphics through a set of easy-to-use client tier objects and controls. These components are the building blocks of the Web ADF's client tier graphics functionality and can be leveraged by Web ADF developers when custom graphics functionality is needed.

To create map graphics in the client tier, the Web ADF JavaScript Library includes the GraphicFeature object. A GraphicFeature can be of any valid Web ADF JavaScript Library geometry type and can have a default, selected, and highlight symbol. These symbols must be one of the Web ADF JavaScript Library symbol types – MarkerSymbol, LineSymbol, or FillSymbol. The type of symbol used will depend on the graphic's geometry type. Attributes can also be defined for GraphicFeatures. These attributes are used by the Web ADF MapTips control to bind a graphic's data to a MapTip's template. And since a GraphicFeature is a client tier object, it exposes client tier events, which can be handled to trigger custom functionality when a graphic is clicked or hovered over.

GraphicFeatureGroups, as their name suggests, provide a way to group multiple GraphicFeatures of the same geometry type into a single object. Symbology can be defined for a GraphicFeatureGroup and will override any symbology defined for GraphicFeatures that are added to it. GraphicFeatureGroups also expose the same events as GraphicFeatures, and any handlers added to a GraphicFeatureGroup for these shared events will apply to all the graphics within the group. Note that, unlike symbology, a handler specified for a GraphicFeatureGroup does not override a handler for the same event on a member GraphicFeature. Rather, both handlers will execute when the event is raised. Additionally, GraphicFeatureGroups expose events to handle when a graphic is added, removed, or modified.

This help system discusses client tier graphic capabilities in the Web ADF JavaScript Library topic titled Graphics and map tips.
Web tier

The Web tier can provide a rich, full-featured development environment and access to server-side resources. ASP.NET Web applications leverage the Microsoft .NET Framework and its capabilities. The .NET environment provides a few options for drawing graphics on a map, but the implementation can be quite complex. However, the .NET framework does provide the Web ADF with a set of objects to extend from which the Web ADF exposes a simple API for creating graphics on a map.

The Web ADF provides a Graphics data source unique to the Web ADF. The Graphics data source can be added as a graphics map resource item (termed "Graphics Layer") to a MapResourceManager and displayed in an associated Map control. A "Graphics Layer" resource is a type of System.Data.DataSet which can hold many DataTables. You can access the Web ADF GraphicsDataSet via the Graphics property on a Graphics Layer resource. Note, to display semi-transparent symbology in Web ADF graphics layers, set the Image Format to PNG32 on the graphics map resource item (e.g. using MapResourceManager resource items collection editor at design-time).

The Web ADF also defines two graphics layer types: ElementGraphicsLayer and FeatureGraphicsLayer. Both are a type of System.Data.DataTable, thus they can be added to the GraphicsDataSet Tables collection. Graphics layer content is stored in-memory by the Web application. As a result, the amount of content in a graphics layer is proportional to the amount of memory required for the Web application. Note that graphics layer types must be created and managed programmatically.

ElementGraphicsLayers are designed to store basic graphic elements, namely geometry and a symbol. One ElementGraphicsLayer can store different types of geometry. In general, ElementGraphicsLayers are used to display selected features in a map. They are not designed for attribute storage.

FeatureGraphicsLayers are designed to emulate a true feature layer. Each layer only supports one geometry type. Web ADF renderers can be applied to symbolize geometry based on attribute values in the DataTable. FeatureGraphicsLayers also support queries.

To render graphic layer content, the Web ADF provides a set of .NET geometry types, symbols, and renderers. .NET graphics layers are always managed on the Web-tier, however rendering may occur on either the Web or client tier. The RenderOnClient property defines where a graphics layer is rendered. If false, a graphics layer is rendered on the Web-tier as an image generated using GDI+ (included with the .NET Framework) and blended with other map resource images. If true, a graphics layer is rendered on the client using ADF JavaScript library components. The topic Working with Web-tier graphics rendered on the client covers patterns and techniques for leveraging this capability. Layer formats can also be used to define renderers, field aliases, and attribute display formatting when rendering graphics layer content on the client. See the topic Working with layer formats to learn about techniques for defining and applying layer formats to graphics layers. The remaining code examples and discussion cover graphics layers managed and rendered on the Web-tier. The example below illustrates working with a Graphics Layer resource (gResource), a GraphicsDataSet (gResource.Graphics) and both graphics layer types.

[C#]
```
IEnumerable gfc = Map1.GetFunctionalities();
ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource gResource = null;
foreach (IGISFunctionality gfunc in gfc)
{
if (gfunc.Resource is ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)
 {
    gResource = (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource) gfunc.Resource;
    break;
 }
}

// *** ElementGraphicsLayer Example

ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer eglayer =
  new ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer();




ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol sms =
  new ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol();
sms.Color = System.Drawing.Color.Black;
sms.Width = 40;

ESRI.ArcGIS.ADF.Web.Display.Graphics.GraphicElement ge =
  new ESRI.ArcGIS.ADF.Web.Display.Graphics.GraphicElement(point, sms);

eglayer.Add(ge);

gResource.Graphics.Tables.Add(eglayer);

// *** FeatureGraphicsLayer Example

ESRI.ArcGIS.ADF.Web.Display.Graphics.FeatureGraphicsLayer fglayer =
  new ESRI.ArcGIS.ADF.Web.Display.Graphics.FeatureGraphicsLayer();

ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol fs =
  new ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol();
fs.Color = System.Drawing.Color.Red;
fs.Type = ESRI.ArcGIS.ADF.Web.Display.Symbol.MarkerSymbolType.Circle;
fs.Width = 12;

ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer sr =
  new ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer(fs);
fglayer.Renderer = sr;

fglayer.Add(point);

gResource.Graphics.Tables.Add(fglayer);
```
Graphics Layer resources are frequently the first resource in a MapResourceManager and thus can be drawn on top of other resources in the map, which makes them ideal for displaying selected features. Since graphics layer content is created and populated programmatically, they can also be used to display dynamic or event data, such as reading geometry coordinates and attributes from a database or data file. The following code provides an example of creating a Web ADF graphics resource dynamically. If an existing Web ADF graphics resource named "AGResource" is not already available in the MapResourceManager (MapResourceManager1) used by the Map (Map1), a new MapResourceItem is created using a graphics resource definition. When finished the resource item is added to the MapResourceManager and the CreateResource method initializes the new graphics resource. The graphics resource is now ready to use. When finished, depending on the Map blending mode, the Map or the individual resource is refreshed.

[C#]
```
ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource gResource = null;
foreach (IGISFunctionality gfunc in Map1.GetFunctionalities())
{
    if (gfunc.Resource.Name == "AGResource")
    {
	gResource = (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)gfunc.Resource;
	break;
    }
    else
    {
	MapResourceItem mapResourceItem = new MapResourceItem();

	GISResourceItemDefinition definition = new GISResourceItemDefinition();

	mapResourceItem.Name = "AGResource";
	definition.ResourceDefinition = "GraphicsResource";
	definition.DataSourceDefinition = "In Memory";
	definition.DataSourceType = "GraphicsLayer";

	definition.DataSourceShared = true;
	mapResourceItem.Parent = MapResourceManager1;
	mapResourceItem.Definition = definition;
	ESRI.ArcGIS.ADF.Web.DisplaySettings displaysettings = new ESRI.ArcGIS.ADF.Web.DisplaySettings();
	displaysettings.Transparency = 0.0F;
	displaysettings.Visible = true;
	mapResourceItem.DisplaySettings = displaysettings;

	MapResourceManager1.ResourceItems.Insert(0, mapResourceItem);
	gResource =
	    (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)
	    MapResourceManager1.CreateResource(mapResourceItem);
	break;
    }
}

// Create a graphics layer, add content, then add it to the graphics resource

if (Map1.ImageBlendingMode == ImageBlendingMode.WebTier)
{
    Map1.Refresh();
}
else
{
    Map1.RefreshResource(gResource.Name);
}

					
```
Server tier

In general, working with graphics in the server-tier means creating graphics in a map image generated by a server, which may be subsequently utilized by the Web ADF. The ability to create graphics on the server depends on the capabilities of the service or data source. Both ArcIMS and ArcGIS Server are capable of creating custom graphics in map images they generate. However, since each provides a different interface to create graphics, different APIs must also be used. Also, graphics added at the server tier will be part of the map image returned to the client. You should consider the order of resources in a map to determine if the graphics will be visible, since another resource may cover the server generated graphics.

The Web ADF is a shallowly stateful application in that it works with data sources in a stateless manner and manages state in the Web-tier. Since both ArcIMS and ArcGIS Server data sources support server-tier graphics, the MapFunctionality for each data source also provides a mechanism to access the data source specific API and add server-side graphics. The server graphics are stored in session state by the Web ADF and reapplied for each map image generated.

Two tutorials presented in this help system introduce developing with ArcGIS Server and ArcIMS in the Web ADF. In both tutorials, graphics are created and rendered on the server using the data source specific API.