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