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
