# Settings

TunnelCAD has two levels of settings: **project settings** that are stored in the `.tun` file, and **application settings** that persist across sessions in a local configuration file.

## Project settings dialog

Open the project settings dialog via **File > Settings...**. The dialog has a category list on the left and an editor panel on the right.

### Project Settings page

- **Project Name** -- the display name for the project, shown in the tab caption.
- **Tunnels** -- a read-only grid listing all tunnel alignments in the project. Tunnel names can be edited directly in this grid.

### Units page

See {doc}`units` for the full description of unit settings available on this page.

## Tunnel settings dialog

Open the tunnel settings dialog by double-clicking a tunnel in the project tree, or by right-clicking a tunnel and selecting **Settings...**. This dialog has three tabs.

### General tab

| Field | Description |
|---|---|
| Name | Tunnel name (unique within the project) |
| Description | Free-text metadata |
| Start Chainage | Beginning station value |
| End Chainage | Ending station value |
| Style | Alignment display style name |

### Line Definitions tab

A grid for managing **measured line definitions**. Each row represents one line definition with the following columns:

| Column | Description |
|---|---|
| Name | Line identifier (used in cross-sections) |
| Layer | Drawing layer assignment |
| Color | Display color (double-click to open the color picker) |
| Dev. Line | Deviation reference line (dropdown of all measured and template lines) |
| Style | Section line style (dropdown from the shared style library) |
| Draw | Visibility toggle (checkbox — single-click to toggle) |
| Closed | Whether the line forms a closed polygon (checkbox — single-click to toggle) |

Use the toolbar buttons to manage definitions:

- **Add** -- creates a new measured line definition (prompts for name).
- **Delete** -- removes the selected definition and all its data from every cross-section.
- **Rename** -- changes the name of the selected definition across all cross-sections.
- **Style Editor** -- opens the section line style editor to create or modify styles in the shared library.

```{admonition} Warning
:class: warning
Deleting a line definition removes all measured data for that line from every cross-section in the tunnel. This cannot be undone.
```

### Template Lines tab

A grid for managing **template line definitions** with the following columns:

| Column | Description |
|---|---|
| Name | Line identifier (used in templates) |
| Layer | Drawing layer assignment |
| Color | Display color (double-click to open the color picker) |
| Draw | Visibility toggle (checkbox — single-click to toggle) |
| Closed | Read-only checkbox, mirrors the template geometry's closed state |

Use the **Add** and **Delete** buttons to manage template line definitions. Deleting a template line removes its geometry from all templates.

## Application settings

Application-level settings are stored in a JSON configuration file:

- **Linux**: `~/.config/TunnelCAD/settings.json`
- **Windows**: `%APPDATA%\TunnelCAD\settings.json`

These settings include:

- **Canvas background color** -- the background color of the drawing canvases.
- **Window position and size** -- restored on next launch.
- **Recent files list** -- the most recently opened project files.

## Debug logging

TunnelCAD includes a built-in debug logging system for troubleshooting. To enable it, add `"debugLog": true` to the `settings.json` file:

```json
{
  "debugLog": true
}
```

When enabled, timestamped log entries are written to `iqcad_debug.log` in the application directory. The log uses flush-per-write, so entries survive crashes. Logging is always compiled into the application but remains dormant until explicitly enabled.