---
product: Chilkat
product_version: 11.7.0
language: delphidll
language_label: Delphi DLL
class: DirTree
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/dd_CkDirTreeRef.html
---
# Chilkat DirTree — Delphi DLL — v11.7.0

> Chilkat 11.7.0 · language=delphidll · class=DirTree
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/DirTree.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/guide.md`.

## Purpose

**Iterate through files and subdirectories under a base directory.**

`Chilkat.DirTree` is a lightweight directory-tree iterator for traversing files and subdirectories under a selected base directory. It supports recursive and non-recursive traversal and exposes useful information about the current item, including absolute path, UNC path, relative path, file size, and whether the current item is a directory.

**Directory traversal**

Iterate through the contents of a base directory, either recursively or one level at a time.

**Current-item details**

Get the current item's full path, relative path, UNC path, size, and directory/file status.

**Recursive scanning**

Traverse entire directory trees when an application needs to process all nested files and folders.

**Non-recursive listing**

Limit iteration to the immediate contents of the base directory when deeper traversal is not needed.

**Path-friendly output**

Use absolute or relative paths depending on whether the application needs filesystem access or archive-style relative names.

**Error-aware iteration**

Use `DoneIterating` to distinguish normal completion from an error when an iteration method returns false.

**Common pattern:** Set the base directory and recursion behavior, begin iterating, process each current item using the path and metadata properties, then check `DoneIterating` when iteration stops to determine whether traversal completed normally or ended because of an error.

For an extended overview, see [DirTree Class Overview](https://www.chilkatsoft.com/dirtree_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```pascal
var
myObject: HCkDirTree;

begin
myObject := CkDirTree_Create();

// ...

