# DVX Shipped Settings and Shared Files

The settings files DVX ships and the files it shares with every program.
The build copies them into `bin/` (text files converted to DOS line
endings, CR+LF, with sed): the settings into `bin/system/`, the themes,
wallpapers, and instrument banks into `bin/shared/`.  At its first start DVX copies `DVX.INI` to
the user folder (`USER`, or the folder `DVXUSER` names), where every
change is saved; the shipped copy is never written.  File types work the
same way, except that the user's `ASSOC.INI` holds only their changes to
the shipped list.


## Files

| Source File | Build Output | Description |
|-------------|-------------|-------------|
| `dvx.ini` | `bin/system/DVX.INI` | The settings a new user starts with |
| `ASSOC.INI` | `bin/system/ASSOC.INI` | File associations: which program opens each document type (shellAssoc.h; changed on the Control Panel's File Types page, in the user's ASSOC.INI) |
| `DOSPROG.BMP` | `bin/system/DOSPROG.BMP` | The icon of a DOS program (EXE, COM, BAT) in Program Manager when it has no picture of its own (SHELL_DOS_ICON, shellProg.h) |
| `themes/cde.thm` | `bin/shared/themes/cde.thm` | CDE color theme |
| `themes/geos.thm` | `bin/shared/themes/geos.thm` | GEOS Ensemble theme |
| `themes/hotdog.thm` | `bin/shared/themes/hotdog.thm` | Hot Dog Stand theme |
| `themes/win31.thm` | `bin/shared/themes/win31.thm` | Windows 3.1 theme |
| `wpaper/blueglow.jpg` | `bin/shared/wpaper/blueglow.jpg` | Wallpaper image |
| `wpaper/swoop.jpg` | `bin/shared/wpaper/swoop.jpg` | Wallpaper image |
| `wpaper/triangle.jpg` | `bin/shared/wpaper/triangle.jpg` | Wallpaper image |
| `banks/DMXOPL.OP2` | `bin/shared/banks/DMXOPL.OP2` | DMXOPL 1.11, a General MIDI instrument bank for FM music by ConSiGno (MIT): https://github.com/sneakernets/DMXOPL, branch master, commit 63bd4821c6adaff29074f1f6486261961c2014b4 (2017-08-22, "V1.11 Release"), GENMIDI.op2 unchanged (SHA-256 d3feb807e5102d7de3075c2351cced7e853ba2da8708eff98cc1c8ef8f240ce2) |
| `banks/DMXOPL.TXT` | `bin/shared/banks/DMXOPL.TXT` | Its licence and credits |
| `banks/DMXOPL3.OP2` | `bin/shared/banks/DMXOPL3.OP2` | DMXOPL3, its OPL3 successor, by Sneakernets (MIT): the same repository, branch DMXOPL3, commit e83c144a2e6d3c283e20f9d16d011126931892f5 (2018-07-13, after the v2.11d release), GENMIDI.op2 unchanged (SHA-256 92fc03c7734c45b1ece2bfad1f79d1abbd2b27ec6b45fbfb1c5a74f5ce0138c9); DVX plays its OPL3-only waveforms as the OPL2's four, as for every bank |
| `banks/DMXOPL3.TXT` | `bin/shared/banks/DMXOPL3.TXT` | Its licence and credits ("DMXOPL3 by Sneakernets", as the author asks) |
| `keys/*.KEY` | `bin/system/KEYS/*.KEY` | DVX's repository key: packages it signs (DVX's own, and everything the package server publishes) are trusted as DVX's |

The desktop sounds (`bin/shared/sounds/`) are made by mksounds and the
fonts (`bin/shared/fonts/`) by mkfont (src/tools).


## dvx.ini Format

Standard INI format with `[section]` headers and `key = value` pairs.
Comments start with `;`. The shell loads the user's copy at startup via
`prefsLoad(platformDvxIniPath())`.

### [video] Section

| Key | Default | Description |
|-----|---------|-------------|
| `width` | 640 | Requested horizontal resolution |
| `height` | 480 | Requested vertical resolution |
| `bpp` | 16 | Preferred color depth (8, 15, 16, 24, 32) |

