HeaderPane
Main
Hide
Share Link
Print

SFTBOX_CELL Structure

The SFTBOX_CELL structure is used with GetCellInfo and SetCellInfo to retrieve and set cell attributes and as part of the SFTBOX_ITEM structure (for a virtual data source).

typedef struct tagSftBoxCELL {
    COLORREF colorBg, colorFg;              // colors (SFTBOX_NOCOLOR if default wanted)
    COLORREF colorBgSel, colorFgSel;        // colors if selected
    HFONT hFont;                            // font handle (NULL if default wanted)
    HBITMAP obsoletehBmp;                   // not used
    short flag;                             // misc flag
#define SFTBOX_BMP_LEFT     0               // picture alignment
#define SFTBOX_BMP_CENTER   0x01
#define SFTBOX_BMP_RIGHT    0x02
#define SFTBOX_BMP_VCENTER  0x10
#define SFTBOX_BMP_TOP      0x20
#define SFTBOX_BMP_BOTTOM   0x40
#define SFTBOX_TEXT_LEFT    0x0100          // text alignment, overrides column default
#define SFTBOX_TEXT_CENTER  0x0200
#define SFTBOX_TEXT_RIGHT   0x0400
#define SFTBOX_TEXT_VCENTER 0x0800
#define SFTBOX_TEXT_TOP     0x1000
#define SFTBOX_TEXT_BOTTOM  0x2000
    short flag2;
#define SFTBOXCELL_IGNORE              1    // ignored cell (for optimal width calculation)
#define SFTBOXCELL_EDITIGNORE          2    // not used
#define SFTBOXCELL_CONTENT_KEEPSIZE    0x04 // not used
#define SFTBOXCELL_CONTENT_DISABLE     0x08 // not used
    SFTBOX_DWORD_PTR cellData;              // cell user data
    HWND hwndCell;                          // reserved

    SFT_PICTURE CellPicture1;               // cell picture

    // gradient and progress bar fields
    int flag3;
#define SFTBOX_CELL_BGVERTICAL         1    // vertical gradient for background color colorBg/colorBgEnd
#define SFTBOX_CELL_BGHORIZONTAL       2    // horizontal gradient for background color colorBg/colorBgEnd
#define SFTBOX_CELL_PROGRESSVERTICAL   4    // vertical gradient for progress bar color colorProgress/colorProgressEnd
#define SFTBOX_CELL_PROGRESSHORIZONTAL 8    // horizontal gradient for progress bar color colorProgress/colorProgressEnd
#define SFTBOX_CELL_PROGRESSFULL     0x8000 // full size progress bar
#define SFTBOX_CELL_PROGRESSSMALL    0x4000 // 1/3 height/centered progress bar
    COLORREF colorBgEnd;                    // background color gradient fill end (combined with colorBg)
    COLORREF colorBgSelEnd;                 // background color gradient fill end if selected (SFTBOX_NOCOLOR if default wanted)
    COLORREF colorProgress;                 // progress bar color
    COLORREF colorProgressEnd;              // progress bar color end color
    int progressVal, progressMax;           // background progress bar indicator

} SFTBOX_CELL, * LPSFTBOX_CELL;

typedef const SFTBOX_CELL * LPCSFTBOX_CELL;

Members

colorBg

The background color used to draw the cell when the item is not selected. Specify SFTBOX_NOCOLOR to use the default background color.

colorFg

The foreground color used to draw the cell text when the item is not selected. Specify SFTBOX_NOCOLOR to use the default text color.

colorBgSel

The background color used to draw the cell when the item is selected. Specify SFTBOX_NOCOLOR to use the default background color.

colorFgSel

The foreground color used to draw the cell text when the item is selected. Specify SFTBOX_NOCOLOR to use the default text color.

hFont

The font used to draw the cell text. If NULL is specified, the combo box control's default font is used. The default font can be defined using the WM_SETFONT message or the CWnd::SetFont function.

obsoletehBmp

Not used. Set to NULL.

flag

The cell picture position, relative to the cell text, and the cell text alignment. The cell picture position is ignored if CellPicture1 is empty.

