SftTree/DLL 7.5 - Tree Control

SFTTREE_ITEM Structure

The SFTTREE_ITEM structure is used by the callback function SFTTREE_VGETITEM to return the requested item information to SftTree/DLL when a virtual data source is used.

typedef struct tagSftTreeITEM {

    unsigned short level;               // item level (0 is highest, no parent)
    
    short fShown;                       // item shown
    short fEnabled;                     // item enabled
    short fFakeExp;                     // item "fake" expandable
    short fOpened;                      // status of item at time of parent close

    int height;                         // item height (used by SftTree/DLL, not modifiable)

#if defined(SFTTREE_OBSOLETE_4)
    HBITMAP hLabel;                     // not used
    HBITMAP hItem;                      // not used
#else
    HBITMAP obsoletehLabel;             // OBSOLETE, Bitmap handle for label picture
    HBITMAP obsoletehItem;              // OBSOLETE, Bitmap handle for item picture
#endif
    SFTTREE_DWORD_PTR dwdData;          // user data for this item

    LPSFTTREE_ROW lpRow;                // row header info (optional)
    LPTSTR lpszRowHeader;               // row header text

    LPSFTTREE_CELL aCells;              // cell information

    LPTSTR * alpszString;               // array of pointers to strings for each cell (required)
    SFTTREE_ID key;                     // item ID
    short flag2;                        // item attributes
#define SFTTREEITEM_IGNORE          1   // ignored item (for optimal width calculation)
#define SFTTREEITEM_EDITIGNORE      2    // ignored item during cell editing 
#define SFTTREEITEM_EXPCOLLAPSEBUTTONHIDE 4 // hide expand/collapse button
    short minHeight;                    // minimum item height or 0 (variable height only)
    short maxHeight;                    // maximum item height or 0 (variable height only)
    SFT_PICTURE ItemPicture;            // item picture
    SFT_PICTURE LabelPicture;           // label picture
    // internal only
    DWORD heightCount;                  // origin stamp of height (internal use only)

} SFTTREE_ITEM, * LPSFTTREE_ITEM;
typedef const SFTTREE_ITEM * LPCSFTTREE_ITEM;

Members

level

The item's level. This field must be set to 0 and is reserved for future use.

fShown

The item's visibility status. This field must be set to TRUE and is reserved for future use.

fEnabled

The item's status. This field can be set to TRUE or FALSE (see GetItemStatus).

fFakeExp

The item's expand status (see GetItemExpandable). This field must be set to FALSE and is reserved for future use.

fOpened

The item's expand status at the time when its parent item was last closed. This field must be set to FALSE and is reserved for future use.

height

This field must be set to 0 and is reserved for future use.

hLabel

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

hItem

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

dwdData

An application defined value. This value can be retrieved using GetItemData. SftTree/DLL does not inspect this value in any other way.

lpRow

A pointer to a SFTTREE_ROW structure defining the item's row header. May be NULL if no row header information needs to be provided (even if row headers are visible).

lpszRowHeader

A pointer to the text to be used for the item's row header. May be NULL if no row header text needs to be provided (even if row headers are visible).

aCells

A pointer to SFTTREE_CELL structures (one for each column defined in the tree control). May be NULL if no additional cell information needs to be provided. If a pointer is present it must point to SFTTREE_CELL structures for all defined columns. The virtual callback function SFTTREE_VGETITEM provides the number of columns in the totCols argument.

alpszString

A pointer to an array of pointers to null-terminated characters. A pointer must be present for each defined columns. The virtual callback function SFTTREE_VGETITEM provides the number of columns in the totCols argument.

key

An application defined key (item ID) for this item. May be 0. This value can be retrieved using GetItemID. SftTree/DLL does not inspect this value in any other way.

flag2

Item attributes. The following values can be combined:

minHeight

The minimum height of the item in pixels in a variable height tree control. The minimum height overrides the usual item height, which is automatically determined based on item attributes. If this value is 0, no minimum height is defined.

This value is ignored in a fixed height tree control, where SetItemHeightMinMax can be used to define minimum and maximum item heights.

maxHeight

The maximum height of the item in pixels in a variable height tree control. The maximum height overrides the usual item height, which is automatically determined based on item attributes. If the maximum height is larger than the required height for the item, portions of the item may be vertically clipped. If this value is 0, no maximum height is defined.

This value is ignored in a fixed height tree control, where SetItemHeightMinMax can be used to define minimum and maximum item heights.

ItemPicture

Defines the item picture. If the hItem member defines a bitmap, ItemPicture is ignored.

item pictures are only displayed if the default item pictures have been defined using SetPictures. If default item pictures have been defined and ItemPicture is empty, the default picture is displayed.

LabelPicture

Defines the label picture. If the hLabel member defines a bitmap, LabelPicture is ignored.

heightCount

This field must be set to 0 and is reserved for internal use.

Comments

The SFTTREE_ITEM structure is used by the callback function SFTTREE_VGETITEM to return the requested item information to SftTree/DLL when a virtual data source is used.

All fields marked "reserved for future use" must be initialized to insure compatibility with future releases of SftTree/DLL.

The SFTTREE_ITEM structure is used to return item information to SftTree/DLL from the callback function SFTTREE_VGETITEM when a virtual data source is used. All information returned in this structure, including structure referred to by pointers in the SFTTREE_ITEM structure, must remain valid until the SFTTREE_VRELEASEITEM callback function is called by SftTree/DLL. This means that all data must be either in static memory or dynamically allocated. Temporary variables cannot be used to hold information.

SftTree/DLL supports "flat" lists only in virtual mode. Hierarchies cannot be represented in virtual mode.

Examples

C

/*------------------------------------------------------------------------------*/
/* This sample code implements the virtual data source member functions to      */
/* retrieve/release data from an external data source.                          */
/*------------------------------------------------------------------------------*/

// Callback of type LPFNSFTTREE_VGETITEM
void CALLBACK Tree_VirtualStorageGetItemCallback(HWND hwnd,
        SFTTREE_DWORD_PTR UserData, int totCols, LONG index, LPSFTTREE_ITEM FAR* lplpItem)
{
    // All item information (including all strings) MUST remain valid until VirtualStorageReleaseItem
    // is called. For this reason, the strings must be allocated using "calloc/malloc" or be static and CANNOT be
    // objects located on the stack (i.e., NO local variables).

    int col;
    static SFTTREE_ITEM m_WorkingItem;
    static TCHAR aText[3][80];           /* Cell text */

View Entire Sample Code

C++

        wsprintf(lpszBuffer, _T("A tooltip for column %d"), column);
        break;
    default:                             /* unhandled type (future expansion) */
        return;
    }
}

// Callback of type LPFNSFTTREE_VGETITEM
void CSampleView::VGetItem(int totCols, LONG index, LPSFTTREE_ITEM FAR* lplpItem)
{
    // All item information (including all strings) MUST remain valid until VReleaseItem
    // is called. For this reason, the strings must be allocated using "new" or be static and CANNOT be
    // objects located on the stack (i.e., NO local variables).

    memset(&m_WorkingItem, 0, sizeof(m_WorkingItem));
    m_WorkingItem.level = 0;             // Provide the level number (must be 0)

View Entire Sample Code

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