# SftTree/DLL 8.0 — Full Documentation

> SftTree/DLL is a tree control for the Windows™ operating system, offering multi-line, multi-column, hierarchical data displays for applications written using C, C++ and MFC.

Online documentation: https://softelvdm.com/Documentation/SftTree%20DLL%208%200

Complete API reference (separate file): https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-reference.txt

## Product Description

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/1_main*

SftTree/DLL is a tree control for the Windows™ operating system, offering multi-line, multi-column, hierarchical data displays for applications written [using C](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingc), C++ and MFC.

### SftTree/DLL Control

![Tree Components](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/components.gif)

SftTree/DLL offers many features from simple, graphical list box displays to complex hierarchical data displays:

- Hierarchical item display
- Fixed or [variable height](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_fixed_variable_height_items) items
- Single and/or [multiple text lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_multiline_cell_text) per [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) with word wrap
- [Cell merging](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_merging) across [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns)
- Single and [multiple selection](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_selections) built-in
- [Virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode) (for flat lists only)
- Owner-drawn cells and [content windows](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contentwindows) for complete control over cell contents
- Printing and Print Preview using SftPrintPreview/DLL
- [Splitter bar](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar)
- [ToolTips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tooltips) and [ScrollTips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_scrolltips)
- [Flyby](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_flyby) (hover) highlighting
- [Drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) with automatic scrolling, within and outside tree control
- Single and multiple [roots](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_rootlevel)
- [Expand/collapse buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons)
- [Column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) as titles or buttons with images and text
- [Column footers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_footers) as titles or buttons with images and text
- Resizable and [reorderable columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_drag_drop)
- Individual column colors
- Fixed width or [open ended](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_openended) last column
- [Row headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) as titles or buttons with images and text
- [Row/column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_row_column_header) as title or button with images and text
- [Row/column footer](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_row_column_footer) as title or button with images and text
- Selectable column alignment (left, right, center)
- [Sorting](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_sortdependents)
- [Cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) using Windows controls
- [Tree items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items) with individual attributes
- All images fully customizable
- [GDI+](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_gdiplus) image support (PNG, alpha-blended images)
- [Tree lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_tree_lines) fully customizable
- Windows visual styles (themes) support
- [Dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) support, automatically following the Windows light/dark setting
- [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) [accessibility](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility) support
- Per-Monitor v2 DPI awareness with automatic scaling of images and pixel dimensions
- Built-in UI Automation provider for screen reader support (Narrator, NVDA, JAWS and others)
- Documentation for AI coding assistants - an offline, full-text API reference formatted for large-language-model grounding, plus an AGENTS.md pointer file, so assistants such as Claude, GitHub Copilot and Cursor can answer questions and generate code against the complete API
- [Right-to-left reading support](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_rtl)
- Support for C and C++ (MFC) using Visual Studio
- Support for Windows 10 and above, 64-bit, 32-bit and ARM64 applications
- Complete implementation, not a sub/superclassed Windows control
- No predefined maximum number of items

### Source Code

The source code for the MFC C++ classes for tree control access is supplied. Any application that you develop as a licensed user can use SftTree/DLL royalty-free (some restrictions apply), as long as only the DLL is shipped with your application.

### Languages Supported

SftTree/DLL supports C, C++ and other languages when using direct calls to the DLL. SftTree/DLL can be called using the definitions provided in the supplied header file. SftTree/DLL is shipped with class definitions which support the Microsoft Foundation Class Library (MFC).

### Environments Supported

Processor support depends on the installed and purchased product versions.

- 64-bit support when running Windows 10 and above with Intel 64-bit processors
- 32-bit applications on Windows 10 and above
- ARM64 support when running Windows 11 and above on ARM64 processors

UNICODE support is available for all platforms.

The product supports the same easy to use API on all platforms.

### Royalties

Any application that you develop can use SftTree/DLL royalty-free in run-time only mode; design-time features are not available. Each user (developer) who needs access to any portion of the product must license a copy of SftTree/DLL.

### AI / LLM Documentation

