Desktop Embedded Mode

Kitto^x applications normally run as a standalone HTTP server and are accessed through a web browser. The Desktop Embedded Mode allows you to wrap the same application inside a native Windows desktop window, using Microsoft Edge WebView2 (TEdgeBrowser). The result looks and behaves like a traditional desktop application — no address bar, no tabs, no bookmarks.

How it works

1. The application starts an in-process HTTP server on localhost (same engine as the standard Kitto^x server)
2. A VCL form with a TEdgeBrowser navigates to http://localhost:<port>/
3. The user interacts with the application as if it were a native desktop app
4. The window title is automatically updated from the HTML <title> element

Requirements

• Delphi 10.4+ with Vcl.Edge unit
• WebView2 Runtime — preinstalled on Windows 10 (21H2+) and Windows 11. For older Windows 10 versions, distribute the Evergreen Bootstrapper (~2 MB)

Quick start

Create a new Delphi project (.dpr) that uses Kitto.Vcl.Embedded instead of Kitto.Vcl.Start:

program MyAppDesktop;

uses
  Kitto.Vcl.Embedded,
  Controllers in '..\..\Source\Controllers.pas',
  Rules in '..\..\Source\Rules.pas',
  UseKitto in '..\..\Source\UseKitto.pas';

{$R *.res}

begin
  TKEmbeddedStart.Start;
end.

That's it. The application will look for a ConfigDesktop.yaml file in the Metadata folder. If not found, it falls back to the standard Config.yaml.

Configuration

Config file resolution

TKEmbeddedStart.Start accepts an optional config file name parameter:

// Explicit config file
TKEmbeddedStart.Start('MyCustomConfig.yaml');

// Default resolution (no parameter):
// 1. Command-line switch: -c MyConfig.yaml
// 2. ConfigDesktop.yaml (if it exists in Metadata/)
// 3. Standard TKConfig resolution (Config_AppName.yaml → Config.yaml)
TKEmbeddedStart.Start;

Desktop node

The Desktop node in Config.yaml controls the window properties:

Desktop:
  ClientWidth: 1000        # Window client width in pixels (default: 1000)
  ClientHeight: 900        # Window client height in pixels (default: 900)
  Maximized: False         # Start maximized (default: False)
  Resizable: True          # Allow window resizing (default: True)
  BorderIcons:
    biSystemMenu: True     # Show system menu (default: True)
    biMinimize: True       # Show minimize button (default: True)
    biMaximize: True       # Show maximize button (default: True)
    biHelp: False          # Show help button (default: False)
  Position: poScreenCenter # Window position (default: poScreenCenter)

The Position property accepts any valid Delphi TPosition value as a string: poDesigned, poDefault, poDefaultPosOnly, poDefaultSizeOnly, poScreenCenter, poDesktopCenter, poMainFormCenter, poOwnerFormCenter.

Server binding

To avoid the Windows Firewall prompt when the application starts, bind the server to 127.0.0.1 (loopback only):

Server:
  Port: 3621
  BindAddress: 127.0.0.1

This is recommended for desktop mode since the application is only accessed locally. When BindAddress is not specified, the server listens on all interfaces (0.0.0.0), which is the correct behavior for web server mode.

Example

The HelloKitto example includes a desktop variant:

• Project: Examples/HelloKitto/Projects/D13/HelloKittoDesktop.dpr
• Config: Examples/HelloKitto/Home/Metadata/ConfigDesktop.yaml

Comparison with browser mode

	Browser mode	Desktop embedded mode
Entry point	TKStart.Start	TKEmbeddedStart.Start
Unit	Kitto.Vcl.Start	Kitto.Vcl.Embedded
UI	External browser	TEdgeBrowser in VCL form
Config	Config.yaml	ConfigDesktop.yaml (fallback to Config.yaml)
Server binding	0.0.0.0 (all interfaces)	127.0.0.1 (recommended)
Distribution	EXE + browser	Single EXE (WebView2 Runtime required)
Multiple users	Yes	Single user (local)
Window control	Browser-managed	Desktop node in config