The system picks the closest available VESA mode. If that mode cannot
be set, or a Shift key is held while DVX starts (or `DVX /SAFE`), the
shell starts in safe video mode (640x480, 16 bpp or the closest the card
has) and asks whether to write that mode here.

### [mouse] Section

| Key | Default | Values | Description |
|-----|---------|--------|-------------|
| `wheel` | normal | normal, reversed | Scroll wheel direction |
| `wheelspeed` | 3 | 1-10 | Lines scrolled per wheel notch |
| `doubleclick` | 500 | 200-900 | Double-click speed (ms) |
| `acceleration` | medium | off, low, medium, high | Mouse acceleration |
| `speed` | 8 | 2-32 | Mickeys per 8 pixels of pointer travel (lower = faster pointer) |

### [shell] Section

| Key | Default | Description |
|-----|---------|-------------|
| `desktop` | apps/kpunch/progman/progman.app | Path to the desktop app loaded at startup |
| `welcome` | (none) | Program started after the desktop; the shipped file names the Welcome window, which deletes the key when the user ticks "Don't show this again" |

### [colors] Section

All 20 system colors as `R,G,B` triplets (0-255). Missing keys use
compiled-in defaults.

| Key | Description |
|-----|-------------|
| `desktop` | Desktop background |
| `windowFace` | Window frame and widget face |
| `windowHighlight` | Bevel highlight (top/left) |
| `windowShadow` | Bevel shadow (bottom/right) |
| `activeTitleBg` | Focused window title bar background |
| `activeTitleFg` | Focused window title bar text |
| `inactiveTitleBg` | Unfocused window title bar background |
| `inactiveTitleFg` | Unfocused window title bar text |
| `contentBg` | Content area background |
| `contentFg` | Content area text |
| `menuBg` | Menu background |
| `menuFg` | Menu text |
| `menuHighlightBg` | Menu selection background |
| `menuHighlightFg` | Menu selection text |
| `buttonFace` | Button face color |
| `scrollbarBg` | Scrollbar background |
| `scrollbarFg` | Scrollbar foreground |
| `scrollbarTrough` | Scrollbar track color |
| `cursorColor` | Mouse cursor foreground |
| `cursorOutline` | Mouse cursor outline |

### [desktop] Section

| Key | Default | Values | Description |
|-----|---------|--------|-------------|
| `wallpaper` | (none) | file path | Path to wallpaper image |
| `mode` | stretch | stretch, tile, center | Wallpaper display mode |
| `saver` | (none) | file name | Screen saver: a program in SHARED\SAVERS or the user's SAVERS |
| `saverWait` | 10 | 1-60 | Minutes with no key or mouse input before the screen saver starts |

### [network] Section

Read by the networking library (dvxnet) when the stack starts; the
Control Panel's Network page edits it.

| Key | Default | Values | Description |
|-----|---------|--------|-------------|
| `dhcp` | true | true, false | Get the address from a DHCP server |
| `address` | (none) | dotted IPv4 | Static address (dhcp = false) |
| `netmask` | (none) | dotted IPv4 | Static subnet mask (dhcp = false) |
| `gateway` | (none) | dotted IPv4 | Static default gateway (optional) |
| `dns1`, `dns2` | (none) | dotted IPv4 | Name servers; they win over the DHCP server's |
| `hostname` | DVX | text | Name sent to the DHCP server and returned by gethostname() |
| `vector` | auto | auto, 0x60-0x80 | Packet driver interrupt |

### [printer] Section

Read by the printing library (print.lib) for every print; the Control
Panel's Printer page edits the port and model, File > Page Setup (and
the Printer page's Page Setup button) the rest.  A page setup that
cannot work (margins leaving no room, values out of range) is ignored
as a whole in favour of the defaults.