The complete SftTree/DLL documentation is also published in an AI/LLM-readable format, following the [llms.txt convention](https://llmstxt.org). The index covering all Softel vdm products is at [https://softelvdm.com/llms.txt](https://softelvdm.com/llms.txt).

The product installation includes an AGENTS.md file at the installation root, which points AI coding assistants at the product's online guide and API reference. The documentation is always read online, as it is updated between product releases.

## New Features

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_newfeatures*

SftTree/DLL 8.0 is virtually 100% upward compatible from version 7.5 and earlier versions. The following major enhancements have been made available with SftTree/DLL 8.0:

- New built-in [UI Automation](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility) provider exposes tree structure, column and [row headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers), selection and expand / collapse state to Narrator, NVDA, JAWS and other screen readers. [Split tree controls](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar) appear as a single unified data grid to assistive technologies. No caller opt-in is required.
- New [Announce](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_announce) function pushes short application-status text ("3 rows added", "Filter cleared", "Saved") to attached screen readers through a UI Automation [notification](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) event.
- New [dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) support with AUTO / ON / OFF setting (see [SetDarkMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_darkmode)). The AUTO setting tracks the Windows "Choose your mode" accessibility setting.
- New [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) accessibility support with AUTO / ON / OFF setting (see [SetHighContrastMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_highcontrast)). The AUTO setting tracks the Windows High Contrast setting.
- New [Per-Monitor DPI](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dpi) v2 awareness. Row height, [grid lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_grid_lines), scroll-bar metrics, drag thresholds, 3D frames, the column drop-down button, the resize handle and the control-owned expand / collapse glyphs scale automatically with the current monitor DPI. See [GetDPI](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_dpi) and the new SFTTREEN_DPI_CHANGED notification.
- New [SetImageScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_imagescaling) function provides a one-call opt-in to automatic DPI scaling of every image the control draws - caller-supplied [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) / label / item / row-header / column-header / column-footer pictures, plus / minus bitmaps and user-supplied tree button bitmaps, as well as control-owned glyphs.
- New [SetPixelScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_pixelscaling) function provides a one-call opt-in to treating caller-supplied pixel dimensions (column widths, indentation, row-header width, horizontal extent, item heights, splitter offset) as 96-DPI reference values. Stored values stay in 96-DPI units so serialized configurations remain portable across monitors of different DPI.
- New [SetSplitterOffsetMin](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_splitteroffsetmin) function sets a minimum splitter bar offset for split tree controls, preventing the user from hiding the left pane.
- New [SetSizeBox](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_sizebox) function controls whether a size box is shown in the tree control's lower-right corner, allowing the user to resize the control by dragging the corner grip. The companion GetSizeBoxActive function reports whether the user is currently dragging the size box, so the host can suspend layout updates during interactive resizing.
- New SFTTREEN_DARKMODE_CHANGED notification is sent when the active dark mode state flips.
- New SFTTREEN_HIGHCONTRAST_CHANGED notification is sent when the Windows High Contrast accessibility state flips.
- New SFTTREEN_DPI_CHANGED notification is sent to Per-Monitor v2 DPI-aware hosts when the control's monitor DPI changes.
- The [SFTTREE_OWNERDRAW](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_ownerdraw) structure exposes the current dark mode state (fDarkMode), current effective DPI (dpi) and current high contrast state (fHighContrast) on every owner-draw callback.
- New documentation for AI coding assistants. SftTree/DLL 8.0 includes an offline, full-text API reference formatted for large-language-model grounding, together with an AGENTS.md pointer file, so AI assistants such as Claude, GitHub Copilot and Cursor can answer questions and generate code against the complete SftTree/DLL API.

## Installing SftTree/DLL

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_installation*

When you are ready to install SftTree/DLL:

1. Run the setup application - The download location is provided either with your license information at the time of purchase or you can download the [product demo](https://softelvdm.com/Store/Product-Detail/Name/SftTree%20DLL%208%200?ProductId=3125). Both the product and demo setup applications are identical and can be used intercheangably.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/installation.png)

2. Follow the instructions on the installation dialogs. Please note that the single developer version of SftTree/DLL can only be installed by one user on one system. Multiple developer licenses and site licenses are available. Contact [Softel vdm, Inc.](https://softelvdm.com/About) for more information.

3. During the installation, you will be prompted to register the product using the License Manager application. Without proper registration, the product will not run. Once you are a registered user, you can take advantage of our [product support](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contactsoftel), free maintenance versions and you will receive information regarding new releases.

4. Once SftTree/DLL has been successfully installed, you will find a new program group *SftTree/DLL 8.0*. Entries for the SftTree/DLL Demo, sample applications and shortcuts to the documentation have been added.

## Upgrading to Version 8.0

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_upgrading*

Only a minimal conversion is required when upgrading from an earlier version of SftTree/DLL to SftTree/DLL 8.0. SftTree/DLL 8.0 is virtually 100% source compatible with SftTree/DLL 7.5. Your application(s) must be recompiled to use SftTree/DLL 8.0. Additional upgrade requirements exist when [upgrading from SftTree/DLL 4.0](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_upgrading_from40) and older versions. Please see "Upgrading from SftTree/DLL 4.0" for more information.

SftTree/DLL 8.0 and older versions of SftTree/DLL can coexist in the same application to make the conversion as easy as possible, however, they cannot be used in the same source code file.

Windows versions prior to Windows 10 are no longer supported. For support of older platforms, an earlier version of SftTree/DLL must be used instead.

### Upgrading to Version 8.0

To allow for SftTree/DLL 8.0 to coexist with older versions on the same system, the Dlls have been renamed and a new window class is used.

SftTree/DLL 8.0 is source code compatible with older releases of SftTree/DLL, provided the following changes are made in existing applications:

### Converting an Existing Application

The conversion effort to upgrade an application using SftTree/DLL 7.5 is very minimal. Most applications will only have to change the window class name used in DIALOG resources (see below).

### Window Class Change

In SftTree/DLL 7.5 (the release prior to SftTree/DLL 8.0), the window class used for SftTree was SftTreeControl75 (SftTreeSplit75). These window classes have been dropped and have been renamed to **SftTreeControl80** (**SftTreeSplit80**).

Any DIALOG resources that use the old window classes must be changed to use SftTreeControl80 and SftTreeSplit80. Without this change, the dialogs will not be displayed.

If the window class name was "hard-coded" in calls to CreateWindow(Ex), the class name must also be changed. The preferred method is to use the preprocessor symbol [SFTTREE_CLASS](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttree_class) ([SFTTREESPLIT_CLASS](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttreesplit_class)).

#### Dll And Lib Files Name Change

The Dlls and Lib files have been renamed for this new release. For the new file names, please see the section "[Building Applications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp)".

When linking statically, the libraries Gdiplus.lib and Msimg32.lib must be added to the linker project settings (see the section "Building Applications").

### What's New in 8.0

SftTree/DLL 8.0 adds four major [accessibility](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility) and rendering features that are enabled automatically on existing controls with no API changes required. Each has a dedicated guide:

- Built-in UI Automation support so screen readers (Narrator, NVDA, JAWS) can read and navigate the tree - see Accessibility (Screen Readers).
- [Dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) that follows the Windows 10 "Choose your mode" setting, or can be forced per control - see Dark Mode.
- [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) accessibility support with strict color-policy compliance - see High Contrast.
- Per-Monitor v2 DPI awareness with two optional opt-in flags for automatic [image scaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dpi) and caller-supplied pixel-dimension scaling - see Per-Monitor DPI and Scaling.

Existing applications inherit dark mode, high contrast, screen-reader support and automatic control-owned metric scaling by simply recompiling against the 8.0 [headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) and libraries. To also scale caller-supplied images and pixel dimensions automatically, one-line opt-in calls are available - see [SetImageScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_imagescaling) and [SetPixelScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_pixelscaling).

## Upgrading from SftTree/DLL 4.0

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_upgrading_from40*

> This topic only applies if you are upgrading from 4.0 or an older version. If you are upgrading from 4.5 or a newer version, please see "[Upgrading to Version 8.0](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_upgrading)"

Only a minimal conversion is required when upgrading from SftTree/DLL 4.0 (or an earlier version) to SftTree/DLL 8.0. SftTree/DLL 8.0 is virtually source compatible with older releases of SftTree/DLL. Your application(s) must be recompiled to use SftTree/DLL 8.0.

SftTree/DLL 8.0 and an older version of SftTree/DLL can coexist in the same application to make the conversion as easy as possible, however, they cannot be used in the same source code file.

### Discontinued Features

- Support for Windows 95, 98 and ME has been dropped
- Support for Borland C++ has been dropped
- Support for Windows SDK Dialog Editor has been dropped
- 16-bit support has been dropped. SftTree/DLL 4.0 was the last release supporting 16-bit applications.

### Upgrading to Version 8.0

Even though SftTree/DLL 8.0 is not completely upward compatible, the conversion effort is very minimal. Some structures used in earlier releases of SftTree have been increased in size, resulting in the requirement to recompile your source code. To allow for SftTree/DLL 4.0 and this new version to coexist when used by multiple applications, the DLLs have been renamed and a new window class is used.

SftTree/DLL 8.0 is source code compatible with older releases of SftTree/DLL, provided the following changes are made in existing applications:

### Converting an Existing Application

The conversion effort to implement SftTree/DLL 8.0 in an application that currently uses version 4.0 (or older) is minimal. Most applications will only have to change the window class name used in DIALOG resources (see below).

### Window Class Change

In releases prior to SftTree/DLL 8.0, the window class used for SftTree was SftTreeControl (SftTreeSplit) or SftTreeControl32 (SftTreeSplit32). These window classes have been dropped and have been renamed to **SftTreeControl80** (**SftTreeSplit80**).

Any DIALOG resources that use the old classes must be changed to use SftTreeControl80 and SftTreeSplit80. Without this change, the dialogs will not be displayed.

If the window class name was "hard-coded" in calls to [Create](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_csfttree_create) or CreateWindow(Ex), the class name must also be changed. The preferred method is to use the preprocessor symbol [SFTTREE_CLASS](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttree_class) ([SFTTREESPLIT_CLASS](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttreesplit_class)).

#### Dll And Lib Files Name Change

The DLLs and LIB files have been renamed for this new release. For the new file names, please see the section "[Building Applications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp)".

#### Using SFTTREE_OBSOLETE_4

A number of structure members and API functions which only accepted bitmap handles have been replaced with the new [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) type which supports bitmaps, icons and ImageLists.

If these are used, compile errors will result, alerting you to the fact that an obsolete feature is used.

[SFTTREE_CELL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_cell) structure - [cell bitmap](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_bitmap) - the *hBmp* member is now called *CellPicture1*

[SFTTREE_ROW](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_row) structure - [row header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) bitmap - the *hBmp* member is now called *RowPicture1*

[SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex) structure - [column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) bitmap - the *hBmp* member is now called *Picture1*

[SFTTREE_ITEM](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_item) - [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode) - the *hLabel* and *hItem* members are now called *[ItemPicture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itempicture)* and *LabelPicture*

The preprocessor symbol [SFTTREE_OBSOLETE_4](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttree_obsolete_4) can be used to make these old structure members accessible to applications, so no conversion is required. By defining this symbol (using #define SFTTREE_OBSOLETE_4) these structure members can be used as in earlier releases. At the same time you can also use the new SFT_PICTURE type. Once you are ready to use the new SFT_PICTURE type throughout, simply remove SFTTREE_OBSOLETE_4.

At the same time, without defining SFTTREE_OBSOLETE_4, any use of the bitmap members will cause a compile error. While you are encouraged to convert to the new SFT_PICTURE structure, this is not required as long as you define SFTTREE_OBSOLETE_4.

#### DWORD and SFTTREE_DWORD_PTR

The type DWORD which was used in various structures and API calls in earlier releases has been replaced with the new type [SFTTREE_DWORD_PTR](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/typedef_sfttree_dword_ptr) in order to support 64-bit applications. This does not affect existing 32-bit applications as this type is identical to a DWORD.

#### SFTTREE_DRAWINGINFO

The structure members *hLabelBitmap* and *hItemBitmap* of the [SFTTREE_DRAWINGINFO](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_drawinginfo) structure are no longer supported. [SetItemLabelPicture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemlabelpicture) and SetItemPicture should now be used instead.

## Overview

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_overview*

Depending on the programming language used, the steps necessary to add a tree control to an application differ somewhat, but the following steps outline the basic method:

First, a tree control is added to a dialog using a resource editor (see "[Creating a Dialog Resource](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_vc)"). When the dialog is later used in an application, the tree control is automatically created and can be accessed using the supplied API. A tree control can also be created outside of a dialog. This is documented in the language specific programming sections "[Using C](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingc)" and "[Using C++/MFC](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingcpp)".

Once the tree control has been created, the API functions documented in sections "[C/C++ API](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api)" and "[C/C++ API (By Category)](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_categories)" can be used to add items, define attributes, enable [tree components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components), etc. The following [samples](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_samples) create a very minimal tree control with three items as pictured below. This example can easily be extended by adding a few calls to define [item pictures](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_item_bitmap) and other tree components to change the appearance of the tree control.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/overview1.gif)

> **Note:** [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) should be used to design the tree control look. With the SftTree/DLL Wizard, most source code is generated for you.

SftTree/DLL 8.0 supports built-in [accessibility](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility): the tree is exposed to screen readers as a UI Automation data grid (see Accessibility (Screen Readers)), follows the Windows "Choose your mode" setting for [dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) (see Dark Mode), honors the [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) accessibility setting (see High Contrast), and is fully Per-Monitor v2 DPI aware (see [Per-Monitor DPI and Scaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dpi)).

### C Sample

```
HWND hwndTree;
int index;
hwndTree = GetDlgItem(hwndDialog, IDC_TREE); // Get the tree window handle
SftTree_SetShow3D(hwndTree, TRUE); // Use 3D display mode
index = SftTree_AddString(hwndTree, "The First Item");
index = SftTree_AddString(hwndTree, "The Second Item");
SftTree_SetItemLevel(hwndTree, index, 1);
index = SftTree_AddString(hwndTree, "The Third Item");
SftTree_SetItemLevel(hwndTree, index, 2);
SftTree_RecalcHorizontalExtent(hwndTree); // For optimal horizontal scrolling
```

### C++/MFC Sample

```
CSftTree m_Tree;
int index;
m_Tree.SubclassDlgItem(IDC_TREE, this); // Connect C++ object to window
m_Tree.SetShow3D(TRUE); // Use 3D display mode
index = m_Tree.AddString("The First Item");
index = m_Tree.AddString("The Second Item");
m_Tree.SetItemLevel(index, 1);
index = m_Tree.AddString("The Third Item");
m_Tree.SetItemLevel(index, 2);
m_Tree.RecalcHorizontalExtent(); // For optimal horizontal scrolling
```

## Tree Components

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components*

The following describes the individual components that are available in a SftTree/DLL tree control. All components, except for the first column displaying an item"s text, are optional. By turning all optional components off, the SftTree/DLL tree control can visually act as a simple list box.

## Tree Items

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items*

An item (also called row) is the term used to refer to one element added to the tree control and includes the [row header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers), all pictures, [tree lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_tree_lines), [expand/collapse buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons) and all [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell).

Items are added using the [AddString](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_addstring) and [InsertString](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_insertstring) functions.

Items within tree controls have relationships to other items based on the level they are on. This determines how items are connected to each other.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/treeitems1.gif)

The following table defines the terms used throughout to identify relationships and the connecting lines drawn for each type:

| Term | Description |
| --- | --- |
| [Dependents](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_dependents) | A dependent is an item which has a [parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent). The item is said to be a dependent of the parent item. Dependents can be parent items themselves or [leaf items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_leaf). A dependent cannot be at the [root level](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_rootlevel). The [GetDependent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_dependent) function can be used to retrieve dependent item information for an item. |
| [Expand](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_expand) Status | The [expand status](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_expandstatus) indicates whether dependent items are visible or not. A parent item that has one or more visible dependents is considered expanded. If a parent item is expanded, all its immediate dependents, i.e., all dependents on the next lower level are visible. If a parent item is collapsed, no immediate dependents are visible. The [GetItemExpand](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemexpand) function returns the current expand status of an item. |
| Leaf Item | A leaf item is an item which has no dependents, i.e., it is not a parent item. Leaf items may have [sibling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_siblings) and parent items. |
| [Parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_parent) | A parent item can be located at any level. In order to become a parent item, an item must be marked expandable (using [SetItemExpandable](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemexpandable)) or have one or more dependents, which are items that immediately follow the parent item and are on a lower level. A parent item may be expanded and collapsed. Expanding a parent item means making its immediate dependents (items on the next lower level) visible. Collapsing a parent item means hiding all its dependents (on all lower levels). The Expand and [Collapse](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_collapse) functions are used to expand and collapse items. Parent items may have sibling and parent items. The GetParent function returns an item's parent index. |
| Root Level | Any item without parent is at the root level, usually level 0. Multiple items can be at the root level, parent items or leaf items. [GetItemLevel](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemlevel) can be used to retrieve an item's level number. |
| Siblings | A sibling is an item which precedes or follows another item on the same level with the same parent. An item can have zero or more sibling items. Sibling items can be parent and leaf items. The [GetSibling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_sibling) functions can be used to retrieve sibling information about an item. |
| Top Parent | A parent item is a [top parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_topparent) (or top level parent) if it has no parent of its own. Top parent items may have sibling items. The [GetTopIndex](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_topindex) function can be used to retrieve the topmost parent item. |
| Visibility Status | The [visibility status](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_visibilitystatus) indicates whether an item is visible or not. An item is considered visible if its immediate and all other parent items are expanded. An item is considered visible even if it isn't currently displayed in the window client area. The [GetItemShown](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemshown) and SetItemShown functions can be used to define an item's visibility status. |

When adding items to a tree control, all that is required from an application is that the level numbers are set. The SftTree/DLL tree control automatically determines the correct relationships and draws connecting lines appropriately. Applications can then interrogate the tree control about relationships and don't have to manage these themselves.

## Expanding/Collapsing Items

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse*

SftTree/DLL supports expanding and collapsing [tree items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items) with minimal application intervention. Items in a tree control are managed as a linear list, or array of items. The application can expand and collapse items without having to add or remove items. The tree control takes care of hiding and making items visible as needed. The [expand/collapse buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons) are automatically displayed as needed for [parent items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent) with [dependent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_dependents) items.

Under program control, an application responds to SFTTREEN_LBUTTON-type [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) and expands and collapses items using [Collapse](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_collapse), [Expand](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_expand) or [SetItemExpand](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemexpand). The current expand/collapse status of an item can be retrieved using GetItemExpand.

An application can also fully control expanding and collapsing tree items. Rather than adding all items initially, including dependent items (child items), an application can add all parent items and mark them as expandable without actually adding the dependent items (see [SetItemExpandable](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemexpandable)). Then, once the application receives a SFTTREEN_LBUTTON-type notification, signaling that the user wants to expand a parent item, the application can insert the dependent items.

## Fixed / Variable Height Items

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_fixed_variable_height_items*

There are two methods by which a tree control determines the height of an item in the list. Based on the [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) SFTTREESTYLE_VARIABLE, a variable height or fixed height tree control is created.

### Fixed Height Tree Control

In a fixed height tree control, each item has the same height. SftTree/DLL determines the best item height for all items by analyzing the [default font](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_font) height (WM_SETFONT, CWnd::SetFont), the number of text lines ([SetItemLines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemlines)), the registered [cell picture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_bitmap) height ([SetCellInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_cellinfo)), 3D display mode ([SetShow3D](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_show3d)), the registered [label picture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_label_bitmap) height ([SetItemLabelPicture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemlabelpicture)), the registered [plus/minus bitmap](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_plusminus_bitmap) height ([SetPlusMinus](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_plusminus)), the [expand/collapse button](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons) bitmap height, the tree line style ([SetTreeLineStyle](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_treelinestyle)), the registered [item picture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_item_bitmap) height ([SetItemPicture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itempicture)), grid line style ([SetShowGrid](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_showgrid)), the [row header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) font ([SetRowHeaderFont](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowheaderfont)), the registered row header picture height ([SetRowInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowinfo)) and the number of text lines ([RowHeaderLines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowheaderlines)). If a component is not used, it is not considered to determine the best height.

[Cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) fonts (SetCellInfo) are not considered. If a cell font is used in a fixed height tree control, the application must insure that the cell font is not larger than the default font.

All row header pictures must be the same height and width (SetRowInfo).

All label pictures must be the same height and width as the registered label picture (SetItemLabelPicture).

All item pictures must be the same height and width (SetItemPicture).

All cell pictures in all [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) must be the same height and width as the registered cell picture (SetCellInfo).

An application can override the height of all items using the [SetItemHeightMinMax](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemheightminmax) function.

### Variable Height Tree Control

In a variable height tree control, items have varying heights. Each item's height is individually recalculated as attributes change. This places an additional performance constraint on the tree control, so the window style SFTTREESTYLE_VARIABLE should only be used when variable height items are necessary.

SftTree/DLL determines the best item height for each item by analyzing the default font height (WM_SETFONT, CWnd::SetFont), the cell font and cell picture height for each column (SetCellInfo), the number of text lines (SetItemLines) and word wrap style for each cell ([SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns)), 3D display mode (SetShow3D), the item's label picture height (SetItemLabelPicture), the registered plus/minus bitmap height (SetPlusMinus), the expand/collapse button bitmap height, the tree line style (SetTreeLineStyle), the item's item picture height (SetItemPicture), grid line style (SetShowGrid), the row header font (SetRowHeaderFont), the item's row header picture height (SetRowInfo) and the maximum number of text lines (RowHeaderLines). If a component is not used, it is not considered to determine the best height.

An application can override the item height using the SetItemHeightMinMax function or for [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode), using the *minHeight*, *maxHeight* members of the [SFTTREE_ITEM](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_item) structure.

## Content Windows

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contentwindows*

Each [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) can contain a child window. This child window becomes the content for the cell and is displayed in its place. Possible examples of such content windows are Flash controls, Windows Media Player, Web Browser controls, dialogs, etc. Almost any type of control or window can be used provided it can be represented by a window handle HWND. SftTree/DLL automatically resizes, hides and disables content windows as needed.

A cell receives a content window by assigning its window handle to the *hwndCell* member of the [SFTTREE_CELL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_cell) structure using [GetCellInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_cellinfo)/SetCellInfo. The *flag2* member of the SFTTREE_CELL structure can be used to control resizing and disabling of the content window using the SFTTREECELL_CONTENT_KEEPSIZE and SFTTREECELL_CONTENT_DISABLE values.

The included [ContentWindows sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_samples) demonstrates how various controls and dialogs can be embedded in the tree control.

Limitations: [Tooltips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tooltips) are not shown for cells based on a content window and content windows will not be printed when SftTree/DLL is used with SftPrintPreview/DLL. Excessive use of content windows may exhaust available system resources.

## Virtual Mode

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode*

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

The tree control can be used to display flat lists (without hierarchy) with up to 2,000,000,000 items. [Bitmaps](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_bitmaps), pictures, colors and all tree control data and attributes are provided by application supplied callback functions which use a [virtual data source](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_datasource). This eliminates lengthy initialization when many items are to be displayed.

## Virtual Data Source

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_datasource*

> SftTree/DLL supports "flat" lists only in [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode). Hierarchies cannot be represented in virtual mode.

A tree control can be populated using conventional methods by adding items one at a time using [AddString](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_addstring) or [InsertString](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_insertstring). While there is no built-in limit to the number of items added this way, the more items added, the longer it takes.

If an application already has all items in memory or mapped to a database or some other data source from which items can readily be retrieved, there is no need to add all items to the tree control. A callback function can be supplied to the tree control (see [VirtualInitialize](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_virtualinitialize)). This callback is a "virtual data source". The callback is called by the tree control for each item as it is needed. Usually, only items that are visible in the tree control window need to be retrieved, ranging from one item to maybe a dozen, depending on the size of the tree control. This results in essentially no time spent populating the tree control.

The tree control can be used to display flat lists (without hierarchy) with up to 2,000,000,000 items. [Bitmaps](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_bitmaps), pictures, colors and all tree control data and attributes are provided by application supplied callback functions. This eliminates lengthy initialization when many items are to be displayed.

The virtual data source callback routine can provide all the information to SftTree/DLL, even [cell pictures](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_bitmap), fonts, etc.

When attaching a [content window](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contentwindows) to a [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell), the [MakeContentWindow](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_makecontentwindow) function must be called to notify the tree control. Otherwise, content windows will not be positioned correctly.

Some functions are not available when a virtual data source is used. Most functions which update item or cell information can not be used and return an error. The application cannot update items in the tree control, it must update its (external) data source instead. By using the provided functions [VirtualItemChanged](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_virtualitemchanged) and [VirtualCount](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_virtualcount), an application can notify the tree control that items or item count have been modified by the application.

## Split Tree Control - Splitter Bar

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar*

A split tree control is a tree control that has multiple [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) and a splitter bar. The splitter bar is used to separate columns so the columns can be scrolled individually. Both the left and right panes can be scrolled horizontally. This is most useful to lock the first column while being able to scroll the remaining columns horizontally.

A split tree control uses the window class [SFTTREESPLIT_CLASS](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttreesplit_class) and the C++ class [CSftTreeSplit](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api). C applications must use the functions prefixed by SftTree**Split**_. Using the incorrect C++ class or C functions will cause unpredictable behavior.

The [SetSplitColumn](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_splitcolumn) function defines the number of columns displayed in the left pane of a split tree control. The width of the splitter bar can be defined using [SetSplitterWidth](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_splitterwidth). The number of columns displayed in the left pane is defined using SetSplitColumn.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/splitter1.gif)

Both panes of a split tree control are synchronized by SftTree/DLL. Internally, the left and right panes are independent tree controls, which communicate with each other to keep their display styles and data contents synchronized. These tree controls are child windows of the split tree control. While the left and right panes exchange information to keep their display and attributes updated, it is possible to affect each pane individually through the window handle or object (see [GetLeftWindow](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_leftwindow) and [GetRightWindow](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rightwindow)).

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Right-To-Left Reading Support

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_rtl*

When the extended style [WS_EX_RIGHT](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles_ext) is given, the tree control will support right-to-left reading where the tree hierarchy is displayed on the right hand side of the control. [Columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) are displayed from right to left, so column 0 is shown on the right side, with column 1 to its left, and so forth. The vertical scroll bar can be positioned along the left edge of the control by using the extended window style WS_EX_LEFTSCROLLBAR.

The extended window style WS_EX_LEFTSCROLLBAR is only supported by certain international Windows versions, such as Hebrew and Arabic Windows.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/rtl1.gif)

All tree control attributes and functions are fully supported when right-to-left reading support is used. In this documentation, the terms "left" and "right" should be reversed when the WS_EX_RIGHT [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) is given.

If a [split tree control](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar) is used, the tree control pane containing the hierarchy is displayed on the right side. Normally, without WS_EX_RIGHT, the hierarchy is shown in the left pane.

Using right-to-left reading support is transparent to the application, but column alignment should be adjusted by the application.

## Using Themes

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_using_themes*

With Windows XP, Windows themes were introduced. Windows themes can be selected by the user using the Control Panel.

If a theme is selected, the display of user interface controls, such as SftTree/DLL, adapts to the current display theme. Themes can provide various display styles for the same control. With themes active, Windows renders (paints) the control:

|  |  |
| --- | --- |
| ![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/theme1.gif) | ![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/theme2.gif) |
| Without Themes | Windows XP (and above) With Themes |

By using the [SetUseThemes](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_usethemes) function, SftTree/DLL adapts to the current theme used. If set to FALSE, themes are not honored and the control is rendered using the built-in style.

SftTree/DLL makes it easy to use the same application across all supported platforms. If Windows themes are not available, the control will simply use its built-in display style, otherwise it will fully exploit Windows themes.

To prepare an application for proper themes support, the tree control should be designed using the [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) under Windows XP  or above. It should be viewed in the SftTree/DLL Wizard both with and without themes (see the *Visuals 1* tab, *Use Themes (on Windows XP and above)* option) to make sure that the defined tree control is visually satisfactory in both cases.

