CATDlgMultiList

3D PLM Enterprise Architecture	User Interface - Dialogs	CATDlgMultiList Select one or several compound items in a list
Quick Reference

CATDialog
  |
  +---CATDlgControl
        |
        +---CATDlgMultiList

The Multiple List
	The multiple list allows the end user to select one or several compound items among a discrete list of predefined compound items. The values are generally character strings. Scrollbars are added if the list is longer or wider than the list display area. The selected value(s) is (are) highlighted. The end user cannot enter values and can only select among those proposed.

Use multiple list whenever you propose to the end user to select compound items from a predefined list.

Styles
Name	Description
default	A single compound item can be selected.
CATDlgLstMultisel	Several compound items can be selected using the Shift and Ctrl keys.

[Top]

Events
Notification	Method	Sent when
CATDlgListSelectNotification	`GetListSelectNotification`	Whenever a line is selected.
CATDlgListActivateNotification	`GetListActivateNotification`	Whenever a line is double clicked.
CATDlgListColumnActivateNotification	`GetListColumnActivateNotification`	Whenever a column is double clicked.
CATDlgListCellModifyNotification	`GetListCellModifyNotification`	Whenever a cell is modified.

[Top]

Programmer's Guide

The multiple list is dedicated to selection.

[Top]

Constructing a Multiple List

These following kinds of multiple list can be constructed.

default	_pMultiList = new CATDlgMultiList (iParent, iName);
Multiselection	_pMMultiList = new CATDlgMultiList (iParent, iName, CATDlgListMultisel);

[Top]

Managing the Line Content

You can do the following to manage the lines displayed in a multiple list:

get the number of lines in the list with the GetLineCount method:
int NumberOfLines; NumberOfLines = _pMultiList->GetLineCount();

get the number of columns in the list with the GetColumnCount method:

int NumberOfColumns;
NumberOfColumns = _pMultiList->GetColumnCount ();

set the column titles with the SetColumnTitle method:

int iNumberOfColumns = 5;
CATUnicodeString _iColumnTitles[5];
ColumnTitles[0] = ...
...
_pMultiList->SetColumnTitles(iNumberOfColumns,_iColumnTitles);

get and set or modify the contents of a given cell with the methods GetColumnItem, SetColumnItem, and SetColumnItems:

get the contents of a cell

CATUnicodeString oCellContents;
int iRowNumber = 3;
int iColumnNumber = 2;
_pMultiList->GetColumnItem(iColumnNumber,
                           oCellContents,
                           iRowNumber);
...

and modify it with another contents

CATUnicodeString iCellContents;
iCellContents = ...
int RowIndex; // index of the updated row
RowIndex = _pMultiList->SetColumnItem(iColumnNumber,
                                      iCellContents,
                                      iRowNumber,
                                      CATDlgDataModify);

Two modes are available: CATDlgDataAdd to add a row and set the contents of its iColumnNumberth cell, which is the default, and CATDlgDataModify to modify the iColumnNumberth cell contents in the iRowNumberth existing row. If iRowNumber is omitted or set to -1, the row is appended to the list. The returned value is the number of the added or modified row. You can also set or modify a group of contiguous cells in the same column:

modify 5 cells in column 2 starting from row 3

CATUnicodeString _iCellContents[5]
_iCellContents[0] = ...
...
int iSize = 5
int iRowNumber =2;
int iRowNumber = 3;
int FirstRowIndex;
FirstRowIndex = _pMultiList->SetColumnItems(iColumnNumber,
                                             _iCellContents,
                                             iSize,
                                             iRowNumber,
                                             CATDlgDataModify);

The value returned is the index of the first row modified or added. If iRowNumber is omitted or set to -1, the rows are appended to the list.

reorder columns with the ReorderColumns method:

int _iNewNumberArray [5] = { 5, 4, 3, 2, 1 };
int iArraySize = 5;
int iFirstColumn = 1;
_pMultiList->ReorderColumns(_iNewNumberArray,
                             iArraySize,
                             iFirstColumn);

This example inverts the five first columns.

delete one or several rows with the ClearLine:method:

delete row 5	int iRowNumber = 5; _pMultiList->ClearLine(iRowNumber);
delete rows 1,3,6	int iRowNum[3] = { 1,3,6 }; int iRowNumSize=3; _pMultiList->ClearLine(iRowNum, iRowNumSize);
delete all rows	_pMultiList->ClearLine();

[Top]

Managing the Line Display

You can manage the line display with the following methods:

get or set the overall visible text width the methods SetVisibleTextWidth and GetVisibleTextWidth:

set number of visible char	int NumberOfVisibleChar = 20; _pMultiList->SetVisibleTextWidth(NumberOfVisibleChar);
get number of visible char	... NumberOfVisibleChar = _pMultiList->GetVisibleTextWidth();

The value returned by the method GetVisibleTextWidth makes sense only if it has been set by the method SetVisibleTextWidth. The method SetVisibleTextWidth is taken into account only if the method SetVisibleColumnCount is not used.

get or set the width of a given column with the methods Get-ColumnTextWidth and SetColumnTextWidth:

get visible column width	int ColumnTextWidth; ColumnTextWidth = _pMultiList->GetColumnTextWidth(); ...
set visible column width	ColumnTextWidth = 10; _pMultiList->GetColumnTextWidth(ColumnTextWidth)

