# 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 intro
.title Welcome to DVX
.toc 0 Welcome to DVX
.default
.index DVX
.index Introduction
.index Getting Started

.h1 Welcome to DVX

DVX is a graphical user interface environment for DOS, designed
for 486-class hardware and above. It provides a windowing system
with a Motif-inspired visual style, cooperative multitasking,
and a widget-based application framework.

DVX features include:

.list
.item A window manager with drag, resize, and minimize support
.item Over 25 built-in widget types including buttons, lists, and trees
.item Dynamic application loading at runtime
.item Theme support with customizable color schemes
.item VESA VBE 2.0+ linear framebuffer rendering
.endlist

.link overview See also: System Overview

.hr

.note tip
Press F1 from any DVX application to open context-sensitive help.
.endnote

.topic overview
.title System Overview
.toc 0 System Overview
.index Architecture
.index Layers

.h1 System Overview

DVX is built as a five-layer architecture, with each layer
providing services to the layer above it.

.h2 Video Layer

The video layer (dvxVideo) handles VESA VBE initialization,
linear framebuffer mapping, backbuffer allocation, and pixel
format detection. It supports 8-bit, 16-bit, and 32-bit color
depths.

.h2 Drawing Layer

The drawing layer (dvxDraw) provides primitive rendering
operations: filled rectangles, beveled borders, text rendering,
bitmap blitting, and clipped drawing.

.h2 Compositor

The compositor (dvxComp) manages a dirty rectangle list. Only
regions that have changed since the last frame are flushed from
the system RAM backbuffer to the video card's linear framebuffer.

.h2 Window Manager

The window manager (dvxWm) handles the window stack, chrome
rendering (title bars, borders, close buttons), drag and resize
interaction, focus management, and menu bars.

.h2 Application Layer

The application layer (dvxApp) ties everything together with
the event loop, mouse and keyboard input, accelerator tables,
and the public API used by applications.

.link widgets See also: Widget System

.topic widgets
.title Widget System
.toc 0 Widget System
.index Widgets
.index Controls

.h1 Widget System

DVX provides a rich set of widgets (controls) for building
application user interfaces. Widgets are loaded as plugin
modules at startup.

.h2 Layout Widgets

.list
.item VBox -- Vertical box layout (stacks children vertically)
.item HBox -- Horizontal box layout (stacks children horizontally)
.item Frame -- Labeled group box with border
.item ScrollPane -- Scrollable container for oversized content
.item Splitter -- Resizable split between two panes
.item TabControl -- Tabbed container
.endlist

.h2 Input Widgets

.list
.item Button -- Push button with text label
.item TextInput -- Single-line text entry field
.item TextArea -- Multi-line text editor with syntax highlighting
.item Checkbox -- Boolean toggle with label
.item Radio -- Mutually exclusive option selector
.item Dropdown -- Drop-down selection list
.item ComboBox -- Editable dropdown with text entry
.item Slider -- Horizontal or vertical value slider
.item Spinner -- Numeric up/down control
.endlist

.h2 Display Widgets

.list
.item Label -- Single-line text display
.item Image -- Bitmap image display
.item ProgressBar -- Visual progress indicator
.item Canvas -- Custom drawing surface
.item Separator -- Horizontal or vertical divider line
.endlist

.h2 Data Widgets

.list
.item ListBox -- Scrollable list of text items
.item ListView -- Multi-column sortable list with headers
.item TreeView -- Hierarchical tree with expand/collapse
.endlist

.topic keyboard
.title Keyboard Shortcuts
.toc 0 Keyboard Shortcuts
.index Keyboard
.index Shortcuts
.index Hotkeys

.h1 Keyboard Shortcuts

The following keyboard shortcuts are available system-wide
in DVX:

.table
  Shortcut        Action
  --------        ------
  Alt+F4          Close active window
  F10             Activate menu bar
  Ctrl+Esc        Open task manager
  Tab             Move focus to next widget
  Shift+Tab       Move focus to previous widget
  Enter           Activate focused button
  Escape          Close dialog or cancel operation
.endtable
