Programming Introduction

General

All the functions and other entities (macroses, types etc.) of the library are declared in the header file fldtree.h. Link your program with the import library fldtree.lib and distribute your program together with fldtree.dll.

Names starting with ECODE_ and FoldersTree_ are reserved by Extreme CodeTM Software.

FoldersTree does not have its own window class, but uses the class of tree view common control (WC_TREEVIEW). In fact, FoldersTree control is a tree view common control which is initialized with FoldersTree_Init function and window messages for which are processed by FoldersTree_ProcessNotificationMessage function. (For details about initialization and processing of window messages see below.)

You must not change GWL_USERDATA (see MSDN about SetWindowLong) value associated with FoldersTree control and lParam member in TVITEM struct associated with items of FoldersTree control, because these are used internally by FoldersTree implementation. To set or get the value associated with the control use functions FoldersTree_SetData and FoldersTree_GetData. To set or get the value associated with a tree item use functions FoldersTree_SetItemData and FoldersTree_GetItemData.

Initialization and Destruction

You must initialize the FoldersTree class by calling FoldersTree_InitClass function and each instance of it by calling FoldersTree_Init function before using. After using you must free the resources associated with each instance and then free the resources associated with the class by calling calling FoldersTree_Destroy and FoldersTree_DestroyClass respecively.

Every item, inserted in a FoldersTree control not by FoldersTree API (but for example by TreeView_InsertItem) must be 'blessed' by calling FoldersTree_BlessItem function immediately after insertion (before calling any other FoldersTree API functions).

Functions

In the current version FoldersTree's functions have the WINAPI calling convention.

The functions working with COM interfaces and dynamically allocated COM objects follow the general COM calling conventions. The main rules is that in parameters are not deallocated by the called function, out parameters are allocated by the called function, and in out parameters are reallocated by the called function if necessarily. For the details see MSDN about Memory Management Rules in COM.

Window Messages Processing

To process window messages for FoldersTree you need to call the function FoldersTree_ProcessNotificationMessage in the window procedure of the parent window of the FoldersTree control for every notification message from the control.

It can be done as follows:

LRESULT CALLBACK ParentWindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
    LRESULT result;

    switch(uMsg)
    {
        /* ... */
        case WM_NOTIFY:
            if(/* the message is from one of FoldersTree controls */)
            {
                result = FoldersTree_ProcessNotificationMessage((NMHDR*)lParam);
                /* ... */
            }
            /* ... */
            return result;
        /* ... */
        default:
            /* ... */
    }
}

Reporting Errors

Many of FoldersTree's functions return a value of type HRESULT. Return value S_OK (which is equal to NOERROR, equal to 0) indicates success. Other return values indicate errors. For deeper details see MSDN about Error Handling in COM.

Value of HRESULT, returned by a FoldersTree API function, may be:

Out-of-memory may be informed by FoldersTree in two ways (Thanks to Microsoft® for providing us with several ways of reporting errors...):

Types of Items

Items in a FoldersTree control are divided into two classes:

All children of associated items must also be associated.

You must not create or delete children of associated items with ordinary tree view messages and macroses (because it would interfere with special functionality of associated items). You should create or delete them only with special FoldersTree functions.

However, you can do anything with not associated items, what you can do with items in an ordinary tree view control, except that you must not change lParam member of the corresponding TVITEM structure.

To insert an associated item at the root of the tree or as a child of a not associated item use FoldersTree_InsertFileSimple function.

Filtering

FoldersTree control filters shell objects deciding whether to include them in the tree. Filtering of shell objects to be included in the tree is two-stage:

  1. By filter flags. For description of these flags see MSDN about SHCONTF enumeration.
  2. By filter function which returns TRUE to include a shell object in the tree or FALSE to exclude. Filter function may be NULL which is equivalent to a function which always returns TRUE.

A shell object is included in the tree if it (and all its ancestors) passes both stages of filtering.

The default for filter flags is SHCONTF_FOLDERS, for filter function -- NULL.

See also: FoldersTree_SetFilterFlags, FoldersTree_SetFilterFunction.