In this topic
- About GraphicTrackers
- Suspending display updates
- Controlling drawing characteristics
- 2D display
- Considerations when using the GraphicTracker
About GraphicTrackers
The GraphicTracker provides a simplified API that allows the developer to easily add, remove, and move graphics smoothly within a map, dynamic map, or globe.
The GraphicTracker removes the need to manually refresh the display when a graphic is added, changed, or moved. Only geometries that support IPoint, IPolyline, and IPolygon can be added to a GraphicTracker with a corresponding point, line, or area symbols. Developers are free to create as many GraphicTrackers as they see fit, but each GraphicTracker must be initialized to use a map or a globe. See the following code example:
[C#]
IGraphicTracker graphicTracker = new GraphicTrackerClass();
graphicTracker.Initialize(theForm.axMapControl1.Map as IBasicMap);
[VB.NET]
Dim graphicTracker As IGraphicTracker = New GraphicTrackerClass()
graphicTracker.Initialize(TryCast(theForm.axMapControl1.Map, IBasicMap))
If you have a form with a GlobeControl and a MapControl displaying moving graphics, then two GraphicTrackers must be initialized—one for each control—and changes made to both.
Each graphic within a GraphicTracker are made of a symbol (IGraphicTrackerSymbol) and a geometry (IGeometry). The graphic is stored as a copy of the geometry and symbol that was supplied to it. Thus, making changes to the original geometry or symbol object will not change the graphic.
To create a graphic, create a geometry and then create a symbol that corresponds with that geometry.
GraphicTracker symbols can be created in two ways.
-
By creating a symbol and passing that into the IGraphicTracker.CreateSymbol method.
-
By creating a symbol from a file by using the IGraphicTracker.CreateSymbolFromPath.
Each GraphicTracker symbol can have a two-dimensional (2D) and three-dimensional (3D) symbol, which will be used in their respective displays. It is not necessary to supply a 3D symbol if the GraphicTracker is only going to be used in 2D mode, however, if the same GraphicTracker is used in 3D the graphics will not display.
To add a graphic call the IGraphicTracker.Add method and pass in the geometry and the associated symbol. The Add method returns an Integer which references the added graphic. This id is very important as it can then be used to manage the graphics properties.
[C#]
IGraphicTrackerSymbol myPointSymbol = IGraphicTracker.CreateSymbol(symbol, null);
int id = graphicTracker.Add(myPointGeometry, myPointSymbol);
[VB.NET]
Dim myPointSymbol As IGraphicTrackerSymbol = IGraphicTracker.CreateSymbol(symbol, Nothing)
Dim id As Integer = graphicTracker.Add(myPointGeometry, myPointSymbol)
If the application needs to use the same GraphicTrackerSymbol more than once it is more efficient to maintain a collection of 2D and/or 3D GraphicTrackerSymbols. This will avoid unnecessary resources being used to create duplicate IGraphicTrackerSymbols. The RSS weather GraphicTracker sample code for RSSWeather.GetSymbol shows how such a collection can be maintained.
The Add() method returns an identifier that is a contiguous zero-based integer. However, it is good practice not to rely on this fact and to store each identifier against the application-specific object that the added graphic represents.
It is possible to change a graphic's geometry or symbol by using the IGraphicTracker.Replace method. The following code example illustrates how to replace the geometry and symbol of a graphic.
[C#]
IGraphicTrackerSymbol myPointSymbol2 = CreateSymbol(symbol2, null);
graphicTracker.Replace(id, myPointGeometry2, myPointSymbol2);
[VB.NET]
Dim myPointSymbol2 As IGraphicTrackerSymbol = CreateSymbol(symbol2, Nothing)
graphicTracker.Replace(id, myPointGeometry2, myPointSymbol2)
Graphics can be updated using the IGraphicTracker.MoveTo method. This will move the centroid of the graphic to the specified coordinate.
The coordinates that you use in the MoveTo method must be in same coordinate system as the data frame.
If a GraphicTracker is no longer required, release the Component Object Model (COM) object for the GraphicTracker. See Releasing COM references for details.
Suspending display updates
The SuspendUpdate property is false by default. This means the GraphicTracker will automatically refresh the display after each graphic is changed. Some applications require graphics to move or change independently of each other—not all at the same time. In this case, a false SuspendUpdate value is preferable. In other applications, having a false SuspendUpdate value can affect performance. For example, if 50 graphics are to be moved periodically on a timer call, the GraphicTracker will have to refresh the display 50 times at each instance.
To address this, set the SuspendUpdate property to true, move the graphics, then set SuspendUpdate to false. This will result in one refresh call and draw all graphics at once. In a dynamic map, the SuspendUpdate property is not relevant.
If you're moving hundreds of graphics periodically when a timer is called, the timer should be called at longer intervals than when only moving tens of graphics. For example, in a 2D map with one thousand graphics, moving all of those graphics every second will produce smoother feedback than moving them every half second. Of course, the timer rate that is easiest to view depends on the graphics card being used as well as the number of graphics used.
Controlling drawing characteristics
Each graphic can be assigned a text label and optional text symbol. The default text symbol is Tahoma, bold, 10 points in size with a vertical offset of 12 points. See the following code example:
[C#]
graphicTracker.SetTextSymbol(id, textSymbol);
graphicTracker.SetLabel(id, "my graphic's label");
...
//To remove the label.
graphicTracker.SetLabel(id, "");
[VB.NET]
graphicTracker.SetTextSymbol(id, textSymbol)
graphicTracker.SetLabel(id, "my graphic's label")
...
'To remove the label.
graphicTracker.SetLabel(id, "")
Programmatically control other drawing characteristics using the following methods and properties.
A symbol's elevation can be floating based on the geometry's z-values or clamped to the ground (3D only).
A symbol's orientation can be set to be billboarded or controlled by the values of the SetPointOrientation method.
A point symbol's pitch, roll and yaw values. In 2D, only the yaw value is used.
A symbol's scale can be fixed based on the symbol's size or automatically shrunk as the display becomes larger in scale.
[C#]
graphicTracker.SetElevationMode(id, esriGTElevation.esriGTElevationClampToGround);
graphicTracker.SetOrientationMode(id, esriGTOrientation.esriGTOrientationAutomatic);
graphicTracker.SetPointOrientation(id, 90, 180, 90);
graphicTracker.SetScaleMode(id, esriGTScale.esriGTScaleFixed);
[VB.NET]
graphicTracker.SetElevationMode(id, esriGTElevation.esriGTElevationClampToGround)
graphicTracker.SetOrientationMode(id, esriGTOrientation.esriGTOrientationAutomatic)
graphicTracker.SetPointOrientation(id, 90, 180, 90)
graphicTracker.SetScaleMode(esriGTScale.esriGTScaleFixed)
The first graphic added will appear underneath subsequent graphics if they have overlapping display areas.
2D display
In a 2D display, such as the Map control, the following properties of a graphic are irrelevant:
- Z-value of the geometry and any movement in the z-axis.
- The esriGTElevation value supplied to the SetElevationMode method; 2D graphics are always clamped to the ground.
- Pitch and roll values supplied to the SetPointOrientation() method.
Considerations when using the GraphicTracker
Performance
There are 4 major factors that can impact the performance of the GraphicTracker.
- Number of Graphics - This is especially important in a 2D application in standard display mode. The more graphics on the screen the longer it will take for the graphics to refresh.
- Complexity of the graphics symbol - Some GraphicTracker symbols will perform better than others. For example, a symbol created using CreateSymbolFromPath method will take longer to refresh then a Simple Marker Symbol.
- Underlying data - The underlying data and complexity of the base map will have an impact on the update rate when panning and zooming a map. Consider using a BasemapLayer to improve this performance.
- Update interval - Each time the GraphicTracker is updated there may be a slight pause as the display is refreshed. (This depends of course on the number of graphics and the complexity of the symbols). Frequent updates can have an impact on the responsiveness of the application.
In order to create a well performing GraphicTracker application a balance must be struck between these factors. It is very possible to update thousands of graphics at an extremely quick update interval. But, complex symbols and user interface responsiveness may be sacrificed.
Timers
Be careful when developing applications with .NET timers. The System.Timers.Timer and System.Threading.Timer classes operate in separate threads. When using these classes be sure the application follows the guidelines set forth by the Writing multithreaded ArcObjects code document. The RSS weather GraphicTracker sample demonstrates updating a GraphicTracker in a multithreaded environment. To keep the updates in the same thread, use the System.Windows.Forms.Timer as this timer will operate in the main thread. An example of this is in the GraphicTracker with the map sample.
Don't forget, the GraphicTracker is not just for moving points. It can also be used for quickly and easily adding graphics to any of the display modes.
See Also:
GraphicTracker with the mapRSS weather GraphicTracker
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
| Development licensing | Deployment licensing |
|---|---|
| Engine Developer Kit | Engine Runtime |
| ArcView | ArcView |
| ArcEditor | ArcEditor |
| ArcInfo | ArcInfo |