SftTree/DLL 6.5

SFTTREE_COLUMN_EX

Softel vdm, Inc.

The SFTTREE_COLUMN_EX structure is used with GetColumns and SetColumns to retrieve and set column attributes.

typedef struct tagSftTreeColumnEx {

    int width;                          // column width
    DWORD style;                        // column default cell alignment and attributes
                                        // use ES_LEFT, ES_CENTER, ES_RIGHT edit window styles
                                        // SFTTREE_MULTILINE if more than one text line
#define SFTTREE_MULTILINE ES_MULTILINE  // allow \r\n
#define SFTTREE_WRAP 0x0010L            // wrap text (always allows \r\n)
#define SFTTREE_TOOLTIP 0x0008L         // enable tooltips
    DWORD styleTitle;                   // column header title style
                                        // use ES_LEFT, ES_CENTER, ES_RIGHT edit window styles
                                        // and SFTTREE_HEADER_DISABLED/UP
    // Do not write to the string addressed directly, replace the pointer instead
    LPTSTR lpszTitle;                   // column header title
    LPTSTR lpszOrig;                    // original header column title - do not alter
#if defined(SFTTREE_OBSOLETE_4)
    HBITMAP hBmp;                       // bitmap (NULL if none wanted)
#else
    HBITMAP obsoletehBmp;               // not used
#endif
    short flag;                         // misc. flag (for bitmap position)
    short flag2;                        // reserved
    short flag3;                        // background gradient and progress bar information
#define SFTTREE_COL_BGVERTICAL       1 // vertical gradient for background color colorBgStart/End (0 = default)
#define SFTTREE_COL_BGHORIZONTAL     2 // horizontal gradient for background color colorBgStart/End (0 = default)
#define SFTTREE_COL_PROGRESSVERTICAL 4 // vertical gradient for progress bar color colorBgProgressStart/End (0 = default)
#define SFTTREE_COL_PROGRESSHORIZONTAL 8 // horizontal gradient for progress bar color colorBgProgressStart/End (0 = default)
#define SFTTREE_COL_PROGRESSFULL     0x8000 // full size progress bar
#define SFTTREE_COL_PROGRESSSMALL    0x4000 // 1/3 height/centered progress bar
    short flag4;                        // reserved

    COLORREF colorBg;                   // column's cell default background color
    COLORREF colorFg;                   // column's cell default foreground color
    COLORREF colorBgSel;                // column's cell default background color if selected
    COLORREF colorFgSel;                // column's cell default foreground color if selected

    /* Column display */
    int realPos;                        // column real position
    int dispPos;                        // column display position
    short colFlag;                      // column flag
#define SFTTREE_COL_LOCKED    0x01      // lock column (can't resize)
#define SFTTREE_COL_KEEPPOS   0x02      // column must stay in position
#define SFTTREE_COL_MERGE     0x04      // column can merge into next
#define SFTTREE_COL_MERGEINTO 0x08      // column allows merge into from previous
    short minWidth;                     // minimum column width
    short flag6;                        // reserved
    short flag7;                        // reserved

    SFT_PICTURE Picture1;               // column header picture

    int fColorsOverrideTheme;           // TRUE if this header's colors override windows theme colors
    COLORREF headerColorBg;             // column header's background color
    COLORREF headerColorFg;             // column header's foreground color
    COLORREF headerColorBgSel;          // column header's background color if selected
    COLORREF headerColorFgSel;          // column header's foreground color if selected
    COLORREF headerColorBgDisabled;     // column header's background color if disabled
    COLORREF headerColorFgDisabled;     // column header's foreground color if disabled
    COLORREF headerColorBgSelDisabled;  // column header's background color if disabled and selected
    COLORREF headerColorFgSelDisabled;  // column header's foreground color if disabled and selected
    COLORREF colorBgEnd;                // column's cell default background color (ending color for gradient fill)
    COLORREF colorBgSelEnd;             // column's cell default background color if selected (ending color for gradient fill)
    COLORREF colorProgress;           	// column's default progressbar color
    COLORREF colorProgressEnd;        	// column's default progressbar color (ending color for gradient fill)

} SFTTREE_COLUMN_EX, * LPSFTTREE_COLUMN_EX;
typedef const SFTTREE_COLUMN_EX * LPCSFTTREE_COLUMN_EX;

