In array mode (i.e. when the file parameter is empty) the array parameter supplies the contents to be loaded into the XTREE grid. It may be specified in the form of an array of fixed length strings, whose layout is determined by the coldef parameter, or as gridmap; see History below.
For the array case, you may either specify an explicit starting element (e.g. ARRAY(1)) or an unformatted variable under which the array is defined (ARRAYX in the example below). Note that you can use DIMX to dynamically allocate the array (either a simple array or a Dynamic Array of Structures), in which case you have to pass it to XTREE via the starting element.
MAP1 ARRAYX ! unformatted variable
MAP2 ARRAY(50),S,100
Each array element must have at least one trailing null byte. Note that by using the overlay feature, you could support several array layouts with the same XTREE statement, i.e.
MAP1 ARRAYX2,@ARRAYX ! overlay on ARRAYX above
MAP2 ARRAY2(10),S,60 ! array of ten sixty byte strings
MAP1 ARRAYX3,@ARRAYX ! yet another overlay
MAP2 ARRAY3(80),S,8 ! array of eighty 8 byte strings
Any text in an individual cell (in array mode) or line (in file mode) which follows a backslash ("\") will be hidden from view (unless the cformat \ switch is specified).
In single-selection file mode, the array parameter is interpreted as an ordinary string to return the text of the selected items (all columns, but with right-justified columns stripped of trailing blanks.) If the XTF_FILANS flag is set, then array is ignored on entry; otherwise it should contain the text of the item to initially select, as returned from the prior call. In CSV mode (see XTF2_CSV), although the return string will contain all the columns (comma-delimited), on entry only the first column is used for locating the initially selected item. If you need more precision than that, use the XTF_FILANS flag/method.
In multiple-selection file mode, the array parameter is ignored. The selection information is passed via the array of one byte flags in the answer parameter, just as in multiple-selection array mode.
For the gridmap case, specify the gridmap name with an empty pair of parens, e.g.
xcall XTREE, sr, sc, answer, $grid(), count, exitcode, er, ec, flags...
Either form of gridmap is accepted, although the handling is somewhat different for the two types. In the case of gridmap(int;varstr;varstr), the handling is analogous to CSV mode except without a file. This is more memory efficient but doesn't support AutoFilter.
In the case of gridmap(int;int;varstr), the grid data is expanded out to an array using column widths based on the actual maximum lengths of the data.
In either case, the operation is limited to display and select only; no editing. The application may specify an empty, partial (pseudo columns only), or full coldef. In the empty or partial case, the column headers are extracted from the gridmap—row 1 in the int;int;varstr case). If the app supplies a coldef with any real columns defined, the column names from the gridmap are ignored, and it is up to the app to make sure that the coldef supplied actually matches the layout of the data.
History
2023 September, A-Shell 6.5.1742: The tree data array argument may now be supplied in the form of a gridmap.
Subtopics
