3D PLM Enterprise Architecture

CATDialog
  |
  +---CATDlgControl
        |
        +---CATDlgSelectorList

The Selector List

The selector list allows the end user to select one or several values among a discrete list of predefined values. 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 selector list whenever you propose to the end user to select values from a predefined list.

[Top]

[Top]

Programmer's Guide

The selector list is dedicated to selection.

[Top]

Constructing a Selector List

These following kinds of selector list can be constructed.

_pSelectList  = new CATDlgSelectorList (iParent, iName);

_pMSelectList = new CATDlgSelectorList (iParent, iName,
                                    CATDlgListMultisel);

[Top]

Managing the Line Content

You can do the following to manage the content of the lines in a selector list:

• get the number of lines in the list with the GetLineCount method:

  int NumberOfLines; NumberOfLines = _pSelectList->GetLineCount();

• get the contents of a given line with the GetLine:method:

  CATUnicodeString oLineContents; int iLineNumber; _pSelectList->GetLine(oLineContents, iLineNumber);

• set or modify the contents of one or several lines with the SetLine method:

  CATUnicodeString * iLineContents iLineContents = "This is my selector list line"; int iLineNumber = 3; int FirstLine; FirstLine = _pSelectList->SetLine(*iLineContents, iLineNumber,CATDlgDataAdd);

  Two modes are available: CATDlgDataAdd to add a line, which is the default, and CATDlgDataModify to modify an existing line. If iLineNumber is omitted or set to -1, the line is appended to the list. You can also set or modify a group of contiguous lines:

  modifies 5 lines starting from line 3

  CATUnicodeString StringArray[5] StringArray[0] = ... ... int iArraySize = 5 int iLineNumber = 3; int FirstLine; FirstLine = _pSelectList->SetLine(StringArray, iArraySize, iLineNumber, CATDlgDataModify);

• delete one or several lines with the ClearLine method:

  deletes lines 1,3,6 delete all lines

  int iLineNumber = 5; _pSelectList->ClearLine(iLineNumber); int iLineNum[3] = { 1,3,6 }; int iLineNumSize=3; _pSelectList->ClearLine(iLineNum, iLineNumSize); _pSelectList->ClearLine();

[Top]

Managing the Line Display

You can manage the line display with the following methods:

• get or set the visible text width:

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

  The value returned by the GetVisibleTextWidth method makes sense only if it has been set by the SetVisibleTextWidth method.

• get or set the visible text height:

  get visible height	int VisibleTextHeight; TextHeight = _pSelectList->GetVisibleTextHeight();
  set visible height	... TextHeight = 8; _pSelectList->SetVisibleTextHeight(TextHeight);

• get or set the position of the first visible character in the line:

  get 1st visible char	int FirstVisibleChar; FirstVisibleChar = _pSelectList->GetFirstColumn();
  set 1st visible char	... FirstVisibleChar = 5; _pSelectList->SetFirstColumn(FirstVisibleChar);

• get or set the position of the first line:

  get 1st line position	int FirstLine; FirstLine = _pSelectList->GetFirstLine();
  set 1st line position	... FirstLine = 3; _pSelectList->SetFirstLine(FirstLine);

[Top]

Managing the Selection in the List

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

• retrieve the number of lines selected using the GetSelectCount method:

  int NumberOfLinesSelected; NumberOfLinesSelected = _pMSelectList->GetSelectCount();

• retrieve the lines selected with the GetSelect method:

  get selected lines as a table of int	int oNumberOfSelectedLine[10]; int oArraySize; _pMSelectList->GetSelect(oNumberOfSelectedLine,oArraySize); ...
  or as a table of CATUnicodeString	CATUnicodeString oSelectedLines[10]; _pMSelectList->GetSelect(oSelectedLines,oArraySize);

  Pay attention to properly allocate and deallocate the table.

• set the lines selected with the SetSelect method:

  set selected lines as a table of int	int iNumberOfSelectedLines[10]; int iArraySize = 10; int iNotify = 1; _pMSelectList->SetSelect(iNumberOfSelectedLines, iArraySize, iNotify); ...
  or as a table of CATUnicodeString	CATUnicodeString * iContentsOfSelectedLines[10]; iContentsOfSelectedLines[0] = ... ... _pMSelectList->SetSelect(iContentsOfSelectedLines, iArraySize, iNotify);

  The lines with the line numbers contained in iNumberOfSelectedLines or with the contents contained in iContentsOfSelectedLines are selected. Set the parameter Notify 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 lines with the ClearSelect method:

  _pMSelectList->ClearSelect();

• query whether a given line is selected:

  query whether a line is selected given its number	CATBool LineIsSelected; int LineNumber = 5; LineIsSelected = _pSelectList->IsSelect(LineNumber); ...
  or its contents	CATUnicodeString LineContents; LineContents = ... LineIsSelected = _pSelectList->IsSelect(LineContents)

  A CATBool is a short.

• get the line number of the selected line under the mouse when the end user displays the contextual menu:

  int LineNumber; LineNumber = _pSelectList->GetContextualLine();

[Top]

Setting a Callback on a Selector List

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

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

[Top]

Setting a Title to a Selector List

The selector list title should be set by the resource file using a key built with the identifier you declare as the second parameter of the selector list constructor. This title is never displayed. If you want to comment the choices available from the selector list in your dialog, use a label.

[Top]

History

Copyright © 2000, Dassault Systèmes. All rights reserved.