3D PLM Enterprise Architecture

CATDialog
  |
  +---CATDlgControl
        |
        +---CATDlgCombo

The Combo

The combo allows the end user to choose a value or an option by selecting a character string from a predefined list, or through a keyboard entry.

Use a combo whenever you propose to the end user to select an alphanumerical value from a discrete list, or enter an alphanumerical value to update a discrete list.

Styles

Name	Display	Description
default		The standard combo, composed of an entry zone which displays the selected value, and a list permanently displayed.
CATDlgCmbDropDown		The drop down combo, composed of an entry zone which displays the selected value, and the list of values to select in, displayed when the arrow located on the right of the entry zone is selected.
CATDlgCmbOptionStyle		The option style combo, which is very near of the drop down combo with a Motif style. This type of combo is replaced by a CATDlgCmbDropDown combo with Windows.
CATDlgCmbEntry		Allows for keyboard text entry in addition to text selection for drop down and standard combos.
CATDlgCmbDouble		The entered number must be a double precision floating number.
CATDlgCmbColor		Shows a color palette. Available in conjunction with CATDlgCmbDropDown only
CATDlgCmbLineType		Shows a linetype palette. Available in conjunction with CATDlgCmbDropDown only
CATDlgCmbBitmap		Shows an icon palette. Available in conjunction with CATDlgCmbDropDown only

[Top]

[Top]

Programmer's Guide

The combo is dedicated to executing a command when it is clicked.

[Top]

Constructing a Combo

These kinds of combo can be constructed, according to their different styles. Styles can be concatenated using the "|" character.

_pCombo            = new CATDlgCombo (iParent, iName);

_pDropDownCombo    = new CATDlgCombo (iParent, iName,
                                   CATDlgCmbDropDown);

_pOptionStyleCombo = new CATDlgCombo (iParent, iName,
                                   CATDlgCmbOptionStyle);

_pDoubleCombo      = new CATDlgCombo (iParent, iName,
                                   CATDlgCmpDouble);

_pColorCombo       = new CATDlgCombo (iParent, iName,
                               CATDlgCmbColor|CATDlgCmbDropDown);

_pLinetypeCombo    = new CATDlgCombo (iParent, iName,
                               CATDlgCmbLineType|CATDlgCmbDropDown);

_pBitmapCombo      = new CATDlgCombo (iParent, iName,
                               CATDlgCmbBitmap|CATDlgCmbDropDown);

[Top]

Color Combo

	A color combo displays a color palette that can contain up to 16 million colors. Colors are assigned for each line using the RGB values ranging each from 0 to 255 passed as parameters of the SetLine method. The selected or current color is displayed in the entry zone.
	When the end user clicks on the arrow, the color palette is displayed and another color can be selected. The number of displayed colors is set using the SetVisibleTextHeight method.
	A name can be assigned to each color. It is displayed beside the color.
	The color names are read from the combo resource file. CATUnicodeString instances must be built from these names, and passed as parameters of the SetLine method.

[Top]

Linetype Combo

	A linetype combo displays a linetype palette. Linetypes are assigned for each line using a pixel pattern expressed using two bytes, a repeating factor of this pattern, and a width expressed as a pixel number, passed as parameters of the SetLine method. The selected or current linetype is displayed in the entry zone.
	When the end user clicks on the arrow, the linetype palette is displayed and another linetype can be selected. The number of displayed linetypes is set using the SetVisibleTextHeight method.
	A name can be assigned to each linetype. It is displayed beside the linetype.
	The linetype names are read from the combo resource file. CATUnicodeString instances must be built from these names, and passed as parameters of the SetLine method.

The linetype is built using a bit pattern, or mask, encoded on two bytes. This mask is shown below for Dashed, DotDashed, and Solid respectively.

This mask can be used with a mapping of one pixel for one bit. Each bit can also be repeated on several pixels. This enlarges the mask. The linetype thickness is set as a number of pixels. The code that creates the combo shown above without the linetype names is as follows:

...
CATUnicodeString * pucsEmpty = new CATUnicodeString();
unsigned short Mask[8] = {0xffff, 0x3333, 0x7777, 0x0c3f, 0x5757, 0xcccc, 0x7ffb, 0x5bbc};
unsigned short Repeat[8] = {1, 4, 4, 2, 8, 1, 4, 4};