Tree controls designed using the SftTree/DLL Wizard for use on Windows XP and above with themes will work identically on all other platforms, even when themes support is not available.

Keep in mind that numerous tree control definitions, particularly relating to colors, have no effect when themes are active. You can find out if a specific tree control setting has any effect with themes active by consulting the detail information in this documentation.

Windows themes are automatically suppressed when [Dark Mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) or [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) is active on the tree control. See Dark Mode and High Contrast for details on the alternative rendering paths used in each case.

## Dark Mode

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode*

SftTree/DLL 8.0 supports dark mode. By default the tree control uses the light palette; an application opts in by calling [SetDarkMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_darkmode) with AUTO so the control follows the Windows 10 "Choose your mode" setting automatically - users who have selected Dark see a dark color palette and users who have selected Light see the traditional palette, and the control re-renders when the user flips between them. SetDarkMode with ON always uses the dark palette regardless of the Windows setting.

What changes in dark mode: the tree background, item text, [grid lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_grid_lines), selection highlight, [column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers), [column footers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_footers), [row headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers), row/column-header corner, row/column-footer corner and the [splitter bar](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar) (in a split tree control) all switch to dark-palette colors. [Cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) edit controls, [tooltips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tooltips) and the Wizard's editors inherit the dark palette automatically via *DarkMode_Explorer* theming.

The tree control's dark mode setting has three values (see SetDarkMode):

|  |  |
| --- | --- |
| **AUTO** | Follow the Windows "Choose your mode" setting. The control re-renders when the system setting flips. |
| **ON** | Always use the dark palette, regardless of the Windows setting. Useful when the hosting application has its own Light / Dark toggle and wants the tree to follow it. |
| **OFF** (default) | Always use the light palette, regardless of the Windows setting. Useful when the application does not yet support dark mode end-to-end and mixing dark and light controls would look wrong. |

SFTTREEN_DARKMODE_CHANGED is sent to the parent window each time the active dark mode state flips (AUTO mode only) so the application can repaint its own chrome around the tree control. IsDarkModeActive reports the current state at any time.

Caller-supplied color overrides ([SetCtlColors](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_ctlcolors), per-column colors, permanent background, odd-row colors, selection colors, grid colors) are still honored in dark mode - the control does *not* override application-chosen colors. If you need specific cells to stand out in dark mode, pick accent colors that read well on both a light and a dark background (mid-tone saturated values in the RGB 30-210 range tend to work in both).

[Windows themes](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_using_themes) are suppressed while dark mode is active. [Header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_header), footer and other chrome elements fall back to the tree's built-in dark-aware GDI rendering path so they match the control's dark palette instead of the system's light-themed header style.

Owner-draw code is responsible for its own dark-mode compliance. Every *[SFTTREE_OWNERDRAW](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_ownerdraw)* callback receives a **fDarkMode** field; owner-draw code should inspect it on each paint and pick its own colors accordingly. The default render path handles non-owner-drawn areas automatically.

### Host dialog integration

