# Remote Forms Protocol

## Overview

Text-based protocol for remote GUI.  A C server on Linux sends form/control
commands over a transport layer; a Delphi 1.0 client on Windows 3.1 creates
native controls and sends user events back.

## Message Format

- One command per message.
- Transport delivers whole messages (today: newline-delimited over serial).
- Strings are double-quoted with escapes: `\"` `\\` `\n` `\r` `\t`.
- Bare tokens (IDs, numbers, type names) are whitespace-delimited.
- IDs are positive integers assigned by the server.

## Server → Client Commands

### FORM.CREATE

    FORM.CREATE <formId> <width> <height> "<title>"

Create a new form with the given dimensions and title.  The form is not
shown until FORM.SHOW is sent.

### FORM.SHOW

    FORM.SHOW <formId>

### FORM.HIDE

    FORM.HIDE <formId>

### FORM.DESTROY

    FORM.DESTROY <formId>

Free the form and all its controls.

### CTRL.CREATE

    CTRL.CREATE <formId> <ctrlId> <type> <left> <top> <width> <height> [Key="val" ...]

Create a control on the specified form.  Inline key/value properties are
applied immediately after creation.  See Control Types and Properties below.

### CTRL.SET

    CTRL.SET <formId> <ctrlId> Key="val" [Key="val" ...]

Update one or more properties on an existing control.

### EVENT.BIND

    EVENT.BIND <formId> <ctrlId> <eventName>

Wire an opt-in event handler.  Auto-wired events do not need explicit binding.

### EVENT.UNBIND

    EVENT.UNBIND <formId> <ctrlId> <eventName>

Remove an event handler.

## Client → Server Events

    EVENT <formId> <ctrlId> <eventName> [<data>]

Event data varies by event type:

| Event     | Data                          |
|-----------|-------------------------------|
| Click     | (none)                        |
| DblClick  | (none)                        |
| Change    | `"new text"`                  |
| Select    | `<index> "selected text"`     |
| KeyDown   | `<vkCode>`                    |
| KeyUp     | `<vkCode>`                    |
| MouseDown | `<x> <y> <button>`           |
| MouseUp   | `<x> <y> <button>`           |
| MouseMove | `<x> <y> <button>`           |
| Enter     | (none)                        |
| Exit      | (none)                        |
| Close     | (none)                        |

## Control Types

| Type     | Delphi Class | Auto-wired Events |
|----------|-------------|-------------------|
| Label    | TLabel      | (none)            |
| Edit     | TEdit       | Change            |
| Button   | TButton     | Click             |
| CheckBox | TCheckBox   | Click             |
| ListBox  | TListBox    | Select            |
| ComboBox | TComboBox   | Select, Change    |
| Memo     | TMemo       | Change            |

Opt-in events (require EVENT.BIND): DblClick, KeyDown, KeyUp, Enter, Exit,
MouseDown, MouseUp, MouseMove.

## Properties

| Property   | Applies To                     | Value Format                              |
|------------|-------------------------------|-------------------------------------------|
| Caption    | Label, Button, CheckBox       | Quoted string                             |
| Text       | Edit, ComboBox, Memo          | Quoted string (`\n` for line breaks)      |
| Items      | ListBox, ComboBox             | Quoted string (`\n`-delimited)            |
| Checked    | CheckBox                      | 0 or 1                                    |
| Enabled    | All                           | 0 or 1                                    |
| Visible    | All                           | 0 or 1                                    |
| MaxLength  | Edit                          | Integer                                   |
| ReadOnly   | Edit, Memo                    | 0 or 1                                    |
| ScrollBars | Memo                          | 0-3 (ssNone..ssBoth)                      |
| ItemIndex  | ListBox, ComboBox             | Integer (-1 = none)                       |
| TabOrder   | All windowed controls         | Integer                                   |

## String Encoding

- Strings in the protocol are always double-quoted.
- Escape sequences: `\"` (literal quote), `\\` (literal backslash),
  `\n` (newline), `\r` (carriage return), `\t` (tab).
- Multi-line values (Memo text, ListBox items) use `\n` within a single
  quoted string.

## Transport Layer

The protocol is transport-agnostic.  Messages are delivered via:

```
int  ReadMessage(char *buf, int maxLen);   // returns bytes read, 0 = none
void WriteMessage(const char *buf);        // sends complete message
```

Current transport: newline-delimited serial (messages terminated by CR+LF).
The transport handles framing; protocol layer never sees delimiters.