Purpose
Creates a region object. You can issue this statement from the MapBasic window in MapInfo Pro.
Syntax
Create Region
[ Into { Window window_id | Variable var_name } ]
num_polygons
[ num_points1 ( x1, y1 ) ( x2, y2 ) [ ... ] ]
[ num_points2 ( x1, y1 ) ( x2, y2 ) [ ... ] ... ]
[ Pen ... ]
[ Brush ... ]
[ Center ( center_x, center_y ) ]
[ Priority n ] [ Name framename ]window_id is a window identifier.
var_name is the name of an existing object variable.
num_polygons specifies the number of polygons that will make up the region (zero or more).
num_points1 specifies the number of nodes in the region's first polygon.
num_points2 specifies the number of nodes in the region's second polygon, etc.
Each x, y pair specifies one node of a polygon.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.
center_x is the x-coordinate of the object centroid.
center_y is the y-coordinate of the object centroid.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.
Description
The Create Region statement creates a region object.
The num_polygons parameter specifies the number of polygons which comprise the region object. If you specify a num_polygons parameter with a value of zero, the object will be created as an empty region (a region with no polygons). You can then use the Alter Object statement to add details to the region.
Depending on your application, you may need to create a region object in two steps, first using Create Region to create an object with no polygons, and then using the Alter Object statement to add details to the region object. If your application needs to create region objects, but it will not be known until run-time how many nodes or how many polygons the regions will contain, you must use the Alter Object statement to add the variable numbers of nodes. See Alter Object statement for more information.
If the statement includes the optional Into Variable clause, the object will be stored in the specified object variable. If the Into clause specifies a window identifier, the object will be stored in the appropriate place in the window (for example, in the editable layer of a Map window). If the Into clause is not provided, MapBasic will attempt to store the object in the topmost window; if objects may not be stored in the topmost window (for example, if the topmost window is a grapher) no object will be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default, MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys statement can re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate system is independent of the coordinate system of any Map window. Objects created on a Layout window, however, are specified in paper units: each x-coordinate represents a distance from the left edge of the page, while each y-coordinate represents the distance from the top edge of the page. For details about paper units, see Set Paper Units statement. By default, MapBasic uses inches as the default paper unit. To use a different paper unit, To use a different paper unit, call the Set Paper Units statement.
The optional Pen clause specifies a line style used to draw the outline of the object; see Pen clause for more details. If no Pen clause is specified, the Create Region statement uses the current line style (the style which appears in the Line Style dialog box). Similarly, the optional Brush clause specifies a fill style; see Brush clause for more details.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order of the newly created object frame on the Layout window.
The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is written to the workspace (WOR) file and the workspace version updates to 1500.
A single-polygon region can contain up to 134,217,724 nodes. There can be a maximum of 20,648,881 polygons per region (multipolygon region or collection).
Example
Dim obj_region As Object
Dim x(100), y(100) As Float
Dim i, node_count As Integer
' If you store a set of coordinates in the
' x() and y() arrays, the following statements
' will create a region object that has a node
' at each x,y location:
' First, create an empty region object
Create Region Into Variable obj_region 0
' Now add nodes to populate the object:
For i = 1 to node_count
Alter Object obj_region Node Add ( x(i), y(i) )
Next
' Now store the object in the Sites table:
Insert Into Sites (Object) Values (obj_region)See Also:
Alter Object statement, Brush clause, Insert statement, Pen clause, Update statement