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.
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).
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.
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: /* ... */ } }
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:
HRESULT_FROM_WIN32
macro (see MSDN);ECODE_E_TREEVIEW
-- the error code indicating that
a tree view common control operation was failed;E_UNEXPECTED
(see MSDN).Out-of-memory may be informed by FoldersTree in two ways (Thanks to Microsoft® for providing us with several ways of reporting errors...):
E_OUTOFMEMORY
;NM_OUTOFMEMORY
message to the parent window of
the control and then (after you
processed this message) returning ECODE_E_TREEVIEW
.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.
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:
SHCONTF
enumeration.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.