# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic sys.welcome
.title Welcome!
.toc 0 Welcome!
.default

.h1 Welcome!

.image help.png center

DVX (DOS Visual eXecutive) is a graphical user interface environment for DOS, designed for 486-class hardware and above. This help file covers the system architecture, the core libdvx API, the widget toolkit, and the platform abstraction layer.

.h2 What Is libdvx?

libdvx is the heart of DVX -- a DXE3 library that provides:

.list
.item A VESA VBE 2.0+ video backend (LFB only, no bank switching).
.item Optimised 2D drawing primitives (rectangle fill, bevels, text, bitmap blits, cursors).
.item A dirty-rectangle compositor that minimises LFB traffic.
.item A window manager with Motif-style chrome, drag/resize, menus, and scrollbars.
.item A retained-mode widget toolkit with automatic layout.
.item Modal dialog helpers, an INI preferences system, a DXE resource system, and per-app memory tracking.
.endlist

Applications written in C link against libdvx (and the widget DXEs they need) to build native DVX programs. Applications written in DVX BASIC compile to bytecode that runs on top of libdvx via the form runtime.

.h2 Target Audience

This document is aimed at developers writing native C code for DVX:

.list
.item System-level contributors maintaining libdvx itself.
.item Widget authors writing new .wgt DXE modules.
.item Application authors writing .app DXE modules.
.item Tool authors (e.g. the BASIC compiler/runtime) that sit on top of libdvx.
.endlist

All examples and signatures assume the DJGPP cross-compiler toolchain.

.h2 What's Covered

.list
.item Architecture -- Five-layer model, display pipeline, event model, build system.
.item API Reference -- Every public function, struct, enum, and constant documented with parameters and return values.
.endlist

Use the table of contents on the left to navigate. The API reference is organised by header file; each function has a one-line summary, parameter table, and (where useful) a working example.

.h2 Conventions

.list
.item Types end in a capital T (e.g. WindowT, DisplayT, BlitOpsT).
.item Enum types end in a capital E (e.g. ColorIdE, WallpaperModeE, ScrollbarOrientE).
.item Public functions use camelCase and prefixes that identify the subsystem: dvx* (application), wm* (window manager), wgt* (widget), prefs* (preferences), draw* / rect* (drawing), dirtyList* / flush* (compositor), video* / packColor / setClipRect (video), platform* (platform layer).
.item Constants use SCREAMING_SNAKE_CASE (e.g. HIT_CONTENT, MB_OK, CURSOR_ARROW).
.item Every header uses stdint.h types (int32_t, uint8_t) and stdbool.h types (bool).
.endlist

.h2 Getting Started

If you're new to DVX, read these topics in order:

.list
.item Architecture Overview -- The big picture, five-layer model, and the design philosophy.
.item Display Pipeline -- How the backbuffer, dirty list, and compositor work together.
.item Event Model -- How input becomes window/widget callbacks.
.item Widget System -- The retained-mode toolkit layered on the window manager.
.item DXE Module System -- How apps and widgets are loaded dynamically.
.endlist

Then dip into the API Reference to find specific functions. The public entry point for any application is dvxInit / dvxRun in dvxApp.h.

.h2 License

DVX is distributed under the MIT License (see the copyright notice at the top of every source file). Third-party code (stb_image, stb_ds, stb_image_write in thirdparty/) is used under its own permissive license.