One value of each of the following tables can be combined and assigned to the flag member.

flagHorizontal cell picture alignment
SFTBOX_BMP_LEFTThe cell picture is displayed to the left of the cell text. If no horizontal cell picture alignment value is specified, SFTBOX_BMP_LEFT is assumed.
SFTBOX_BMP_CENTERThe cell picture is displayed in the center of the cell, the cell text is not shown.
SFTBOX_BMP_RIGHTThe cell picture is displayed to the right of the cell text.
flagVertical cell picture alignment
SFTBOX_BMP_VCENTERThe cell picture is vertically centered within the cell. If no vertical cell picture alignment value is specified, the vertical alignment defined using the style member of the SFTBOX_COLUMN structure of the cell's column applies.
SFTBOX_BMP_TOPThe cell picture is vertically aligned with the top of the cell.
SFTBOX_BMP_BOTTOMThe cell picture is vertically aligned with the bottom of the cell.
flagHorizontal cell text alignment
not specifiedIf no horizontal cell text alignment is specified, the default defined using the style member of the SFTBOX_COLUMN structure of the cell's column applies.
SFTBOX_TEXT_LEFTThe cell text is left aligned within the cell.
SFTBOX_TEXT_CENTERThe cell text is centered within the cell.
SFTBOX_TEXT_RIGHTThe cell text is right aligned within the cell.
flagVertical cell text alignment
not specifiedIf no vertical cell text alignment is specified, the default defined using the style member of the SFTBOX_COLUMN structure of the cell's column applies.
SFTBOX_TEXT_TOPThe cell text is aligned with the top of the cell.
SFTBOX_TEXT_VCENTERThe cell text is vertically centered within the cell.
SFTBOX_TEXT_BOTTOMThe cell text is aligned with the bottom of the cell.

flag2

Cell attributes. The following values can be combined:

flag2Cell attributes
0No additional attributes.
SFTBOXCELL_IGNOREThe cell is ignored for optimal column width calculation using MakeColumnOptimal and CalcOptimalColumnWidth. This attribute is typically used if certain cell contents are known to be unusually long, which would make a column too wide.
SFTBOXCELL_EDITIGNORENot used by the combo box control.
SFTBOXCELL_CONTENT_KEEPSIZENot used by the combo box control.
SFTBOXCELL_CONTENT_DISABLENot used by the combo box control.

cellData

Can be used by the application to store an application-defined value.

hwndCell

Reserved. Must be set to NULL.

CellPicture1

Defines the cell picture displayed next to the cell text. The cell picture position is defined using the flag member.

flag3

Cell attributes defining background and progress bar attributes.

The following values can be combined:

flag3Cell attributes
0No additional attributes. A gradient fill is horizontal and a progress bar uses the full height of the cell.
SFTBOX_CELL_BGVERTICALIf the cell (or column defaults) define a cell background color (colorBg) and an ending color (colorBgEnd) resulting in a gradient fill, the area is filled using a vertical gradient fill.
SFTBOX_CELL_BGHORIZONTALIf the cell (or column defaults) define a cell background color (colorBg) and an ending color (colorBgEnd) resulting in a gradient fill, the area is filled using a horizontal gradient fill.
SFTBOX_CELL_PROGRESSVERTICALIf the cell defines a progress bar (progressMax) with a color (colorProgress) and an ending color (colorProgressEnd) resulting in a gradient fill, the area is filled using a vertical gradient fill.
SFTBOX_CELL_PROGRESSHORIZONTALIf the cell defines a progress bar (progressMax) with a color (colorProgress) and an ending color (colorProgressEnd) resulting in a gradient fill, the area is filled using a horizontal gradient fill.
SFTBOX_CELL_PROGRESSFULLIf the cell defines a progress bar (progressMax), the full height of the cell is used to render the progress bar.
SFTBOX_CELL_PROGRESSSMALLIf the cell defines a progress bar (progressMax), the progress bar is vertically centered within the cell and is approximately 1/3 of the full height of the cell. The defined background colors (colorBg) fill the remainder of the cell.

colorBgEnd