CkDirTree_Dispose(myObject);
end;
```

`function CkDirTree_Create: HCkDirTree; stdcall;`

Creates an instance of the HCkDirTree object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

`procedure CkDirTree_Dispose(handle: HCkDirTree); stdcall;`

Objects created by calling CkDirTree_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Delphi DLL.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `procedure CkDirTree_getDebugLogFilePath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; procedure CkDirTree_putDebugLogFilePath(objHandle: HCkDirTree; newPropVal: PWideChar); stdcall; function CkDirTree__debugLogFilePath(objHandle: HCkDirTree): PWideChar; stdcall;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `procedure CkDirTree_getLastErrorHtml(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__lastErrorHtml(objHandle: HCkDirTree): PWideChar; stdcall;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `procedure CkDirTree_getLastErrorText(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__lastErrorText(objHandle: HCkDirTree): PWideChar; stdcall;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `procedure CkDirTree_getLastErrorXml(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__lastErrorXml(objHandle: HCkDirTree): PWideChar; stdcall;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `function CkDirTree_getLastMethodSuccess(objHandle: HCkDirTree): wordbool; stdcall; procedure CkDirTree_putLastMethodSuccess(objHandle: HCkDirTree; newPropVal: wordbool); stdcall;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `function CkDirTree_getVerboseLogging(objHandle: HCkDirTree): wordbool; stdcall; procedure CkDirTree_putVerboseLogging(objHandle: HCkDirTree; newPropVal: wordbool); stdcall;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `procedure CkDirTree_getVersion(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__version(objHandle: HCkDirTree): PWideChar; stdcall;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `BaseDir` | property, read/write | `procedure CkDirTree_getBaseDir(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; procedure CkDirTree_putBaseDir(objHandle: HCkDirTree; newPropVal: PWideChar); stdcall; function CkDirTree__baseDir(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `DoneIterating` | property, read-only | `function CkDirTree_getDoneIterating(objHandle: HCkDirTree): wordbool; stdcall;` |
| `FileSize32` | property, read-only | `function CkDirTree_getFileSize32(objHandle: HCkDirTree): Integer; stdcall;` |
| `FileSize64` | property, read-only | `function CkDirTree_getFileSize64(objHandle: HCkDirTree): Int64; stdcall;` |
| `FileSizeStr` | property, read-only | `procedure CkDirTree_getFileSizeStr(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__fileSizeStr(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `FullPath` | property, read-only | `procedure CkDirTree_getFullPath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__fullPath(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `FullUncPath` | property, read-only | `procedure CkDirTree_getFullUncPath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__fullUncPath(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `IsDirectory` | property, read-only | `function CkDirTree_getIsDirectory(objHandle: HCkDirTree): wordbool; stdcall;` |
| `Recurse` | property, read/write | `function CkDirTree_getRecurse(objHandle: HCkDirTree): wordbool; stdcall; procedure CkDirTree_putRecurse(objHandle: HCkDirTree; newPropVal: wordbool); stdcall;` |
| `RelativePath` | property, read-only | `procedure CkDirTree_getRelativePath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; function CkDirTree__relativePath(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `UncommonOptions` | property, read/write | `procedure CkDirTree_getUncommonOptions(objHandle: HCkDirTree; outPropVal: HCkString); stdcall; procedure CkDirTree_putUncommonOptions(objHandle: HCkDirTree; newPropVal: PWideChar); stdcall; function CkDirTree__uncommonOptions(objHandle: HCkDirTree): PWideChar; stdcall;` |
| `AdvancePosition` | method | `function CkDirTree_AdvancePosition(objHandle: HCkDirTree): wordbool; stdcall;` |
| `BeginIterate` | method | `function CkDirTree_BeginIterate(objHandle: HCkDirTree): wordbool; stdcall;` |

## Properties

### DirTree.BaseDir

`Chilkat 11.7.0 · delphidll · DirTree · BaseDir · property · read/write`

```pascal
procedure CkDirTree_getBaseDir(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
procedure CkDirTree_putBaseDir(objHandle: HCkDirTree; newPropVal: PWideChar); stdcall;
function CkDirTree__baseDir(objHandle: HCkDirTree): PWideChar; stdcall;
```

Specifies the root directory whose contents are traversed. Set this property before calling `BeginIterate`.

The value may be an absolute filesystem path or a relative path. A relative path is resolved from the calling process's current working directory.

**Iteration scope:** The iterator visits the files and subdirectories contained under this directory. The `Recurse` property determines whether nested levels are included.

### DirTree.DoneIterating

`Chilkat 11.7.0 · delphidll · DirTree · DoneIterating · property · read-only`

```pascal
function CkDirTree_getDoneIterating(objHandle: HCkDirTree): wordbool; stdcall;
```

Indicates whether the traversal has reached its normal end and no current item remains.

This property is especially important because both `BeginIterate` and `AdvancePosition` can return *`False`* for either normal completion or an error:

| Method result | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `False` | `True` | The directory was empty, or the last item has been passed. This is normal completion. |
| `False` | `False` | An error occurred. Examine `LastErrorText`. |

### DirTree.FileSize32

`Chilkat 11.7.0 · delphidll · DirTree · FileSize32 · property · read-only`

```pascal
function CkDirTree_getFileSize32(objHandle: HCkDirTree): Integer; stdcall;
```

Returns the size of the current file in bytes as a 32-bit integer. The value is `0` when the current item is a directory.

**Large files:** A 32-bit integer cannot represent all modern file sizes. Use `FileSize64` when the language binding provides it, or `FileSizeStr` when a decimal string is more portable.

### DirTree.FileSize64

`Chilkat 11.7.0 · delphidll · DirTree · FileSize64 · property · read-only`

```pascal
function CkDirTree_getFileSize64(objHandle: HCkDirTree): Int64; stdcall;
```

Returns the size of the current file in bytes as a 64-bit integer. The value is `0` when the current item is a directory.

This is the preferred numeric size property for files that may exceed the range of `FileSize32`. In bindings that do not expose a 64-bit integer property, use `FileSizeStr`.

### DirTree.FileSizeStr

`Chilkat 11.7.0 · delphidll · DirTree · FileSizeStr · property · read-only · since 9.5.0.88`

```pascal
procedure CkDirTree_getFileSizeStr(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
function CkDirTree__fileSizeStr(objHandle: HCkDirTree): PWideChar; stdcall;
```

Returns the size of the current file in bytes as an unsigned decimal string. The value is `0` when the current item is a directory.

This representation is useful for very large files and for language bindings where a 64-bit integer is unavailable or inconvenient. Convert the string to an appropriate arbitrary-precision or 64-bit numeric type only when arithmetic is required.

### DirTree.FullPath

`Chilkat 11.7.0 · delphidll · DirTree · FullPath · property · read-only`

```pascal
procedure CkDirTree_getFullPath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
function CkDirTree__fullPath(objHandle: HCkDirTree): PWideChar; stdcall;
```

Returns the absolute filesystem path of the current file or subdirectory, including the item's name.

The path uses the native path syntax for the operating system. For a path relative to `BaseDir`, use `RelativePath`.

### DirTree.FullUncPath

`Chilkat 11.7.0 · delphidll · DirTree · FullUncPath · property · read-only`

```pascal
procedure CkDirTree_getFullUncPath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
function CkDirTree__fullUncPath(objHandle: HCkDirTree): PWideChar; stdcall;
```

Returns the current item's Windows extended-length absolute path. For example, a local path may be returned as `\\?\C:\data\reports\file.txt`; a network path may use the `\\?\UNC\server\share\...` form.

**Windows path form:** The `\\?\` prefix asks Windows to use extended-length path parsing and is useful when working with paths that may exceed legacy path-length limits. Use `FullPath` when an ordinary native absolute path is preferred.

### DirTree.IsDirectory

`Chilkat 11.7.0 · delphidll · DirTree · IsDirectory · property · read-only`

```pascal
function CkDirTree_getIsDirectory(objHandle: HCkDirTree): wordbool; stdcall;
```

Returns *`True`* when the current item is a subdirectory and *`False`* when it is a file.

Check this property before using a file-size property. Directory items report a size of `0`.

### DirTree.Recurse

`Chilkat 11.7.0 · delphidll · DirTree · Recurse · property · read/write`

```pascal
function CkDirTree_getRecurse(objHandle: HCkDirTree): wordbool; stdcall;
procedure CkDirTree_putRecurse(objHandle: HCkDirTree; newPropVal: wordbool); stdcall;
```

Controls whether traversal descends into nested subdirectories.

| `True` | Visit files and directories throughout the complete tree rooted at `BaseDir`. |
| :--- | --- |
| `False` | Visit only the immediate contents of `BaseDir`. |

The default value is *`True`*. Set this property before calling `BeginIterate`.

### DirTree.RelativePath

`Chilkat 11.7.0 · delphidll · DirTree · RelativePath · property · read-only`

```pascal
procedure CkDirTree_getRelativePath(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
function CkDirTree__relativePath(objHandle: HCkDirTree): PWideChar; stdcall;
```

Returns the path of the current file or subdirectory relative to `BaseDir`, including the item's name.

For example, if `BaseDir` is `C:\data` and the current item is `C:\data\images\logo.png`, this property returns `images\logo.png` on Windows. Path separators follow the operating system's native convention.

### DirTree.UncommonOptions

`Chilkat 11.7.0 · delphidll · DirTree · UncommonOptions · property · read/write · since 11.1.0`

```pascal
procedure CkDirTree_getUncommonOptions(objHandle: HCkDirTree; outPropVal: HCkString); stdcall;
procedure CkDirTree_putUncommonOptions(objHandle: HCkDirTree; newPropVal: PWideChar); stdcall;
function CkDirTree__uncommonOptions(objHandle: HCkDirTree): PWideChar; stdcall;
```

Provides a comma-separated list of specialized compatibility options. The default is the empty string, and applications should normally leave it unchanged.

| Keyword | Effect |
| :--- | :--- |
| `Q_EncodePaths` | Returns path-valued output properties in Chilkat's Q-encoded representation. Introduced in Chilkat v11.1.0. This changes only the returned string representation; it does not change which filesystem items are traversed. |

## Methods

### DirTree.AdvancePosition

`Chilkat 11.7.0 · delphidll · DirTree · AdvancePosition · method`

```pascal
function CkDirTree_AdvancePosition(objHandle: HCkDirTree): wordbool; stdcall;
```

Advances the traversal from the current item to the next file or subdirectory.

If the method returns *`True`*, the current-item properties—such as `FullPath`, `RelativePath`, `IsDirectory`, and the file-size properties—describe the newly selected item.

| Return value | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `True` | `False` | The iterator advanced successfully and a current item is available. |
| `False` | `True` | The last item has been passed; traversal completed normally. |
| `False` | `False` | An error occurred. Examine `LastErrorText`. |

Returns True for success, False for failure.

### DirTree.BeginIterate

`Chilkat 11.7.0 · delphidll · DirTree · BeginIterate · method`

```pascal
function CkDirTree_BeginIterate(objHandle: HCkDirTree): wordbool; stdcall;
```

Initializes a new traversal using the current `BaseDir` and `Recurse` settings.

If the method returns *`True`*, the iterator is positioned at the first file or subdirectory, and the current-item properties can be read immediately. Continue by processing that item and then calling `AdvancePosition`.

| Return value | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `True` | `False` | The first item is available. |
| `False` | `True` | The directory contains no items in the selected traversal scope. This is not an error. |
| `False` | `False` | Initialization failed. Examine `LastErrorText`. |

**Property lifetime:** Treat the current-item properties as valid only while the iterator is positioned on an item—that is, after a successful `BeginIterate` or `AdvancePosition`.

Returns True for success, False for failure.