Function Reference

_ArrayDisplay

Displays a 1D or 2D array as a ListView

#include <Array.au3>
_ArrayDisplay ( Const ByRef $aArray [, $sTitle = "ArrayDisplay" [, $sArrayRange = "" [, $iFlags = 0 [, $vUser_Separator = Default [, $sHeader = Default [, $iDesired_Colwidth = Default]]]]]] )

Parameters

$aArray Array to display
$sTitle [optional] Title for dialog. Default = "ArrayDisplay".
$sArrayRange [optional] Range of rows/columns to display. Default ("") = entire array. (See below for details)
$iFlags [optional] Determine UDF options. Add required values together
    $ARRAYDISPLAY_COLALIGNLEFT (0) = (default) Column text alignment - left
    $ARRAYDISPLAY_TRANSPOSE (1) = Transposes the array (2D only)
    $ARRAYDISPLAY_COLALIGNRIGHT (2) = Column text alignment - right
    $ARRAYDISPLAY_COLALIGNCENTER (4) = Column text alignment - center
    $ARRAYDISPLAY_VERBOSE (8) = Verbose - display MsgBox on error and splash screens during processing of large arrays
    16 = Deprecated
    32 = Deprecated
    $ARRAYDISPLAY_NOROW (64) = No 'Row' column displayed
    $ARRAYDISPLAY_CHECKERROR (128) = return if caller @error <> 0
$vUser_Separator [optional] Deprecated. Always use the Opt("GUIDataSeparatorChar").
$sHeader [optional] Column names in header (string of names separated by current separator character - usually "|"). Default see Remarks.
$iDesired_Colwidth [optional] If positive Max width to which a ListView column will expand to show content. Default = 350 pixels.
    If Negative all columns, except the first one set to 55, will be set to Abs($iDesired_Colwidth).

Return Value

Success: 1
Failure: 0 and @error flag set as follows:
@error: 1 - $aArray is not an array
2 - $aArray has too many dimensions (only 1D and 2D supported)
3 - @error is set when the function is called

Remarks

If the function is passed a non-array variable or an array of more than 2 dimensions the function returns an error and the script continues. If the "verbose" parameter is set in $iFlags a MsgBox will be displayed which offers the chance to exit the script immediately or to continue the script with the normal error return.

Although there are no limits on the size of the array to be displayed, there is a Windows control limitation which means that the ListView headers and columns do not align if there are more than approximately 600.

The $sArrayRange parameter syntax is as follows:

"7" Show rows 0-7 with all columns
"7:" Show rows 7-end with all columns
"|7" Show all rows with columns 0-7
"|7:" Show all rows with columns 7-end
"7|7" Show rows 0-7 with columns 0-7
"5:7" Show rows 5-7 with all columns
"|5:7" Show all rows with columns 5-7
"7|5:7" Show rows 0-7 with columns 5-7
"5:7|7" Show rows 5-7 with columns 0-7
"5:7|5:7" Show rows 5-7 with columns 5-7

Any column values are ignored for 1D arrays.

$sHeader names (separated by the current separator character) will be used for as many columns as there are names. If no, or not enough, custom names are specified then the default header of "Row|Col0" for 1D arrays or "Row|Col0|Col1|...|Col n" for 2D is substituted. If the array is displayed transposed, the header is ignored.
The variable $ARRAYDISPLAY_ROWPREFIX can be set to change the prefix of the row numbering (default: #).
To force number comparison on a specific column just terminate the corresponding name with $ARRAYDISPLAY_NUMERICSORT (default: *).

The array dimensions are displayed below the array. They are in red text if the array is transposed or only a range of elements is displayed - a tooltip displays the particular occurence(s).

If the "verbose" parameter is set in $iFlags a splash dialog is displayed during initial processing when the array to display has more than 10000 elements.

An array element containing another array or map is displayed as {Array} or {Map}.

When using $ARRAYDISPLAY_TRANSPOSE or $sArrayRange, a copy of the $aArray is created, so additional memory is used.

Click on a column header to sort it. On a big number of Row used, it can take some seconds. A ToolTip will be displayed on the loading warning that the sort can take some seconds.

Example

#include <Array.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()

        ; Create 1D array to display
        Local $aArray_1D[5] = ["Item 0", "Item 1", "A longer Item 2 to show column expansion", "Item 3", "Item 4"]

        _ArrayDisplay($aArray_1D, "1D display")

        ; Create 2D array to display
        Local $aArray_2D[20][15]
        For $i = 0 To UBound($aArray_2D) - 1
                For $j = 0 To UBound($aArray_2D, 2) - 1
                        $aArray_2D[$i][$j] = "Item " & StringFormat("%02i", $i) & StringFormat("%02i", $j)
                Next
        Next

        _ArrayDisplay($aArray_2D, "2D display")
        _ArrayDisplay($aArray_2D, "2D display transposed", Default, 1)

        ReDim $aArray_2D[20][10]
        $aArray_2D[5][5] = "A longer item to show column expansion"
        _ArrayDisplay($aArray_2D, "Expanded column - custom titles - no row/column", Default, 64, Default, "AA|BB|CC|DD|EE|FF|GG|HH|II|JJ")

        $aArray_2D[5][5] = "Column alignment set to right"
        _ArrayDisplay($aArray_2D, "Range set - right align", "3:7|4:9", 2, Default, "AA|BB|CC|DD|EE|FF")

        $aArray_2D[5][5] = "Column alignment set to left"
        Opt("GUIDataSeparatorChar", "!")
        _ArrayDisplay($aArray_2D, "! Header separator", "3:7|4:9", Default, Default, "AA!BB!CC!DD!EE!FF")

        ; Create non-array variable to force error - MsgBox displayed as $iFlags set
        Local $vVar = 0, $iRet, $iError
        $iRet = _ArrayDisplay($vVar, "No MsgBox on Error")
        $iError = @error
        MsgBox(0, "_ArrayDisplay() Error", "return without internal Msgbox $iret =" & $iRet & " @error=" & $iError)

        $iRet = _ArrayDisplay($vVar, "MsgBox on Error", Default, 8)
        $iError = @error
        MsgBox(0, "_ArrayDisplay() Error", "return internal Msgbox with no force Exit $iret =" & $iRet & " @error=" & $iError)

EndFunc    ;==>Example