Working with graphics

In this topic

About working with graphics

Drawing graphics on a Web Application Developer Framework (ADF) map can be accomplished using techniques available in each tier of a Web ADF application (that is, client, Web, and server). Each tier is associated with a different development environment and a different way for rendering graphic elements on a map is used. 
Since the Web ADF consolidates 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 uses graphics. 
The following illustration shows where graphics layers can be created and rendered in each tier. The Web ADF includes a public JavaScript library that provides the components to create graphics residing solely on the client Web browser. The Web ADF also manages a set of map resources on the Web tier, including the types of Web ADF graphics (ArcGIS Server and ArcIMS).  
ADF graphics map resources are used to manage Web tier graphics layers and render them on the Web tier as a map image or renders on the client using ADF JavaScript graphic features. The ArcGIS Server and ArcIMS map resources use their respective service capabilities on the server tier to create a graphics layer and merge it with other map data layers in a single map image. Assuming browser blending is enabled for the Web ADF Map control, each map image will overlay in the Web browser in the order of the Web ADF resources. This topic discusses different options available in each tier and how they apply to the Web ADF.

Client tier

For a Web application, the client is usually a Web browser. Web browsers work with Web standards for display and interaction with a Web page, such as Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), JavaScript, and so on.
The available tools in this development environment are limited by what the Web browser supports. CSS can be used to place elements, such as images, over other elements on a page. Vector graphic support is variable, but Scalable Vector Graphics (SVG) and Vector Markup Language (VML) can be used to draw vector graphics on or over other elements on a page.
The Web ADF includes a public JavaScript library that 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 on the client tier, the Web ADF JavaScript library includes the GraphicFeature object. A GraphicFeature can be any valid Web ADF JavaScript library geometry type and can have a default, selected, and highlight symbol. These symbols must be one of the following Web ADF JavaScript library symbol types—MarkerSymbol, LineSymbol, or FillSymbol. The symbol type used depends 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 MapTips' template. 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 provide a way to group multiple GraphicFeatures of the same geometry type into a single object. Symbology can be defined for a GraphicFeatureGroup and overrides 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 apply to all the graphics in the group. Unlike symbology, a handler specified for a GraphicFeatureGroup does not override a handler for the same event on a member GraphicFeature. Rather, both handlers execute when the event is raised. Additionally, GraphicFeatureGroups expose events to handle when a graphic is added, removed, or modified. 
For more information on client tier graphic capabilities, see Graphics and MapTips. 

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 complex. However, the .NET Framework provides the Web ADF with a set of objects to extend from, which the Web ADF exposes in a simple application programming interface (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 (Graphics Layer) to a MapResourceManager and displayed in an associated Map control. A Graphics Layer resource is a type of System.Data.DataSet that can hold many DataTables. You can access the Web ADF GraphicsDataSet via the Graphics property on a Graphics Layer resource. To display semi-transparent symbology in Web ADF graphics layers, set the image format to PNG32 on the graphics map resource item (for example, using the MapResourceManager Resource Items Collection Editor dialog box at design time). 
The Web ADF also defines the following graphics layer types—ElementGraphicsLayer and FeatureGraphicsLayer. Both are a type of System.Data.DataTable and 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. Graphics layer types must be created and managed programmatically.
ElementGraphicsLayers 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 on a map (not for attribute storage).
FeatureGraphicsLayers 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. Graphics layers (that is, .NET) are always managed on the Web tier; however, rendering can occur on the Web or client tier. The RenderOnClient property defines where a graphics layer is rendered. If set to false, a graphics layer is rendered on the Web tier as an image generated using the Windows Graphics Device Interface (GDI+), which is included with the .NET Framework and blended with other map resource images. 
If set to true, a graphics layer is rendered on the client using ADF JavaScript library components. For more information on patterns and techniques for leveraging this capability, see Working with Web tier graphics rendered on the client.   
Layer formats can also be used to define renderers, field aliases, and attribute display formatting when rendering graphics layer content on the client. For more information about techniques to define and apply layer formats to graphics layers, see Working with layer formats. 
The remaining code examples and information in this section cover graphics layers managed and rendered on the Web tier. The following code example shows 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 can be drawn on top of other resources on the map, making 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 example shows how to create a Web ADF graphics resource dynamically. If an existing Web ADF graphics resource (AGResource) is not already available in the MapResourceManager (MapResourceManager1) used by the Map (Map1), a 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

Working with graphics on the server tier means creating graphics in a map image generated by a server, which can 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. 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. Consider the order of resources on a map to determine if the graphics will be visible, since another resource can 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 on the Web tier. Since 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 generated map image.
For more information on developing with ArcGIS Server and ArcIMS in the Web ADF to create and render graphics using the data source specific API, see How to access ArcGIS Server from a Web application and How to access ArcIMS from a Web application.


See Also:

Graphics and MapTips
Working with Web tier graphics rendered on the client
Working with layer formats
How to access ArcGIS Server from a Web application
How to access ArcIMS from a Web application