ArrayRectangular Method (ActiveX)

Creates a 2D or 3D rectangular array of objects.

Supported platforms: Windows only

Signature

VBA:

RetVal = object.ArrayRectangular(NumberOfRows, NumberOfColumns, NumberOfLevels, DistBetweenRows, DistBetweenColumns, DistBetweenLevels)

object

Type: All drawing objects

The objects this method applies to.

NumberOfRows

Access: Input-only

Type: Long

The number of rows in the rectangular array. This must be a positive number. If this number is 1, then NumberOfColumns must be greater than 1.

NumberOfColumns

Access: Input-only

Type: Long

The number of columns in the rectangular array. This must be a positive number. If this number is 1, then NumberOfRows must be greater than 1.

NumberOfLevels

Access: Input-only

Type: Long

The number of levels in a 3D array.

DistBetweenRows

Access: Input-only

Type: Double

The distance between the rows. If the distance between rows is a positive number, rows are added upward from the base entity. If the distance is a negative number, rows are added downward.

DistBetweenColumns

Access: Input-only

Type: Double

The distance between the columns. If the distance between columns is a positive number, columns are added to the right of the base entity. If the distance is a negative number, columns are added to the left.

DistBetweenLevels

Access: Input-only

Type: Double

The distance between the array levels. If the distance between levels is a positive number, levels are added in the positive direction from the base entity. If the distance is a negative number, levels are added in the negative direction.

Return Value (RetVal)

Type: Variant (array of objects)

The array of newly created objects.

Remarks

For a 2D array, specify the NumberOfRows, NumberOfColumns, DistBetweenRow, and DistBetweenColumns. For creating a 3D array, specify the NumberOfLevels and DistBetweenLevels as well.

A rectangular array is constructed by replicating the object in the selection set the appropriate number of times. If you define one row, you must specify more than one column and vice versa.

The object in the selection set is assumed to be in the lower left-hand corner, and the array is generated up and to the right. If the distance between rows is a negative number, rows are added downward. If the distance between columns is a negative number, the columns are added to the left.

AutoCAD builds the rectangular array along a baseline defined by the current snap rotation angle. This angle is zero by default, so the rows and columns of a rectangular array are orthogonal with respect to the X and Y drawing axes. You can change this angle and create a rotated array by setting the snap rotation angle to a nonzero value. To do this, use the SnapRotationAngle property.

Rectangular array with NumberOfRows = 4, NumberOfColumns = 3, DistBetweenRows = a, DistBetweenColumns = b. The base entity is represented in blue.

Note: You cannot execute this method while simultaneously iterating through a collection. An iteration will open the work space for a read-only operation, while this method attempts to perform a read-write operation. Complete any iteration before you call this method.

AttributeReference: You should not attempt to use this method on AttributeReference objects. AttributeReference objects inherit this method because they are one of the drawing objects, however, it is not feasible to perform this operation on an attribute reference.

Examples

VBA:

Sub Example_ArrayRectangular()
    ' This example creates a circle and then performs
    ' a rectangular array on that circle.
    
    ' Create the circle
    Dim circleObj As AcadCircle
    Dim center(0 To 2) As Double
    Dim radius As Double
    center(0) = 2#: center(1) = 2#: center(2) = 0#
    radius = 0.5
    Set circleObj = ThisDrawing.ModelSpace.AddCircle(center, radius)
    ThisDrawing.Application.ZoomAll
    MsgBox "Perform the rectangular array on the circle.", , "ArrayRectangular Example"
    
    ' Define the rectangular array
    Dim numberOfRows As Long
    Dim numberOfColumns As Long
    Dim numberOfLevels As Long
    Dim distanceBwtnRows As Double
    Dim distanceBwtnColumns As Double
    Dim distanceBwtnLevels As Double
    numberOfRows = 5
    numberOfColumns = 5
    numberOfLevels = 2
    distanceBwtnRows = 1
    distanceBwtnColumns = 1
    distanceBwtnLevels = 1
    
    ' Create the array of objects
    Dim retObj As Variant
    retObj = circleObj.ArrayRectangular(numberOfRows, numberOfColumns, numberOfLevels, distanceBwtnRows, distanceBwtnColumns, distanceBwtnLevels)
    
    ZoomAll
    MsgBox "Rectangular array completed.", , "ArrayRectangular Example"
    
End Sub

Visual LISP:

(vl-load-com)
(defun c:Example_ArrayRectangular()
    ;; This example creates a circle and then performs
    ;; a rectangular array on that circle.
    (setq acadObj (vlax-get-acad-object))
    (setq doc (vla-get-ActiveDocument acadObj))

    ;; Create the circle
    (setq center (vlax-3d-point 2 2 0)  
          radius 0.5)

    (setq modelSpace (vla-get-ModelSpace doc))  
    (setq circleObj (vla-AddCircle modelSpace center radius))
    (vla-ZoomAll acadObj)

    (alert "Perform the rectangular array on the circle.")

    ;; Define the rectangular array
    (setq numberOfRows 5
          numberOfColumns 5
          numberOfLevels 2
          distanceBwtnRows 1.0
          distanceBwtnColumns 1.0
          distanceBwtnLevels 1.0)

    ;; Create the array of objects
    (setq retObj (vla-ArrayRectangular circleObj numberOfRows numberOfColumns numberOfLevels
		                                 distanceBwtnRows distanceBwtnColumns distanceBwtnLevels))

    (vla-ZoomAll acadObj)
    (alert "Rectangular array completed.")
)