The tree control follows the dark mode setting at the **control** level. The hosting dialog itself - title bar, dialog background, static labels, group boxes, edits and any standard Win32 controls placed alongside the tree - also needs to be wired into dark mode for the dialog to render coherently. The shared [SftDarkMode](https://softelvdm.com/Documentation/SftDarkMode/Topic/1_main) helper provides that integration: a single header (SftDarkMode.h) used by every Softel vdm DLL product that handles dialog title bars, WM_CTLCOLOR* responses, the Windows "Choose your mode" toggle, and dark NC scrollbars on standard controls.

A typical adoption is four call sites: [SftDarkMode_Init](https://softelvdm.com/Documentation/SftDarkMode/Topic/function_init) at process startup, [SftDarkMode_ApplyToDialog](https://softelvdm.com/Documentation/SftDarkMode/Topic/function_applytodialog) from each WM_INITDIALOG, [SftDarkMode_HandleDialogMessage](https://softelvdm.com/Documentation/SftDarkMode/Topic/function_handledialogmessage) routed from each dialog procedure, and an optional [SftDarkMode_SetActive](https://softelvdm.com/Documentation/SftDarkMode/Topic/function_setactive) when the application exposes its own Light / Dark toggle.

Platform note: Dark mode requires Windows 10 or later. On earlier platforms the setting is stored but has no visual effect.

## High Contrast

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast*

Windows High Contrast is an [accessibility](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility) setting, not a visual preference. Users who enable it have committed to a specific high-contrast color scheme for everything on screen, and Microsoft's accessibility guidelines require applications to let the user's scheme win over any application-chosen colors. SftTree/DLL 8.0 follows this rule automatically.

When Windows High Contrast is active, the tree control:

- renders backgrounds in *COLOR_WINDOW*, text in *COLOR_WINDOWTEXT*, selection in *COLOR_HIGHLIGHT* / *COLOR_HIGHLIGHTTEXT*, [grid lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_grid_lines) in *COLOR_BTNSHADOW*, and similar for other roles,
- ignores caller-supplied color overrides ([SetCtlColors](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_ctlcolors), per-column colors, permanent background, odd-row colors) on the default render path - the user's contrast theme wins,
- suppresses [Windows themes](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_using_themes). [Column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers), [column footers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_footers) and [row headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) fall back to a non-themed GDI path that honors system colors directly.

The tree control's high contrast setting has three values (see [SetHighContrastMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_highcontrast)):

|  |  |
| --- | --- |
| **AUTO** | Follow the Windows High Contrast setting. The control re-renders when the setting flips. |
| **ON** | Always use the system palette, regardless of the Windows High Contrast setting. Useful for testing or for applications that want consistent high-contrast rendering for a specific tree. |
| **OFF** (default) | Ignore the Windows High Contrast setting and render normally. Not recommended in shipping applications - it means users with accessibility needs will see rendering that does not comply with their contrast theme. |

SFTTREEN_HIGHCONTRAST_CHANGED is sent to the parent window each time the active state flips (AUTO mode only) so the application can repaint its own chrome to match. IsHighContrastActive reports the current state at any time.

Owner-draw code is responsible for its own high-contrast compliance. Every *[SFTTREE_OWNERDRAW](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_ownerdraw)* callback receives a **fHighContrast** field; owner-draw code should inspect it on each paint and re-map role colors to the matching system color instead of using the application's normal palette. Failing to do this makes owner-drawn [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) unreadable under a user's high-contrast theme.

[Dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) and Windows High Contrast are independent. If the user has both enabled, high contrast takes precedence - the contrast theme's palette wins over the dark palette, because honoring the user's contrast theme is the stronger accessibility requirement.

## Accessibility (Screen Readers)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_accessibility*

SftTree/DLL 8.0 ships with built-in Windows UI Automation (UIA) support. Users who rely on Narrator, NVDA, JAWS or any other UIA-compatible assistive technology can read and navigate SftTree controls without the hosting application doing any work. No opt-in, no code change, no separate build.

What the screen reader sees:

|  |  |
| --- | --- |
| Control type | **Data grid**. Row / column / [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) navigation is available through standard grid shortcuts. A [split tree control](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar) exposes a *single* unified data grid (not two nested grids) so the user experiences the same structure regardless of split. |
| Rows | Each item is a row fragment that carries its tree *level*, expand / collapse state, and selection state. The [parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent) / child / [sibling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_siblings) hierarchy of the tree is preserved in UIA navigation. |
| [Column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) / [row headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) / [footers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_footers) | Exposed as separate header fragments with the header text spoken as the *Name*. [Sort indicators](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_sortindicator) are reflected in the header *Name* ("ascending" / "descending"). [Header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_header) and row-header *HelpText* is routed through the application's registered [ToolTipsCallback](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_tooltipscallback) so the same text shown as an on-hover tooltip is also announced. |
| Cells | Each cell is addressable individually. Cells using *[SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture)* check-box or radio-button types advertise the matching control type (CheckBox / RadioButton) and the Toggle / SelectionItem patterns, so the screen reader announces "checked" / "unchecked" / "mixed" as appropriate. |
| Patterns implemented | Selection, SelectionItem, Grid, GridItem, Table, TableItem, ExpandCollapse, Scroll, ScrollItem, Invoke, Value (read-only), Toggle. |

Event [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) raised automatically: selection changed, caret changed, vertical / horizontal scroll, expand / collapse, column resize, insert / delete item, cell toggle-state changed.

There is nothing to turn on. The provider loads on demand the first time a UIA client queries the control, so there is no overhead for applications whose users never attach an assistive technology.

Two things the application controls:

- Register a ToolTipsCallback (see SetToolTipsCallback) so the column-header, row-header, row/column-header-corner and column-footer *HelpText* - what the screen reader speaks in addition to the header's short name - is descriptive. SftTree does not store header help text itself; the callback owns it. If no callback is registered, *HelpText* is empty.
- Call [Announce](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_announce) to push short application-status text ("3 rows added", "Filter cleared", "Saved") to attached screen readers. Announce is the right tool for momentary status updates that do not have a visible representation in the tree.

[Dark mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_darkmode) and [Windows High Contrast](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_highcontrast) are independent accessibility settings. SftTree honors both automatically (see [SetDarkMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_darkmode) and [SetHighContrastMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_highcontrast)).

Platform note: The UIA notification event used by Announce requires Windows 10 version 1709 or later. On earlier platforms Announce is a silent no-op. All other UIA features work on Windows 7 and later.

## Per-Monitor DPI and Scaling

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dpi*

SftTree/DLL 8.0 is fully Per-Monitor v2 DPI-aware. A tree control hosted on a Per-Monitor v2 aware top-level window will re-render automatically when its window moves to a monitor of a different DPI or when the system DPI changes. The control owns the metrics it controls; the caller owns the images and fonts it provides. Two opt-in flags let the caller hand those over to the control as well.

### Host setup

The host application must declare Per-Monitor v2 DPI awareness. This is the single most common reason SftTree/DLL 8.0 applications do not re-render correctly when moved between monitors of different DPI. Without a PMv2 declaration, Windows silently keeps the process in System-aware mode: the DPI is fixed for the process lifetime, SftTree does not observe DPI changes, [SFTTREEN_DPI_CHANGED](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_dpi) is never raised, and high-DPI monitors render at System-DPI sizes stretched by Windows. Visual Studio's default *app.manifest* does **not** declare PMv2 awareness - the developer must opt in explicitly.

Two approaches - pick one:

#### Application manifest (recommended)

Add a *<dpiAwareness>* / *<dpiAware>* element to the application manifest. Both elements are usually included for back-compatibility with older Windows 10 builds:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <asmv3:application xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
    <asmv3:windowsSettings>
      <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
      <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">True/PM</dpiAware>
    </asmv3:windowsSettings>
  </asmv3:application>
</assembly>
```

In a Visual Studio C++ project, set *Project Properties -> Manifest Tool -> Input and Output -> Additional Manifest Files* to the .manifest file above, or edit the auto-generated manifest directly. In a C# / .NET project, check *Application -> DPI awareness* and select *Per Monitor V2*.

#### Runtime API

Alternatively, call SetProcessDpiAwarenessContext at process startup, before any window is created:

```
SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
```

Caveat: This call must run before the first window (including hidden startup dialogs or splash screens) is created. If a window has already been created, Windows rejects the call and the process remains in whichever mode the manifest specified - which, with the Visual Studio default, is System-aware.

#### Verifying the declaration worked

Quick check at runtime: GetDpiForWindow on the tree control returns the current monitor's DPI - 96 at 100%, 120 at 125%, 144 at 150%, 192 at 200%. If the returned value never changes as you drag the window between monitors with different scale factors, the host is not in PMv2 mode.

### What scales automatically

When the host is Per-Monitor v2 aware, the tree control scales these metrics itself on every DPI change without any caller involvement:

- row height and item height,
- grid-line thickness,
- scroll bar and scroll arrow metrics,
- drag threshold,
- 3D frame widths,
- column drop-down / filter button width,
- the resize handle bitmap (between panes of a split tree),
- the built-in expand / collapse glyphs (the control-owned plus/minus and triangle shapes used when the application does not supply custom tree button bitmaps),
- the [splitter bar](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar) width in a split tree control.

### What the caller controls

Two independent opt-in flags let the caller choose whether caller-supplied pixel metrics and caller-supplied images also scale with DPI. Both default to back-compatible behavior (no automatic scaling) so existing applications keep working unchanged.

| Flag | Covers | ASIS (default) | STRETCH |
| --- | --- | --- | --- |
| [SetImageScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_imagescaling) | Every image the control draws: caller-supplied [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) / label / item / row-header / column-header / column-footer pictures; plus / minus bitmaps ([SetPlusMinus](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_plusminus)); user-supplied tree button bitmaps ([SetButtons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_buttons)); control-owned glyphs and the check-mark PNGs used in column-filter drop-downs. | Images are drawn at their native pixel size. [Bitmaps](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_bitmaps) supplied at 96 DPI look physically smaller on a high-DPI monitor. | Images are scaled by *currentDPI / 96*. Bitmaps use *HALFTONE* stretch; [GDI+](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_gdiplus) images use *InterpolationModeHighQualityBicubic*. |
| [SetPixelScaling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_pixelscaling) | Caller-supplied pixel dimensions: column widths (*[SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex).width / .minWidth*), indentation ([SetIndentation](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_indentation)), [row header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) width ([SetRowHeaderWidth](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowheaderwidth)), horizontal extent and offset, item min / max heights, splitter offset ([SetSplitterOffset](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_splitteroffset), [SetSplitterOffsetMin](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_splitteroffsetmin)). | Values are used verbatim in physical screen pixels. A column width of 100 is 100 pixels on any monitor. | Values are interpreted as 96-DPI reference pixels. A column width of 100 is 100 pixels at 100%, 150 pixels at 150%, 200 pixels at 200%. Storage and getters always return caller-reference units so serialized configurations stay portable. |

### Decision guide

| Goal | Setting |
| --- | --- |
| "My existing application already ships multiple image sizes or only targets 96 DPI" | Leave SetImageScaling ASIS (default). Ship SFT_PICTURE images sized for the target DPI. |
| "I want crisp images on high-DPI monitors without code changes" | Call SetImageScaling with SFTTREE_IMAGESCALING_STRETCH once at control creation. |
| "Column widths should stay physically the same size as the user moves between monitors" | Call SetPixelScaling with SFTTREE_PIXELSCALING_STRETCH once at control creation. |
| "My serialized / saved column widths must stay portable across DPI" | SetPixelScaling STRETCH. Storage stays in 96-DPI reference pixels regardless of monitor. |
| "I have owner-draw code that caches pixel metrics" | Stop caching. Read the *[dpi](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_ownerdraw)* field on every SFTTREE_OWNERDRAW callback and re-compute pixel sizes each paint. |

### Caller responsibilities on DPI change

When the control's monitor DPI changes, SftTree raises **SFTTREEN_DPI_CHANGED** to the parent window. The application should:

- re-send WM_SETFONT with a font sized for the new DPI (SftTree does not own the application's font),
- if SetImageScaling is ASIS and the caller wants crisp images, re-register SFT_PICTURE cell / label / item / row-header / column-header / column-footer images at the new physical size,
- if SetImageScaling is STRETCH, no action needed - the control scales existing images automatically,
- if SetPixelScaling is ASIS, re-apply column widths / indentation / etc. scaled for the new DPI,
- if SetPixelScaling is STRETCH, no action needed - the control scales stored values automatically.

### Owner-draw

The SFTTREE_OWNERDRAW structure carries the control's current effective DPI in its **dpi** field. Owner-draw code should read this value on every paint and must not cache pixel metrics across callbacks. GetDPI returns the same value outside a paint callback.

Platform note: Per-Monitor v2 DPI awareness requires Windows 10 version 1703 or later. On older platforms the host process runs in System-aware or Unaware mode and DPI is effectively fixed for the process lifetime - SftTree still renders correctly but does not fire SFTTREEN_DPI_CHANGED.

## Item IDs

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_item_ids*

Items in a tree control are managed as a linear list or array of items. All API functions that access a particular item require the item index. This is a zero-based number describing the item position. The first item in the tree control has item index 0, the second is item 1, etc. Consequently, if an item is inserted at the top of the list, all previously added items now receive a new item index.

|  |  |
| --- | --- |
| *Index 0* | First Item |
| *Index 1* | Second Item |
| *Index 2* | Third Item |
| *Index 3* | Fourth Item |

Once a new item is added, the tree control looks like this:

|  |  |
| --- | --- |
| *Index 0* | New Item |
| *Index 1* | First Item |
| *Index 2* | Second Item |
| *Index 3* | Third Item |
| *Index 4* | Fourth Item |

An item index describes the position in the tree control, so it is subject to change if items are added or removed.

In some cases it may be easier to work with a constant value describing an item no matter where it is located in the list of items. This is possible using item IDs. Once an item has been added to the tree control, its ID can be retrieved using [GetItemID](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemid). The returned item ID does not change, even if other items are added or removed. Given an item ID, the current item index can be found using [GetItemIndex](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemindex).

Saving the item ID is most useful for top level [parent items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent). Top level items usually show item categories. Since adding or removing child items of other parent items changes a top level parent's index, it is easier to work with item IDs. When a top level parent item is added, save the item ID retrieved using GetItemID. Later, regardless of how many other items have been added or removed, a call to GetItemIndex with the saved item ID will return the current item index.

```
SFTTREE_ID savedID; 
int index; 
index = m_Tree1.AddString("Category 1"); 
savedID = m_Tree1.GetItemID(index); 
. . . other items added/inserted and removed
// retrieve the item index for "Category 1" 
index = m_Tree1.GetItemIndex(savedID);
. . . processing for Category 1
```

## Horizontal Scrolling

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_horizontalscrolling*

SftTree/DLL fully supports horizontal scrolling. With SftTree/DLL, adding a horizontal scroll bar is very easy, even if multiple [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) are used. Of course, the tree control [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) WS_HSCROLL must be specified when creating the tree control. By calling [RecalcHorizontalExtent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_recalchorizontalextent), SftTree/DLL will evaluate the optimal horizontal scrolling extent and add a horizontal scroll bar to the control.

> Even if a horizontal scroll bar is defined, RecalcHorizontalExtent **must** be called  after all items have been added, otherwise the horizontal scroll bar will not be enabled or updated.

## Multi-Line Cell Text

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_multiline_cell_text*

[Cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) can consist of several text lines. The number of text lines can be defined using [SetItemLines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemlines). In a [fixed height](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_fixed_variable_height_items) tree control, the specified number of lines are reserved for each cell text. Should the cell text consist of fewer lines, the text is vertically centered. In a variable height tree control, up to the specified number of lines are displayed. If fewer text lines are available, the item height is adjusted if possible, based on other item attributes.

If more text lines are available than fit in the [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell), the symbol "+" is shown in the bottom right of the cell.

Cell text can word-wrap and can contain explicit line breaks (cr-lf or \r\n). Word-wrap is defined using [SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns) (see [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex), SFTTREE_WRAP).

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Cell Merging

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_merging*

The contents of a [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) can merge into an adjacent cell (on the right), including the cell colors, fonts and graphics attributes.

If a cell is empty, i.e. has no [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) or graphic, the cell immediately to the left may merge into the empty cell, using the additional space to display its contents.

The column containing the cell has to be defined in the column's [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex) (SFTTREE_COL_MERGE) structure, indicating that the cell may merge into the next column's empty cell. The next column has to be defined in the column's SFTTREE_COLUMN_EX (SFTTREE_COL_MERGEINTO) structure, indicating that it can be "merged into". The cell in the next column must be empty, i.e. it has no cell text or picture.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/mergedcell1.gif)

[Column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) also use the settings found in the column's SFTTREE_COLUMN_EX structure. If a column header is empty and the previous column has been adequately defined in the column's SFTTREE_COLUMN_EX structure, the column headers merge. If the [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) are resizable, a small resizing handle is shown in the combined column header.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/mergedcell2.gif)

## Expand/Collapse Buttons

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons*

Expand/collapse buttons are optional buttons displayed to allow users to expand and collapse tree sections by clicking a button. The button graphics can be modified and are shared between all items (see [SetButtons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_buttons)). Items on level 0 (the highest level or [root level](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_rootlevel)) have special level 0 expand/collapse buttons which can be enabled separately, but share the same graphics.

Expand/collapse buttons are enabled using [SetShowButtons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_showbuttons) and [SetShowButton0](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_showbutton0). The location of an expand/collapse button can be determined using the [GetExpandCollapseButtonRect](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_expandcollapsebuttonrect) function.

Expand/collapse buttons for individual items can be suppressed using the [SetItemExpandCollapseButton](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemexpandcollapsebutton) function.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Row Headers

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers*

The optional row headers are available for single- and multi-column tree controls, with labeled buttons or just titles. The [SetShowRowHeader](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_showrowheader) function defines the row header display style. The header or button labels may be left or right justified or centered within the available width (see [SetRowHeaderStyle](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowheaderstyle)). Row headers can also contain pictures.

The built-in row headers offered by SftTree/DLL support one single or multiple lines of text for each item (see [SetRowHeaderLines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowheaderlines)) and one bitmap or icon for each item (see [SetRowInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rowinfo)).

In a [fixed height](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_fixed_variable_height_items) tree control all pictures must be the same height and width for all items. In a variable height tree control, the row header pictures can be of varying height and width.

If a user clicks on a row header, the application receives a [SFTTREEN_LBUTTONDOWN_ROW](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification.

The row header buttons reflect the currently selected item(s) (see [GetCurSel](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_cursel) or [GetSel](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_sel)).

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Column Headers

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers*

The optional column header is available for single- and multi-column trees, with labeled buttons or just titles. The header text is defined using the [SetHeader](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_header) function. Each header or button label may be left or right justified or centered within the column boundaries. Column header attributes are defined using the [SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns) function. Column headers can contain a single or multiple lines of text and a picture.

All pictures must be the same height and width for all column headers.

If a user clicks on a column header, the application receives a [SFTTREEN_LBUTTONDOWN_COLUMN_HEADER](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification.

If the resizing area of a column header is double-clicked, a SFTTREEN_LBUTTONDBLCLK_COLUMNRES notification is generated. The application could resize the column using [MakeColumnOptimal](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_makecolumnoptimal) in response to the notification.

Only one column header button can be in the pressed position at any one time.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Column Footers

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_footers*

The optional column footer is available for single- and multi-column trees, with labeled buttons or just titles. The footer text is defined using the [SetFooter](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_footer) function. Each footer or button label may be left or right justified or centered within the column boundaries. Column footer attributes are defined using the [SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns) function. Column footers can contain a single or multiple lines of text and a picture.

All pictures must be the same height and width for all column footers.

If a user clicks on a column footer, the application receives a [SFTTREEN_LBUTTONDOWN_COLUMN_FOOTER](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification.

If the resizing area of a column footer is double-clicked, a SFTTREEN_LBUTTONDBLCLK_COLUMNRES notification is generated. The application could resize the column using [MakeColumnOptimal](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_makecolumnoptimal) in response to the notification.

Only one column footer button can be in the pressed position at any one time.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Columns

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns*

A SftTree/DLL tree control can define multiple columns, each with its individual text alignment (left, right, center). A tree control can also define a header with titles, each with its individual text alignment. [Column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) attributes are defined using the [SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns) function.

Columns can be reordered and resized by the user without application program intervention (unless disabled by the application). An application could save these column widths and column order in an INI file or the registry for future use.

Each column has a defined width (see [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex)). The last column can be defined as an [open-ended](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_openended) column using the SetOpenEnded function.

Using the SetOpenEnded function, the last displayed column can be defined as open-ended, which is the default if the application doesn't define any columns. An open-ended last column will display the complete text and graphics specified for the last (or only) column and never truncate any data. A fixed-width last column is defined with a specified width (see "Columns") and any data which doesn't fit is truncated.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/shortcut.gif) [Tree Components](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tree_components)

## Column Drag & Drop

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_drag_drop*

SftTree/DLL can be enabled to allow users of the control to reorder [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) by dragging a column and dropping it at the new position in the control. The application can define certain columns that must remain in their current position (see [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex), *colFlag* member, SFTTREE_COL_KEEPPOS). Columns that must remain in their current position cannot be moved.

As a user reorders columns, this is completely transparent to the application. An application still references [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) by the "real" column number, which is the original column number that the cell had before columns were reordered by the user. While columns appear in a new order after dragging a column to a new position, the application references columns and cells by their [real column number](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_display_vs_real_column) which never changes.

A user can drag a column by clicking the left mouse button on a [column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) and, without releasing the mouse button, move the cursor to a new location. A vertical bar indicates the location where the column will be inserted. Once the correct position is reached, the user releases the mouse button. An application receives the [SFTTREEN_REORDERED](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification after the column positions have been changed.

While a column drag & drop is in progress, the user can abort it by pressing the Escape key.

When using a [split tree control](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_splitter_bar), columns can only be reordered within one pane. They cannot be moved from one pane to the other.

If an application wants to retain the column order between sessions, the *dispPos* member of the SFTTREE_COLUMN_EX structure must be saved for each column. When the application is restarted and the tree control is reinitialized, the values of the *dispPos* member can be restored for each column before calling [SetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns). An INI file or the Windows Registry can be used to save these values.

The [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) can be used to view events that are generated by the tree control.

## Column Resizing

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_resizing*

A SftTree/DLL control can define multiple [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns), each with its individual text alignment (left, right, center). A tree control can also define a header with titles, each with its individual text alignment. Columns can be resized by the user without application program intervention (unless disabled by the application). By dragging the separator between column titles (or buttons), users can adjust column widths to their particular needs. An application receives the [SFTTREEN_COLUMNSIZE](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification after the column sizes have been changed.

If the user resizes a column and makes it so small that its column width becomes 0, the next column to the left may also be affected (made smaller) in the same resizing operation, based on the settings of [SetCrossColumnResize](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_crosscolumnresize).

Columns can be defined with a minimum column width (see [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex), *minWidth* member). This will prevent the user from hiding a column. The user is unable to make the column smaller than the minimum width defined. However, an application can still make the column smaller using functions such as [MakeColumnOptimal](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_makecolumnoptimal), etc.

An application can define certain columns as locked (see SFTTREE_COLUMN_EX, SFTTREE_COL_LOCKED). Columns that are locked cannot be resized. This could be useful for columns that contain a picture which always has the same width. By using MakeColumnOptimal to calculate the optimal width of the column, the column is wide enough to display all of its data, so there is no need to allow the user to resize it.

If the resizing area of a [column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers) is double-clicked, a SFTTREEN_LBUTTONDBLCLK_COLUMNRES notification is generated. The application could resize the column using MakeColumnOptimal in response to the notification.

Locked columns are also useful to hide entire columns from a user, e.g., if a user does not have sufficient authorization to view some data, the application could still load all information into the control, yet hide selected columns by locking them and setting their width to 0. This simplifies program logic as the application can work with constant column numbers, yet the data is not shown to users with insufficient authority.

An application could save column widths as they have been altered by a user in an INI file or the registry for future use.

The [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) can be used to view events that are generated by the tree control.

## Display vs. Real Columns

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_display_vs_real_column*

When allowing [column drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_drag_drop) to reorder [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns), the user may see columns in an order other than the order in which an application sees the columns. An application always uses "real" columns in API calls. A column which was originally added as column 0 will always remain column 0 for API calls made by the application, even if the column order has been changed and the column is no longer the first column displayed. This simplifies the application's programming logic as it can assume that the column position never changes. SftTree/DLL translates the real column number into the actual column number. The actual column number is referred to as the "display column" number.

The display column number is identical to the order in which the columns are displayed.

### Translating Real Column to Display Column

An application can retrieve a "real" column's "display" column number by inspecting the column information returned by [GetDisplayColumn](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_displaycolumn) or [GetColumns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_columns). In this example, the real column number of the third column is translated to the display column number:

**C**

```
displayPosition = SftTree_GetDisplayColumn(2);
```

or

```
LPSFTTREE_COLUMN_EX lpCol;
int nCols, displayPosition; 
nCols = SftTree_GetColumnsEx(hwndTree, &lpCol);/* Get column attributes */
displayPosition = lpCol[2].dispPos; /* Extract the display position */ 
```

**C++**

```
displayPosition = m_Tree.GetDisplayColumn(2);
```

or

```
LPSFTTREE_COLUMN_EX lpCol;
int nCols, displayPosition; 
nCols = m_Tree.GetColumns(&lpCol); /* Get all column attributes */
displayPosition = lpCol[2].dispPos; /* Extract the display position */ 
```

### Translating Display Column to Real Column

If an application needs to translate a display column number to a real column number, the column information returned by [GetRealColumn](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_realcolumn) or GetColumns can be used:

In this example, the display column number of the second displayed column is translated to the real column number. Please note that even though GetColumns returns an array of [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex) structures in **real** column order, the *realPos* member can be retrieved only by using a **display** column number as an array index.

**C**

```
realPosition = SftTree_GetRealColumn(1);
```

or

```
LPSFTTREE_COLUMN_EX lpCol;
int nCols, realPosition; 
nCols = SftTree_GetColumnsEx(hwndTree, &lpCol);/* Get column attributes */
realPosition = lpCol[1].realPos; /* Extract the real position */ 
```

**C++**

```
realPosition = m_Tree.GetRealColumn(1);
```

or

```
LPSFTTREE_COLUMN_EX lpCol;
int nCols, realPosition; 
nCols = m_Tree.GetColumns(&lpCol); /* Get all column attributes */
realPosition = lpCol[1].realPos; /* Extract the real position */ 
```

## Drag & Drop

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop*

SftTree/DLL supports a drag & drop protocol by sending WM_COMMAND messages to the parent window if the tree control has the appropriate [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) SFTTREESTYLE_DRAGDROP defined. This drag & drop mechanism is generally only suitable to implement drag & drop within one tree control. When dragging between different controls, other mechanisms such as OLE drag & drop must be used.

When dragging within the tree control, the drop target will automatically be updated and the data will automatically start scrolling vertically when the mouse cursor moves into the areas marked below. Once the mouse cursor goes beyond those areas, indicating a drag operation outside the tree control, scrolling stops automatically. No application program intervention is required for this to take place. A header or scroll bar is not required. This drag-scrolling support is identical to the drag-scrolling supported by OLE conventions.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/dragdrop1.gif)

If drag & drop support outside of the current tree control is desired, the [SFTTREE_DRAGINFO](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_draginfo) structure can be interrogated to find the current target window of the drag & drop operation.

## Cell Editing

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing*

SftTree/DLL supports editing of [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) using a unique approach. SftTree/DLL will notify your application of certain events (such as double-clicking on a tree item). Your application can then create any Windows control at a location specified by SftTree/DLL. The Windows control is "attached" to the tree control, but your application receives all messages and [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) for the new control, so even owner-drawn controls or custom controls can be used. SftTree/DLL will notify your application when editing (using your control) should end, either with or without data validation.

The [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) can be used to generate sample code implementing cell editing. The sample code uses an edit control, but any Windows control can be used instead.

To simplify handling of special keystrokes such as Escape, Return, arrow keys, which are normally handled by the child window, these can be intercepted by the application using [SetKeyHandling](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_keyhandling). Once a keystroke for a child window is intercepted during cell editing, the SFTTREEN_KEYINTERCEPTED notification occurs. The intercepted key can be retrieved using the GetKeyHandling function. Using SetKeyHandling eliminates the need to subclass the child window, simplifying the implementation of cell editing.

By intercepting the Tab, Return and arrow keys, simple [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) navigation while cell editing is possible. Individual items can be ignored for cell editing using the [SetItemEditIgnore](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_itemeditignore) function. Or individual cells can be ignored for cell editing using the [SFTTREE_CELL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_cell) structure's *flag2* member (SFTTREECELL_EDITIGNORE).

The CellEditing example demonstrates the techniques used for cell editing with complete cell navigation using edit controls and combo boxes.

## Keyboard Interface

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_keyboard*

A tree control responds to the PgUp, PgDn, Home, End keys, etc. to change the selected item (see "[Selections](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_selections)").

The left arrow collapses the current item (by generating the [SFTTREEN_LBUTTONDOWN_BUTTON](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification). If the item is not expanded, the item's [parent item](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent) becomes the current item.

The right arrow expands the current item (by generating the SFTTREEN_LBUTTONDOWN_BUTTON notification). If the item is not collapsed, the first child item becomes the current item.

The up arrow makes the previous visible item the current item.

The down arrow makes the next visible item the current item.

Typing one or more alphanumeric characters while a tree control has the input focus will reposition the selection on a matching item, based on the [SetCharSearchMode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_charsearchmode) settings.

The + key on the numeric keypad expands the current item (by generating the SFTTREEN_LBUTTONDOWN_BUTTON notification).

The - key on the numeric keypad collapses the current item (by generating the SFTTREEN_LBUTTONDOWN_BUTTON notification).

The * key on the numeric keypad expands the current item (by generating the SFTTREEN_EXPANDALL notification).

The Return key can be used to expand/collapse items or can be handled by handling the SFTTREEN_VK_RETURN notification.

The space bar selects/deselects the current item (honoring the Control and Shift keys).

Depending on the [SetSelectionArea](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_selectionarea) setting used, the Control key can be used to move the caret location without moving the current selection.

## Selections

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_selections*

A SftTree/DLL tree control supports single and multiple selection, based on the [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) SFTTREESTYLE_MULTIPLESEL used when the tree control is created. As the selection changes, an application receives the [SFTTREEN_SELCHANGE](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) notification.

> The area where a selection change occurs can be defined using the [SetSelectionArea](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_selectionarea) function.

### Single Selection

In single selection mode, only one item can be selected (highlighted) at a time. When a new item is selected, the previously selected item is then no longer selected. The current position (or caret location) is automatically selected, except while a [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) operation is in progress. The caret location indicates the drop target and the selected item is the source. Drag & drop can cause the caret location to be a deselected item. This behavior can be affected by the [SetDropHighlightStyle](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_drophighlightstyle) function.

Depending on the SetSelectionArea setting used, items can be selected using the mouse by clicking anywhere on the item to be selected, from [row header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_row_headers) (leftmost position), [label picture](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_label_bitmap) to the right side of the window area. Moving the caret location, using the arrow keys, also automatically selects the item at the caret location.

### Multiple Selection

In multiple selection mode, many items can be selected (highlighted) at the same time. The current position (or caret location) is automatically moved to the new location when clicking anywhere on an item.

Items can be selected using the mouse by clicking anywhere on the area defined by the SetSelectionArea function or by using the arrow keys. The new selection replaces the previous selection. If the Control key is used, the selection is added to previous selections. If the Shift key is used, the entire range of items is selected, from the first selected item to the newly selected item. If the Shift and the Control keys are pressed, a range of items is added to the previous selection(s).

Depending on the SetSelectionArea settings, the Control key (in combination with directional keys) can be used to move the caret location without moving the current selection.

The [SetRubberbandSelection](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_rubberbandselection) function can be used to enable click-drag selection of multiple items using a selection rectangle.

## ScrollTips

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_scrolltips*

[ScrollTips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_scrolltips) are displayed when the user drags the vertical scroll bar's scroll box using the mouse. By default, the [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) of the first displayed item in the client area (see [GetTopIndex](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_topindex)) is shown as a ToolTip next to the scroll bar. An application can override the text displayed using the [ToolTips](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tooltips) callback function [SFTTREE_TOOLTIPSPROC](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/typedef_sfttree_tooltipsproc).

ScrollTips are enabled using SetScrollTips.

## ToolTips

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_tooltips*

If the text or picture in a [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) are only partially visible, a ToolTip may be displayed if the mouse cursor rests above the partially displayed area. The ToolTip window then displays the complete [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) and cell graphic by extending the cell and overlaying adjacent windows. Once the mouse cursor is moved away from the cell, the ToolTip disappears.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/tooltip1.gif)

ToolTips are enabled for each column individually (see each column's [SFTTREE_COLUMN_EX](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_column_ex) structure). It is also possible to display ToolTips even if the cells are already completely visible (see [SetToolTipAlways](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_tooltipalways)).

The [SetControlInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_controlinfo) function can be used to define the delay after which a ToolTip is shown and hidden ([SFTTREE_CONTROL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_control), toolTipTimeOn and toolTipTimeOff).

## Progress Bar

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_progressbar*

SftTree/DLL supports a simple progress bar display in each [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell). If enabled, the progress bar is rendered as cell background, with the [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) and image displayed in the cell as usual. For a partial height progress bar, the cell background is also rendered using the defined background colors.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/prog1.jpg)

The progress bar can be enabled in a cell using [SFTTREE_CELL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_cell), progressMax and progressVal. The progress bar colors are defined using the structure members colorProgress and colorProgressEnd.

### C Sample

```
HWND hwndTree;
SFTTREE_CELLINFOPARM CellInfo;
CellInfo.version = 7;
CellInfo.index = itemIndex;
CellInfo.iCol = col;
SftTree_GetCellInfo(hwndTree, &CellInfo);
CellInfo.Cell.progressMax = 100;    // maximum value 0 - 100
CellInfo.Cell.progressVal = 33;     // current value
SftTree_SetCellInfo(hwndTree, &CellInfo);
```

### C++/MFC Sample

```
CSftTree m_Tree;
SFTTREE_CELLINFOPARM CellInfo;
CellInfo.version = 7;
CellInfo.index = i;
CellInfo.iCol = 0;
m_Tree.GetCellInfo(&CellInfo);
CellInfo.Cell.progressMax = 100;    // maximum value 0 - 100
CellInfo.Cell.progressVal = 33;     // current value
m_Tree.SetCellInfo(&CellInfo);
```

## Flyby Highlighting

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_flyby_highlighting*

As the mouse cursor is positioned above any [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) of an item in the tree control, the cell in the first displayed column can be shown underlined. Flyby highlighting can be enabled using [SFTTREE_CONTROL](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_control), iFlybyStyle.

> If a selection style is used that uses a rounded outline rectangle with a gradient fill, the [cell text](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell_text) is not underlined. Instead, a rounded outline rectangle with a gradient fill is used to highlight the item, based on the current selection style (see [GetSelectionStyle](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_selectionstyle)).

Flyby highlighting helps users easily identify where the mouse cursor is located in a multi-column tree control.

|  |  |
| --- | --- |
| ![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/flyby1.gif) | ![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/flyby2.gif) |
| Simple selection style | Rounded outline rectangle selection style |

## Bitmap Transparency

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_bitmap_transparency*

SftTree/DLL automatically uses bitmap transparency for all bitmaps used throughout a tree control. When a bitmap is displayed, the background can show through portions of the bitmap. SftTree/DLL accomplishes this by dynamically modifying a copy of the bitmap to adjust for the background color.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/transparency_1.gif)![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/transparency_1b.gif)

The top, left pixel of each bitmap is inspected as the bitmap is painted. The color of that pixel represents the bitmap's background color. This color is replaced throughout the bitmap with the actual background color.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/transparency_2.gif)

If the bitmap image includes the top, left pixel, add an extra row or column of pixels to the bitmap, so the image does not include the top, left pixel.

Bitmap transparency is only used for bitmaps and is not used for icons, images in an ImageList control or other images that can be represented by a [SFT_PICTURE](https://softelvdm.com/Documentation/SftPicture2/Topic/struct_sft_picture) structure.

Bitmap transparency for bitmaps is fully automatic and cannot be turned off.

## GDI+

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_gdiplus*

If GDI+ is available, the tree control supports additional features not otherwise available:

- Image support for PNG, TIFF, JPEG, GIF, Exif, EMF+, EMF (GDI+ images) with full support for alpha-blended (translucent and semi-transparent) images
- Rounded outline rectangle with gradient fill for selected items, highlighted items ([flyby highlighting](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_flyby_highlighting)) or drop target items
- Transition effects for [expand/collapse buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_expandcollapse_buttons) and [tree lines](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_tree_lines) are used when the mouse enters/leaves the tree control

GDI+ is available on all supported Windows versions (Windows 10 and above).

An application can test whether GDI+ is available using the [GetGDIPlusAvailable](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_gdiplusavailable) function.

## Context Menu

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contextmenu*

A context menu (or popup menu) is easily implemented with SftTree/DLL. The context menu is typically used when the user right-clicks on the [column header](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers). As an example, a context menu could be used to hide and display [columns](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_columns) in a tree control that has column headers.

> Before displaying a context menu, an application should always send a WM_CANCELMODE message to the tree control.

### **WM_CONTEXTMENU**

Applications receive the Windows message [WM_CONTEXTMENU](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windows_messages) when the user right-clicks on a window. The parent window of the tree control receives the message.

The WM_CONTEXTMENU message is generated if the user right-clicks anywhere within the tree control.

For more information on the WM_CONTEXTMENU message, please see the Windows API documentation.

## Demo Application

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_demo_application*

During the installation of SftTree/DLL, an icon for the demo application "Demo" is installed in the program group *SftTree/DLL 8.0*.

This demo application shows some of the features available in SftTree/DLL. It is also used to access other [samples](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_samples) included in the demo or product and the online help.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/demo.png)

> All sample programs and complete sample source code can be found in the directory "\Program Files\Softelvdm\SftTree DLL 8.0\Samples". On Windows 64-bit versions, the root folder is \Program Files** (x86)**. Each sample is installed in its own subdirectory. All samples are supplied with a precompiled executable (Exe) and an entry is added to the *SftTree/DLL 8.0* program group for each sample.

## Samples

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_samples*

SftTree/DLL includes sample code for both C and C++.

The samples listed in the following table can be found in the folder "\Program Files\Softelvdm\SftTree DLL 8.0\Samples". On Windows 64-bit versions, the root folder is \Program Files** (x86)**. These samples are also referenced throughout the documentation.

| C Sample | C++ Sample | Description |
| --- | --- | --- |
| [C CellEditing Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_cellediting) | [C++ CellEditing Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_cellediting) | [Cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) using an edit control and a combo box, with [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) navigation and restricted cells. |
| - | [C++ ContentWindows Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_contentwindows) | Tree control with cells containing Flash, Windows Media Player, Internet Explorer and a dialog. |
| [C ContextMenu Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_contextmenu) | [C++ ContextMenu Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_contextmenu) | Context menus, [sort indicators](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_sortindicator) and [dropdown/filter buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_dropdown). |
| [C DragDrop Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_dragdrop) | [C++ DragDrop Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_dragdrop) | [Drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) within and between tree controls. |
| - | [C++ OLEDrag Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_oledrag) | Drag & drop (using OLE mechanisms) within a tree control and with Windows Explorer. |
| [C OwnerDraw Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_ownerdraw) | [C++ OwnerDraw Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_ownerdraw) | Owner-draw cells and [column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers). |
| [C TreeImages Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_treeimages) | [C++ TreeImages Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_treeimages) | Various image types, [progress bars](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_progressbar), checkbox and radio button manipulation. |
| - | [C++ Speed Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_speed) | A simple example to test the performance when adding and deleting many items. |
| - | [C++ TreeView Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_treeview) | example classes to use [CSftTree](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api) and CSftTreeSplit in a view in the same manner as MFC's CTreeView class. |
| [C Virtual Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_virtual) | [C++ Virtual Sample](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_virtual) | Tree control in [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode), used to display a list with 1 million items. |

## CellEditing Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_cellediting*

This sample illustrates [cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) using an edit control and a combo box, with [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) navigation and restricted cells.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\CellEditing\CellEditing.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\CellEditing\CellEditing.c (on 32-bit Windows versions).

[Full sample source — CellEditing Sample (C) (806 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## ContextMenu Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_contextmenu*

This sample illustrates context menus, [sort indicators](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_sortindicator) and [dropdown/filter buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_dropdown).

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\ContextMenu\ContextMenu.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\ContextMenu\ContextMenu.c (on 32-bit Windows versions).

[Full sample source — ContextMenu Sample (C) (723 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## DragDrop Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_dragdrop*

This sample illustrates [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) within and between tree controls.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\DragDrop\DragDrop.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\DragDrop\DragDrop.c (on 32-bit Windows versions).

[Full sample source — DragDrop Sample (C) (560 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## OwnerDraw Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_ownerdraw*

This sample illustrates owner-draw [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) and [column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers).

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\OwnerDraw\OwnerDraw.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\OwnerDraw\OwnerDraw.c (on 32-bit Windows versions).

[Full sample source — OwnerDraw Sample (C) (588 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## TreeImages Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_treeimages*

This sample illustrates various image types, [progress bars](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_progressbar), checkbox and radio button manipulation.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\TreeImages\TreeImages.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\TreeImages\TreeImages.c (on 32-bit Windows versions).

[Full sample source — TreeImages Sample (C) (1061 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## Virtual Sample (C)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_c_virtual*

This sample illustrates a tree control in [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode), used to display a list with 1 million items.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\C\Virtual\Virtual.c or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\C\Virtual\Virtual.c (on 32-bit Windows versions).

[Full sample source — Virtual Sample (C) (531 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## CellEditing Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_cellediting*

This sample illustrates [cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) using an edit control and a combo box, with [cell](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) navigation and restricted cells.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\CellEditing\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\CellEditing\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — CellEditing Sample (C++) (707 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## ContentWindows Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_contentwindows*

This sample illustrates a tree control with [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) containing Flash, Windows Media Player, Internet Explorer and a dialog.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\ContentWindows\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\ContentWindows\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — ContentWindows Sample (C++) (419 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## ContextMenu Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_contextmenu*

This sample illustrates context menus, [sort indicators](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_sortindicator) and [dropdown/filter buttons](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_dropdown).

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\ContextMenu\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\ContextMenu\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — ContextMenu Sample (C++) (654 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## DragDrop Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_dragdrop*

This sample illustrates [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) within and between tree controls.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\DragDrop\Dlg.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\DragDrop\Dlg.cpp (on 32-bit Windows versions).

[Full sample source — DragDrop Sample (C++) (564 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## OLEDrag Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_oledrag*

This sample illustrates [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) (using OLE mechanisms) within a tree control and with Windows Explorer.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\OLEDrag\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\OLEDrag\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — OLEDrag Sample (C++) (481 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## OwnerDraw Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_ownerdraw*

This sample illustrates owner-draw [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell) and [column headers](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_column_headers).

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\OwnerDraw\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\OwnerDraw\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — OwnerDraw Sample (C++) (496 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## TreeImages Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_treeimages*

This sample illustrates various image types, [progress bars](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_progressbar), checkbox and radio button manipulation.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\TreeImages\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\TreeImages\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — TreeImages Sample (C++) (961 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## Speed Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_speed*

This sample tests the performance when adding and deleting many items.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\Speed\SpeedDlg.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\Speed\SpeedDlg.cpp (on 32-bit Windows versions).

[Full sample source — Speed Sample (C++) (348 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## TreeView Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_treeview*

Sample classes to use [CSftTree](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api) and CSftTreeSplit in a view in the same manner as MFC's CTreeView class.

[Full sample source — TreeView Sample (C++) (45 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## Virtual Sample (C++)

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/sample_cpp_virtual*

This sample illustrates a tree control in [virtual mode](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_virtual_mode), used to display a list with 1 million items.

The source code is located at C:\Program Files (x86)\Softelvdm\SftTree DLL 8.0\Samples\MFC\Virtual\SamplVw.cpp or C:\Program Files\Softelvdm\SftTree DLL 8.0\Samples\MFC\Virtual\SamplVw.cpp (on 32-bit Windows versions).

[Full sample source — Virtual Sample (C++) (485 lines) →](https://softelvdm.com/Vault/Softelvdm.com/llms/SftTree-DLL-8.0-samples.txt)

## SftTree/DLL Wizard

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard*

During the installation of SftTree/DLL, an icon for the application "Wizard" is installed in the program group *SftTree DLL 8.0*.

![](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/wizmain.png)

This application can be used to generate most of the source code needed to interact with a tree control in a dialog or a window. It honors most SftTree/DLL attributes and should be used at design-time to build the necessary tree control initialization code.

The SftTree/DLL Wizard application is used to design a tree control look. Most control attributes can be manipulated, except pictures and bitmaps. Sample pictures are provided by the SftTree/DLL Wizard and cannot be changed. Of course, an application can freely define its own pictures. Once the desired look has been achieved, the run-time source code used to initialize the tree control can be generated for C and C++/MFC by clicking on the corresponding tab. The generated source code contains step by step instructions on how to incorporate it into an application.

## ClassInfo - Class Information

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/r_wizard_class*

![Class Info Tab](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/wizclass.png)

Based on the information entered on this page, the generated source code is adjusted to reflect the following settings:

| Label | Description |
| --- | --- |
| Tree control ID: | Enter the ID used for the tree control in a DIALOG resource or as child window. |
| Tree control variable name used for C source code: | Enter the variable name used to hold the window handle of the tree control in a C application. This field is not used for C++ applications. |
| Tree control variable name used in parent window class: | Enter the variable name used for the C++ tree control object, as used by the parent window of the tree control. |
| Create a class derived from [CSftTree](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api): | Select this option if you want to create a class derived from CSftTree or CSftTreeSplit. By deriving your own class, you can add additional functionality to your tree control and reuse it in a number of windows where a tree control is used. It also allows you to easily handle [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) and other [Windows messages](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windows_messages) such as character input (OnChar) in the tree control object, rather than in a parent window class. If this option is not selected, you are adding a tree control based on CSftTree or CSftTreeSplit directly to a parent window and all notifications have to be handled in the parent window. |

## Events - Event Viewer

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/r_wizard_events*

![Event Viewer](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/wizevents.png)

All [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) generated by the tree control are displayed as they occur.

## Values - API Return Values

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/r_wizard_values*

![API Return Values](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/wizvalues.png)

This page displays the most commonly used API return values. It is best used to determine what values an API function returns. The values are extracted from the sample tree control displayed in the wizard.

## C, C++/MFC - Generated Sample Code

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/r_wizard_edit*

![Generated Sample Code](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/wizedit.png)

The [sample source code](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_samples) generated using the C or C++/MFC tabs can be used to implement a tree control in an application. Usually the source code can be used with just minor modifications. By following the comments in this source code, the relevant sections can be copied to your application.

Use the *Edit*, *Find* menu command to locate text.

## Building Applications

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp*

This section describes how to prepare an application using the C or C++ programming language to successfully use SftTree/DLL.

### Updating Project Settings

|  |
| --- |
| Include Files |
| Lib Files |
| Adding The Lib File |
| Linking Statically |
| Resource Script |
| Additional Lib Files |

### Include Files

In order for #include files to be located in the SftTree/DLL product directory, each project that uses SftTree/DLL must be updated to search the product directory.

The default include directory name is \Program Files\Softelvdm\SftTree DLL 8.0\Include, unless changed during installation. On Windows 64-bit versions, the root folder is \Program Files** (x86)**.

Make sure to update all configurations (both Debug and Release).

Using the *Project*, *Properties...* menu command, the project's Property Pages are accessed so the #include directory search path settings can be modified.

![#include Directory](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc1_vsnet.png)

### Lib Files

In addition, the correct Lib file must be linked using the Link Input settings.

The Lib file name depends on the current processor target, according to the table below (see "Adding The Lib File").

The file name must be enclosed in quotes (") if the path contains spaces.

Make sure to update all configurations (both Debug and Release).

Using the *Project*, *Properties...* menu command, the project's Linker, Input properties are accessed so Additional Dependencies can be modified.

![Lib File](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc2_vsnet.png)

### Adding The Lib File

The application's executable (Exe or Dll) must be linked with the correct Lib file, depending on the target environment (see "Updating Project Settings" above). If a Dll is used, it must be available and accessible at run-time for proper execution. The Dll used at run-time depends on the Lib file used at link time. If static linking is selected, the Dll is not required.

All required Lib and Dll files are located in the product directories \Program Files\Softelvdm\SftTree DLL 8.0\Lib and \Program Files\Softelvdm\SftTree DLL 8.0\Dll. On Windows 64-bit versions, the root folder is \Program Files** (x86)**.

#### Intel 64-Bit Operating Systems

When building applications for 64-bit processors running Windows 10 and above, one of the following Lib files is used:

| Lib File | Dll File | Description |
| --- | --- | --- |
| SftTree_x64_A_80.lib | SftTree_x64_A_80.dll | 64-bit Applications using** ANSI** character representation |
| SftTree_x64_A_80_Static.lib | none - see section "Linking Statically" below | 64-bit Applications using** ANSI** character representation |
| SftTree_x64_U_80.lib | SftTree_x64_U_80.dll | 64-bit Applications using** UNICODE **character representation |
| SftTree_x64_U_80_Static.lib | none - see section "Linking Statically" below | 64-bit Applications using** UNICODE** character representation |

Depending on the Lib file used, the matching Dll must be distributed with your application. When using a statically linked library, the Dll is not required, but the application must be updated as described in section "Linking Statically" below.

#### Intel 32-Bit Operating Systems

When building applications for Windows 10 and above, one of the following Lib files is used:

| Lib File | Dll File | Description |
| --- | --- | --- |
| SftTree_IX86_A_80.lib | SftTree_IX86_A_80.dll | 32-bit Applications using** ANSI** character representation |
| SftTree_IX86_A_80_Static.lib | none - see section "Linking Statically" below | 32-bit Applications using** ANSI** character representation |
| SftTree_IX86_U_80.lib | SftTree_IX86_U_80.dll | 32-bit Applications using** UNICODE **character representation |
| SftTree_IX86_U_80_Static.lib | none - see section "Linking Statically" below | 32-bit Applications using** UNICODE** character representation |

Depending on the Lib file used, the matching Dll must be distributed with your application. When using a statically linked library, the Dll is not required, but the application must be updated as described in section "Linking Statically" below.

Support for Intel 32-Bit Processors is included with SftTree/DLL 8.0.

#### ARM64 Operating Systems

When building applications for ARM64 processors running Windows 11 and above, one of the following Lib files is used:

| Lib File | Dll File | Description |
| --- | --- | --- |
| SftTree_ARM64_A_80.lib | SftTree_ARM64_A_80.dll | ARM64 Applications using** ANSI** character representation |
| SftTree_ARM64_U_80.lib | SftTree_ARM64_U_80.dll | ARM64 Applications using** UNICODE **character representation |

Depending on the Lib file used, the matching Dll must be distributed with your application.

### Linking Statically

This step is only required if a Lib file is selected above, that eliminates the Dll. If the Dll is distributed with your application and a suitable Lib file is chosen above, this step can be skipped.

The entire project must be compiled with the [SFTTREE_STATIC](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/def_sfttree_static) preprocessor symbol defined.

Make sure to update all configurations (both Debug and Release).

Using the *Project*, *Properties...* menu command, the project's C/C++, Preprocessor properties are accessed so Preprocessor Definitions can be modified.

![SFTTREE_STATIC](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc3_vsnet.png)

### Resource Script

When linking statically, your application must provide the resources for SftTree/DLL controls. This is accomplished by including the provided header file SftTreeResources.rci into the application's resource script. This file uses predefined ID values which cannot be changed.

Make sure to update all configurations (both Debug and Release).

Update the resource script by switching to Resource View using the *View*, *Resource View* (or *View*, *Other Windows*, *Resource View*) menu command, then use the *Edit*, *Resource Includes* menu command:

![Resource Includes](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc4_vsnet.png)

In order for the include file to be located, the include path for Resources must be updated:

![Resource Path](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc5_vsnet.png)

### Additional Lib Files

> Depending on the SftTree/DLL Lib file used, it may also be necessary to add additional Lib files to the application. Typically, the following libraries are required to allow successful linking:

```
imm32.lib gdiplus.lib version.lib Msimg32.lib
```

Make sure to update all configurations (both Debug and Release).

Certain features of the control require [GDI+](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_gdiplus) support. GDI+ is available on all supported Windows versions (Windows 10 and above).

If you don't want to distribute gdiplus.dll, you can use the delayload feature of the linker by adding the following to your linker options:

```
/delayload:gdiplus.dll
```

This will allow the control to use GDI+, if available, and use alternate presentation methods if it is not available.

Using the *Project*, *Properties...* menu command, the project's Linker, Input properties are accessed so Additional Dependencies can be modified.

![Link Options](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/usingc6_vsnet.png)

## Creating a Dialog Resource

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_vc*

This section describes how to add a tree control to a dialog using Visual Studio.

### Adding a Tree Control to a Dialog

To add a SftTree/DLL control to a dialog, use the "Custom Control" toolbar button. Click on the button and then the dialog being designed to add a control.

![Custom Control](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/vc1vs.png)

Once a custom control has been added to a dialog, you can edit the control properties by using the *View, Properties...* menu command.

![Properties](https://softelvdm.com/Vault/Softelvdm.com/docx/SftTree%20DLL%208.0/image/vc2vs.png)

To define a SftTree/DLL control, enter the class **SftTreeControl80** or **SftTreeSplit80** in the edit field labeled *Class*. A window caption is not necessary, so the edit field marked *Caption* can be left blank.

|  | Window Class Name |
| --- | --- |
| Tree Control | SftTreeControl80 |
| Split Tree Control | SftTreeSplit80 |

### SftTree/DLL Control Styles

To enter a SftTree/DLL [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) in the User Control Properties dialog, use the following list to add the desired style values and enter the resulting hexadecimal value in the field marked *Style*. For detailed information, see "Window Styles".

The [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) displays the style value as part of the generated source code so it can be copied.

| Style | Value | Description |
| --- | --- | --- |
| SFTTREESTYLE_DISABLENOSCROLL | 0x00000001 | Prevents the scroll bars from being hidden when scrolling is not possible. The scroll bars are disabled when scrolling is not possible. |
| SFTTREESTYLE_DRAGDROP | 0x00000010 | Enables [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) processing for the tree control. WM_COMMAND messages are then sent to the tree control's parent window for drag & drop processing. |
| SFTTREESTYLE_LEFTBUTTONONLY | 0x00000020 | When this style is selected, the tree control will ignore the middle and right mouse buttons. No [notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) will be sent to the parent window when the middle or right mouse buttons are clicked. [WM_CONTEXTMENU](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windows_messages) messages are generated instead. |
| SFTTREESTYLE_MULTIPLESEL | 0x00000008 | Enables multiple [tree items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items) to be selected at the same time. The mouse, the Shift and Control keys can be used to select multiple items. |
| SFTTREESTYLE_NOTIFY | 0x00000004 | The SftTree/DLL control will send WM_COMMAND messages to the parent window for special event notification. |
| SFTTREESTYLE_SCROLL | 0x00000040 | When this style is selected, the window styles WS_HSCROLL and WS_VSCROLL given when the tree control is created determine whether scroll bars are present. If this style is not selected, scroll bars are automatically added to the tree control when needed. E.g., to prevent a vertical scroll bar from being added to the tree control, define the SFTTREESTYLE_SCROLL style and do not add the WS_VSCROLL style. |
| SFTTREESTYLE_VARIABLE | 0x00000080 | Defines a [variable height](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_fixed_variable_height_items) tree control, where the height of each item varies based on the fonts, pictures, lines of text, word wrapping and other attributes used. |
| SFTTREESTYLE_WANTKEYBOARDINPUT | 0x00000002 | The SftTree/DLL control will send WM_VKEYTOITEM messages to the parent window for keyboard input processing. |
| WS_BORDER | 0x00800000 | Draws a border around the control. The border is a dark line. |
| WS_HSCROLL | 0x00100000 | Adds a horizontal scroll bar to the tree control. |
| WS_VSCROLL | 0x00200000 | Adds a vertical scroll bar to the tree control. |

### Test Mode

In the dialog test mode offered by Visual Studio, the SftTree/DLL control will not be displayed. Instead, a gray box will show the location of the control. When using the Tab key to test the tab stops, the simulated SftTree/DLL control will not receive the input focus and appear not to have a tab stop defined.

## Using C

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingc*

This section describes how to use SftTree/DLL in an application written using the C programming language.

### Adding SftTree/DLL to an Application

Please see "[Building Applications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp)" to prepare a project for development with SftTree/DLL.

|  |  |
| --- | --- |
| A) | Every source program making use of a SftTree/DLL control must include the required header file SftTree.h by using the #include directive.`#include "SftTree.h" /* SftTree/DLL required header file */`This include statement should appear after the #include <windows.h> statement. The file is located in the directory \Program Files\Softelvdm\SftTree DLL 8.0\Include (unless changed during the installation). On Windows 64-bit versions, the root folder is \Program Files** (x86)**.The project settings may need to be updated so the #include file can be located (see "Building Applications" for more information). |
| B) | In order to use SftTree/DLL controls, an application must call the [SftTree_RegisterApp](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_registerapp) function. The call to this function is required so that SftTree/DLL window classes can be registered. This call has to be made before any SftTree/DLL controls are created. Add the following statement to your source code, where your application registers its window classes (normally during application initialization):`SftTree_RegisterApp(hInstance); /* Use SftTree/DLL with this application */` |
| C) | Once SftTree/DLL controls are no longer needed, an application must call the [SftTree_UnregisterApp](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_unregisterapp) function. The call to this function is required so that SftTree/DLL window classes can be unregistered and cleanup processing can take place. This call has to be made after all SftTree/DLL controls have been destroyed (normally during application termination).`SftTree_UnregisterApp(hInstance); /* No longer use SftTree/DLL */` |
| D) | The application's executable (Exe or Dll) must be linked with the correct Lib file, depending on the target environment. Please see "Building Applications" for more information.The project settings may need to be updated so the Lib files can be located (see "Building Applications" for more information). |