get or set the number of visible rows with the methods GetVisibleLineCount and SetVisibleLineCount:

get the number of visible rows	int NumberOfVisibleRows; NumberOfVisibleRows = _pMultiList->GetVisibleLineCount(); ...
set the number of visible rows	NumberOfVisibleRows = 10; _pMultiList->SetVisibleLineCount(NumberOfVisibleRows);

get or set the number of visible columns with the methods GetVisibleColumnCount and SetVisibleColumnCount:

get 1st line position	int NumberOfVisibleColumns; NumberOfVisibleColumns = _pMultiList->GetVisibleColumnCount();
set number of visible columns	... NumberOfVisibleColumns = 5; _pMultiList->SetVisibleColumnCount(NumberOfVisibleColumns);

get or set the position of the first visible row with the methods GetFirstLine and SetFirstLine:

get 1st visible row position	int FirstRow; FirstRow = _pMultiList->GetFirstLine();
set 1st visible row position	... FirstRow = 3; _pMultiList->SetFirstLine(FirstRow);

get or set column visibility with the methods GetColumnVisibility and GetColumnVisibility:

set column 2 visible	int iColumnNumber = 2; _pyMultiList->SetColumnVisibility(iColumnNumber, CATDlgShow);
query column 3 visibility	... iColumnNumber = 3; if (_pyMultiList->GetColumnVisibility(iColumnNumber) == CATDlgHidden) ...

synchronize the vertical scrolling between two instances of CATDlgMultiList:
_pyMultiList->Synchronize(_iMultiListToSynchronize);

[Top]

Managing the Selection in the List

To help manage the selection in the list displayed, you can use the following methods:

retrieve the number of rows selected using the GetSelectCount method:

int NumberOfRowsSelected;
NumberOfRowsSelected= _pMultiList->GetSelectCount();

retrieve the indices or contents of the rows selected with the GetSelect method:

get selected rows as a table of int

int _oSelectedRows[10];
int oArraySize;
int NumberOfSelectedRows;
NumberOfSelectedRows = _pMultiList->GetSelect(
_oSelectedRows,
oArraySize);

or as a table of CATUnicodeString

...
CATUnicodeString _oSelectedRows[10];
NumberOfSelectedRows = _pMultiList->GetSelect(_oSelectedRows, oArraySize);

Pay attention to properly allocate and deallocate the tables.

set the rows selected with the SetSelect method:

set selected rows as a table of int

int _iSelectedRows[10];
int iArraySize = 10;
int iNotify = 1;
int NumberOfSelectedRows;
NumberOfSelectedRows = _pMultiList->SetSelect(
_iSelectedRows,
iArraySize, iNotify);
...

or as a table of
CATUnicodeString

CATUnicodeString * iContentsOfSelectedLines[10];
iContentsOfSelectedLines[0] = ...
int iColumnNumber;
NumberOfSelectedRows = _pMultiList->SetSelect(iColumnNumber,
                                             iContentsOfSelectedLines,
                                             iArraySize, iNotify);

The lines with the line numbers contained in iNumberOfSe-lectedLines or with the contents contained in Set the parameter iNotify to a non null value if you want the corresponding notification to be sent. Otherwise set to 0, no notification is sent.

deselect all selected rows with the ClearSelect method:
_pMultiList->ClearSelect();

query whether a given row is selected:

query whether a
row is selected given its number

CATBool RowIsSelected;
int RowNumber = 5;
RowIsSelected= _pMultiList->IsSelect(RowNumber );
...

or its contents

CATUnicodeString RowContents;
RowContents = ...;
int ColumnNumber;
RowIsSelected = _pMultiList->IsSelect(ColumnNumber, RowContents);

A CATBool is a short.

set or query for column sensitivity with the methods SetColumnSensitivity and IsSetColumnSensitivity:

set column 2 sensitive	int ColumnNumber = 2; _pMultiList->SetColumnSensitivity(ColumnNumber, CATDlgEnable); ...
query column 3 sensitivity	ColumnNumber = 3; if (_pMultiList->IsSetColumnSensitivity(ColumnNumber) == CATDlgDisable) ...

get the row number of the selected row under the mouse when the end user displays the contextual menu:
int RowNumber; RowNumber= _pMultiList->GetContextualLine();

[Top]

Setting a Callback on a Multiple List

Set a callback on a multiple list to be informed whenever the end user selects a line as follows:

AddAnalyseNotificationCB(
  _pMultiList,                                   // multiple list 
  _pMultiList->GetListSelectNotification(),      // notification
  (CATCommand)&MultiList::MethodToExecute,       // method to execute 
  CATCommandClientData iUsefulData);             // useful data for this method

[Top]

Setting a Title to a Multiple List

The multiple list title should be set by the resource file using a key built with the identifier you declare as the second parameter of the multiple list constructor. This title is never displayed. If you want to comment the choices available from the multiple list in your dialog, use a label. In addition, each column in a multiple list can have a title. Refer to Managing the Line Content.

[Top]

History

Version: 1 [Jan 2000]	Document created
[Top]

3D PLM Enterprise Architecture

User Interface - Dialogs