Members

width

The width of the column (in pixels).  Specify a width greater or equal to 0.  A hidden column has a width of 0.  The last column also must have a defined width, even if it is defined as an open-ended column (see SetOpenEnded).  An open-ended last column will display the complete text specified for the last (or only) column and never truncate any data.  A fixed-width last column is defined with a specified width and any data which doesn't fit is truncated.

The width defined must be larger or equal to minWidthminWidth defines the minimum width of the column.

For compatibility with earlier releases of SftTree/DLL (2.0 and lower), the last column can have this member specified as -1, which makes the last column an open-ended column.  New applications should use SetOpenEnded instead.

style

The item style and alignment default used for the column.  This value applies to all cells in this column.

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

 

style

Horizontal cell text alignment

not specified

If no horizontal cell text alignment is specified, the default is ES_LEFT.

ES_LEFT

The cell text is left aligned within the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

ES_CENTER

The cell text is centered within the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

ES_RIGHT

The cell text is right aligned within the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

 

style

Vertical cell text alignment

not specified

If no vertical cell text alignment is specified, the default is SFTTREE_VCENTER.

SFTTREE_TOP

The cell text and cell picture are aligned with the top of the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

SFTTREE_VCENTER

The cell text and cell picture are vertically centered within the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

SFTTREE_BOTTOM

The cell text and cell picture are aligned with the bottom of the cell.  Cells can override this default by defining new alignment values using the SFTTREE_CELL, flag member.

The style value can optionally be combined with one or more of the following values:

 

SFTTREE_MULTILINE

Cell text can contain new-line characters ('\n') to indicate the start of a new line.  Also use SetItemLines, so the item height can be properly determined.

SFTTREE_WRAP

Cell text will word wrap within the available cell width and height.  SFTTREE_MULTILINE must also be specified for word wrap.

SFTTREE_TOOLTIP

ToolTips are displayed in this column for truncated cells.

styleTitle

The column header style used for the column.

If column header text contains more than one line of text, the SetMultilineHeader function must be used.

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

 

styleTitle

Horizontal column header text alignment

not specified

If no horizontal column header text alignment is specified, the default is ES_LEFT.

ES_LEFT

The column header text is left aligned within the column header.

ES_CENTER

The column header text is centered within the column header.

ES_RIGHT

The column header is right aligned within the column header.

 

styleTitle

Vertical column header text alignment

not specified

If no vertical column header alignment is specified, the default is SFTTREE_VCENTER.

SFTTREE_TOP

The column header text and picture are aligned with the top of the column header.

SFTTREE_VCENTER

The column header text and picture are vertically centered within the column header.

SFTTREE_BOTTOM

The column header text and picture are aligned with the bottom of the column header.

The styleTitle value can optionally be combined with one or more of the following values:

 

SFTTREE_HEADER_DISABLED

The column header for the column is disabled, cannot be clicked and is displayed in a "grayed" fashion.  The column contents (cells) are otherwise unaffected.

SFTTREE_HEADER_UP

The column header button will automatically return to its "up" position when clicked.

lpszTitle

The column header title. Header text can contain multiple lines of text using cr-lf (\r\n).  SetMultilineHeader must be used to enable multiple lines of text.  This member may be NULL to indicate that no title is specified for the column.

lpszOrig

Reserved.  Set to NULL when initializing a SFTTREE_COLUMN_EX structure.

hBmp

The handle of the picture to display in the column's header.  Specify NULL to omit the column picture.  All column header pictures must be the same size.  This member is provided for compatibility with older SftTree/DLL versions.  The Picture1 member should be used instead.  This member is only accessible if the preprocessor symbol SFTTREE_OBSOLETE_4 is defined.

flag

The picture location relative to the column header text.

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

 

flag

Horizontal column header picture alignment

SFTTREE_BMP_LEFT