### Adding a Tree Control

There are two methods to add a tree control to an application:

- using dialog resources
- using CreateWindow(Ex)

Adding a tree control using dialog resources is accomplished by using a resource editor to design a dialog. Once a tree control is created, its window handle can be obtained by using the Windows GetDlgItem function. For more information, see "[Creating a Dialog Resource](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_vc)".

Another method to create a tree control is by using the CreateWindow(Ex) Windows call:

```
hwndTree = CreateWindow(
    TEXT(SFTTREE_CLASS), /* Window class */
    TEXT(""), /* Caption (none) */
    SFTTREESTYLE_NOTIFY | /* Notify parent window */
    SFTTREESTYLE_DRAGDROP | /* Drag & drop enabled */
    SFTTREESTYLE_LEFTBUTTONONLY | /* Only respond to left mouse button */
    SFTTREESTYLE_SCROLL | /* Honor WS_H/VSCROLL */
    SFTTREESTYLE_DISABLENOSCROLL | /* Disable scrollbars instead of hiding */
    WS_HSCROLL | WS_VSCROLL | /* Vertical and horizontal scrollbars */
    WS_VISIBLE | WS_CHILD, /* Visible, child window */
    x, y, cx, cy, /* Location */
    hwndParent, /* Parent window */
    (HMENU) IDC_TREE, /* Tree control ID */
    app_instance, /* Application instance */
    NULL);
if (g_hwndTree == NULL)
    ; /* Error handling here */
```

