Understanding Cursors in ArcObjects (Understanding the Cursor in ArcObject!

Download an English attachment: Cursor in ArcObject

Chinese Translation:

Cursor in ArcObject

This article is an article in the first installment of ArcUser 2006, introducing
The Cursor object in Arcobjects introduces how foreigners know Cursor.
. The content of this article is simple and easy to understand.

Author: Eric Pimpler, President, GeoSpatial Training & Consulting, LLC
Translation: Hao

What will happen to your mind when you hear the term cursor? Where does it show on the screen where it will start the next input activity symbol (that is, the mouse on the screen )? In AO, cursor represents a subset of records obtained by using attribute or spatial queries for element classes or tables. This subset is saved in memory rather than visualized. Do not confuse it with the selection set. The selection set object is used In ArcMap to display the selected elements or Row Records. cursor is not used for the purpose of display.

For example, a query cursor can be used to program and generate a rental table that contains all the plains that have suffered floods in 100 and whose property value exceeds $0.1 million. AO provides the ability to obtain cursor from a geographical dataset (element class) and a common data table. These cursor objects allow you to manage record sets in a single object. This article describes these AO objects, methods, and attributes, which are used to operate cursor objects.

Cursor VS FeatureCursor
The cursor used by AO to manage the record subset depends on the data source. Cursor and featurecursor are very similar objects, except that cursor is used to operate tables, while the latter is used to operate element classes. In other words, cursor is a class structure created for a specific purpose-a subset of records stored in a traditional database table, the subset of featurecursor records is stored in the shapefile, personal geodatabase, or enterprise-level geodatabase.

Cursors type
There are three types of Cursor in the cursor and FeatureCursor groups. The most common one is Search Cursor, which is used for query operations to return a subset of records that meet the query conditions. Search Cursor is a read-only cursor that you can use to traverse the obtained information.

You cannot use this cursor to insert, update, or delete records in a table. Insert Cursor is used to Insert a new record to a table, while Update Cursor is used to Update or delete the record. The records returned by these two cursor can be limited by an attribute or space query.

It is very important to generate an appropriate type of cursor for your operations. For example, do not generate a search cursor if you try to update records in a table. As mentioned above, search cursor is a read-only structure that prevents you from updating data. In this article, we will reveal the details of each cursor.

Cursor Class

As mentioned above, the cursor class is used to generate an object for interaction with database tables. In AO, the cursor class is a non-instantiated object, which means that you must use another object to obtain an instance of the cursor class. In AO, the table class is used to generate an instance of the cursor class. The table class contains three methods to generate an instance of the cursor class, the returned cursor type depends on the method called by the programmer. Figure 1 shows the OMD of Table Class in AO. The ITable interface has three methods to return specific types of cursor. The Search, Insert, and Update Methods of the ITable interface can be used to return cursor instances. The names of these methods correspond to the returned cursor type.

After one of these methods is called, AO returns an ICursor instance. Fig2 shows the OMD of a Cursor class. Search, Insert, and Update can both return an ICursor instance. ICursor has an attribute Fields and many methods that can operate on a subset of records, but whether these methods are available depends on the cursor type you are using. For example, if you generate a search cursor, an error is returned when you call the InsertRow and UpdateRow methods.

FeatureCursor Class

The FeatureCursor class is very similar to the Cursor class. The difference is that the former is to operate on geographical datasets, while the latter is to operate on traditional database tables. The geographic dataset of shapefile and geodatabase is represented as an AO element class in AO. Similar to the cursor class, the FeatureCursor class is also a non-instantiated object generated by the FeatureClass object method. Similar to the ITable interface, the IFeatureClass interface also contains the Search, Insert, and Update methods used to return an IFeatureCursor instance.

After one of the methods is called, an IFeatureCursor instance will be returned. IFeatureCursor's attributes and methods are slightly different from ICursor's names, however, its functions differ greatly, for example, InsertFeature VS InsertRow.

Use attributes and space constraints

Look at the OMD diagram of FeatureClass and Table to find the Search, Insert, and Update methods. Note that each method can be used to return a cursor. The cursor contains a parameter, which is an IQueryFilter instance. Note: The IQueryFilter parameter indicates that IQueryFilter is an object that can be generated in the memory to limit the subset of records.

For example, if you are querying a parcel database, you may need to limit the returned parcels results so that their values are greater than $0.1 million. You can use the IQueryFilter interface. In addition, if you use a FeatureClass object, you can also use the ISpatialFilter interface to generate SpatialFilter. In this way, you can return all the parcel (query using space) in the flood area, and the value is more than $0.1 million (query using properties ). Remember that spatial queries can only be used in element classes. If you use spatial queries on a database table, an error is returned because no geographic object can be used as a filter. Let's take a look at the details of the QueryFilter and SpatialFilter classes.

QueryFilter

Before generating a cursor or featurecursor from a dataset, you can define a QueryFilter to restrict the number of returned records. QueryFilter is a generated class (component class). You can use the NEW keyword in VBA to generate an instance object of this type. You can use the IQueryFilter interface to process the QueryFilter class and define an attribute constraint. The WhereClause attribute is used to limit this query. The following code is an example:
Dim pQueryFilter as IQueryFilter
Set pQueryFilter = New QueryFilter
PQueryFilter. WhereClause = "Prop_Val> = 100000"

SpatialFilter

SpatialFilter can be used to generate a subset of records Based on Spatial Constraints. It can be used in FeatureClass, but cannot be used in Table. SpatialFilter is a component class. You can use the New keyword to generate an instance of a class. SpatialFilter uses the Geometry attribute and SpatialRel attribute to set query constraints. The Geometry attribute is used to set a specific geographical element, while SpatialRel is used to preset its spatial relationship, such as intersection, superposition, or adjacent.

Since SpatialFilter is a QueryFilter, it can also access all its attributes and methods. Therefore, you can use the WhereClause attribute of IQueryFilter to bind space and attribute restrictions. The following is an example of joint use:
Dim pSpatialFilter As ISpatialFilter
Set pSpatialFilter = New SpatialFilter
Set pSpatialFilter. Geometry = pFloodPolygon
PSpatialFilter. SpatialRel = esriSpatialRelContains
PSpatialFilter. WhereClause = "prop_val> 100000"
Set pFCursor = pCustomerLayer. Search (pSpatialFilter, True)

Use Cursor to access records

Now you have a good understanding of the general mechanism for generating cursor. Let's see how to use a cursor to access the returned records. Remember, cursor is a set of records from only one table or element class in memory.

When a cursor is generated for the first time, an associated pointer is also generated. You can use a cursor to access a row of records at a time. This pointer helps you track which row records are currently being accessed. With initialization, the pointer can actually point to the first record. To obtain the first record through cursor, you must call the NextRow or NextFeature method. These two methods point to the next record of cursor. But when it is called for the first time, it actually points to the first record. Each time these methods are called, they point to the next record.

In some ways, you can reach the end position of records that can be recorded in the cursor. For example, using NewRow or NewFeature will return a Nothing object, indicating that it is already at the end of the cursor. The cursor in AO is a one-way moving object, which does not allow you to return the previous position. Once you have accessed a record, you cannot return it again.

Conclusion

The AO cursor structure allows programmers to query, insert, update, and delete element classes and table records. These cursor structured poems that are easy to generate and have strong applicability exist in a set of records in the memory. They can use QueryFilter or SpatialFilter to set constraints. Once generated, these cursor structures provide a structure that is easy to access and can only be moved forward to access the content of a single record.