A-Shell Consolidated Reference

XTREE supports item drag-drop, within a single XTREE control, as a means of allowing the user to re-order the rows and to communicate the new order back to the application. For drag/drop between XTREEs, see XTF2_DRAGDROP2. For example, you may want to present a list of fields available for export and allow the user to determine the output order by rearranging the list using drag/drop. Or you may want to load up an XTREE with a list of all of your illegally downloaded MP3 tunes and use the drag/drop feature to create ordered play lists.

To enable the feature, specify the XTF_DRAGDROP bit in the flags parameter, and insert two fields at the start of the answer array, along the lines of how you would set up the answer array for editable cells. The first field is a four-character string to return the original row number for the given display row, and the second field is a one-character item selection flag, just as you would have for multi-selection.

For example:

MAP1 ANSWERX

   MAP2 ANSARY(MAX_ROWS)

      MAP3 ORG'ROW,S,4    ! original row number of this display row

      MAP3 SELECTION,S,1  ! selection flags

      MAP3 CB,S,1         ! a checkbox column

      MAP3 EDATA,S,8      ! a 8 character editable column

      <etc>

 

Note that the ORG'ROW field must be first, followed by the SELECTION field, followed by any editable checkboxes, followed by any other editable cells. In the example above, the ORG'ROW and SELECTION fields would be mandatory while the CB and EDATA fields would only apply if you happened to have one editable checkbox column and one editable text column.)

The SELECTION field is treated just as it would be when multi-select is enabled (i.e. SELECTION(I)="1" if item I is selected, or "0" if not.) Note that the presence of a SELECTION array usually indicates that multiple selection is supported, but in this case it does not necessarily imply that. In fact, the drag-drop operation currently only works for one row at a time, although you can still allow multi-selection for reasons independent of drag-drop. In normal (single selection) case, all of the SELECTION() entries will be "0" except for the one selected item.)

The ORG'ROW field is formatted as a decimal number of up to 4 digits with leading spaces. This imposes a maximum of 9999 rows when using drag-drop, which is a reasonable limit since drag-drop becomes somewhat impractical anyway when you have more than several dozen items.

Since the array used to load items is not returned by XTREE, and all other related return data specifying row numbers is coded relative to the original order of the rows (as opposed to the last display order), the ORG'ROW() array provides the only way for the app to determine what the last display order was. This might even motivate you to enable drag/drop just for the purpose of being able to easily process the array data according to the way the user sorted it.

The ORG'ROW() array is ordered according to the display order of the rows, unlike all the other arrays within the answer array, which are ordered according to the original array order. As an example of using ORG'ROW(), the following code would print the original array data according to the display order (resulting from drag/drop and/or column sorting):

FOR I = 1 TO MAX_ROWS

    J = VAL(ORG'ROW(I))

    IF (J > 0) PRINT ARRAY(J)

NEXT I

 

See Also