For more information on the various parameters used, see the Windows API documentation.

### Handling Notifications

As with standard Windows controls, applications must respond to events and messages to cause controls to respond to user requests. Most applications may want to implement some form of [notification](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) handler. By using the [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) application, sample event handlers are generated for you. For additional information, see "Notifications".

#### Expanding/Collapsing Items

**Note:** A tree control will only send notification messages if its [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) includes the SFTTREESTYLE_NOTIFY style.

By handling the appropriate notification, a tree control can respond to the mouse-button clicks on the small button bitmaps or (double-)clicks on other areas of the tree control. If an application does not implement an event handler, the [tree items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items) do not automatically expand and collapse. The following code sample illustrates how the notifications could be handled:

```
case WM_COMMAND:                     /* WM_COMMAND message handler */
    if ((int) LOWORD(wParam) == IDC_TREE) {
        switch(HIWORD(wParam)) {
        case SFTTREEN_LBUTTONDBLCLK_TEXT:
        case SFTTREEN_LBUTTONDOWN_BUTTON:
        case SFTTREEN_LBUTTONDBLCLK_BUTTON: {
            int index;
            BOOL fExpand, fControl;
            /* Get current position */
            index = SftTree_GetExpandCollapseIndex(hwndTree);
            /* Check if item is expanded */
            fExpand = SftTree_GetItemExpand(hwndTree, index);
            /* If the CONTROL key is pressed, expand all dependent levels */
            fControl = (BOOL)(GetKeyState(VK_CONTROL)&0x8000);
            if (fExpand)
                SftTree_Collapse(hwndTree, index, TRUE);
            else
                SftTree_Expand(hwndTree, index, TRUE, fControl);
            break;
         }
        case SFTTREEN_EXPANDALL: { // expand all
            int index;
            index = SftTree_GetExpandCollapseIndex(hwndTree);
            SftTree_Expand(hwndTree, index, TRUE, TRUE);
            break;
         }
        case SFTTREEN_AUTOEXPANDING: {
            int index;
            index = SftTree_GetExpandCollapseIndex(hwndTree);
            SftTree_Expand(hwndTree, index, TRUE, FALSE);
            break;
         }
        }
    }
    break;
```