The column header picture is displayed to the left of the cell text.  If no horizontal column header picture alignment value is specified, SFTTREE_BMP_LEFT is assumed.

SFTTREE_BMP_CENTER

The column header picture is displayed in the center of the cell, the column header text is not shown.

SFTTREE_BMP_RIGHT

The column header picture is displayed to the right of the column header text.

 

flag

Vertical column header picture alignment

SFTTREE_BMP_VCENTER

The column header picture is vertically centered within the column header.  If no vertical column header alignment value is specified, SFTTREE_BMP_VCENTER is assumed.

SFTTREE_BMP_TOP

The column header picture is vertically aligned with the top of the column header.

SFTTREE_BMP_BOTTOM

The column header picture is vertically aligned with the bottom of the column header.

colorBg

The default background color used to draw cells that are not selected.  Cells can override the default background color using SFTTREE_CELL, colorBg.

colorFg

The default foreground color used to draw cells that are not selected.  Cells can override the default foreground color using SFTTREE_CELL, colorFg.

colorBgSel

The default background color used to draw cells that are selected.  Cells can override the background color using SFTTREE_CELL, colorBgSel.

colorFgSel

The default foreground color used to draw cells that are selected.  Cells can override the foreground color using SFTTREE_CELL, colorFgSel.

realPos

This field is read/only and cannot be set by the application.  SetColumns ignores the value in this field.  realPos is used to convert a display column number into a real column number.  As a user reorders columns (see SetReorderColumns), the real column number used by an application differs from the display column number.  For more information see section "Display vs. Real Columns".

dispPos

This field specifies the zero-based display position of the column.  As a user reorders columns (see SetReorderColumns), the real column number used by an application differs from the display column number.  dispPos contains the actual (visible) column number the real column represents.  For more information see section "Display vs. Real Columns".  An application can set this field to 0 (for all columns) so real and display column numbers are identical, otherwise a display column number can be specified for each column.

colFlag

The column attributes. The following values can be combined:

 

SFTTREE_COL_LOCKED

This style causes the column to be a fixed-width column so the user cannot resize it even if column resizing has been allowed (see SetResizeHeader).  By defining a column as locked and specifying a width of 0, a column can be hidden from the user.

SFTTREE_COL_KEEPPOS

This style causes the column to remain in the current display position even if column drag & drop has been defined (see SetReorderColumns).  Typically, column 0 could be locked in place, so the user always has the most important data shown first.

SFTTREE_COL_MERGE

Allows the contents of this column to merge into the next displayed column if the contents of the next cell (or column header) are empty and the next column allows being merged into (SFTTREE_COL_MERGEINTO).  This style also applies to column headers.

SFTTREE_COL_MERGEINTO

Allows the contents of the previous column to merge into this column if the cell (or column header) in this column is empty.  This style also applies to column headers.

minWidth

The minimum width of the column (in pixels).  Specify a minimum width greater or equal to 0.  If a value greater than 0 is specified, the user cannot make this column smaller than the specified value by resizing the column.  The minWidth value is only used when the user resizes the column.  Functions such as MakeColumnOptimal do not take minWidth into consideration.  If minWidth is 0, the column has no minimum width.

Picture1

Defines the picture displayed next to the column header.  If the hBmp member defines a picture, Picture1 is ignored.

flag2, flag4, flag6, flag7

Reserved.  Set to 0 when initializing a SFTTREE_COLUMN_EX structure.

flag3

Defines default cell attributes for cells in this column.

The following values can be combined:

 

flag3

Cell attributes

0

No additional attributes.

SFTTREE_COL_BGVERTICAL

The default for all background gradient fills of cells in this column is a vertical gradient fill. Cells can override this default using SFTTREE_CELL, flag3.

SFTTREE_COL_BGHORIZONTAL

The default for all background gradient fills of cells in this column is a horizontal gradient fill. Cells can override this default using SFTTREE_CELL, flag3.

SFTTREE_COL_PROGRESSVERTICAL

The default for all progress bar gradient fills of cells in this column is a vertical gradient fill. Cells can override this default using SFTTREE_CELL, flag3.