| Key | Default | Values | Description |
|-----|---------|--------|-------------|
| `port` | LPT1 | LPT1, LPT2, LPT3, COM1, COM2, COM3, COM4, FILE | Where printed output goes |
| `baud` | 9600 | 300, 1200, 2400, 4800, 9600, 19200, 38400 | A serial printer's speed (port COM1-COM4) |
| `handshake` | dtrdsr | none, xonxoff, rtscts, dtrdsr | How a serial printer holds the computer back: XON / XOFF characters, or its ready line on the computer's CTS or DSR (Apple's ImageWriter cable) |
| `file` | PRINTER.PRN | file path | The file used with port = FILE |
| `model` | text | text, epson9, epson24, laserjet, laserjet300, epson9color, epson24color, deskjet500c, deskjetcolor, postscript, postscriptcolor, imagewriter, imagewritercolor | Printer model; all but text print pictures; epson9color, epson24color, deskjet500c, deskjetcolor, postscriptcolor, and imagewritercolor in color |
| `linesPerPage` | 0 | 0, 10-200 | Lines per page; 0 = the model's usual length (66, laser 60) |
| `columns` | 80 | 20-255 | Characters across the page |
| `marginTop`, `marginBottom` | 3 | lines | Top and bottom margins (header / footer in their middle line) |
| `marginLeft`, `marginRight` | 5 | characters | Left and right margins |
| `tabWidth` | 8 | 1-16 | Tab stops for printed text |
| `wrap` | true | true, false | Wrap long lines at a word, or cut them off |
| `header`, `footer` | &f, Page &p | text | &f file name, &p page, &n pages, &d date, &t time, &l &c &r left / centre / right, && an ampersand |


## Theme Files (.thm)

Theme files use the same INI format as dvx.ini but contain only a
`[colors]` section with the 20 color keys. The Control Panel can
load and save themes via `dvxLoadTheme()` / `dvxSaveTheme()`.

Bundled themes:

| File | Description |
|------|-------------|
| `cde.thm` | CDE (Common Desktop Environment) -- warm tan/blue palette |
| `geos.thm` | GEOS Ensemble -- cyan/grey palette |
| `hotdog.thm` | Hot Dog Stand -- the infamous yellow/red/black palette |
| `win31.thm` | Windows 3.1 -- grey/navy palette |


## Dependency Files (.dep)

Plain text files listing module base names that must be loaded before
this module. One name per line. Empty lines and `#` comments are
ignored. Names are case-insensitive.

### Library Dependencies

| Dep File | Module | Dependencies |
|----------|--------|--------------|
| `libdvx.dep` | libdvx.lib | libtasks |
| `texthelp.dep` | texthelp.lib | libtasks, libdvx |
| `listhelp.dep` | listhelp.lib | libtasks, libdvx |
| `dvxshell.dep` | dvxshell.lib | libtasks, libdvx, texthelp, listhelp |
| `basrt.dep` | basrt.lib | libtasks, libdvx |
| `serial.dep` | serial.lib | libtasks, libdvx |
| `crypto.dep` | crypto.lib | libdvx |
| `seclink.dep` | seclink.lib | crypto, serial, libdvx |

### Widget Dependencies

| Dep File | Widget | Dependencies |
|----------|--------|--------------|
| `textinpt.dep` | textinpt.wgt | texthelp |
| `combobox.dep` | combobox.wgt | texthelp, listhelp |
| `spinner.dep` | spinner.wgt | texthelp |
| `ansiterm.dep` | ansiterm.wgt | texthelp |
| `dropdown.dep` | dropdown.wgt | listhelp |
| `listbox.dep` | listbox.wgt | listhelp |
| `listview.dep` | listview.wgt | listhelp |
| `treeview.dep` | treeview.wgt | listhelp |


## Wallpaper Images

| File | Description |
|------|-------------|
| `wpaper/blueglow.jpg` | Blue gradient glow |
| `wpaper/swoop.jpg` | Curved swoosh pattern |
| `wpaper/triangle.jpg` | Geometric triangle pattern |

Wallpapers support BMP, PNG, JPEG, and GIF formats. They are
pre-rendered to screen dimensions in native pixel format at load time.

## The Repository Key

DVX trusts as its own the packages signed by the keys in `SYSTEM\KEYS`,
and refuses an update of DVX itself (`kpunch.dvx`) signed by any other.
The key pair is made once, on a computer the package server never
touches:

    bin/host/dvxpkg keygen "DVX Repository" KPUNCH

`KPUNCH.KEY` (the public half) goes in `config/keys/`, so every build
ships it.  `KPUNCH.SEC` stays offline, with the operator who approves
packages (server/README.md); `config/keys/.gitignore` keeps a stray copy
of it out of the repository.