#### Drag & Drop

**Note: **A tree control will only support [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) operations if its window style includes the SFTTREESTYLE_DRAGDROP style.

When a user initiates a drag & drop operation, a WM_COMMAND / SFTTREEN_BEGINDRAG notification is sent to the parent window. All items that are currently selected are part of the drag & drop operation. To abort the operation at this point, the application can clear all [selections](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_selections) or send a WM_CANCELMODE message to the tree control. However, items may not be deleted or inserted during a drag & drop operation.

To find out more about the current drag & drop operation, an application can use [SftTree_GetDragInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_draginfo), which makes a pointer to a [SFTTREE_DRAGINFO](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_draginfo) structure available. This area is only valid while processing one WM_COMMAND notification and must be retrieved for each notification. The SFTTREE_DRAGINFO structure members are read/only unless otherwise indicated. SftTree_GetDragInfo should be used when processing SFTTREEN_BEGINDRAG, SFTTREEN_DRAGGING and SFTTREEN_ENDDRAG or SFTTREEN_CANCELDRAG notifications.

A user can abort a drag & drop operation by pressing the Escape key, at which point an application will receive a SFTTREEN_CANCELDRAG notification.

For more information, see the SFTTREE_DRAGINFO structure.

#### Cell Editing

**Note:** A tree control will only generate the [cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) notifications if its window style includes the SFTTREESTYLE_NOTIFY style.

SftTree/DLL supports a very easy cell editing protocol. Unlike other custom controls, no new API has to be used to edit data in a SftTree/DLL tree control. Existing Windows controls can be used to edit [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell), and because they are completely under your application's control, even owner-drawn controls and other custom controls can be used.

An application can "attach" a control to a SftTree/DLL control by creating the control and defining the tree control as the control's [parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent). This control, usually used to edit cells, is completely under your application's control. The tree control forwards all messages for the control directly to your application. This control can be created in response to a mouse button click (or double-click), or any other reasonable event in your application. Any Windows control can be used (edit controls, combo boxes, etc.). [SftTree_GetDisplayCellRect](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_displaycellrect) can be used to determine the proper location for the control.

This example shows how an application can respond to a left mouse-button double-click event by creating an edit control on the current item:

```
/* These routines handle cell editing. In this example,    */
/* an edit control is used. Any Windows control can be     */
/* used, even custom controls       .                      */

/* Start editing in response to a                          */
/* SFTTREEN_LBUTTONDBLCLK_TEXT notification.               */

int m_editIndex;                         /* Index of item being edited */
int m_editCol;                           /* Column # being edited */
HWND m_hwndEdit;                         /* Control used for editing */

/* Edit a specific cell.                                   */

static void StartEdit(int index, int col)
{
    TCHAR szBuffer[80];
    RECT rect;
    HWND EditParent;

    /* Make the cell completely visible */
    SftTree_MakeCellVisible(hwndTree, index, col);
    /* Get the location */
    if (!SftTree_GetDisplayCellRect(hwndTree, index, col, TRUE, &rect, NULL))
        return;
    m_editIndex = index; /* save position */
    m_editCol = col;

    /* Change selection style to not shown anything */
    SftTree_SetNoFocusStyle(hwndTree, SFTTREE_NOFOCUS_NOTHING);

    /* Repaint now in case we scrolled to make item visible */
    UpdateWindow(hwndTree);

    /* Create the edit control.*/
    /* Based on the tree control attributes and your preference, you may */
    /* have to adjust the rectangle used for the edit control. */

    SftTree_AdjustCellEditRect(hwndTree, m_editIndex, m_editCol, &rect);
    EditParent = SftTree_GetCellEditWindow(hwndTree, m_editIndex, m_editCol);
    m_hwndEdit = CreateWindow(TEXT("EDIT"), TEXT(""),/* Class, Title */
            WS_CHILD|WS_BORDER|ES_LEFT|ES_AUTOHSCROLL, /* Styles */
            rect.left, rect.top, rect.right-rect.left, rect.bottom-rect.top,
            EditParent,                  /* Tree control */
            (HMENU) IDC_EDIT_your_id,    /* <-- provide unique ID */
            app_instance,                /* <-- provide instance handle */
            NULL);
    if (!m_hwndEdit)                     /* Failed */
        return;

    /* Set some edit control attributes */

    /* Copy the font used for tree items */
    SendMessage(m_hwndEdit, WM_SETFONT, SendMessage(hwndTree, WM_GETFONT, 0, 0L), 0L);

    /* Copy the text found in the tree control */
    SftTree_GetTextCol(hwndTree, m_editIndex, m_editCol, szBuffer);
    SetWindowText(m_hwndEdit, szBuffer);
    /* Select all text in the edit control and display it */
    SendMessage(m_hwndEdit, EM_SETSEL, 0, -1L);
    ShowWindow(m_hwndEdit, SW_SHOW);
    SetFocus(m_hwndEdit);                /* Set input focus to the control */
}

. . .
```

```
case WM_COMMAND:                     /* WM_COMMAND message handler */
    if ((int) LOWORD(wParam) == IDC_TREE) {
        switch(HIWORD(wParam)) {
        case SFTTREEN_LBUTTONDBLCLK_TEXT: {
            /* Edit the current cell */
            /* Get cell to edit (honors cell merging) */
            int index, col;
            index = SftTree_GetCaretIndex(hwndTree);/* Get item index */
            col = SftTree_GetCaretColumn(hwndTree);/* Get column number */
            StartEdit(index, col);
            break;
         }
        case SFTTREEN_QUITEDIT:
            /* Abandon editing */
            QuitEdit();
            break;
        case SFTTREEN_VALIDATEEDIT:
            /* Validate input data */
            ValidateEdit();
            break;
        }
    }
    break;
```

Once a tree control has an attached child window, it generates the SFTTREEN_QUITEDIT and SFTTREEN_VALIDATEEDIT notifications, which signal the tree's parent window to abandon editing by destroying any associated controls, or to validate the input data, issue error messages and/or destroy the controls. When an application receives the SFTTREEN_QUITEDIT notification, it must unconditionally abort editing by destroying all child controls.

```
/* Quit editing in response to a SFTTREEN_QUITEDIT         */
/* notification.                                           */

static void QuitEdit(void)
{
    if (m_hwndEdit) {
        /* If the control has the focus, set the focus back to the */
        /* tree control after destroying the control */

        BOOL fHadFocus = (GetFocus() == m_hwndEdit);

        DestroyWindow(m_hwndEdit);
        m_hwndEdit = NULL;
        /* Restore nofocus display method */
        SftTree_SetNoFocusStyle(hwndTree, SFTTREE_NOFOCUS_KEEPSEL);
        if (fHadFocus)
            SetFocus(hwndTree);          /* Back to tree control */
    }
}

/* Validate edit data in response to a                     */
/* SFTTREEN_VALIDATEEDIT notification.                     */

static void ValidateEdit(void)
{
    if (m_hwndEdit) {
        TCHAR szBuffer[80];

        /* Get the text from the edit control */
        GetWindowText(m_hwndEdit, szBuffer, sizeof(szBuffer));

        /* Validate the data */
        if (lstrcmp(TEXT(""), szBuffer) == 0) {
            MessageBox(NULL, TEXT("Just to demonstrate data input validation, this example ")
                   TEXT("rejects empty cells.  Please enter some data."),
                   TEXT("SftTree/DLL"), MB_OK|MB_TASKMODAL|MB_ICONSTOP);
            SetFocus(m_hwndEdit);
        } else {
            DestroyWindow(m_hwndEdit);
            m_hwndEdit = NULL;
            /* Save the data in the tree control */
            SftTree_SetTextCol(hwndTree, m_editIndex, m_editCol, szBuffer);
            /* Restore nofocus display method */
            SftTree_SetNoFocusStyle(hwndTree, SFTTREE_NOFOCUS_KEEPSEL);
        }
    }
}
```

While editing cells using a control, the user may abort editing by pressing the Escape key. This generates a SFTTREEN_QUITEDIT notification.

#### Additional Considerations

When creating controls for cell editing, a suitable font may have to be used. If a control is too small to display the data, the data may not only be clipped, but may even be completely suppressed. This is particularly noticeable with edit controls. An application can choose to increase the size of the control used for cell editing.

If cell editing is started under program control during a WM_INITDIALOG message or anytime the tree control has not yet been painted, the tree control has to be painted explicitly before a child control can be attached. This can be accomplished by using the *UpdateWindow* call.

### 3D Display

The [extended window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles_ext) WS_EX_CLIENTEDGE can be specified for the tree control, resulting in a 3D edge instead of a flat border.

## Using C++/MFC

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingcpp*

This section describes how to use SftTree/DLL in an application written [using C](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_usingc)++ and the Microsoft Foundation Class library (MFC).

### Adding SftTree/DLL to an Application

Please see "[Building Applications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp)" to prepare a project for development with SftTree/DLL.

|  |  |
| --- | --- |
| A) | Every source program making use of a SftTree/DLL control must include the required header file SftTree.h by using the #include directive.`#include "SftTree.h" /* SftTree/DLL required header file */`This include statement should appear after the #include <stdafx.h> statement or can be included at the end of stdafx.h. The file is located in the directory \Program Files\Softelvdm\SftTree DLL 8.0\Include (unless changed during the installation). On Windows 64-bit versions, the root folder is \Program Files** (x86)**.The project settings may need to be updated so the #include file can be located (see "Building Applications" for more information). |
| B) | The source program SftTreeM.cpp must be added to your project. It is added to the project, without making any modifications to the file, using Visual Studio's *Project, Add To Project, Files...* menu command. The file is located in the directory \Program Files\Softelvdm\SftTree DLL 8.0\Include (unless changed during the installation). On Windows 64-bit versions, the root folder is \Program Files** (x86)**.Instead of simply adding it to the project, you can include the file using the #include directive. However, it must be included in a source file (*.cpp) as it is not a header file and only one source file can #include the file SftTreeM.cpp.`#include "SftTreeM.cpp"`This include statement should appear after the #include "SftTree.h" statement.The project settings may need to be updated so the source file or #include file can be located (see "Building Applications" for more information). |
| C) | In order to use SftTree/DLL controls, an application must call the [CSftTree::RegisterApp](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_registerapp) function. The call to this function is required so that SftTree/DLL window classes can be registered. This call has to be made before any SftTree/DLL controls are created. Add the following statement to your source code. The preferred location is the InitInstance member function of your CWinApp or CSftTree_App based application object:`CSftTree::RegisterApp(); /* Use SftTree/DLL with this application */` |
| D) | Once SftTree/DLL controls are no longer needed, an application must call the [CSftTree::UnregisterApp](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_unregisterapp) function. The call to this function is required so that SftTree/DLL window classes can be unregistered and cleanup processing can take place. This call has to be made after all SftTree/DLL controls have been destroyed. The preferred location is the ExitInstance member function of your CWinApp based application object: `CSftTree::UnregisterApp(); /* No longer use SftTree/DLL */` |
| E) | The application's executable (Exe or Dll) must be linked with the correct Lib file, depending on the target environment. Please see "Building Applications" for more information.The project settings may need to be updated so the Lib files can be located (see "Building Applications" for more information). |

### Adding a Tree Control

ClassWizard does not support new classes such as [CSftTree](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api), so any tree control instance variables, [notification](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) handlers, message map entries, etc., have to be added manually. To simplify this process, you can copy these items that are generated by ClassWizard for other "standard" Windows controls (such as a list box).

There are two methods to add a tree control to an application:

- using dialog resources
- using [CSftTree::Create](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_csfttree_create)

Adding a tree control using dialog resources is accomplished by using a resource editor to design a dialog. For more information, see "[Creating a Dialog Resource](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_vc)". Once a tree control is created, its CSftTree based object can be obtained by using the Windows GetDlgItem function or attached to a CSftTree or CSftTreeSplit object using SubclassDlgItem.

```
CSftTree * pTree;
pTree = (CSftTree *) GetDlgItem(IDC_TREE);
```

or

```
CSftTree m_Tree;
m_Tree.SubclassDlgItem(IDC_TREE, this);
```

Another method to create a tree control is by using the CSftTree::Create or CSftTreeSplit::Create member function.

```
CSftTree m_Tree;
if (!m_Tree.Create(
        SFTTREESTYLE_NOTIFY | /* Notify parent window */
        SFTTREESTYLE_DRAGDROP | /* Drag & drop enabled */
        SFTTREESTYLE_LEFTBUTTONONLY | /* Only respond to left mouse button */
        SFTTREESTYLE_SCROLL | /* Honor WS_H/VSCROLL */
        SFTTREESTYLE_DISABLENOSCROLL | /* Disable scrollbars instead of hiding */
        WS_HSCROLL | WS_VSCROLL | /* Vertical and horizontal scrollbars */
        WS_VISIBLE | WS_CHILD, /* Visible, child window */
        CRect(x, y, x+cx, y+cy), /* Location */
        this, /* Parent window */
        IDC_TREE)) /* Tree control ID */
    ; /* Error handling here */
```

For more information on the various parameters used, see the Create member function documentation.

### Handling Notifications

As with standard Windows controls, applications must respond to events and messages to cause controls to respond to user requests. Most applications may want to implement some form of notification handler. By using the [SftTree/DLL Wizard](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_wizard) application, sample event handlers are generated for you.

ClassWizard does not support new classes such as CSftTree. So any tree control instance variables, notification handlers, message map entries, etc., have to be added manually. To simplify this process, you can copy these items that are generated by ClassWizard for other "standard" Windows controls (such as a list box).

#### Expanding/Collapsing Items

**Note:** A tree control will only send notification messages if its [window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles) includes the SFTTREESTYLE_NOTIFY style.

By handling the appropriate notification, a tree control can respond to the mouse-button clicks on the small button bitmaps or (double-)clicks on other areas of the tree control. If an application does not implement an event handler, the [tree items](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_items) do not automatically expand and collapse. The following code sample illustrates how the notifications could be handled:

```
/* Add the following to your parent window class. */
afx_msg void OnLButtonExpandCollapse();
afx_msg void OnExpandAll();
afx_msg void OnAutoExpand();
```

```
/* Add the following to the parent window message map. */
ON_SFTTREEN_LBUTTONDOWN_BUTTON(IDC_TREE, OnLButtonExpandCollapse)
ON_SFTTREEN_LBUTTONDBLCLK_BUTTON(IDC_TREE, OnLButtonExpandCollapse)
ON_SFTTREEN_EXPANDALL(IDC_TREE, OnExpandAll)
ON_SFTTREEN_AUTOEXPANDING(IDC_TREE, OnAutoExpand)
```

```
/* Respond to events as the user clicks on different tree  */
/* components.  The events handled here can be changed to  */
/* suit your application.                                  */
```

```
void CYourClass::OnLButtonExpandCollapse()
{
    /* get index of item to expand/collapse */
    int index = m_Tree.GetExpandCollapseIndex();
    /* get current expand/collapsed status */
    BOOL fExpanded = m_Tree.GetItemExpand(index);
    /* if control key is used we'll expand all dependents */
    BOOL fDepth = (::GetKeyState(VK_CONTROL)&0x8000);

    if (fExpanded)
        m_Tree.Collapse(index, TRUE);
    else
        m_Tree.Expand(index, TRUE, fDepth);
}

/* Respond to numeric keypad multiply key.                 */

void CYourClass::OnExpandAll()
{
    /* get index of item to expand/collapse */
    int index = m_Tree.GetExpandCollapseIndex();

   m_Tree.Expand(index, TRUE, TRUE);
}

/* Auto-Expand                                             */

void CYourClass::OnAutoExpand()
{
    /* get index of item to expand/collapse */
    int index = m_Tree.GetExpandCollapseIndex();

    m_Tree.Expand(index, TRUE, FALSE);
}
```