SFTTREE_COL_PROGRESSHORIZONTAL

The default for all progress bar gradient fills of cells in this column is a horizontal gradient fill. Cells can override this default using SFTTREE_CELL, flag3.

SFTTREE_COL_PROGRESSFULL

The default for all progress bars in this column is a full size progress bar, using the full height of the cell.

SFTTREE_COL_PROGRESSSMALL

The default for all progress bars in this column is a vertically centered progress bar, approximately 1/3 of the full height of the cell.

fColorsOverrideTheme

Defines whether an application can override Windows themes and the column header colors are used to render the column header. Set to TRUE to use the defined colors ( headerColorBg, headerColorBgSel, headerColorBgDisabled, headerColorBgSelDisabled, headerColorFg, headerColorFgSel, headerColorFgDisabled, headerColorFgSelDisabled) instead of Windows themes, otherwise set to FALSE. If all colors are set to their default value (SFTTREE_NOCOLOR), Windows themes are used.

headerColorBg

The background color used to render this column's header, when Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (defined using SFTTREE_COLORS, colorColHdrBg).

headerColorFg

The text color used to render this column's header, when Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (defined using SFTTREE_COLORS, colorColHdrFg).

headerColorBgSel

The background color used to render this column's header when it is pressed and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorBg).

headerColorFgSel

The text color used to render this column's header when it is pressed and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorFg).

headerColorBgDisabled

The background color used to render this column's header when it is disabled and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorBg).

headerColorFgDisabled

The text color used to render this column's header when it is disabled and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorFg).

headerColorBgSelDisabled

The background color used to render this column's header when it is pressed and disabled and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorBg).

headerColorFgSelDisabled

The text color used to render this column's header when it is pressed and disabled and Windows themes are not used or the application can override themes (fColorsOverrideTheme). Specify SFTTREE_NOCOLOR to use the default color (headerColorFg).

colorBgEnd

The default ending background color used to draw cells that are not selected. Specify SFTTREE_NOCOLOR to use the default background color. If colorBg is not defined, colorBgEnd is ignored. Cells can override the default background color using SFTTREE_CELL, colorBgEnd. colorBgEnd combined with colorBg define a gradient fill used to render the cell's background. The default gradient fill orientation can be defined using flag3.

colorBgSelEnd

The default ending background color used to draw cells that are selected. Specify SFTTREE_NOCOLOR to use the default background color. If colorBgSel is not defined, colorBgSelEnd is ignored. Cells can override the default background color using SFTTREE_CELL, colorBgSelEnd. colorBgEnd combined with colorBg define a gradient fill used to render the cell's background. The default gradient fill orientation can be defined using flag3.

colorProgress

The default color used to draw a progress bar. Specify SFTTREE_NOCOLOR to use the default background color. Cells can override the default background color using SFTTREE_CELL, colorProgress. A progress bar is only shown if a cell's SFTTREE_CELL, progressMax value has been set to a value greater than 0.

colorProgressEnd

The default ending color used to draw a progress bar. Specify SFTTREE_NOCOLOR to use the default background color. If colorProgress is not defined, colorProgressEnd is ignored. Cells can override the default background color using SFTTREE_CELL, colorProgressEnd. colorProgressEnd combined with colorProgress define a gradient fill used to render the progress bar. The default gradient fill orientation can be defined using flag3. A progress bar is only shown if a cell's SFTTREE_CELL, progressMax value has been set to a value greater than 0.

Comments

The SFTTREE_COLUMN_EX structure is used with GetColumns and SetColumns to retrieve and set column attributes.

Due to the variable number of levels and the resulting hierarchical display, the width of the first column is always treated as a minimum width.  The text portion of the first column will always be at least of the specified width, no matter what level the item is on.  This can result in the first column being much wider than the defined width.  Use GetOverheadWidth to calculate the actual width of the first column.

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).

See Also  C/C++ API  |  CategoriesNotifications

 


Feedback / comments / error reports for this topic
© 2009 - Softel vdm, Inc. - www.softelvdm.com