Alter Object statement - MapBasic - 2023

Purpose

Modifies the shape, position, or graphical style of an object. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Alter Object obj
	{ Info object_info_code, new_info_value | 
		Geography object_geo_code , new_geo_value | 
		Node { 
			Add [ Position polygon_num, node_num ] ( x, y ) | 
			Set Position polygon_num, node_num ( x , y ) | 
			Remove Position polygon_num, node_num } } 

obj is an object variable.

object_info_code is an integer code relating to the ObjectInfo() function (e.g., OBJ_INFO_PEN).

new_info_value specifies the new object_info_code attribute to apply (e.g., a new Pen style).

object_geo_code is an integer code relating to the ObjectGeography() function (e.g., OBJ_GEO_POINTX).

new_geo_value specifies the new object_geo_code value to apply (e.g., the new x-coordinate).

polygon_num is a integer value (one or larger), identifying one polygon from a region object or one section from a polyline object.

node_num is a integer value (one or larger), identifying one node from a polyline or polygon.

x, y are x- and y-coordinates of a node.

Description

The Alter Object statement alters the shape, position, or graphical style of an object.

The effect of an Alter Object statement depends on whether the statement includes an Info clause, a Node clause, or a Geography clause. If the statement includes an Info clause, MapBasic alters the object's graphical style (e.g., the object's Pen and Brush styles). If the statement includes a Node clause, MapBasic adds, removes, or repositions a node (this applies only to polyline or region objects). If the statement includes a Geography clause, MapBasic alters a geographical attribute for objects other than polylines and regions (e.g., the x- or y-coordinate of a point object).

Info clause

By issuing an Alter Object statement with an Info clause, you can reset an object's style (e.g., the Pen or Brush). The Info clause lets you modify the same style attributes that you can query through the ObjectInfo() function.

For example, you can determine an object's current Brush style by calling the ObjectInfo() function:

Dim b_fillstyle As Brush
b_fillstyle = ObjectInfo(Selection.obj, OBJ_INFO_BRUSH)

Conversely, the following Alter Object statement allows you to reset the Brush style:

Alter Object obj_variable_name 
	Info OBJ_INFO_BRUSH, b_fillstyle

Note that you use the same code (e.g., OBJ_INFO_BRUSH) in both the ObjectInfo() function and the Alter Object statement.

The table below summarizes the values you can specify in the Info clause to perform various types of style alterations. Note that the obj_info_code values are defined in the standard MapBasic definitions file, MAPBASIC.DEF. Accordingly, your program should Include "MAPBASIC.DEF" if you intend to use the Alter Object...Info statement.

Geography clause

By issuing an Alter Object statement with a Geography clause, you can alter an object's geographical coordinates. The Geography clause applies to all object types except for polylines and regions. To alter the coordinates of a polyline or region object, use the Node clause (described below) instead of the Geography clause.

The Geography clause lets you modify the same attributes that you can query through the ObjectGeography() function. For example, you can obtain a line object's end coordinates by calling the ObjectGeography() function:

Dim o_cable As Object
Dim x, y As Float 
x = ObjectGeography(o_cable, OBJ_GEO_LINEENDX)
y = ObjectGeography(o_cable, OBJ_GEO_LINEENDY) 

Conversely, the following Alter Object statements let you alter the line object's end coordinates:

Alter Object o_cable 
	Geography OBJ_GEO_LINEENDX, x 
Alter Object o_cable
	Geography OBJ_GEO_LINEENDY, y 

The table below summarizes the values you can specify in the Geography clause in order to perform various types of geographic alterations. Note that the obj_geo_code values are defined in the standard MapBasic definitions file, MAPBASIC.DEF. Your program should Include "MAPBASIC.DEF" if you intend to use the Alter Object...Geography statement.

Node clause

By issuing an Alter Object statement with a Node clause, you can add, remove, or reposition nodes in a polyline or region object.

If the Node clause includes an Add sub-clause, the Alter Object statement adds a node to the object. If the Node clause includes a Remove sub-clause, the statement removes a node. If the Node clause includes a Set Position sub-clause, the statement repositions a node.