#### Drag & Drop

**Note:** A tree control will only support [drag & drop](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_dragdrop) operations if its window style includes the SFTTREESTYLE_DRAGDROP style.

When a user initiates a drag & drop operation, a WM_COMMAND / SFTTREEN_BEGINDRAG notification is sent to the parent window. All items that are currently selected are part of the drag & drop operation. To abort the operation at this point, the application can clear all [selections](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_selections) or send a WM_CANCELMODE message to the tree control. However, items may not be deleted or inserted during a drag & drop operation.

To find out more about the current drag & drop operation, an application can use [GetDragInfo](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_draginfo), which makes a pointer to a [SFTTREE_DRAGINFO](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/struct_sfttree_draginfo) structure available. This area is only valid while processing one notification and must be retrieved for each notification. The SFTTREE_DRAGINFO structure fields are read/only unless otherwise indicated. GetDragInfo should be used when processing SFTTREEN_BEGINDRAG, SFTTREEN_DRAGGING and SFTTREEN_ENDDRAG or SFTTREEN_CANCELDRAG notifications.

A user can abort a drag & drop operation by pressing the Escape key, at which point an application will receive a SFTTREEN_CANCELDRAG notification.

For more information, see the SFTTREE_DRAGINFO structure.

#### Cell Editing

**Note:** A tree control will only generate the [cell editing](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_cell_editing) notifications if its window style includes the SFTTREESTYLE_NOTIFY style.

SftTree/DLL supports a very easy cell editing protocol. Unlike other custom controls, no new API has to be used to edit data in a SftTree/DLL tree control. Existing Windows controls can be used to edit [cells](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_cell), and because they are completely under your application's control, even owner-drawn controls and other custom controls can be used.

An application can "attach" a control to a SftTree/DLL control by creating the control and defining the tree control as the control's [parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent). This control, usually used to edit cells, is completely under your application's control. The tree control forwards all messages for the control directly to your application. This control can be created in response to a mouse button click (or double-click), or any other reasonable event in your application. Any Windows control can be used (edit controls, combo boxes, etc.). [GetDisplayCellRect](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/function_displaycellrect) can be used to determine the proper location for the control.

This example shows how an application can respond to a left mouse-button double-click event by creating an edit control on the current item:

```
/* Cell Editing */
int m_editIndex;                     /* Index of item being edited */
int m_editCol;                       /* Column # being edited */
CEdit* m_pEdit;                      /* Control used for editing */

void StartEdit(int index, int col);  /* Start cell editing */
afx_msg void OnStartEdit();          /* Start cell editing */
afx_msg void OnQuitEdit();           /* Abandon cell editing */
afx_msg void OnValidateEdit();       /* Validate input */

/* Add the following to the window message map.            */

/* Cell Editing */
ON_SFTTREEN_LBUTTONDBLCLK_TEXT(IDC_TREE, OnStartEdit)
ON_SFTTREEN_QUITEDIT(IDC_TREE, OnQuitEdit)
ON_SFTTREEN_VALIDATEEDIT(IDC_TREE, OnValidateEdit)

/* Add the following to your parent window class           */
/* constructor.                                            */

m_pEdit = NULL;                      /* No cell editing */

/* These routines handle cell editing. In this example,    */
/* an edit control is used. Any Windows control can be     */
/* used, even custom controls.                             */

/* Edit a specific cell.                                   */

void CYourClass::StartEdit(int index, int col)
{
    CRect rect;

    /* Make the cell completely visible */
    m_Tree.MakeCellVisible(index, col);
    /* get the item location */
    if (!m_Tree.GetDisplayCellRect(index, col, TRUE, &rect, NULL))
        return;                          /* No column active */
    m_editIndex = index; /* save position */
    m_editCol = col;

    /* Change selection style to not shown anything */
    m_Tree.SetNoFocusStyle(SFTTREE_NOFOCUS_NOTHING);

    /* Repaint now in case we scrolled to make item visible */
    m_Tree.UpdateWindow();

    /* Create the edit control.*/
    /* Based on the tree control attributes and your preference, you may */
    /* have to adjust the rectangle used for the edit control. */

    m_Tree.AdjustCellEditRect(m_editIndex, m_editCol, rect);
    CWnd* pEditParent = m_Tree.GetCellEditWindow(m_editIndex, m_editCol);
    m_pEdit = new CEdit;
    m_pEdit->Create(
            WS_CHILD|WS_BORDER|ES_LEFT|ES_AUTOHSCROLL, /* Styles */
            rect,                        /* Coordinates */
            pEditParent,                 /* Parent window */
            IDC_EDIT_your_id);           /* <-- provide unique ID */

    /* Set some edit control attributes */

    /* Copy the font used for tree items */
    m_pEdit->SetFont(m_Tree.GetFont(), FALSE);

    /* Copy the text found in the tree control */
    CString str;
    m_Tree.GetText(m_editIndex, m_editCol, str);
    m_pEdit->SetWindowText(str);
    /* Select all text in the edit control and display it */
    m_pEdit->SetSel(0, -1, TRUE);
    m_pEdit->ShowWindow(SW_SHOW);
    m_pEdit->SetFocus();                 /* Set input focus to the control */
}

/* Start editing in response to a                          */
/* SFTTREEN_LBUTTONDBLCLK_TEXT notification.               */

void CYourClass::OnStartEdit()
{
    /* Get cell to edit (honors cell merging) */
    int index, col;
    index = m_Tree.GetCaretIndex();      /* Get item index */
    col = m_Tree.GetCaretColumn();       /* Get column number */
    StartEdit(index, col);
}
```

Once a tree control has one or more attached child windows, it generates the SFTTREEN_QUITEDIT and SFTTREEN_VALIDATEEDIT notifications, which signal the tree's parent window to abandon editing by destroying any associated controls, or to validate the input data, issue error messages and/or destroy the controls. When an application receives the SFTTREEN_QUITEDIT notification, it must unconditionally abort editing by destroying all child controls.

```
/* Quit editing in response to a SFTTREEN_QUITEDIT         */
/* notification.                                           */

void CYourClass::OnQuitEdit()
{
    if (m_pEdit) {
        /* If the control has the focus, set the focus back to the */
        /* tree control after destroying the control */

        BOOL fHadFocus = (GetFocus() == m_pEdit);

        m_pEdit->DestroyWindow();
        delete m_pEdit;
        m_pEdit = NULL;
        /* Restore nofocus display method */
        m_Tree.SetNoFocusStyle(SFTTREE_NOFOCUS_KEEPSEL);
        if (fHadFocus)
            m_Tree.SetFocus();           /* Back to tree control */
    }
}

/* Validate edit data in response to a                     */
/* SFTTREEN_VALIDATEEDIT notification.                     */

void CYourClass::OnValidateEdit()
{
    if (m_pEdit) {
        CString str;

        /* Get the text from the edit control */
        m_pEdit->GetWindowText(str);

        /* Validate the data */
        if (str == _T("")) {
            AfxMessageBox(_T("Just to demonstrate data input validation, ")
               _T("this example rejects empty cells.  Please enter some data."));
            m_pEdit->SetFocus();
        } else {
            m_pEdit->DestroyWindow();
            delete m_pEdit;
            m_pEdit = NULL;
            /* Save the data in the tree control */
            m_Tree.SetText(m_editIndex, m_editCol, str);
            /* Restore nofocus display method */
            m_Tree.SetNoFocusStyle(SFTTREE_NOFOCUS_KEEPSEL);
        }
    }
}
```

While editing cells using a control, the user may abort editing by pressing the Escape key. This generates a SFTTREEN_QUITEDIT notification.

#### Additional Considerations

When creating controls for cell editing, a suitable font may have to be used. If a control is too small to display the data, the data may not only be clipped, but may even be completely suppressed. This is particularly noticeable with edit controls. An application can choose to increase the size of the control used for cell editing.

If cell editing is started under program control during a WM_INITDIALOG message or anytime the tree control has not yet been painted, the tree control has to be painted explicitly before a child control can be attached. This can be accomplished by using the *UpdateWindow* call.

### 3D Display

The [extended window style](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_windowstyles_ext) WS_EX_CLIENTEDGE can be specified for the tree control, resulting in a 3D edge instead of a flat border.

## MFC and Notifications

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_notificationsmfc*

[Notifications](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_notifications) can be handled by a tree control's parent window or directly by the tree control itself (in a derived class). WM_COMMAND messages are sent by the control to the parent window. The notification codes used are listed in section "Notifications".

### Parent Window

If you want to handle Windows notification messages sent by a tree control to its [parent](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/pop_parent) (usually a class derived from CDialog or CView), add a message-map entry and a message-handler member function to the parent class for each notification.

Message-map entries take the following form for WM_COMMAND and WM_NOTIFY notifications:

```
ON_Notification( id, memberFxn )
```

The parent's function prototype is as follows:

```
/* for WM_COMMAND notifications */
afx_msg void memberFxn( );
```

```
/* for WM_NOTIFY notifications */
afx_msg void memberFxn(NMHDR * pNotifyStruct, LRESULT* result);
```

*Notification* specifies one of the available notification codes listed in Notifications. *id *specifies the child window ID of the control sending the notification and *memberFxn* is the name of the parent member function in your application which handles the notification.

### Example

```
// Event handler prototype added to dialog class 
afx_msg void OnSelChange(); 
```

```
// Event handler(s) added to message map 
BEGIN_MESSAGE_MAP(CYourDialog, CDialog)
 ON_SFTTREEN_SELCHANGE(IDC_TREE, OnSelChange)
END_MESSAGE_MAP() 
```

```
// event handler implementation 
void CYourDialog::OnSelChange() 
{ 
    // get index of the newly selected item 
    int index = m_Tree.GetCurSel();
} 
```

### Derived Objects

By overriding the OnChildNotify function of an object derived from [CSftTree](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/i_api), you can handle messages in the object's class. The parameters are as documented in Notifications. Please see the Visual C++ documentation for additional information regarding the OnChildNotify function. However, the use of message reflection as shown next is the preferred method to handle messages.

MFC defines the ON_CONTROL_REFLECT and ON_NOTIFY_REFLECT macros which allow adding notifications directly to the message map. SftTree/DLL implements all required macros based on ON_CONTROL_REFLECT and ON_NOTIFY_REFLECT. See the MFC documentation for more information on message reflection.

Message-map entries take the following form:

```
ON_Notification_REFLECT( memberFxn )
```

The function prototype is as follows:

```
/* for WM_COMMAND notifications */
afx_msg void memberFxn( );
```

```
/* for WM_NOTIFY notifications */
afx_msg void memberFxn(NMHDR * pNotifyStruct, LRESULT* result);
```

*Notification* specifies one of the available notification codes listed in Notifications. *memberFxn* is the name of the member function in your object's class which handles the notification.

### Example

```
BEGIN_MESSAGE_MAP(CYourTree, CSftTree)
  ON_WM_CREATE()
  ON_SFTTREEN_SELCHANGE_REFLECT(OnSelChangeReflect)
END_MESSAGE_MAP() 
```

```
// event handler implementation 
void CYourTree::OnSelChangeReflect() 
{ 
    // get index of the newly selected item 
    int index = GetCurSel();
} 
```

## Distributing the Dlls

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_distributing*

Distributing the Dlls included with SftTree/DLL is only possible in accordance with the license agreement. The license agreement is furnished with the purchase of SftTree/DLL.

The Dlls contain your license number and are serialized.

Modification of the original Dlls as included with the product is not permitted to insure that no incompatibilities exist between different software packages that use SftTree/DLL. Any install procedure that is used to install Dlls which are included with SftTree/DLL must do proper version checking.

> Applications you create with SftTree/DLL for distribution must be complete end-user applications. It is not possible to distribute the controls to unlicensed users for development purposes. This means that your distributed end-user application cannot be a Debug build, cannot contain debug information, symbol information, etc.

### Dlls

Certain product Dlls can be distributed royalty-free with your application in accordance with the licensing agreement. The licensing agreement is furnished with the purchase of SftTree/DLL.

The application's executable (Exe or Dll) must be linked with the correct LIB file, depending on the target environment and the compiler used. The Dll must be available and accessible at run-time for proper execution (unless static [linking](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_buildingapp) is used). The Dll used at run-time depends on the LIB file used at link time.

For the required Dll, please see "Building Applications". If the application is linked statically to SftTree/DLL, a Dll is not required.

All required files can be found in the directory \Program Files\Softelvdm\SftTree DLL 8.0\Lib and \Program Files\Softelvdm\SftTree DLL 8.0\Dll, unless changed during the installation. On Windows 64-bit versions, the root folder is \Program Files** (x86)**.

Please note that available processor support depends on the installed and purchased product versions.

### GDI+ (Optional)

Certain features of the control require [GDI+](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_gdiplus) support. GDI+ is available on all supported Windows versions (Windows 10 and above).

If GDI+ support is not available, the features are simply disabled and alternate presentation methods are used, if necessary.

### Target Directory

The Dlls can be installed in the application's directory and can be used locally, without interfering with any other applications which may use other versions of SftTree/DLL.

The Dlls included with SftTree/DLL can also be installed in the Windows System directory. On 64-bit Windows, 64-bit Dlls are installed in the System32 directory and the 32-bit Dlls are installed in the SysWOW64 directory. On 32-bit Windows, the 32-bit Dlls are installed in the System32 directory. When installing Dlls in Windows directories, strict version checking and reference counting must be performed to avoid conflicts if different software packages use SftTree/DLL.

### Version Checking

The Dlls included with SftTree/DLL carry proper version information. A shared Dll should only be replaced if its version information indicates that the existing Dll is older.

Commercial installers and setup programs have built-in features to insure proper Dll versioning. See your installer's documentation for more information.

### Reference Counting

If a Dll is installed into the Windows System(32) or SysWOW64 directory, it can potentially be installed and used by other applications also. It is required that any Dll installed in such a shared location keep proper reference counts by updating the proper Windows registry keys:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs

Commercial installers and setup programs have built-in features to insure proper usage and reference counting. See your installer's documentation for more information.

## Technical Support for SftTree/DLL 8.0

*Source: https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_contactsoftel*

### Product Updates

New major versions and product maintenance are available with an active support subscription. Your product purchase includes the first year's support subscription at no extra charge. After the first year, the support subscription can be renewed for continued availability of major versions and product maintenance.

While your support subscription is active, free product maintenance for the current release is available from our web site. Such free updates usually don't include any [new features](https://softelvdm.com/Documentation/SftTree%20DLL%208%200/Topic/g_newfeatures) as a new release would, but include product and documentation fixes and corrections. In addition, new major and minor versions are also available at no extra charge for the duration of your active support subscription.

You can download updates by using the *Product Update* entry in the *SftTree/DLL 8.0* program group of the Windows Start menu.

### Before Contacting Product Support

Your product purchase includes the first year's support subscription at no extra charge, which includes free product support. After the first year, the support subscription can be renewed for continued availability of product support, major versions and product maintenance.

Comprehensive help files can assist you in using SftTree/DLL. If you have difficulties using SftTree/DLL, please use the following sources of information:

- Obtain help using the help files provided.
- Review support information or download product maintenance from our web site at [https://softelvdm.com/Product/Support/Name/SftTree DLL 8 0?ProductId=3125](https://softelvdm.com/Product/Support/Name/SftTree%20DLL%208%200?ProductId=3125).

If this does not resolve your problem, please contact Softel vdm, Inc. Product Support.

### Contacting Product Support

If you have reviewed the help and product documentation, please contact Softel vdm, Inc. Product Support. For current contact information please visit [https://softelvdm.com/support](https://softelvdm.com/support).

**IMPORTANT: **Please include your license number in all cases. Without your license number, we will not be able to help you. Your license number is printed on your installation media (CD) or you may have received it as part of your online delivery.