ComObjArray

Creates a SafeArray for use with COM.

OutputVar := ComObjArray(VarType, Count1 , Count2, ... Count8)

Function Example: arr := ComObjArray(VT_BSTR := 8,10,10,10)

Parameters

OutputVar

The name of the variable in which to store the wrapper object containing the SafeArray.

VarType

The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.

See ComObjType for a list of possible values.

CountN

The size of each dimension. Arrays containing up to 8 dimensions are supported.

ArrayObj

A wrapper object containing the SafeArray.

Methods

Array wrapper objects support the following methods:

Array.MaxIndex(n): Returns the upper bound of the nth dimension. If n is omitted, it defaults to 1.

Array.MinIndex(n): Returns the lower bound of the nth dimension. If n is omitted, it defaults to 1.

Array.Clone(): Returns a copy of the array.

Array._NewEnum(): Not typically called by script; allows for-loops to be used with SafeArrays.

General Remarks

Array wrapper objects may also be returned by COM methods and ComObject. Scripts may determine if a value is an array as follows:

if ComObjType(obj) & 0x2000
    MsgBox % "Array subtype: " . ComObjType(obj) & 0xfff
else
    MsgBox Not an array.

Arrays with up to 8 dimensions are supported.

Since SafeArrays are not designed to support multiple references, when one SafeArray is assigned to an element of another SafeArray, a separate copy is created. However, this only occurs if the wrapper object has the F_OWNVALUE flag, which indicates it is responsible for destroying the array. This flag can be removed by using ComObjFlags.

When a function or method called by a COM client returns a SafeArray with the F_OWNVALUE flag, a copy is created and returned instead, as the original SafeArray is automatically destroyed.

Related

ComObject, ComObjType, ComObjValue, ComObjActive, ComObjFlags, Array Manipulation Functions (MSDN)

Examples

; Example #1: Simple usage.

arr := ComObjArray(VT_VARIANT:=12, 3)
arr[0] := "Auto"
arr[1] := "Hot"
arr[2] := "key"
Loop % arr.MaxIndex() + 1
   t .= arr[A_Index-1]
MsgBox % t

; Example #2: Multiple dimensions.

arr := ComObjArray(VT_VARIANT:=12, 3, 4)

; Get the number of dimensions:
dim := DllCall("oleaut32\SafeArrayGetDim", "ptr", ComObjValue(arr))

; Get the bounds of each dimension:
Loop dim
    dims .= arr.MinIndex(A_Index) " .. " arr.MaxIndex(A_Index) "`n"
MsgBox %dims%

; Simple usage:
Loop 3 {
    x := A_Index-1
    Loop 4 {
        y := A_Index-1
        arr[x, y] := x * y
    }
}
MsgBox % arr[2, 3]