IDLffShape::GetEntity

IDLffShape::GetEntity

The IDLffShape::GetEntity function method returns the entities you specify from a Shapefile.

Syntax

Result = Obj->[IDLffShape::]GetEntity([Index] [, /ALL] [, /ATTRIBUTES])

Return Value

Returns a type {IDL_SHAPE_ENTITY} structure array. For more information on the structure, see Entities.

Note

Since an entity structure contains IDL pointers, you must free all the pointers returned in these structures when the entity is no longer needed using the IDLffShape::DestroyEntity method.

Note

Since entities cannot be modified in a Shapefile, an entity is read directly from the Shapefile each time you use the IDLffShape::GetEntity method even if you have already read that entity. If you modify the structure array returned by this method for a given entity and then use IDLffShape::GetEntity on that same entity, the modified data will NOT be returned, the data that is actually written in the file is returned.

Arguments

Index

A scalar or array of longs specifying the entities for which you want to retrieve with 0 being the first entity in the Shapefile. If the ALL keyword is set, this argument is not required. If you do not specify any entities and the ALL keyword is not set, the first entity (0) is returned.

Keywords

ALL

Set this keyword to retrieve all entities from the Shapefile. If this keyword is set, the Index argument is not required.

ATTRIBUTES

Set this keyword to return the attributes in the entity structure. If not set, the ATTRIBUTES tag in the entity structure will be a null IDL pointer.

Examples

In the following example, all of the entities from the states.shp Shapefile are read:

PRO ex_shapefile 
 
; Open the states Shapefile in the examples directory. 
myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ 
   SUBDIR=['examples', 'data'])) 
 
; Get the number of entities so we can parse through them. 
myshape->IDLffShape::GetProperty, N_ENTITIES=num_ent 
 
; Read all the entities.  
FOR x=1, (num_ent-1) DO BEGIN 
   ;Read the entity x 
   ent = myshape->IDLffShape::GetEntity(x) 
   ;Clean-up of pointers 
   myshape->IDLffShape::DestroyEntity, ent 
ENDFOR 
 
; Close the Shapefile. 
OBJ_DESTROY, myshape 
 
END

Version History

Introduced: 5.4