AddArea()
Summary
Adds an area feature to an area layer.
Changes
Support for non-topological areas added in Version 6.0/2012.
Syntax
new_id = AddArea(int ID, array poly, array options)
| Argument | Contents |
|---|---|
| ID | The ID of the new area, or null to generate an ID automatically |
| poly | A three-element array, as indicated below: |
| Element | Type | Contents |
|---|---|---|
| n_polygons | Integer | Number of polygons that describe the area |
| n_points | Array | The number of points in each polygon |
| coords | Array | The complete array of coordinates that define the area |
| Option | Type | Contents |
|---|---|---|
| Progress Message | String | A progress message. |
| Reason | String | If provided, a record will be added to the database's log file, with this used as the Reason column. If it's not provided, no entry will be added, even if the other options are present. |
| Comment | String | Text for the comment field of the log file. |
| User | String | User name for the log file. |
Returns
The integer ID of the new area.
Notes
-
The current layer can be a topological or non-topological area layer in a standard geographic file, which can be determined with GetDBTopology(), or an external area layer, such as Oracle or SQL Spatial.
-
For a new topological area that does not touch existing areas, any outermost polygons (including the main polygon and any islands) should have their coordinates be clockwise. Inner polygons, such as lakes and other holes in an outermost polygon, should have their coordinates be counterclockwise. The nesting continues with islands in those lakes being clockwise, etc.
-
For a new topological area that does touch existing areas, polygon overlay is invoked and the behavior is different: if the polygon is counterclockwise, only the portions of the area that intersect with existing areas get added. If it is clockwise, the entire area gets added.
-
You can use IsClockwise() to determine the orientation of a polygon.
-
Non-topological areas are added as is, without running polygon overlay.
Example
// Add an area to a parcel file
SetLayer("Parcels")
on escape do Return() end
coords = ClickShape()
poly = {1, {coords.length}, coords}
new_id = AddArea(, poly, )
ShowMessage("The new area feature has an ID of " + String(new_id))Error Codes
| Error Type | Meaning |
|---|---|
| Error | The current layer is not an area layer, or is not from a standard geographic file; or ID is already in use |
See Also
| Function | Summary |
|---|---|
| DeleteArea() | Deletes an area feature from an area layer |
| GetArea() | Get the coordinates that describe an area feature |
| GetDBTopology() | Determines whether a standard geographic file is topological |
| IsClockwise() | Checks to see if an array of coordinates is clockwise or not |