DoDialogGetListItemsEx

Prototype

Matrix DoDialogGetListItemsEx( Matrix mSelections, String sTitle, String sMessage, Matrix mItems, Matrix mColumnHeaders, Matrix mColumnWidths, Matrix mInitialSelections, int nMinNumSelections, int nMaxNumSelections )

Return Value

The return value is 1 on success or 0 on failure. If the user clicks Cancel or closes the dialog box, the return value is 0.

Parameters

Matrix mSelections
Upon successful return, mSelections is a column vector containing the 1-based indices of the rows in mItems that were selected by the user. If the user made no selection, the mSelections matrix is undefined (i.e. nrow(mSelections) = 0 and ncol(mSelections) = 0 and type(mSelections) = 'U').

String sTitle
The title of the dialog box.

String sMessage
A message that appears at the top of the dialog box.

Matrix mItems
A character matrix containing the items to be displayed in the dialog box. Each row in mItems is treated as a single selectable item. If mItems contains multiple columns, each item is formatted into multiple columns in the dialog box. In this case, the mColumnHeaders parameter must specify the text for each column header.

Matrix mColumnHeaders
A character vector specifying the text for each column header. The string mColumnHeaders[i] specifies the heading text for column mItems[,i]. If mItems contains only one column, you are not required to have a column header. In this case, pass the numeric scalar value zero for the mColumnHeaders parameter.

Matrix mColumnWidths
A numeric vector specifying the width of each column in units of characters. A value of 8 implies the column should be wide enough to accommodate eight characters of average width. The value mColumnWidths[i] specifies the width of column mItems[,i]. If mColumnWidths[i] is 0, the column is sized automatically to accommodate the widest string. If mColumnWidths[i] is -1, the column is sized automatically to accommodate the widest string and the column is aligned right flush. If mColumnWidths[i] is less than -1, the column's width is -mColumnWidths[i] and the column is aligned right flush. If you want all the columns to be sized automatically, pass the numeric scalar value zero for the mColumnWidths parameter.

Matrix mInitialSelections
A numeric vector specifying the 1-based indices of the rows in mItems that should be preselected when the dialog box appears. If you do not want any items to be preselected, set this parameter to zero.

int nMinNumSelections
A scalar value specifying the minimum number of selections the user must make. The value of nMinNumSelections must be greater than or equal to zero.

int nMaxNumSelections
A scalar value specifying the maximum number of selections the user may make. If nMaxNumSelections is greater than the number of rows in mItems, the user may select all the items.

Remarks

This module is an extended version of the DoDialogGetListItems module.

This module displays a dialog box that enables the user to select items from a list.

The dialog box's OK button is only enabled when the user has made between nMinNumSelections and nMaxNumSelections selections.

The dialog box enables you to sort the items by a particular column by clicking the column's header. The first time you click a column's header, the items are sorted in ascending order by that column. The second time you click a column's header, the items are sorted in descending order by that column. Sorting the items does not affect the indices returned in the mSelections matrix. The indices in mSelections are always relative to the original ordering.

Two situations in which you would want to set the width of a column explicitly are:

• The text within the column consists of single character strings such as "M" for male and "F" for female. In this case, the automatic sizing logic would cause the column heading "Sex" to be clipped.
• You want all the columns to be visible and you don't care if some of the text strings are clipped.

Example

declare DataObject dobj;
dobj = DataObject.CreateFromFile( "baseball" );

numvar = dobj.GetNumVar();
do i = 1 to numvar;
    varnames = varnames // dobj.GetVarName( i );
    varlabels = varlabels // dobj.GetVarLabel( varnames[i] );
    if dobj.IsNumeric( varnames[i] ) then
        vartypes = vartypes // "Numeric";
    else
        vartypes = vartypes // "Character";
    if dobj.IsNominal( varnames[i] ) then
        varml = varml // "Nominal";
    else
        varml = varml // "Interval";
    end;

ok = DoDialogGetListItemsEx(
        selections,
        "Select Variables",
        "Please select zero or more variables.",
        varnames || varlabels || vartypes || varml,
        { "Name", "Label", "Type", "Measure Level" },
        { -1, -1, -1, 10 },
        { 3 5 },
        0,
        numvar );
if ok then
    if type(selections) = 'U' then
        print "No selection";
    else
        print (varnames[selections]);
else
    print "Function failed";

See Also

DoDialogGetListItem
DoDialogGetListItems