Function Reference


Displays a 1D or 2D array in a ListView to aid debugging

#include <Debug.au3>
_DebugArrayDisplay ( Const ByRef $aArray [, $sTitle = "DebugArray" [, $sArrayRange = "" [, $iFlags = 0 [, $vUser_Separator = Default [, $sHeader = Default [, $iMax_ColWidth = Default [, $hUser_Function = ""]]]]]]] )


$aArray Array to display
$sTitle [optional] Title for dialog. Default = "DebugArray".
$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
    $ARRAYDISPLAY_NOROW (64) = No 'Row' column displayed
$vUser_Separator [optional] Sets column display option when copying data to clipboard.
    Character = Delimiter between columns.
    Number = Fixed column width - longer items will be truncated.
    Default = Current separator character (usually "|").
$sHeader [optional] Column names in header (string of names separated by current separator character - usually "|"). Default see Remarks.
$iMax_Colwidth [optional] Max width to which a ListView column will expand to show content. Default = 350 pixels.
$hUser_Function [optional] A variable assigned to the user defined function to run. Default = none. See remarks.

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)


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 LitView 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 4 buttons at the bottom of the dialog have the following functions:
Copy Data & Hdr/Row Copy the array or the selected row(s) to the clipboard adding full header and row identification.
Copy Data Only Copy the array or the selected row(s) to the clipboard with no header or row identification.
Run User Func Run the user-defined function passed in $sUser_Function. This function is entirely separate from the UDF and must be created and coded by the user to accept 2 (and only 2) parameters which will be provided by the UDF itself: the full array being displayed and a 1D array holding the selected rows indices with a count in the [0] element. These parameters can then be used inside the user function as required. The button is not displayed if no function is specified.
Exit script Exit the script immediately.

The array dimensions are displayed at lower left. 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. A similar dialog is displayed when the "Copy Data" buttons are used on a 10000+ element display - if this is likely to occur consideration should be given to using a "User Function" to store the array for later processing.

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

Clicking on a column header sort it.


#include <Debug.au3>
#include <MsgBoxConstants.au3>


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"]

    _DebugArrayDisplay($aArray_1D, "1D display")

    ; Create 2D array to display
    Local $aArray_2D[25][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)

    _DebugArrayDisplay($aArray_2D, "2D display")

    $aArray_2D[5][5] = "A longer item to show column expansion"
    _DebugArrayDisplay($aArray_2D, "Expanded column - custom titles - no buttons or 'Row' column", Default, 32 + 64, Default, "AA|BB|CC|DD|EE|FF|GG|HH|II|JJ")

    ; Assign the user function to a variable to pass as a parameter
    Local $hUserFunction = _UserFunc

    $aArray_2D[5][5] = "Column alignment set to right"
    _DebugArrayDisplay($aArray_2D, "Range set - right align - copy column width - user function", "3:7|4:9", 2, 15, "AA|BB|CC|DD|EE|FF", Default, $hUserFunction)
    _DebugArrayDisplay($aArray_2D, "Range set - transposed", "3:7|4:9", 1, Default, "AA|BB|CC|DD|EE|FF") ; Note no col names as transposed

    $aArray_2D[5][5] = "Column alignment set to left"
    Opt("GUIDataSeparatorChar", "!")
    _DebugArrayDisplay($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 = _DebugArrayDisplay($vVar, "No MsgBox on Error")
    $iError = @error
    MsgBox(0, "_DebugArrayDisplay() Error", "return without internal Msgbox $iret =" & $iRet & " @error=" & $iError)

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

EndFunc    ;==>Example

; Note that the user function MUST have TWO parameters even if you do not intend to use both of them
Func _UserFunc($aArray_2D, $aSelected)

    ; But if a parameter is not used do this to prevent an Au3Check warning
    #forceref $aArray_2D

    _DebugArrayDisplay($aSelected, "Selected cols")

EndFunc    ;==>_UserFunc