---
product: Chilkat
product_version: 11.7.0
language: pascal
language_label: Lazarus Pascal
class: DirTree
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/pascal_DirTreeRef.html
---
# Chilkat DirTree — Lazarus Pascal — v11.7.0

> Chilkat 11.7.0 · language=pascal · 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/pascal/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 / Free**

```pascal
uses
  Chilkat.DirTree;

var
  obj: TDirTree;
begin
  obj := TDirTree.Create;
  try
    if not obj.IsValid then
      raise Exception.Create('Failed to create a TDirTree instance.');

    // ... use obj ...

  finally
    obj.Free;
  end;
end;
```

`constructor Create;`

Allocates the underlying CkDirTree object and returns a new TDirTree instance. Simply adding **Chilkat.DirTree** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed).

`destructor Destroy; override;`

Every TDirTree created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkDirTree handle. A native (unmanaged) memory leak occurs if the object is never freed.

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 Lazarus Pascal.

## 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` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | 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` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `BaseDir` | property, read/write | `property BaseDir: string read GetBaseDir write SetBaseDir;` |
| `DoneIterating` | property, read-only | `property DoneIterating: Boolean read GetDoneIterating;` |
| `FileSize32` | property, read-only | `property FileSize32: Integer read GetFileSize32;` |
| `FileSize64` | property, read-only | `property FileSize64: Int64 read GetFileSize64;` |
| `FileSizeStr` | property, read-only | `property FileSizeStr: string read GetFileSizeStr;` |
| `FullPath` | property, read-only | `property FullPath: string read GetFullPath;` |
| `FullUncPath` | property, read-only | `property FullUncPath: string read GetFullUncPath;` |
| `IsDirectory` | property, read-only | `property IsDirectory: Boolean read GetIsDirectory;` |
| `Recurse` | property, read/write | `property Recurse: Boolean read GetRecurse write SetRecurse;` |
| `RelativePath` | property, read-only | `property RelativePath: string read GetRelativePath;` |
| `UncommonOptions` | property, read/write | `property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions;` |
| `AdvancePosition` | method | `function AdvancePosition: Boolean;` |
| `BeginIterate` | method | `function BeginIterate: Boolean;` |

## Properties

### DirTree.BaseDir

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

```pascal
property BaseDir: string read GetBaseDir write SetBaseDir;
```

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 · pascal · DirTree · DoneIterating · property · read-only`

```pascal
property DoneIterating: Boolean read GetDoneIterating;
```

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 · pascal · DirTree · FileSize32 · property · read-only`

```pascal
property FileSize32: Integer read GetFileSize32;
```

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 · pascal · DirTree · FileSize64 · property · read-only`

```pascal
property FileSize64: Int64 read GetFileSize64;
```

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 · pascal · DirTree · FileSizeStr · property · read-only · since 9.5.0.88`

```pascal
property FileSizeStr: string read GetFileSizeStr;
```

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 · pascal · DirTree · FullPath · property · read-only`

```pascal
property FullPath: string read GetFullPath;
```

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 · pascal · DirTree · FullUncPath · property · read-only`

```pascal
property FullUncPath: string read GetFullUncPath;
```

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 · pascal · DirTree · IsDirectory · property · read-only`

```pascal
property IsDirectory: Boolean read GetIsDirectory;
```

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 · pascal · DirTree · Recurse · property · read/write`

```pascal
property Recurse: Boolean read GetRecurse write SetRecurse;
```

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 · pascal · DirTree · RelativePath · property · read-only`

```pascal
property RelativePath: string read GetRelativePath;
```

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 · pascal · DirTree · UncommonOptions · property · read/write · since 11.1.0`

```pascal
property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions;
```

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 · pascal · DirTree · AdvancePosition · method`

```pascal
function  AdvancePosition: Boolean;
```

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 · pascal · DirTree · BeginIterate · method`

```pascal
function  BeginIterate: Boolean;
```

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.