DTLdesktop — Reference Manual v1.1-1

Preface

Purpose

This manual describes what DTLdesktop is, why it was created, and what it does. It is a functional and architecture reference. It deliberately contains no menu description, no command reference, and no step-by-step procedure.

DTLdesktop captures and restores a complete Windows desktop configuration — screen layout and orientation, per-monitor wallpaper, and the position of every desktop icon — as a named profile, and coordinates their restoration in a single verified operation.

Intended audience

This document is intended for administrators of multi-monitor workstations, maintainers of the NetDTL suite, and anyone who needs to understand DTLdesktop's capture and restoration behavior before integrating it into a workstation or a startup script.

Design principles

• Locality: profiles are stored locally, alongside the application, with no dependency on a remote service.
• Independence from Windows naming: configuration recognition relies on a normalized geometric signature, unaffected by how Windows names or renumbers screens.
• Coordination: orientation, resolution, wallpapers, and icons are treated as a single coherent desktop state, not as three independent settings.
• Verification: every profile application is checked afterward; a discrepancy triggers an automatic attempt to return to the previous state.
• Non-intrusive diagnostics: comparing a profile to the current state never applies any change.
• Language: DTLdesktop's interface is in French; this manual is available in French and English.

Background

Origin of the need

On Windows, the layout of desktop icons and the assignment of a wallpaper to each monitor are not reliably preserved when the screen configuration changes: adding, removing, or physically swapping a monitor, changing resolution or orientation, or reconnecting after sleep or a docking-station change. Windows then redistributes icons according to its own logic, and the association between a given wallpaper and a given screen can be lost or shifted to the wrong screen.

An aggravating factor lies in how screens are named in the first place: the identifiers Windows assigns to each monitor are not stable over time. A simple physical swap of two screens can be enough to reverse this numbering, even though the layout the user actually intended has not changed.

Problem addressed

DTLdesktop was created to address this problem at its root: recognize a screen configuration by its geometry rather than by the name Windows happens to assign it at a given moment, and restore, in a single verified operation, the entire desktop state associated with that configuration — orientation, resolution, the wallpaper matching each screen's current orientation, and the position of every icon.

Architecture

Overview

DTLdesktop is organized into three layers: a system-access layer for Windows display, per-monitor wallpaper, and desktop icon APIs; a profile-modeling layer that captures, compares, and applies a desktop state; and a presentation layer, interactive or non-interactive.

If verification of any of these three branches fails, DTLdesktop attempts to automatically roll back to the desktop state captured just before the application.

Components

File organization

Data model

Configuration signature

Each profile records a normalized geometric signature of the full set of screens: position relative to the top-left-most screen, width, height, orientation, and primary-screen status, sorted deterministically. This signature makes no reference to any device name. It is recomputed from the actually observed configuration whenever a comparison is needed, which lets a previously known layout be recognized even if Windows has renamed or renumbered the screens since the profile was captured.

Screen identification

Beyond the geometric signature, each screen has a native Windows identifier used to associate it with its wallpaper; this identifier is distinct from the display device name. When every identifier of a profile is found in the current configuration, the match is established on that basis; otherwise it relies on the geometric signature alone.

Icon identification

Each desktop icon is identified by its name and by its rank among icons sharing that same name, which distinguishes several identically named icons present on the desktop at the same time. This pair serves as the key used, during restoration, to find the icon matching a saved position.

Profile versions

The document describing wallpapers has evolved from a single global wallpaper format to a format that associates, with each screen, a distinct wallpaper for landscape orientation and a distinct one for portrait orientation. A profile in the older format remains readable and continues to work; it is rewritten in the newer format as soon as a wallpaper is reconfigured for one of its monitors.

Features

Screen configuration detection

DTLdesktop queries the Windows monitor enumeration API to obtain, for each screen, its position, dimensions, orientation, rotation, and primary-screen status. This reading is complemented with the identifier and wallpaper associated with each monitor; when the per-monitor wallpaper interface is unavailable, DTLdesktop falls back to Windows's global wallpaper.

Capturing and restoring desktop icons

DTLdesktop reads, directly inside the Windows Explorer process, the list view that holds the desktop icons — the name and position of each — and can then write those positions back into the same list. This reading and writing crosses the process boundary through a memory region allocated inside Explorer, because the desktop icon list belongs to that process, not to DTLdesktop.

Per-monitor wallpaper management

DTLdesktop associates two distinct wallpapers with each screen of a profile, one for landscape orientation and one for portrait orientation, and applies whichever matches the screen's actual orientation at the time of restoration. The "Fill" display mode is systematically checked and reapplied if Windows has not preserved it.

Coordinated profile application and safety

Applying a profile changes, in order, screen layout and orientation, then wallpapers, then icon positions, and then verifies that all three actually match the expected state. Before any change, the current desktop state — display modes, wallpapers, icons — is kept in memory. If verification fails at any step, DTLdesktop attempts to automatically restore that previous state rather than leaving the desktop in a non-conforming intermediate state.

Diagnostics and comparison without changes

DTLdesktop can compare the current desktop state to a saved profile — orientation or resolution discrepancies, icons that have moved, gone missing, or newly appeared, non-conforming wallpapers — without applying any change. This function is used to examine a discrepancy before deciding on a correction.

Profile recognition and automation

From the geometric signature of the current configuration, DTLdesktop determines whether it exactly matches a saved profile, whether it matches a compatible profile with different screen identifiers, or whether it is a new configuration with no associated profile. This recognition does not depend on the device names Windows assigns, and therefore remains valid after a physical swap of screens. DTLdesktop can be used interactively or non-interactively, which allows automatic restoration of the recognized profile to be integrated into a workstation or a task run at startup.

Internal reference

Internal modules

Robustness and integrity

• Any operation depending on display, wallpapers, or icons fails explicitly outside Windows.
• Applying a profile is bracketed by a capture of the previous state and a subsequent verification; a verification failure triggers an attempt to return to that previous state.
• A profile name is normalized and stripped of characters the file system disallows before any use.
• Profile files are written through a temporary file followed by an atomic replace, to avoid a partially written profile in case of interruption.
• An unavailable per-monitor wallpaper interface causes wallpaper reading and writing to fall back to the global mechanism, without interrupting the operation.

Appendices

Known limits

• DTLdesktop only works on Windows; operations depending on display, wallpapers, or icons cannot run on another platform.
• Restoring desktop icons requires access to the Windows Explorer process with a sufficient privilege level; an insufficient privilege level prevents this restoration.
• Icon identification relies on its name and its rank among icons sharing that name; renaming an icon or changing the number of identically named icons between capture and restoration can prevent it from being recognized.
• A "compatible" profile (different screen identifiers, identical geometry) is distinguished from an exact match, and is not necessarily the one that was active at the time it was captured.
• The single global-wallpaper profile format remains readable for compatibility, but is rewritten to the per-orientation format as soon as a wallpaper is reconfigured for a monitor.

Versions and schemas

Glossary