The ending background color used to draw the cell when the item is not selected. Specify SFTBOX_NOCOLOR if no gradient fill is wanted. If colorBg is not defined, colorBgEnd is ignored. colorBgEnd combined with colorBg define a gradient fill used to render the cell's background. The gradient fill orientation can be defined using flag3.

colorBgSelEnd

The ending background color used to draw the cell when the item is selected. Specify SFTBOX_NOCOLOR if no gradient fill is wanted. If colorBgSel is not defined, colorBgSelEnd is ignored. colorBgSelEnd combined with colorBgSel define a gradient fill used to render the cell's background. The gradient fill orientation can be defined using flag3.

colorProgress

The color used to draw the progress bar. Specify SFTBOX_NOCOLOR to use the column's default progress bar color (see SFTBOX_COLUMN, colorProgress). If the column doesn't define a color either, the system highlight color (COLOR_HIGHLIGHT) is used. The progress bar is only shown if progressMax has been set to a value greater than 0.

colorProgressEnd

The ending color used to draw the progress bar. Specify SFTBOX_NOCOLOR if no gradient fill is wanted. If colorProgress is not defined, colorProgressEnd is ignored and the column's default progress bar colors are used. colorProgressEnd combined with colorProgress define a gradient fill used to render the progress bar. The gradient fill orientation can be defined using flag3. The progress bar is only shown if progressMax has been set to a value greater than 0.

progressVal

Defines the current value for the progress bar. Allowable values for progressVal are 0 to progressMax. The progress bar is only shown if progressMax has been set to a value greater than 0. The progress bar is rendered as the background of the cell, starting at the left edge. Its horizontal size is proportional to the progressVal value. Once progressVal reaches the maximum defined using progressMax, the progress bar fills the entire cell.

progressMax

Defines the maximum value for the progress bar. The progress bar is only shown if progressMax has been set to a value greater than 0. h1 Comments

The SFTBOX_CELL structure is used with GetCellInfo and SetCellInfo to retrieve and set cell attributes and as part of the SFTBOX_ITEM structure (for a virtual data source). GetCellInfo and SetCellInfo usually retrieve and set attributes for one cell described by the SFTBOX_CELLINFOPARM structure members index and iCol.

SetCellInfo can be used to set all cells of an item to the same values using one call to SetCellInfo, instead of multiple calls, one for each cell. By setting the SFTBOX_CELLINFOPARM structure members index to the item index and iCol to -1, the values of the provided SFTBOX_CELL structure are copied and assigned to each cell. The following structure members are copied: colorBg, colorFg, colorBgSel, colorFgSel, hFont, flag, flag2, flag3, colorBgEnd, colorBgSelEnd, colorProgress, colorProgressEnd. This is usually used to propagate custom color values to all cells of an item.

An RGB value or a GetSysColor index value can be specified for all color values. If a color index is used, the high-order bit must be set (e.g., COLOR_WINDOW | 0x80000000L).

A cell may have an associated cell picture without the picture component actually being visible. The cell picture doesn't become visible until the cell picture size has been registered using SetCellInfo by setting the index member of the SFTBOX_CELLINFOPARM structure to -1. Only one picture is used to register the picture size. After registering the picture size, any number of pictures may be used.

In a fixed height combo box control, all cell pictures used for all cells must be the same size. In a variable height combo box control (see SFTBOXSTYLE_VARIABLE), cell pictures can be of varying sizes. The (largest) cell picture size must be registered using SetCellInfo. A new picture size can be registered at any time, but all cell pictures in use must be replaced by pictures of the new size (or smaller).

Fonts are owned by the application and the associated font handles have to remain valid as long as the combo box control uses them. Fonts have to be deleted using DeleteObject once they are no longer needed.

In a dropdown list combo box, the cell attributes of the selected item are also used to display the item in the static portion.

Cell text can be retrieved using GetText and modified using SetText.

Pointer typedefs: LPSFTBOX_CELL is a pointer to a SFTBOX_CELL structure, LPCSFTBOX_CELL is a pointer to a constant SFTBOX_CELL structure.

See Also C/C++ API | Categories | Notifications


Last Updated 11/21/2026 - (email)
© 2026 Softel vdm, Inc.