The Alter Object statement's Node clause is often used in conjunction with the Create Pline statement and the Create Region statement. Create statements allow you to create new polyline and region objects. However, Create statements are somewhat restrictive, because they force you to state at compile time the number of nodes that will comprise the object. In some situations, you may not know how many nodes should go into an object until run-time.

If your program will not know until run-time how many nodes should comprise an object, you can issue a Create Pline statement or a Create Region statement which creates an "empty" object (an object with zero nodes). Your program can then issue an appropriate number of Alter Object...Node Add statements, to add nodes as needed.

Within the Node clause, the Position sub-clause includes two parameters, polygon_num and node_num, that let you specify exactly which node you want to reposition or remove. The Position sub-clause is optional when you are adding a node. The polygon_num and node_num parameters should always be 1 (one) or greater.

The polygon_num parameter specifies which polygon in a multiple-polygon region (or which section in a multiple-section polyline) should be modified.

Region Centroids

The Centroid of a Region can be set by using the Alter Object command with the syntax noted below:

Alter Object Obj Geography OBJ_GEO_CENTROID, PointObj

Note that PointObj is a point object. This differs from other values input by Alter Object Geography, which are all scalars. A point is needed in this instance because we need two values which define a point. The Point that is input is checked to make sure it is a valid Centroid (for example, it is inside the region). If the Obj is not a region, or if PointObj is not a point object, or if the point is not a valid centroid, then an error is returned.

An easy way to center an X and Y value for a centroid is as follows:

Alter Object Obj Geography OBJ_GEO_CENTROID, CreatePoint(X, Y)

The user can also query the centroid by using the ObjectGeography() function as follows:

PointObj = ObjectGeography(Obj, OBJ_GEO_CENTROID)

There are other ways to get the Centroid, including the Centroid() function, CentroidX() function, and CentroidY() function.

OBJ_GEO_CENTROID is defined in MAPBASIC.DEF.

Multipoint Objects and Collections

The Alter Object statement supports the following object types.

• Multipoint: sets a Multipoint symbol as shown in the following:

	Alter Object obj_variable_mpoint 
		Info OBJ_INFO_SYMBOL, NewSymbol

• Collection: By issuing an Alter Object statement with an Info clause, you can reset collection parts (Region, Polyline or Multipoint) inside the collection object. The Info clause allows you to modify the same attributes that you can query through the ObjectInfo() function. For example, you can determine a collection object's region part by calling the ObjectInfo() function:

	Dim ObjRegion As Object
	ObjRegion = ObjectInfo(Selection.obj, OBJ_INFO_REGION)

Also, the following Alter Object statement allows you to reset the region part of a collection object:

	Alter Object obj_variable_name 
	Info OBJ_INFO_REGION, ObjRegion

The Alter Object statement inserts and deletes nodes to/from Multipoint objects.

	Alter Object obj Node statement

To insert nodes within a Multipoint object:

Dim mpoint_obj as object
Create Multipoint Into Variable mpoint_obj 0
Alter Object mpoint_obj Node Add (0,1)
Alter Object mpoint_obj Node Add (2,1)

To delete nodes from a Multipoint object:

Alter Object mpoint_obj Node Remove Position polygon_num, node_num

mpoint_obj is a Multipoint object variable.

polygon_num is ignored for Multipoint, it is advisable to set it to 1.

node_num is the number of a node to be removed.

To set nodes inside a Multipoint object:

Alter Object mpoint_obj Node Set Position polygon_num, node_num (x,y)

mpoint_obj is a Multipoint object variable.

polygon_num is ignored for Multipoint, it is advisable to set it to 1.

node_num is the number of a node to be changed.

x and y are the new coordinates of the node node_num.

Example

Dim myobj As Object, i As Integer
Create Region Into Variable myobj 0
For i = 1 to 10
	Alter Object myobj
		Node Add (Rnd(1) * 100, Rnd(1) * 100)
	Next 

See Also:

Create Pline statement, Create Region statement, Insert statement, ObjectGeography() function, ObjectInfo() function, Update statement