Cursors in ArcObjects, Explained

In ArcObjects, a cursor refers to a set of records or subset of records obtained by any query (Attribute/ Spatial) over a FeatureClass or Table. -> Getting confused with selection set and Cursors? Cursors are always not for display, whereas selection set is bound by display or any selected features in ArcMap display is called as selection set.

Cursor ? FeatureCursor = ?

Cursor and FeatureCursor are similar objects. The work location of them brought in separation or two different terminologies among them. Yes, Cursors work location is always a table, whereas FeatureCursor’s work location is always a FeatureClass or IFeatureClass. A Cursor would return you any object that you have queried for whereas IFeatureCursor would return you an IFeature.

Types of Cursors

There are three types of cursors found in both the Cursor and FeatureCursor classes. The most commonly used type of cursor is the Search Cursor. It is used in query operations to return a subset of records based on your query. Search Cursors are read-only cursors.  Insert, update or delete is not possible with a Search Cursor.

A second type of cursor, the Insert Cursor, is specifically used to insert a new record in a table. The Update Cursor is used to update or delete records in a table. The records returned in an Update or Search Cursor can be constrained to match attribute criteria and/or spatial criteria. It is important that you create the proper type of cursor for the operation that you are performing.

Cursor Class

The Cursor class is used to create objects that work with database tables. The Cursor class in ArcObjects is an instantiable class. Which means you must use another object to obtain an instance of this class. In this case, the Table class in ArcObjects is used to create an instance of the cursor class. The Table class contains three methods that can be used to return an instance of the Cursor class. The type of cursor returned is dependent upon the method called. Figure 1 shows the Object model diagram for the Table class in ArcObjects.

 The ITable interface has three methods that can be used to return specific types of cursor objects. The Search, Insert, and Update methods on ITable are used to return cursor instances. The names of the methods correspond to the type of cursor returned.

After one of these methods has been called, ArcObjects returns an instance of ICursor. Figure 2 shows the object model diagram for the Cursor class. Search, Insert, and Update all return an instance of ICursor. ICursor has one property (Fields) and a number of methods that can be used to manipulate the subset of records. Some of the methods available on ICursor may not be applicable depending on the type of cursor that you are working with. For instance, if you created a Search Cursor, the InsertRow and UpdateRow methods will return an error if called since you are not working with Insert or Update Cursors.

FeatureCursor Class

The FeatureCursor class is very similar to the Cursor class with the exception that FeatureCursor are used when you’re working with geographic datasets rather than traditional database tables. Geographic datasets are typically shapefiles and geodatabase FeatureClass. Similar to the Cursor class, the FeatureCursor class is an instantiable class created through the use of a method on a FeatureClass object. We also have Search, Insert and Update methods alike ITable interface which returns an instance of IFeatureCursor. The properties and methods available on IFeatureCursor are functionally similar to those on ICursor.

Applying Attribute and Spatial Constraints

While you browse along the OMD of a FeatureClass and Table, Search, Insert and Update methods are used to return a cursor that contains a parameter of IQueryFilter instance.

IQueryFilter object is the query to subset a table or it helps you to subset a record from a table or a FeatureClass, in memory. Similarly for any query of Spatial sort SpatialFilter should be used, but SpatialFilter can only be applied on a FeatureClass. If further attempt over the Table gives you an ERROR as because we lack spatial information over any normal table.

  

QueryFilter

To subset any record from a table or a FeatureClass, you need to define a QueryFilter which specifies the records to be returned. Create a new instance of IQueryFilter and define an attribute constraint for your search by using WhereClause property.

IQueryFilter qFilter = new QueryFilterClass;

qFilter.WhereClasue=”Name=’ArcObjects’”;

This would be used as like

 IFeatureCursor fCursor= featureClass.Search (qFilter, true);

SpatialFilter

As discussed earlier a SpatialFilter can only be applied to produce a subset of records based on spatial criteria.

Just like QueryFilter, SpatialFilter is also a creatable class so the New keyword can be used to create an instance of this class. SpatialFilter uses a Geometry property and a SpatialRel property to define the search criteria. The Geometry property is used to specify a particular geographic feature. SpatialRel can be set to one of a predefined set of constants such as intersects, overlaps, or touches. Because SpatialFilter is a type of QueryFilter, it also has access to all the methods and properties on that class. Therefore, you can use the WhereClause property on IQueryFilter to combine spatial and attribute constraints. The below snippet helps you understand how a SpatialFilter and QueryFilter can be combined together.

ISpatialFilter spatialFilter = new SpatialFilterClass;

spatialFilter.Geometry = pMyPloygon;

spatialFilter.SpatialRel = esriSpatialRelContains;

spatialFilter.WhereClause =”Name=’ArcObjects’”;

IFeatureCursor fCursor = featureClass.Search (spatialFilter, true);

Accessing Records in a Cursor

I believe we have a good understanding on creating cursors, now let’s look at how we can access the cursor (records) returned from a table or FeatureClass.

When a cursor is created you also get a Pointer created, this pointer points to the first record in the cursor while the cursor is initialized. To keep moving to the next record you need to make a call to the NextRow (Table) or NextFeature (IFeatureClass) method. These two methods help you to move the pointer ahead from its current position in the cursor and thereby fetching that particular record information. Subsequent call to the NextRow or NextFeature methods will keep the pointer heading towards the end of the record set or the Cursor which will return null at once point.

IFeatureCursor featureCursor= featureClass.Search (queryFilter, true);

IFeature pFeature=featureCursor.NextFeature ();

While (pFeature! =null)

{

                // To-do any of your logic

                // this keeps the pointer moving head of the current position

                PFeaure= featureCursor.NextFeature ();

}

Reference

Understanding Cursors in ArcObjects by Eric Pimpler, President, GeoSpatial Training & Consulting, LLC