SftTree/DLL 7.5 - Tree Control

SFTTREE_CELL Structure

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

typedef struct tagSftTreeCELL {
    COLORREF colorBg;                   // foreground color (SFTTREE_NOCOLOR if default wanted)
    COLORREF colorFg;                   // background color (SFTTREE_NOCOLOR if default wanted)
    COLORREF colorBgSel;                // foreground color if selected (SFTTREE_NOCOLOR if default wanted)
    COLORREF colorFgSel;                // background color if selected (SFTTREE_NOCOLOR if default wanted)
    HFONT hFont;                        // font handle (NULL if default wanted)
#if defined(SFTTREE_OBSOLETE_4)
    HBITMAP hBmp;                       // cell bitmap (NULL if none wanted)
#else
    HBITMAP obsoletehBmp;               // not used
#endif
    short flag;                         // misc flag
#define SFTTREE_BMP_LEFT     0          // bitmap alignment
#define SFTTREE_BMP_CENTER   0x01
#define SFTTREE_BMP_RIGHT    0x02
#define SFTTREE_BMP_VCENTER  0x10
#define SFTTREE_BMP_TOP      0x20
#define SFTTREE_BMP_BOTTOM   0x40
#define SFTTREE_TEXT_LEFT    0x0100     // text alignment, overrides column default
#define SFTTREE_TEXT_CENTER  0x0200
#define SFTTREE_TEXT_RIGHT   0x0400
#define SFTTREE_TEXT_VCENTER 0x0800
#define SFTTREE_TEXT_TOP     0x1000
#define SFTTREE_TEXT_BOTTOM  0x2000
    short flag2;
#define SFTTREECELL_IGNORE          1   // ignored item (for optimal width calculation)
#define SFTTREECELL_EDITIGNORE      2   // ignored item during cell editing
#define SFTTREECELL_CONTENT_KEEPSIZE 0x04 // keep content window size (requires variable height tree control)
#define SFTTREECELL_CONTENT_DISABLE 0x08 // don't enable/disable content window
    SFTTREE_DWORD_PTR cellData;         // cell user data
    HWND hwndCell;                      // cell is using this content window

    SFT_PICTURE CellPicture1;           // cell picture
    
    int flag3;
#define SFTTREE_CELL_BGVERTICAL       1 // vertical gradient for background color colorBgStart/End (0 = default)
#define SFTTREE_CELL_BGHORIZONTAL     2 // horizontal gradient for background color colorBgStart/End (0 = default)
#define SFTTREE_CELL_PROGRESSVERTICAL 4// vertical gradient for progress bar color colorBgProgressStart/End (0 = default)
#define SFTTREE_CELL_PROGRESSHORIZONTAL 8 // horizontal gradient for progress bar color colorBgProgressStart/End (0 = default)
#define SFTTREE_CELL_PROGRESSFULL     0x8000 // full size progress bar
#define SFTTREE_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 (SFTTREE_NOCOLOR if default wanted)
    COLORREF colorProgress;             // progress bar color
    COLORREF colorProgressEnd;          // progress bar color end color
    int progressVal, progressMax;       // background progress bar indicator

} SFTTREE_CELL, * LPSFTTREE_CELL;
typedef const SFTTREE_CELL * LPCSFTTREE_CELL;

Members

colorBg

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

colorFg

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

colorBgSel

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

colorFgSel

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

hFont

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

hBmp

A bitmap handle defining the cell picture, displayed next to the cell text. Specify NULL to omit the cell picture. This member is provided for compatibility with older SftTree/DLL versions. The CellPicture1 member should be used instead. This member is only accessible if the preprocessor symbol SFTTREE_OBSOLETE_4 is defined.

flag

The cell picture position, relative to the cell text. This member is ignored if CellPicture1 is empty and hBmp is NULL.

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

flag2

Cell attributes. The following values can be combined:

cellData

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

hwndCell

Defines the content window to be displayed by this cell. Specify NULL to omit the content window.

CellPicture1

Defines the cell picture displayed next to the cell text. If the hBmp member defines a picture, CellPicture1 is ignored.

flag3

Cell attributes defining background and progress bar attributes.

The following values can be combined:

colorBgEnd

The ending background color used to draw the cell when the item is not selected. Specify SFTTREE_NOCOLOR to use the default background color. 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 SFTTREE_NOCOLOR to use the default background color. 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 SFTTREE_NOCOLOR to use the default background color. 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 SFTTREE_NOCOLOR to use the default background color. If colorProgress is not defined, colorProgressEnd is ignored. 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. 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.

Comments

The SFTTREE_CELL structure is used with GetCellInfo and SetCellInfo to retrieve and set cell attributes and as part of the SFTTREE_ITEM structure (for a virtual data source). GetCellInfo and SetCellInfo usually retrieve and set attributes for one cell described by the SFTTREE_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 SFTTREE_CELLINFOPARM structure members index to the item index and iCol to -1, the values of the provided SFTTREE_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 SFTTREE_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 tree control, all cell pictures used for all cells must be the same size. In a variable height tree control, 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 tree control uses them. Fonts have to be deleted using DeleteObject once they are no longer needed.

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

Examples

C

                SftTree_SetCellInfo(g_hwndTree, &CellInfo);

                i = SftTree_AddString(g_hwndTree, TEXT("Progress Bar - Partial"));
                SftTree_SetItemLevel(g_hwndTree, i, 1);
                CellInfo.version = 7;
                CellInfo.index = i;
                CellInfo.iCol = 0;
                SftTree_GetCellInfo(g_hwndTree, &CellInfo);
                CellInfo.Cell.flag3 = SFTTREE_CELL_PROGRESSHORIZONTAL|SFTTREE_CELL_PROGRESSSMALL;
                CellInfo.Cell.progressMax = 200;    // maximum value 0 - 200
                CellInfo.Cell.progressVal = 133;    // current value
                SftTree_SetCellInfo(g_hwndTree, &CellInfo);


                i = SftTree_AddString(g_hwndTree, TEXT("Progress Bar - with gradient fill"));
                SftTree_SetItemLevel(g_hwndTree, i, 1);

View Entire Sample Code

C++

            m_Tree.SetCellInfo(&CellInfo);

            i = m_Tree.AddString(_T("Progress Bar - Partial"));
            m_Tree.SetItemLevel(i, 1);
            CellInfo.version = 7;
            CellInfo.index = i;
            CellInfo.iCol = 0;
            m_Tree.GetCellInfo(&CellInfo);
            CellInfo.Cell.flag3 = SFTTREE_CELL_PROGRESSHORIZONTAL|SFTTREE_CELL_PROGRESSSMALL;
            CellInfo.Cell.progressMax = 200;    // maximum value 0 - 200
            CellInfo.Cell.progressVal = 133;    // current value
            m_Tree.SetCellInfo(&CellInfo);

            i = m_Tree.AddString(_T("Progress Bar - with gradient fill"));
            m_Tree.SetItemLevel(i, 1);
            CellInfo.version = 7;

View Entire Sample Code

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