_pLinetypeCombo->SetLine(*pucsEmpty, Mask[0], Repeat[0], 1, 0);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[1], Repeat[1], 1, 1);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[2], Repeat[2], 1, 2);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[3], Repeat[3], 1, 3);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[4], Repeat[4], 1, 4);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[5], Repeat[5], 1, 5);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[6], Repeat[6], 1, 6);
_pLinetypeCombo->SetLine(*pucsEmpty, Mask[7], Repeat[7], 3, 7);
...

The fourth parameter is the thickness expressd in pixels. It is set to 1, except for the last linetype for which it is set to 3 pixels. The last parameter is the line number.

[Top]

Managing the Line Content

Lines in a combo are numbered beginning with 0.

• You can retrieve the number of lines with GetLineCount:

  int LineCount = _pCombo->GetLineCount();

• You can get the content of a line with GetLine. For example, retrieve the content of the fourth line.

  	int iLineNumber = 3;
  Standard, dropdown, or option style combo	CATUnicodeString oLineContent; _pCombo->GetLine(oLineContent, iLineNumber);
  Double combo	double oLineValue; oLineValue = _pDoubleCombo->GetLine(iLineNumber);
  Color combo	unsigned char oRed, oGreen, oBlue; _pColorCombo->GetLine(oLineContent, oRed, oGreen, oBlue, iLineNumber);
  Linetype combo	unsigned short oMask, oRepeat, oWeight; _pLinetypeCombo->GetLine(oLineContent, oMask, oRepeat, oWeight, iLineNumber);

• You can set the content of a line with SetLine. For example, set the content of the third line.

  	int iLineNumber = 2;
  Standard, dropdown, or option style combo	CATUnicodeString iLineContent = ...; _pCombo->SetLine(iLineContent, iLineNumber);
  Double combo	double iLineValue; _pDoubleCombo->SetLine(iLineValue, iLineNumber);
  Color combo	// Set athe red color unsigned char iRed=255, iGreen=0, iBlue=0; _pColorCombo->SetLine(iLineContent, iRed, iGreen, iBlue, iLineNumber);
  Linetype combo	// Set a solid line unsigned short iMask=0xffff, iRepeat=1, iWeight=1; _pLinetypeCombo->SetLine(iLineContent, iMask, iRepeat, iWeight, iLineNumber);

• You can delete all lines, a given line, or several lines.

  delete all lines	_pCombo->ClearLine();
  delete the fourth line	int LineToClear = 3; _pCombo->ClearLine(LineToClear);
  delete four lines (2nd, 5th, 9th, and 12th)	int LinesToClear[4] = {1, 4, 8, 11}; int NumberOfLinesToClear = 4; _pCombo->ClearLine(LinesToClear, NumberOfLinesToClear);

[Top]

Managing the Line Display

To help manage the line display in the combo, you can use the following methods:

• managing the number of lines displayed with GetVisibleTextHeight and SetVisibleTextHeight:

  get number of visible lines	int Height; Height = _pCombo->GetVisibleTextHeight();
  set number of visible lines	int Height = 10; _pCombo->SetVisibleTextHeight(Height);

• managing the number of visible characters in the entry zone with GetVisibleTextWidth and SetVisibleTextWidth:

  get number of visible characters	int Width; Width = _pCombo->GetVisibleTextWidth();
  set number of visible characters	int Width = 15; _pCombo->SetVisibleTextWidth(Width);

  The visible text width is expressed in number of characters.

[Top]

Managing the Selection

You can manage the selection with the methods GetSelect, SetSelect, and ClearSelect:

int SelectedLineNumber;
SelectedLineNumber = _pCombo->GetSelect();

int SelectedLineNumber = 8;
_pCombo->SetSelect(SelectedLineNumber);

_pCombo->ClearSelect();

[Top]

Managing the Keyboard Entry

You can manage the keyboard entry field with the methods GetField, SetField, and ClearField:

CATUnicodeString FieldText;
_pCombo->GetField(FieldText);

double FieldValue;
FieldValue = _pDoubleCombo->GetField();

CATUnicodeString FieldText = ...;
_pCombo->SetField(FieldText);

double FieldValue = 3.14159;
_pDoubleCombo->SetField(FieldValue );

_pCombo->ClearField();

[Top]

Setting a Callback on a Combo

Set a callback on a non editable combo to be informed whenever the end user selects a value in the combo:

AddAnalyseNotificationCB(
  _pCombo,                                    // combo 
  _pCombo->GetComboSelectNotification(),      // notification
  (CATCommand)&Combo::MethodToExecute,        // method to execute 
  CATCommandClientData iUsefulData);          // useful data for this method 

[Top]

Setting a Title to a Combo

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

[Top]

History

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