About This Reference
This book describes the programming interface of DVX in C: how the system is built, every header and function of the core library, the shell that loads programs and runs their tasks, every widget, and every library the DVX SDK has headers for. It is a book to look things up in, not to read from front to back.
To learn to write programs, widgets, and libraries for DVX, start with its companion, the the DVX C Programming Guide. It assumes you know C and walks through the SDK, the way DVX programs work, and each part of the system with programs you build and run, and it points into this book for the details.
How This Book Is Organized
-
Chapter 1 explains how DVX is put together: its layers, the display pipeline, windows, widgets, dialogs, resources, and the other subsystems.
-
Chapter 2 describes the core library, libdvx, header by header: types, drawing, fonts and text, windows, menus, widgets, dialogs, resources, preferences, and the platform layer.
-
Chapter 3 describes the shell, which loads programs, widgets, and libraries and runs them, the cooperative tasks programs run in, and the Task Manager.
-
Chapter 4 has a section for each widget, in alphabetical order, with its C API.
-
The chapters after it describe the SDK’s libraries, grouped by what they do: Chapter 5, Chapter 6, Chapter 7, Chapter 8, Chapter 9, and Chapter 10.
-
Chapter 11 describes the libraries that run and build DVX BASIC programs, for C programs that compile, run, or debug BASIC.
DVX’s own help has the same text, under Technical Reference (for Developers): open it from Program Manager’s Help menu.
To find something by its name, use the index at the back.
Chapter 1. System Architecture
1.1. DVX Architecture Overview
DVX (DOS Visual eXecutive) is a complete windowing GUI compositor targeting DJGPP/DPMI on DOS. It provides overlapping windows with Motif-style chrome, a retained-mode widget toolkit, cooperative multitasking of DXE-loaded applications, and a dirty-rectangle compositor optimized for 486/Pentium hardware.
1.1.1. Key Design Constraints
-
VESA VBE video: the linear framebuffer whenever the card offers one; otherwise (VBE 1.x, or a DPMI host that will not map it) the platform flush writes through the 64 KB bank window. Drawing always targets the system RAM backbuffer, so nothing above the flush knows the difference. Initialization fails only without VBE or a usable mode.
-
486 baseline — all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant.
-
Single-tasking cooperative model — applications yield the CPU via tsYield(); there is no preemptive scheduler.
-
A single emulator is the trusted reference platform for testing; any bugs observed there are treated as DVX bugs.
-
The system font (8x16) and the mouse cursors are compiled in as static const data, so DVX can always draw; every other font is a .DFN file loaded from the font folders (SHARED\FONTS and the user’s FONTS) when a program opens it.
The runtime environment consists of a bootstrap loader (dvx.exe) that loads core DXE libraries, widget plugins, and the shell, which in turn loads and manages DXE application modules.
1.1.2. Contents
See also: Display Pipeline (Section 1.3); Window System (Section 1.4); Widget System (Section 1.5); Modal Dialogs (Section 1.6); Resource System (Section 1.7); Preferences System (Section 1.8); DVX Folders (Section 1.9); Per-App Memory Tracking (Section 1.10); DXE Module System (Section 1.11); Event Model (Section 1.12); Font System (Section 1.13); Color System (Section 1.14); Platform Layer (Section 1.15); Build System (Section 1.16).
1.2. Five-Layer Architecture
DVX is organized into five layers, each implemented as a single .h/.c pair. Every header includes dvxTypes.h (the shared type definitions) to avoid circular dependencies. The layers are strictly stacked: each layer depends only on the layers below it.
Applications (DXE .app modules) ================================================== | | | +------------------------------------------+ | | | Layer 5: dvxApp (Application API) | | dvxApp.h / dvxApp.c | | Event loop, window creation, public API | | | +------------------------------------------+ | | | Layer 4: dvxWm (Window Manager) | | dvxWm.h / dvxWm.c | | Window stack, chrome, drag, resize | | | +------------------------------------------+ | | | Layer 3: dvxComp (Compositor) | | dvxComp.h / dvxComp.c | | Dirty rect tracking, merge, LFB flush | | | +------------------------------------------+ | | | Layer 2: dvxDraw (Drawing Primitives) | | dvxDraw.h / dvxDraw.c | | Rects, bevels, text, blits, cursors | | | +------------------------------------------+ | | | Layer 1: dvxVideo (Video Backend) | | dvxVideo.h / dvxVideo.c | | VESA VBE, LFB mapping, pixel format | | | +------------------------------------------+ | | | | +------------------------------------------+ | | | Platform Layer (dvxPlat.h) | | dvxPlatformDos.c | | OS-specific: video, input, asm spans | | | +------------------------------------------+ | | | | +------------------------------------------+ | | | Shared Types (dvxTypes.h) | | | | DisplayT, WindowT, RectT, ColorSchemeT | | | +------------------------------------------+ | ==================================================
1.2.1. Layer Summary
| Layer | Header | Responsibility |
|---|---|---|
1 - Video |
dvxVideo.h |
VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle. |
2 - Draw |
dvxDraw.h |
All 2D drawing: rectFill, rectCopy, drawBevel, drawText/drawTextN, drawMaskedBitmap (cursor), drawTermRow (batch terminal row). Stateless beyond clip rect. Dispatches hot inner loops through BlitOpsT function pointers. |
3 - Compositor |
dvxComp.h |
Dirty rectangle tracking (dirtyListAdd), pairwise merge of overlapping rects (dirtyListMerge), and flushRect to copy dirty regions from backBuf to LFB. |
4 - Window Manager |
dvxWm.h |
Window lifecycle, Z-order stack, chrome drawing (title bars, bevels, close/minimize/maximize gadgets), hit testing, drag/resize, menu bars, scrollbars, system menu, keyboard move/resize, minimized icon bar. |
5 - Application |
dvxApp.h |
Public API aggregating all layers into AppContextT. Provides dvxInit/dvxShutdown, dvxRun/dvxUpdate, window creation helpers, image loading, clipboard, accelerator tables, theme management, wallpaper, video mode switching, screenshot capture. |
1.3. Display Pipeline
The double-buffer strategy is the single most important performance decision in DVX. All drawing goes to a system RAM backbuffer (DisplayT.backBuf); only dirty rectangles are flushed to video memory (platformFlushRect), which only the platform layer reaches: on DOS through a selector over the linear framebuffer or the VGA window, so DS keeps its normal limit and a wild pointer faults instead of writing to the screen, DOS’s memory, or the interrupt vectors.
This matters because writes to video memory over the PCI bus are 10-50x slower than writes to main RAM on 486/Pentium hardware for random-access patterns.
1.3.1. Per-Frame Compositing Pipeline
1. Input poll (mouse, keyboard)
|
2. Event dispatch (focus window callbacks)
|
3. Layers call dirtyListAdd() for changed regions
|
4. dirtyListMerge() consolidates overlapping rects
|
5. For each merged dirty rect:
a. Clip and redraw desktop background (or wallpaper)
b. For each window (back-to-front, painter's algorithm):
- wmDrawChrome() -- frame, title bar, gadgets, menu bar
- wmDrawContent() -- blit per-window content buffer
- wmDrawScrollbars()
c. Draw minimized window icons
d. Draw popup menus / tooltips (overlay pass)
e. Draw software mouse cursor
|
6. flushRect() -- copy each dirty rect from backBuf to LFB
|
7. Yield (platformYield)
1.3.2. Key Data Structures
DisplayT — Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer — no globals.
BlitOpsT — Vtable of span fill/copy function pointers resolved at init time for the active pixel depth. On DOS these dispatch to hand-written rep stosl / rep movsd asm inner loops.
DirtyListT — Fixed-capacity dynamic array of RectT. Linear scanning for merge candidates is cache-friendly at typical sizes (under 128 rects). If the list fills up, the compositor merges aggressively or falls back to full-screen repaint.
1.3.3. Why This Works on a 486
-
A full 640x480x32bpp frame is 1.2 MB — far too much to flush every frame over a slow PCI bus.
-
A typical dirty region during normal interaction (typing, menu open) is a few KB.
-
Merging overlapping dirty rects into larger rects reduces per-rect overhead and improves bus utilization.
-
Per-window content buffers persist across frames, so windows don’t repaint on expose — only when their own content changes.
1.4. Window System
1.4.1. WindowT Structure
| Field Group | Purpose |
|---|---|
Geometry (x, y, w, h) |
Outer frame rectangle (including chrome). |
Content area (contentX/Y/W/H) |
Computed from frame minus chrome. Where application content lives. |
Content buffer (contentBuf, contentPitch) |
Per-window backbuffer in native pixel format. Persists across frames. |
Chrome state (menuBar, vScroll, hScroll) |
Optional menu bar and scrollbars. Affect content area computation. |
Widget tree (widgetRoot) |
Root of the retained-mode widget tree (NULL if using raw callbacks). |
Callbacks |
onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onMenuOpen, onScroll, onCursorQuery, onFocus, onBlur, onRawKey (game input windows). |
1.4.2. Window Stack (Z-Order)
WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:
-
Back-to-front iteration for painting (painter’s algorithm).
-
Front-to-back iteration for hit testing (first hit wins).
-
Reordering by pointer swap (no copying of large WindowT structs).
Only one drag/resize/scroll operation can be active system-wide at a time (single mouse), so that state lives on the stack, not on individual windows.
1.4.3. Chrome Layout
+-------------------------------------------+ | 4px outer border (raised bevel) | | +-------------------------------------+ | | | [X] Title Bar Text [_] [^] [X] | | 20px title height | +-------------------------------------+ | | | 2px inner border | | | +-------------------------------------+ | | | Menu Bar (optional, 20px) | | | +-------------------------------------+ | | | | | | | Content Area | | | | | | | | | S | | S = vertical scrollbar | | | B | | (16px wide) | +-------------------------------------+ | | | Horizontal Scrollbar (optional) | | 16px tall | +-------------------------------------+ | | 4px outer border | +-------------------------------------------+
Chrome constants are compile-time defines:
CHROME_BORDER_WIDTH = 4px CHROME_TITLE_HEIGHT = 20px CHROME_INNER_BORDER = 2px CHROME_MENU_HEIGHT = 20px SCROLLBAR_WIDTH = 16px
1.4.4. Hit Test Regions
wmHitTest() iterates the stack front-to-back and returns a hit-part identifier: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE. Resize edge detection returns a bitmask of RESIZE_LEFT, RESIZE_RIGHT, RESIZE_TOP, RESIZE_BOTTOM (corners combine two edges).
1.4.5. Menu System
Menus use fixed-size inline char buffers for labels (MAX_MENU_LABEL = 32 with the NUL, no heap strings; a longer label is cut). Both menus per bar and items per menu are stored in dynamic arrays that grow on demand, with no count limit. Supports cascading submenus via MenuItemT.subMenu pointer; a submenu belongs to its item and is freed with it (wmRemoveMenuItem, wmClearMenuItems) or with the menu that holds it. Item types: normal, checkbox, radio. Separators are non-interactive items. The popup state (PopupStateT) tracks a stack of parent frames for cascading submenu nesting.
1.5. Widget System
The widget system (dvxWgt.h) is a retained-mode toolkit layered on top of the window manager. Widgets form a tree rooted at a per-window VBox container.
1.5.1. WidgetT Base Structure
Every widget shares the same WidgetT struct. The type field is a runtime-assigned integer ID. The wclass pointer references the widget’s WidgetClassT vtable. Widget-specific private data is stored in w->data (opaque void*).
Tree linkage: parent, firstChild, lastChild, nextSibling. No prevSibling — this halves pointer overhead and removal is still O(n) for typical tree depths of 5-10.
1.5.2. Layout Engine
Two-pass flexbox-like algorithm:
-
Bottom-up (calcMinSize) — compute minimum sizes for every widget, starting from leaves.
-
Top-down (layout) — allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).
Size hints use a tagged encoding: the top 2 bits of an int32_t select the unit (pixels, character widths, or percentage of parent), the low 30 bits hold the value. Macros: wgtPixels(v), wgtChars(v), wgtPercent(v). A percentage in minW, minH, maxW, or maxH is of the inside of the parent container (its width or height), in padding or spacing of the container’s own width. The bottom-up pass knows no size yet, so a percentage counts as 0 there: it never raises a measured minimum, a window’s fit, or its scroll bars, and nothing can feed back. The top-down pass resolves each percentage against the size its container has just been given (nested ones compose, a resize resolves them again), out of the room beyond what was measured: padding, then spacing, then the children’s minimums, which shrink in proportion when they want more room than there is, so a percentage never squeezes a widget below its minimum. After that a percentage minimum acts as a pixel one (weights share out the rest; a maximum wins). The rules are written down at the top of widgetLayout.c.
A backdrop (wgtSetBackdrop) stays out of both passes: it adds nothing to its parent’s minimum, and the layout gives it the parent’s whole box. It paints before its siblings, which paint over it, and the mouse passes through it to the parent.
wgtInvalidate measures and lays out the whole window at once (its scroll bars too). A window’s tree that has grown since it was last measured (widgets added and no wgtInvalidate, fit, or resize since) is measured by its next full paint, so a program that builds its widgets and lets the window paint gets a laid-out window.
1.5.3. Widget Class Dispatch (WidgetClassT)
Each widget type provides a WidgetClassT with a handlers[] array indexed by stable method IDs. Method IDs are never reordered or reused — new methods append at the end. A change to the slots that would break a compiled widget bumps DVX_ABI_VERSION instead, and the loader then refuses widgets built for the old number (see Binary Interface Version).
Methods include: PAINT, PAINT_OVERLAY, CALC_MIN_SIZE, LAYOUT, ON_MOUSE, ON_KEY, ON_ACCEL_ACTIVATE, DESTROY, GET_TEXT, SET_TEXT, POLL, ON_BLUR, ON_WHEEL, ON_MOUSE_EVENT, ON_KEY_UP, ON_FOCUS, GET_FACE, ON_FORMAT_CHANGE, HIT_CHROME, MIN_PERCENT, and more (30 defined, IDs 0-29, room for 32). MIN_PERCENT gives a class’s own minimum as a percentage of its container (a BASIC UserControl’s natural size in percent), which the layout treats as it treats a percentage minW or minH. HIT_CHROME says which points are a control’s chrome (its scroll bars and the corner between them, a list’s column headers): a press of any button there fires no click or mouse events, as in Visual Basic. ON_FORMAT_CHANGE is how a widget that keeps pixels or packed colors in the display format converts them when dvxChangeVideoMode changes the color depth (convertPixels, dvxVideo.h): Canvas, Image, and ImageButton convert their pictures, the Terminal packs its 16 colors again, and Program Manager’s icon view decodes its icons again; DVX converts window icons itself. A widget class whose version is not WGT_CLASS_VERSION is rejected by wgtRegisterClass.
Class Flags
| Flag | Meaning |
|---|---|
WCLASS_FOCUSABLE |
Can receive keyboard focus (Tab navigation) |
WCLASS_HORIZ_CONTAINER |
Lays out children horizontally (HBox) |
WCLASS_PAINTS_CHILDREN |
Widget handles child rendering itself |
WCLASS_NO_HIT_RECURSE |
Mouse hit testing stops at the widget (it handles its children’s clicks) |
WCLASS_FOCUS_FORWARD |
An accelerator on it moves the focus to the next focusable widget (a Label) |
WCLASS_HAS_POPUP |
Has a drop-down popup overlay |
WCLASS_SCROLLABLE |
Mouse wheel sends Up/Down arrow keys |
WCLASS_SCROLL_CONTAINER |
ScrollPane — scrolling viewport |
WCLASS_NEEDS_POLL |
Needs periodic polling (e.g. AnsiTerm comms) |
WCLASS_SWALLOWS_TAB |
Tab key goes to widget, not focus navigation |
WCLASS_RELAYOUT_ON_SCROLL |
The whole window is laid out again while its scroll bar is dragged |
WCLASS_PRESS_RELEASE |
Click = press + release (buttons) |
WCLASS_ACCEL_WHEN_HIDDEN |
Its accelerator works while it is hidden |
WCLASS_HAS_TEXT |
Its data starts with its own text (strdup’d, freed with it) |
WCLASS_RAISES_EVENTS |
The class fires the mouse, click, key, and scroll callbacks itself (a BASIC UserControl) |
WCLASS_FIXED_FONT |
Edits text by columns: a proportional font draws as the system font |
WCLASS_SWALLOWS_ENTER |
Enter goes to widget, not a dialog’s default button |
WCLASS_CLICK_ON_PICK |
Click = the user’s pick of an item, by mouse or keys (lists) |
WCLASS_ONE_LINE |
One line high: grows along a row, keeps its height in a column |
1.5.4. Available Widget Types
Each widget is a separate .wgt DXE module (a module may register more than one type: Box has VBox, HBox, and Frame). 32 widget modules are included:
| Widget | Description |
|---|---|
Box (VBox/HBox) |
Vertical and horizontal layout containers |
Button |
Clickable push button with label |
Canvas |
Raw drawing surface for custom painting |
Checkbox |
Boolean toggle with checkmark |
ComboBox |
Text input with dropdown list |
DataCtrl |
Data-bound control for database operations |
DbGrid |
Database grid (tabular data display) |
Dropdown |
Dropdown selection list |
HelpView |
Help viewer pane (topics, links, pictures) |
Image |
Static image display |
ImageButton |
Button with bitmap icon |
Label |
Static text label |
ListBox |
Scrollable selection list |
ListView |
Multi-column list with headers and sorting |
ProgressBar |
Determinate progress indicator |
Radio |
Radio button (mutual exclusion group) |
RichEdit |
Styled text editor (fonts, colors, paragraphs) |
RichLabel |
Styled text display |
ScrollPane |
Scrollable viewport container |
Separator |
Visual divider line |
Slider |
Value selection via draggable thumb |
Spacer |
Empty space for layout |
Spinner |
Numeric input with up/down arrows |
Splitter |
Resizable split pane |
StatusBar |
Window status bar with sections |
TabControl |
Tabbed page container |
Terminal (AnsiTerm) |
ANSI terminal emulator widget |
TextInput |
Single-line text entry field |
Timer |
Periodic timer events |
Toolbar |
Toolbar with icon buttons |
TreeView |
Hierarchical tree display |
WrapBox |
Flow layout (wrapping horizontal container) |
1.5.5. Widget API Registry
Each widget DXE registers a small API struct under a name during wgtRegister(). A name is registered once: a second API or interface under a name already taken is refused (logged) and the first stays. Callers retrieve it via wgtGetApi("button", sizeof(ButtonApiT)) and cast to the widget-specific API type. Every API struct starts with a WgtApiHeaderT (the provider’s DVX_ABI_VERSION and struct size), so wgtGetApi refuses a table built for another ABI or shorter than the caller expects. Per-widget headers provide typed accessors so callers avoid manual casts. Adding a new widget requires zero changes to the core.
1.5.6. Widget Interface Descriptors (WgtIfaceT)
Each widget can register an interface descriptor that describes its BASIC-facing properties, methods, and events. These descriptors are used by the form runtime and IDE for generic dispatch and property panel enumeration. Properties have typed getters/setters (WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_ENUM).
1.6. Modal Dialogs (dvxDlg.h)
Pre-built modal dialog boxes block the caller and run their own event loop via dvxUpdate() until the user dismisses them. Each dialog makes itself the modal window (dvxModalBegin) to prevent input from reaching other windows while open; modal windows stack, so the one before it is modal again when it closes or is taken away (dvxModalEnd).
1.6.1. Dialog Types
| Function | Purpose |
|---|---|
dvxMessageBox |
Generic message box with button/icon flags (MB_OK, MB_YESNO, MB_ICONERROR, etc.) |
dvxButtonBox |
Message box with the caller’s own buttons (up to DVX_BUTTON_BOX_MAX); returns the index chosen |
dvxErrorBox |
Shortcut for MB_OK + MB_ICONERROR |
dvxInfoBox |
Shortcut for MB_OK + MB_ICONINFO |
dvxFileDialog |
File open/save dialog (or, with FD_FOLDER, a folder chooser) with directory navigation, a drive dropdown, and a filter dropdown |
dvxInputBox |
Single-line text input with OK/Cancel |
dvxIntInputBox |
Integer input with spinner, clamp range, and step |
dvxChoiceDialog |
List selection with OK/Cancel |
dvxColorDialog |
Color picker: basic colors, Red/Green/Blue sliders and number boxes, a preview |
dvxFontDialog |
Font picker: family, style, size, underline and strikeout, a sample |
dvxPromptSave |
Canonical "Save changes?" Yes/No/Cancel dialog |
The custom dialog kit builds any other dialog from widgets with the same behavior (modal, Enter for OK, Escape and closing for Cancel, ended cleanly with its program): dvxDialogCreate makes the empty dialog, dvxDialogAddField adds labeled text boxes, dvxDialogAddOkCancel the OK and Cancel buttons with an onOk check, dvxDialogEnd ends it from the program’s own callbacks, and dvxDialogRun sizes, runs, and destroys it.
1.6.2. Flag Encoding
dvxMessageBox flags split into two nibbles: button configuration (low) and icon type (high). This matches the Win16 MessageBox() convention so OR’d flags read naturally:
dvxMessageBox(ctx, "Confirm", "Delete file?", MB_YESNO | MB_ICONQUESTION);
Return values are ID_OK / ID_CANCEL / ID_YES / ID_NO / ID_RETRY; closing a box instead of answering it returns ID_CANCEL, whatever its buttons.
1.7. Resource System (dvxRes.h)
Resources are appended to DXE3 files (.app, .wgt, .lib) after the normal DXE content. The DXE loader never reads past the DXE header, so the appended data is invisible to dlopen. Every DXE can carry its own icons, text strings, and binary data without separate resource files.
1.7.1. On-Disk Layout
[DXE3 content] -- untouched, loaded by dlopen [resource data entries] -- sequential, variable length [resource directory] -- fixed-size entries (48 bytes each) [footer] -- magic + directory offset + count (16 bytes)
Readers start from the end: seek to EOF - sizeof(footer), verify the magic (DVX_RES_MAGIC = "DVXR"), then seek to the directory. Entries are sorted at open time so lookups are O(log n) via bsearch.
1.7.2. Types
| Type ID | Value | Payload |
|---|---|---|
DVX_RES_ICON |
1 |
A picture: BMP, PNG, JPEG, or GIF (icons included: icon32, icon24) |
DVX_RES_TEXT |
2 |
Null-terminated string (localizable UI text, author, copyright) |
DVX_RES_BINARY |
3 |
Arbitrary data (app-specific) |
DVX_RES_FONT |
4 |
A .DFN font the program carries (the shell adds it for the program when it loads it) |
1.7.3. Runtime API
| Function | Description |
|---|---|
dvxResOpen |
Open a handle by reading the footer and directory |
dvxResRead |
Look up a resource by name and read its data into a malloc’d buffer |
dvxResFind |
Look up a resource’s directory entry (no data copy) |
dvxResClose |
Release the handle |
dvxResAppend |
Append a new resource to a DXE file |
dvxResRemove |
Remove a resource by name |
The dvxApp.h wrappers (dvxResLoadIcon, dvxResLoadText, dvxResLoadData) combine open + read + close for the common case.
1.8. Preferences System (dvxPrefs.h)
Handle-based API over classic INI files. Multiple files can be open at once. Each prefsLoad / prefsCreate returns a PrefsHandleT opaque pointer passed to subsequent calls and freed with prefsClose. The system INI is DVX.INI in the user folder: prefsLoad(platformDvxIniPath()).
1.8.1. Usage Pattern
PrefsHandleT *h = prefsLoad(platformDvxIniPath());
int32_t w = prefsGetInt(h, "video", "width", 640);
bool sound = prefsGetBool(h, "audio", "enable", true);
const char *bg = prefsGetString(h, "desktop", "wallpaper", "");
prefsSetInt(h, "video", "width", 800);
prefsSave(h);
prefsClose(h);
Boolean getters recognize "true"/"yes"/"1" and "false"/"no"/"0" (case-insensitive). If the file does not exist, prefsLoad still returns a valid empty handle with the path captured so prefsSave can write a new file.
1.9. DVX Folders (dvxPlat.h)
Files are kept apart by who writes them. The DVX folder holds the program: Setup installs it, an upgrade replaces all of it, and DVX only reads it. Everything written while DVX runs goes in the user folder, the one folder to back up.
C:\DVX\
DVX.COM DVX.EXE SETUP.EXE SETUP.LST (DVX.COM starts DVX.EXE)
SYSTEM\ tools, and the shipped DVX.INI and ASSOC.INI
KEYS\ PACKAGES\ the keys DVX trusts, what is installed (DVX's own)
LIBS\ WIDGETS\
APPS\<vendor>\<program>\ a program, its help, and DATA\ (files it ships)
SHARED\ shipped for every program
FONTS\ SOUNDS\ THEMES\ WPAPER\ BANKS\ SAVERS\
USER\ the user folder
DVX.INI ASSOC.INI DVX.LOG PROGRAMS.CAC SECLINK.RND
FONTS\ SOUNDS\ THEMES\ WPAPER\ BANKS\ SAVERS\ the user's own files
KEYS\ the publishers' keys the user trusts
APPS\<vendor>\<program>\ each program's settings and saved files
DOWNLOAD\ Terminal's downloads
SOFTWARE\ Software's packages being fetched (never Terminal's files)
-
The user folder is USER in the DVX folder unless the DVXUSER environment variable names another (a second disk, a network folder per person, a writable folder when DVX runs from a CD-ROM). When it cannot be written, DVX uses DVXUSER in the TEMP folder and says so; without TEMP, settings are kept until DVX exits.
-
The first start copies SYSTEM\DVX.INI (with its comments and defaults) to the user folder; the first start in TEMP copies the DVX.INI of the folder that cannot be written instead, when it has one. ASSOC.INI in the user folder holds only the user’s changes to SYSTEM\ASSOC.INI (an empty value removes a shipped file type), so an upgrade’s new file types appear while the user’s choices stay.
-
Only packages fill SHARED: DVX’s own, and add-on packages of fonts, sounds, themes, wallpapers, instrument banks, and screen savers, each in a folder of its vendor’s under its kind (SHARED\FONTS\<vendor>\...). A program reads it but never writes or installs into it; a program’s own files live with it (DATA, or resources in its .app), under its vendor and program folder, so two programs' files never collide.
-
SHARED and the user folder have the same six kinds of folder (DvxKindE: FONTS, SOUNDS, THEMES, WPAPER, BANKS, and SAVERS). A lookup looks in the user’s first, so a user’s file of the same name wins; lists show both; saving always goes to the user’s. Settings store a file in one of these folders by its name alone.
-
Each program’s writable folder is the user folder’s APPS\ plus the program’s path (DxeAppContextT.userDir, BASIC App.User). A BASIC program’s is made when it first uses App.User; a C program makes its own with shellEnsureUserDir before it writes there. Its shipped files are in DATA beside the .app (shellDataPath, BASIC App.Data), read-only.
-
The help files the loader recompiles when libraries or widgets change are written in APPS: DVX updating its own install. The step is skipped when APPS cannot be written.
Every folder name is defined once in dvxPlat.h (DVX_SYSTEM_DIR, DVX_APPS_DIR, DVX_SHARED_DIR, DVX_USER_DIR, DVX_DATA_DIR, and the kinds' names), with the functions that find them (platformUserInit, platformUserPath, platformDvxIniPath, platformAppUserDir, platformKindFind, platformKindReadDir, and the rest; see the API reference).
1.10. Per-App Memory Tracking (dvxMem.h)
All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage. When a program ends, what it still has allocated is logged ("Memory: program <id> ended with <n> bytes still allocated to it; they stay until DVX exits"): DVX keeps no list of a program’s blocks, so it frees none of them for it.
1.10.1. Transparent Interception
DXE code does NOT need to include dvxMem.h. The DXE export table maps malloc / free / calloc / realloc / strdup / strndup to the dvxXxx wrappers, so standard C code is tracked automatically. Memory the C library allocates itself (asprintf, getcwd with no buffer, the regular expression functions) is not tracked; free and realloc pass such a pointer on to the C library.
Explicit use (e.g. in the Task Manager) can include dvxMem.h to call:
| Function | Purpose |
|---|---|
dvxMemGetAppUsage |
Query current bytes allocated for an app |
dvxMemGetRetained |
Query the bytes ended apps left allocated (in use until DVX exits) |
dvxMemResetApp |
Start an app’s accounting over, logging what it left allocated (nothing is freed) |
dvxMemSetApp |
Make an app the current one (a library’s own memory: DVX_MEM_SYSTEM) |
The dvxMemAppIdPtr pointer is set by the shell to &ctx->currentAppId so the allocator always knows which app to charge.
1.11. DXE Module System
DVX uses DJGPP’s DXE3 (Dynamic eXtension) format for all loadable modules. DXE3 supports RTLD_GLOBAL symbol sharing — symbols exported by one module are visible to all subsequently loaded modules. This is critical: widget DXEs call core API functions (e.g. rectFill, wgtInvalidate) that are exported by the core library DXE.
1.11.1. Module Types
| Extension | Directory | Purpose | Examples |
|---|---|---|---|
.lib |
LIBS/ |
Libraries: infrastructure APIs. Those with constructors, and the shell, load as DVX starts; every other one when something first needs one of its names. Each exports an ABI stamp. |
libtasks.lib, libdvx.lib, dvxshell.lib |
.wgt |
WIDGETS/ |
Widget type plugins. Each exports wgtRegister() and an ABI stamp. |
button.wgt, listview.wgt, ansiterm.wgt |
.app |
APPS/*/ |
Application modules. Each exports appDescriptor (which records its ABI) and appMain(). Loaded on demand by the shell. |
progman.app, notepad.app, cpanel.app |
1.11.2. Binary Interface Version
DVX_ABI_VERSION (dvxTypes.h) is one number for the binary interface between all modules. Each .lib and .wgt exports <baseName>AbiVersion (written by DVX_ABI_STAMP(baseName) in its main source file); each app’s AppDescriptorT starts with abiVersion (SHELL_APP_DESCRIPTOR fills it); each widget API struct starts with a WgtApiHeaderT; each widget class carries WGT_CLASS_VERSION, which is the same number. The loader checks every .lib and .wgt right after loading it: at the start, one of DVX’s own (under LIBS\KPUNCH or WIDGETS\KPUNCH) whose stamp is missing or different stops the boot with a message naming it, while an add-on’s is skipped and named in the box the shell shows once it starts (as is an add-on that cannot be loaded at all, or one that needs it); a library loaded later (see Boot Sequence) is refused and logged, and what needed it fails then; the shell refuses a mismatched app with a message box; wgtGetApi and wgtRegisterClass refuse mismatched tables and classes. Details always go to DVX.LOG. The bump rule and the size-table test that enforces it are described with DVX_ABI_VERSION in the API reference (dvxTypes.h).
1.11.3. Boot Sequence
dvx.com (DVX.COM: starts dvx.exe again after each DOS program, dvxshell's shell.run)
|
dvx.exe (loader)
|
+-- Enter VGA mode 13h, display splash screen with progress bar
|
+-- Scan LIBS/ for *.lib, WIDGETS/ for *.wgt
|
+-- Read .dep files for each module (dependency base names)
|
+-- Index the names each library exports (its file's DXE header and
| export table only; a hash and the library for each name)
|
+-- Load, each after the libraries it needs:
| - the libraries with constructors (code that runs as they load:
| audio, music, joystick, the network, Task Manager, texthelp)
| - the library with shellMain (dvxshell.lib)
| - every widget; each .wgt that exports wgtRegister() has it called
| - dlopen() with RTLD_GLOBAL; ABI stamp checked; one of DVX's own
| that cannot load stops the boot, an add-on is skipped and
| named in a box once the shell starts (/SAFE leaves every
| add-on out)
| - each module opened is logged with where it is in memory
| ("Module: <path> at 0x<address> (<n> bytes)", for crash
| reports)
|
+-- Bring the help files built at start-up up to date: when a
| module or help file under LIBS or WIDGETS is added, removed, or
| changed, each help file whose sources changed is built again (a
| source that does not compile is left out, logged, and named in
| the box)
|
+-- Find and call shellMain()
|
+-- Every other library loads when something first needs one of
| its names: a module being opened (platformModuleOpen), or a
| dlsym(NULL) (BASIC's DECLARE LIBRARY, dvxLibraryLoaded).
| platformLoadedSymbol looks a name up without loading; what
| binds to a library once it is loaded hears of each one
| through the shell's hook (platformSetLibraryLoadHook: the
| cryptography library's random numbers are seeded then)
|
+-- dvxInit() -- video mode, input, font, colors, cursors
|
+-- Load shell app (progman.app)
|
+-- Main loop:
dvxUpdate() (yields) -> shellReapApps() -> close, exit,
and DOS-run requests -> screen saver
1.11.4. Application Lifecycle
Two kinds of DXE apps:
Callback-only (hasMainLoop = false)
appMain() creates windows, registers callbacks, and returns. The app lives through GUI callbacks driven by the shell’s main loop. Lifecycle ends when the last window is closed. No extra task stack needed — simpler and cheaper.
Main-loop (hasMainLoop = true)
A dedicated cooperative task is created. appMain() runs in that task with its own loop, calling tsYield() (or dvxUpdate, which yields) to share CPU. Needed for apps with continuous work (terminal emulators, games). Lifecycle ends when appMain() returns.
Input is taken on the shell’s own task (see Event Model), so every window callback — a callback-only app’s and a main-loop app’s alike — runs there, never on another program’s stack; a main-loop app’s own loop sees what its callbacks did when it next runs. A BASIC program’s events are the exception: its form runtime queues those the shell’s task dispatches and runs them on the program’s own task at its next turn (DoEvents, its event loop), so a handler that waits (DoEvents, SHELL, a modal form) holds only its own program. Its UserControls' events (their mouse, keys, focus, Resize, and Paint) wait for that turn the same way: a program’s code never runs on two tasks at once.
1.11.5. Crash Recovery
The platform layer installs signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, the handler logs platform-specific diagnostics (register dump on DJGPP, and the module the faulting address is in, with the offset into it that addr2line reads against the module’s own link: see Debugging in the SDK guide), then longjmps to a recovery point: in a program’s own task, the one at that task’s base (platformSetCrashTarget, shellTaskRun), where only that task stops and the shell ends the program at the main task’s next turn, inside whatever loop the main task is in (a dialog box it has open keeps working, and the fault box opens over it); on the main task, the shell’s main loop. The crashed app is killed; other apps and the shell survive. This provides Windows 3.1-style fault tolerance. While DVX starts, each part that runs programs has a recovery point of its own, so a program that crashes then is ended the same way; a crash in DVX’s own start-up code stops DVX with a message in text mode.
1.11.6. Per-App Memory Tracking
All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage. When a program ends, what it still has allocated is logged ("Memory: program <id> ended with <n> bytes still allocated to it; they stay until DVX exits"): DVX keeps no list of a program’s blocks, so it frees none of them for it.
1.12. Event Model
DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame. The first four steps run only in a frame that takes input: the context’s inputHere hook decides, and the shell lets only its own task take it (or any task, once the shell’s has not for a quarter of a second, busy in a long call), so callbacks run on the shell’s task; a frame on another task just paints and yields.
-
Poll mouse — platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection.
-
Poll keyboard — platformKeyboardRead() returns ASCII + scancode. Non-blocking; returns false if buffer is empty. Shift/Ctrl/Alt+F-keys arrive as the plain F-key plus modifier flags. If an input entropy hook is installed (dvxSetInputEntropyHook), input events are timestamped and fed to it here.
-
Dispatch to focused window — the event loop fires window callbacks (onKey, onMouse, etc.) on the focused window. If the window has a widget tree, the widget system’s installed handlers dispatch to individual widgets.
-
Tooltips, widget polling (WCLASS_NEEDS_POLL), cursor blink, and widget timers.
-
Deferred paint flush — every window whose paintNeeded was raised by wgtInvalidate / wgtInvalidatePaint during the frame is painted once (the highest requested level wins). Windows queued for destruction are skipped. After a partial repaint (wgtInvalidatePaint only) the widget paint narrows the window’s dirty area to the boxes of the widgets it repainted, joined and widened two pixels (a container that paints its children itself counts as its own box), so only that part of the screen is composited and flushed; a full repaint, an open popup list, and a window that paints itself composite the whole window.
-
Deferred destroy flush — windows destroyed from inside callbacks are torn down once the dispatch depth is back to zero.
-
Compositor pass — merge dirty rects, composite, flush to LFB.
-
Yield — the idle callback after a frame with nothing to paint, the busy callback after one that painted (the shell’s run the idle handlers — audio streams, network, serial pollers — at least every 20 ms either way, and yield to the other tasks every frame), or platformYield() without them.
1.12.1. Event Dispatch Chain
Mouse/Keyboard Input
|
Global handlers (Ctrl+Esc, modal filter)
|
System-wide hotkeys (dvxRegisterHotkey)
|
Menu keys (Alt+letter), accelerator table check (focused window)
|
Window callback (onMouse / onKey)
|
[If widget tree installed:]
|
widgetOnMouse / widgetOnKey
|
Widget hit test (widgetHitTest)
|
wclsOnMouse / wclsOnKey (vtable dispatch)
|
Universal callbacks (onClick, onChange, etc.)
While a menu is open it takes every key (menus are keyboard-modal), except Alt+letter, which closes it first and is then handled as usual: the bar’s menu of that letter opens, or a control’s access key acts (the system menu does the same). Tab and Shift+Tab move the focus between widgets; a widget that wants Tab (swallowTab, WCLASS_SWALLOWS_TAB), the only widget that can take the focus, and a window where the focus has nowhere to go (no widget can take it, or no widgets at all) get it in onKey instead. A press on a window’s chrome (title bar, menu bar, scroll bars, gadgets) takes the focus from its widget only for the moment: the window’s next paint hands it back to the same widget.
A mouse click comes in Visual Basic’s order: onMouseDown at the press, then onMouseUp and onClick at the release, onClick only when the release is over the widget. A button (WCLASS_PRESS_RELEASE) clicks at the release over it; a list’s onClick (WCLASS_CLICK_ON_PICK) is its pick, after the press’s onMouseDown; any other widget holds the press, so the left release’s onMouseUp is its own wherever the mouse is. A double click is onMouseDown, onMouseUp, onClick, onDblClick, onMouseUp (outside a button or a list, the second press is the onDblClick alone).
Mouse events use two hit tests. widgetHitTest finds the widget whose class handles the press; it stops at a WCLASS_NO_HIT_RECURSE container (Splitter, ScrollPane), so the container’s ON_MOUSE handler still gets the press (divider drag, scrollbar clicks, forwarding into its children). widgetCallbackTarget continues through non-focusable NO_HIT_RECURSE containers into the child whose paintClip (the visible part when it was last painted) contains the point. The universal callbacks (onClick, onDblClick, onMouseDown/Up/Move), context menus, tooltips, and the cursor shape use that target, so a control inside a Splitter pane or ScrollPane viewport gets its own events only where it is visible; on the container’s own chrome the container is the target.
1.12.2. Accelerator Tables
Per-window accelerator tables map key + modifier combinations to command IDs. The runtime normalizes key/modifier at registration time with the same rule it applies to every keystroke (letters uppercased, Ctrl+letter and Alt+letter mapped to the letter, Ctrl/Alt always significant, Shift significant except for a printable character typed without Ctrl/Alt), so matching at dispatch time is two integer comparisons per entry. Matched accelerators fire the window’s onMenu callback with the command ID, unifying the menu and hotkey code paths.
1.12.3. Mouse Wheel
The wheel goes to the focused window. It is first offered to a WGT_METHOD_ON_WHEEL handler on the focused widget and then on each ancestor (delta in notches, positive = down, reverse setting applied); a handler that returns true consumes it. Otherwise a WCLASS_SCROLLABLE focused widget, or its nearest scroll-container ancestor, receives Up/Down arrow keys (wheelStep per notch), and failing that the window’s own scrollbar moves. The focused widget’s onScroll callback fires in every case. The lists (ListBox, ListView, TreeView) scroll their view in their ON_WHEEL handlers without moving the selection, as Visual Basic’s do; a Dropdown or ComboBox scrolls its open list, or steps its closed box one item a notch (a pick each).
1.12.4. Mouse Cursor
Software-rendered cursor using the classic AND/XOR mask approach. Eight cursor shapes are compiled in (dvxCur.h, CURSOR_COUNT): arrow, horizontal resize, vertical resize, NW-SE diagonal resize, NE-SW diagonal resize, busy (hourglass), crosshair, and no-drop (a circle with a slash, for drag and drop: dvxDragCursorSet). The cursor is painted into the backbuffer on top of the composited frame and the affected region is flushed to the LFB each frame.
1.13. Font System
Every text call takes a BitmapFontT, and there are two kinds of them. The system font is the 8x16 VGA ROM font (code page 437, 256 glyphs) built into libdvx: 8-pixel cells, one byte per glyph row, so character positions are a multiplication, glyph lookup an index, and every scanline a single byte — the hot paths of drawChar, drawTextN, and drawTermRow depend on it. A loaded font (dvxText.h) is one size of a font family from the FONTS folder (Setup installs the base set of DejaVu Sans, Sans Mono, and Serif or none, and the More Fonts add-on the others; a family that is not there opens as the system font): per-glyph advances and bitmap boxes, any width, proportional or fixed-pitch, and in up to four styles. The same calls draw and measure both; a loaded font’s glyphs field is what sends them to the general paths.
1.13.1. BitmapFontT
typedef struct {
int32_t charWidth; // cell width (fixed pitch) or the digit 0's advance
int32_t charHeight; // line height
int32_t firstChar; // 0
int32_t numChars; // 256
const uint8_t *glyphData; // system font: charHeight bytes per glyph; loaded: bitmaps
const FontGlyphT *glyphs; // loaded font: per-glyph metrics; NULL: the system font
const uint32_t *glyphAt; // loaded font: each glyph's bitmap offset
int32_t ascent; // top of a line to the baseline
int32_t pixelSize;
uint32_t style; // FONT_STYLE_BOLD / ITALIC
uint32_t flags; // FONT_FLAG_PROPORTIONAL, _SYNTH_BOLD, _SYNTH_ITALIC, _GRAY
int32_t underlineY; // underline and accelerator row
int32_t strikeY; // strike-through row
int32_t lineThick;
void *priv; // the font cache's entry
uint32_t serial; // new whenever the glyphs are built (again)
} BitmapFontT;
A FontGlyphT is six bytes: advance, bitmap width and height, the bitmap’s offset from the pen (left, and top up from the baseline), and flags. A glyph’s bitmap is height rows of (width + 7) / 8 bytes, the leftmost pixel in the top bit.
1.13.2. Text Rendering Functions
drawChar() — Renders a single character. Supports opaque (background fill) and transparent modes.
drawTextN() — Optimized batch rendering for a known character count. Clips once for the entire run, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character rendering for long runs. In a loaded font each glyph is drawn at the pen; every bitmap byte whose 8 pixels lie inside the clip rectangle goes through the same unrolled row writers as the system font, so only the bytes on a clip edge are drawn pixel by pixel.
drawTermRow() — Renders an 80-column terminal row in a single pass, with per-cell foreground/background from a 16-color palette, blink attribute support, and cursor rendering. Exists because per-character terminal rendering is unacceptably slow on target hardware.
drawTextAccel() — Renders text with & accelerator markers. The character after & is marked with the font’s underline across its advance to indicate the keyboard shortcut.
drawTextStyled() — Text with an underline and / or strike-through as wide as it, at the font’s rows.
textWidth(), textWidthN(), textWidthAccel() — Widths: for the system font a multiplication, for a loaded font the sum of the advances.
1.13.3. Loading Fonts
dvxFontOpen(family, size, style) reads the family list from FONTS (once, at the first call: each .DFN file’s header and size table), picks the face for the style — the exact one, else one with fewer style bits whose missing bits are made — and that face’s size nearest the one asked for. It never scales. The font is built once into a glyph table and bitmaps of its own, so drawing never decides anything per glyph:
-
A character the face has is copied; when a style is made, bold thickens each stroke by a column (two from 24 pixels) and italic moves each row one column right per four rows above the baseline.
-
Box drawing, block, and shade characters (CP437 B0-DF) the face lacks — or all of them, when its file asks, or when a made bold widens a fixed pitch — are drawn to fill the character cell from a table of each character’s arms (none, single, or double; up, down, left, and right), so lines join across characters. They are never thickened or slanted.
-
Any other character the face lacks comes from DejaVu Sans (DejaVu Sans Mono for a fixed-pitch face, centered in its pitch) at the nearest size in the same style, or from the system font when those are not installed.
-
What nothing has is a blank as wide as a space.
Fonts are cached and counted: the same family, size, and style opened again is the same font. Up to eight fonts no one holds stay loaded, the least recently used unloaded first. Everything the font system allocates is charged to the system, not to the program that happened to open a font.
1.13.4. Fonts a Program Carries
A family is installed (the FONTS folder, read by its full path so a program that changes the current folder still finds them) or added for an owner: a program’s app id, or 0 for every program. The shell calls dvxFontAddResources for each program it loads (its DVX_RES_FONT resources, read in place: a font source is a file and the font’s offset and length in it) and dvxFontRemoveOwner when its resources are released; a program can add .DFN files or fonts in memory itself. Every lookup is for the running program (*dvxMemAppIdPtr, the shell’s currentAppId; window callbacks run as the window’s program).
Opening a font picks its face per style from the program’s own family and the installed one together: the style’s faces in sFaceOrder’s order, the first style either has; then the nearest size of either face’s sizes; then the program’s face when it has that size, else the installed one. So a program’s faces and sizes win, and the installed family fills in the rest. A program with no families of its own shares the cache with every other; one with its own gets fonts built for it alone (their fallback glyphs may come from its families too). A program’s fonts that change or go are detached from the cache: the ones no one holds unloaded, held ones kept as they are.
Each face holds its source counted, and each font built from it holds it too, so a font’s license (dvxFontLicence) is always the one of the face it was built from, its program ended or not.
The building works on one level per pixel (0 to FONT_GRAY_FULL) whatever the source, and packs the finished glyph at the font’s own depth, so made styles, box characters, and fallback glyphs are the same code for both kinds of font.
1.13.5. Smoothed Text
A .DFN size can come twice: 1-bit, and smoothed — FONT_GRAY_BPP (2) bits per pixel, four levels from none to full, rendered by FreeType with light hinting. mkfont smooths the sizes fonts.ini lists under smooth. A 1-bit size is FreeType’s 1-bit hinted rendering, except at the sizes listed under graycut, where it is the light-hinted rendering with every pixel at least half covered set: some faces' 1-bit hinting draws them too light (DejaVu Serif Bold at its smoothed sizes, which comes out near regular weight, and DejaVu Sans Bold at 8 pixels). When smoothing is on (dvxFontSetSmooth), such a size opens from its smoothed strike and the font has FONT_FLAG_GRAY; every other size, and every face without one, stays 1-bit.
Drawing a full-level pixel is a store of the text color, as for a 1-bit font. A partial one is the text color blended into the pixel under it, channel by channel through the display’s PixelFormatT masks and shifts; text mostly stands on one color, so each glyph keeps its last blend per level and reuses it while the color under it stays the same. Only partial pixels cost more than 1-bit text. At 8 bits per pixel there is nothing to blend with: the pixels of FONT_GRAY_HALF and more are drawn and the rest dropped. The scaled text path (drawTextScaled) does the same.
The application decides (dvxSetFontSmoothing): smoothing is on when the user wants it (DVX.INI [fonts] smoothing, on by default; Control Panel’s Video page) and the screen has more than 8 bits per pixel, and a video mode change applies it again. Turning it on or off builds every open font again in place: widgets keep their font pointers, the glyphs change under them, and the font’s serial changes so caches of measurements (list column widths and the like) know to measure again. Every window is then laid out and painted again.
1.13.6. Widget Fonts
Any widget can have a font of its own (wgtSetFont; BASIC’s FontName, FontSize, FontBold ... properties), and the widgets inside a container draw with the container’s font unless they have their own, so a form’s font is the default for everything on it. wgtFontFor(w, inherited) walks up the parent chain to the nearest font set, else takes the one passed down (the application’s). The class dispatch helpers hand every paint, measure, and layout method that font, so widget code just uses its font parameter — the same code serves the system font, a proportional font, and a fixed-pitch one of any size. Event handlers, which are given no font, call wgtFont(w). Widgets measure text with textWidth / textWidthN, never with character counts. A class that edits text by columns (TextBox, Terminal, ComboBox, Spinner: WCLASS_FIXED_FONT) given a proportional font draws with the system font instead; a fixed-pitch font of any size works there, its column math using that font’s charWidth and charHeight.
Underline and strike-through are part of a font, as in Visual Basic: a font opened with them shares the glyphs of the same font without them, and every text call draws its lines. A widget holds its font open while it is set and closes it when destroyed (widgetFree, the one place a widget is freed).
1.13.7. Rich Text
Text in several fonts in one control is built on the text flow (dvxFlow.h): runs of text, each in a font and a color, laid out into wrapped, aligned lines as tall as the tallest font on them, with offsets for carets, hit tests, and selections. The RichLabel widget is one flow built by calls. The RichEdit widget keeps its document in the richtext library (styled text: runs of interned styles over code page 437 text, an alignment per paragraph, copy / replace / restyle, and RTF in and out) and lays each paragraph out as a flow of its own, so an edit lays out only the paragraphs it touched and repaints only the rows they hold (its quick repaint); a change of height repaints the widget. Its undo steps are pieces of styled text swapped back in, and Copy keeps a styled copy for a paste of the same text.
1.13.8. Font Files (.DFN)
One file holds one family in one style at every size it comes in — its screen sizes, their smoothed copies, and its print sizes (mkfont’s print key; the SDK guide’s Making Fonts) — made on the build host by mkfont (src/tools/mkfont.c) with FreeType from TrueType, OpenType, Type 1, BDF, and PCF fonts, as listed in src/fonts/fonts.ini. Opening a font reads only the header and the strike table, so sizes nothing uses cost disk space, not memory. A .DFN is a pure format conversion: the converter never adds or changes a glyph, it only marks the characters a face lacks. Little-endian, every record read whole:
| Part | Size | Holds |
|---|---|---|
DfnHeaderT |
60 bytes |
"DVXF", format version (2), style, face flags (fixed pitch; box characters drawn by DVX), strike count (1 to 64), family name (31 characters), where the notice and license texts are and their lengths |
DfnStrikeT x count |
24 bytes each |
per size, smallest first: where its glyph table and bitmaps are, the bitmaps' size, the pixel size, ascent, descent, line height, widest advance |
FontGlyphT x 256 |
6 bytes each |
per size, at its glyph table offset |
glyph bitmaps |
as listed |
per size, back to back in character order |
notice text |
as listed |
the family and style, the source fonts it was converted from, and their copyright notices |
license text |
as listed |
the license of the font it came from |
Each glyph’s bitmap starts where the one before ends, so the reader (dvxFontFmt.c) works out the offsets and checks that they fill the strike’s bitmaps exactly. Every count, offset, and size is checked against the font’s length before it is used: a damaged file is refused, never read past.
Each file carries what its license asks to go with every copy of the font: the notice and license texts, transliterated to ASCII with CR LF line ends. They are read only when asked for (dvxFontLicence, the Font dialog’s License button), never when text is drawn, so they cost nothing at run time. A font goes nowhere without its license: copied, installed, or carried inside a program as a resource.
The reader takes a DfnSourceT: a file of its own, a font inside another file at an offset (a program’s font resource), or a font in memory. dfnOpen reads the header and strike table, dfnLoadStrike one size, and dfnLoadText a text.
1.13.9. Performance Optimization
AppContextT stores a fixed-point 16.16 reciprocal of font.charHeight (charHeightRecip) so that dividing by charHeight (the pixel-to-row mapping for popup menu and system menu hover/click) becomes a multiply+shift instead of an integer divide, which costs 40+ cycles on a 486.
1.14. Color System
1.14.1. Pixel Format
PixelFormatT describes the active VESA mode’s pixel encoding. Populated once from the VBE mode info block. Stores shift, mask, and bit count for each channel so packColor() can convert RGB to native format with shift-and-mask arithmetic — no per-pixel computation.
Supported depths:
| Depth | Bytes/Pixel | Notes |
|---|---|---|
8 bpp |
1 |
Palette mode. Nearest-index via 6x6x6 color cube + gray ramp. |
15 bpp |
2 |
5-5-5 RGB (1 bit unused). |
16 bpp |
2 |
5-6-5 RGB. |
32 bpp |
4 |
8-8-8 RGB (8 bits unused). |
1.14.2. ColorSchemeT — Theming
All 20 UI colors are pre-packed into display pixel format at init time. Every color is a uint32_t that can be written directly to the framebuffer with zero per-pixel conversion. The scheme must be regenerated on video mode change, but mode changes require re-init anyway.
Color roles mirror classic Motif/Windows 3.x conventions:
-
desktop — desktop background
-
windowFace, windowHighlight, windowShadow — window chrome bevel triplet
-
activeTitleBg/Fg, inactiveTitleBg/Fg — focused vs. unfocused title bar
-
contentBg/Fg — window content area
-
menuBg/Fg, menuHighlightBg/Fg — menus
-
buttonFace — button background
-
scrollbarBg/Fg/Trough — scrollbar components
-
cursorFg/Bg — mouse cursor colors
Source RGB values are kept in AppContextT.colorRgb[] for theme save/load. Themes are stored as INI files with a [colors] section. The API provides dvxLoadTheme(), dvxSaveTheme(), dvxSetColor(), and dvxResetColorScheme().
1.14.3. Bevel Styles
Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:
BEVEL_RAISED(colorScheme, borderWidth) -- raised 3D look BEVEL_SUNKEN(colorScheme, face, borderWidth) -- sunken/inset look BEVEL_TROUGH(colorScheme) -- 1px scrollbar trough BEVEL_SB_BUTTON(colorScheme) -- scrollbar button
1.15. Platform Layer
All OS-specific and CPU-specific code is isolated behind platform/dvxPlat.h. To port DVX, implement a new dvxPlatformXxx.c against this header.
1.15.1. Implementations
| File | Target | Details |
|---|---|---|
dvxPlatformDos.c |
DJGPP/DPMI |
Real VESA VBE, INT 33h mouse, INT 16h keyboard, rep movsd/rep stosl asm spans, DPMI physical memory mapping for LFB, INT 9 hook for key-up, CuteMouse Wheel API. |
dvxPlatformHost.c |
Linux (test) |
Host test backend: in-memory framebuffer, scripted mouse/keyboard queues, fake clock. Used only by the host test suites. |
dvxPlatformUtil.c |
Shared |
Code common to both backends (paths, globbing, F-key normalization, string helpers). |
1.15.2. Abstraction Areas
Video
platformVideoInit() — mode probe and framebuffer setup. platformVideoShutdown() — restore previous mode. platformVideoEnumModes() — enumerate available modes.
Framebuffer Flush
platformFlushRect() — copy dirty rect from backBuf to video memory. On DOS, each scanline uses rep movsd for near-optimal aligned 32-bit writes over the bus, to the linear framebuffer or, on a card without one, through the 64 KB bank window (platformBankChunk cuts the runs at the window’s end).
Optimized Memory Spans
Six functions: platformSpanFill8/16/32() and platformSpanCopy8/16/32(). Called once per scanline of every rectangle fill, blit, and text draw. On DOS these use inline assembly for critical inner loops.
Mouse Input
Polling model. platformMousePoll() returns position and button bitmask. Wheel support via CuteMouse API. platformMouseInit() can be called again after a video-mode change; it re-applies the speed, acceleration, and wheel settings after the driver reset.
Keyboard Input
platformKeyboardRead() — non-blocking key read; Shift/Ctrl/Alt+F1..F12 are reported as the plain F-key scancode (platformNormalizeFKeyScan). The keyboard hook (a chain on INT 9 on DOS; its code and data are pinned with platformLockRegion) decodes every key going down and up into a held-key table and a queue of raw events (platformKeyEventRead, platformKeyIsDown), which feed onKeyUp and game input windows. platformAltScanToChar() — scancode-to-ASCII lookup for Alt+key combinations.
Timing
platformClock() / platformClockHz() — monotonic UI tick counter. platformMicros() — high-resolution monotonic clock (PIT, with the TSC between interrupts when there is one). The timer service owns the timer interrupt: callbacks at up to 1000 Hz (platformTimerAdd) while the BIOS keeps its 18.2 Hz tick. platformEntropyStamp() — fine-grained timestamp (TSC, or BIOS tick + PIT counter) for input-timing entropy.
Crash Recovery
platformInstallCrashHandler() — signal handlers + longjmp for fault tolerance. platformSetCrashTarget() — the hook that picks the faulting task’s own recovery point. platformOutOfMemory() — stb_ds allocation-failure hook; logs and raises SIGSEGV so it takes the same recovery path. platformAppExit() / platformAppAbort() / platformAppQuickExit() — exit(), abort(), and _exit() as loaded modules see them: the shell’s hook ends only the calling program, by the same recovery path, without a fault message; exit() runs the program’s atexit handlers first. platformAssertFail() — a module’s failed assert(): logged, then the program ends as abort() ends it.
DXE Support
platformRegisterDxeExports() — register C runtime and platform symbols for DXE resolution. A module gets the C library from dvx.exe; the calls that would stop or freeze all of DVX are given as DVX’s own versions (atexit, exit, abort, assert, sleep, usleep, delay, system, signal, console input: see The C Library a Module Gets in the API reference). platformModuleClose() — dlclose for modules: drops the module’s note (platformModuleAt, used by crash reports).
1.16. Build System
1.16.1. Cross-Compilation
DVX is cross-compiled from Linux using a DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc). The top-level Makefile orchestrates building all subsystems in dependency order.
make -- build everything ./mkcd.sh -- build + create ISO for the target emulator
1.16.2. Build Targets
all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps
| Target | Output | Description |
|---|---|---|
core |
bin/libs/libdvx.lib |
GUI core library (draw, comp, wm, app, widget infrastructure) |
tasks |
bin/libs/libtasks.lib |
Cooperative task switcher |
loader |
bin/dvx.exe bin/dvx.com |
Bootstrap loader (the DOS executable) DVX.COM, the real-mode program that starts dvx.exe (16-bit, host GNU as/ld) |
widgets |
bin/widgets/*.wgt |
32 widget module plugins |
shell |
bin/libs/dvxshell.lib |
DVX Shell (app management, desktop) |
taskmgr |
bin/libs/taskmgr.lib |
Task Manager (loaded as a separate DXE) |
texthelp |
shared library |
Shared text editing helpers (clipboard, word boundaries) |
listhelp |
shared library |
Shared dropdown/list helpers |
apps |
bin/apps/*/*.app |
Application modules (progman, notepad, clock, etc.) |
tools |
bin/dvxres |
Resource compiler (runs on Linux, builds resource sections into DXEs) |
serial |
serial DXE libs |
UART driver, HDLC packets, security, seclink |
sql |
SQL DXE lib |
SQLite integration |
1.16.3. DXE3 Build Process
Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:
# Compile i586-pc-msdosdjgpp-gcc -O2 -march=i486 -mtune=i586 -c -o widget.o widget.c # Link as DXE (exports all non-static symbols) dxe3gen -o widget.wgt -U widget.o # Optionally append resources dvxres build widget.wgt widget.res
The -E flag specifies exported symbols (prefixed with underscore per DJGPP convention). -U marks unresolved symbols as OK (they’ll be resolved at load time from previously loaded DXEs).
1.16.4. Deployment (mkcd.sh)
-
Runs make all.
-
Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib).
-
Counts widget modules.
-
Creates an ISO 9660 image from bin/ using mkisofs: -iso-level 1 (strict 8.3 filenames for DOS), -J (Joliet extensions for long names), -V DVX (volume label).
-
Places the ISO at the target emulator’s CD-ROM mount path.
1.16.5. Compiler Flags
-O2 Optimization level 2 -march=i486 486 instruction set baseline -mtune=i586 Optimize scheduling for Pentium -Wall -Wextra Full warnings
1.16.6. Directory Layout
dvxgui/ +-- src/ | +-- loader/ Bootstrap loader (dvx.exe) | +-- libs/kpunch/ Libraries (*.lib), each in its own folder | | +-- libdvx/ Core: video, drawing, compositor, windows, widgets | | | +-- platform/ Platform layer (dvxPlat.h, dvxPlatformDos.c, ...) | | | +-- thirdparty/ stb_image, stb_ds, stb_image_write | | +-- libtasks/ Cooperative task switcher | | +-- dvxshell/ DVX Shell (Program Manager's host, program loading) | | +-- texthelp/ Shared text editing helpers | | +-- listhelp/ Shared dropdown/list helpers | | +-- serial/ rs232: ISR-driven UART driver | | +-- crypto/ X25519, XChaCha20-Poly1305, Ed25519, DH, XTEA, SHA-256 | | +-- seclink/ Packet transport (HDLC, CRC-16) and the secure link | | +-- dvxnet/ TCP/IP (lwIP) and the BSD socket layer | | +-- pkg/ Add-on packages (ZIP, manifests, signatures, install) | | +-- sql/ SQLite integration | | +-- ... audio, music, print, conn, xfer, http, json, and more | +-- widgets/kpunch/ Widget modules (*.wgt), each in its own folder (35) | +-- apps/kpunch/ Programs (*.app): progman, notepad, cpanel, dvxbasic, ... | +-- savers/kpunch/ Screen savers | +-- addons/ Add-on package sources (fonts, instrument banks) | +-- include/basic/ BASIC include files (*.bas) | +-- installer/ SETUP.EXE and the package tools | +-- sdk/ SDK templates | +-- tools/ Build tools (dvxres, dvxhlpc, ...); proxy/: Linux proxy | +-- test/ Test suites (host and DOS) +-- bin/ Build output (dvx.exe, system/, libs/, widgets/, apps/) +-- obj/ Intermediate object files +-- dist/ Release media and the SDK +-- docs/ Documentation
Chapter 2. The Core Library
2.1. DVX GUI API Reference
DOS Visual eXecutive — Complete public API documentation covering every public function, type, and constant in the libdvx headers.
The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. Additional headers cover dialogs, resources, preferences, memory tracking, the platform abstraction, and the widget system.
2.1.1. Headers
-
dvxTypes.h — Shared type definitions and constants
-
dvxCur.h — Embedded mouse cursor bitmaps
-
dvxFont.h — Embedded 8x16 CP437 bitmap font
-
dvxText.h — Font families and loaded fonts
-
dvxFlow.h — Flowing text: runs in fonts and colors, wrapped and aligned
-
dvxPal.h — 8-bit mode 256-color palette
-
dvxVideo.h — Layer 1: VESA VBE video backend
-
dvxDraw.h — Layer 2: 2D drawing primitives
-
dvxComp.h — Layer 3: Dirty rectangle compositor
-
dvxWm.h — Layer 4: Window manager
-
dvxApp.h — Layer 5: Application API
-
dvxDlg.h — Modal dialog boxes
-
dvxRes.h — DXE-embedded resource system
-
dvxPrefs.h — INI preferences system
-
dvxMem.h — Per-app memory tracking
-
dvxEndian.h — Byte order loads and stores
-
dvxHash.h — Hashes, checksums, and hex digits
-
dvxDrv.h — Driver modules
-
dvxWgt.h — Widget system public API
-
dvxWgtP.h — Widget plugin API
-
platform/dvxPlat.h — Platform abstraction layer
See also: dvxCur.h — Cursor Definitions (Section 2.3); dvxFont.h — Bitmap Font Data (Section 2.4); dvxText.h — Fonts (Section 2.5); dvxFlow.h — Flowing Text (Section 2.6); dvxPal.h — 8-bit Palette (Section 2.7); dvxVideo.h — Layer 1: Video Backend (Section 2.8); dvxDraw.h — Layer 2: Drawing Primitives (Section 2.9); dvxComp.h — Layer 3: Compositor (Section 2.10); dvxWm.h — Layer 4: Window Manager (Section 2.11); dvxApp.h — Layer 5: Application API (Section 2.12); dvxDlg.h — Modal Dialogs (Section 2.15); dvxRes.h — Resource System (Section 2.16); dvxPrefs.h — Preferences (Section 2.17); dvxMem.h — Memory Tracking (Section 2.18); dvxEndian.h — Byte Order (Section 2.19); dvxHash.h — Hashes and Checksums (Section 2.20); dvxDrv.h — Driver Modules (Section 2.13); dvxWgt.h — Widget System (Section 2.14); dvxWgtP.h — Widget Plugin API (Section 2.21); platform/dvxPlat.h — Platform Layer (Section 2.22).
2.2. dvxTypes.h — Shared Type Definitions
Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions — only structs, enums, typedefs, and compile-time constants.
2.2.1. Binary Interface Version
DVX_ABI_VERSION is one number for the whole binary interface between dvx.exe, libraries (.lib), widgets (.wgt), and apps (.app). Every module records the value it was compiled with, and a module whose value differs from the running system’s is refused instead of being allowed to call the wrong functions:
| Module / table | Where the value is recorded | Checked by |
|---|---|---|
.lib, .wgt |
DVX_ABI_STAMP(baseName) exports <baseName>AbiVersion |
The loader, right after loading the module. For one of DVX’s own a missing or different stamp stops the boot with a message naming the file; an add-on is skipped and named in the box the shell shows as it starts (a library loaded after the start is refused and logged). Details in DVX.LOG. |
.app |
AppDescriptorT.abiVersion, set by SHELL_APP_DESCRIPTOR |
The shell, before appMain. The user sees "This program was built for a different version of DVX and cannot run."; DVX.LOG has both versions. |
Widget API |
WgtApiHeaderT.abiVersion, set by WGT_API_HEADER |
wgtGetApi (which also checks the table’s size). |
Widget class |
WidgetClassT.version (WGT_CLASS_VERSION is DVX_ABI_VERSION) |
wgtRegisterClass. |
Driver (.drv) |
DvxDriverHeaderT.abiVersion, set by DVX_DRIVER_HDR |
dvxDriversLoad, when the library of its device class loads it (a mismatched driver is skipped and logged). |
Every library and widget module writes the stamp once at file scope in its main source file; the argument is the module file’s base name (libdvx for LIBDVX.LIB, box for BOX.WGT):
#include "dvxTypes.h"
DVX_ABI_STAMP(mylib);
Bump rule: increment DVX_ABI_VERSION in the same change that alters anything an already compiled module depends on — the size, member order, or member types of a public struct or widget API struct in an SDK header; a WGT_METHOD_* slot or the meaning of a WidgetClassT slot; the parameters, return type, or calling contract of a public or exported function (or its removal); the value of a public constant modules compile in. Adding a function, a constant, or a struct no existing struct embeds needs no bump. After a bump, run make -C src/test/abi update to regenerate the committed size table (src/test/abi/abiSizes.txt). The abi host test fails when a public struct changes size without a bump, or when the table was not regenerated.
2.2.2. Core Structures
PixelFormatT
Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.
| Field | Description |
|---|---|
int32_t bitsPerPixel |
8, 15, 16, or 32 |
int32_t bytesPerPixel |
1, 2, 2, or 4 |
uint32_t redMask, greenMask, blueMask |
Bitmasks for each color channel |
int32_t redShift, greenShift, blueShift |
Bit position of each color field |
int32_t redBits, greenBits, blueBits |
Number of bits per channel |
DisplayT
Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to the screen (platformFlushRect). No DisplayT holds a pointer to video memory: the platform layer keeps the way to it (on DOS, a selector over the linear frame buffer or the VGA window), so a wild pointer that leaves DVX’s memory faults, ending only its program, instead of writing to the screen or to DOS’s memory. A display of your own (dvxContentDisplay, wgtCanvasGetDisplay, or one you fill in) is its backBuf alone.
| Field | Description |
|---|---|
int32_t width, height |
Screen dimensions in pixels |
int32_t pitch |
Bytes per scanline |
PixelFormatT format |
Active pixel format |
uint8_t *backBuf |
System RAM backbuffer |
uint8_t *palette |
768 bytes for 8-bit mode, NULL otherwise |
int32_t clipX, clipY, clipW, clipH |
Current clip rectangle |
RectT
Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.
| Field | Description |
|---|---|
int32_t x, y |
Top-left corner |
int32_t w, h |
Width and height |
BlitOpsT
Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).
| Field | Description |
|---|---|
SpanFillFnT spanFill |
Fill a horizontal span with a solid color |
SpanCopyFnT spanCopy |
Copy a horizontal span between buffers |
int32_t bytesPerPixel |
Bytes per pixel for the active mode |
int32_t pitch |
Bytes per scanline |
BevelStyleT
Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.
| Field | Description |
|---|---|
uint32_t highlight |
Lighter color (top/left edges) |
uint32_t shadow |
Darker color (bottom/right edges) |
uint32_t face |
Interior fill color (0 = no fill) |
int32_t width |
Border thickness in pixels (typically 2) |
BitmapFontT
The one font type every text call takes. Two kinds share it: the built-in system font (dvxFont8x16: 8-pixel cells of the VGA 8x16 font, one byte per glyph row, glyphs NULL; text takes the byte-aligned fast paths) and a loaded font (dvxFontOpen, dvxText.h: a size of a .DFN font file, or the system font made bold or italic), whose glyphs give each character’s advance and bitmap box. Every character of code page 437 draws in either kind.
| Field | Description |
|---|---|
int32_t charWidth |
Cell width of a fixed-pitch font; the digit 0’s width in a proportional one (for "so many characters wide") |
int32_t charHeight |
Line height |
int32_t firstChar |
Code of the first glyph (0) |
int32_t numChars |
Number of glyphs (256) |
const uint8_t *glyphData |
System font: charHeight bytes per glyph; loaded font: the glyph bitmaps |
const FontGlyphT *glyphs |
Loaded font: each character’s glyph; NULL for the system font |
const uint32_t *glyphAt |
Loaded font: where each glyph’s bitmap starts in glyphData |
int32_t ascent |
Rows from the top of a line to the baseline |
int32_t pixelSize |
The size the font was made at (16 for the system font) |
uint32_t style |
FONT_STYLE_BOLD / FONT_STYLE_ITALIC the font draws |
uint32_t flags |
FONT_FLAG_PROPORTIONAL, FONT_FLAG_SYNTH_BOLD, FONT_FLAG_SYNTH_ITALIC, FONT_FLAG_GRAY |
int32_t underlineY |
Row of an underline and of accelerator marks, from the top of a line |
int32_t strikeY |
Row of a strike-through line |
int32_t lineThick |
Rows in those lines |
void *priv |
The font cache’s (dvxFontClose); NULL for fonts not from dvxFontOpen |
uint32_t serial |
A loaded font’s own number, never reused; new when its glyphs are built again (dvxFontSetSmooth). 0 for the system font as compiled in |
Measure text with textWidth / textWidthN, never strlen * charWidth: a loaded font may be proportional.
FontGlyphT
One character of a loaded font, the same 6-byte record a .DFN file stores. The glyph’s bitmap is height rows of FONT_ROW_BYTES(width) bytes, the leftmost pixel in the top bit, at glyphData + glyphAt[character]. In a smoothed font (FONT_FLAG_GRAY) each pixel is FONT_GRAY_BPP bits instead: rows of FONT_ROW_BYTES_BPP(width, FONT_GRAY_BPP) bytes, a pixel’s level 0 (none) to FONT_GRAY_FULL read with FONT_GRAY_LEVEL(row, x); FONT_BPP(font) is a font’s bits per pixel.
| Field | Description |
|---|---|
uint8_t advance |
Pen movement after the glyph |
uint8_t width, height |
Bitmap size |
int8_t left |
Pen position to the bitmap’s left column (negative: the glyph reaches back) |
int8_t top |
Baseline to the bitmap’s top row (up is positive) |
uint8_t flags |
FONT_GLYPH_MISSING in a file (a loaded font has every glyph) |
Font styles and flags
| Define | Value | Description |
|---|---|---|
FONT_STYLE_BOLD |
0x01 |
Bold face (dvxFontOpen) |
FONT_STYLE_ITALIC |
0x02 |
Italic face (dvxFontOpen) |
FONT_STYLE_UNDERLINE |
0x04 |
Underline drawn with the text (drawTextStyled) |
FONT_STYLE_STRIKE |
0x08 |
Strike-through drawn with the text (drawTextStyled) |
FONT_STYLE_FACE |
0x03 |
The face bits (bold and italic) |
FONT_FLAG_PROPORTIONAL |
0x01 |
Characters differ in width |
FONT_FLAG_SYNTH_BOLD |
0x02 |
Bold made from the regular face (thickened) |
FONT_FLAG_SYNTH_ITALIC |
0x04 |
Italic made by slanting the upright face |
FONT_FLAG_GRAY |
0x08 |
Smoothed: glyph pixels of FONT_GRAY_BPP bits (dvxFontSetSmooth) |
ColorSchemeT
All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.
| Field | Description |
|---|---|
uint32_t desktop |
Desktop background color |
uint32_t windowFace |
Window body / chrome face |
uint32_t windowHighlight |
Bevel highlight (top/left edge) |
uint32_t windowShadow |
Bevel shadow (bottom/right edge) |
uint32_t activeTitleBg, activeTitleFg |
Focused window title bar |
uint32_t inactiveTitleBg, inactiveTitleFg |
Unfocused window title bar |
uint32_t contentBg, contentFg |
Window content area default colors |
uint32_t menuBg, menuFg |
Menu bar and popup background/text |
uint32_t menuHighlightBg, menuHighlightFg |
Menu item highlight |
uint32_t buttonFace |
Button face color |
uint32_t scrollbarBg, scrollbarFg, scrollbarTrough |
Scrollbar element colors |
uint32_t cursorFg, cursorBg |
Mouse cursor colors |
ColorIdE
Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.
Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.
DirtyListT
List of dirty rectangles. The rect array is preallocated to a soft cap (128) by dirtyListInit; at the cap dirtyListAdd merges or collapses rects instead of growing, so the array is only (re)allocated when the initial allocation failed.
| Field | Description |
|---|---|
RectT *rects |
Dynamic array of dirty rectangles |
int32_t count |
Current number of dirty rects |
int32_t cap |
Allocated capacity |
WindowT
Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.
| Field | Description |
|---|---|
int32_t id |
Unique window identifier |
int32_t appId |
Shell app ID (0 = shell itself) |
int32_t x, y, w, h |
Outer frame position and dimensions |
int32_t contentX, contentY, contentW, contentH |
Content area inset from frame |
char title[MAX_TITLE_LEN] |
Window title text: MAX_TITLE_LEN - 1 (127) characters and the NUL; a longer title is cut |
bool visible, focused, minimized, maximized, resizable, modal |
Window state flags (modal: no minimize gadget, no open or close sound; dvxModalBegin sets it while the window is in the modal stack) |
bool modalBegun, modalWas |
DVX’s: in the modal stack by dvxModalBegin, and the window’s own modal flag from before, given back when it leaves the stack |
bool disabled |
The user’s input reaches nothing of the window (dvxSetWindowEnabled, which changes it) |
bool iconNeedsRefresh |
true when contentBuf changed (for minimized icon refresh) |
bool gameInput |
Game input: see below |
bool noAccessKeys |
True when the window’s controls take no access keys (Alt+letter goes to its menu bar or the one it borrows): a form designer’s surface, whose controls are being designed |
uint8_t paintNeeded |
PAINT_NONE / PAINT_PARTIAL / PAINT_FULL |
int32_t maxW, maxH |
Maximum dimensions |
int32_t preMaxX, preMaxY, preMaxW, preMaxH |
Saved geometry before maximize |
uint8_t *contentBuf |
Per-window content backbuffer |
int32_t contentPitch |
Content buffer bytes per row |
uint8_t *iconData |
Icon pixel data, NULL if none |
int32_t iconW, iconH, iconPitch |
Icon image dimensions and pitch |
MenuBarT *menuBar |
Menu bar (NULL if no menus) |
ScrollbarT *vScroll, *hScroll |
Scrollbars (NULL if not present) |
struct WidgetT *widgetRoot |
Widget tree root (NULL if none) |
MenuT *contextMenu |
Right-click context menu |
AccelTableT *accelTable |
Keyboard accelerator table |
int32_t menuWinId |
The id of the window whose menu bar this one’s Alt+letter and F10 open (0 for none): a tool window of a program’s main window. A menu bar of the window’s own is then opened by the mouse only (a designer’s preview of a form’s menus). The window’s own controls' access keys come first (unless noAccessKeys); a main window that is gone, hidden, or minimized lends none |
struct WidgetT *defaultBtn, *cancelBtn |
Default (Enter) and cancel (Escape) buttons, NULL for none (dvxSetWindowButtons); cleared when the button is destroyed |
struct WindowT *modalPrev |
The modal window this one took over from (dvxModalBegin), NULL for none |
void *userData |
Application-defined data pointer |
Callbacks:
| Callback | Description |
|---|---|
onPaint(WindowT *win, RectT *dirtyArea) |
Content repaint requested; a painter that changed only part of dirtyArea may narrow it, and only that part is composited |
onKey(WindowT *win, int32_t key, int32_t mod) |
Key press: key is the character’s code, or scancode | KEY_EXT_FLAG for a key with no character (KEY_F1, KEY_UP, ...) |
onKeyUp(WindowT *win, int32_t scancode, int32_t mod) |
Key release: scancode is always the key’s scancode | KEY_EXT_FLAG, a character key’s too (the A key goes down as 'a', 0x61, and comes up as 0x1E | KEY_EXT_FLAG), so a press and its release do not compare equal |
onMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons) |
Mouse event (content-relative) |
onResize(WindowT *win, int32_t newW, int32_t newH) |
Window resized |
onClose(WindowT *win) |
Close requested |
onMenu(WindowT *win, int32_t menuId) |
Menu item or accelerator activated |
onMenuOpen(WindowT *win, MenuT *menu) |
A menu of the bar or a submenu is about to open (its items can still change); it opens after only if it still can, and a menu-bar menu with no items opens none |
onScroll(WindowT *win, ScrollbarOrientE orient, int32_t value) |
Scrollbar value changed |
int32_t onCursorQuery(WindowT *win, int32_t x, int32_t y) |
Return CURSOR_* for hit position |
onFocus(WindowT *win) |
Window gained focus |
onBlur(WindowT *win) |
Window lost focus |
onRawKey(WindowT *win, const RawKeyEventT *evt) |
Key pressed or released (gameInput windows) |
mod is the BIOS shift-state byte for both: test its KEY_MOD_* bits (Shift, Ctrl, Alt); the lock keys' and Insert’s toggles ride above them.
Game input: while a window with gameInput set has the keyboard focus, DVX keeps only Alt+Tab, Ctrl+Esc, and Alt+F4 for itself. Every other keystroke, F1, F10, Alt+letter, Ctrl+F12, accelerators, and hotkeys included, goes straight to onKey (except while a menu opened with the mouse, or the keyboard move/size mode, is taking keys). onRawKey then receives each key going down and up (RawKeyEventT: set-1 scancode, extended flag, repeat flag, modifiers from the held-key table), after the frame’s onKey calls. When the focus moves away the window gets a release for every key still held (with no modifiers), and the held-key table starts over for the next window. onKeyUp keeps working as for any window. Mouse input is unchanged. The game library (game.h) adds gameKeyIsDown, frame pacing, and timers.
WindowStackT
Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.
| Field | Description |
|---|---|
WindowT **windows |
Dynamic array of window pointers |
int32_t count, cap |
Current count and allocated capacity |
int32_t focusedIdx |
Stack index of focused window |
int32_t dragWindow, dragOffX, dragOffY |
Active drag state |
int32_t dragStartX, dragStartY |
Mouse position at drag begin (for deadzone) |
bool dragActive |
True once mouse moved past deadzone |
int32_t resizeWindow, resizeEdge |
Active resize state |
int32_t scrollWindow, scrollOrient, scrollDragOff |
Active scroll drag state |
MenuT / MenuItemT / MenuBarT
Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.
| Field | Description |
|---|---|
MenuItemT.label |
Item text (supports & accelerator markers) |
MenuItemT.id |
Application-defined command ID |
MenuItemT.type |
MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE |
MenuItemT.separator |
true = horizontal divider line |
MenuItemT.enabled, checked |
Item state |
MenuItemT.accelKey |
Lowercase accelerator character (0 = none) |
MenuItemT.subMenu |
Child menu for cascading (NULL if leaf) |
MenuT.label |
Menu bar label (e.g. "File") |
MenuT.items |
Dynamic array of MenuItemT |
MenuT.itemCount, itemCap |
Current count and allocated capacity |
MenuT.barX, barW |
Computed position/width on the menu bar |
MenuT.accelKey |
Lowercase accelerator character (0 = none) |
MenuT.enabled |
A menu-bar menu’s title is not grayed (dvxSetMenuEnabled); every menu starts true |
MenuT.visible |
A menu-bar menu is on the bar (dvxSetMenuVisible); every menu starts true |
MenuBarT.menus |
Dynamic array of MenuT |
MenuBarT.menuCount, menuCap |
Current count and allocated capacity |
MenuBarT.activeIdx |
Open popup index (-1 = none) |
MenuBarT.positionsDirty |
True when barX/barW need recomputation |
ScrollbarT
Window-level scrollbar state. Managed by the WM layer, drawn after content.
| Field | Description |
|---|---|
ScrollbarOrientE orient |
ScrollbarVerticalE or ScrollbarHorizontalE |
int32_t min, max |
Scroll range |
int32_t value |
Current position |
int32_t pageSize |
Visible portion (for proportional thumb sizing) |
int32_t x, y, length |
Computed screen position and track length |
AccelTableT / AccelEntryT
Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match. Only the normalized form is stored (see dvxAddAccel), so matching is two integer comparisons per entry.
| Field | Description |
|---|---|
AccelEntryT.cmdId |
Command ID passed to onMenu |
AccelEntryT.normKey |
Normalized key (see dvxAddAccel) |
AccelEntryT.normMods |
Normalized ACCEL_* modifiers (see dvxAddAccel) |
AccelTableT.entries |
Dynamic array of AccelEntryT |
AccelTableT.count, cap |
Current count and allocated capacity |
VideoModeInfoT
Describes an available video mode (enumerated at init).
| Field | Description |
|---|---|
int32_t w, h |
Resolution |
int32_t bpp |
Bits per pixel |
CursorT
Software-rendered 16x16 cursor using AND/XOR mask encoding.
| Field | Description |
|---|---|
int32_t width, height |
Cursor dimensions (always 16x16) |
int32_t hotX, hotY |
Hot spot coordinates |
const uint16_t *andMask |
AND mask (0 = draw pixel, 1 = transparent) |
const uint16_t *xorData |
XOR data (0 = black, 1 = white where AND = 0) |
2.2.3. Bevel Convenience Macros
| Macro | Description |
|---|---|
BEVEL_RAISED(cs, bw) |
Raised bevel style from ColorSchemeT ptr and border width |
BEVEL_SUNKEN(cs, face, bw) |
Sunken bevel style with explicit face color |
BEVEL_TROUGH(cs) |
1px sunken trough (for scrollbar tracks) |
BEVEL_SB_BUTTON(cs) |
1px raised scrollbar button |
2.2.4. Chrome Constants
| Define | Value | Description |
|---|---|---|
CHROME_BORDER_WIDTH |
4 |
Outer frame border width |
CHROME_TITLE_HEIGHT |
20 |
Title bar height |
CHROME_TITLE_PAD |
4 |
Title text padding |
CHROME_INNER_BORDER |
2 |
Inner chrome border |
CHROME_MENU_HEIGHT |
20 |
Menu bar height |
CHROME_TOTAL_TOP |
26 |
Total inset from top of frame to content |
CHROME_TOTAL_SIDE |
6 |
Total inset from side of frame to content |
CHROME_TOTAL_BOTTOM |
6 |
Total inset from bottom of frame to content |
2.2.5. Hit Test Constants
| Define | Value | Description |
|---|---|---|
HIT_CONTENT |
0 |
Content area |
HIT_TITLE |
1 |
Title bar |
HIT_CLOSE |
2 |
Close gadget |
HIT_RESIZE |
3 |
Resize border |
HIT_MENU |
4 |
Menu bar |
HIT_VSCROLL |
5 |
Vertical scrollbar |
HIT_HSCROLL |
6 |
Horizontal scrollbar |
HIT_MINIMIZE |
7 |
Minimize gadget |
HIT_MAXIMIZE |
8 |
Maximize gadget |
HIT_NONE |
-1 |
No window hit (desktop) |
2.2.6. Mouse Button Flags
| Define | Value | Description |
|---|---|---|
MOUSE_LEFT |
1 |
Left mouse button |
MOUSE_RIGHT |
2 |
Right mouse button |
MOUSE_MIDDLE |
4 |
Middle mouse button |
2.2.7. Accelerator Modifier Flags
The keyboard modifier flags are the BIOS shift-state bits. KEY_MOD_* (dvxTypes.h) is the single definition; ACCEL_* are aliases of the same values for accelerator tables.
| Define | Value | Description |
|---|---|---|
KEY_MOD_SHIFT |
0x03 |
Either Shift key (BIOS shift state bits) |
KEY_MOD_CTRL |
0x04 |
Ctrl key |
KEY_MOD_ALT |
0x08 |
Alt key |
ACCEL_SHIFT |
0x03 |
Alias of KEY_MOD_SHIFT |
ACCEL_CTRL |
0x04 |
Alias of KEY_MOD_CTRL |
ACCEL_ALT |
0x08 |
Alias of KEY_MOD_ALT |
2.2.8. Extended Key Codes
Non-ASCII keys are delivered as (scancode | KEY_EXT_FLAG). The platform layer reports Shift/Ctrl/Alt+F1..F12 as the plain F-key code with the modifier in the shift-state flags (e.g. Alt+F4 arrives as KEY_F4 with KEY_MOD_ALT).
| Define | Description |
|---|---|
KEY_EXT_FLAG |
0x100, marks an extended (scancode) key |
KEY_F1 .. KEY_F10 |
Function keys (KEY_SCAN_F1..F10 = 0x3B..0x44, | KEY_EXT_FLAG) |
KEY_F11, KEY_F12 |
0x85 | KEY_EXT_FLAG, 0x86 | KEY_EXT_FLAG |
KEY_INSERT |
Insert key |
KEY_DELETE |
Delete key |
KEY_HOME |
Home key |
KEY_END |
End key |
KEY_PGUP |
Page Up key |
KEY_PGDN |
Page Down key |
KEY_UP, KEY_DOWN |
Arrow keys |
KEY_LEFT, KEY_RIGHT |
Arrow keys |
KEY_CTRL_LEFT |
Ctrl+Left (0x73 | KEY_EXT_FLAG) |
KEY_CTRL_RIGHT |
Ctrl+Right (0x74 | KEY_EXT_FLAG) |
KEY_CTRL_END |
Ctrl+End (0x75 | KEY_EXT_FLAG) |
KEY_CTRL_HOME |
Ctrl+Home (0x77 | KEY_EXT_FLAG) |
Raw Scancodes
KEY_SCAN_* are the raw BIOS scancodes (without KEY_EXT_FLAG): KEY_SCAN_ESC, KEY_SCAN_TAB, KEY_SCAN_SPACE, KEY_SCAN_F1 .. KEY_SCAN_F12, KEY_SCAN_HOME, KEY_SCAN_END, KEY_SCAN_PGUP, KEY_SCAN_PGDN, KEY_SCAN_INSERT, KEY_SCAN_DELETE, KEY_SCAN_UP, KEY_SCAN_DOWN, KEY_SCAN_LEFT, KEY_SCAN_RIGHT, KEY_SCAN_CTRL_LEFT, KEY_SCAN_CTRL_RIGHT, KEY_SCAN_CTRL_END, KEY_SCAN_CTRL_HOME, KEY_SCAN_ALT_TAB.
Raw Key Codes
A raw key code names one physical key: its set-1 make code (1-127), plus KEY_RAW_EXT (0x80) for keys sent behind an 0xE0 prefix (gray arrows and navigation keys, right Ctrl and Alt, keypad Enter). KEY_RAW_CODE(scancode, extended) builds one. The code is the same whatever modifier is held; letters, digits, and punctuation use their KEY_SCAN_* / BIOS scancode. Used by the held-key table (platformKeyIsDown, gameKeyIsDown) and RawKeyEventT.
| Define | Value | Key |
|---|---|---|
KEY_RAW_LSHIFT, KEY_RAW_RSHIFT |
0x2A, 0x36 |
Left / right Shift |
KEY_RAW_LCTRL, KEY_RAW_RCTRL |
0x1D, 0x9D |
Left / right Ctrl |
KEY_RAW_LALT, KEY_RAW_RALT |
0x38, 0xB8 |
Left / right Alt |
KEY_RAW_F11, KEY_RAW_F12 |
0x57, 0x58 |
F11, F12 |
KEY_RAW_UP, KEY_RAW_DOWN |
0xC8, 0xD0 |
Gray arrows (the keypad’s are 0x48, 0x50) |
KEY_RAW_LEFT, KEY_RAW_RIGHT |
0xCB, 0xCD |
|
KEY_RAW_KP_ENTER |
0x9C |
Keypad Enter |
KEY_RAW_PAUSE |
0xC5 |
Pause (a press and a release at once) |
KEY_RAW_COUNT |
256 |
Size of the held-key snapshot |
RawKeyEventT: uint8_t scancode (the make code), bool extended, bool down, bool repeat (a typematic repeat of a key already down), int32_t modifiers (KEY_MOD_* from the held-key table after the event, with KEY_MOD_LSHIFT 0x02 and KEY_MOD_RSHIFT 0x01 apart).
ASCII Key Codes
| Define | Value | Description |
|---|---|---|
KEY_ESCAPE |
0x1B |
Escape |
KEY_ENTER |
0x0D |
Enter / Return |
KEY_TAB |
0x09 |
Tab |
KEY_SPACE |
0x20 |
Space |
KEY_BACKSPACE |
0x08 |
Backspace |
KEY_ASCII_DEL |
0x7F |
ASCII DEL (not KEY_DELETE) |
KEY_ASCII_PRINT_FIRST |
0x20 |
First printable character |
KEY_ASCII_PRINT_LAST |
0x7E |
Last printable character |
KEY_ASCII_FIRST |
0x01 |
First key that is a character (KEY_IS_ASCII(key): 0x01 .. 0xFF, not an extended key; it raises onKeyPress) |
KEY_ASCII_LAST |
0xFF |
Last key that is a character |
KEY_CTRL_A |
0x01 |
Ctrl+A (BIOS reports Ctrl+letter as 0x01..0x1A) |
KEY_CTRL_C |
0x03 |
Ctrl+C |
KEY_CTRL_V |
0x16 |
Ctrl+V |
KEY_CTRL_X |
0x18 |
Ctrl+X |
KEY_CTRL_Z |
0x1A |
Ctrl+Z |
2.3. dvxCur.h — Cursor Definitions
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec. The AND mask selects transparency (1 = transparent, 0 = opaque) and the XOR data selects black vs. white for opaque pixels.
2.3.1. Cursor Shape IDs
| Define | Value | Description |
|---|---|---|
CURSOR_ARROW |
0 |
Standard arrow (hot spot at tip) |
CURSOR_RESIZE_H |
1 |
Horizontal resize (left/right arrows) |
CURSOR_RESIZE_V |
2 |
Vertical resize (up/down arrows) |
CURSOR_RESIZE_DIAG_NWSE |
3 |
NW-SE diagonal resize |
CURSOR_RESIZE_DIAG_NESW |
4 |
NE-SW diagonal resize |
CURSOR_BUSY |
5 |
Hourglass (wait) |
CURSOR_CROSSHAIR |
6 |
Crosshair for placement |
CURSOR_NO_DROP |
7 |
Circle with a slash: a drag cannot drop here (see dvxDragCursorSet) |
CURSOR_COUNT |
8 |
Total number of cursor shapes |
2.4. dvxFont.h — Bitmap Font Data
2.4.1. dvxFont.h — Embedded Bitmap Font Data
Raw glyph bitmaps for the standard 8x16 VGA ROM font covering the full IBM Code Page 437 character set (256 glyphs). Compiled in as a static const array, avoiding a real-mode INT 10h call at startup.
Glyph format: 1 bit per pixel, 8 pixels wide, MSB = leftmost pixel. Each glyph occupies 16 consecutive bytes (one byte per scanline). The 8-pixel width means per-scanline rendering never needs bit shifting across byte boundaries.
CP437 covers:
-
0-31 — Smiley, card suits, arrows, notes (classic extended ASCII glyphs)
-
32-126 — Printable ASCII
-
127 — House glyph
-
128-175 — Accented Latin letters, currency, fractions
-
176-223 — Box-drawing characters (essential for chrome gadgets)
-
224-254 — Greek letters, math symbols, super/subscripts
-
255 — Non-breaking space
2.4.2. Data
font8x16
const uint8_t array of FONT_NUM_CHARS * FONT_CHAR_HEIGHT = 4096 bytes containing the packed 1bpp glyph bitmaps, in ASCII code order. It has external linkage with a single definition in the core library (the translation unit that defines DVX_FONT_IMPL before including dvxFont.h); every other includer sees only the extern declaration.
2.4.3. Constants
| Define | Value | Description |
|---|---|---|
FONT_NUM_CHARS |
256 |
Glyph count (full 8-bit character range) |
FONT_CHAR_WIDTH |
8 |
Fixed glyph width in pixels (defined in dvxTypes.h) |
FONT_CHAR_HEIGHT |
16 |
Glyph height in pixels (defined in dvxTypes.h) |
FONT_SYS_ASCENT |
12 |
Rows above the baseline (letters sit on row 11) |
FONT_SYS_UNDERLINE_Y |
15 |
Underline and accelerator mark row (the cell’s last) |
FONT_SYS_STRIKE_Y |
8 |
Strike-through row (the middle of the lower-case letters) |
FONT_SYS_LINE_THICK |
1 |
Rows in those lines |
2.5. dvxText.h — Fonts
The font families DVX draws with: "System", the built-in 8x16 font, and the families in the FONTS folder. Which families that folder holds depends on the install — Setup puts in the base set (DejaVu Sans, Sans Mono, and Serif) or none, and the More Fonts add-on the rest — and dvxFontOpen of a family that is not there gives the system font. A family has up to four faces (regular, bold, italic, bold italic), each a .DFN file holding the face at the pixel sizes it was made at; the files are made on the build host from TrueType, Type 1, and bitmap fonts (src/tools/mkfont.c), so DVX only copies bitmaps. A face’s file holds its screen sizes, their smoothed copies, and its print sizes together (the base set’s have 25 to 100 pixels for printing; FONT_SIZES_MAX sizes at most). More files of the same family and style (up to four in all) add the sizes the face lacks, each size read from the file it came in: a program’s own copy of a face adds its sizes that way.
dvxFontOpen gives a BitmapFontT every text call draws and measures with. It never scales: it picks the face’s size nearest the one asked for. A style the family has no face for is made from the nearest face — bold by thickening each stroke a column (two from 24 pixels), italic by slanting a column per four rows — and the font’s flags say so. Every character of code page 437 draws: what a face lacks is filled in when the font loads. Box drawing, block, and shade characters are drawn to fill the character cell (the pitch, or the digit 0’s width) so lines join, also in place of a face’s own when its file asks; other characters come from FONT_FALLBACK_FAMILY (FONT_FALLBACK_FIXED for a fixed-pitch face, centered in its pitch) at the nearest size and the same style, or from the system font when that family is not installed.
A face can also hold a size smoothed (anti-aliased): each pixel one of four levels, from none to full, drawn as that blend of the text color and what is under it. When smoothing is on (dvxFontSetSmooth) such a size opens smoothed, with FONT_FLAG_GRAY set and FONT_GRAY_BPP bits per pixel; other sizes and faces stay 1-bit. At 8 bits per pixel there are no colors to blend: the pixels of FONT_GRAY_HALF and more are drawn, the rest not.
Fonts are shared and counted: the same family, size, and style opened again is the same font, and dvxFontClose gives one up. A few fonts no one holds stay loaded so reopening them is quick. A font’s memory belongs to DVX, not to the program that opened it. The family list is read from DVX_FONTS_DIR the first time it is needed, and again after dvxFontRescan or a change to what is installed (platformInstalledChanged: a package with fonts going in or out), so fonts a package installs appear without restarting DVX; a file that cannot be read is logged and skipped. The family names dvxFontFamilyName gives stay valid while DVX runs.
2.5.1. Fonts a Program Carries
A program can carry fonts of its own: font resources in its file (DVX_RES_FONT, dvxRes.h; a .res line "name font FILE.DFN", or a BASIC project’s Fonts), .DFN files it adds with dvxFontAddFile, or fonts in memory (dvxFontAddMemory). The shell adds a program’s font resources when it loads the program and forgets them when the program ends; whatever a program adds itself goes then too. Its fonts are its own: every call here works for the running program (the app id the shell sets while a program’s code runs, window callbacks included), and other programs never see them.
The program sees the installed families and its own. Where it has a family that is installed too, its faces and sizes come first, and the installed family fills in the styles and sizes it lacks: a program that carries DejaVu Sans Bold at 36 pixels gets that size from its own file and every other size and style of DejaVu Sans from the installed fonts. The nearest size is chosen from both together. Fonts built for a program that carries fonts are cached for it alone; programs that carry none share every font.
A .DFN carries its notice (where the font came from and its copyright notices) and its license, so they go wherever the font goes; dvxFontLicence reads them, and the Font dialog shows them (its License button).
2.5.2. Constants
| Define | Value | Description |
|---|---|---|
DVX_FONTS_DIR |
"FONTS" |
The fonts folder (dvxPlat.h), in SHARED and in the user folder |
FONT_SYSTEM_FAMILY |
"System" |
The built-in 8x16 font’s family name |
FONT_FALLBACK_FAMILY |
"DejaVu Sans" |
Fills what a proportional face lacks |
FONT_FALLBACK_FIXED |
"DejaVu Sans Mono" |
Fills what a fixed-pitch face lacks |
FONT_SIZES_MAX |
64 |
The most sizes a face has (dvxFontSizes) |
2.5.3. dvxFontOpen
BitmapFontT *dvxFontOpen(const char *family, int32_t pixelSize, uint32_t style);
The font of family at the size nearest pixelSize in style. NULL, "", and a family there is none of give the system font (16 pixels; plain, it is dvxFont8x16 itself, drawn by the fast fixed paths).
| Parameter | Description |
|---|---|
family |
Family name (any case) |
pixelSize |
Size wanted, in pixels |
style |
FONT_STYLE_BOLD and / or FONT_STYLE_ITALIC pick the face; FONT_STYLE_UNDERLINE and / or FONT_STYLE_STRIKE are kept in the font’s style, and every text call draws its lines with it |
Returns: The font, or NULL when out of memory. Close it with dvxFontClose.
2.5.4. dvxFontClose
void dvxFontClose(BitmapFontT *font);
Give up a font dvxFontOpen gave. NULL and fonts not from dvxFontOpen (dvxFont8x16, the application context’s font) are ignored.
2.5.5. dvxFontFamilyCount / dvxFontFamilyName
int32_t dvxFontFamilyCount(void);
const char *dvxFontFamilyName(int32_t index);
The number of families (the system font’s included) and family index: "System" first, then the others in alphabetical order. dvxFontFamilyName returns NULL for an index out of range.
2.5.6. dvxFontFamilyOf
const char *dvxFontFamilyOf(const BitmapFontT *font);
The family a font was opened from; "System" for the system font and for fonts not from dvxFontOpen.
2.5.7. dvxFontFamilyFixed
bool dvxFontFamilyFixed(const char *family);
True when every face of family is fixed-pitch (the system font is; a family there is none of is not): the families an editor or terminal can use.
2.5.8. dvxFontSizes
int32_t dvxFontSizes(const char *family, uint32_t style, int32_t *sizes, int32_t max);
The pixel sizes family has in style — those of the face the style is drawn from — smallest first, into sizes (at most max).
Returns: How many sizes there are (which may be more than max); 0 for a family there is none of.
2.5.9. dvxFontRetain
BitmapFontT *dvxFontRetain(BitmapFontT *font);
Hold font once more, for keeping a font someone else opened (each hold is given up with dvxFontClose). Returns font; fonts not from dvxFontOpen are returned as they are.
2.5.10. dvxFontRescan
void dvxFontRescan(void);
Read the FONTS folder again on the next call, after fonts were added or removed. The fonts no one holds are unloaded; open fonts stay valid. DVX does the same by itself after what is installed changes (platformInstalledChanged, which installing or removing a package calls), so a program needs it only for font files it copied into the folder itself.
2.5.11. dvxFontSetSmooth / dvxFontSmooth / dvxFontSmoothBegin / dvxFontRebuildStep
void dvxFontSetSmooth(bool smooth);
bool dvxFontSmooth(void);
void dvxFontSmoothBegin(bool smooth);
bool dvxFontRebuildStep(void);
Smooth fonts where their face has the size smoothed, or stop; dvxFontSmooth says which it is (off at first). The fonts open are built again in place: the same BitmapFontT pointers with new glyphs and a new serial, so code that keeps measurements of a font compares its serial too, and text is laid out again. The fonts no one holds are unloaded. dvxFontSetSmooth builds them all before it returns; dvxFontSmoothBegin only switches and marks them, and each dvxFontRebuildStep builds one of them again (15-150 ms a font), false when none is left (the fonts before the fonts with lines, which copy them). Programs call dvxSetFontSmoothing (dvxApp.h) instead, which follows the user’s choice and the screen’s depth and builds the fonts a frame at a time.
2.5.12. dvxFontAddFile / dvxFontAddMemory
bool dvxFontAddFile(int32_t owner, const char *path);
bool dvxFontAddMemory(int32_t owner, const void *data, uint32_t length, const char *name);
Add the .DFN at path, or held in data (length bytes, copied at once; name names it in the log), as a face of its family for program owner (an app id; 0 for every program, as SETUP.EXE adds the fonts it carries). Families added for owner 0 are seen by every program and kept by dvxFontRescan.
Returns: True when added; false, logged, when the font cannot be read, calls its family "System", or brings no size that owner’s face of that family and style lacks (a second file of a face adds its sizes to it).
2.5.13. dvxFontAddResources
int32_t dvxFontAddResources(int32_t owner, const char *path);
Add every font resource (DVX_RES_FONT) of the file at path — a program, a library, or a resource file — for owner. The shell calls it for each program it loads.
Returns: How many fonts were added.
2.5.14. dvxFontRemoveOwner
void dvxFontRemoveOwner(int32_t owner);
Forget every face added for owner (the shell does when a program ends; for 0, the faces added for every program, the installed ones staying). Its fonts no one holds are unloaded; a held one stays as it is until it is closed.
2.5.15. dvxFontLicence
char *dvxFontLicence(const BitmapFontT *font);
The texts that go with the face font was built from: its notice — the family and style, the fonts it was converted from, and their copyright notices — then a blank line and its license. ASCII with CR LF line ends; malloc’d (the caller frees it).
Returns: The texts; NULL for the system font, and when the font’s file cannot be read.
2.5.16. Code Page 437 and Unicode
extern const uint16_t dfnCp437[DFN_CHAR_COUNT];
int32_t dfnFromUnicode(uint32_t code);
int32_t dfnTextFromUnicode(uint32_t code);
uint32_t dfnTextToUnicode(uint8_t ch);
Declared in dvxFontFmt.h. DVX text and its fonts are code page 437. dfnCp437[c] is the Unicode code point of character c’s glyph (0 for none), so the characters below 32 are the smileys, card suits, and arrows the fonts draw for them; dfnFromUnicode is the character whose glyph a code point is, -1 for none. For text, dfnTextFromUnicode and dfnTextToUnicode keep ASCII (line ends, tabs, and the other controls included) as itself and map the rest through code page 437; dfnTextFromUnicode is -1 for a code point DVX has no character for. The JSON library reads and writes Unicode this way, and BASIC’s ChrW$ and AscW are these two.
2.6. dvxFlow.h — Flowing Text
A flow is a document built in order: runs of text, each in a font and a color, line breaks, and paragraph starts, each with an alignment. dvxFlowLayout wraps it to a width into lines; dvxFlowPaint draws them. The RichLabel widget is a flow with calls around it; the RichEdit widget lays out each of its paragraphs as a flow and edits through the offset calls below.
Layout is greedy: a word and the spaces after it go on the line when the word fits, else the line ends and the word starts the next one, without its leading spaces. A word wider than a whole line is broken where the line is full. A line is as tall as the tallest font on it — the largest ascent above one baseline and the deepest descent below it — and its trailing spaces neither count toward its width (alignment) nor draw (an underline would show them). A word may go on across runs (a style changed inside it, or punctuation in a run of its own); it wraps as one word, and only a word wider than a whole line breaks, where the line is full. Underline and strike-through come with a run’s font (dvxText.h).
Offsets number the text added from 0, each run’s characters after the one before (breaks and paragraphs take none); an offset is the caret before that character. Each line owns the offsets from its start to the next line’s start — the spaces it wrapped at included — and the last line those to the text’s end. Text that is all empty lays out as one empty line in its first run’s font, so an empty paragraph keeps a height and a caret place.
2.6.1. Constants
| Define | Value | Description |
|---|---|---|
FLOW_ALIGN_LEFT |
0 |
Paragraph alignment |
FLOW_ALIGN_CENTER |
1 |
|
FLOW_ALIGN_RIGHT |
2 |
|
FLOW_COLOR_DEFAULT |
0xFFFFFFFF |
A run in the color dvxFlowPaint is given |
FLOW_WIDTH_NATURAL |
INT32_MAX |
dvxFlowLayout’s width for the natural size: lines break only at breaks and paragraphs |
2.6.2. Functions
| Function | Description |
|---|---|
TextFlowT *dvxFlowCreate(void) |
An empty flow (one left-aligned paragraph); NULL out of memory. |
void dvxFlowDestroy(flow) |
Free it and give up the fonts it holds. NULL is ignored. |
void dvxFlowClear(flow) |
Empty it again. |
bool dvxFlowAddText(flow, text, len, font, color) |
Add len bytes of text (len below 0: up to the NUL) in font and color (0x00RRGGBB or FLOW_COLOR_DEFAULT). The flow holds the font (dvxFontRetain) and copies the text. |
bool dvxFlowAddBreak(flow) |
Start a new line in the same paragraph (two in a row make an empty line, as tall as the font before it). |
bool dvxFlowAddParagraph(flow, align) |
Start a new paragraph aligned FLOW_ALIGN_*; it ends the line before it when that has text, and on an empty flow it sets the first paragraph’s alignment. |
int32_t dvxFlowLayout(flow, width) |
Lay it out width pixels wide; returns its height. The same width again costs nothing. |
int32_t dvxFlowHeight(flow) / dvxFlowWidth(flow) |
The last layout’s height and widest line. |
void dvxFlowPaint(flow, d, ops, x, y, defaultFg) |
Draw the lines that meet the clip rectangle, top-left at x, y, aligned within the width laid out at (the widest line’s for FLOW_WIDTH_NATURAL); FLOW_COLOR_DEFAULT runs in defaultFg (a packed pixel). Transparent. |
void dvxFlowPaintSel(flow, d, ops, x, y, defaultFg, selStart, selEnd, selFg, selBg) |
dvxFlowPaint with offsets selStart to selEnd selected: their text in selFg on selBg (packed pixels), a line’s undrawn trailing spaces too. |
int32_t dvxFlowTextLength(flow) |
The characters added (the last offset). |
int32_t dvxFlowLineCount(flow) |
The last layout’s lines. |
int32_t dvxFlowLineOf(flow, offset) |
The line the caret before offset is on (a line’s end is the next line’s start); -1 with no lines. |
int32_t dvxFlowLineStart(flow, line) |
The offset a line starts at; past the last line, the text’s length. |
void dvxFlowLineBox(flow, line, &y, &h) |
A line’s top and height. |
void dvxFlowCaret(flow, offset, &x, &y, &h) |
The caret before offset: its x, and its line’s top and height (alignment included). |
int32_t dvxFlowHitTest(flow, x, y) |
The offset nearest a point: on the line at y (the first or last beyond them), the character boundary nearest x. A line that wrapped at a space ends before it. |
TextFlowT *flow = dvxFlowCreate();
BitmapFontT *bold = dvxFontOpen("DejaVu Sans", 14, FONT_STYLE_BOLD);
dvxFlowAddText(flow, "Warning: ", -1, bold, DVX_RGB(160, 0, 0));
dvxFlowAddText(flow, "the disk is almost full.", -1, &ctx->font, FLOW_COLOR_DEFAULT);
dvxFontClose(bold);
dvxFlowLayout(flow, 200);
dvxFlowPaint(flow, d, ops, x, y, fg);
2.7. dvxPal.h — 8-bit Palette
2.7.1. dvxPal.h — 256-Color Palette for 8-bit Mode
| Range | Purpose |
|---|---|
0-215 |
6x6x6 color cube — uniformly distributed RGB (6 levels per channel: 0, 51, 102, 153, 204, 255). Index = r*36 + g*6 + b. |
216-231 |
16-step gray ramp for smooth gradients |
232-239 |
Dedicated UI chrome colors (highlight, shadow, title bar, desktop) |
240-255 |
Reserved (black) |
The cube layout enables O(1) color lookup: snapping an RGB triplet to the nearest cube vertex is integer division by 51. The gray ramp and chrome slots hold colors that need exact values not available in the cube.
2.7.2. Layout Constants
| Define | Value | Description |
|---|---|---|
PAL_ENTRIES |
256 |
Palette size |
PAL_CHANNELS |
3 |
Bytes per entry (R, G, B) |
PAL_CUBE_LEVELS |
6 |
Levels per channel in the color cube |
PAL_CUBE_STEP |
51 |
Distance between cube levels (255 / 5) |
PAL_CUBE_ROUND |
25 |
Rounding bias when snapping to a cube level |
PAL_CUBE_COUNT |
216 |
Number of cube entries (indices 0-215) |
PAL_GREY_FIRST |
216 |
First gray-ramp index |
PAL_GREY_COUNT |
16 |
Gray-ramp entries |
PAL_GREY_STEP |
17 |
Distance between gray levels (255 / 15) |
PAL_CHROME_FIRST |
232 |
First chrome color index |
PAL_RESERVED_FIRST |
240 |
First reserved (black) index |
2.7.3. Chrome Color Indices
| Define | Value | Description |
|---|---|---|
PAL_CHROME_HIGHLIGHT |
232 |
White (bevel highlight) |
PAL_CHROME_SHADOW |
233 |
Dark gray (bevel shadow) |
PAL_CHROME_ACTIVE_BG |
234 |
Navy (focused title bar) |
PAL_CHROME_INACTIVE_BG |
235 |
Gray (unfocused title bar) |
PAL_CHROME_DESKTOP |
236 |
Steel blue (desktop) |
PAL_CHROME_SELECTION |
237 |
Navy (selection highlight) |
PAL_CHROME_TEXT |
238 |
Black (text) |
PAL_CHROME_WHITE |
239 |
Bright white |
2.7.4. Inline Functions
dvxPalSet
static inline void dvxPalSet(uint8_t *pal, int32_t idx, uint8_t r, uint8_t g, uint8_t b);
Store one RGB entry at index idx of a PAL_ENTRIES * PAL_CHANNELS palette buffer.
dvxGeneratePalette
static inline void dvxGeneratePalette(uint8_t *pal);
Populate a 768-byte (256 * 3) RGB buffer with the default DVX 8-bit palette. Called once at init in 8-bit mode to program the DAC.
| Parameter | Description |
|---|---|
pal |
Output RGB buffer (768 bytes) |
dvxNearestPalEntry
static inline uint8_t dvxNearestPalEntry(const uint8_t *pal, uint8_t r, uint8_t g, uint8_t b);
Find the nearest palette entry for an RGB color using minimum Euclidean distance. Two-phase: snap to color cube vertex (O(1)), then scan gray ramp and chrome entries (216-239) for a closer match. Called by packColor() in 8-bit mode.
| Parameter | Description |
|---|---|
pal |
Active 768-byte RGB palette |
r, g, b |
Color components (0-255) |
Returns: Palette index (0-239) of the nearest match.
2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI (or, for a card with no linear framebuffer, its bank window), system RAM backbuffer allocation, pixel format discovery, and color packing.
2.8.1. videoInit
int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.
| Parameter | Description |
|---|---|
d |
Display context to initialize |
requestedW/H |
Desired screen resolution |
preferredBpp |
Preferred bits per pixel (8, 15, 16, or 32) |
Returns: 0 on success, negative on failure.
2.8.2. videoShutdown
void videoShutdown(DisplayT *d);
Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.
| Parameter | Description |
|---|---|
d |
Display context to shut down |
2.8.3. packColor
uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);
Pack an RGB triplet into the display’s native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.
| Parameter | Description |
|---|---|
d |
Display context (provides pixel format) |
r, g, b |
Color components (0-255) |
Returns: Native pixel value suitable for direct framebuffer write.
2.8.4. packColorRgb
uint32_t packColorRgb(const DisplayT *d, uint32_t rgb);
packColor of a DVX color 0x00RRGGBB: the form a widget’s fgColor or bgColor, or a theme’s color, takes on the screen. The top byte is ignored. DVX_RGB(r, g, b) makes such a color from its channels (0-255), and DVX_RGB_RED, DVX_RGB_GREEN, and DVX_RGB_BLUE take them apart (dvxVideo.h).
| Parameter | Description |
|---|---|
d |
Display context (provides pixel format) |
rgb |
The color, &HRRGGBB |
Returns: Native pixel value suitable for direct framebuffer write.
2.8.5. unpackColor
void unpackColor(const DisplayT *d, uint32_t color, uint8_t *r, uint8_t *g, uint8_t *b);
Reverse of packColor — decode a native pixel value to 8-bit RGB components. For direct-color modes, reverses the shift/mask arithmetic and widens a field narrower than 8 bits by repeating its bits, so black and full channels come back exact (white in a 16-bit mode reads as 255, 255, 255). For 8-bit mode, looks up the palette entry at the given index.
| Parameter | Description |
|---|---|
d |
Display context |
color |
Packed native pixel value |
r, g, b |
Output: color components (0-255) |
2.8.6. convertColor / convertPixels
uint32_t convertColor(const PixelFormatT *from, const DisplayT *d, uint32_t color);
uint8_t *convertPixels(const PixelFormatT *from, const DisplayT *d, const uint8_t *src, int32_t w, int32_t h, int32_t srcPitch, int32_t *outPitch);
Pixels kept in the display format — a picture from dvxLoadImage, a drawing, a packed color — are in the format the screen had when they were made. After dvxChangeVideoMode to another color depth they must be converted (or made again) before they are drawn or drawn on: drawing the old bytes in the new format reads and writes past the buffer when the depth grew. Keep the DisplayT format a buffer was made in with it, and when it differs from the display’s (memcmp of the two PixelFormatT), convert. Each pixel is unpacked as from has it and packed as d has it; 8-bit values are read through DVX’s own palette, the one every 8-bit desktop mode shows. dvxChangeVideoMode paints every window again afterwards (onPaint), the natural place to check. Widgets convert what they keep themselves (WGT_METHOD_ON_FORMAT_CHANGE: Canvas, Image, ImageButton, and the Terminal’s colors), and DVX converts window icons. A program that keeps pictures of its own in the display format (icons it drew with rectCopy, say) converts them, or drops and decodes them again, the same way: a private widget class of its own can take WGT_METHOD_ON_FORMAT_CHANGE, as Program Manager’s icon view does.
convertColor gives the pixel value color of the format from, packed in d’s format. convertPixels gives a new w x h buffer in d’s format (free it) with every pixel of src (the format from, srcPitch bytes a row) converted, its pitch in *outPitch; NULL when out of memory or the size is empty.
| Parameter | Description |
|---|---|
from |
The format the pixels are in (the display’s format when they were made) |
d |
The display whose format they go to |
color |
A pixel value in from’s format |
src |
The pixels (w x h, srcPitch bytes a row) |
outPitch |
Output: the new buffer’s bytes a row |
2.8.7. setClipRect
void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);
Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. It replaces the clip there was (it does not narrow it); the caller must save and restore the clip rect around scoped operations.
| Parameter | Description |
|---|---|
d |
Display context |
x, y, w, h |
Clip rectangle in d’s own coordinates (its buffer’s: the screen for the back buffer, the content area for a window’s content display, the drawing for a canvas’s), cut to the buffer (0, 0, d->width, d->height) |
2.9. dvxDraw.h — Layer 2: Drawing Primitives
All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display’s backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.
2.9.1. drawInit
void drawInit(BlitOpsT *ops, const DisplayT *d);
Populate a BlitOpsT with the correct span functions for the display’s pixel depth (1, 2, or 4 bytes per pixel). Must be called once after videoInit(). For any other pixel size the span functions are left NULL so misuse fails loudly instead of drawing with the wrong depth.
| Parameter | Description |
|---|---|
ops |
BlitOpsT to populate |
d |
Initialized display context |
2.9.2. rectFill
void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
x, y, w, h |
Rectangle to fill |
color |
Packed pixel color |
2.9.3. rectCopy
void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing. Rows are copied with ops->spanCopy (rep movsd on DOS); when both pitches equal the row size the whole block is one span. Source and destination must not overlap.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
dstX, dstY |
Destination position in backbuffer |
srcBuf |
Source pixel buffer |
srcPitch |
Source buffer bytes per row |
srcX, srcY |
Origin within source buffer |
w, h |
Rectangle dimensions to copy |
2.9.4. rectCopyGrayscale
void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
Copy a rectangle with grayscale conversion. Each pixel’s RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance. In 8-bit mode the gray is mapped back to the nearest palette entry (cached per index); on an 8-bit display without a palette the indices are copied unchanged.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
dstX, dstY |
Destination position |
srcBuf, srcPitch |
Source buffer and pitch |
srcX, srcY |
Source origin |
w, h |
Rectangle dimensions |
2.9.5. rectCopyTransparent
void rectCopyTransparent(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h, uint32_t keyColor);
Copy with color-key transparency. Pixels matching keyColor are skipped, letting the destination show through. Used to draw image buttons and icons with transparent backgrounds.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
dstX, dstY |
Destination position |
srcBuf, srcPitch |
Source buffer and pitch |
srcX, srcY |
Source origin |
w, h |
Rectangle dimensions |
keyColor |
Packed color treated as transparent |
2.9.6. drawBevel
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);
Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with the face color unless face is BEVEL_NO_FILL (0 is packed black and fills normally).
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
x, y, w, h |
Outer bevel rectangle |
style |
Bevel colors and width |
2.9.7. drawChar
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);
Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Character position |
ch |
Character to draw |
fg, bg |
Foreground and background packed colors |
opaque |
true = fill background, false = transparent |
Returns: Advance width (charWidth for the system font, the glyph’s advance for a loaded font).
2.9.8. drawText
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
Draw a null-terminated string. Equivalent to drawTextN over the whole string (one background span per scanline, character-range clipping).
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Start position |
text |
Null-terminated string |
fg, bg |
Foreground and background packed colors |
opaque |
true = fill background, false = transparent |
2.9.9. drawTextN
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);
Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Start position |
text |
Character buffer (not required to be null-terminated) |
count |
Number of characters to render |
fg, bg |
Foreground and background packed colors |
opaque |
true = fill background, false = transparent |
2.9.10. drawTextScaled
void drawTextScaled(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t scale, uint32_t fg);
Draw a null-terminated string scale times as large: every glyph pixel becomes a scale x scale block in fg, and the background shows through. For titles and banners in the 8x16 font (DVX Setup’s title, the Welcome window). The text is textWidth(font, text) * scale wide and font->charHeight * scale tall. Each run of set pixels in a glyph row is one rectFill, which clips. Scale 1 is drawText; a scale below 1 draws nothing. BASIC: FontScale on a form or PictureBox (Print, TextWidth, TextHeight).
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Top-left corner |
text |
Null-terminated string |
scale |
Size multiple (1 = normal) |
fg |
Packed text color |
2.9.11. textWidth
int32_t textWidth(const BitmapFontT *font, const char *text);
Return the pixel width of a null-terminated string: the sum of its characters' advances (for the system font strlen(text) * charWidth).
| Parameter | Description |
|---|---|
font |
Bitmap font |
text |
Null-terminated string |
Returns: Width in pixels.
2.9.12. textWidthN
int32_t textWidthN(const BitmapFontT *font, const char *text, int32_t count);
The pixel width of the first count characters of text (0 when count is 0 or less): where a caret after them goes, how much of a line fits.
| Parameter | Description |
|---|---|
font |
Bitmap font |
text |
Characters (not required to be null-terminated) |
count |
How many to measure |
Returns: Width in pixels.
2.9.13. textWrap
typedef void (*TextWrapLineFnT)(const char *line, int32_t lineLen, int32_t lineIndex, void *userData);
int32_t textWrap(const BitmapFontT *font, const char *text, int32_t maxW, TextWrapLineFnT lineFn, void *userData);
Word-wrap text into lines no wider than maxW pixels: each line takes as many characters as fit, breaking at the last space; a word wider than maxW is cut where the line is full (a line always holds at least one character). Spaces at the start of a line are dropped. CR, LF, and CR LF end a line, or make an empty one (length 0). lineFn gets each line in order: its first character (the line is not null-terminated), its length, and its index from 0. Message boxes and the Label’s WordWrap wrap their text with it.
| Parameter | Description |
|---|---|
font |
Bitmap font |
text |
Null-terminated string |
maxW |
Widest line, in pixels |
lineFn |
Called for each line (NULL: only count them) |
userData |
Passed to lineFn |
Returns: The number of lines.
2.9.14. drawTextStyled
void drawTextStyled(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t style, uint32_t fg, uint32_t bg, bool opaque);
void drawTextStyledN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t style, uint32_t fg, uint32_t bg, bool opaque);
Draw text (drawText, drawTextN) with the lines style asks for: FONT_STYLE_UNDERLINE at the font’s underlineY and FONT_STYLE_STRIKE at its strikeY, lineThick rows, as wide as the text, in fg. Bold and italic are the font’s own (dvxFontOpen); those bits of style are ignored here.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Top-left of the line |
text |
Text (drawTextStyledN: count characters of it) |
style |
FONT_STYLE_UNDERLINE and / or FONT_STYLE_STRIKE |
fg, bg |
Foreground and background packed colors |
opaque |
true = fill background, false = transparent |
2.9.15. accelParse
char accelParse(const char *text);
Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
| Parameter | Description |
|---|---|
text |
Text with optional & accelerator marker |
Returns: Lowercase accelerator character, or 0 if none.
2.9.16. drawTextAccel
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
Draw text with & accelerator markers. The character after & is marked with the font’s underline (underlineY; the system font’s last row) across its advance to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Start position |
text |
Text with & markers |
fg, bg |
Foreground and background packed colors |
opaque |
true = fill background, false = transparent |
2.9.17. textWidthAccel
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
Measure text width excluding & markers (so "&File" measures as the width of "File").
| Parameter | Description |
|---|---|
font |
Bitmap font |
text |
Text with optional & markers |
Returns: Width in pixels.
2.9.18. drawMaskedBitmap
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);
Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
x, y |
Screen position |
w, h |
Bitmap dimensions |
andMask |
AND transparency mask (one uint16_t per row) |
xorData |
XOR color data |
fgColor, bgColor |
Cursor foreground and background packed colors |
2.9.19. drawTermRow
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);
Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. The attribute byte uses the CGA layout described by the TERM_ATTR_* constants.
| Define | Value | Description |
|---|---|---|
TERM_ATTR_FG_MASK |
0x0F |
Foreground palette index (low nibble) |
TERM_ATTR_BG_SHIFT |
4 |
Shift of the background index |
TERM_ATTR_BG_MASK |
0x07 |
Background palette index (bits 4-6, after shifting) |
TERM_ATTR_BLINK |
0x80 |
Blink attribute |
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
x, y |
Row start position |
cols |
Number of columns |
lineData |
Packed ch/attr byte pairs (2 bytes per cell) |
palette |
16-entry packed color palette |
blinkVisible |
false = hide blinking characters |
cursorCol |
Column for inverted text cursor (-1 = none) |
2.9.20. drawArrowGlyph
void drawArrowGlyph(DisplayT *d, const BlitOpsT *ops, int32_t cx, int32_t cy, int32_t rows, ScrollArrowDirE dir, uint32_t color);
Draw a solid triangle of rows rows (base 2 * rows - 1 pixels) pointing in direction dir (ScrollArrowUpE/DownE/LeftE/RightE), centered on (cx, cy). The shared direction glyph for scrollbar arrows, spinners, tab scroll buttons, navigation bars, and sort indicators.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
cx, cy |
Center of the glyph |
rows |
Number of rows (tip to base) |
dir |
Direction the tip points |
color |
Fill color |
2.9.21. drawScrollbar
void drawScrollbar(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, ScrollbarOrientE orient, int32_t x, int32_t y, int32_t length, int32_t barW, int32_t thumbPos, int32_t thumbSize);
Paint a complete scrollbar from a ready-made thumb geometry: the sunken trough, an arrow button (drawScrollbarArrowButton) at each end, and a raised thumb thumbPos pixels past the first arrow button. The window scrollbars, the widget scrollbars, and wmDrawScrollbarAt (which computes the thumb from a scroll state) all paint through it.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
orient |
ScrollbarVerticalE (arrows up and down) or ScrollbarHorizontalE (arrows left and right) |
x, y |
Top-left corner of the bar |
length |
Bar length in pixels along its axis, both arrow buttons included |
barW |
Bar thickness, which is also the side of the square arrow buttons (SCROLLBAR_WIDTH for the standard look) |
thumbPos |
Thumb offset in pixels from the end of the first arrow button |
thumbSize |
Thumb length in pixels; 0 or less draws no thumb |
2.9.22. drawScrollbarArrow
void drawScrollbarArrow(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t x, int32_t y, int32_t size, ScrollArrowDirE dir);
Draw the arrow glyph of a scrollbar button whose top-left is (x, y) and side is size, using drawArrowGlyph centered in the button with colors->scrollbarFg.
2.9.23. drawScrollbarArrowButton
void drawScrollbarArrowButton(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t x, int32_t y, int32_t size, ScrollArrowDirE dir);
Draw one complete arrow button of a scrollbar, as the scrollbar painter does at each end of a bar: a size x size raised button (1px bevel on colors->scrollbarBg) whose top-left is (x, y), with the drawScrollbarArrow glyph pointing dir centered on it. The BASIC DrawScrollArrow method draws with it.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
x, y |
Top-left corner of the button |
size |
Side of the square button in pixels |
dir |
Direction the arrow points (ScrollArrowUpE/DownE/LeftE/RightE) |
2.9.24. drawFocusRect
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
x, y, w, h |
Focus rectangle bounds |
color |
Dot color (packed) |
2.9.25. drawFocusRectDots
typedef void (*DrawDotFnT)(void *ctx, int32_t x, int32_t y);
void drawFocusRectDots(int32_t x, int32_t y, int32_t w, int32_t h, DrawDotFnT fn, void *ctx);
The dots drawFocusRect draws, one fn call each and without clipping: the one definition of the pattern, for drawing it somewhere other than the back buffer. drawFocusRect plots them in the back buffer inside the clip rect; the BASIC DrawFocusRect method of forms and PictureBoxes sets them on the canvas.
2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter’s algorithm), flush to LFB.
2.10.1. dirtyListInit
void dirtyListInit(DirtyListT *dl);
One-time initialization: empty the list and preallocate its rect array to the soft cap (128) so adding rects never allocates. Calling it again keeps the existing array.
| Parameter | Description |
|---|---|
dl |
Dirty list to initialize |
2.10.2. dirtyListAdd
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);
Enqueue a dirty rectangle (empty rects are ignored). At the soft cap the list is merged first; if it is still full, every rect (including the new one) is collapsed into one bounding rect. A rect is never dropped while the list has any storage: if the array cannot be allocated it is unioned into the first entry.
| Parameter | Description |
|---|---|
dl |
Dirty list |
x, y, w, h |
Dirty rectangle in screen coordinates |
2.10.3. dirtyListMerge
void dirtyListMerge(DirtyListT *dl);
Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
| Parameter | Description |
|---|---|
dl |
Dirty list to merge |
2.10.4. dirtyListClear
void dirtyListClear(DirtyListT *dl);
Reset the dirty list to empty (sets count to 0).
| Parameter | Description |
|---|---|
dl |
Dirty list to clear |
2.10.5. flushRect
void flushRect(DisplayT *d, const RectT *r);
Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
| Parameter | Description |
|---|---|
d |
Display context |
r |
Rectangle to flush |
2.10.6. rectIntersect
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);
Compute the intersection of two rectangles.
| Parameter | Description |
|---|---|
a, b |
Input rectangles |
result |
Output: intersection rectangle (valid only when return is true) |
Returns: true if the rectangles overlap, false if disjoint.
2.11. dvxWm.h — Layer 4: Window Manager
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
2.11.2. Window Lifecycle
wmCreateWindow
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
| Parameter | Description |
|---|---|
stack |
Window stack |
d |
Display context |
title |
Window title text |
x, y |
Initial position |
w, h |
Initial outer frame dimensions |
resizable |
true = allow user resize |
Returns: Pointer to new WindowT, or NULL on failure.
2.11.3. Z-Order and Focus
wmRaiseWindow
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);
Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list for repaint marking |
idx |
Stack index of window to raise |
2.11.4. Geometry
wmUpdateContentRect
void wmUpdateContentRect(WindowT *win);
Recompute contentX/Y/W/H from the window’s outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
| Parameter | Description |
|---|---|
win |
Window to update |
wmReallocContentBuf
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);
Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward. An empty content area (contentW or contentH 0 or below, as at a window’s smallest size with scroll bars) gets no buffer (contentBuf NULL). Returns 0, or -1 when memory runs out.
| Parameter | Description |
|---|---|
win |
Window to reallocate |
d |
Display context (for bytes-per-pixel) |
Returns: 0 on success, -1 on allocation failure.
wmMinWindowSize
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);
Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
| Parameter | Description |
|---|---|
win |
Window |
minW, minH |
Output: minimum width and height |
wmClampWindowPos
void wmClampWindowPos(const WindowT *win, int32_t *x, int32_t *y, int32_t screenW, int32_t screenH);
Clamp a candidate window position so the window’s title bar stays reachable on a screenW x screenH screen. Shared by mouse dragging (wmDragMove) and keyboard move.
| Parameter | Description |
|---|---|
win |
Window being moved |
x, y |
In/out: candidate position, clamped in place |
screenW, screenH |
Screen size |
2.11.5. Menu Bar
wmAddMenuBar
MenuBarT *wmAddMenuBar(WindowT *win);
Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window: a second call replaces the first, freeing it with its menus.
| Parameter | Description |
|---|---|
win |
Window to add menu bar to |
Returns: Pointer to the new MenuBarT, or NULL when out of memory (the window keeps the bar it had). wmAddMenu takes the NULL and returns NULL, and the item calls do nothing for a NULL menu, so a chain of them needs no checks.
wmDestroyMenuBar
void wmDestroyMenuBar(WindowT *win, const DisplayT *d);
Free the menu bar and reclaim the content area. The content buffer is reallocated to fit the grown content area.
| Parameter | Description |
|---|---|
win |
Window to remove menu bar from |
d |
Display context; pass NULL only during window teardown |
wmAddMenu
MenuT *wmAddMenu(MenuBarT *bar, const char *label);
Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File") and keeps MAX_MENU_LABEL - 1 (31) characters.
| Parameter | Description |
|---|---|
bar |
Menu bar (NULL: none is made) |
label |
Menu label text |
Returns: Pointer to the new MenuT to populate with items, or NULL when out of memory or bar is NULL.
wmInsertMenu
MenuT *wmInsertMenu(MenuBarT *bar, int32_t idx, const char *label);
Put a dropdown menu on the menu bar at idx (0: first; cut to the menus there are), as wmAddMenu does at the end. A visible menu put on a bar whose menus are all hidden shows the bar again: the caller lays the window out again (dvxResizeWindow with the same size), as for wmRemoveMenu.
| Parameter | Description |
|---|---|
bar |
Menu bar |
idx |
Where on the bar |
label |
Menu label text |
Returns: Pointer to the new MenuT to populate with items, or NULL when out of memory.
wmMenuBarLayout
void wmMenuBarLayout(WindowT *win);
Lay out the titles of win’s menu bar (MenuT.barX and barW, relative to the window) when a change left them stale: MenuBarT.positionsDirty, set when a menu is added, removed, renamed, hidden, or shown. Nothing otherwise, so it is cheap to call. Whatever reads barX or barW calls it first — the paint, the mouse’s hit tests, a menu opening below its title — so a change counts at its next use, not only after the next paint.
wmMenuBarShown
bool wmMenuBarShown(const WindowT *win);
True when the window shows its menu bar: it has one, with no menus yet or with one that is visible (MenuT.visible). A bar whose menus are all hidden takes no room, as if there were none: no strip, no clicks, no keys.
wmMenuContains
bool wmMenuContains(const MenuT *tree, const MenuT *menu);
True when menu is tree itself or one of its submenus, at any depth; false for NULL.
wmAddMenuItem
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);
Append a clickable item to a menu. The id is passed to the window’s onMenu callback when selected. The label keeps MAX_MENU_LABEL - 1 (31) characters. This call and the other wmAdd item calls (check, radio, separator) do nothing for a NULL menu or when out of memory; the menus' and items' arrays grow as needed (no count limit).
| Parameter | Description |
|---|---|
menu |
Menu to append to |
label |
Item label (supports & markers) |
id |
Application-defined command ID |
wmAddMenuCheckItem
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);
Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
| Parameter | Description |
|---|---|
menu |
Menu to append to |
label |
Item label |
id |
Command ID |
checked |
Initial checked state |
wmAddMenuRadioItem
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);
Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
| Parameter | Description |
|---|---|
menu |
Menu to append to |
label |
Item label |
id |
Command ID |
checked |
Initial checked state |
wmAddMenuSeparator
void wmAddMenuSeparator(MenuT *menu);
Insert a horizontal separator line. Separators are not interactive.
| Parameter | Description |
|---|---|
menu |
Menu to append separator to |
wmRemoveMenu
bool wmRemoveMenu(WindowT *win, MenuT *menu, const DisplayT *d);
Take one menu (a wmAddMenu result) off the window’s menu bar and free it with its items and submenus. Removing the last menu removes the bar, and the content buffer is reallocated for d as by wmDestroyMenuBar. The content area changes size when the bar goes, so the caller lays the window out again (dvxResizeWindow with the same size does it and fires onResize). The BASIC RemoveMenu method uses it.
| Parameter | Description |
|---|---|
win |
Window whose menu bar holds the menu |
menu |
The menu to remove |
d |
Display, for reallocating the content buffer when the bar goes |
Returns: true if the menu was on the bar.
A menu that may be open is closed first (dvxCloseMenu), and dvxMenuBarChanged afterwards keeps another open menu of the bar at its new place.
wmRemoveMenuItem
bool wmRemoveMenuItem(MenuT *menu, int32_t id);
Remove a menu item by command ID. Searches the menu’s items array and shifts remaining items down to close the gap. An item with a submenu (wmAddSubMenu: its id is -1) takes the submenu with it, freed. Close an open menu showing it first (dvxCloseMenu).
| Parameter | Description |
|---|---|
menu |
Menu to remove item from |
id |
Command ID to remove |
Returns: true if a matching item was found and removed.
wmClearMenuItems
void wmClearMenuItems(MenuT *menu);
Remove all items from a menu while preserving the menu itself on the menu bar, freeing the items' submenus. Use when rebuilding a menu’s contents dynamically (e.g. a recent-files submenu). Close an open menu showing it first (dvxCloseMenu): the open menu’s state points into the items.
| Parameter | Description |
|---|---|
menu |
Menu to empty |
wmMenuItemIsChecked
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);
Query the checked state of a menu item by command ID. Searches all menus in the bar.
| Parameter | Description |
|---|---|
bar |
Menu bar |
id |
Command ID to query |
Returns: true if checked.
wmMenuItemSetChecked
void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);
Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.
| Parameter | Description |
|---|---|
bar |
Menu bar |
id |
Command ID |
checked |
New checked state |
wmMenuItemSetEnabled
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);
Enable or disable a menu item by command ID, searching every menu of the bar and their submenus. A disabled item is grayed and cannot be chosen.
| Parameter | Description |
|---|---|
bar |
Menu bar |
id |
Command ID |
enabled |
true = enabled, false = grayed out |
wmMenuFindItemInMenu, wmMenuItemSetCheckedInMenu, wmMenuItemSetEnabledInMenu
MenuItemT *wmMenuFindItemInMenu(MenuT *menu, int32_t id);
void wmMenuItemSetCheckedInMenu(MenuT *menu, int32_t id, bool checked);
void wmMenuItemSetEnabledInMenu(MenuT *menu, int32_t id, bool enabled);
The same for a standalone menu (a context menu made by wmCreateMenu, with no menu bar): find an item by command ID in menu and its submenus, at any depth (NULL when there is none, or menu is NULL); set its checked state (checking a radio item unchecks the others of its group); or enable or gray it. A NULL menu or an ID no item has does nothing.
wmMenuItemSetLabel
void wmMenuItemSetLabel(MenuItemT *item, const char *label);
Give an item a new label, written as wmAddMenuItem takes it: & before the accelerator letter, and the key text after a tab ("&Open\tCtrl+O"). The accelerator follows the new label; the item’s ID, type, and state stay. An open popup shows the new label the next time it is drawn. A NULL item or label does nothing.
wmAddSubMenu
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);
Create a cascading submenu attached to a parent menu (an item whose id is -1). The child MenuT is heap-allocated and belongs to its item: it is freed with the menu that holds the item (with the window’s menu bar when the window is destroyed, by wmRemoveMenu or wmDestroyMenuBar, or by wmFreeMenu for a wmCreateMenu menu) or when the item is removed (wmRemoveMenuItem, wmClearMenuItems).
| Parameter | Description |
|---|---|
parentMenu |
Parent menu to attach submenu to |
label |
Submenu label text |
Returns: Pointer to the child MenuT, or NULL on allocation failure or a NULL parentMenu.
wmCreateMenu
MenuT *wmCreateMenu(void);
Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().
Returns: Pointer to the new MenuT, or NULL when out of memory.
wmFreeMenu
void wmFreeMenu(MenuT *menu);
Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively. Call dvxCloseMenu first when it may be open (a context menu shown, or one of its submenus): the open menu’s state points into it.
| Parameter | Description |
|---|---|
menu |
Menu to free (NULL does nothing) |
2.11.6. Scrollbars
wmAddVScrollbar
ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
Attach a vertical scrollbar to the right edge of the window’s content area. Shrinks contentW by SCROLLBAR_WIDTH pixels. If the window already has a vertical scrollbar, that ScrollbarT is reused (same pointer) and reset to the new range with value = min. A negative pageSize is treated as 0.
| Parameter | Description |
|---|---|
win |
Window |
min, max |
Scroll value range |
pageSize |
Visible portion (controls thumb size) |
Returns: Pointer to the window’s ScrollbarT, or NULL on allocation failure.
wmAddHScrollbar
ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels. If the window already has a horizontal scrollbar, that ScrollbarT is reused and reset. A negative pageSize is treated as 0.
| Parameter | Description |
|---|---|
win |
Window |
min, max |
Scroll value range |
pageSize |
Visible portion |
Returns: Pointer to the window’s ScrollbarT, or NULL on allocation failure.
2.11.7. Drawing
wmDrawChrome
void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo. When the window has a content buffer, the content well (content area and scrollbar strips) is not painted: follow with wmDrawContent and wmDrawScrollbars, as the compositor does.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font for title text |
colors |
Color scheme |
win |
Window to draw chrome for |
clipTo |
Dirty rectangle to clip drawing to |
wmDrawContent
void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);
Blit the window’s content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing); rows are copied with ops->spanCopy.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
win |
Window |
clipTo |
Dirty rectangle |
wmDrawScrollbars
void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
win |
Window |
clipTo |
Dirty rectangle |
wmDrawMinimizedIcons
void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);
Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window’s content with a beveled border.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
stack |
Window stack |
clipTo |
Dirty rectangle |
wmDrawWindowIcon
void wmDrawWindowIcon(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowT *win, int32_t x, int32_t y);
Draw one window’s icon at (x, y), ICON_TOTAL_SIZE square, as the minimized icon strip shows it: the window’s icon image when it has one, else a scaled thumbnail of its content (or the face color) in a beveled border. The window switcher (Alt+Tab) draws it too.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
win |
Window |
x, y |
Top-left corner on the screen |
wmDrawScrollbarAt
void wmDrawScrollbarAt(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, ScrollbarOrientE orient, int32_t x, int32_t y, int32_t length, int32_t scrollPos, int32_t visibleItems, int32_t totalItems);
Draw a standalone scrollbar of either orientation at the given screen coordinates, without a ScrollbarT struct. A vertical bar (ScrollbarVerticalE) is SCROLLBAR_WIDTH wide and length tall with up and down arrow buttons; a horizontal one (ScrollbarHorizontalE) is length wide and SCROLLBAR_WIDTH tall with left and right arrow buttons. Thumb size and position are computed from scrollPos / visibleItems / totalItems with the window scrollbars' rule; there is no thumb when everything is visible. wmVScrollbarAtClick maps a click on the bar to a new scrollPos. The BASIC DrawScrollBar method draws with it.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
orient |
ScrollbarVerticalE or ScrollbarHorizontalE |
x, y |
Screen position (top-left corner of the bar) |
length |
Bar length in pixels along its axis, both arrow buttons included |
scrollPos |
Current first visible item index |
visibleItems |
Visible item count (for thumb size) |
totalItems |
Total item count |
wmDrawVScrollbarAt
void wmDrawVScrollbarAt(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t x, int32_t y, int32_t h, int32_t scrollPos, int32_t visibleItems, int32_t totalItems);
wmDrawScrollbarAt for a vertical bar h tall. Used by popup lists (dropdown, combobox) that need a scrollbar inline within a popup overlay.
| Parameter | Description |
|---|---|
d |
Display context |
ops |
Blit operations vtable |
colors |
Color scheme |
x, y |
Screen position (top of scrollbar) |
h |
Bar height in pixels, both arrow buttons included |
scrollPos |
Current top visible item index |
visibleItems |
Visible item count (for thumb size) |
totalItems |
Total item count |
wmVScrollbarAtClick
int32_t wmVScrollbarAtClick(int32_t length, int32_t offset, int32_t scrollPos, int32_t visibleItems, int32_t totalItems);
Apply a click on a scrollbar drawn by wmDrawScrollbarAt (either orientation) or wmDrawVScrollbarAt with the same length and scroll state; offset is the click’s offset along the bar from its start: down from the top of a vertical bar, right from the left end of a horizontal one. Only that offset matters, so the function serves both orientations. Returns the new scrollPos: the arrow buttons step one item, the trough steps a page (visibleItems) toward the click, and the thumb leaves the position unchanged. The result is clamped to 0 .. totalItems - visibleItems. The thumb comes from the same geometry the paint uses, so a click always matches what is drawn.
wmVScrollbarZoneAt
ScrollHitE wmVScrollbarZoneAt(int32_t length, int32_t offset, int32_t scrollPos, int32_t visibleItems, int32_t totalItems);
The part of such a bar under offset (ScrollHitE), as wmVScrollbarAtClick would act on it, without acting: for repeating a held arrow or trough press (widgetScrollbarPressStep).
2.11.8. Hit Testing
wmHitTest
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);
Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
| Parameter | Description |
|---|---|
stack |
Window stack |
mx, my |
Screen coordinates |
hitPart |
Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc. |
Returns: Stack index of hit window, or -1 for desktop.
wmWindowById
WindowT *wmWindowById(const WindowStackT *stack, int32_t id);
The window on the stack whose id is id, or NULL when there is none (it was destroyed). Code that must find a window again later keeps its id rather than its pointer.
wmResizeEdgeHit
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);
Determine which edge(s) of a window’s border zone are targeted for resize. A corner reaches along both of its edges up to the groove drawn near it (16 pixels from the corner), so a press anywhere on the frame between a corner and its grooves resizes diagonally. wmHitTest reports no resize edges for a maximized window.
| Parameter | Description |
|---|---|
win |
Window |
mx, my |
Screen coordinates |
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
wmMinimizedIconHit
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);
Hit-test minimized icons at the bottom of the screen.
| Parameter | Description |
|---|---|
stack |
Window stack |
d |
Display context |
mx, my |
Screen coordinates |
Returns: Stack index of the minimized window, or -1.
2.11.9. Drag and Resize
wmDragBegin
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);
Begin a window drag operation. Records the mouse offset from the window origin. A maximized window is not dragged (no drag begins), as in Windows 3.1; wmDragMove also leaves a window that was maximized during the drag where it is.
| Parameter | Description |
|---|---|
stack |
Window stack |
idx |
Stack index of window to drag |
mouseX/Y |
Current mouse position |
wmDragMove
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);
Update window position during an active drag. Dirties both old and new positions.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
mouseX/Y |
Current mouse position |
screenW/H |
Screen dimensions (for clamping) |
wmDragEnd
void wmDragEnd(WindowStackT *stack);
End the current drag operation. Clears dragWindow state.
| Parameter | Description |
|---|---|
stack |
Window stack |
wmResizeBegin
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);
Begin a window resize operation. Records which edge(s) are being dragged.
| Parameter | Description |
|---|---|
stack |
Window stack |
idx |
Stack index |
edge |
Bitmask of RESIZE_xxx flags |
mouseX/Y |
Current mouse position |
wmResizeMove
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);
Update window dimensions during an active resize. Enforces the window’s least size (wmMinWindowSize: its chrome, gadgets, and menu bar; MIN_WINDOW_W/H are only tiling’s and cascading’s floor) and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
d |
Display context |
mouseX/Y |
In/out: mouse position (clamped on return) |
2.11.10. Scrollbar Interaction
wmScrollbarClick
ScrollHitE wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, ScrollbarOrientE orient, int32_t mx, int32_t my);
Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb: wmScrollbarZone) and either adjusts the value immediately or begins a thumb drag. Returns the part hit (ScrollHitNoneE when nothing), so the caller can repeat an arrow or trough step while the button is held, as the event loop does: SCROLL_REPEAT_DELAY_MS after the press, then every SCROLL_REPEAT_RATE_MS, while the pointer stays on that part.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
idx |
Stack index of window |
orient |
ScrollbarVerticalE or ScrollbarHorizontalE |
mx, my |
Click screen coordinates |
wmScrollbarDrag
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);
Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
mx, my |
Current mouse position |
wmScrollbarZone
ScrollHitE wmScrollbarZone(const WindowT *win, ScrollbarOrientE orient, int32_t mx, int32_t my);
The part of win’s scrollbar (orient) under the screen point mx, my, reduced to the offset along the bar, as wmScrollbarClick would act on it, without acting. ScrollHitNoneE when the window has no such bar, nothing to scroll, or no track.
| Parameter | Description |
|---|---|
stack |
Window stack |
2.11.11. Minimize / Maximize / Restore
wmMaximize
void wmMaximize(DirtyListT *dl, const DisplayT *d, WindowT *win);
Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
| Parameter | Description |
|---|---|
dl |
Dirty list |
d |
Display context |
win |
Window to maximize |
wmMinimize
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);
Minimize a window. Hides the window and shows an icon at the bottom of the screen.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
win |
Window to minimize |
wmRestore
void wmRestore(DirtyListT *dl, const DisplayT *d, WindowT *win);
Restore a maximized window to its pre-maximize geometry.
| Parameter | Description |
|---|---|
dl |
Dirty list |
d |
Display context |
win |
Maximized window to restore |
wmRestoreMinimized
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
Restore a minimized window (show it again, remove the icon) and raise it to the top. It does NOT change focus, so no onBlur/onFocus fires here; applications use dvxRestoreWindow, which also focuses the window with correct callback attribution.
| Parameter | Description |
|---|---|
stack |
Window stack |
dl |
Dirty list |
d |
Display context |
win |
Minimized window to restore |
2.11.12. Minimized Icon Layout
wmMinimizedIconPos
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);
Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
| Parameter | Description |
|---|---|
d |
Display context |
index |
Ordinal index of the minimized icon |
x, y |
Output: screen position |
wmMinimizedIconRect
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);
Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
| Parameter | Description |
|---|---|
stack |
Window stack |
d |
Display context |
y, h |
Output: vertical extent of icon area |
2.11.13. Miscellaneous
wmSetTitle
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);
Set the window title and dirty the title bar for repaint.
| Parameter | Description |
|---|---|
win |
Window |
dl |
Dirty list |
title |
New title text |
wmSetIconData
void wmSetIconData(WindowT *win, uint8_t *pixels, int32_t w, int32_t h, int32_t pitch);
Install an icon that is already in display pixel format (for example from dvxLoadImage). Takes ownership of the malloc’d pixel buffer; it is freed with the window or when the next icon replaces it.
| Parameter | Description |
|---|---|
win |
Window |
pixels |
Display-format pixels (ownership transfers to the window) |
w, h |
Icon size in pixels |
pitch |
Bytes per row |
2.12. dvxApp.h — Layer 5: Application API
The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.
2.12.1. AppContextT
Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller’s stack or statically.
Fields applications and the shell commonly read (all others are internal state):
| Field | Description |
|---|---|
DisplayT display |
Screen display context (use dvxGetDisplay) |
WindowStackT stack |
Window stack (z-order, focus, drag state) |
int32_t mouseX, mouseY |
Current mouse position |
int32_t mouseButtons |
Current MOUSE_* button bitmask |
int32_t mouseWheel |
Wheel delta this frame (positive = down) |
int32_t keyModifiers |
Current BIOS shift state (KEY_MOD_*) |
int32_t keyFocusWinId |
Window the held-key table was last cleared for (0 = none; internal) |
int32_t wheelDirection |
1 = normal, -1 = reversed |
int32_t wheelStep |
Lines per wheel notch (1-10, default 3) |
PlatformTicksT dblClickTicks |
Double-click interval in platformClock ticks |
int32_t dblClickMs |
Double-click interval in milliseconds (as given to dvxSetMouseConfig) |
int32_t mouseAccel |
Acceleration threshold last applied (MOUSE_ACCEL_*) |
int32_t mouseMickeys |
Mickeys per 8 pixels last applied (MOUSE_SPEED_DEFAULT at start) |
uint32_t charHeightRecip |
16.16 reciprocal of font.charHeight (popup row mapping) |
WindowT *modalWindow |
If non-NULL, only this window receives input; set it with dvxModalBegin and dvxModalEnd |
frameGuard |
Host hook that runs each frame of dvxUpdate (see dvxUpdate); NULL: frames run as they are |
int32_t dispatchDepth |
Callback nesting depth; destroys are deferred while > 0 |
uint32_t windowsCreated |
Windows created by dvxCreateWindow so far (the shell compares it before and after a close request to see whether the app showed a prompt) |
WinCloseReasonE closeReason |
Why the window whose onClose runs is closing (dvxRequestWindowClose); WinCloseUserE outside one |
int32_t currentAppId |
App charged for allocations and callbacks (0 = shell) |
bool busy |
Busy cursor shown and input blocked |
bool fontSmoothing |
Text smoothing wanted (dvxSetFontSmoothing; on at start) |
idleCallback / idleCtx |
Called instead of yielding when a frame had no events |
onCtrlEsc, onF1, onTitleChange |
Shell hooks (with their ctx pointers) |
VideoModeInfoT *videoModes |
stb_ds array of settable modes |
char wallpaperPath[] |
Current wallpaper source path (empty = none) |
WallpaperModeE wallpaperMode |
Stretch, tile, or center |
dvxSetMouseConfig programs the mouse speed and acceleration into the platform layer, which re-applies them after every mouse driver reset; mouseAccel and mouseMickeys only record the last values applied (for dvxMouseToPrefs and settings pages).
2.12.2. Initialization and Shutdown
dvxInit
int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.
| Parameter | Description |
|---|---|
ctx |
Application context to initialize |
requestedW/H |
Desired screen resolution |
preferredBpp |
Preferred bits per pixel |
Returns: 0 on success, negative on failure.
dvxShutdown
void dvxShutdown(AppContextT *ctx);
Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().
| Parameter | Description |
|---|---|
ctx |
Application context |
dvxChangeVideoMode
int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.
| Parameter | Description |
|---|---|
ctx |
Application context |
requestedW/H |
New resolution |
preferredBpp |
New bits per pixel |
Returns: 0 on success, -1 on failure (old mode restored).
2.12.3. Event Loop
dvxRun
void dvxRun(AppContextT *ctx);
Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.
| Parameter | Description |
|---|---|
ctx |
Application context |
dvxUpdate
bool dvxUpdate(AppContextT *ctx);
Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames). When the context’s frameGuard hook is set, the frame runs through it: bool frameGuard(AppContextT *ctx, bool (*frame)(AppContextT *ctx)) calls frame(ctx) and returns what it returns, and may set a recovery point around it. The shell does on its own task: a program whose code crashes in such a frame (or calls exit()), in the loop of a dialog box open there, say, is ended, the frame returns as if done (the result is whether the GUI still runs), and the frames below it, the box’s loop among them, go on.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: false when the GUI wants to exit.
2.12.4. Window Management
Every dvx* function that takes a WindowT pointer accepts NULL as a no-op (functions that return a status return failure).
dvxCreateWindow
WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied. A position where another window’s top-left corner already is moves down and right by the title bar’s height, again while that place is taken too (starting over once at that distance from the screen’s top-left corner), so a new window never hides one exactly under it; then the window is kept on the screen (one larger than the screen goes to 0, 0). Its open sound plays a frame later, unless it is a modal window.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title: MAX_TITLE_LEN - 1 (127) characters are kept; NULL for none |
x, y |
Screen position |
w, h |
Outer frame dimensions |
resizable |
true = allow user resize |
Returns: Pointer to new WindowT, or NULL when out of memory.
dvxCreateWindowCentered
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);
dvxCreateWindow at the position that centers the window on the screen (so it too moves down and right when another window’s corner is already there).
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title |
w, h |
Outer frame dimensions |
resizable |
true = allow user resize |
Returns: Pointer to new WindowT, or NULL when out of memory.
dvxDestroyWindow
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);
Destroy a window, free all its resources, and dirty its former region.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to destroy |
dvxRaiseWindow
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);
Raise a window to the top of the Z-order and give it focus.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to raise |
dvxGetFocusedWindow
WindowT *dvxGetFocusedWindow(const AppContextT *ctx);
The window with the focus: the active window, the one the keyboard goes to. It may be another program’s window (or a dialog box over the program’s own), so compare its appId with the program’s, or the pointer with its own windows. BASIC: Screen.ActiveForm.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: The focused window, or NULL when no window has the focus.
dvxLowerWindow
void dvxLowerWindow(AppContextT *ctx, WindowT *win);
Put a window behind every other one, its open menus and keyboard move or size mode closed first. When it had the focus, the window now on top gets it. No-op for NULL or a window pending destruction. The BASIC Form.ZOrder vbSendToBack uses it.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to lower |
dvxRequestWindowClose
void dvxRequestWindowClose(AppContextT *ctx, WindowT *win, WinCloseReasonE reason);
Ask a window to close exactly as its close box, Alt+F4, and the system menu’s Close do. The window’s onClose runs (under the window’s app ID) and decides — a save prompt may keep the window open; a window without onClose is destroyed. While onClose runs, ctx->closeReason is reason, so it can tell why it is asked; afterwards it is what it was before. A clean frame is composited first so an open menu is erased before onClose shows a dialog. When no dispatch is in progress the window may already be freed on return, so look it up again by its id rather than using the pointer. NULL does nothing. The shell’s Exit DVX sequence uses this to ask each app to close.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to ask to close |
reason |
Why: WinCloseUserE (the close box, Alt+F4, and the system menu’s Close pass it), WinCloseExitE (Exit DVX is closing every program), or WinCloseRequestE (the shell asked the program to close: another program’s close request, shellRequestAppClose, or a screen saver’s end). A BASIC form’s QueryUnload gets it as UnloadMode: vbFormControlMenu, vbAppWindows, or vbAppTaskManager. |
dvxRestoreWindow
void dvxRestoreWindow(AppContextT *ctx, WindowT *win);
Restore a minimized window (or un-maximize a maximized one), then raise and focus it. Focus-change callbacks (onBlur of the old window, onFocus of the restored one) run under their own app’s ID. No-op for NULL or a window pending destruction.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to restore |
dvxFitWindow
void dvxFitWindow(AppContextT *ctx, WindowT *win);
Resize a window to exactly fit its widget tree’s computed minimum size (plus chrome), never smaller than the window manager’s minimum window size. Used for dialog boxes and fixed-layout windows.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to fit |
dvxFitWindowW
void dvxFitWindowW(AppContextT *ctx, WindowT *win);
Resize window width only to fit widget tree’s minimum width (plus chrome), never below the window manager’s minimum width.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to fit |
dvxFitWindowH
void dvxFitWindowH(AppContextT *ctx, WindowT *win);
Resize window height only to fit widget tree’s minimum height (plus chrome), never below the window manager’s minimum height.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to fit |
dvxResizeWindow
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);
Programmatically resize a window to the specified outer dimensions, shifting it so it stays on screen. A size smaller than the window’s frame fits in (wmMinWindowSize) becomes the smallest it does, as a drag stops there. The content buffer is reallocated and onResize fires at once; the repaint waits for the next frame.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to resize |
newW, newH |
New outer frame dimensions |
dvxMoveWindow
void dvxMoveWindow(AppContextT *ctx, WindowT *win, int32_t x, int32_t y);
Move a window’s frame so its top-left corner is at x, y (screen coordinates), keeping its size, as dragging its title bar does: the title bar stays reachable (wmClampWindowPos: the top on the screen, the title bar above the bottom edge, at least DRAG_MIN_VISIBLE pixels across on it), the old and new places are repainted at the next composite, and a maximized window that moves is no longer maximized. The content buffer is untouched (no onResize, no onPaint). No-op for NULL or a window pending destruction. The keyboard’s Move (the system menu) uses it. BASIC programs move a form with its Left and Top properties and its Move method.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to move |
x, y |
New screen position of the frame’s top-left corner |
dvxMinimizeWindow
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);
Minimize a window (show as icon at bottom of screen). A modal window (WindowT.modal, or the modal window) is never minimized: it would take the input with it into an icon. Its minimize gadget is not drawn, and its system menu’s Minimize is gray.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to minimize |
dvxMaximizeWindow
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);
Maximize a window (expand to fill screen or maxW/maxH). Any window, a not resizable one too, as Windows' ShowWindow does (BASIC’s WindowState = vbMaximized on a fixed form); the user’s ways to maximize (the gadget, a title-bar double-click, the system menu’s Maximize) are a resizable window’s only, and the system menu’s Restore puts any maximized window back. dvxCascadeWindows and the dvxTileWindows calls move a window that is not resizable but keep its size.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to maximize |
dvxHideWindow
void dvxHideWindow(AppContextT *ctx, WindowT *win);
Hide a window without destroying it. Marks the exposed region dirty. A modal window stops being modal (as with dvxModalEnd).
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to hide |
dvxModalBegin, dvxModalEnd
void dvxModalBegin(AppContextT *ctx, WindowT *win);
void dvxModalEnd(AppContextT *ctx, WindowT *win);
dvxModalBegin makes win the modal window (ctx->modalWindow: only it takes input), keeping the window it takes over from in win->modalPrev, and marks it a modal window while it is (WindowT.modal: no minimize gadget, no open or close sound); dvxModalEnd ends that, giving back the WindowT.modal the window had before dvxModalBegin (a window that stays open gets its minimize gadget and sounds back; a dialog box that set the flag itself keeps it) and repainting its title bar, and every dvxModalBegin needs its dvxModalEnd. The dialog boxes, BASIC’s modal forms, and the Printing window use them. Modal windows stack: when one stops being modal — with dvxModalEnd, or hidden, or destroyed (its program was ended, so its own dvxModalEnd never comes) — it leaves the stack wherever it is in it, its own WindowT.modal given back, and when it was the modal window, the newest one before it that can still take input (shown and not queued for destroy) is modal again. So a dialog box over another keeps the outer one modal after it, whatever ends it, and one ended out of order leaves the newer one modal. A window begun again is first taken out of the stack. dvxModalEnd on a window that is not modal does nothing. Ctrl+Esc still works while a modal window is up: the window the shell’s Ctrl+Esc hook brings forward (the Task Manager) is made modal over it in turn, and the window that was modal is modal again when it closes. When no modal window is left under it (the dialog’s program was ended from the Task Manager), it is an ordinary window again, its own WindowT.modal (and its minimize gadget) given back.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
The modal window |
2.12.5. Invalidation
dvxInvalidateRect
void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);
Put a sub-region of a window’s content area back on the screen at the next composite, from the window’s content buffer as it is. onPaint is not called: draw into the buffer first (dvxContentDisplay), or use dvxInvalidateWindow, which calls onPaint. Coordinates are relative to the content area, not the screen; only the part inside the content area counts (nothing outside it, the chrome or another window, is touched).
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window |
x, y, w, h |
Dirty rectangle in content-relative coordinates |
dvxInvalidateWindow
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);
Repaint the whole window: onPaint runs at once, before this returns, with the whole content area as dirtyArea (a widget window lays out and paints all its widgets), and the window is composited at the next frame. Nothing happens for a window pending destruction.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to invalidate |
2.12.6. Window Properties
dvxSetTitle
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);
Set a window’s title text and dirty the title bar.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window |
title |
New title text |
dvxCloseMenu
void dvxCloseMenu(AppContextT *ctx, const MenuT *menu);
Close the open menu — a dropped-down menu of a menu bar or a context menu, with the submenus open from it — when it shows menu or a submenu of menu, at any depth, so menu can then be changed or freed. Call it before freeing a menu (wmFreeMenu), taking one off a menu bar (wmRemoveMenu, wmDestroyMenuBar), or putting items into or taking them out of one (wmAddMenuItem and the other wmAdd item calls, wmRemoveMenuItem, wmClearMenuItems): the open menu’s state points into it, and the compositor and the mouse read it while it is open. Nothing when no menu is open or the open one is another. A window’s destruction closes its open menu by itself. The BASIC form runtime calls it before every such change of a form’s menus (AddMenuItem, RemoveMenuItem, DestroyMenu, RemoveMenu, Load and Unload of an element, an item’s Visible, the form unloading).
| Parameter | Description |
|---|---|
ctx |
Application context |
menu |
The menu about to change or be freed |
dvxMenuBarChanged
void dvxMenuBarChanged(AppContextT *ctx, WindowT *win);
Tell DVX win’s menu bar changed: a menu put on it (wmAddMenu, wmInsertMenu) or taken off it (wmRemoveMenu); dvxSetMenuCaption, dvxSetMenuEnabled, and dvxSetMenuVisible call it themselves. The bar repaints, its titles are laid out again before they are next used (wmMenuBarLayout), and its open menu keeps its place: a menu put on the bar or taken off it before the open one moves its index (the depressed title, where Left and Right go from), and it closes when its menu is no longer on the bar or can no longer open.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
The window whose menu bar changed |
dvxSetMenuCaption
void dvxSetMenuCaption(AppContextT *ctx, WindowT *win, MenuT *menu, const char *caption);
Give a menu of win’s menu bar (a wmAddMenu result) a new title, written as wmAddMenu takes it (& before the access key): Alt and that letter open it from then on, and the bar repaints. On a menu of no bar (a context menu) only its label changes. The BASIC form runtime’s Caption of a top-level menu uses it.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
The window whose bar has the menu |
menu |
The menu |
caption |
New title text |
dvxSetMenuEnabled
void dvxSetMenuEnabled(AppContextT *ctx, WindowT *win, MenuT *menu, bool enabled);
Gray a menu of win’s menu bar (enabled false) or not. A grayed title does not open, by the mouse or by the keyboard (Alt and its letter, F10, Left and Right pass over it), and its open menu closes. The BASIC Enabled of a top-level menu uses it.
dvxSetMenuVisible
void dvxSetMenuVisible(AppContextT *ctx, WindowT *win, MenuT *menu, bool visible);
Show a menu of win’s menu bar on the bar or not. A hidden menu takes no room and no keys, its open menu closes, and dvxShowContextMenu can still show it (a popup menu kept on the bar). Hiding the last visible menu takes the bar away and showing one brings it back: the window keeps its size, so its content area grows or shrinks (onResize). The BASIC Visible of a top-level menu uses it.
dvxSetWindowButtons
void dvxSetWindowButtons(WindowT *win, struct WidgetT *defaultBtn, struct WidgetT *cancelBtn);
Give a window with widgets the default and cancel buttons a dialog box has (either may be NULL): Enter presses defaultBtn (usually OK) unless the focused control uses Enter itself (widgetUsesEnter: a button presses itself, an open drop-down list takes its choice, multi-line text gets a new line), and Escape presses cancelBtn (usually Cancel) once no menu or drop-down list is open. A disabled or hidden button is not pressed, and a button destroyed is forgotten. The keys reach the buttons through the widget layer’s onKey (widgetOnKey, installed by wgtInitWindow), so a window that replaces onKey calls widgetOnKey for them. The dialog boxes use it for their OK and Cancel; Control Panel, the DVX Demo’s Widget Demo, and the IDE’s Preferences, Project Properties, Menu Editor, and Find/Replace windows set theirs with it. BASIC forms have their own: a CommandButton’s Default and Cancel properties.
| Parameter | Description |
|---|---|
win |
The window |
defaultBtn |
Pressed by Enter (NULL: none) |
cancelBtn |
Pressed by Escape (NULL: none) |
dvxSetWindowEnabled
void dvxSetWindowEnabled(AppContextT *ctx, WindowT *win, bool enabled);
Enable or disable a whole window, as Windows' EnableWindow does (BASIC: Form.Enabled). A disabled window takes none of the user’s input: no click, mouse move, wheel, or key reaches its widgets or its onMouse, onKey, onKeyUp, onRawKey, or onScroll, and its frame does nothing either — a click on its title bar, borders, close box, or menu bar neither moves, sizes, closes, nor activates it, Alt+F4, F10, Alt+Space, its accelerators, and its widgets' access keys do nothing, Alt+Tab passes it over, and its icon is not restored by a double click. Its widgets paint disabled: the enabled chain (widgetIsEnabledChain) ends at the window. It still paints, its timers run, and the program can move, size, show, hide, raise, focus, and destroy it; Ctrl+Esc, F1, the screenshot keys, and the system-wide hotkeys still work while it is active. Disabling closes what the user had open on it (its menus, system menu, drop-down list, keyboard move or size) and takes the focus from its focused widget (onBlur), which gets it back (onFocus) when the window is enabled again; the window itself stays the active one. Read win->disabled for the state. A disabled window that is modal (dvxModalBegin) leaves the user nothing but Ctrl+Esc (Task Manager) until the program enables it.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
The window |
enabled |
true: the user’s input reaches it; false: none does |
dvxSetWindowIcon
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);
Load an icon for a window from an image file. The image is converted to the display format as dvxLoadImage converts it (each pixel packed to the nearest color the screen has, no dithering) and installed with wmSetIconData. After a change to another color depth (dvxChangeVideoMode) DVX converts the icon to the new format.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window |
path |
Image file path |
Returns: 0 on success, -1 on failure.
2.12.7. Accessors
dvxGetFont
const BitmapFontT *dvxGetFont(const AppContextT *ctx);
Get a pointer to the default font.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: Pointer to the active BitmapFontT.
dvxGetColors
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);
Get a pointer to the current color scheme.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: Pointer to the active ColorSchemeT.
dvxGetDisplay
DisplayT *dvxGetDisplay(AppContextT *ctx);
Get a pointer to the display context.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: Pointer to the DisplayT.
dvxGetBlitOps
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);
Get a pointer to the blit operations vtable.
| Parameter | Description |
|---|---|
ctx |
Application context |
Returns: Pointer to the active BlitOpsT.
dvxContentDisplay
void dvxContentDisplay(const AppContextT *ctx, const WindowT *win, DisplayT *out);
Fill *out with a copy of the display redirected at the window’s content buffer: backBuf points at win->contentBuf, width/height/pitch are the content size and pitch, and the clip rect covers the whole buffer. Pixel format fields come from the real display. Use it to draw straight into a window’s content buffer with the normal drawing primitives, for example from an onPaint handler that does not use widgets. Nothing drawn through the copy can reach the screen: only the platform layer reaches video memory, and only for the display it set up.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window whose content buffer is the target |
out |
Output: display context for drawing into the buffer |
static void onPaint(WindowT *win, RectT *dirty) {
DisplayT cd;
dvxContentDisplay(ctx, win, &cd);
rectFill(&cd, dvxGetBlitOps(ctx), 0, 0, win->contentW, win->contentH, dvxGetColors(ctx)->contentBg);
}
2.12.8. Color Scheme
dvxSetColor
void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);
Set a single color by ID. Repacks to native pixel format; every window is painted again at the next frame (once, however many colors change before it) and the whole screen composited.
| Parameter | Description |
|---|---|
ctx |
Application context |
id |
Color ID (ColorIdE) |
r, g, b |
RGB values (0-255) |
dvxGetColor
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);
Get a color’s RGB values by ID.
| Parameter | Description |
|---|---|
ctx |
Application context |
id |
Color ID (ColorIdE) |
r, g, b |
Output: RGB values |
dvxApplyColorScheme
void dvxApplyColorScheme(AppContextT *ctx);
Apply all colors from ctx->colorRgb[] at once (repack + full repaint).
| Parameter | Description |
|---|---|
ctx |
Application context |
dvxResetColorScheme
void dvxResetColorScheme(AppContextT *ctx);
Reset all colors to the built-in defaults and repaint.
| Parameter | Description |
|---|---|
ctx |
Application context |
dvxLoadTheme
bool dvxLoadTheme(AppContextT *ctx, const char *filename);
Load a theme file (INI format with [colors] section) and apply it through dvxColorsFromPrefs. Each color is a "name = r,g,b" key in [colors]; keys outside that section, unknown names, and malformed values are ignored, and channels are clamped to 0..255. A missing file returns false.
| Parameter | Description |
|---|---|
ctx |
Application context |
filename |
Path to theme INI file |
Returns: true on success.
dvxSaveTheme
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);
Save the current color scheme to a theme file (the keys dvxColorsToPrefs writes). When the file already exists its comments and other lines are kept and only the [colors] keys are updated. The new copy is written to a temporary file first and swapped in only when every write succeeded, so a failed save leaves the old theme intact.
| Parameter | Description |
|---|---|
ctx |
Application context |
filename |
Output file path |
Returns: true on success.
dvxColorsFromPrefs / dvxColorsToPrefs
bool dvxColorsFromPrefs(AppContextT *ctx, PrefsHandleT *h);
void dvxColorsToPrefs(const AppContextT *ctx, PrefsHandleT *h);
The [colors] section of an INI handle, the one place its keys are read and written: dvxLoadTheme / dvxSaveTheme, the shell at start (DVX.INI), and Control Panel (OK, and its Cancel snapshot in a prefsCreate handle) all use these. FromPrefs reads every "name = r,g,b" key (malformed ones ignored, channels clamped to 0..255), repaints only when a color changed and returns true when any color key was read. ToPrefs writes every color.
2.12.9. Wallpaper
dvxSetWallpaper
bool dvxSetWallpaper(AppContextT *ctx, const char *path);
Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper. If the image cannot be loaded, the current wallpaper and its saved path are kept and false is returned.
| Parameter | Description |
|---|---|
ctx |
Application context |
path |
Image file path, or NULL to clear |
Returns: true on success.
dvxSetWallpaperMode
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);
Change the wallpaper display mode; a loaded wallpaper is rendered again. With none loaded the mode is kept for the next one.
| Parameter | Description |
|---|---|
ctx |
Application context |
mode |
WallpaperStretchE, WallpaperTileE, or WallpaperCenterE |
dvxWallpaperFromPrefs / dvxWallpaperToPrefs
bool dvxWallpaperFromPrefs(AppContextT *ctx, PrefsHandleT *h);
void dvxWallpaperToPrefs(const AppContextT *ctx, PrefsHandleT *h);
The [desktop] wallpaper and mode keys of an INI handle (mode through prefsWallpaperChoices). FromPrefs applies them: a missing mode is WALLPAPER_MODE_DEFAULT and a missing wallpaper means none; the image is built again only when the path or mode differs from the current one. It returns false when the named image could not be loaded. ToPrefs writes the path (removes the key when there is none) and the mode.
2.12.10. Text Smoothing
dvxSetFontSmoothing
void dvxSetFontSmoothing(AppContextT *ctx, bool on);
Smooth text, or stop (ctx->fontSmoothing; on after dvxInit). Text is smoothed when on and the screen has more than 8 bits per pixel (dvxFontSmoothBegin, dvxText.h), in the faces and sizes that have a smoothed strike; dvxChangeVideoMode applies it again at the new depth. The fonts open are built again a font a frame (dvxUpdate calls dvxFontRebuildStep), and every window is laid out and painted again after the last.
dvxFontsFromPrefs / dvxFontsToPrefs
void dvxFontsFromPrefs(AppContextT *ctx, PrefsHandleT *h);
void dvxFontsToPrefs(const AppContextT *ctx, PrefsHandleT *h);
The [fonts] keys of an INI handle: smoothing (true or false; true when missing). FromPrefs applies it with dvxSetFontSmoothing; ToPrefs writes the setting. The shell uses FromPrefs at start and Control Panel both for OK and for its Cancel snapshot.
2.12.11. Mouse Configuration
dvxSetMouseConfig
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold, int32_t mickeyRatio, int32_t wheelStep);
Configure mouse behavior. Updates the in-memory AppContextT fields and programs any INT 33h settings that need driver-side adjustment.
| Parameter | Description |
|---|---|
ctx |
Application context |
wheelDir |
1 = normal, -1 = reversed |
dblClickMs |
Double-click speed in milliseconds (e.g. 500) |
accelThreshold |
Double-speed threshold in mickeys/sec (0 = don’t change) |
mickeyRatio |
Mickeys per 8 pixels (0 = don’t change, 8 = default speed) |
wheelStep |
Lines to scroll per wheel notch (1-10, default 3) |
The speed, acceleration, and wheel settings are re-applied by the platform layer after every mouse driver reset, so they survive a live video-mode change. The values are kept in AppContextT (wheelDirection, dblClickMs, mouseAccel, mouseMickeys, wheelStep).
dvxMouseFromPrefs / dvxMouseToPrefs
void dvxMouseFromPrefs(AppContextT *ctx, PrefsHandleT *h);
void dvxMouseToPrefs(const AppContextT *ctx, PrefsHandleT *h);
The [mouse] keys of an INI handle: wheel and acceleration (by name, through prefsWheelDirChoices and prefsAccelChoices), doubleclick (milliseconds), speed (mickeys per 8 pixels), and wheelspeed. FromPrefs applies them with dvxSetMouseConfig, defaults for missing keys (MOUSE_*_DEFAULT); ToPrefs writes the configuration in effect (an acceleration no choice has leaves that key alone). The shell uses FromPrefs at start and Control Panel both for OK and for its Cancel snapshot.
2.12.12. Input Entropy
dvxSetInputEntropyHook
typedef void (*DvxEntropyHookT)(const uint8_t *data, int32_t len);
void dvxSetInputEntropyHook(DvxEntropyHookT fn);
Install a sink for input-timing entropy (for example a random-number generator’s add-entropy routine). While a hook is set, every keyboard event and every mouse change (movement, button, wheel) is recorded as a 32-bit platformEntropyStamp value followed by the event bytes (scancode, ASCII, and shift state; or position, buttons, and wheel delta). Records are batched and handed to fn once 64 bytes have accumulated, so the cost per event stays negligible. An idle mouse is not recorded. Changing or clearing the hook discards any pending partial batch. The core library has no link-time dependency on any consumer; the shell resolves one at run time.
| Parameter | Description |
|---|---|
fn |
Entropy sink, or NULL to disable |
2.12.13. Desktop Sounds
The sounds DVX plays for its events. Which file each event plays (or none) is set on the Control Panel’s Sounds page and kept in DVX.INI [sounds]; the sound library plays them (see its developer help). Without the sound library, or without sound hardware, nothing is heard and nothing else changes.
typedef enum {
SoundDefaultE, // the default beep (dvxBeep)
SoundStartE, // DVX started
SoundExitE, // DVX is ending
SoundErrorE,
SoundWarningE,
SoundQuestionE,
SoundInfoE,
SoundWindowOpenE,
SoundWindowCloseE,
SoundCountE
} DvxSoundE;
-
dvxMessageBox (and the dialogs built on it: dvxErrorBox, dvxInfoBox, dvxPromptSave, ...) plays the event of its icon: MB_ICONERROR SoundErrorE, MB_ICONWARNING SoundWarningE, MB_ICONQUESTION SoundQuestionE, MB_ICONINFO SoundInfoE, no icon SoundDefaultE.
-
A window created with dvxCreateWindow plays SoundWindowOpenE at the next dvxUpdate, unless it has become modal by then (dialogs are quiet); destroying a window that is not modal plays SoundWindowCloseE.
-
The shell plays SoundStartE once the shell app is up, and SoundExitE (waiting for it) when DVX ends.
dvxPlaySound / dvxPlaySoundWait / dvxBeep
void dvxPlaySound(DvxSoundE event);
void dvxPlaySoundWait(DvxSoundE event);
void dvxBeep(void);
Play the sound of an event. dvxPlaySound returns at once while the sound plays on; dvxPlaySoundWait returns once it has played (at most a few seconds); dvxBeep is dvxPlaySound(SoundDefaultE). An event without a sound is silent.
dvxSetSoundHook
typedef void (*DvxSoundHookT)(DvxSoundE event, bool wait);
void dvxSetSoundHook(DvxSoundHookT fn);
The function that plays the sounds, set by the sound library when it loads (NULL: silent). Programs do not call it.
dvxSetWaitPump / dvxWaitPump
typedef bool (*DvxWaitPumpT)(void);
void dvxSetWaitPump(DvxWaitPumpT fn);
bool dvxWaitPump(void);
A library that waits for something (a sound to end, as dvxPlaySoundWait does) calls dvxWaitPump between its checks: DVX goes on meanwhile, and so do the events of the BASIC program that waits, as in DoEvents (the hook the BASIC runtime sets with dvxSetWaitPump). It returns false when the wait should stop: the program is ending, or its code may not wait (a control written in BASIC). Without a hook it yields the processor and returns true.
2.12.14. Full-Screen Exclusive Mode
A window’s program takes the whole screen in a video mode of its own (a game at 320x200, say) while every other program keeps running: windows keep painting into their own buffers, and the desktop is drawn again when the program lets go. The owner’s window must have the focus: when it loses it (Alt+Tab, Ctrl+Esc, a dialog, another window coming to the front) the desktop comes back and onChange hears ExclusiveSuspendedE; when the window has the focus again the mode is set again and onChange hears ExclusiveActiveE (draw the whole frame: the screen and the backbuffer start black). While active every key but Alt+Tab, Ctrl+Esc, and Alt+F4 goes to the window as in game input mode, the mouse cursor is not drawn, onMouse gets full-screen coordinates, dvxScreenshot saves the full screen, and dvxChangeVideoMode fails. Closing the window, the program ending or being ended, and dvxExclusiveEnd give the screen back. See the Writing Games guide.
typedef enum {
ExclusiveActiveE, // the screen is the program's: draw the whole frame
ExclusiveSuspendedE, // its window lost the focus: the desktop is back until it has the focus again
ExclusiveEndedE // the mode could not be set again: full screen is over
} ExclusiveStateE;
typedef void (*ExclusiveFnT)(WindowT *win, ExclusiveStateE state, void *userData);
dvxExclusiveBegin
int32_t dvxExclusiveBegin(AppContextT *ctx, WindowT *win, int32_t width, int32_t height, int32_t bpp, ExclusiveFnT onChange, void *userData);
Take the whole screen for win (raised and focused): the smallest mode of at least width x height, at bpp when there is one (0: any depth). At 8 bpp (or 0) a request that fits 320x200 gets VGA mode 13h, and one that fits 320x240 VGA Mode X (square pixels, two pages flipped at the retrace), unless the card has a VBE mode no larger with a linear frame buffer. onChange (may be NULL) hears ExclusiveActiveE before this returns. A window that already has full screen gets the new size.
Returns: DVX_EXCL_OK; DVX_EXCL_ERR_ARGS (no such window, or a bad size); DVX_EXCL_ERR_BUSY (another window has full screen); DVX_EXCL_ERR_MODE (no mode could be set; the desktop is back).
dvxExclusiveEnd
void dvxExclusiveEnd(AppContextT *ctx, WindowT *win);
Give the screen back: the desktop’s mode, palette, and mouse, and a full repaint. onChange is not called. Nothing when win does not have full screen.
dvxExclusiveMirror
int32_t dvxExclusiveMirror(AppContextT *ctx, WindowT *win, ExclusiveFnT onChange, void *userData);
Full screen for a window’s own content (a window of widgets, a drawing) rather than a picture the program draws: the smallest mode of at least the content’s size in the desktop’s pixel format, the content scaled by the largest whole factor that fits and centered on black, and shown again whenever the window paints (any dirty rectangle over its content). The mouse works on the content as in the window — onMouse gets content coordinates — and its cursor is drawn, in the shape the content asks for. Keys, suspending, resuming, and giving back are as for dvxExclusiveBegin; the BASIC form runtime’s Form.FullScreen is this.
Returns: as dvxExclusiveBegin; DVX_EXCL_ERR_MODE also when there is no mode in the desktop’s pixel format.
dvxExclusiveDisplay / dvxExclusiveBlitOps
DisplayT *dvxExclusiveDisplay(AppContextT *ctx);
const BlitOpsT *dvxExclusiveBlitOps(AppContextT *ctx);
The full-screen display (its size may be larger than asked for) and the span operations for its pixel format while active; NULL while suspended or without full screen. Draw into the display’s backBuf, with DVX’s draw functions if you like, then dvxExclusiveFlush.
dvxExclusiveFlush
void dvxExclusiveFlush(AppContextT *ctx, const RectT *r);
Copy a rectangle of the backbuffer to the screen (NULL: all of it). Nothing when not active. In Mode X a whole-screen flush goes to the hidden page, which is shown from the next vertical retrace (the call waits for it): no tearing; a smaller rectangle goes to the page on show.
dvxExclusivePresent8
bool dvxExclusivePresent8(AppContextT *ctx, const uint8_t *src, int32_t srcW, int32_t srcH, int32_t srcPitch);
Show an 8-bit picture of palette indexes on the whole screen: scaled by the largest whole factor that fits, centered on black, through the palette in any pixel format, and flushed (the whole screen, so Mode X flips pages). Returns false (and does nothing) when not active, so a caller falls back to drawing in its window.
dvxExclusiveSetPalette
void dvxExclusiveSetPalette(AppContextT *ctx, const uint8_t *pal, int32_t first, int32_t count);
Set palette entries first..first+count-1 (pal is the whole 256-entry table, R, G, B bytes per entry). At 8 bpp they go to the DAC at once, so a picture on screen changes color; at other depths the next dvxExclusivePresent8 uses them. The palette is kept while suspended and set again on resuming; the desktop’s palette comes back whenever the desktop does.
2.12.15. DOS Programs: dvxRunDos
int32_t dvxRunDos(AppContextT *ctx, const char *program, const char *args, const char *folder, bool pause);
bool dvxDosBatch(const char *program, const char *args, const char *folder, bool pause, char *out, int32_t outSize);
int32_t platformDosRun(const char *command, const char *folder, bool pause, const DisplayT *desktop);
bool platformPathAbsolute(const char *path, char *out, int32_t outSize);
dvxRunDos runs a DOS program (an .EXE, .COM, or .BAT file, or a command DOS knows) with DVX stepped aside, and comes back. Full screen, menus, and drags end; program is made absolute (a bare name stays one, for the PATH) and given to DOS by its short name, with args after it, in folder (NULL or "": the program’s own folder). platformDosRun then runs the suspend hooks (newest first), lets the keyboard hook and the timer service go (the timers are kept and stand still), sets text mode, gives the INT 24h handler and Ctrl+Break back to DOS, makes the folder current, and runs the command line with system() (as at the DOS prompt: a batch file through the command interpreter, PATH, redirection); with pause it prints "Press any key to return to DVX." and waits for a key. Everything is taken back in the opposite order, the desktop’s mode (and palette) set again, and the resume hooks run (oldest first); dvxRunDos sets the mouse up again where it was, forgets held keys, and repaints the whole screen. DVX logs "DOS: running" and "DOS: back from" with the command line. Nothing of DVX runs meanwhile: close the other programs first (the shell’s shellRunDos asks them). Returns the program’s exit code, or -1 when it could not be run (errno: ENOENT, ENOMEM, E2BIG for a command line longer than DOS’s 126 characters). DVX stays in memory: the program gets the conventional memory DVX’s DOS part and the DPMI host leave. On the host, platformDosRun is system() in the folder with the hooks around it.
dvxDosBatch writes the same run as a DOS batch file into out, for a run with DVX out of memory (the shell’s hand-over to DVX.COM, shell.run): ECHO OFF, the drive and CD of the folder (short names), the program’s line (CALL before a batch file), and with pause "Press any key to return to DVX." and a wait, lines ending in CR LF. It returns false (errno ENOENT, or E2BIG for a line longer than DVX_DOS_LINE_MAX, 127, or a batch longer than outSize) when there is nothing to write.
platformPathAbsolute makes a path absolute against the current folder (it need not exist).
2.12.16. Optional Libraries: dvxLibraryLoaded
bool dvxLibraryLoaded(const char *name);
Whether the library (or widget) name, its file’s base name in any case ("pkgnet", "dvxsql"), is installed and loaded. DVX loads a library when something first needs it, so asking loads one that is installed but not loaded yet. It looks for the module’s ABI stamp (DVX_ABI_STAMP: name and DVX_ABI_SUFFIX), which the loader checks before it takes the module; a module that is not there, or did not load, has none. Some parts of DVX are optional (Setup’s "What to install" page installs them as bundles: src/packages.ini), so a program that uses one of their libraries only when it is there asks first, and does not import it: an import of a missing library stops the program from loading. BASIC: SysLibraryLoaded (system.bas).
2.12.17. Idle Time: dvxIdleMs
uint32_t dvxIdleMs(const AppContextT *ctx);
The milliseconds since the last key or mouse input: a key (pressed, released, or typed), the mouse moving, a button, or the wheel, injected input (a test script, SysSendKey) included, and input that came while DVX was busy and was thrown away. DVX coming back from a DOS program or from full-screen mode counts as input too. The shell’s screen saver starts after DVX.INI [desktop] saverWait minutes of it (shellSaver.h); BASIC: SysIdleSeconds. The time is kept in AppContextT.lastInputTime (platformClock ticks).
2.12.18. Accelerators
dvxCreateAccelTable
AccelTableT *dvxCreateAccelTable(void);
Allocate a new accelerator table. Attach to a window via win->accelTable.
Returns: Pointer to new AccelTableT.
dvxFreeAccelTable
void dvxFreeAccelTable(AccelTableT *table);
Free an accelerator table and its entries.
| Parameter | Description |
|---|---|
table |
Table to free (NULL does nothing) |
dvxAddAccel
void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);
Register a keyboard shortcut. On match, fires the window’s onMenu callback with cmdId.
The key and modifiers are normalized at registration with the same rule applied to every keystroke:
-
Ctrl+letter control codes map back to the letter, and Alt+letter/digit scancodes map to the character, so ('S', ACCEL_CTRL) and ('S', ACCEL_ALT) both match.
-
Letters are uppercased ('s' and 'S' are the same key).
-
Ctrl and Alt are always significant. Shift is significant for extended keys (F-keys, arrows, ...) and for any Ctrl/Alt combination, so Ctrl+S and Ctrl+Shift+S are different accelerators, as are F5 and Shift+F5.
-
A printable character typed without Ctrl/Alt matches regardless of Shift, because the character already encodes Shift ('+', 'A').
-
KEY_ENTER and KEY_BACKSPACE with ACCEL_CTRL or ACCEL_ALT match those keys however the BIOS reports them (with Alt it gives no ASCII byte; the keypad Enter has scancodes of its own), so (KEY_ENTER, ACCEL_ALT) is Alt with either Enter key.
| Parameter | Description |
|---|---|
table |
Accelerator table (NULL is a no-op) |
key |
ASCII character or KEY_Fxx / KEY_* constant |
modifiers |
Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT |
cmdId |
Command ID passed to onMenu |
dvxRemoveAccel
void dvxRemoveAccel(AccelTableT *table, int32_t cmdId);
Remove every shortcut of command cmdId from the table: a menu item that lost its key or went away. The BASIC menu Shortcut property and RemoveMenuItem use it.
| Parameter | Description |
|---|---|
table |
Accelerator table (NULL is a no-op) |
cmdId |
Command whose shortcuts go |
dvxAccelFormat
void dvxAccelFormat(int32_t key, int32_t modifiers, char *out, int32_t outSize);
Write a key and its modifiers (given as for dvxAddAccel) as text, the way menus show it after a tab: the modifiers Ctrl, Alt, and Shift in that order, each followed by +, then the key — a letter or digit, F1 to F12, or one of the names Backspace, Del, Down, End, Enter, Esc, Home, Ins, Left, PgDn, PgUp, Right, Space, Tab, Up. Key 0 gives "".
dvxAccelFormat(KEY_ENTER, ACCEL_ALT, text, sizeof(text)); // "Alt+Enter"
dvxAccelKeyNames
#define DVX_ACCEL_NAMES_MAX 128
int32_t dvxAccelKeyNames(char *out, int32_t outSize);
The named keys, each as dvxAccelFormat writes it, as an English list for a message: "Backspace, Del, Down, End, Enter, Esc, Home, Ins, Left, PgDn, PgUp, Right, Space, Tab, and Up". Program Manager’s shortcut key rule names them this way. DVX_ACCEL_NAMES_MAX holds the list with its NUL. Returns the length written, or -1 (and out "") when it does not fit. BASIC: HotkeyNames$ (shell.bas).
dvxAccelParse
bool dvxAccelParse(const char *text, int32_t *outKey, int32_t *outMods);
Read key text as dvxAccelFormat writes it ("F2", "Ctrl+X", "Alt+Enter", "Shift+Del") into a key and ACCEL_* modifiers for dvxAddAccel or dvxRegisterHotkey. Case does not matter, blanks around the parts are ignored, and Delete and Insert are accepted for Del and Ins. Returns false, with *outKey 0, for empty text, an unknown modifier, or an unknown key.
2.12.19. System-Wide Hotkeys
A hotkey is a keystroke that works whichever window has the focus (or when none has): its callback runs instead of anything the focused window would do with the keys, including its menu keys and accelerators. Program Manager’s item shortcut keys are hotkeys. Hotkeys are not checked while a menu or a modal dialog is open, and the keys DVX keeps for itself (dvxSystemKeyUse) can never be hotkeys.
A hotkey belongs to the app that was current when it was registered (ctx->currentAppId, set by the shell whenever app code runs). When an app exits, crashes, or is ended from the Task Manager, the shell removes its hotkeys with dvxUnregisterAppHotkeys, so a callback never outlives the code it points into. The callback also runs with currentAppId set to that app.
dvxRegisterHotkey
typedef void (*DvxHotkeyFnT)(void *userCtx);
int32_t dvxRegisterHotkey(AppContextT *ctx, int32_t key, int32_t modifiers, DvxHotkeyFnT fn, void *userCtx);
Register a system-wide hotkey. key and modifiers are given and normalized exactly as for dvxAddAccel. A key needs Ctrl or Alt unless it is a function or navigation key (KEY_EXT_FLAG set), so a hotkey cannot swallow typing.
| Parameter | Description |
|---|---|
ctx |
Application context |
key |
ASCII character or KEY_Fxx / KEY_* constant |
modifiers |
Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT |
fn |
Called with userCtx when the keystroke is pressed |
userCtx |
Passed to fn |
Returns: the hotkey’s id (greater than zero), or DVX_HOTKEY_NONE when refused: NULL ctx or fn, a character key without Ctrl or Alt, a key DVX keeps for itself (dvxSystemKeyUse), or a keystroke that is already a hotkey (first come, first served).
dvxSystemKeyUse
const char *dvxSystemKeyUse(int32_t key, int32_t modifiers);
The keys DVX keeps for itself and acts on first, whichever window has the focus, so no hotkey, accelerator, menu, or program ever gets them. key and modifiers are given as for dvxAddAccel. For one of them the result is what it does, worded to finish a sentence such as "Ctrl+Alt+F4 cannot be a shortcut key: it ..."; NULL for any other key. The same table drives the key dispatch, so the two never disagree:
| Keys | Result |
|---|---|
Alt+Tab, with any other modifier too |
"switches to another window" |
Alt+F4, with any other modifier too |
"closes the active window" |
Ctrl+Esc, with any other modifier too |
"opens the Task Manager" |
Ctrl+Shift+F12 (and Ctrl+Alt+Shift+F12) |
"saves a picture of the active window’s contents" |
Ctrl+F12, with Alt too |
"saves a picture of the screen" |
F1 alone |
"opens help" |
F10 alone |
"opens the menu bar" |
Alt+Space, with any other modifier too |
"opens the window menu" |
Ctrl+Alt+Del, with Shift too |
"restarts the computer" (the BIOS acts on it; DVX never sees it) |
Program Manager refuses these as item shortcut keys (pmHotkeyParse) and says what each does.
2.12.20. Hung Apps
dvxAppIsHung
#define DVX_HUNG_APP_MS 5000
bool dvxAppIsHung(const AppContextT *ctx, int32_t appId);
True when appId has been inside one of its window callbacks (an event handler that has not returned to the event loop, such as a button handler in an endless loop) for DVX_HUNG_APP_MS or longer. An app with a modal dialog of its own open is waiting for the user, not hung. The Task Manager shows such an app as "Not responding". Every window callback dvxUpdate dispatches is booked per app (nested calls count once, from the outermost); widget Timer callbacks are not window callbacks and are not tracked.
2.12.21. Window Arrangement
dvxCascadeWindows
void dvxCascadeWindows(AppContextT *ctx);
Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height; the diagonal wraps back to the top-left corner when the next window would leave the screen.
| Parameter | Description |
|---|---|
ctx |
Application context |
dvxTileWindows
void dvxTileWindows(AppContextT *ctx);
Arrange visible windows in an NxM grid filling the screen. Windows are never placed off screen: when there are more windows than fit at the minimum window size, the extra tiles overlap.
| Parameter | Description |
|---|---|
ctx |
Application context |
2.12.22. Image I/O
DVX_IMAGE_PATTERNS
#define DVX_IMAGE_PATTERNS "*.bmp;*.png;*.jpg;*.jpeg;*.gif"
The picture formats DVX reads (BMP, PNG, JPEG, GIF), as patterns of their file names: the one list of them. A file dialog’s filter takes it inside a label ({ "Pictures (" DVX_IMAGE_PATTERNS ")" }), and platformFilterMatch(name, DVX_IMAGE_PATTERNS) tells whether a file name is a picture’s. DVX’s own file dialogs, Control Panel’s wallpaper list, and the help rebuild’s check of help pictures use it. The decoders libdvx compiles in are these formats, so a format added to one is added to the other. BASIC programs have SysPicturePatterns$ (system.bas).
dvxLoadImage
uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);
Load an image file (one of DVX_IMAGE_PATTERNS' formats) and convert to the display’s native pixel format. A file that is no image but a DVX program, widget, or library with an icon resource gives that icon (dvxResLoadIconData), so every picture that takes a file name can show a program’s icon. Caller must free with dvxFreeImage().
Called from a program’s own task (where the task takes no input: a BASIC program), the image loaders decode a big picture a part at a time, a frame of DVX’s every 32 KB read, so the other programs go on; none of the caller’s code runs meanwhile. On the task that takes the input they decode in one go.
| Parameter | Description |
|---|---|
ctx |
Application context |
path |
Image file path |
outW, outH |
Output: image dimensions |
outPitch |
Output: row pitch in bytes |
Returns: Pixel buffer, or NULL on failure. An image without pixels (a width or height of 0, which some BMP headers declare) is a failure for every image loader.
dvxLoadImageFromMemory
uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);
Load an image from a memory buffer (typically resource data). Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().
| Parameter | Description |
|---|---|
ctx |
Application context |
data |
Image data buffer |
dataLen |
Buffer size in bytes |
outW, outH |
Output: image dimensions |
outPitch |
Output: row pitch in bytes |
Returns: Pixel buffer, or NULL on failure.
dvxLoadImageAlpha
uint8_t *dvxLoadImageAlpha(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch, bool *outHasAlpha, uint32_t *outKeyColor);
Load an image from memory with alpha transparency. Pixels with alpha < 128 are replaced with a packed magenta key color. If any transparent pixels are found, *outHasAlpha is set to true and *outKeyColor receives the packed key color for use with rectCopyTransparent. Caller must free with dvxFreeImage.
| Parameter | Description |
|---|---|
ctx |
Application context |
data |
Image data buffer |
dataLen |
Buffer size in bytes |
outW, outH |
Output: image dimensions |
outPitch |
Output: row pitch |
outHasAlpha |
Output: true if any transparent pixels found |
outKeyColor |
Output: packed key color (valid when outHasAlpha is true) |
Returns: Pixel buffer, or NULL on failure.
dvxFreeImage
void dvxFreeImage(uint8_t *data);
Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().
| Parameter | Description |
|---|---|
data |
Buffer to free |
dvxImageInfo
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);
Query image dimensions without decoding the full file (its header only: a picture damaged after it may still fail to load).
| Parameter | Description |
|---|---|
path |
Image file path |
outW, outH |
Output: image dimensions |
Returns: true on success; false for an unreadable image or one without pixels.
dvxImageInfoFromMemory
bool dvxImageInfoFromMemory(const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH);
dvxImageInfo for an image’s bytes in memory (as LoadPicture checks a picture before a control shows it).
dvxSaveImage
int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);
Save native-format pixel data to an image file: BMP when path ends in .bmp (case-insensitive), PNG otherwise.
| Parameter | Description |
|---|---|
ctx |
Application context |
data |
Pixel data in display native format |
w, h |
Image dimensions |
pitch |
Row pitch in bytes |
path |
Output file path |
Returns: 0 on success, -1 on failure.
2.12.23. Screenshots
dvxScreenshot
int32_t dvxScreenshot(AppContextT *ctx, const char *path);
Save the entire screen (backbuffer contents) to an image file (BMP for a .bmp path, PNG otherwise). Converts from native pixel format to RGB (15/16-bit channels are expanded to full intensity). Shows the busy cursor while writing and restores the caller’s busy state afterwards.
| Parameter | Description |
|---|---|
ctx |
Application context |
path |
Output file path |
Returns: 0 on success, -1 on failure.
dvxWindowScreenshot
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);
Save a window’s content to an image file (BMP for a .bmp path, PNG otherwise). A repaint still pending from wgtInvalidate is run first, so the image shows the current state. Restores the caller’s busy state afterwards.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window |
path |
Output file path |
Returns: 0 on success, -1 on failure.
2.12.24. Clipboard
dvxClipboardClear
void dvxClipboardClear(void);
Empty the clipboard; dvxClipboardGet then returns NULL.
dvxClipboardCopy
bool dvxClipboardCopy(const char *text, int32_t len);
Copy len bytes of text to the clipboard: one heap buffer DVX keeps for every program, grown as needed (it is not shared with DOS programs run from DVX). Copying nothing (NULL text or a len of 0 or less) empties the clipboard, like dvxClipboardClear.
| Parameter | Description |
|---|---|
text |
Text to copy |
len |
Length in bytes |
Returns: true, or false when out of memory: the clipboard is then empty (a paste never brings back what was copied before).
dvxClipboardGet
const char *dvxClipboardGet(int32_t *outLen);
Retrieve the current clipboard contents, NUL-terminated, with their length in *outLen. Returns a pointer to the clipboard’s own buffer, valid until the next dvxClipboardCopy or dvxClipboardClear (copy what is kept), or NULL if empty.
| Parameter | Description |
|---|---|
outLen |
Output: length of clipboard text |
Returns: Clipboard text, or NULL.
2.12.25. Drag Feedback
For programs that implement drag and drop: an outline or a picture that follows the mouse over every window (drawn under the cursor) until it is hidden. One is shown at a time; showing another replaces it. The program still tracks the mouse and decides where a drop lands; this only draws.
dvxDragOutlineShow
void dvxDragOutlineShow(AppContextT *ctx, int32_t w, int32_t h, int32_t offX, int32_t offY);
Show a w x h dotted outline (two-tone, so it shows on any background) whose top-left corner stays (offX, offY) from the mouse pointer — typically the dragged object’s size and its offset from where it was grabbed.
dvxDragImageShow
void dvxDragImageShow(AppContextT *ctx, const uint8_t *pixels, int32_t w, int32_t h, int32_t pitch, bool hasKey, uint32_t keyColor);
Show a picture centered on the mouse pointer. pixels are in the display’s native format, as dvxLoadImage or dvxLoadImageAlpha return them, and must stay valid until the feedback is hidden or replaced. With hasKey, pixels of keyColor are transparent (pass dvxLoadImageAlpha’s outputs).
dvxDragFeedbackHide
void dvxDragFeedbackHide(AppContextT *ctx);
Remove the outline or picture. The usual cursor shapes come back (see dvxDragCursorSet).
dvxDragCursorSet
void dvxDragCursorSet(AppContextT *ctx, int32_t cursorId);
Choose the mouse cursor shown while the outline or picture is up: CURSOR_NO_DROP where a drop cannot land, CURSOR_ARROW (the default) where it can. The program calls it as the mouse moves, since only it knows its drop targets. While drag feedback is shown this cursor replaces the usual shapes (resize arrows, a widget’s own cursor); hiding the feedback puts them back and resets the choice to CURSOR_ARROW. Values outside the cursor table are ignored.
2.12.26. Resource Loading
dvxResLoadIcon
uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);
Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().
| Parameter | Description |
|---|---|
ctx |
Application context |
dxePath |
Path to DXE file |
resName |
Resource name within the DXE |
outW, outH |
Output: image dimensions |
outPitch |
Output: row pitch |
Returns: Pixel buffer, or NULL if not found.
dvxResLoadIconData
void *dvxResLoadIconData(const char *dxePath, uint32_t *outSize);
The icon of a DVX program, widget, or library file as the bytes of its image file: its DVX_RES_NAME_ICON resource ("icon32", a program’s icon), else DVX_RES_NAME_WIDGET_ICON ("icon24", a widget’s toolbox icon). Decode it with dvxLoadImageFromMemory or dvxLoadImageAlpha. Caller must free() the buffer.
| Parameter | Description |
|---|---|
dxePath |
Path to the program, widget, or library file |
outSize |
Output: size of the data in bytes |
Returns: The data, or NULL when the file has neither resource (or is no DVX file).
dvxResLoadText
bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);
Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.
| Parameter | Description |
|---|---|
dxePath |
Path to DXE file |
resName |
Resource name |
buf |
Output buffer |
bufSize |
Buffer capacity |
Returns: true on success.
dvxResLoadData
void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);
Load a raw binary resource from a DXE file. Returns a malloc’d buffer that the caller must free.
| Parameter | Description |
|---|---|
dxePath |
Path to DXE file |
resName |
Resource name |
outSize |
Output: data size in bytes |
Returns: Data buffer, or NULL if not found.
2.13. dvxDrv.h — Driver Modules
One model for the hardware drivers of every device class (sound, joysticks, ...). A driver is a module of its own, a file <name>.drv in its class’s folder under bin/libs (built like a library, but the loader does not load it). The library of the device class loads its drivers only when a program first needs that kind of device, probes them, keeps the ones it uses, and unloads the rest, so drivers for hardware that is not there, or for a device class nobody uses, never stay in memory. Nothing lists drivers: adding one is dropping its file into the folder.
Each driver exports one descriptor under a name its class chooses (audioDriver, joyDriver, ...). The descriptor is the class’s own struct and starts with a DvxDriverHeaderT, written with DVX_DRIVER_HDR (the classes wrap it in their own macro, such as AUDIO_DRIVER or JOY_DRIVER).
2.13.1. Types
| Type | Members |
|---|---|
DvxDriverHeaderT |
abiVersion (DVX_ABI_VERSION the driver was built for), size (sizeof the whole descriptor), name (short name, lower case, no blanks; DVX.INI settings use it), priority (higher is tried first). |
DvxDriverModT |
handle (NULL once kept out of the list or unloaded), desc (the descriptor), kind (index of the descriptor symbol found). |
DvxDriverClassT |
symbols (descriptor symbol of each kind, as dlsym wants it: DVX_SYM("name")), minSizes (smallest descriptor accepted per kind), kinds, valid (the class’s own check of a descriptor, such as its functions being present; NULL for none). |
DVX_DRIVER_HDR(type, name, priority) fills the header: { DVX_ABI_VERSION, sizeof(type), name, priority }.
2.13.2. Functions
dvxDriversLoad
DvxDriverModT *dvxDriversLoad(const char *dir, const DvxDriverClassT *cls);
Loads every *.drv in dir (relative to the DVX directory), looks each descriptor up, and checks it: the ABI version, the size, a name, and the class’s valid function. The valid ones come back as an stb_ds array sorted by priority (highest first, by name on a tie); a module that does not load, has no valid descriptor, or repeats a name a higher priority driver already has is logged to DVX.LOG and unloaded. NULL when there are none.
dvxDriverKeep
DvxDriverModT dvxDriverKeep(DvxDriverModT *mods, int32_t index);
Takes mods[index] out of the list (so dvxDriversFree leaves it loaded) and returns it; unload it with dvxDriverUnload when done.
2.13.3. Writing a Device Class
A library that has drivers puts them in drivers/<name>/ in its source folder; its Makefile sets OBJDIR and DRVDIR and writes $(foreach d,$(DVX_DRIVERS),$(eval $(call DVX_DRIVER_RULE,$d))) (common.mk), which builds each folder into $(DRVDIR)/<name>.drv. The library defines its descriptor struct (starting with DvxDriverHeaderT), a macro that writes it, and a DvxDriverClassT; it calls dvxDriversLoad when it first needs devices, dvxDriverKeep for the drivers it uses, and dvxDriversFree for the rest. Driver code resolves the library’s functions when it loads, since the libraries are loaded for everyone to use.
2.14. dvxWgt.h — Widget System
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
2.14.1. WidgetT Structure
Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget’s DXE.
| Field | Description |
|---|---|
int32_t type |
Widget type ID (assigned by wgtRegisterClass) |
const WidgetClassT *wclass |
Vtable for this widget type |
char name[MAX_WIDGET_NAME] |
Widget name for lookup via wgtFind |
parent, firstChild, lastChild, nextSibling |
Tree linkage pointers |
WindowT *window |
Owning window |
int32_t x, y, w, h |
Computed geometry (relative to content area) |
int32_t calcMinW, calcMinH |
Computed minimum size (from layout pass) |
int32_t minW, minH, maxW, maxH |
Size hints (tagged sizes): the least and the most the layout gives the widget |
int32_t weight |
Extra-space distribution weight (0=fixed, 100=normal) |
WidgetAlignE align |
Main-axis alignment for children |
int32_t spacing, padding |
Tagged sizes for child spacing and padding |
uint32_t fgColor, bgColor |
Custom colors (0 = use scheme defaults) |
BitmapFontT *font |
The widget’s own font (wgtSetFont); NULL = its container’s (wgtFontFor) |
bool visible, enabled, readOnly |
State flags |
bool swallowTab |
Tab key goes to widget, not focus navigation (so does the Tab of the only widget of its window that can take the focus) |
bool paintDirty |
Needs repaint (set by wgtInvalidatePaint) |
bool childDirty |
A descendant needs repaint (for WCLASS_PAINTS_CHILDREN) |
bool pressed |
WCLASS_PRESS_RELEASE: set while button is pressed |
bool backdrop |
Set by wgtSetBackdrop: the widget covers its parent behind the parent’s other children |
char accelKey |
Accelerator character (0 = none) |
int32_t contentOffX, contentOffY |
Content offset for mouse event coordinates |
void *userData, *data |
Application data and widget-private data |
const char *tooltip |
Tooltip text (NULL = none) |
MenuT *contextMenu |
Right-click menu (NULL = none) |
uint32_t serial |
Unique per allocation, never reused while the process runs (tells "the same widget" from a new widget at a recycled address) |
RectT paintClip |
Display clip when last painted (content-buffer coords, w = 0 until first paint); used by mouse dispatch inside clipping containers |
onEvent(w, name, args, argc) |
Custom (named) events: every event wgtFireEvent fires that has no universal callback below (see Custom Events) |
Universal Callbacks:
| Callback | Description |
|---|---|
onClick(WidgetT *w) |
Widget clicked, as in Visual Basic: after the release’s onMouseUp, when the release is over the widget (a list’s, WCLASS_CLICK_ON_PICK, is its pick, after the press’s onMouseDown); not for a press on its chrome: a scroll bar, a list’s column headers |
onDblClick(WidgetT *w) |
Widget double-clicked (not on its chrome either): at the second press. Outside a button or a list that press is the onDblClick alone and its release an onMouseUp: MouseDown, MouseUp, Click, DblClick, MouseUp, as in Visual Basic |
onChange(WidgetT *w) |
Value changed |
onFocus(WidgetT *w) |
Widget gained focus |
onBlur(WidgetT *w) |
Widget lost focus |
onKeyPress(WidgetT *w, int32_t keyAscii) |
A key that is a character (KEY_IS_ASCII: a printable key, Enter, Backspace, Esc, Tab, a Ctrl+letter), after onKeyDown and before the widget acts on the key (wgtKeyReplace changes or cancels it) |
onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift) |
Key down, before onKeyPress and before the widget acts on the key (wgtKeyReplace changes or cancels it) |
onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift) |
Key up |
onMouseDown(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Mouse button pressed: button is its MOUSE_* bit (MOUSE_LEFT 1, MOUSE_RIGHT 2, MOUSE_MIDDLE 4, Visual Basic’s vbLeftButton, vbRightButton, vbMiddleButton); x and y are relative to the widget’s content |
onMouseUp(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Mouse button released (button as for onMouseDown); the left release of a press goes to the widget pressed, wherever the mouse is (the press holds the mouse). Neither fires for a press of any button on the control’s chrome (its scroll bars, a list’s column headers: WGT_METHOD_HIT_CHROME), as in Visual Basic |
onMouseMove(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Mouse moved: button is the MOUSE_* mask of the buttons held (0 = none); none while a press on a control’s chrome is held |
onScroll(WidgetT *w, int32_t delta) |
Mouse wheel |
onValidate(WidgetT *w) |
Return false to cancel a write |
The universal callbacks belong to the widget’s host (the application or the form runtime). A widget class sees the same input earlier through its own class methods: WGT_METHOD_ON_MOUSE_EVENT, WGT_METHOD_ON_KEY_UP, WGT_METHOD_ON_FOCUS, WGT_METHOD_ON_BLUR, and WGT_METHOD_ON_WHEEL run before the matching callback (see Method IDs). A key is the exception, as in Visual Basic and Windows: onKeyDown, then onKeyPress (a key that is a character), and only then WGT_METHOD_ON_KEY, the class acting on the key, so the host sees the widget as it was before the key and can change the key or cancel it with wgtKeyReplace (widgetKeyTo).
2.14.2. Size Specification Macros
| Macro | Description |
|---|---|
wgtPixels(v) |
Size in pixels |
wgtChars(v) |
Size in character widths (multiplied by charWidth at layout) |
wgtPercent(v) |
Size as a percentage: in minW/minH/maxW/maxH of the parent container’s inner width or height, in padding/spacing of the container’s own width; counts 0 when measured, resolved by the layout out of the room it has to spare (see wgtsys.dhs Percentages, widgetLayout.c) |
2.14.3. Widget Class Flags
- WCLASS_FOCUSABLE
-
Can receive keyboard focus (Tab navigation)
- WCLASS_HORIZ_CONTAINER
-
Lays out children horizontally (vs. vertical)
- WCLASS_PAINTS_CHILDREN
-
Widget handles child rendering itself
- WCLASS_NO_HIT_RECURSE
-
Class hit testing stops here (the container’s ON_MOUSE gets the press); universal callbacks still reach visible children of a non-focusable container
- WCLASS_FOCUS_FORWARD
-
Accel hit forwards focus to next focusable sibling
- WCLASS_HAS_POPUP
-
Has dropdown popup overlay
- WCLASS_SCROLLABLE
-
Mouse wheel sends Up/Down arrow keys
- WCLASS_SCROLL_CONTAINER
-
Scroll container (ScrollPane)
- WCLASS_NEEDS_POLL
-
Needs periodic polling
- WCLASS_SWALLOWS_TAB
-
Tab key goes to widget, not focus navigation
- WCLASS_RELAYOUT_ON_SCROLL
-
Full relayout on scrollbar drag
- WCLASS_PRESS_RELEASE
-
Click = press + release over the widget (Button, ImageButton, CheckBox, OptionButton): the press shows it pressed, the release over it acts and fires onClick (from its WGT_METHOD_ON_DRAG_END), and the dispatcher fires no onClick at the press
- WCLASS_ACCEL_WHEN_HIDDEN
-
Accelerator matching works even when invisible
- WCLASS_HAS_TEXT
-
The first field of w->data is the widget’s own text (strdup / free)
- WCLASS_RAISES_EVENTS
-
The class fires the universal mouse, click, key, and scroll callbacks itself (wgtFireEvent); the dispatcher does not call them for its widgets. Its class methods still get every event. A BASIC UserControl has it: its host sees only what the control’s code raises. GotFocus / LostFocus still reach onFocus / onBlur.
- WCLASS_FIXED_FONT
-
The class edits text by character columns (TextBox, TextArea, Terminal, ComboBox, Spinner): given a proportional font it draws with the system font instead (wgtFontFor); a fixed-pitch font of any size is used.
- WCLASS_SWALLOWS_ENTER
-
The class uses Enter itself (Button and ImageButton, which Enter presses, TextArea, RichEdit, Terminal, a help link): in a window with a default button (a dialog box, a window with dvxSetWindowButtons, a BASIC form with a Default button) Enter goes to the focused widget instead of pressing that button. A drop-down whose list is open keeps Enter too; any other focused widget (a check box, an option button) never sees it there, as in Windows.
- WCLASS_CLICK_ON_PICK
-
onClick is the user’s pick of an item, as a Windows list box’s selection notice is (ListBox, ListView, TreeView, ComboBox, Dropdown): the class calls widgetFirePick(w, changed, itemEvent, item) for each pick, which fires onChange when changed (the pick changed the selection; picking the item already selected changes nothing), the class’s own item event when itemEvent is not NULL (a ListView’s ItemClick, a TreeView’s NodeClick, Expand, or Collapse: wgtFireEvent with item its one argument), and then onClick. A pick made by a press gets its events from the dispatcher after the press’s onMouseDown (for a double click’s second press, onChange when it chose another item, then onDblClick instead; a class whose second press acts on the item, as a TreeView opens or closes a node, calls widgetFireDoublePick, whose item event then also fires, before onDblClick); a pick made with the keys or in a popup list gets them at once. A press that picks nothing (a scroll bar, a column header, a ComboBox’s text or arrow, a Dropdown’s closed box) gets no onClick; in a ListView or TreeView a press below the items is a pick of nothing (onClick alone), as Visual Basic’s Click there.
- WCLASS_ONE_LINE
-
One line high (TextBox, ComboBox): along a row (HBox) the widget grows as its weight says, but in a column (VBox) it keeps its height and gets no share of the extra room, so a single-line box under a label stays one line tall in a window with room to spare.
A control’s chrome — its scroll bars and the corner between them, a column header or header border (ListView, DbGrid) — is what its class’s WGT_METHOD_HIT_CHROME says (bool (w, vx, vy)), for a press of any button: that press fires no onClick, onDblClick, onMouseDown, or onMouseUp (nor the class’s WGT_METHOD_ON_MOUSE_EVENT), and no onMouseMove comes while it is held (a scroll arrow held down, a thumb dragged), as Visual Basic raises no Click, DblClick, MouseDown, MouseUp, or MouseMove there; a press on the control’s content after it is never the second of a double click (multiClickDetect counts presses on chrome and on content apart, widgetPressIsChrome). The class’s own handlers (WGT_METHOD_ON_MOUSE, a thumb drag) still run, and a right press on the content still opens the control’s context menu. ListBox, ListView, TreeView, DbGrid, TextArea, RichEdit, the Terminal, and ScrollPane have the method. A class without it may call widgetPressOnChrome() from its WGT_METHOD_ON_MOUSE handler for the left press it is handling, and a left press that steps a scroll bar is chrome by itself (widgetScrollbarPressStep, which widgetScrollbarApplyHit calls). Outside a press dispatch the call does nothing.
2.14.4. Window Integration
wgtInitWindow
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);
Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs the seven window callbacks for widget-based event dispatch: onPaint, onMouse, onKey, onKeyUp, onResize, onFocus, and onBlur (handlers set before the call are replaced: set your own afterwards and chain to widgetOnFocus / widgetOnBlur). The root widget’s userData is set to the AppContextT pointer (the window’s userData is left for the application). The window’s first paint measures and lays out the widgets added to it, and so does its next full paint after more are added, so a program that builds its widgets needs no wgtInvalidate for them to appear laid out. Calling it again on a window that already has a widget root returns that root.
| Parameter | Description |
|---|---|
ctx |
Application context |
win |
Window to initialize |
Returns: Root VBox widget (add children to this).
2.14.5. Widget Operations
wgtGetContext
AppContextT *wgtGetContext(const WidgetT *w);
Retrieve the AppContextT stored in the root widget’s userData: in O(1) through the widget’s window when it is attached, otherwise by walking up to the root of its tree. Lets any widget access the full application context.
| Parameter | Description |
|---|---|
w |
Any widget in the tree |
Returns: Pointer to the AppContextT.
wgtInvalidate
void wgtInvalidate(WidgetT *w);
Re-measure and re-lay out the widget’s whole window immediately (adding or removing window scrollbars as needed, so widget geometry can be read right away) and schedule a full repaint. The paint happens once per frame in the deferred paint flush of dvxUpdate, so several invalidations in one event handler cost one paint. Use after structural changes (adding/removing children, text changes that affect size). Widgets added to a window since it was last measured are measured by its next full paint even without wgtInvalidate; call it when the geometry is needed before then or the window will not otherwise be painted in full.
| Parameter | Description |
|---|---|
w |
Widget to invalidate |
wgtInvalidatePaint
void wgtInvalidatePaint(WidgetT *w);
Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).
| Parameter | Description |
|---|---|
w |
Widget to repaint |
wgtSetText
void wgtSetText(WidgetT *w, const char *text);
Set widget text content (dispatches to the widget class’s SET_TEXT handler).
| Parameter | Description |
|---|---|
w |
Widget |
text |
New text |
wgtGetText
const char *wgtGetText(const WidgetT *w);
Get the widget’s current text content.
| Parameter | Description |
|---|---|
w |
Widget |
Returns: Text string (empty string if no handler).
wgtSetFont / wgtFont / wgtFontFor
bool wgtSetFont(WidgetT *w, const char *family, int32_t size, uint32_t style);
const BitmapFontT *wgtFont(const WidgetT *w);
const BitmapFontT *wgtFontFor(const WidgetT *w, const BitmapFontT *inherited);
wgtSetFont gives w the font of family at the size nearest size in style (dvxFontOpen, dvxText.h: FONT_STYLE_BOLD, ITALIC, UNDERLINE, STRIKE); the widgets inside w draw with it too unless they have their own — a form’s font is its root widget’s. A NULL family gives the font up, so w uses its container’s again. The window is laid out again. Returns false when out of memory (w keeps the font it had). The font is closed when w is destroyed.
wgtFontFor is the font w draws with: its own, else the nearest container’s up the parent chain, else inherited (the font passed down: the application’s, or NULL for a metrics query that needs none). A class with WCLASS_FIXED_FONT given a proportional font gets the system font. The class dispatch helpers (wclsPaint, wclsPaintOverlay, wclsCalcMinSize, wclsLayout, wclsGetLayoutMetrics, wclsGetPopupRect) hand every method this font, so a widget’s paint, measure, and layout methods simply use their font parameter. Code that is given no font — mouse and key handlers, helpers — calls wgtFont(w), the same with the application’s font. Size hints in characters (wgtChars) count the widget’s own font.
| Parameter | Description |
|---|---|
w |
Widget |
family |
Family name (NULL: inherit again) |
size |
Pixel size wanted |
style |
FONT_STYLE_* bits |
inherited |
The font the caller would otherwise use |
wgtSetEnabled
void wgtSetEnabled(WidgetT *w, bool enabled);
Enable or disable a widget. Disabled widgets are grayed out and do not receive input; disabling a container also blocks mouse and keyboard input to every widget inside it and draws them disabled (grayed), as in Windows Forms (Visual Basic 6 leaves them looking enabled): each widget paints its disabled look from the enabled chain (widgetIsEnabledChain), and wgtSetEnabled repaints the container’s whole subtree. Enabled again, they paint normally, unless one is disabled itself (its own flag is never changed). Setting the current value is a no-op.
| Parameter | Description |
|---|---|
w |
Widget |
enabled |
true = enabled, false = disabled |
wgtSetReadOnly
void wgtSetReadOnly(WidgetT *w, bool readOnly);
Set read-only mode. Allows scrolling and selection but blocks editing.
| Parameter | Description |
|---|---|
w |
Widget |
readOnly |
true = read-only |
wgtSetFocused
void wgtSetFocused(WidgetT *w);
Set keyboard focus to a widget.
| Parameter | Description |
|---|---|
w |
Widget to focus |
wgtGetFocused
WidgetT *wgtGetFocused(void);
Get the currently focused widget.
Returns: Focused widget, or NULL.
wgtKeyReplace
void wgtKeyReplace(int32_t key);
Called from a widget’s onKeyDown or onKeyPress callback: the key the widget acts on instead of the one being dispatched. Give another key to change it, or 0 to cancel it: the widget does nothing with the key, and after onKeyDown no onKeyPress follows. This is what setting KeyCode or KeyAscii does in Visual Basic, and how DVX BASIC honors those ByRef parameters. Outside those callbacks it does nothing (a key dispatched inside a callback, by DoEvents, has its own).
| Parameter | Description |
|---|---|
key |
The key the widget gets: a key code as the callbacks receive them, or 0 for none |
wgtSetBackdrop
void wgtSetBackdrop(WidgetT *w, bool on);
Make w a backdrop of its parent, or (on false) an ordinary child again. A backdrop is no part of its parent’s layout: the parent’s minimum size, its other children’s places, and the window’s scroll bars are as if it were not there, and the layout gives it the parent’s whole box. It paints before the parent’s other children, wherever it sits among them, so they paint over it; when it repaints alone (wgtInvalidatePaint), they repaint over it too. The mouse never hits it: a press on it goes to the parent (widgetHitTest). A Canvas backdrop’s buffer follows the parent’s size both ways, keeping its drawing, the grown part in the color behind it (wgtBackColor): a picture behind a window’s widgets, as DVX BASIC draws a form’s graphics behind its controls. The parent is a box (VBox, HBox, a window’s root); a container that paints its own children (WCLASS_PAINTS_CHILDREN) does not paint backdrops first. Does nothing for a widget with no parent.
| Parameter | Description |
|---|---|
w |
Widget |
on |
true = backdrop, false = an ordinary child |
wgtSetVisible
void wgtSetVisible(WidgetT *w, bool visible);
Show or hide a widget. Hiding a subtree that holds keyboard focus drops the focus. Setting the current value is a no-op.
| Parameter | Description |
|---|---|
w |
Widget |
visible |
true = visible, false = hidden |
wgtSetName
void wgtSetName(WidgetT *w, const char *name);
Set a widget’s name for lookup via wgtFind().
| Parameter | Description |
|---|---|
w |
Widget |
name |
Name string (max MAX_WIDGET_NAME chars) |
wgtFind
WidgetT *wgtFind(WidgetT *root, const char *name);
Find a widget by name. Searches the subtree rooted at root.
| Parameter | Description |
|---|---|
root |
Root of subtree to search |
name |
Widget name to find |
Returns: Matching widget, or NULL.
wgtDestroy
void wgtDestroy(WidgetT *w);
Destroy a widget and all its children. Removes from parent’s child list.
| Parameter | Description |
|---|---|
w |
Widget to destroy |
wgtSetTooltip
void wgtSetTooltip(WidgetT *w, const char *text);
Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.
| Parameter | Description |
|---|---|
w |
Widget |
text |
Tooltip text, or NULL |
widgetOnResize
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);
Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.
| Parameter | Description |
|---|---|
win |
Window being resized |
newW, newH |
New content dimensions |
2.14.6. Layout
wgtResolveSize
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);
Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").
| Parameter | Description |
|---|---|
taggedSize |
Tagged size value |
parentSize |
Parent dimension (for PERCENT mode) |
charWidth |
Font character width (for CHARS mode) |
Returns: Size in pixels.
wgtGetPaddingPx / wgtSetPaddingPx / wgtGetSpacingPx / wgtSetSpacingPx
int32_t wgtGetPaddingPx(const WidgetT *w);
void wgtSetPaddingPx(WidgetT *w, int32_t size);
int32_t wgtGetSpacingPx(const WidgetT *w);
void wgtSetSpacingPx(WidgetT *w, int32_t size);
A container’s padding (space inside its edge) and spacing (gap between children). The getters return the pixels the layout uses now: the container’s default while the field is WGT_GAP_DEFAULT (every widget starts so), a size in characters or percent as it resolves. The setters take pixels, clamped to 0..WGT_GAP_PIXELS_MAX (0 is no gap), or a size made by wgtChars or wgtPercent (a percentage of the container’s own width, out of the room it has beyond its measured minimum), and re-lay out the window. The BASIC Padding and Spacing properties of VBox, HBox, Frame, ScrollPane, and WrapBox use these (Padding = SizePercent(5) with layout.bas; a WrapBox takes no percentage, its height coming from its rows).
wgtLayout
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);
Execute the full two-pass layout algorithm on a tree at an explicit size. Pass 1 (bottom-up): compute minimum sizes; a cap (maxW/maxH) wins over a larger minimum, so a widget whose content asks for more than its cap is given its cap and the rest of the space goes to its siblings. Pass 2 (top-down): allocate space with weighted distribution; a weighted child capped by maxW/maxH stops at its cap and the space it cannot take goes to the other weighted children. Window-managed trees are laid out by wgtInvalidate and the paint path; this is for laying out a tree on demand.
| Parameter | Description |
|---|---|
root |
Root widget |
availW/H |
Available space |
font |
Bitmap font (for character-based sizing) |
wgtPaint
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, bool fullRepaint);
Paint the widget tree by depth-first traversal (every widget, or only dirty ones) using the display’s current clip rect. Popup overlays are not painted here; the window paint handler paints them afterwards so they are on top.
| Parameter | Description |
|---|---|
root |
Root widget |
d |
Display context |
ops |
Blit operations vtable |
font |
Bitmap font |
colors |
Color scheme |
fullRepaint |
true = repaint every widget; false = only paintDirty widgets |
2.14.7. Debug
2.14.8. Dynamic Widget Registration
wgtRegisterClass
int32_t wgtRegisterClass(const WidgetClassT *wclass);
Register a new widget class at runtime. Stores the class in the first free widgetClassTable slot (or appends one). The WidgetClassT must remain valid until wgtUnregisterClass is called for it (typically static const in a DXE). A class whose version is not WGT_CLASS_VERSION is rejected (logged, returns -1).
| Parameter | Description |
|---|---|
wclass |
Widget class vtable to register |
Returns: Assigned type ID, or -1 if wclass is NULL or its version does not match.
wgtUnregisterClass
void wgtUnregisterClass(int32_t classId);
Release a class registered with wgtRegisterClass, typically from an app’s shutdown before its module is unloaded. Every widget of the class must already be destroyed. The slot is cleared: creating a widget with the freed ID fails (returns NULL), and a later wgtRegisterClass may reuse the ID. Out-of-range or already-free IDs are ignored.
| Parameter | Description |
|---|---|
classId |
Type ID returned by wgtRegisterClass |
wgtUnregisterIface
void wgtUnregisterIface(const char *name);
Remove the interface registered under name (wgtRegisterIface). A widget class made at run time — a BASIC program’s own UserControl — leaves the registry this way when its owner is done with it, so the name can be registered again. Nothing happens when no interface has the name.
wgtUnregisterAppClasses
void wgtUnregisterAppClasses(int32_t appId);
Release every class, API (wgtRegisterApi), and interface (wgtRegisterIface) registered while appId was the current app (AppContextT.currentAppId at registration time), since all of them point into the app’s module. The shell calls it whenever it unloads an app (normal exit or End Task), once the app’s windows and widgets are gone. appId 0 (boot-time widget modules) is ignored.
| Parameter | Description |
|---|---|
appId |
App whose classes are released |
wgtRegisterApi
void wgtRegisterApi(const char *name, const void *api);
Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type. A name is registered once: a second API under a name already taken is refused and logged, and the first stays.
| Parameter | Description |
|---|---|
name |
Widget type name (e.g. "button", "listbox") |
api |
Pointer to the widget’s API struct |
Every API struct starts with a WgtApiHeaderT member named header, which the provider fills with WGT_API_HEADER(its API type):
typedef struct {
WgtApiHeaderT header;
WidgetT *(*create)(WidgetT *parent, const char *text);
} ButtonApiT;
static const ButtonApiT sApi = {
.header = WGT_API_HEADER(ButtonApiT),
.create = wgtButton
};
| Type / Macro | Description |
|---|---|
WgtApiHeaderT |
{ uint32_t abiVersion; uint32_t size; }: the DVX_ABI_VERSION the provider was built with and the sizeof its API struct. |
WGT_API_HEADER(apiType) |
Initializer for the header member: { DVX_ABI_VERSION, sizeof(apiType) }. |
WgtApiPrefixT |
{ WgtApiHeaderT header; WgtApiFnT create; }: the part every API struct shares. Generic callers that do not know the widget’s own API type use it. |
|
Warning
|
The create function must be the first field after the header. wgtCreateByName (which the form runtime and the designer use) instantiates widgets through WgtApiPrefixT.create, cast to the signature WgtIfaceT.createSig names, so whichever field comes first is what gets invoked. If the struct has multiple constructor variants, the one matching createSig must come first; put helper constructors, index accessors, and other entry points after it. |
wgtGetApi
const void *wgtGetApi(const char *name, uint32_t minSize);
Retrieve a registered widget API struct by name, checked against the caller’s view of it. A struct built for another DVX_ABI_VERSION, or smaller than minSize (an older, shorter table), is refused and the refusal logged.
| Parameter | Description |
|---|---|
name |
Widget type name |
minSize |
sizeof the API type the caller will use: sizeof(ButtonApiT) for a typed accessor, sizeof(WgtApiPrefixT) when only create is called |
Returns: Pointer to the API struct, or NULL if not found or refused. Per-widget headers wrap the call in a typed accessor (dvxButtonApi() and friends).
2.14.9. Widget Interface Descriptors
wgtBasicColor
static inline uint32_t wgtBasicColor(uint32_t color);
Converts a color between DVX’s 0x00RRGGBB layout (WidgetT fgColor / bgColor, packColor’s channels, the color dialog) and DVX BASIC’s Visual Basic layout &HBBGGRR (RGB(), QBColor, ForeColor / BackColor, drawing-method color arguments) by swapping the red and blue bytes; the top byte is kept, so the function is its own inverse. A widget’s BASIC methods call it once where a BASIC color comes in and once where one goes back out.
| Parameter | Description |
|---|---|
color |
A color in either layout |
Returns: The color in the other layout.
wgtColorFromBasic, wgtColorToBasic
#define WGT_COLOR_SET 0x01000000u
#define WGT_COLOR_RGB_MASK 0x00FFFFFFu
static inline uint32_t wgtColorFromBasic(uint32_t basic);
static inline uint32_t wgtColorToBasic(uint32_t color);
A widget’s own color (WidgetT fgColor / bgColor) is 0x00RRGGBB with WGT_COLOR_SET, so black (WGT_COLOR_SET alone) is a color the widget has, not none: 0 means the widget has no color of its own (the color scheme’s, or, for bgColor, what the widget sits on: wgtBackColor). wgtColorFromBasic makes such a color of a DVX BASIC color (&HBBGGRR; its top byte does not count), as a control’s ForeColor or BackColor takes it; wgtColorToBasic gives one back as DVX BASIC’s. C code that sets a widget’s color itself adds WGT_COLOR_SET to the 0x00RRGGBB value.
| Parameter | Description |
|---|---|
basic |
A DVX BASIC color, &HBBGGRR |
color |
A widget’s color with WGT_COLOR_SET |
Returns: wgtColorFromBasic, the widget color; wgtColorToBasic, the DVX BASIC color.
wgtRegisterIface
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);
Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch. A type name is registered once: a second interface under a name already taken is refused and logged, and the first stays; only the interface a stand-in waits for (wgtRegisterIfaceLater) takes a registered name, the stand-in’s. A BASIC name (basName) may repeat — two programs may each have a control of their own of one name — and resolves to the interface registered first (wgtFindByBasName); two of one BASIC name registered by the same program, or by two installed widget modules, are logged.
| Parameter | Description |
|---|---|
name |
Widget type name |
iface |
Interface descriptor |
wgtRegisterIfaceLater
typedef void (*WgtIfaceLoadFnT)(const char *name);
void wgtRegisterIfaceLater(const char *name, const WgtIfaceT *stub, WgtIfaceLoadFnT load);
Register name for an interface that comes later. DVX’s loader registers each installed control written in DVX BASIC this way, so the BASIC run-time library loads only when a program first needs one. Until then stub (kept by the caller, like any interface) stands for the interface: wgtIfaceAt lists it, and wgtFindByBasName, wgtResolveTypeName, and wgtIfaceGetPath find it, with nothing loaded. The first wgtGetIface of the name, and so the first wgtCreateByName, calls load(name) once. load registers the real interface with wgtRegisterIface, which takes over the stand-in’s entry (its type name, file path, and place in the list), or drops the name with wgtUnregisterIface when the interface cannot be had. A name already registered is refused and logged.
| Parameter | Description |
|---|---|
name |
Widget type name |
stub |
The stand-in interface (its basName at least) |
load |
Called the first time the interface itself is needed |
wgtIfaceIsLater
bool wgtIfaceIsLater(const char *name);
Whether name is a stand-in still waiting for its interface (wgtRegisterIfaceLater). False for a real interface and for a name not registered.
wgtGetIface
const WgtIfaceT *wgtGetIface(const char *name);
Retrieve an interface descriptor by widget type name. A stand-in’s interface (wgtRegisterIfaceLater) is loaded first.
| Parameter | Description |
|---|---|
name |
Widget type name |
Returns: Interface descriptor, or NULL.
wgtFindByBasName
const char *wgtFindByBasName(const char *basName);
Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"): the interface registered first when several have that name. Case-insensitive search.
| Parameter | Description |
|---|---|
basName |
VB-style widget name |
Returns: Internal type name, or NULL.
wgtIfaceCount
int32_t wgtIfaceCount(void);
Return the number of registered widget interfaces.
Returns: Count of registered interfaces.
wgtIfaceAt
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);
Get a registered widget interface by index; for a stand-in (wgtRegisterIfaceLater), its stub, with nothing loaded.
| Parameter | Description |
|---|---|
idx |
Index (0-based) |
outName |
Output: type name |
Returns: Interface descriptor.
wgtIfaceGetPath
const char *wgtIfaceGetPath(const char *name);
Get the .wgt DXE file path for a registered widget.
| Parameter | Description |
|---|---|
name |
Widget type name |
Returns: File path string.
2.14.10. Typed Dispatch Helpers
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
| Function | Method ID | Description |
|---|---|---|
wclsHas(w, methodId) |
— |
Check if handler exists |
wclsPaint(w, d, ops, font, colors) |
WGT_METHOD_PAINT |
Paint the widget |
wclsPaintOverlay(w, d, ops, font, colors) |
WGT_METHOD_PAINT_OVERLAY |
Paint overlay (popups) |
wclsCalcMinSize(w, font) |
WGT_METHOD_CALC_MIN_SIZE |
Compute minimum size |
wclsLayout(w, font) |
WGT_METHOD_LAYOUT |
Layout children |
wclsGetLayoutMetrics(w, font, ...) |
WGT_METHOD_GET_LAYOUT_METRICS |
Get pad, gap, extraTop, borderW |
wclsOnMouse(w, root, vx, vy) |
WGT_METHOD_ON_MOUSE |
Handle mouse event |
wclsOnKey(w, key, mod) |
WGT_METHOD_ON_KEY |
Handle key event |
wclsOnAccelActivate(w, root) |
WGT_METHOD_ON_ACCEL_ACTIVATE |
Handle accelerator |
wclsDestroy(w) |
WGT_METHOD_DESTROY |
Destroy widget data |
wclsOnChildChanged(parent, child) |
WGT_METHOD_ON_CHILD_CHANGED |
Notify parent of change |
wclsGetText(w) |
WGT_METHOD_GET_TEXT |
Get widget text |
wclsSetText(w, text) |
WGT_METHOD_SET_TEXT |
Set widget text |
wclsClearSelection(w) |
WGT_METHOD_CLEAR_SELECTION |
Clear text selection |
wclsClosePopup(w) |
WGT_METHOD_CLOSE_POPUP |
Close dropdown popup |
wclsGetPopupRect(w, font, ...) |
WGT_METHOD_GET_POPUP_RECT |
Get popup screen rect |
wclsOnDragUpdate(w, root, x, y) |
WGT_METHOD_ON_DRAG_UPDATE |
Update during drag |
wclsOnDragEnd(w, root, x, y) |
WGT_METHOD_ON_DRAG_END |
End drag operation |
wclsGetCursorShape(w, vx, vy) |
WGT_METHOD_GET_CURSOR_SHAPE |
Get cursor for position |
wclsPoll(w, win) |
WGT_METHOD_POLL |
Periodic polling |
wclsQuickRepaint(w, outY, outH) |
WGT_METHOD_QUICK_REPAINT |
Fast partial repaint |
wclsScrollChildIntoView(parent, child) |
WGT_METHOD_SCROLL_CHILD_INTO_VIEW |
Scroll child visible |
wclsOnBlur(w) |
WGT_METHOD_ON_BLUR |
Widget lost keyboard focus |
wclsOnWheel(w, delta) |
WGT_METHOD_ON_WHEEL |
Mouse wheel; true = consumed |
wclsOnMouseEvent(w, action, button, x, y, shift) |
WGT_METHOD_ON_MOUSE_EVENT |
Every press, release, and move (hover too) |
wclsOnKeyUp(w, keyCode, shift) |
WGT_METHOD_ON_KEY_UP |
Key released on the focused widget |
wclsOnFocus(w) |
WGT_METHOD_ON_FOCUS |
Widget gained keyboard focus |
wclsOnFormatChange(w, from) |
WGT_METHOD_ON_FORMAT_CHANGE |
Screen’s pixel format changed from *from |
wclsHitChrome(w, vx, vy) |
WGT_METHOD_HIT_CHROME |
Whether (vx, vy) is on the control’s chrome |
wclsMinPercent(w, across) |
WGT_METHOD_MIN_PERCENT |
The class’s own minimum in percent of the container (0: none) |
The central dispatcher calls WGT_METHOD_ON_MOUSE_EVENT for every widget whose class has it, at exactly the points where it calls the universal mouse callbacks and on the same widget (the one under the cursor; inside a non-focusable WCLASS_NO_HIT_RECURSE container, a child with the method gets them itself, and a container with the method keeps them), and always before the callback. action is a WgtMouseActionE: WgtMouseDownE and WgtMouseUpE carry the button’s MOUSE_* bit (MOUSE_LEFT 1, MOUSE_RIGHT 2, MOUSE_MIDDLE 4, as onMouseDown gets it), WgtMouseMoveE the MOUSE_* mask of the held buttons (0 is a hover move). x and y are content-relative (contentOffX / contentOffY subtracted), shift is the KEY_MOD_* Shift / Ctrl / Alt state. A class that captures the mouse on a press (sets sDragWidget in its WGT_METHOD_ON_MOUSE handler) also gets the moves while the button is held and the left release, wherever the pointer is. WGT_METHOD_ON_KEY_UP runs before onKeyUp with the same arguments, WGT_METHOD_ON_FOCUS before onFocus (the counterpart of ON_BLUR). If a class method destroys widgets, the callback after it is skipped. Classes without these methods see no change.
The mouse wheel is offered first to an ON_WHEEL handler on the focused widget, then on each ancestor, with delta in notches (positive = down, the user’s reverse-wheel setting already applied; the lines-per-notch preference is AppContextT.wheelStep). Returning true consumes the event. Otherwise a WCLASS_SCROLLABLE focused widget (or a scroll-container ancestor) receives Up/Down arrow keys, and failing that the window scrollbar moves. The widget’s onScroll callback fires in every case.
2.14.11. Method IDs
Fixed constants used to index into WidgetClassT.handlers[]. Method IDs are stable ABI — new methods are appended at the next sequential ID, never reordered or reused.
| ID | Symbol | Signature |
|---|---|---|
0 |
WGT_METHOD_PAINT |
void (w, d, ops, font, colors) |
1 |
WGT_METHOD_PAINT_OVERLAY |
void (w, d, ops, font, colors) |
2 |
WGT_METHOD_CALC_MIN_SIZE |
void (w, font) |
3 |
WGT_METHOD_LAYOUT |
void (w, font) |
4 |
WGT_METHOD_GET_LAYOUT_METRICS |
void (w, font, pad, gap, extraTop, borderW) |
5 |
WGT_METHOD_ON_MOUSE |
void (w, root, vx, vy) |
6 |
WGT_METHOD_ON_KEY |
void (w, key, mod) |
7 |
WGT_METHOD_ON_ACCEL_ACTIVATE |
void (w, root) |
8 |
WGT_METHOD_DESTROY |
void (w) |
9 |
WGT_METHOD_ON_CHILD_CHANGED |
void (parent, child) |
10 |
WGT_METHOD_GET_TEXT |
const char *(w) |
11 |
WGT_METHOD_SET_TEXT |
void (w, text) |
12 |
WGT_METHOD_CLEAR_SELECTION |
bool (w) |
13 |
WGT_METHOD_CLOSE_POPUP |
void (w) |
14 |
WGT_METHOD_GET_POPUP_RECT |
void (w, font, contentH, popX, popY, popW, popH) |
15 |
WGT_METHOD_ON_DRAG_UPDATE |
void (w, root, x, y) |
16 |
WGT_METHOD_ON_DRAG_END |
void (w, root, x, y) |
17 |
WGT_METHOD_GET_CURSOR_SHAPE |
int32_t (w, vx, vy) |
18 |
WGT_METHOD_POLL |
void (w, win) |
19 |
WGT_METHOD_QUICK_REPAINT |
int32_t (w, outY, outH) |
20 |
WGT_METHOD_SCROLL_CHILD_INTO_VIEW |
void (parent, child) |
21 |
WGT_METHOD_ON_BLUR |
void (w) |
22 |
WGT_METHOD_ON_WHEEL |
bool (w, delta) |
23 |
WGT_METHOD_ON_MOUSE_EVENT |
void (w, action, button, x, y, shift) |
24 |
WGT_METHOD_ON_KEY_UP |
void (w, keyCode, shift) |
25 |
WGT_METHOD_ON_FOCUS |
void (w) |
26 |
WGT_METHOD_GET_FACE |
uint32_t (w, colors) |
27 |
WGT_METHOD_ON_FORMAT_CHANGE |
void (w, from) |
28 |
WGT_METHOD_HIT_CHROME |
bool (w, vx, vy) |
29 |
WGT_METHOD_MIN_PERCENT |
int32_t (w, across) |
— |
WGT_METHOD_MAX = 32 |
(room for future methods) |
WGT_METHOD_MIN_PERCENT gives the class’s own minimum along an axis (across true: the width) as a percentage, 0 to 100, of the inside of the container the widget is in, or 0 for none: a natural size that is a share of the container, as a BASIC UserControl’s header Width = 50% is. It follows the rules of a percentage minW or minH (see wgtsys.dhs Percentages, widgetLayout.c): the class’s WGT_METHOD_CALC_MIN_SIZE measures it as nothing (calcMinW / calcMinH leave it out), and the layout gives it out of the room the container has to spare. With a percentage minW or minH too, the larger of the two counts (widgetMinPercent, dvxWgtP.h). Classes without the method have no such minimum.
WGT_METHOD_ON_FORMAT_CHANGE runs for every widget of every window when dvxChangeVideoMode changes the screen’s pixel format (another color depth), after the new mode is set and before anything is painted again; from is the old PixelFormatT. A class that keeps pixels or packed colors in the display format converts them there (convertPixels and convertColor, dvxVideo.h; ctx->display is the new format), or drops them to be made again. Canvas, Image, and ImageButton convert their pictures, the Terminal packs its 16 colors again, and Program Manager’s icon view decodes its icons again; DVX converts window icons itself.
WGT_CLASS_VERSION is DVX_ABI_VERSION (see Binary Interface Version). The framework rejects WidgetClassT structs whose version does not match.
2.14.13. Size Encoding Constants
| Define | Value | Description |
|---|---|---|
WGT_SIZE_TYPE_MASK |
0xC0000000 |
Top 2 bits: unit type selector |
WGT_SIZE_VAL_MASK |
0x3FFFFFFF |
Bottom 30 bits: numeric value |
WGT_SIZE_PIXELS |
0x00000000 |
Unit tag: pixels |
WGT_SIZE_CHARS |
0x40000000 |
Unit tag: character widths |
WGT_SIZE_PERCENT |
0x80000000 |
Unit tag: percentage of parent |
WGT_GAP_DEFAULT |
0xC0000000 |
padding / spacing: the container’s own default (wgtPixels(0) is no gap) |
WGT_WEIGHT_FILL |
100 |
Default "flexible" weight value |
2.14.14. Widget Interface Descriptors
WgtPropDescT
Describes a BASIC-exposed property on a widget type. Used by the form runtime and IDE for generic get/set dispatch.
| Field | Description |
|---|---|
name |
BASIC property name (e.g. "Caption", "Value") |
type |
Data type: WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_FLOAT, or WGT_IFACE_ENUM |
getFn |
Getter function pointer (NULL if write-only) |
setFn |
Setter function pointer (NULL if read-only) |
enumNames |
For WGT_IFACE_ENUM: NULL-terminated array of value names |
checked |
true when setFn returns bool: false refuses the value (outside the property’s range), changing nothing |
A property is readable when getFn is not NULL and writable when setFn is not NULL — the one rule for every interface (the form runtime, the designer, and the property sheet all apply it). A dynamic interface (WgtIfaceT.dyn) puts WGT_DYN_ACCESS in getFn / setFn for "present"; they are never called. A FLOAT getter returns float and its setter takes float. A checked property’s setter (checked true) has the same arguments and returns bool: a ListBox’s ListIndex refuses an index past its list, a scroll bar’s Value one outside Min to Max, as Visual Basic’s controls refuse them; wgtIfaceSetProp then answers false and the BASIC form runtime raises error 380 (Invalid property value). The rows of a table give it as their last field ({ "ListIndex", WGT_IFACE_INT, (void *)get, (void *)set, NULL, true }). An enumerated property refuses a number its enumNames has no name for the same way.
WgtMethodDescT
Describes an invokable method on a widget type.
| Field | Description |
|---|---|
name |
BASIC method name (e.g. "Clear", "SetFocus") |
sig |
Calling convention ID (WGT_SIG_xxx) |
fn |
Function pointer |
Calling convention IDs (method sig field). IDs are stable ABI; new ones are appended.
| Define | ID | Handler signature |
|---|---|---|
WGT_SIG_VOID |
0 |
void fn(WidgetT *) |
WGT_SIG_INT |
1 |
void fn(WidgetT *, int32_t) |
WGT_SIG_BOOL |
2 |
void fn(WidgetT *, bool) |
WGT_SIG_STR |
3 |
void fn(WidgetT *, const char *) |
WGT_SIG_INT_INT |
4 |
void fn(WidgetT *, int32_t, int32_t) |
WGT_SIG_INT_BOOL |
5 |
void fn(WidgetT *, int32_t, bool) |
WGT_SIG_RET_INT |
6 |
int32_t fn(const WidgetT *) |
WGT_SIG_RET_BOOL |
7 |
bool fn(const WidgetT *) |
WGT_SIG_RET_BOOL_INT |
8 |
bool fn(const WidgetT *, int32_t) |
WGT_SIG_INT3 |
9 |
void fn(WidgetT *, int32_t, int32_t, int32_t) |
WGT_SIG_INT4 |
10 |
void fn(WidgetT *, int32_t, int32_t, int32_t, int32_t) |
WGT_SIG_RET_INT_INT_INT |
11 |
int32_t fn(const WidgetT *, int32_t, int32_t) |
WGT_SIG_INT_INT_STR |
12 |
void fn(WidgetT *, int32_t, int32_t, const char *) |
WGT_SIG_INT5 |
13 |
void fn(WidgetT *, int32_t, int32_t, int32_t, int32_t, int32_t) |
WGT_SIG_RET_STR_INT |
14 |
const char *fn(const WidgetT *, int32_t) |
WGT_SIG_RET_STR_INT_INT |
15 |
const char *fn(const WidgetT *, int32_t, int32_t) |
WGT_SIG_STR_BOOL_BOOL |
16 |
bool fn(WidgetT *, const char *, bool, bool) |
WGT_SIG_STR_STR_BOOL |
17 |
int32_t fn(WidgetT *, const char *, const char *, bool) |
WGT_SIG_RET_STR |
18 |
const char *fn(const WidgetT *) |
WGT_SIG_STR_INT |
19 |
void fn(WidgetT *, const char *, int32_t) |
WGT_SIG_INT_STR |
20 |
void fn(WidgetT *, int32_t, const char *) |
WGT_SIG_STR_STR |
21 |
void fn(WidgetT *, const char *, const char *) |
WGT_SIG_STR_BOOL |
22 |
void fn(WidgetT *, const char *, bool) |
WGT_SIG_RET_INT_STR |
23 |
int32_t fn(WidgetT *, const char *) — status-returning string method (e.g. Load/Save) |
WGT_SIG_STR_STR_BOOL_BOOL |
24 |
bool fn(WidgetT *, const char *, const char *, bool, bool) |
WGT_SIG_RET_INT_INT |
25 |
int32_t fn(const WidgetT *, int32_t) |
WGT_SIG_DYNAMIC |
26 |
bool fn(WidgetT *, const WgtValueT *args, int32_t argc, WgtValueT *ret) (WgtDynMethodFnT): any arguments, as they come |
WGT_SIG_CHK_INT |
27 |
bool fn(WidgetT *, int32_t) — checked |
WGT_SIG_CHK_STR_INT |
28 |
bool fn(WidgetT *, const char *, int32_t) — checked |
WGT_SIG_IDX_GET_INT |
29 |
bool fn(const WidgetT *, int32_t idx, int32_t *out) — an indexed property’s read: an int32_t result |
WGT_SIG_IDX_SET_INT |
30 |
bool fn(WidgetT *, int32_t idx, int32_t value) — an indexed property’s assignment |
WGT_SIG_IDX_SET_STR |
31 |
bool fn(WidgetT *, int32_t idx, const char *value) — an indexed property’s assignment |
WGT_SIG_IDX_GET_BOOL |
32 |
bool fn(const WidgetT *, int32_t idx, bool *out) — an indexed property’s read: a bool result |
WGT_SIG_IDX_SET_BOOL |
33 |
bool fn(WidgetT *, int32_t idx, bool value) — an indexed property’s assignment |
WGT_SIG_IDX_SET_DYNAMIC |
34 |
WgtDynMethodFnT — an indexed property’s assignment taking its arguments as they come (the index arguments, then the value) |
WGT_SIG_DYN_1 |
35 |
WgtDynMethodFnT — one argument |
WGT_SIG_DYN_2 |
36 |
WgtDynMethodFnT — two arguments |
WGT_SIG_DYN_1_2 |
37 |
WgtDynMethodFnT — one or two arguments |
WGT_SIG_IDX_GET_STR |
38 |
bool fn(const WidgetT *, int32_t idx, const char **out) — an item’s text, read as an indexed property’s read is |
WGT_SIG_IDX2_GET_STR |
39 |
bool fn(const WidgetT *, int32_t row, int32_t col, const char **out) — a cell’s text, the same way |
WGT_SIG_ITEM_INT |
40 |
bool fn(WidgetT *, int32_t idx) — a method of item idx (checked: false is no item there) |
WGT_SIG_ITEM_INT_BOOL |
41 |
bool fn(WidgetT *, int32_t idx, bool value) — the same, with a Boolean |
WGT_SIG_ITEM_INT_STR |
42 |
bool fn(WidgetT *, int32_t idx, const char *value) — the same, with a string |
WGT_SIG_ITEM_INT_INT_STR |
43 |
bool fn(WidgetT *, int32_t row, int32_t col, const char *value) — a method of a cell, with a string |
wgtSigInfo describes each signature (WgtSigInfoT: argc, retType, argTypes[], WGT_SIG_MAX_ARGS = 5, and kind; NULL for the dynamic signatures). wgtSigDynamic(sig, &fewest, &most) is true for a dynamic one (WGT_SIG_DYNAMIC, WGT_SIG_IDX_SET_DYNAMIC, WGT_SIG_DYN_*), which a WgtDynMethodFnT takes, with the fewest and most arguments it takes (-1 and -1: any number; either pointer may be NULL). A call with another number than a WGT_SIG_DYN_* or a dynamic interface’s methodArgs gives is not made: wgtIfaceCallMethod answers false and the BASIC form runtime raises error 449 or 450. wgtIfaceCallMethod is the one place that calls through these signatures. A checked signature (kind WGT_SIG_KIND_CHECKED, WGT_SIG_KIND_INDEX_GET, WGT_SIG_KIND_INDEX_SET, or WGT_SIG_KIND_ITEM) returns false, doing nothing, when an argument is out of range (an index past the list), and wgtIfaceCallMethod then returns false; the BASIC form runtime raises error 5 for a checked method (WGT_SIG_KIND_CHECKED: an argument a method checks, such as AddItem’s position) and error 381 (Invalid property array index) for an indexed property and for an item’s method (WGT_SIG_KIND_ITEM: one whose first argument names the item it reads or changes, such as a TreeView’s SetItemText, and the WGT_SIG_IDX_GET_* reads that are methods, such as GetItemText).
Several methods of an interface may have one name when each takes another number of arguments, as a ListBox’s AddItem text and AddItem text, index: a call takes the one its arguments fit (wgtIfaceFindMethodArgs). An indexed property (BASIC’s List1.ItemData(i), read and assigned) is two methods of one name: its read, a WGT_SIG_IDX_GET_* (or any signature with a result) taking the index, and its assignment, a WGT_SIG_IDX_SET_* taking the index and then the value, which only an assignment calls. List the read first: wgtIfaceFindMethod finds the first of a name.
WgtEventDescT
Describes an event beyond the standard common set (Click, DblClick, Change, GotFocus, LostFocus, the key and mouse events ...). The widget fires it with wgtFireEvent.
| Field | Description |
|---|---|
name |
Event name (e.g. "ColumnClick", "Timer") |
params |
The handler’s parameter list as BASIC writes it ("Topic As String", "" for none); NULL when the event is one of the BASIC master list’s (Timer, Validate, Reposition) and takes its parameters from there |
params is the only place a widget’s own event parameters are written down: the IDE’s handler stubs and designer.bas CtlEventParams$ read it. The shipped widgets' own events: ListView ColumnClick (Column As Integer, 0-based), TextArea GutterClick (LineNumber As Integer, 1-based), HelpPane LinkClick (Topic As String).
WgtIfaceT
Top-level interface descriptor registered by each widget DXE.
| Field | Description |
|---|---|
basName |
VB-style name (e.g. "CommandButton"), or NULL |
props |
Array of WgtPropDescT |
propCount |
Length of props array |
methods |
Array of WgtMethodDescT |
methodCount |
Length of methods array |
events |
Array of WgtEventDescT (extras beyond common set) |
eventCount |
Length of events array |
createSig |
How to call the widget’s create() function (WgtCreateSigE) |
createArgs |
Default numeric args for design-time instantiation |
isContainer |
true = widget can hold child widgets |
defaultEvent |
Default event name for form designer |
namePrefix |
Auto-name prefix (NULL = derive from basName) |
dyn |
Dynamic interface hooks (WgtDynIfaceT), NULL for a widget written in C |
WgtDynIfaceT
typedef struct {
WidgetT *(*create)(WidgetT *parent, const WgtIfaceT *iface);
bool (*getProp)(WidgetT *w, int32_t propIdx, WgtValueT *out);
bool (*setProp)(WidgetT *w, int32_t propIdx, const WgtValueT *value);
bool (*callMethod)(WidgetT *w, int32_t methodIdx, const WgtValueT *args, int32_t argc, WgtValueT *ret);
bool (*methodArgs)(const WgtIfaceT *iface, int32_t methodIdx, int32_t *outMin, int32_t *outMax);
void *ctx;
} WgtDynIfaceT;
A widget class whose properties and methods are not C functions with fixed signatures (a BASIC UserControl, a scripted widget) sets WgtIfaceT.dyn. The generic access functions then call these hooks instead of the descriptors' getFn / setFn / fn: create makes a widget for wgtCreateByName, propIdx and methodIdx index the interface’s props[] and methods[]. Each hook returns false when it could not do the job. A value read is converted to the property’s type; a method whose sig is a fixed WGT_SIG_* gets its arguments converted to that signature and its result converted to the signature’s type, a WGT_SIG_DYNAMIC method gets them as they come. methodArgs (may be NULL) gives the fewest and most arguments a dynamic method takes (*outMax -1: no most), true when it knows them; a call with another number is not made (a BASIC UserControl gives its procedures' counts: its Optional and ParamArray parameters taken into account). Strings returned follow the WgtValueT lifetime rule. ctx is the provider’s own pointer.
2.14.15. Generic Values
WgtValueT
typedef struct {
uint8_t type; // WGT_IFACE_*
int32_t len; // STRING: its length when it may hold NUL bytes; 0 = up to its NUL
union {
int32_t i; // INT, BOOL (0 / 1), ENUM
double f; // FLOAT, DOUBLE
const char *s; // STRING
};
} WgtValueT;
One property value, method argument or result, or event argument. WGT_IFACE_NONE (5) is "no value" (a void method’s result). A STRING value never owns its text: an argument’s text belongs to the caller for the duration of the call; a returned one (a property read, a method result) belongs to the widget and stays valid until the next call on that widget or until the widget changes or is destroyed — copy it to keep it. wgtValueInt, wgtValueBool, wgtValueFloat, wgtValueDouble, and wgtValueStr (NULL becomes "") build values; wgtValueBytes(s, len) builds a STRING of len bytes that may hold NUL bytes (s[len] must still be a NUL). A BASIC string holds any bytes, so the form runtime passes every string this way, and a STRING’s length is wgtValueLen(v): its len, or up to its NUL when len is 0. A widget that takes binary text (Terminal Write) reads that length; one that wants C text reads s, which stops at the first NUL. FLOAT is BASIC’s Single, DOUBLE its Double: a DOUBLE property or argument keeps every digit (a value through FLOAT is rounded to a float by a static widget’s getter and setter, and the form runtime shows it as a Single); as text a DOUBLE has 15 significant digits.
wgtValueToInt / wgtValueToBool / wgtValueToFloat / wgtValueToText
int32_t wgtValueToInt(const WgtValueT *v);
bool wgtValueToBool(const WgtValueT *v);
double wgtValueToFloat(const WgtValueT *v);
const char *wgtValueToText(const WgtValueT *v, char *buf, int32_t bufSize);
Convert any value: numbers convert to each other (a FLOAT truncates toward zero and is clamped to the int32_t range), a BOOL is 0 / 1, a STRING is parsed (decimal, strtod, wgtParseBool), NONE is 0 / false / "". wgtValueToText returns the value’s own text for a STRING, otherwise formats into buf (INT / ENUM decimal, BOOL "True" / "False", FLOAT %g); WGT_VALUE_TEXT_MAX (32) bytes hold any non-STRING value.
2.14.16. Generic Widget Access
One implementation of "create, read, write, and call by name" for every widget, static or dynamic. The form runtime, the IDE designer, and C programs all use it; nothing else switches on WGT_SIG_* or WgtCreateSigE.
wgtIfaceSetType / wgtGetIfaceOf
void wgtIfaceSetType(const char *name, int32_t typeId);
const WgtIfaceT *wgtGetIfaceOf(const WidgetT *w, const char **outName);
wgtIfaceSetType binds the interface registered under name to the widget class typeId (from wgtRegisterClass); every shipped widget calls it in wgtRegister after wgtRegisterIface. An interface keeps the class it was bound to first, so a module whose registration under a name already taken was refused cannot take that interface for its own class. wgtGetIfaceOf then finds the interface of any widget of that class (NULL when none is bound); outName (may be NULL) receives the registered type name. wgtUnregisterClass drops the binding.
wgtResolveTypeName
const char *wgtResolveTypeName(const char *name);
The registered type name for a BASIC name ("CommandButton" -> "button", tried first) or for a type name that has an API or an interface; NULL when neither is registered. A stand-in’s name (wgtRegisterIfaceLater) resolves without loading its interface.
wgtIfaceFindProp / wgtIfaceFindMethod / wgtIfaceFindEvent
const WgtPropDescT *wgtIfaceFindProp(const WgtIfaceT *iface, const char *propName);
const WgtMethodDescT *wgtIfaceFindMethod(const WgtIfaceT *iface, const char *methodName);
const WgtEventDescT *wgtIfaceFindEvent(const WgtIfaceT *iface, const char *eventName);
Case-insensitive lookups of a descriptor by name (the first match); NULL when iface is NULL or nothing matches.
const WgtMethodDescT *wgtIfaceFindMethodArgs(const WgtIfaceT *iface, const char *methodName, int32_t argc, bool set, int32_t *outMin, int32_t *outMax);
The method of that name a call with argc arguments takes: the methods of one name take different numbers of them, and with set only an indexed property’s assignment (WGT_SIG_KIND_INDEX_SET or WGT_SIG_IDX_SET_DYNAMIC) is taken, without it never one. NULL when none takes argc; *outMin and *outMax (either may be NULL) are the fewest and most arguments the methods of that name take (0 and -1 when there is none), for the error a caller reports. A dynamic method takes the arguments wgtIfaceMethodArgs says, any number when it says none.
bool wgtIfaceMethodArgs(const WgtIfaceT *iface, const WgtMethodDescT *m, int32_t *outMin, int32_t *outMax);
The fewest and most arguments method m of iface takes: its fixed signature’s count (wgtSigInfo), a WGT_SIG_DYN_*'s (wgtSigDynamic), or what the dynamic interface’s methodArgs says. False when it takes any number (*outMin 0, *outMax -1); with true, *outMax -1 means no most (a ParamArray).
wgtCreateByName
WidgetT *wgtCreateByName(const char *name, WidgetT *parent);
Create a widget of type name (a BASIC or type name, wgtResolveTypeName) under parent: a dynamic interface’s create hook, otherwise the API’s create function called by the interface’s createSig with its createArgs ("" for a text, an empty picture for WGT_CREATE_PARENT_DATA; a type without an interface is created as fn(parent)). A stand-in’s interface (wgtRegisterIfaceLater) is loaded first. Returns NULL when the type is unknown or creation failed.
wgtGetProp / wgtSetProp / wgtCallMethod
bool wgtGetProp(WidgetT *w, const char *propName, WgtValueT *out);
bool wgtSetProp(WidgetT *w, const char *propName, const WgtValueT *value);
bool wgtCallMethod(WidgetT *w, const char *methodName, const WgtValueT *args, int32_t argc, WgtValueT *ret);
By name on any widget, through its interface (wgtGetIfaceOf). False when the widget has no interface or no such property or method, otherwise as wgtIfaceGetProp / wgtIfaceSetProp / wgtIfaceCallMethod. wgtCallMethod takes the method of the name whose argument count is argc (wgtIfaceFindMethodArgs), else the first of the name.
WgtValueT v = wgtValueStr("Right");
WgtValueT item = wgtValueStr("one");
WgtValueT count;
wgtSetProp(label, "Alignment", &v);
wgtCallMethod(list, "AddItem", &item, 1, NULL);
wgtCallMethod(list, "ListCount", NULL, 0, &count);
wgtIfaceGetProp / wgtIfaceSetProp
bool wgtIfaceGetProp(const WgtIfaceT *iface, WidgetT *w, const WgtPropDescT *p, WgtValueT *out);
bool wgtIfaceSetProp(const WgtIfaceT *iface, WidgetT *w, const WgtPropDescT *p, const WgtValueT *value);
Read or write property p (from iface’s props[]) of w. A read is false when p is write-only or the dynamic hook failed (out is then the zero value of p’s type); a STRING read is never NULL. A write converts value to p’s type (wgtValueTo*; a STRING for an ENUM property is looked up in enumNames, case-insensitive) and is false when p is read-only, an enum name is unknown, an enum number has no name (a C widget’s), a checked setter refused the value, or the dynamic hook refused.
wgtIfaceGetPropText / wgtIfaceSetPropText
bool wgtIfaceGetPropText(const WgtIfaceT *iface, WidgetT *w, const WgtPropDescT *p, char *out, int32_t outSize);
bool wgtIfaceSetPropText(const WgtIfaceT *iface, WidgetT *w, const WgtPropDescT *p, const char *text);
The same through the .frm / property-sheet text form: ENUM by value name, INT decimal, BOOL wgtParseBool (written "True" / "False"), FLOAT strtod / %g, STRING as it is. A read fails for an enum value that has no name.
wgtIfaceCallMethod
bool wgtIfaceCallMethod(const WgtIfaceT *iface, WidgetT *w, const WgtMethodDescT *m, const WgtValueT *args, int32_t argc, WgtValueT *ret);
Call method m with argc arguments, converted to the signature’s types (wgtSigInfo); extra arguments are ignored. ret (may be NULL) receives the result, type WGT_IFACE_NONE for a void method. Returns false without calling when fewer arguments than the signature needs were given (ret is then the zero value of the result type), when a dynamic method does not take argc arguments (wgtIfaceMethodArgs), when a checked method found an argument out of range, and when a dynamic method failed.
2.14.17. Custom Events
wgtFireEvent
bool wgtFireEvent(WidgetT *w, const char *name, WgtValueT *args, int32_t argc);
Fire event name on w. The universal events go to their WidgetT callback with their arguments taken from args (a missing one is 0): Click -> onClick, DblClick -> onDblClick, Change -> onChange, GotFocus -> onFocus, LostFocus -> onBlur, KeyPress (KeyAscii) -> onKeyPress, KeyDown / KeyUp (KeyCode, Shift) -> onKeyDown / onKeyUp, MouseDown / MouseUp / MouseMove (Button, X, Y, or the VB form Button, Shift, X, Y) -> onMouseDown / onMouseUp / onMouseMove (which take no Shift), Scroll (Delta) -> onScroll (names case-insensitive). Every other name goes to w->onEvent; the universal names never do, so a host that sets both sees each event once. Validate is not mapped (onValidate answers a question; fire it directly). onEvent may write back into args (ByRef parameters; the form runtime writes every ByRef parameter back, a String as text that stays valid until the next event). Returns false when a handler destroyed widgets — do not touch w then.
ListView (ColumnClick), TextArea (GutterClick), and HelpView (LinkClick) fire their own events this way after their C callbacks (wgtListViewSetHeaderClickCallback, wgtTextAreaSetGutterClick, wgtHelpViewSetLinkCallback), which stay for C programs; the event is skipped when the C callback destroyed widgets. A TextArea’s gutter takes clicks when either is set.
2.14.18. Property Data Type Constants
| Define | Value | Description |
|---|---|---|
WGT_IFACE_STRING |
0 |
const char * |
WGT_IFACE_INT |
1 |
int32_t |
WGT_IFACE_BOOL |
2 |
bool |
WGT_IFACE_FLOAT |
3 |
float (WgtValueT: double) |
WGT_IFACE_ENUM |
4 |
int32_t with named values |
WGT_IFACE_NONE |
5 |
WgtValueT only: no value |
WGT_IFACE_DOUBLE |
6 |
double (BASIC Double) |
2.14.19. Create Function Signature Constants
| Define | Value | Form |
|---|---|---|
WGT_CREATE_PARENT |
0 |
fn(parent) |
WGT_CREATE_PARENT_TEXT |
1 |
fn(parent, const char *text) |
WGT_CREATE_PARENT_INT |
2 |
fn(parent, int32_t) |
WGT_CREATE_PARENT_INT_INT |
3 |
fn(parent, int32_t, int32_t) |
WGT_CREATE_PARENT_INT_INT_INT |
4 |
fn(parent, int32_t, int32_t, int32_t) |
WGT_CREATE_PARENT_INT_BOOL |
5 |
fn(parent, int32_t, bool) |
WGT_CREATE_PARENT_BOOL |
6 |
fn(parent, bool) |
WGT_CREATE_PARENT_DATA |
7 |
fn(parent, data, w, h, pitch) — created by wgtCreateByName with no data: an empty picture |
WGT_MAX_CREATE_ARGS is 3.
2.15. dvxDlg.h — Modal Dialogs
Pre-built modal dialog boxes that block the caller and run their own event loop via dvxUpdate() until the user dismisses them. Modal dialogs make themselves the modal window (dvxModalBegin) to prevent input from reaching other windows for the dialog’s lifetime, and the window that was modal before is modal again after (dvxModalEnd), also when the dialog was taken away because its program was ended. Their OK (or first) and Cancel (or last) buttons are the window’s default and cancel buttons (dvxSetWindowButtons).
2.15.1. Message Box Flags
Button configurations (low nibble):
| Define | Value | Description |
|---|---|---|
MB_OK |
0x0000 |
OK button only (default) |
MB_OKCANCEL |
0x0001 |
OK and Cancel |
MB_YESNO |
0x0002 |
Yes and No |
MB_YESNOCANCEL |
0x0003 |
Yes, No, and Cancel |
MB_RETRYCANCEL |
0x0004 |
Retry and Cancel |
Icon types (high nibble, OR with button flags):
| Define | Value | Description |
|---|---|---|
MB_ICONINFO |
0x0010 |
Information icon |
MB_ICONWARNING |
0x0020 |
Warning icon |
MB_ICONERROR |
0x0030 |
Error icon |
MB_ICONQUESTION |
0x0040 |
Question mark icon |
Return values:
| Define | Value | Button pressed |
|---|---|---|
ID_OK |
1 |
OK |
ID_CANCEL |
2 |
Cancel, or the box closed (its close gadget, Alt+F4, its program ended), whatever its buttons |
ID_YES |
3 |
Yes |
ID_NO |
4 |
No |
ID_RETRY |
5 |
Retry |
2.15.2. dvxMessageBox
int32_t dvxMessageBox(AppContextT *ctx, const char *title, const char *message, int32_t flags);
Display a modal message box. Blocks the caller by running dvxUpdate() in a loop until a button is pressed or the dialog is closed. Enter presses the first button and Escape the last (OK, Cancel, or No). Closing the box instead (its close gadget, Alt+F4, its program ended) returns ID_CANCEL, whatever its buttons are, an MB_OK box’s too. The window is automatically destroyed on return.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title (NULL leaves the title bar empty) |
message |
Body text, word-wrapped (may contain '\n') |
flags |
MB_xxx button + icon flags, OR’d together |
Returns: ID_xxx of the button that was pressed, ID_CANCEL when the box was closed, or ID_CANCEL at once for a NULL ctx or message.
// Example: yes/no confirmation
int32_t r = dvxMessageBox(ctx, "Save", "Save changes before closing?", MB_YESNOCANCEL | MB_ICONQUESTION);
if (r == ID_YES) { saveFile(); }
2.15.3. dvxButtonBox
int32_t dvxButtonBox(AppContextT *ctx, const char *title, const char *message, int32_t iconFlags, const char * const *labels, int32_t count);
A message box with the caller’s own buttons, for a question the MB_xxx sets do not cover (for example Yes / No / Yes to All / Cancel). It looks and behaves like dvxMessageBox: Enter presses the first button, and Escape or closing the box chooses the last one, so make the last button the one that changes nothing. Each button is at least 80 pixels wide, wider for a long label, and the box is as wide as the message wraps to (320 pixels of content) or wider when its row of buttons needs it.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title (NULL leaves the title bar empty) |
message |
Body text (word-wrapped; may contain '\n') |
iconFlags |
One MB_ICONxxx value, or 0 for none |
labels |
Button labels; '&' marks the accelerator |
count |
Number of buttons, 1 to DVX_BUTTON_BOX_MAX (6) |
Returns: the index in labels of the button chosen, or -1 for bad arguments.
static const char *const labels[] = { "&Retry", "&Skip", "&Cancel" };
int32_t pick = dvxButtonBox(ctx, "Copy", "The disk is full.", MB_ICONERROR, labels, 3);
2.15.4. dvxErrorBox
int32_t dvxErrorBox(AppContextT *ctx, const char *title, const char *message);
Convenience wrapper for MB_OK | MB_ICONERROR. Title defaults to "Error" when NULL.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Dialog title, or NULL for "Error" |
message |
Error message |
Returns: ID_OK, or ID_CANCEL when the box was closed rather than answered (see dvxMessageBox).
2.15.5. dvxInfoBox
int32_t dvxInfoBox(AppContextT *ctx, const char *title, const char *message);
Convenience wrapper for MB_OK | MB_ICONINFO. Title defaults to "Information" when NULL.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Dialog title, or NULL for "Information" |
message |
Informational message |
Returns: ID_OK, or ID_CANCEL when the box was closed rather than answered (see dvxMessageBox).
2.15.6. File Dialog
FileFilterT
Describes a filter entry in the file dialog’s format dropdown. The glob pattern is extracted from inside the parentheses. Patterns are case-insensitive, may be a semicolon-separated list, and support '*' and '?' anywhere ("readme*", "a*.txt", "*.*" matches every file); blank entries in a list are ignored. A label without parentheses is itself the pattern when it contains a wildcard; otherwise it matches every file.
| Field | Description |
|---|---|
label |
e.g. "Text Files (*.txt)" or "Pictures (" DVX_IMAGE_PATTERNS ")" |
File Dialog Flags
| Define | Value | Description |
|---|---|---|
FD_OPEN |
0x0000 |
File open dialog (default): only a file that exists is taken |
FD_SAVE |
0x0001 |
File save dialog (with overwrite prompt) |
FD_FOLDER |
0x0002 |
Choose a folder, new or existing |
FD_CREATE |
0x0004 |
With FD_OPEN: a name that is no file is taken after "NAME does not exist. Do you want to create it?" (title "Confirm Create"); the caller makes the file |
FD_NAME |
0x0008 |
Not with FD_FOLDER: outPath holds a file name to suggest on entry (such as Untitled.txt); the name box starts with it, focused and selected, so Enter takes it and typing replaces it |
dvxFileDialog
bool dvxFileDialog(AppContextT *ctx, const char *title, int32_t flags, const char *initialDir, const FileFilterT *filters, int32_t filterCount, char *outPath, int32_t outPathSize);
Display a modal file open/save dialog. Shows a directory listing with parent/drive-letter navigation, a drive dropdown, a filename input, and an optional filter dropdown. The path box always shows the current folder, and the drive dropdown (platformDriveList, so listing the drives never touches empty floppy or CD-ROM drives) its drive; choosing a drive goes to its root, and a drive that cannot be read shows "Drive X: is not ready." and leaves the dialog where it was. Typing "D:" or "D:folder" in the path box changes drive/folder; the file name box also accepts a relative or absolute path ("sub\x.txt", "C:\X\A.TXT") and navigates to its folder. A folder that does not exist shows an "Invalid Path" error. An open dialog takes only a file that exists: another name shows "NAME does not exist. Check the file name and try again." (title "File Not Found") and the dialog stays open, unless FD_CREATE is given too, for a program that makes the file it is given. A save dialog asks "NAME already exists. Do you want to replace it?" (title "Confirm Save") before giving back a file that exists. A path that would not fit outPath (outPathSize, its NUL included) shows "The path is too long." (title "Invalid Filename", or "Invalid Folder" in a folder dialog) and the dialog stays open, so true always means outPath holds the whole path. The keyboard starts in the file name box, as in Windows. With FD_NAME the name box starts with the name the caller put in outPath, selected (without it, outPath is only written, so a buffer that was never set is fine). The dialog closes at once if the app that owns it is ended. BASIC: DlgFileSaveAs$ (commdlg.bas) suggests a name.
With FD_FOLDER the dialog chooses a folder: the list shows folders only (filters are not used), the name box is "Folder name", and OK returns the folder shown, or the folder of the typed name in it (or the typed path itself when it is absolute). That folder need not exist yet; the caller makes it (platformMkdirRecursive). A name that is a file shows an "Invalid Folder" error, and so does a new name the disk cannot hold. An initialDir that does not exist yet opens at its nearest existing folder with the rest already in the name box, so OK alone returns initialDir unchanged. The default title is "Choose a Folder".
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title (NULL = "Open", "Save As", or "Choose a Folder") |
flags |
FD_OPEN (with FD_CREATE or not), FD_SAVE, or FD_FOLDER; FD_NAME with FD_OPEN or FD_SAVE |
initialDir |
Starting directory (NULL = current working directory) |
filters |
Array of FileFilterT, or NULL |
filterCount |
Number of filter entries |
outPath |
Output buffer for selected path (with FD_NAME, the name to suggest on entry) |
outPathSize |
Capacity of outPath buffer, its NUL included (a longer path is refused) |
Returns: true if the user selected a file (or folder), false if canceled or closed.
2.15.7. Input Boxes
dvxInputBox
bool dvxInputBox(AppContextT *ctx, const char *title, const char *prompt, const char *defaultText, char *outBuf, int32_t outBufSize);
Display a modal input box with a prompt label, text field, and OK/Cancel buttons. The prompt is word-wrapped to the dialog width and may contain '\n'. The defaultText starts selected, as in Windows: typing replaces it, Enter keeps it, and End or an arrow key goes on from it. The field accepts at most outBufSize - 1 characters (capped at 4096), so the caller receives exactly what was typed. An outBufSize below 2 (no room for any input) returns false without showing the dialog.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title |
prompt |
Prompt label above the input field |
defaultText |
Initial text (NULL = empty) |
outBuf |
Output buffer |
outBufSize |
Capacity of outBuf |
Returns: true if OK was pressed, false if canceled.
dvxIntInputBox
bool dvxIntInputBox(AppContextT *ctx, const char *title, const char *prompt, int32_t defaultVal, int32_t minVal, int32_t maxVal, int32_t step, int32_t *outVal);
Display a modal integer input box with a spinner (up/down arrows) for clamped numeric input.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title |
prompt |
Prompt label |
defaultVal |
Initial value |
minVal |
Minimum allowed value |
maxVal |
Maximum allowed value |
step |
Increment per arrow click |
outVal |
Output: entered value |
Returns: true if OK pressed, false if canceled.
2.15.8. Choice Dialog
dvxChoiceDialog
bool dvxChoiceDialog(AppContextT *ctx, const char *title, const char *prompt, const char **items, int32_t itemCount, int32_t defaultIdx, int32_t *outIdx);
Display a modal dialog with a listbox of choices. The user picks one item and clicks OK, or cancels.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title |
prompt |
Prompt label above the list |
items |
Array of choice strings |
itemCount |
Number of items |
defaultIdx |
Initially highlighted item (-1 = none) |
outIdx |
Output: selected index |
Returns: true if a choice was made, false if canceled.
2.15.9. Color Dialog
dvxColorDialog
bool dvxColorDialog(AppContextT *ctx, const char *title, uint32_t *rgbInOut);
Display a modal color picker: a palette of 48 basic colors, Red, Green, and Blue sliders each paired with a number box (0-255), and a preview swatch. Clicking a basic color sets all three channels; the basic color matching the current color is framed. From the keyboard, Tab moves between the sliders and number boxes (the Red slider has the focus first), the arrow keys, Page Up/Down, Home, and End move a slider, and Enter chooses OK. Works at every color depth; on 8-bit desktops the swatches show the nearest palette colors, but the chosen value is exact.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title (NULL: "Color") |
rgbInOut |
In: the starting color; out: the chosen color. Both 0x00RRGGBB (DVX BASIC’s colors are &HBBGGRR; wgtBasicColor converts between the two) |
Returns: true if OK was chosen, false if canceled or closed (then *rgbInOut is unchanged).
Macros for the 0x00RRGGBB layout (dvxVideo.h): DVX_RGB(r, g, b) builds a color from three 0-255 channels, and DVX_RGB_RED(rgb), DVX_RGB_GREEN(rgb), and DVX_RGB_BLUE(rgb) take one apart.
uint32_t rgb = DVX_RGB(r, g, b);
if (dvxColorDialog(ctx, "Title Bar", &rgb)) {
dvxSetColor(ctx, ColorActiveTitleBgE, DVX_RGB_RED(rgb), DVX_RGB_GREEN(rgb), DVX_RGB_BLUE(rgb));
}
2.15.10. Font Dialog
dvxFontDialog
bool dvxFontDialog(AppContextT *ctx, const char *title, uint32_t flags, DvxFontChoiceT *choiceInOut);
Display a modal font picker: lists of the font families (dvxText.h), the four styles (Regular, Bold, Italic, and Bold Italic), and the sizes the chosen family comes in for the chosen style; Underline and Strikeout boxes; and a sample drawn in the chosen font as it changes. Choosing another family or style keeps the size nearest the one chosen. The labels' underlined letters move to the lists from the keyboard; Enter chooses OK.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title (NULL: "Font") |
flags |
DVX_FONT_DLG_FIXED: offer only fixed-pitch families (for a text editor or a terminal) |
choiceInOut |
In: the starting font (a family there is none of starts on "System"); out: the chosen one |
DvxFontChoiceT holds family (FONT_FAMILY_MAX characters with the NUL), size (pixels), and style (FONT_STYLE_* bits, the lines included) — what wgtSetFont and dvxFontOpen take.
Returns: true if OK was chosen, false if canceled or closed (then *choiceInOut is unchanged).
DvxFontChoiceT choice = { "DejaVu Sans", 14, FONT_STYLE_BOLD };
if (dvxFontDialog(ctx, NULL, 0, &choice)) {
wgtSetFont(label, choice.family, choice.size, choice.style);
}
2.15.11. Custom Dialogs
Any dialog built from widgets, with the behavior of the boxes above: modal, Enter chooses OK (unless the focused control uses Enter itself: a button presses itself, an open drop-down list takes its choice, multi-line text gets a new line; see widgetUsesEnter), Escape or closing the window cancels, a nested dialog (a Browse button, an error box) works, and the dialog ends cleanly if its program is ended meanwhile.
typedef bool (*DvxDialogOkFnT)(WindowT *dlg, void *userCtx);
WindowT *dvxDialogCreate(AppContextT *ctx, const char *title, int32_t contentW);
WidgetT *dvxDialogAddField(WindowT *dlg, const char *label, int32_t labelW, int32_t maxLen, const char *value);
void dvxDialogAddOkCancel(WindowT *dlg, const char *okLabel, DvxDialogOkFnT onOk, void *userCtx);
void dvxDialogEnd(WindowT *dlg, bool accepted);
bool dvxDialogRun(AppContextT *ctx, WindowT *dlg);
dvxDialogCreate makes an empty, modal, not resizable dialog whose content area is contentW pixels wide (NULL on failure; title NULL for none); add widgets under dlg->widgetRoot, or labeled text boxes with dvxDialogAddField. dvxDialogAddOkCancel adds the right-aligned OK (labeled okLabel, "&OK" when NULL) and Cancel buttons after them. dvxDialogRun sizes the dialog — contentW wide (the root widget’s minW), or wider when the widgets need more, and as tall as the widgets — centers it, runs it, and destroys it; it returns true when it ended with OK. Every created dialog must be run.
The dialog window is DVX’s own: its userData holds the dialog’s state (dvxDialogEnd and the OK button find it there), and it has DVX’s onKey (Enter and Escape) and onClose (closing cancels). Leave those three alone; keep the program’s own state in onOk’s userCtx, or in the widgets' userData.
dvxDialogAddField adds a row: a label labelW pixels wide and a text box of up to maxLen characters holding value, filling the rest of the row. It returns the text box (NULL on failure); the box’s parent is the row, so a Browse... button can be added after it with wgtButton(box->parent, ...). Give every field’s label the same labelW so the boxes line up.
onOk (may be NULL) runs when OK is chosen, while the widgets still exist: copy their values out and return true to close the dialog, or tell the user what is wrong and return false to keep it open. It is never called for Cancel.
dvxDialogEnd ends a running dialog from any of the caller’s own widget callbacks, such as a double-click in a list or an extra button: accepted true acts like OK (onOk runs first and can keep the dialog open), false like Cancel. Use it only on a dialog made by dvxDialogCreate.
static bool onOk(WindowT *dlg, void *userCtx) {
(void)dlg;
return dvxCopyTrimmed((char *)userCtx, NAME_MAX, wgtGetText(sName)) > 0;
}
WindowT *dlg = dvxDialogCreate(ctx, "Name", 240);
sName = dvxDialogAddField(dlg, "&Name:", 60, NAME_MAX - 1, "");
dvxDialogAddOkCancel(dlg, NULL, onOk, name);
if (dvxDialogRun(ctx, dlg)) {
// name holds the text
}
2.15.12. Save Prompt
Return codes for dvxPromptSave:
| Define | Value | Action |
|---|---|---|
DVX_SAVE_YES |
1 |
Save, then proceed |
DVX_SAVE_NO |
2 |
Discard, then proceed |
DVX_SAVE_CANCEL |
3 |
Abort the operation |
dvxPromptSave
int32_t dvxPromptSave(AppContextT *ctx, const char *title);
Display a canonical "Save changes?" dialog with Yes/No/Cancel buttons and the question icon. The message is always "Save changes?"; the title is only the window’s title, so a document’s name goes there. Enter answers Yes; Escape and closing the box cancel.
| Parameter | Description |
|---|---|
ctx |
Application context |
title |
Window title, such as the document’s name (NULL: "Save") |
Returns: DVX_SAVE_YES, DVX_SAVE_NO, or DVX_SAVE_CANCEL.
2.16. dvxRes.h — Resource System
2.16.1. dvxRes.h — DXE-Embedded Resource System
Resources are appended to DXE3 files (.app, .wgt, .lib) after the normal DXE content. The DXE loader never reads past its own header-specified sections, so the appended resource block is invisible to dlopen. This lets each DXE carry its own icons, localized text, help content, and binary data without separate resource files.
2.16.2. File Layout
[DXE3 content] -- untouched, loaded by dlopen [resource data entries] -- sequential, variable length [resource directory] -- fixed-size entries (48 bytes each) [footer] -- magic + directory offset + entry count (16 bytes)
Reading starts from the end: seek to EOF - sizeof(footer), verify the magic, then seek to the directory.
2.16.3. Constants
| Define | Value | Description |
|---|---|---|
DVX_RES_ICON |
1 |
A picture: BMP, PNG, JPEG, or GIF (icons included) |
DVX_RES_TEXT |
2 |
Null-terminated string |
DVX_RES_BINARY |
3 |
Arbitrary binary data (app-specific) |
DVX_RES_FONT |
4 |
A .DFN font the program carries (added for it when it loads; dvxText.h) |
DVX_RES_MAGIC |
0x52585644 |
Footer signature ("DVXR" little-endian) |
DVX_RES_NAME_MAX |
32 |
Max resource name length including null |
DVX_RES_ONLY_MAGIC |
"DVXRESONLY" |
First bytes (NUL included, DVX_RES_ONLY_MAGIC_LEN) of a file that holds only resources |
A file that starts with DVX_RES_ONLY_MAGIC has no code before its resources — a control written in DVX BASIC, installed as a .wgt (see Using BASIC Controls from C). The loader does not load such a widget file as a module: it registers the file’s controls by name, and the BASIC run-time library reads the file the first time one is needed.
2.16.4. Structures
DvxResDirEntryT
Directory entry describing one resource (48 bytes on disk).
| Field | Description |
|---|---|
name |
Resource name (up to 32 chars, null-terminated) |
type |
DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY |
offset |
Absolute file offset of the data |
size |
Data size in bytes |
reserved |
Padding (must be zero) |
2.16.5. Runtime API
dvxResOpen
DvxResHandleT *dvxResOpen(const char *path);
Open a resource handle by reading the footer and directory. Returns NULL if the file has no resource block or cannot be read. Entries are sorted on open for O(log n) name lookup via bsearch.
| Parameter | Description |
|---|---|
path |
Path to the DXE (or any file) with appended resources |
Returns: Handle pointer, or NULL.
dvxResRead
void *dvxResRead(DvxResHandleT *h, const char *name, uint32_t *outSize);
Find a resource by name and read its data into a freshly malloc’d buffer. Caller must free the returned buffer.
| Parameter | Description |
|---|---|
h |
Resource handle |
name |
Resource name |
outSize |
Output: data size in bytes |
Returns: Data buffer, or NULL if not found or I/O failed.
dvxResFind
const DvxResDirEntryT *dvxResFind(DvxResHandleT *h, const char *name);
Look up a resource’s directory entry by name. The returned pointer is valid until dvxResClose. A name of DVX_RES_NAME_MAX (32) or more characters never matches (names are not truncated to a prefix).
| Parameter | Description |
|---|---|
h |
Resource handle |
name |
Resource name |
Returns: Pointer to directory entry, or NULL if not found.
dvxResClose
void dvxResClose(DvxResHandleT *h);
Close a resource handle and free its memory.
| Parameter | Description |
|---|---|
h |
Handle to close |
dvxResAppend
int32_t dvxResAppend(const char *path, const char *name, uint32_t type, const void *data, uint32_t dataSize);
Append a resource to an existing DXE file. Preserves existing resources and adds the new one. Thin wrapper over the resource writer in tools/dvxResWrite.h.
| Parameter | Description |
|---|---|
path |
Target DXE path |
name |
Resource name (up to DVX_RES_NAME_MAX - 1 chars) |
type |
DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY |
data |
Resource payload |
dataSize |
Payload size in bytes |
Returns: 0 on success, -1 on failure.
dvxResRemove
int32_t dvxResRemove(const char *path, const char *name);
Remove a resource from a DXE file by name. The resource block is rewritten through a temporary file that is swapped in only when every write succeeded, so a failed write leaves the original file intact. If this was the last resource, the result is the bare DXE content with no resource block.
| Parameter | Description |
|---|---|
path |
Target DXE path |
name |
Resource name to remove (32 or more characters never matches) |
Returns: 0 on success, -1 if not found, the name is too long, or I/O failed.
2.17. dvxPrefs.h — Preferences System
2.17.1. dvxPrefs.h — INI Preferences System
Handle-based API over classic INI files. Each prefsLoad/prefsCreate returns a PrefsHandleT that must be passed to all subsequent calls and freed with prefsClose when done. Multiple INI files can be open simultaneously.
BASIC programs reach the same functions through prefs.bas (dvxPrefsBas.c in libdvx): PrefsLoad, PrefsCreate, PrefsGet$, PrefsGetInt, PrefsGetBool, PrefsSet, PrefsSetInt, PrefsSetBool, PrefsGetSecret$, PrefsSetSecret, PrefsRemove, PrefsKeyName$ (prefsKeyName, "" past the last key), PrefsApplyChanges (prefsApplyChanges; a before of 0 is empty), PrefsSave, PrefsSaveAs, and PrefsClose, on handles (1, 2, ...; 0 = none) that belong to the program that made them and are closed, unsaved, when it ends. True is -1, False 0. PrefsDvxIni$ is platformDvxIniPath() (the user folder’s DVX.INI), PrefsSetVideoMode is prefsSetVideoMode, and PrefsVideoWidth / PrefsVideoHeight / PrefsVideoBpp are the three values of prefsGetVideoMode (DVX_DEFAULT_VIDEO_* for a missing key or a bad handle). The choice tables below are PREFS_CHOICE_ACCEL (0), PREFS_CHOICE_WALLPAPER (1), and PREFS_CHOICE_WHEEL (2) there: PrefsChoiceCount, PrefsChoiceLabel$, PrefsChoiceName$ (iniName), PrefsChoiceValue, PrefsChoiceIndex, PrefsChoiceIndexOfValue, PrefsChoiceDefault (the index of the choice MOUSE_ACCEL_DEFAULT / WALLPAPER_MODE_DEFAULT / MOUSE_WHEEL_DIR_DEFAULT names; -1 for an unknown table), and PrefsGetChoice(handle, section, key, table) with the table’s default. PrefsGetChoiceFrom(handle, section, key, choiceNames, defaultName) is prefsGetChoice on a table the program gives as "|"-separated names (each choice’s iniName and label is its name, its value its index).
PrefsHandleT *prefsBasHandle(int32_t handle);
The settings behind a prefs.bas handle, NULL for 0 or a handle that is not open. Other libraries' BASIC entry points that take a prefs.bas handle (system.bas, joystick.bas, net.bas, print.bas, sound.bas) resolve it with this; libdvx is loaded first, so the symbol is always there.
2.17.2. The system INI
DVX’s own settings are in DVX.INI in the user folder: prefsLoad(platformDvxIniPath()) (dvxPlat.h, DVX folders). The first start copies the shipped SYSTEM\DVX.INI there, with its comments and defaults; keys it does not have keep the defaults compiled into the code.
2.17.4. Lifecycle
prefsCreate
PrefsHandleT *prefsCreate(void);
Create an empty preferences handle with no associated file. Use this when building an INI from scratch before calling prefsSaveAs.
Returns: New handle, or NULL on allocation failure.
prefsDvxIniShared
PrefsHandleT *prefsDvxIniShared(void);
DVX.INI for reading, shared: parsed again only when the file’s text changed (its text is read and compared, a fraction of a parse), for code that reads settings often (every sound, every song). Its users do not close it, change it, or keep it past their own call: the next call may read the file again.
prefsLoad
PrefsHandleT *prefsLoad(const char *filename);
Load an INI file into a new handle. If the file does not exist but a backup copy left by an interrupted save does (same name with the extension replaced by ~ and its first two characters, e.g. DVX.~IN), the backup is read instead, so the next save restores the file. Otherwise a missing file gives a valid empty handle. Either way the path is stored so prefsSave can write the file later.
File format rules:
-
Lines of any length are read without truncation; LF and CR LF endings are accepted.
-
"[name]" starts a section; "key = value" is a key (blanks around key and value are trimmed). Keys before the first section belong to section "".
-
Section and key names match case-insensitively. With duplicates, the first one wins.
-
Blank lines, ';' and '#' comments, and lines that are neither a section nor a key are kept.
-
On save, every line not changed through the API (comments, unknown lines, untouched keys, and headers) keeps its content; changed or new keys are written as "key = value". Every line is written with CR LF endings, so a file with LF-only endings is rewritten in full.
| Parameter | Description |
|---|---|
filename |
Path to INI file |
Returns: Handle, or NULL for a NULL filename or on allocation failure.
prefsSave
bool prefsSave(PrefsHandleT *h);
Save the in-memory state back to the file that was loaded (or captured by prefsLoad for a non-existent file). Returns false and writes nothing when the file existed but could not be read by prefsLoad, so an unreadable file is never replaced by defaults. Uses the same crash-safe write as prefsSaveAs.
| Parameter | Description |
|---|---|
h |
Preferences handle |
Returns: true on success.
prefsLoadFailed
bool prefsLoadFailed(const PrefsHandleT *h);
True when the file prefsLoad was given exists but could not be read: the handle holds none of its settings and prefsSave refuses to replace it. A program that writes the file anew with prefsSaveAs checks it first, so it never overwrites what it could not read. False for NULL. BASIC: PrefsLoadFailed in prefs.bas.
prefsSaveAs
bool prefsSaveAs(PrefsHandleT *h, const char *filename);
Save to a specific file, overriding the handle’s stored path. The data is written to a sibling file whose extension is replaced by $ and the first two characters of the original extension (8.3-safe, e.g. DVX.INI -> DVX.$IN) and swapped in only after every write succeeded; the previous file is parked as DVX.~IN during the swap and then removed. A failed save (disk full, write error) returns false and leaves the previous file intact. When DVX runs from read-only media (platformIsReadOnly), a file that cannot be written is kept in memory instead (the save returns true) and prefsLoad of the same path reads that copy until DVX exits.
| Parameter | Description |
|---|---|
h |
Preferences handle |
filename |
Output file path |
Returns: true on success.
prefsMemorySaves
uint32_t prefsMemorySaves(void);
How many saves only memory could keep (prefsSave and prefsSaveAs while platformIsReadOnly; wraps around). The shell compares it at the top of its main loop and, the first time in a session that it changed after the start-up notice, tells the user that their changes last only until DVX exits. A BASIC program that needs to know asks FileOpsReadOnlySystem: while it is True, every save is one of these.
2.17.5. Getters
prefsGetString
const char *prefsGetString(PrefsHandleT *h, const char *section, const char *key, const char *defaultVal);
Retrieve a string value from [section]/key. The returned pointer is valid until the key is modified or the handle is closed.
| Parameter | Description |
|---|---|
h |
Preferences handle |
section |
Section name (without brackets) |
key |
Key name |
defaultVal |
Returned if the key is not present |
Returns: Key value or defaultVal.
prefsGetInt
int32_t prefsGetInt(PrefsHandleT *h, const char *section, const char *key, int32_t defaultVal);
Retrieve an integer value. Supports decimal and negative numbers.
| Parameter | Description |
|---|---|
h |
Preferences handle |
section |
Section name |
key |
Key name |
defaultVal |
Returned if the key is absent or non-numeric |
Returns: Parsed int, or defaultVal.
prefsGetBool
bool prefsGetBool(PrefsHandleT *h, const char *section, const char *key, bool defaultVal);
Retrieve a boolean value. The whole value must be "true", "yes", or "1" (true) or "false", "no", or "0" (false), in any case; anything else (e.g. "t", "10", "normal") returns defaultVal.
| Parameter | Description |
|---|---|
h |
Preferences handle |
section |
Section name |
key |
Key name |
defaultVal |
Returned if the key is absent or unrecognized |
Returns: Parsed bool, or defaultVal.
prefsGetSecret
void prefsGetSecret(PrefsHandleT *h, const char *section, const char *key, char *out, int32_t outSize);
Read back a secret prefsSetSecret stored, into out (cut to outSize - 1 characters and always terminated; nothing is written when outSize is 0 or less). A missing key, or a NULL handle, gives "". A value prefsSetSecret did not write (one typed into the file by hand: no leading "*", or not hex digits after it) is copied as it is, so a password can be put in the file by hand and is scrambled the next time the program saves it.
| Parameter | Description |
|---|---|
h |
Preferences handle |
section |
Section name |
key |
Key name |
out |
Receives the text |
outSize |
Size of out in bytes |
prefsGetVideoMode / prefsSetVideoMode
void prefsGetVideoMode(PrefsHandleT *h, int32_t *width, int32_t *height, int32_t *bpp);
void prefsSetVideoMode(PrefsHandleT *h, int32_t width, int32_t height, int32_t bpp);
Read or store the [video] display mode DVX starts in (keys width, height, and bpp). Missing keys read as DVX_DEFAULT_VIDEO_W/H/BPP (640x480, 16 bpp). The one place those key names live: the shell (start-up and safe video mode), the Control Panel, and Setup all go through these two functions.
2.17.6. Setters
prefsSetString
void prefsSetString(PrefsHandleT *h, const char *section, const char *key, const char *value);
Set a string value. Creates the section and key if they do not already exist; a new key is placed after the section’s last key (not after trailing comments that belong to the next section). A NULL value is stored as an empty string.
prefsSetInt
void prefsSetInt(PrefsHandleT *h, const char *section, const char *key, int32_t value);
Set an integer value (stored in decimal).
prefsSetBool
void prefsSetBool(PrefsHandleT *h, const char *section, const char *key, bool value);
Set a boolean value (stored as "true"/"false").
prefsSetSecret
void prefsSetSecret(PrefsHandleT *h, const char *section, const char *key, const char *value);
Store a secret, such as a password, so it cannot be read at a glance: "*", a 32-bit salt as 8 hex digits, then each byte of the text XORed with an xorshift32 keystream started from the salt, as 2 hex digits. Each call takes a new salt (clock(), time(), and a call count), so the same text is stored differently each time. This is obfuscation, not encryption: anyone with this code can read the value back, so the file still needs the care of any file holding a password. An empty or NULL value is stored as "". prefsGetSecret reads it back.
prefsRemove
void prefsRemove(PrefsHandleT *h, const char *section, const char *key);
Remove a key from a section. No-op if the key does not exist.
prefsKeyName
const char *prefsKeyName(PrefsHandleT *h, const char *section, int32_t index);
Name of the index-th distinct key (0-based, file order) in a section, or NULL past the last one (and for a NULL handle or section or a negative index), so a section with keys not known in advance can be walked. A key repeated in the section counts once: the first, which the getters read. The pointer is valid until the key is removed or prefsClose.
for (int32_t i = 0; (key = prefsKeyName(h, "associations", i)) != NULL; i++) {
printf("%s = %s\n", key, prefsGetString(h, "associations", key, ""));
}
prefsApplyChanges
void prefsApplyChanges(PrefsHandleT *h, PrefsHandleT *before, PrefsHandleT *after);
Make in h only the changes that turn before into after: every key of after that before lacks or holds with another value is set in h, and every key of before that after lacks is removed from h. Keys the two agree on are left in h as they are, spelling and all. Section and key names compare in any case, values exactly; a key repeated in a section counts once (the first). A NULL before counts as empty, so every key of after is set; a NULL h or after changes nothing. h must be a third handle.
This is how a settings window saves without undoing what changed in the file while it was open (another program’s save, a hand edit): it stores its settings into a prefsCreate handle when it opens, stores them again into another on OK, then loads the file afresh, applies the difference, and saves. The Control Panel saves DVX.INI this way.
PrefsHandleT *disk = prefsLoad(platformDvxIniPath());
prefsApplyChanges(disk, opened, now);
ok = prefsSave(disk);
prefsClose(disk);
2.17.7. Shared Preference Vocabularies
Enumerated preferences are stored in DVX.INI by name. One table per preference is the single source of truth for the label the Control Panel shows, the spelling written to the INI, and the value applied.
typedef struct {
const char *label; // user-facing text (dropdown item)
const char *iniName; // spelling stored in the INI
int32_t value; // value applied
} PrefsChoiceT;
extern const PrefsChoiceT prefsAccelChoices[PREFS_ACCEL_CHOICE_COUNT];
extern const PrefsChoiceT prefsWallpaperChoices[PREFS_WALLPAPER_CHOICE_COUNT];
extern const PrefsChoiceT prefsWheelDirChoices[PREFS_WHEEL_DIR_CHOICE_COUNT];
| Table | INI key | Entries (iniName: value) | Default |
|---|---|---|---|
prefsAccelChoices |
[mouse] acceleration |
off, low, medium, high: MOUSE_ACCEL_* threshold |
MOUSE_ACCEL_DEFAULT ("medium") |
prefsWallpaperChoices |
[desktop] mode |
stretch, tile, center: WallpaperModeE (indexed by it) |
WALLPAPER_MODE_DEFAULT ("stretch") |
prefsWheelDirChoices |
[mouse] wheel |
normal: 1, reversed: -1 (MOUSE_WHEEL_DIR_*) |
MOUSE_WHEEL_DIR_DEFAULT ("normal") |
The entry counts are PREFS_ACCEL_CHOICE_COUNT (4), PREFS_WALLPAPER_CHOICE_COUNT (3), and PREFS_WHEEL_DIR_CHOICE_COUNT (2). MOUSE_WHEEL_DIR_NORMAL (1) and MOUSE_WHEEL_DIR_REVERSED (-1) in dvxTypes.h are also the wheelDir values for dvxSetMouseConfig.
Labels are the capitalized names ("Off", "Stretch", "Reversed", ...). The accel table is in dropdown order. dvxMouseFromPrefs and dvxWallpaperFromPrefs (dvxApp.h) read [mouse] wheel, [mouse] acceleration, and [desktop] mode through prefsGetChoice, and the Control Panel builds its dropdowns from the same tables.
prefsChoiceIndex
int32_t prefsChoiceIndex(const PrefsChoiceT *choices, int32_t count, const char *name);
Return the index of the choice whose iniName equals name (case-insensitive), or -1 when there is none (also for a NULL name).
prefsChoiceIndexOfValue
int32_t prefsChoiceIndexOfValue(const PrefsChoiceT *choices, int32_t count, int32_t value);
Return the index of the choice whose value equals value, or -1 when there is none. A dropdown built from a choice table selects this index for the current setting.
prefsChoiceLabels
void prefsChoiceLabels(const PrefsChoiceT *choices, int32_t count, const char **labels);
Fill labels[0..count-1] with the choices' labels, for wgtDropdownSetItems. No strings are copied: the pointers are the table’s own.
prefsGetChoice
int32_t prefsGetChoice(PrefsHandleT *h, const char *section, const char *key, const PrefsChoiceT *choices, int32_t count, const char *defaultName);
Return the index of the choice named by the key’s value; the index of defaultName when the key is missing or holds an unknown name. Use choices[index].value for the value to apply.
2.18. dvxMem.h — Memory Tracking
2.18.1. dvxMem.h — Per-App Memory Tracking
Wraps malloc/free/calloc/realloc/strdup/strndup with a 16-byte header that records the owning app ID and allocation size. The Task Manager displays per-app memory usage. The accounting is all it is: when an app ends, what it still has allocated is logged and its count starts over, and nothing it allocated is freed for it.
DXE code does NOT need to include this header for tracking to work. The DXE export table maps malloc/free/calloc/realloc/strdup/strndup to these wrappers transparently. Call sites that need the explicit dvxXxx names (e.g. dvxMemGetAppUsage) or the dvxMemAppIdPtr declaration should include dvxMem.h directly.
2.18.3. Allocation Wrappers
dvxMalloc
void *dvxMalloc(size_t size);
Tracked malloc. Returns a pointer to user memory (header is hidden in front of it).
dvxRealloc
void *dvxRealloc(void *ptr, size_t size);
Tracked realloc. A pointer the wrappers did not allocate (its header magic does not match: memory the C library allocated itself, such as asprintf’s) is passed to the C library’s realloc and stays untracked, as dvxFree passes it to free.
2.18.4. Accounting
dvxMemGetAppUsage
uint32_t dvxMemGetAppUsage(int32_t appId);
Return the total bytes currently charged to the given app ID.
| Parameter | Description |
|---|---|
appId |
App ID to query |
Returns: Bytes allocated for this app.
dvxMemGetRetained
uint32_t dvxMemGetRetained(void);
Return the bytes that apps which have ended left allocated. dvxMemResetApp starts an ended app’s count over without freeing anything, so that app’s figure going back to 0 does not mean its memory came back: what it left is added here, and is subtracted again only if its owner frees the block later. The Task Manager shows the figure when it is not 0.
Returns: Bytes still allocated that no running app’s dvxMemGetAppUsage counts.
dvxMemResetApp
void dvxMemResetApp(int32_t appId);
Start the given app’s accounting over: its usage reads 0, and a block it allocated that is freed later is not subtracted again (the block carries the old generation). What was still charged to it is logged first ("Memory: program <id> ended with <n> bytes still allocated to it; they stay until DVX exits"), and the atexit handlers it never ran (it was ended by force) are dropped. Nothing is freed: a library’s buffers made while the app ran stay valid, and what was left is counted by dvxMemGetRetained from then. The shell calls it when an app ends, however it ends.
| Parameter | Description |
|---|---|
appId |
App ID to flush |
dvxMemSetApp
int32_t dvxMemSetApp(int32_t appId);
Make appId the current app (the one what is allocated from now is charged to, as the shell sees it too) and return the one before, to set back afterwards. A library keeps its own memory as DVX’s (DVX_MEM_SYSTEM, 0) whichever app’s call made it, so the Task Manager does not charge a cache or a font to the program that happened to ask first; the audio library calls a program’s callback as that program. Without a shell (host tools) nothing changes and 0 comes back.
int32_t prev = dvxMemSetApp(DVX_MEM_SYSTEM);
// ... allocations that belong to the library ...
dvxMemSetApp(prev);
2.19. dvxEndian.h — Byte Order
File formats and wire protocols fix their byte order. These inline functions read and write it a byte at a time, so they work at any alignment and on any computer. Header only: include it and call, nothing to link.
uint16_t dvxGetBe16(const uint8_t *p);
uint32_t dvxGetBe32(const uint8_t *p);
uint16_t dvxGetLe16(const uint8_t *p);
uint32_t dvxGetLe24(const uint8_t *p);
uint32_t dvxGetLe32(const uint8_t *p);
void dvxPutBe32(uint8_t *p, uint32_t v);
void dvxPutLe16(uint8_t *p, uint32_t v);
void dvxPutLe32(uint8_t *p, uint32_t v);
Get reads the value at p, high byte first (Be) or low byte first (Le); Put writes v at p the same way (dvxPutLe16 writes the low 16 bits of v). Cast a load to a signed type for a signed field, for example (int16_t)dvxGetLe16(p) for a 16-bit sample.
2.20. dvxHash.h — Hashes and Checksums
2.20.2. FNV-1a
#define DVX_FNV_BASIS 2166136261u
#define DVX_FNV_PRIME 16777619u
uint32_t dvxFnvByte(uint32_t hash, uint8_t byte);
uint32_t dvxFnvBytes(uint32_t hash, const void *data, int32_t len);
Start from DVX_FNV_BASIS and fold in bytes. dvxFnvByte takes one, so a caller can fold case or skip characters as it goes; dvxFnvBytes takes len bytes. Both return the hash carried on.
2.20.3. CRC-16-CCITT
uint16_t dvxCrc16(uint16_t crc, const uint8_t *data, int32_t len);
The CRC of len bytes (polynomial 0x1021, high bit first), carried on from crc, computed a byte at a time without a table. Seed 0 for XMODEM and ZMODEM, 0xFFFF for CCITT-FALSE (the serial packet layer’s).
2.20.4. Hex Digits
#define DVX_HEX_DIGITS "0123456789abcdef"
#define DVX_HEX_RADIX 16
#define DVX_NIBBLE_BITS 4
#define DVX_NIBBLE_MASK 0x0F
int32_t dvxHexValue(int32_t c);
DVX_HEX_DIGITS[n] is the digit for the nibble n. dvxHexValue is a digit’s value (0 to 15, either case), -1 for any other character.
2.21. dvxWgtP.h — Widget Plugin API
Included by widget .c files (DXE modules) to access core infrastructure for tree manipulation, focus management, scrollbar drawing, layout helpers, and shared interaction state. This header is NOT intended for application code — use dvxWgt.h for the public widget API.
2.21.1. Validation Macros
VALIDATE_WIDGET / VALIDATE_WIDGET_VOID
VALIDATE_WIDGET(w, wtype, retval); // returns retval on mismatch
VALIDATE_WIDGET_VOID(w, wtype); // returns void on mismatch
Bail out of a widget method if the widget pointer is NULL or its type does not match the expected wtype. Use at the top of every widget-specific API function.
2.21.2. Core Constants
| Define | Value | Description |
|---|---|---|
DEFAULT_SPACING |
4 |
Default pixel spacing between VBox/HBox children |
DEFAULT_PADDING |
4 |
Default internal padding for containers |
SB_MIN_THUMB |
14 |
Minimum scrollbar thumb size in pixels |
WGT_SB_W |
14 |
Widget-internal scrollbar width |
The KEY_MOD_* modifier bits are defined in dvxTypes.h (see Accelerator Modifier Flags).
2.21.3. Inline Helpers
clampInt
static inline int32_t clampInt(int32_t val, int32_t lo, int32_t hi);
Clamp val into the [lo, hi] range.
drawTextEmbossed
static inline void drawTextEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors);
Draw text twice — once offset by (1,1) in highlight color, then overlaid in shadow color at (x,y) — for a classic Motif-style embossed look used on disabled labels.
drawTextAccelEmbossed
void drawTextAccelEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors);
Embossed text with & accelerator markers (declared in dvxDraw.h). Same offset logic as drawTextEmbossed, but processes & markers. drawWidgetTextAccel uses it for disabled widgets.
2.21.4. Shared Interaction State
Extern variables defined in widgetCore.c (sClosedPopup in widgetEvent.c, sKeyPressedBtn and sCursorBlinkFn in dvxApp.c). These hold system-wide widget state: only one focused widget, one open popup, one pressed button at a time.
| Variable | Type | Purpose |
|---|---|---|
sCursorBlinkOn |
bool |
Current state of the text cursor blink |
sDblClickTicks |
clock_t |
Double-click interval in clock() ticks |
sDebugLayout |
bool |
When true, draw colored debug borders around containers |
sClosedPopup |
WidgetT* |
Widget whose popup just closed (suppresses re-open) |
sFocusedWidget |
WidgetT* |
Currently focused widget |
sKeyPressedBtn |
WidgetT* |
Button being pressed via keyboard (for release tracking) |
sOpenPopup |
WidgetT* |
Currently open popup (dropdown/combo list) |
sDragWidget |
WidgetT* |
Widget being dragged (any drag type) |
sPollWidgets |
WidgetT** |
Dynamic array of poll widgets (stb_ds) |
sCursorBlinkFn |
fn ptr |
Callback invoked when the blink flips (repaints focused text) |
2.21.5. Core Widget Functions
widgetAlloc
WidgetT *widgetAlloc(WidgetT *parent, int32_t type);
Allocate a new WidgetT, initialize its fields to defaults, link it as the last child of parent (if non-NULL), and assign its class pointer from widgetClassTable[type].
widgetAddChild
void widgetAddChild(WidgetT *parent, WidgetT *child);
Append child to parent’s child list. Updates parent’s firstChild/lastChild and child’s nextSibling pointers.
2.21.6. Focus Management
widgetFindNextFocusable
WidgetT *widgetFindNextFocusable(WidgetT *root, WidgetT *after);
Find the next focusable widget in tab order after the given widget. Wraps to the beginning at the end of the tree.
widgetFindPrevFocusable
WidgetT *widgetFindPrevFocusable(WidgetT *root, WidgetT *before);
Find the previous focusable widget in tab order. Wraps to the end at the beginning of the tree.
widgetFindByAccel
WidgetT *widgetFindByAccel(WidgetT *root, char key);
Find a focusable widget whose accelKey (lowercase) matches the given character. Used for Alt+letter hotkeys on buttons and labels.
widgetRestoreFocus
bool widgetRestoreFocus(WindowT *win);
Give a shown window that holds the window manager’s focus, and in which no widget has the keyboard focus, its widget focus: the widget that had it when the window last lost focus, else the first focusable widget. Nothing for a hidden or unfocused window. widgetOnPaint runs it at each paint; a BASIC form’s Show runs it to choose the first focus there, as VB does, so code running after Show cannot change it. Returns false when a focus callback destroyed widgets.
widgetUsesEnter
bool widgetUsesEnter(const WidgetT *w);
True when the focused widget w uses Enter itself: a drop-down whose list is open, or a class with WCLASS_SWALLOWS_ENTER (Button, ImageButton, TextArea, RichEdit, Terminal, a help link). A window with a default button (DVX dialog boxes, a window with dvxSetWindowButtons, BASIC forms with a Default button) gives Enter to such a widget and otherwise presses the default button without passing the key on, as in Windows.
2.21.7. Hit Testing
widgetHitTest
WidgetT *widgetHitTest(WidgetT *w, int32_t x, int32_t y);
Find the deepest widget at (x, y) within w’s subtree. Respects WCLASS_NO_HIT_RECURSE: the search stops at such a container, whose class ON_MOUSE handler receives the press. A backdrop (wgtSetBackdrop) is never hit: the press is its parent’s. Hit testing ignores the enabled flag; event dispatch checks widgetIsEnabledChain on the result.
widgetCallbackTarget
WidgetT *widgetCallbackTarget(WidgetT *root, int32_t x, int32_t y);
Find the widget the universal callbacks (onClick, onDblClick, onMouseDown/Up/Move), context menus, tooltips, and the cursor shape go to. Starts from widgetHitTest; while the result is a non-focusable WCLASS_NO_HIT_RECURSE container (Splitter, ScrollPane), it continues into the child whose paintClip (the part actually visible when last painted) contains the point. Returns the container itself when the point is on its own chrome (divider, scrollbars) or no child is visible there.
2.21.8. Utility Queries
widgetCountVisibleChildren
int32_t widgetCountVisibleChildren(const WidgetT *w);
Count children whose visible flag is true.
widgetFrameBorderWidth
int32_t widgetFrameBorderWidth(const WidgetT *w);
Return the effective border width for a container widget (used to inset child layout).
widgetIsFocusable
bool widgetIsFocusable(int32_t type);
True if the widget class with this type ID has the WCLASS_FOCUSABLE flag.
2.21.9. Clipboard
2.21.10. Scrollbar Helpers
ScrollHitE
Scrollbar hit-test result (dvxTypes.h; window and widget scrollbars alike).
| Value | Description |
|---|---|
ScrollHitNoneE |
Click fell outside the scrollbar |
ScrollHitArrowDecE |
Up/left arrow |
ScrollHitArrowIncE |
Down/right arrow |
ScrollHitPageDecE |
Trough above/before the thumb |
ScrollHitPageIncE |
Trough below/after the thumb |
ScrollHitThumbE |
The draggable thumb |
widgetScrollbarThumb
void widgetScrollbarThumb(int32_t trackLen, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t *thumbPos, int32_t *thumbSize);
Compute thumb position and size for a scrollbar with the given geometry. Enforces SB_MIN_THUMB.
widgetDrawScrollbarV
void widgetDrawScrollbarV(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbH, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);
Draw a vertical scrollbar (WGT_SB_W wide) inside a widget.
widgetDrawScrollbarH
void widgetDrawScrollbarH(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbW, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);
Draw a horizontal scrollbar (WGT_SB_W high) inside a widget.
widgetScrollbarHitTest
ScrollHitE widgetScrollbarHitTest(int32_t sbLen, int32_t relPos, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);
Classify a click position along a scrollbar into ScrollHitE. sbLen is the scrollbar length, relPos is the click position along the bar.
widgetScrollbarApplyHit
bool widgetScrollbarApplyHit(int32_t sbLen, int32_t relPos, int32_t total, int32_t visible, int32_t lineStep, int32_t pageStep, int32_t *pPos, int32_t *outDragOff);
Apply a click on a widget scrollbar to the scroll position *pPos: an arrow moves it by lineStep, the trough by pageStep, and the result is clamped to [0, total - visible]. A click on the thumb leaves *pPos unchanged and returns true with *outDragOff set to the grab offset inside the thumb; the caller then starts its thumb drag (see widgetScrollbarThumbDragScroll). The one arrow/page/thumb dispatch shared by every scrollbar-owning widget. It asks widgetScrollbarPressStep first, so a held arrow or trough press repeats with no code in the widget: the dispatcher runs the widget’s ON_MOUSE again at the press point.
widgetScrollbarPressStep
bool widgetScrollbarPressStep(ScrollHitE zone);
Whether a press on part zone of a scrollbar steps it. Every press handler that steps a bar calls it first (widgetScrollbarApplyHit and the drop-down lists do). A real press always steps, and an arrow or trough part is noted: while the left button stays down, the event loop (widgetScrollRepeatPoll, every frame) runs the press handler again at the press point SCROLL_REPEAT_DELAY_MS after the press, then every SCROLL_REPEAT_RATE_MS, paused while the pointer is off the widget (or its open list). A repeated press steps only on the part it began on, so a trough repeat stops when the thumb reaches the press point and never begins a thumb drag.
widgetScrollbarThumbDragScroll
int32_t widgetScrollbarThumbDragScroll(int32_t trackLen, int32_t total, int32_t visible, int32_t relMouse, int32_t maxScroll);
Map a dragged thumb position to a scroll position in [0, maxScroll]. relMouse is where the thumb’s leading edge should be, relative to the start of a track of trackLen pixels (the mouse position minus the grab offset). Returns 0 when maxScroll <= 0.
widgetScrollbarNeeds
void widgetScrollbarNeeds(int32_t totalW, int32_t totalH, int32_t *innerW, int32_t *innerH, bool *needV, bool *needH);
Which scrollbars content totalW x totalH pixels needs in a viewport of *innerW x *innerH (the area inside the widget’s border). A vertical bar narrows the viewport, which may make the content too wide; a horizontal bar shortens it, which may make the content too tall; both cases are followed through. *innerW and *innerH come back less the bars (WGT_SB_W each). For rows of a fixed height pass rows * height: the content is too tall exactly when there are more rows than whole rows fit. ListBox, ListView, TreeView, ScrollPane, and DBGrid decide their bars with it; BASIC’s ScrollBarsNeeded is the same rule.
2.21.11. Layout Functions
widgetCalcMinSizeBox / widgetCalcMinSizeTree
void widgetCalcMinSizeBox(WidgetT *w, const BitmapFontT *font);
void widgetCalcMinSizeTree(WidgetT *w, const BitmapFontT *font);
Generic box-container min-size calculation (bottom-up layout pass). widgetCalcMinSizeBox handles a single VBox/HBox; widgetCalcMinSizeTree recurses through the whole subtree. Hidden children and backdrops (wgtSetBackdrop) count for nothing.
widgetLayoutBox / widgetLayoutChildren
void widgetLayoutBox(WidgetT *w, const BitmapFontT *font);
void widgetLayoutChildren(WidgetT *w, const BitmapFontT *font);
Generic box-container layout (top-down pass). widgetLayoutBox lays out a single container, placing its visible children that are not backdrops; widgetLayoutChildren runs the widget’s layout handler, then gives each of its visible backdrops (wgtSetBackdrop) its whole box and lays that one out.
2.21.12. Event Dispatch
widgetOnPaint / widgetOnMouse / widgetOnKey / etc.
void widgetOnPaint(WindowT *win, RectT *dirtyArea);
void widgetOnMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons);
void widgetOnKey(WindowT *win, int32_t key, int32_t mod);
void widgetOnKeyUp(WindowT *win, int32_t scancode, int32_t mod);
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);
void widgetOnScroll(WindowT *win, ScrollbarOrientE orient, int32_t value);
void widgetOnFocus(WindowT *win);
void widgetOnBlur(WindowT *win);
Window-level event handlers that dispatch to individual widgets in the tree. wgtInitWindow installs these as the window’s onPaint/onMouse/onKey/etc. callbacks.
widgetKeyTo / widgetKeyToFocus
void widgetKeyTo(WidgetT *w, int32_t key, int32_t mod);
void widgetKeyToFocus(WindowT *win, int32_t key, int32_t mod);
A key for widget w: its onKeyDown, then onKeyPress for a key that is a character (KEY_IS_ASCII), then the class’s own handling (WGT_METHOD_ON_KEY), as Visual Basic and Windows order them, so a callback can change or cancel the key (wgtKeyReplace). A disabled or hidden widget gets nothing, and the dispatch stops when a callback destroys w. widgetKeyToFocus gives the key to win’s focused widget; widgetOnKey presses the window’s default or cancel button first. The BASIC form runtime calls widgetKeyTo for a key that waited for the program’s turn.
2.21.13. Paint Helpers
widgetPaintOne
void widgetPaintOne(WidgetT *w, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);
Paint a widget and its subtree: it records its clip rect and calls its PAINT handler when it or the whole window is to repaint, then paints its children, its backdrops (wgtSetBackdrop) first and the others over them (all of them again when a backdrop repainted). A container that paints its own children (WCLASS_PAINTS_CHILDREN) paints them itself, only when it or one of them needs it.
widgetPaintOverlays
void widgetPaintOverlays(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);
Paint the overlay pass: dropdown popups and tooltips drawn on top of the main tree.
widgetQuickPaintBegin
bool widgetQuickPaintBegin(WidgetT *w, DisplayT *cd);
A display onto w’s window content buffer, clipped to w and every ancestor, for a widget’s quick repaint (WGT_METHOD_QUICK_REPAINT) outside the paint walk: the widget draws the rows that changed and reports them, and only those are flushed. Returns false when w cannot be painted that way now — hidden, clipped away entirely, or inside a scroll container, whose viewport is not its rect (w is then invalidated for the normal paint) — and the caller drops what it meant to draw. The Terminal and RichEdit widgets use it.
2.21.14. Pressable Button Helpers
Shared state machine for WCLASS_PRESS_RELEASE widgets (Button, ImageButton, CheckBox, OptionButton). The w->pressed flag tracks the visual state; these helpers fire the widget’s onClick callback on release-within-bounds.
widgetPressableOnMouse / widgetPressableOnKey / widgetPressableOnDragUpdate / widgetPressableOnDragEnd / widgetPressableOnAccelActivate
void widgetPressableOnMouse(WidgetT *w, WidgetT *root, int32_t vx, int32_t vy);
void widgetPressableOnKey(WidgetT *w, int32_t key, int32_t mod);
void widgetPressableOnDragUpdate(WidgetT *w, WidgetT *root, int32_t x, int32_t y);
void widgetPressableOnDragEnd(WidgetT *w, WidgetT *root, int32_t x, int32_t y);
void widgetPressableOnAccelActivate(WidgetT *w, WidgetT *root);
Register these directly as the widget class’s handlers for WGT_METHOD_ON_MOUSE, WGT_METHOD_ON_KEY, WGT_METHOD_ON_DRAG_UPDATE, WGT_METHOD_ON_DRAG_END, and WGT_METHOD_ON_ACCEL_ACTIVATE. widgetPressableOnKey presses on Space and Enter.
widgetPressablePress / widgetPressableRelease
void widgetPressablePress(WidgetT *w);
bool widgetPressableRelease(WidgetT *w, WidgetT *root, int32_t x, int32_t y);
For a class that acts on its click (a check box toggles, an option button is selected) with handlers of its own. widgetPressablePress is a press from the keyboard (Space, an access key): w shows pressed, and the app loop releases it once the key’s dispatch is done (WGT_METHOD_ON_DRAG_END at w’s center), so the key’s onKeyDown and onKeyPress come first. widgetPressableRelease, called from the class’s WGT_METHOD_ON_DRAG_END, shows w released and returns true when (x, y) is inside w: then the class acts and fires its onClick; moving off before the release cancels the click.
2.22. platform/dvxPlat.h — Platform Layer
2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
All OS-specific and CPU-specific code is isolated behind this interface. Port DVX to a new platform by implementing a new dvxPlatformXxx.c against this header. The target implementation is dvxPlatformDos.c for DJGPP/DPMI; dvxPlatformHost.c is a Linux backend used only by the host test suites (fake clock, in-memory framebuffer, scripted input). Code shared by both lives in dvxPlatformUtil.c.
Platform functions must be stateless (or manage their own internal state) and must not reference AppContextT or any layer above dvxTypes.h.
2.22.2. Constants
| Define | Value | Description |
|---|---|---|
DVX_MAX_PATH |
260 |
Maximum file path length |
PLATFORM_SYSINFO_MAX |
4096 |
Maximum size of formatted system info text |
DVX_PATH_SEP |
"\\" |
Native directory separator on DOS |
2.22.3. Types
PlatformKeyEventT
Keyboard event with ASCII and scancode separated. Extended keys (arrows, F-keys) have ascii == 0 and a non-zero scancode.
| Field | Description |
|---|---|
ascii |
ASCII value, 0 for extended/function keys |
scancode |
PC scancode (e.g. 0x48 = Up, 0x50 = Down) |
modifiers |
KEY_MOD_SHIFT, KEY_MOD_CTRL, and KEY_MOD_ALT bits held for this key (no lock or Insert toggles) |
2.22.4. Lifecycle
dvxLog
void dvxLog(const char *fmt, ...);
Append a formatted line to dvx.log. Implemented in dvx.exe and exported to every DXE via the loader. The file is opened and closed for each line; once a line takes it past the limit platformSetLogLimit set (the loader sets PLATFORM_LOG_FILE_MAX, 512 KB, for DVX.LOG), only its newest lines are kept, half the limit at most, after the line "Log: older lines were removed when the log passed N bytes" (the file is replaced whole, so a fault meanwhile leaves the old one). A tool or test that sets no limit gets a log that only grows.
platformInit
void platformInit(void);
One-time platform initialization (a second call does nothing new; the loader and dvxInit both call it). On DOS this disables Ctrl+C and Ctrl+Break at every level (the DJGPP runtime check, SIGINT, and DOS break checking via INT 21h AH=33h) so the user cannot kill the GUI from inside a graphics mode, and points the real-mode INT 24h (critical error) vector at a stub in DOS memory that answers Fail. From then on a drive that is not ready, a write-protected disk, or a removed disk makes the DOS call return an error (errno) instead of waiting at "Abort, Retry, Fail" on the hidden text screen, so no DVX code needs a guard of its own. The handler is never removed: DOS restores the vector from the PSP when DVX exits. It does not install crash handlers (see platformInstallCrashHandler).
2.22.5. Timing
platformClock / platformClockHz
typedef uint32_t PlatformTicksT;
PlatformTicksT platformClock(void);
PlatformTicksT platformClockHz(void);
#define PLATFORM_MS_TO_TICKS(ms)
#define PLATFORM_TICKS_TO_MS(ticks)
Monotonic tick counter for UI timing (double-click, tooltip delay, cursor blink, timers), advancing platformClockHz() ticks per second. PlatformTicksT is unsigned so "now - then" is wrap-safe: always compare intervals by subtraction, never raw tick values. PLATFORM_MS_TO_TICKS converts milliseconds to ticks at the platform rate, PLATFORM_TICKS_TO_MS ticks to milliseconds (the millisecond clock the conn and xfer engines take is PLATFORM_TICKS_TO_MS(platformClock())).
platformEntropyStamp
uint64_t platformEntropyStamp(void);
Fine-grained, free-running timestamp for entropy. It is not a clock: units and wrap point are backend-specific. On DOS it reads the live PIT channel 0 counter (about 0.84 us resolution, its own crystal) and returns it in the top 16 bits of the CPU time-stamp counter (RDTSC) when CPUID reports one, so a sample carries the jitter between the two clocks; otherwise the BIOS tick count shifted left 16 bits with the PIT counter in the low 16 bits. Used by dvxSetInputEntropyHook and by the security library’s entropy gathering.
platformMicros
uint64_t platformMicros(void);
Monotonic microseconds, the high-resolution clock for games and measurements. On DOS it counts from the start of the timer service (dvxInit): the PIT input clocks the timer interrupt has counted plus the part of the running period, read from the latched channel 0 count (about 0.84 us steps), or on a CPU with a time-stamp counter the TSC cycles since the last interrupt at the rate measured over the interrupt period before it, so the clock never drifts from the PIT and a TSC whose rate changes (power saving, an emulator) does no harm. The host backend returns its fake clock. Not for use inside a timer callback.
Timer Service
#define PLATFORM_PIT_HZ 1193182
#define PLATFORM_PIT_BIOS_DIVISOR 65536
#define PLATFORM_TIMER_MAX_HZ 1000
#define PLATFORM_TIMER_FAST_MAX_HZ 30000
#define PLATFORM_TIMER_SLOTS 16
typedef void (*PlatformTimerFnT)(void *userData);
void platformTimerInit(void);
void platformTimerShutdown(void);
int32_t platformTimerAdd(uint32_t hz, PlatformTimerFnT fn, void *userData, int32_t ownerAppId);
int32_t platformTimerAddFast(uint32_t hz, PlatformTimerFnT fn, void *userData, int32_t ownerAppId);
void platformTimerRemove(int32_t timerId);
void platformTimerRemoveOwner(int32_t ownerAppId);
void platformTimerStats(PlatformTimerStatsT *out);
One timer interrupt for everything that must run at a steady rate however busy the programs are (audio refill, joystick polling). dvxInit starts the service; dvxShutdown stops it. On DOS it owns PIT channel 0 (rate generator mode) and INT 8: the interrupt runs as fast as the fastest registered timer needs (at most PLATFORM_TIMER_MAX_HZ; the BIOS 18.2 Hz when there is none) and exactly one interrupt per 65536 PIT clocks is passed on to the BIOS handler, so the BIOS tick count, the DOS time of day, clock(), and the floppy motor timeout keep their normal rate. A rate change takes effect at once (the PIT is restarted and the part of the period already run is counted). Shutdown restores the BIOS square-wave mode and the old vector; it also runs at exit() and from the crash handler when a crash is not recovered.
platformTimerAdd calls fn(userData) hz times a second, 1 to PLATFORM_TIMER_MAX_HZ; exact on average, while single intervals vary by up to one interrupt period. It returns a timer id, or -1 (bad arguments, all PLATFORM_TIMER_SLOTS in use, service not running). ownerAppId is recorded for platformTimerRemoveOwner, which the shell calls when a program ends; use 0 for a library that removes its own timers. gameTimerAdd (game.lib) registers one for the calling program. After platformTimerRemove returns, the callback is not running and will not run again.
platformTimerAddFast is the same for a device that must be fed at an audio rate (the PC speaker’s digital sound): hz may be up to PLATFORM_TIMER_FAST_MAX_HZ. The whole timer interrupt then runs that often, so the callback must be very short (a few port writes); ask for PLATFORM_PIT_HZ / divisor to be called on every interrupt.
|
Warning
|
The callback runs INSIDE THE TIMER INTERRUPT, with interrupts disabled, on a small stack. Keep it to a few dozen microseconds; do not call the C library, DVX, or DOS; do not use floating point; and pin its code and every byte it touches with platformLockRegion (a page fault there is fatal on DOS). Set flags and counters, fill buffers, write I/O ports. |
PlatformTimerStatsT reports rateHz (the interrupt rate, rounded), divisor (the PIT reload value), interrupts (since the service started), and biosTicks (of those, passed on to the BIOS).
Interrupt-Safe Updates and Shutdown Hooks
uint32_t platformIrqSave(void);
void platformIrqRestore(uint32_t state);
#define PLATFORM_SHUTDOWN_HOOKS 8
typedef void (*PlatformShutdownFnT)(void);
bool platformShutdownHookAdd(PlatformShutdownFnT fn);
void platformShutdownHookRemove(PlatformShutdownFnT fn);
#define PLATFORM_SUSPEND_HOOKS 8
typedef void (*PlatformSuspendFnT)(bool suspending);
bool platformSuspendHookAdd(PlatformSuspendFnT fn);
void platformSuspendHookRemove(PlatformSuspendFnT fn);
platformIrqSave disables interrupts and returns the previous state for platformIrqRestore; bracket the few instructions that change data an interrupt handler reads (nothing happens on the host).
A shutdown hook runs when DVX ends without its normal shutdown (exit() or a crash with no recovery point), before the timer service and the keyboard hook are given back, so a module that drives hardware from an interrupt (a sound card playing by DMA) can stop it. Each hook runs once. platformServicesStop (void platformServicesStop(void)) is that ending: the hooks, then the timer service and the keyboard hook. The exit path (atexit) and the crash handler without a recovery point call it, and so does the shell when DVX itself fails while it starts, while the modules are still loaded; every part does nothing the second time. A module removes its hook before it is unloaded; at most PLATFORM_SHUTDOWN_HOOKS exist at once (Add returns false when full; adding one already present does nothing).
A suspend hook runs as fn(true) before DVX steps aside for a DOS program (platformDosRun, dvxRunDos) and as fn(false) once DVX is back, so a module that drives hardware itself lets it go (and takes it again then, or at its next use): audio.lib stops every sound, closes the output and the synthesizers, and opens the synthesizers again; music.lib stops every music and lets go of where it plays, closing its context (and the SoundFont kept on the wavetable synthesizer) when none is left; dvxnet stops the packet driver (it starts again at the next use). Suspending runs the newest hook first (a library built on another, loaded after it, lets go before it), resuming the oldest first; a hook may remove itself as they run. At most PLATFORM_SUSPEND_HOOKS; the same rules as the shutdown hooks otherwise.
2.22.6. Video
platformVideoInit / platformVideoShutdown
int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
void platformVideoShutdown(DisplayT *d);
Low-level video mode setup and teardown. Called by videoInit / videoShutdown. On DOS the mode is used through its linear framebuffer when the card offers one (VBE 2.0+) and the DPMI host maps it; otherwise through its 64 KB bank window (any VBE version), which only platformFlushRect sees. The log says which ("Video: 640x480 at 16 bpp, linear frame buffer" or "..., banked: window A, 64 KB in 64 KB steps"). It fails only when there is no VBE ("VBE: No VESA BIOS extension (VBE) found") or no usable mode; the shell then tells the user to load a VESA driver such as UniVBE.
platformVideoEnumModes
void platformVideoEnumModes(void (*cb)(int32_t w, int32_t h, int32_t bpp, void *userData), void *userData);
Enumerate the graphics modes platformVideoInit can actually set (on DOS: VBE modes at 8, 15, 16, or 32 bpp, linear or banked; 24 bpp is not offered). cb is invoked once per distinct width/height/depth. Feeds the video-mode list offered to the user; platformVideoInit selects its own best match independently.
platformVideoSetPalette
void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count);
Program the VGA/VESA DAC palette registers (8-bit mode only). pal is the full 256-entry RGB table (3 bytes per entry); entries firstEntry..firstEntry+count-1 are written, clamped to the 256-entry table.
platformVideoFreeBuffers
void platformVideoFreeBuffers(DisplayT *d);
Free the backbuffer and palette without restoring text mode. Used when switching between graphics modes live.
platformVideoReadBack
bool platformVideoReadBack(const DisplayT *d, uint8_t *out);
Copy what video memory holds for d (the display on show: the desktop, or a full-screen program’s) into out, pitch * height bytes, from the linear framebuffer or through a banked mode’s window that can be read (which may be the other window). False where it cannot: Mode X (platformVideoExclusiveCapture reads that), or a banked mode with no readable window. The DOS test harness’s VIDEOCHECK step compares it with the backbuffer, since screenshots are taken from the backbuffer and could not show a flush that wrote to the wrong place.
2.22.7. Framebuffer Flush
platformFlushRect
void platformFlushRect(const DisplayT *d, const RectT *r);
Copy a rectangle from the system RAM backbuffer to video memory. The single critical path where bus write speed matters. On DOS, each scanline (or the whole rectangle, when it spans whole scanlines) is one rep movsd run of aligned 32-bit writes to the linear framebuffer. A mode with no linear framebuffer (a VBE 1.x card, or a DPMI host that will not map it) is written through its bank window instead: a run is cut where the window ends and the window moved on (VBE function 4F05h) only when the next byte is outside it. System Information says which ("Video memory access").
platformBankChunk
#define PLATFORM_BANK_NONE 0xFFFFFFFFu
uint32_t platformBankChunk(uint32_t offset, uint32_t length, uint32_t granBytes, uint32_t winBytes, uint32_t *winStart);
The window arithmetic of the banked flush, shared so the host tests check it. The window shows winBytes of video memory from *winStart and moves in steps of granBytes (granBytes <= winBytes). For a copy of length bytes to offset, it moves *winStart to the step at or below offset when offset is not in the window (or *winStart is PLATFORM_BANK_NONE, not known yet, as after a mode set), and returns how many bytes fit before the window ends. The caller switches the bank when *winStart changed, copies that many bytes, and goes on with the rest.
2.22.8. Span Operations
platformSpanFill8/16/32
void platformSpanFill8(uint8_t *dst, uint32_t color, int32_t count);
void platformSpanFill16(uint8_t *dst, uint32_t color, int32_t count);
void platformSpanFill32(uint8_t *dst, uint32_t color, int32_t count);
Fill count pixels at dst with color. Three depth variants because the fill instruction differs by size. On DOS these use inline rep stosl / rep stosw / rep stosb asm.
platformSpanCopy8/16/32
void platformSpanCopy8(uint8_t *dst, const uint8_t *src, int32_t count);
void platformSpanCopy16(uint8_t *dst, const uint8_t *src, int32_t count);
void platformSpanCopy32(uint8_t *dst, const uint8_t *src, int32_t count);
Copy count pixels from src to dst. On DOS these use rep movsd.
2.22.9. Mouse Input
platformMouseInit
void platformMouseInit(int32_t screenW, int32_t screenH);
Initialize the mouse driver and constrain movement to the screen bounds. On DOS this resets the INT 33h driver, sets the X/Y range, and centers the cursor. Safe to call again after a video-mode change: the speed, acceleration, and wheel settings applied earlier are re-applied after the driver reset.
platformMousePoll
void platformMousePoll(int32_t *mx, int32_t *my, int32_t *buttons);
Poll current mouse state. Buttons is a bitmask: bit 0 = left, bit 1 = right, bit 2 = middle. MOUSE_BUTTON_MASK (MOUSE_LEFT | MOUSE_RIGHT | MOUSE_MIDDLE, in dvxPlat.h) covers every bit it can report.
platformMouseWheelInit / platformMouseWheelPoll
bool platformMouseWheelInit(void);
int32_t platformMouseWheelPoll(void);
Detect and activate the CuteMouse Wheel API. platformMouseWheelPoll returns the accumulated delta (positive = scroll down) since the last poll.
2.22.10. Keyboard Input
platformKeyboardGetModifiers
int32_t platformKeyboardGetModifiers(void);
Return the modifier keys held, as the BIOS shift-state byte has them: bit 0 right Shift, bit 1 left Shift (KEY_MOD_SHIFT is both), bit 2 Ctrl (KEY_MOD_CTRL), bit 3 Alt (KEY_MOD_ALT). The byte’s Scroll Lock, Num Lock, Caps Lock, and Insert toggles above them are left out, as they are from every key event’s modifiers, so a test such as mod == KEY_MOD_CTRL holds with Num Lock on.
platformKeyboardRead
bool platformKeyboardRead(PlatformKeyEventT *evt);
Non-blocking read of the next key from the keyboard buffer. Returns true if a key was available. On DOS this uses INT 16h AH=11h/10h; extended keys have their ASCII byte zeroed, and Shift/Ctrl/Alt+F1..F12 are reported as the plain F-key scancode (see platformNormalizeFKeyScan) with the modifier available from platformKeyboardGetModifiers.
platformNormalizeFKeyScan
int32_t platformNormalizeFKeyScan(int32_t scancode);
Map the BIOS scancodes for Shift/Ctrl/Alt+F1..F12 (Shift F1-F10 0x54-0x5D, Ctrl 0x5E-0x67, Alt 0x68-0x71, Shift/Ctrl/Alt F11-F12 0x87-0x8C) onto the plain F-key scancodes (F1-F10 0x3B-0x44, F11 0x85, F12 0x86). Any other scancode is returned unchanged. Applied by every backend’s platformKeyboardRead.
Raw Keys and the Held-Key Table
#define PLATFORM_KEY_EVENT_QUEUE 64
#define PLATFORM_KEPT_KEYS(X) // X(name, key code, scan code, modifier) for Alt+Tab, Alt+F4, Ctrl+Esc
void platformKeyHookInit(void);
void platformKeyHookShutdown(void);
bool platformKeyEventRead(RawKeyEventT *evt);
bool platformKeyIsDown(int32_t rawCode);
void platformKeyStateGet(uint8_t out[KEY_RAW_COUNT]);
void platformKeyStateClear(void);
void platformInjectScan(uint8_t scan);
The keyboard hook (on DOS a chain on INT 9 that reads port 60h before the BIOS handler stores the key for platformKeyboardRead) decodes every set-1 byte: 0xE0 prefixes, the fake Shift codes the keyboard wraps around gray keys (dropped), the Pause burst (one press and one release), and keyboard replies such as ACK and overrun (dropped). Each key going down or up updates the held-key table and is queued as a RawKeyEventT (at most PLATFORM_KEY_EVENT_QUEUE; newer events are dropped when the queue is full, the table still changes). Keys are named by raw code, KEY_RAW_CODE(scancode, extended) (see dvxTypes.h): Left and Right Shift, Ctrl, and Alt are keys of their own, and the code does not change with modifiers. dvxInit installs the hook and dvxShutdown removes it; the event loop reads the queue (onKeyUp, onRawKey) and clears the table whenever the keyboard focus moves. platformKeyStateGet copies the table (1 = down). platformInjectScan feeds one byte to the decoder as if the keyboard had sent it (the test script’s KEYDOWN / KEYUP use it). The combinations DVX keeps even from a game (Alt+Tab, Alt+F4, and Ctrl+Esc) never reach the table or the queue: not their key’s press, repeats, or release. PLATFORM_KEPT_KEYS lists them once, as X(name, key code, set-1 scan code, modifier); the decoder expands it at interrupt time, and the event loop’s table of the keys DVX keeps (dvxSystemKeyUse) builds its first entries from it.
2.22.11. System Information
platformGetSystemInfo
const char *platformGetSystemInfo(const DisplayT *display);
Return a pre-formatted text string with hardware/OS information (CPU, clock, memory, video, mouse, disks), valid until the next call. Each call reads the memory, the screen mode (display), and the drives as they are then; the processor’s clock (which takes about 165 ms to measure) is measured on the first call only. The shell logs it at start and gathers it again each time it is shown (shellGetSystemInfo).
2.22.12. File System
platformValidateFilename
const char *platformValidateFilename(const char *dir, const char *name);
Validate a name for a new file or folder in folder dir (NULL or "" for the current one) against the rules of its disk. On DOS: platformValidateLongName where platformLongNames(dir), else platformValidateShortName, and dir with the name must stay under DVX_MAX_PATH. The host backend refuses an empty name, . and .., separators, and control characters, and ignores dir. Returns NULL if valid, or a human-readable error string. The file dialog, the File Manager (fileOpsValidateName), and the IDE’s project rename all use it.
Long file names: platformLongNames / platformValidateLongName / platformValidateShortName / platformLongNameChar / platformShortPath / platformTruePath / platformSameFile / platformRename
#define PLATFORM_LONG_NAME_MAX 255
bool platformLongNames(const char *path);
const char *platformValidateLongName(const char *name);
const char *platformValidateShortName(const char *name);
bool platformLongNameChar(char c);
bool platformShortPath(const char *path, char *out, int32_t outSize);
bool platformTruePath(const char *path, char *out, int32_t outSize);
bool platformSameFile(const char *a, const char *b);
int32_t platformRename(const char *oldPath, const char *newPath);
The DOS C library uses the long-name calls (INT 21h 71xxh) by itself whenever a driver provides them (Windows, DOSLFN), so open, fopen, rename, mkdir, stat, and the directory readers all take and return long names; these functions cover what the C library does not.
platformLongNames is true when the drive holding path (NULL or "": the current drive) takes long file names. On DOS that is a loaded long-name driver covering that drive; elsewhere always.
platformValidateLongName and platformValidateShortName are the two DOS name rules by themselves, whatever the disk takes; each returns NULL or why the name is not valid. A long name has 1 to PLATFORM_LONG_NAME_MAX characters and may hold spaces, several dots, and + , ; = [ ]; it may not hold a control character or \ / : * ? " < > |, and may not end with a dot or a space (DOS drops them). An 8.3 name has 1 to 8 printable ASCII characters, then at most one dot and up to 3 more, none of them a space or " * + , / : ; < = > ? [ \ ] |. Neither may be . or .., or a device name (CON, PRN, AUX, NUL, CLOCK$, COM1 to COM9, LPT1 to LPT9) before its first dot. They are shared code, so the host tests check the DOS rules too.
platformLongNameChar is true when a long name may hold character c; a file transfer uses it to turn the characters a sender’s name cannot keep into _.
platformShortPath writes the short (8.3) form of an existing path into out, for what reads names before a long-name driver loads (AUTOEXEC.BAT) or cannot take blanks (an old program’s command line). On a drive with long names DOS gives every part’s short name (INT 21h AX=7160h CL=1); elsewhere, and when DOS cannot, path itself is copied (platformPathTidy: "C:/DVX" gives "C:\\DVX"). False when out is too small.
platformTruePath writes the one spelling of path that every way of naming its file or folder leads to, for telling by name whether two paths are one item and for naming something kept beside it (the SQL library names a database’s journal and keys its locks this way). path may name a file not made yet in a folder that is there. On DOS it is fully qualified (the drive and folder it is relative to, "..", a SUBSTed drive as what it stands for; _truename) and then put in the long form where the drive has long names (INT 21h AX=7160h CL=2); the host backend follows links (realpath). Two hard links to one file stay two names (platformSameFile tells those). When the platform cannot say, path itself is copied. False when out is too small.
platformSameFile is true when a and b are two spellings of one existing file or folder, for a rename or a save that must not take the item itself for another one using the new name. On DOS both are fully qualified by DOS (_truename: case, .., the current drive and folder) and then made short (platformShortPath), so a change of case and a long name against its 8.3 alias both name the same item; the host backend compares the device and inode stat reports. The BASIC NAME statement and fileOpsRename use it.
platformRename is rename(), and also gives an item its own name spelled otherwise: in other letters, or its own 8.3 alias (which then replaces the long name). DOS with long names refuses a rename onto the item’s own alias and ignores a short name put in other letters, so on DOS, on a drive with long names, such a rename (platformSameFile, with the last parts of the two names differing) goes through a scratch name beside the item (platformPathSibling with PLATFORM_TMP_EXT): the item is renamed there, then to the new name, and put back when the second step fails; a scratch name already in use fails it with EEXIST. newPath must not name another item, which rename() would replace. Returns 0, or -1 with errno. The BASIC NAME statement and fileOpsRename use it.
platformChangeErrno
int32_t platformChangeErrno(const char *path, bool made, int32_t err);
The errno a failed change to the disk stands for: making the file or folder at path (made true), or deleting or renaming the one there, that failed with err. DOS garbles a disk that refuses a change, such as a write-protected floppy or a CD-ROM: the DOS C library’s open() ends a create that failed by looking for a folder of that name, so the create reports ENOENT, and a CD-ROM driver answers a delete, rename, or new folder it does not do with "invalid function", which the C library reports as EINVAL. Those, for a path whose folder is there (and, unless it was being made, an item that is there), become EACCES: the disk refused. Any other err is returned as it is, so a missing folder or a missing item still says ENOENT. Pass errno through it before reporting a failed create, delete, rename, or new folder; BASIC’s OPEN, KILL, NAME, and FILECOPY, FileOpsSaveText, and the File Manager’s operations (fileOps) do.
platformStatSize
uint64_t platformStatSize(const struct stat *st);
The size stat reported for a file. A FAT32 file reaches 4 GB - 1 byte, but the DOS C library’s st_size is a signed 32-bit off_t, so a file past 2 GB reads as negative there; platformStatSize reads it as the unsigned 32-bit size DOS keeps. Use it wherever a file size comes from stat or fstat.
platformFileStamp
typedef struct {
uint32_t size; // bytes (a file of 4 GB or more: 0xFFFFFFFF)
uint32_t time; // its date and time, as the platform keeps them
} PlatformStampT;
bool platformFileStamp(const char *path, PlatformStampT *out);
A file’s size and time from its folder alone, for telling whether a file read before has changed: compare two stamps for equality only. On DOS it is one directory search; stat makes several DOS calls there, tens of milliseconds each on a slow disk. Elsewhere it is stat, with the time’s nanoseconds folded in. False when path is no file, or holds a wildcard. DOS keeps a file’s time to two seconds, so a file rewritten at the same size within two seconds keeps its stamp. The shell’s program cache checks the programs it keeps with it.
platformMkdirRecursive
int32_t platformMkdirRecursive(const char *path);
Create a directory and all parent directories (like mkdir -p). Existing directories are not an error. Returns 0 on success, -1 on failure (including a path of DVX_MAX_PATH characters or more).
platformChdir
int32_t platformChdir(const char *path);
Change the working directory, including drive letter on DOS (switches drive first when the path starts with "X:"). If the chdir fails (no such folder, no such drive, or a drive with no disk in it) the previous drive is restored. A drive prefix that is not a letter is rejected. Where there are no drives (the host backend), a drive alone ("C:") changes nothing and succeeds, so BASIC’s CHDRIVE does nothing there. Returns 0 on success, -1 on failure.
platformDriveCurDir
int32_t platformDriveCurDir(char drive, char *out, int32_t outSize);
The current directory of drive letter drive ('C' or 'c') into out, in the form getcwd gives the current drive’s (its letter case too) and in native separators: BASIC’s CURDIR$(drive$). On DOS, INT 21h AH=47h tells whether DOS has the drive, from what it keeps for it (the disk is not read, so a drive with no disk in it answers with the directory it last had), and the directory is what DJGPP’s _fixpath gives for "X:." (long names where the drive takes them). Where there are no drives (the host backend), every letter’s directory is the one current directory. Returns 0, or -1 with errno: ENODEV when drive is no letter, EIO when DOS has no such drive or cannot answer for it (pass it through platformDriveErrno, which says ENXIO for a drive with no disk in it; the host backend answers so for a drive "X:" that hostDriveNotReady named), ERANGE when out is too small.
Path separators: platformPathIsSep / platformPathNative / platformPathSame / platformPathIsUnder / platformPathJoin / platformPathDirName / platformPathTidy
bool platformPathIsSep(char c);
char *platformPathNative(char *path);
bool platformPathSame(const char *a, const char *b);
const char *platformPathIsUnder(const char *path, const char *dir);
bool platformPathJoin(char *out, int32_t outSize, const char *dir, const char *name);
bool platformPathDirName(const char *path, char *out, int32_t outSize);
char *platformPathTidy(char *path);
DVX paths follow DOS rules on every platform: '/' and '\\' are the same separator, so a path a program writes with '/' works on DOS exactly as with '\\', and names compare without case (DOS and the host build also share INI files, projects, and program paths). Every path DVX shows uses the native separator, DVX_PATH_SEP ('\\' on DOS). DVX’s own path code goes through these functions; a program that splits, compares, or joins paths should too, never testing for one separator by hand.
-
platformPathIsSep: true for '/' and '\\'.
-
platformPathNative: rewrites path’s separators as DVX_PATH_SEP, in place, before it is shown (the DOS C library’s getcwd and realpath give "c:/dvx"). Returns path.
-
platformPathSame: true when a and b name the same place by DOS rules: separators alike, a trailing one ignored, case ignored. Text only: "." or a relative path is not resolved.
-
platformPathIsUnder: when path is dir or lies below it, the rest of path after dir and its separator ("" for dir itself); NULL otherwise.
-
platformPathJoin: dir and name with one separator between them (none added when dir ends in one), every separator native; an absolute name, or an empty dir, gives name alone. False when it does not fit.
-
platformPathDirName: the folder part of path in native separators: a root keeps its separator ("C:\\X.TXT" gives "C:\\", since "C:" alone is the drive’s current folder), "C:X.TXT" gives "C:", a bare name gives ".". False when it does not fit.
-
platformPathParent: the folder holding path, a trailing separator ignored, in native separators ("C:/DVX/APPS/" gives "C:\\DVX", "/a" gives "/"). False for a root, a name without a folder, or when it does not fit.
-
platformPathIsRoot: true for a drive or file-system root: "C:", "C:\\", "/", or "\\".
-
platformPathTidy: platformPathNative, then each run of separators made one (a leading pair, a network "\\\\server", kept) and a trailing separator dropped unless it is a root’s: the form for a path handed to DOS directly, without the C library in between. platformShortPath and the file operations library’s attribute calls use it.
platformPathDirEnd
char *platformPathDirEnd(const char *path);
Return a pointer to the last directory separator in path (platformPathIsSep), or NULL.
platformPathIsAbsolute
bool platformPathIsAbsolute(const char *path);
True for a path rooted at a separator ('/' or '\\') or qualified with a drive letter ("C:..."). A NULL path is not absolute.
platformPathBaseName
const char *platformPathBaseName(const char *path);
Return a pointer to the leaf (basename) portion of path: after the last separator, or after a drive ("C:A.TXT" gives "A.TXT").
platformCopyFile
bool platformCopyFile(const char *srcPath, const char *dstPath);
Byte-for-byte file copy. Returns false on any open, read, or write failure (errno says why, ENOSPC for a full disk); a partially written destination is removed so no truncated copy is left behind. A copy onto itself (platformPathSame) does nothing and returns true: opening the copy would otherwise empty the original first.
platformCopyFileWith
typedef struct {
void *src;
void *dst;
char dstPath[DVX_MAX_PATH];
} PlatformCopyT;
bool platformCopyFileWith(PlatformCopyT *job, const char *srcPath, const char *dstPath, bool (*goOn)(void *ctx), void *ctx);
void platformCopyAbandon(PlatformCopyT *job);
platformCopyFile asking goOn(ctx) between pieces, for a caller that lets other work go on while a big file copies; false from goOn stops the copy, which then fails like any other (its partial copy removed). job (the caller’s; NULL for none) holds the copy’s open files (FILE *) and its destination while it runs and is empty again after. A caller that can be ended while goOn lets other work run (a BASIC program’s FileCopy, ended from the Task Manager) keeps job where it is freed with it: platformCopyAbandon then closes the files and removes the partial copy (nothing for a job not copying).
platformPathSibling
#define PLATFORM_TMP_EXT ".$"
#define PLATFORM_BAK_EXT ".~"
#define PLATFORM_SIBLING_EXT_MAX 3
bool platformPathSibling(char *out, int32_t outSize, const char *path, const char *ext);
Write path with its file-name extension replaced by ext into out, followed by as many leading characters of the original extension as fit in PLATFORM_SIBLING_EXT_MAX characters (a full-length ext such as ".BAK" replaces the extension outright; a name with no extension gets ext appended). Replacing rather than appending keeps an 8.3 name valid on DOS without long file names, and keeping part of the original extension gives files that differ only in extension distinct scratch names: USER\DVX.INI becomes USER\DVX.$IN (temp) and USER\DVX.~IN (backup), FOO.APP and FOO.HLP become FOO.$AP and FOO.$HL. Returns false when the result does not fit in outSize or would name path itself (compared case-insensitively).
platformScratchFile
bool platformScratchFile(char *out, int32_t outSize, const char *path, const char *ext);
Make a new, empty scratch file beside path for a crash-safe rewrite and give its name in out: the ext sibling of path (platformPathSibling) when nothing has that name, else ext’s marker and two digits (FOO.$00 to FOO.$99). It is never a file that was there already, so two saves of one file that both let DVX go on while they write cannot share a scratch file, and a leftover or a file of the user’s is not written over. The caller writes it (fopen "wb") and then swaps it in with platformReplaceFile, or removes it. Returns false (errno says why) when none can be made.
platformReplaceFile
bool platformReplaceFile(const char *tmpPath, const char *path);
Crash-safe swap of a fully written tmpPath in for path. The original is renamed aside first (DOS rename cannot overwrite) to its backup name, the PLATFORM_BAK_EXT sibling of path, or a numbered one (FOO.~00 to FOO.~99) when something has that name already: a backup that is there is never deleted. The backup is removed only once the replacement is in place; if the swap fails the original is restored and tmpPath removed. A directory or a read-only file at path is never moved aside: the call fails with errno EACCES and removes tmpPath. A crash between the two renames leaves only the backup, and prefsLoad falls back to reading the PLATFORM_BAK_EXT sibling. The resource writer and the help compiler save this way, into a scratch file from platformScratchFile.
platformCanReplaceFile
bool platformCanReplaceFile(const char *path);
True when platformReplaceFile would put a file at path: nothing is there yet, or a file that may be written (not a directory or a read-only file). The check is the one platformReplaceFile makes. A long write into the scratch file asks it first, so the work is not lost to a refusal at the swap: a recording into a file (audioRecFile) is refused at the start for a read-only file, as it would be by opening that file to write.
platformWriteFile
bool platformWriteFile(const char *path, const void *data, int32_t len);
Write len bytes of data as the whole of path, all or nothing: into the PLATFORM_TMP_EXT sibling, then swapped in with platformReplaceFile, so a full disk or an I/O error leaves the file as it was. False when it was not done. The preferences system, the IDE’s saves, Setup, and the package records use it.
platformWalkDir
typedef bool (*PlatformWalkFnT)(const char *path, const char *name, void *ctx);
bool platformWalkDir(const char *dir, PlatformWalkFnT fn, void *ctx);
Visit every file below dir, depth first, entering folders as they come and skipping names that start with '.'. A folder’s names are read in full before any is visited (DOS has few file handles), and which are folders comes with them (platformDirEntryIsDir), not from a stat of each. fn gets each file’s full path and its name; returning false stops the walk, and platformWalkDir then returns false too. A folder that cannot be read is skipped. The loader’s module and help scans and the shell’s program list use it.
platformReadFile
char *platformReadFile(const char *path, int32_t *outLen);
Slurp a whole file into a freshly malloc’d, NUL-terminated buffer. Caller frees. Binary-safe: the NUL is past the end of the reported length.
dvxReadDir / dvxReadDirFree
char **dvxReadDir(const char *dirPath);
void dvxReadDirFree(char **entries);
The names in dirPath (all but "." and ".."), each a malloc’d string, in an stb_ds array: arrlen gives the count, and a NULL follows the last name (it is not counted), so code without stb_ds (an SDK program) walks the names to it. NULL when the folder cannot be opened; an empty folder gives an array holding only the NULL. dvxReadDirFree frees every name and the array.
char **names = dvxReadDir("SHARED\\FONTS");
for (char **n = names; n && *n; n++) {
// use *n
}
dvxReadDirFree(names);
platformGlobMatch
bool platformGlobMatch(const char *pattern, const char *name);
Simple glob pattern match. Case-insensitive. Supports * (zero or more chars) and ? (single char). Iterative (a mismatch lets the last * take one more character), so patterns with many stars stay fast.
platformFilterMatch
#define PLATFORM_FILTER_ALL "*.*"
bool platformFilterMatch(const char *name, const char *filter);
True when name matches filter: platformGlobMatch patterns separated by ';', ',', or blanks ("*.txt;*.bat", "*.bmp, *.jpg"). A pattern equal to PLATFORM_FILTER_ALL matches every file, with or without an extension, as on DOS; a NULL or blank filter matches everything too. The file dialog (dvxFileDialog) and the file operations library (fileOpsListDir) both use it, so a filter behaves the same everywhere.
platformDriveList / platformDiskSpace / platformBootDrive / platformDriveErrno
#define PLATFORM_DRIVE_MAX 26
#define PLATFORM_DRIVE_ROOT_MAX 4
typedef enum {
PlatformDriveFixedE,
PlatformDriveRemovableE,
PlatformDriveRemoteE // network drive or CD-ROM
} PlatformDriveTypeE;
typedef struct {
char root[PLATFORM_DRIVE_ROOT_MAX]; // "C:\"
PlatformDriveTypeE type;
} PlatformDriveT;
int32_t platformDriveList(PlatformDriveT *out, int32_t max);
bool platformDiskSpace(const char *path, uint64_t *totalBytes, uint64_t *freeBytes);
char platformBootDrive(void);
int32_t platformDriveErrno(const char *path, int32_t err);
platformDriveList fills out[] with the drives that exist, in letter order, and returns the count. On DOS it uses IOCTL calls only (INT 21h AX=4409h remote, 440Eh logical drive map, 4408h removable), never the media, so empty floppy and CD-ROM drives are listed at once; the second letter of a shared floppy drive (B: on a one-floppy system) is left out because using it makes DOS ask for a disk swap. The host backend reports one drive, "/". System Information and the file operations library both use it.
platformDiskSpace reports the size and free space of the disk holding path (DOS: INT 21h AX=7303h, the FAT32 call that counts past 2 GB, on the root of the path’s drive letter or the current drive, falling back to AH=36h, which tops out near 2 GB, where DOS does not have it; host: statvfs of the nearest existing folder of path, so a folder about to be created reports its disk). False when unknown.
platformDriveErrno is err, or ENXIO (the C library’s "drive not ready") when path is on a drive that is there but has no disk in it, such as an empty floppy or CD-ROM drive. DOS, failing the critical error such a drive makes (DVX’s handler answers Fail), reports what was asked of it as a missing file or folder (ENOENT, ENOTDIR), access denied, or an I/O error; for those the drive itself is asked: a drive platformDriveList gives (never the second letter of a shared floppy drive) whose free space platformDiskSpace cannot read. The asking waits as long as the failed call did, so it is made only after a failure. Pass a failed file operation’s errno through it before reporting the error: the BASIC runtime’s file errors give 71 (Disk not ready) for ENXIO, and the file operations library says "The drive is not ready.". The host backend answers ENXIO for paths that start with what hostDriveNotReady(prefix) set (NULL for none), for host tests.
platformBootDrive returns the letter of the drive DOS started from (INT 21h AX=3305h, DOS 4.0+), whose root holds its start-up files (CONFIG.SYS and AUTOEXEC.BAT, or FreeDOS’s FDCONFIG.SYS and FDAUTO.BAT), or 0 where there is none (older DOS, and every platform but DOS).
DVX folders: platformUserInit / platformUserDir / platformUserPath / platformDvxIniPath / platformAppUserDir / platformKindFind
#define DVX_SYSTEM_DIR "SYSTEM"
#define DVX_APPS_DIR "APPS"
#define DVX_SHARED_DIR "SHARED"
#define DVX_USER_DIR "USER"
#define DVX_DATA_DIR "DATA"
#define DVX_USER_ENV "DVXUSER"
#define DVX_INI_NAME "DVX.INI"
#define DVX_ASSOC_NAME "ASSOC.INI"
#define DVX_CACHE_NAME "PROGRAMS.CAC"
#define DVX_SEED_NAME "SECLINK.RND"
#define DVX_FONTS_DIR "FONTS"
#define DVX_SOUNDS_DIR "SOUNDS"
#define DVX_THEMES_DIR "THEMES"
#define DVX_WPAPER_DIR "WPAPER"
#define DVX_BANKS_DIR "BANKS"
#define DVX_SAVERS_DIR "SAVERS"
#define DVX_VENDOR_DIR "KPUNCH"
#define DVX_SWITCH_SAFE "/SAFE"
#define DVX_SWITCH_RUN "/RUN="
#define DVX_SWITCH_NEXT "/NEXT="
#define DVX_SWITCH_BACK "/BACK"
int32_t platformFindSwitch(int argc, char *argv[], const char *name);
typedef enum {
DvxKindFontsE,
DvxKindSoundsE,
DvxKindThemesE,
DvxKindWpaperE,
DvxKindBanksE,
DvxKindSaversE,
DvxKindCountE
} DvxKindE;
void platformUserInit(void);
const char *platformUserDir(void);
bool platformUserDirOf(char *out, int32_t outSize, const char *dvxDir);
const char *platformUserEnvDir(void);
bool platformUserInTemp(void);
bool platformUserPath(char *out, int32_t outSize, const char *rel);
const char *platformDvxIniPath(void);
bool platformAppUserDir(char *out, int32_t outSize, const char *appPath);
const char *platformKindName(DvxKindE kind);
bool platformKindDir(char *out, int32_t outSize, DvxKindE kind, bool user);
bool platformKindBrowseDir(char *out, int32_t outSize, DvxKindE kind);
bool platformKindFind(char *out, int32_t outSize, DvxKindE kind, const char *name);
bool platformKindNameOf(DvxKindE kind, const char *path, char *out, int32_t outSize);
char **platformKindReadDir(DvxKindE kind);
The DVX folder (the working directory) holds the program, which Setup installs, an upgrade replaces, and DVX only reads; everything written while DVX runs goes in the user folder, so it is the one folder to back up.
| Folder | Holds |
|---|---|
SYSTEM |
DVX’s own tools and files, and the shipped DVX.INI and ASSOC.INI |
LIBS, WIDGETS |
The libraries and widgets |
APPS\<vendor>\<program> |
A program, its help, and DATA (the files it ships; read-only) |
SHARED |
FONTS, SOUNDS, THEMES, WPAPER, BANKS, and SAVERS: what DVX and add-on packages ship for every program (an add-on’s in a folder of its vendor’s, such as FONTS\ACME) |
USER (the user folder) |
DVX.INI, ASSOC.INI (the user’s changes to SYSTEM’s), DVX.LOG, PROGRAMS.CAC (the shell’s program cache), SECLINK.RND (the random store the network and secure links keep), the user’s own FONTS, SOUNDS, THEMES, WPAPER, BANKS, and SAVERS, KEYS (publishers' keys the user trusts), APPS\<program path> (each program’s settings and saved files), and DOWNLOAD (Terminal’s downloads; Software’s packages being fetched in DOWNLOAD\SOFTWARE, PKGNET_DIR) |
Only packages put files in SHARED: DVX’s own, and add-on packages (pkg.lib), each in its vendor’s folders. A program reads it but never writes or installs into it; a program’s own files live with it (its DATA folder, or resources inside the .app), under its own vendor and program folder, so two programs' files never collide.
platformUserInit, called once by the loader (and not exported to modules), decides the user folder: the folder the DVXUSER environment variable names, else USER in the DVX folder, made when missing. When it cannot be written (DVX on a CD-ROM, or a folder DVXUSER names that cannot be written), DVXUSER in the TEMP folder is used instead and platformUserInTemp is true; without a TEMP folder nothing can be saved and platformIsReadOnly is true, and DVX.INI is read from the folder that cannot be written. The first start copies SYSTEM\DVX.INI to the user folder; the first start in TEMP (no DVX.INI there yet) copies every file of the folder that cannot be written but its log (DVX.LOG) — DVX.INI, ASSOC.INI, the programs' folders in APPS, and the user’s own fonts, themes, sounds, and wallpapers — and SYSTEM’s DVX.INI only when that folder has none, so a read-only copy of DVX starts from its own user folder with a TEMP folder or without. Later starts copy nothing again. platformUserEnvDir is the folder DVXUSER names (native separators, "" when it is not set or is too long for a path; platformUserDirOf reads DVXUSER through it), which the shell’s start-up message names when it is the folder that cannot be written. platformUserDir is the folder (DVXUSER or USER before platformUserInit has decided); platformUserPath joins a name to it; platformDvxIniPath is its DVX.INI. platformUserDirOf is the user folder of a DVX installed in another folder (DVXUSER, else that folder’s USER), for Setup: DVXUSER is read as that DVX reads it from its own folder, so a folder without a drive is in that DVX folder, and one rooted without a drive is on its drive.
DVX’s command-line switches: DVX /SAFE (or Shift held while it starts) is a safe start, in safe video mode and without add-on libraries and widgets; DVX /RUN=program [arguments] starts a program, or opens a document, once the desktop is up. DVX_SWITCH_NEXT and DVX_SWITCH_BACK are DVX.COM’s (shell.run in the shell’s help): /NEXT=folder is where DVX leaves DVX.COM a DOS program to run instead of running it itself, and /BACK says this start is DVX coming back after one. platformFindSwitch is the argv index of the argument that starts with a switch (matched without case by its first letters, as DOS takes switches), or -1; the loader and the shell both use it. The search ends at DVX_SWITCH_RUN (which itself is found): everything after it is the /RUN= command, so DVX /RUN=GAME.APP /SAFE passes /SAFE to the game, and DVX’s own switches go before /RUN=.
platformAppUserDir is a program’s folder in the user folder: APPS\KPUNCH\TERMINAL\TERMINAL.APP gives USER\APPS\KPUNCH\TERMINAL; a program kept in the user folder gives APPS and its path in there (USER\PROJECTS\TODO\TODO.APP, and the project run from DVX BASIC, gives USER\APPS\PROJECTS\TODO); a program outside the DVX folder, or right in the user folder, gives USER\APPS\<its file name without the extension>. It is not made here (the shell’s userDir and BASIC’s App.User are made on first use).
SHARED and the user folder have the same six kinds of folder (DvxKindE): fonts, sounds, themes, desktop pictures, MIDI instrument banks, and screen savers. Each may hold folders of add-on vendors (SHARED\FONTS\ACME), one level deep, whose files are named VENDOR\NAME. platformKindName is a kind’s folder name; platformKindDir is SHARED’s (user false) or the user’s (user true); platformKindBrowseDir is where a file dialog for the kind starts (the user’s when it exists, else SHARED’s). platformKindFind finds a file of a kind by name (NAME or VENDOR\NAME, either separator), the user’s first, so a user’s file of the same name wins; any other name with a folder in it, or an absolute one, is taken as the path it is (a VENDOR\NAME not in the kind’s folders is tried that way too). platformKindNameOf is the other way: a file in one of the kind’s folders gives its name alone, or VENDOR\NAME in a vendor’s folder, which is what settings store (DVX.INI [sounds], [desktop] wallpaper and saver, and [audio] midiBank), so moving the user folder or DVX keeps them working. platformKindReadDir lists both folders: the user’s names (sorted, case ignored), then SHARED’s not among them, with each vendor folder’s files as VENDOR\NAME (the folders themselves are not listed), a NULL after the last name as dvxReadDir gives it; free it with dvxReadDirFree. BASIC: FileOpsUserDir$, FileOpsUserPath$, FileOpsUserInTemp, FileOpsKindDir$, FileOpsKindBrowseDir$, FileOpsKindFind$, FileOpsKindName$, and FileOpsKindList (fileops.bas, with FILEOPS_KIND_FONTS to FILEOPS_KIND_SAVERS), and App.User for a program’s own folder.
Read-only media: platformSetReadOnly / platformIsReadOnly / platformDirIsWritable / platformTempDir / platformSetLogMemory / platformLogMemory / platformLogPath / platformSetLogLimit
#define PLATFORM_LOG_MEM_MAX 16384
#define PLATFORM_LOG_FILE_MAX (512 * 1024)
void platformSetReadOnly(bool readOnly);
bool platformIsReadOnly(void);
bool platformDirIsWritable(const char *dir);
const char *platformTempDir(void);
void platformSetLogMemory(void);
const char *platformLogMemory(void);
const char *platformLogPath(void);
void platformSetLogLimit(int32_t maxBytes);
platformUserInit records with platformSetReadOnly whether anything can be saved: platformIsReadOnly is true only when the user folder cannot be written and there is no TEMP folder to put it in (platformTempDir: the TEMP or else TMP variable in native separators, NULL when neither is set; platformDirIsWritable creates and removes a scratch file in dir). Then: the log is kept in memory; prefsSave and prefsSaveAs keep a file they cannot write in memory, and prefsLoad reads it back until DVX exits (prefsMemorySaves counts these saves); the shell says so once at startup (and, when the user folder went in TEMP, says that instead), and once more at the first such save of the session, so a change that only lasts until DVX exits never looks saved; and a program that allows several copies runs only once when there is no TEMP folder (a second copy is a temporary copy of the module). The boot-time help rebuild is skipped when nothing can be saved or the APPS folder cannot be written (its output and counts could not be kept). platformSetLogMemory sends dvxLog to a buffer holding the latest PLATFORM_LOG_MEM_MAX bytes (the oldest whole lines are dropped), which platformLogMemory returns (the shell’s System Information shows it, the only place a user can read it); platformSetLogPath goes back to a file. platformLogPath is the file dvxLog appends to, "" while the log is in memory. platformSetLogLimit keeps a log file to maxBytes (0, the default: no limit; see dvxLog); the loader sets PLATFORM_LOG_FILE_MAX for DVX.LOG. SETUP.EXE logs to memory unless /LOG= is given, so it never writes to its own disk.
platformLineEnding / platformStripLineEndings
const char *platformLineEnding(void);
int32_t platformStripLineEndings(char *buf, int32_t len);
platformLineEnding returns the native line ending string ("\r\n" on DOS). platformStripLineEndings removes every '\r' from buf[0..len) in place and NUL-terminates the result, so buf must hold at least len + 1 bytes. Returns the new length.
2.22.13. String Helpers
dvxSkipWs
const char *dvxSkipWs(const char *s);
Advance past leading spaces and tabs. Returns s unchanged if NULL or already non-whitespace.
dvxTrimRight
int32_t dvxTrimRight(char *buf);
Strip trailing spaces, tabs, carriage returns, and newlines from buf in place. Returns the new length.
dvxStrListAdd
#include "stb_ds_wrap.h"
static inline bool dvxStrListAdd(char ***list, const char *s);
Add a malloc’d copy of s to the stb_ds string list *list, the kind dvxReadDir makes and dvxReadDirFree frees. Returns false, with nothing added, when there is no memory for it, so the list never holds a NULL entry. It is inline in stb_ds_wrap.h, so the copy comes from the caller’s own strdup and a program’s copies count as its memory. A list whose entries must stay in step with something else (one entry per row or per item) cannot skip one: check the result and give up the whole list, or add the copy yourself.
dvxCopyTrimmed
int32_t dvxCopyTrimmed(char *dst, int32_t dstSize, const char *src);
Copy src into dst without its leading spaces and tabs or its trailing whitespace, truncated to fit dstSize. A NULL src gives an empty string. Returns the length of the result. The usual way to read a trimmed value out of a text box: dvxCopyTrimmed(name, sizeof(name), wgtGetText(input)).
dvxNextArg
#define DVX_ARG_QUOTE '"'
const char *dvxNextArg(const char *p, char *out, int32_t outSize, bool *quoted);
Copy the next argument of the command line p into out and return the text after it, or NULL when only blanks are left (or p is NULL). Arguments are separated by blanks and tabs; one that starts with a double quote runs to the closing quote (or the end), keeps its blanks, and loses the quotes, and *quoted is set. The copy is truncated to fit outSize. This is the one rule for splitting command lines: the shell’s Run command, program launch arguments, and the BASIC COMMAND$ function all use it. Walk every argument with:
const char *p = args;
bool quoted;
char arg[DVX_MAX_PATH];
while ((p = dvxNextArg(p, arg, sizeof(arg), "ed)) != NULL) {
// use arg
}
dvxArgAppend
int32_t dvxArgAppend(char *buf, int32_t bufSize, int32_t pos, const char *arg);
Append arg to the command line in buf at pos as one argument that dvxNextArg reads back whole: in double quotes when it holds a blank or a tab (a long name such as C:\My Programs\Thing.app), as it is otherwise. No blank is put before it: between two arguments the caller appends one first (dvxStrAppendf(buf, bufSize, pos, " ")). An empty arg adds nothing. Returns the new length, or -1 when it does not fit (as dvxStrAppendf). The shell’s file-type associations and its help (shellOpenHelpFile, which F1 and Help menus use) build their command lines with it; BASIC programs have ShellArgQuote$.
2.22.14. DXE Module Support
platformRegisterDxeExports
void platformRegisterDxeExports(void);
Register platform and C runtime symbols with the dynamic module loader so DXE modules can resolve them at load time. The loader’s own, so not exported to modules.
platformModuleClose
int platformModuleClose(void *handle);
dlclose for modules: a module’s dlclose is this one. It closes a module opened with platformModuleOpen (dlclose’s return), and once the module’s last open is closed drops the note crash reports place a fault with: the loader notes each module it opens with where it is in memory and logs "Module: <path> at 0x<address> (<n> bytes)", and the crash report names the module a faulting address is in and the offset into it (see Debugging in the SDK guide).
The C Library a Module Gets
A module links no C library of its own: dvx.exe gives it dvx.exe’s, and a module that uses a name it does not give does not load: a program’s load fails with a message naming the symbol ("unresolved symbol: _j0"), and a widget or library is skipped as DVX starts, the name in DVX.LOG ("dlopen: unresolved symbol: _j0"). It gives the standard C library and DJGPP’s common additions to it (strings, ctype, stdio, files and directories, time, the POSIX file calls, regular expressions, the drand48 and multibyte functions), the floating-point library, float and double (sqrtf, powf, and the rest), and the helpers GCC calls for builtins and 64-bit arithmetic (__popcountsi2, __udivdi3, ...), but not the Bessel and gamma functions (j0, j1, jn, y0, y1, yn, gamma, gamma_r, lgamma, lgamma_r, and their float versions: a module that needs one links DJGPP’s math library into itself, LIBS = $(DJGPP_PREFIX)/i586-pc-msdosdjgpp/lib/libm.a in its Makefile, which brings nothing that clashes with DVX), dlopen (platformModuleOpen opens a module with what it needs), the complex-number helpers, and the calls that would take the machine from DVX (fork, spawn, exec, the conio console). Where sharing the machine with DVX and every other program needs it, the call a module gets is DVX’s own:
-
malloc, calloc, realloc, free, strdup, strndup: dvxMem.h’s, counted against the program (the Task Manager’s memory column).
-
exit: ends only the program; its atexit handlers run, then it ends as End Task ends it (platformAppExit).
-
abort, _exit, _Exit: end only the program, its atexit handlers not run (abort reports status PLATFORM_ABORT_STATUS).
-
atexit: the handler belongs to the program (one a library registers with no program running belongs to DVX). A program’s handlers run, newest first, before it is unloaded: at exit() and whenever its appShutdown would run (it returns from appMain or closes its last window, End Task while it responds, DVX exiting). abort(), _exit(), a fault, and End Task of a program that does not respond drop them.
-
assert: a failed assert is logged ("Assertion failed: <test>, file <file>, line <line>, function <name>") and ends only the program, as abort() does.
-
sleep, usleep, delay: wait while DVX runs on. On a program’s own task (appMain of a main-loop program, or a task it made) every other task runs meanwhile. On DVX’s own task, where every window callback runs, nothing else does (a frame there could run the waiting program’s own handlers inside its call), so a callback waits with a timer (platformTimerAdd, the Timer widget) instead.
-
system: refused and logged: -1 with errno ENOSYS (system(NULL), asking for a command interpreter, is 0). A program runs a DOS program with dvxRunDos, which steps DVX aside first.
-
signal: SIGSEGV, SIGFPE, and SIGILL are refused and logged (SIG_ERR, errno EINVAL): DVX’s crash handler keeps them, so a fault ends only the program. Any other signal is the C library’s.
-
getchar, gets, scanf, vscanf: end of file at once: DVX has no console for a program.
-
fgetc, getc, fgets, fread, fscanf, vfscanf, read: the C library’s, but a read of a stdin that is the console gives end of file.
-
dlclose: platformModuleClose.
A module that writes to stdout or stderr writes to the console under DVX’s screen, which nobody sees; dvxLog writes to DVX.LOG.
2.22.15. Interrupt-Safe Memory
platformLockRegion / platformUnlockRegion
int32_t platformLockRegion(const void *addr, uint32_t size, bool isCode);
int32_t platformUnlockRegion(const void *addr, uint32_t size, bool isCode);
Pin (or unpin) a code (isCode = true) or data range into physical memory so an interrupt handler can touch it without faulting under a paging DPMI host. On DOS this converts the address to linear using the code or data segment base and calls the DPMI lock/unlock linear region services. Shared by the key-up INT 9 hook and the serial driver’s ISR. Returns 0 on success, -1 on failure; a no-op returning 0 on hosts without paging concerns.
2.22.16. Crash Recovery
platformInstallCrashHandler
void platformInstallCrashHandler(jmp_buf *recoveryBuf, volatile int *crashSignal, PlatformLogFnT logFn);
Install signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, logs platform-specific diagnostics via logFn, stores the signal in *crashSignal, then longjmps to recoveryBuf. Calling it again moves the recovery point: recoveryBuf must hold a live setjmp point whenever a fault can come, so a caller that leaves the frame that set it passes another, or NULL. Without a recovery buffer, platformServicesStop runs, the screen goes back to text mode (platformTextMode), and the signal’s default action runs (on DOS the C library’s report, now readable). The shell keeps a recovery point live from its first moment: the main loop’s, a start-up part’s, or the one where DVX stops when it fails while starting.
platformSetCrashTarget
typedef jmp_buf *(*PlatformCrashTargetFnT)(void);
void platformSetCrashTarget(PlatformCrashTargetFnT fn);
A hook the crash handler asks at the time of a fault for where to longjmp: the recovery point of the code that faulted, or NULL for the one platformInstallCrashHandler gave. It runs inside the handler, so it may only read state. The shell gives each program’s task a recovery point of its own at the task’s base (shellTaskRun) and answers with it while that task runs: a fault, or exit() and abort() (platformAppExit), in a program’s task then lands on that task’s own stack, and no frame of the main task is unwound, so a dialog box open on the main task keeps its loop. On the main task itself, each frame of dvxUpdate has a recovery point too (the context’s frameGuard), and the shell answers with the innermost one while a program’s code runs there (currentAppId is a program’s): a callback program’s code that faults or exits inside the loop of a dialog box open on the main task lands back in that frame, which returns as if done once the program is ended, so the box keeps its loop and its answer still reaches the code that opened it. NULL removes the hook.
platformTextMode
void platformTextMode(void);
Put the screen in text mode (mode 3 on DOS) so a message printed as DVX stops can be read, unless it is in that mode already (setting it again would wipe what is on the screen). Nothing is freed: for DVX stopping after a fault, where platformVideoShutdown’s freeing cannot be trusted. Nothing on the host.
platformAppExit / platformAppAbort / platformAppQuickExit / platformAssertFail / platformAtExit / platformSetAppExitHook
#define PLATFORM_ABORT_STATUS 3
typedef void (*PlatformAppExitFnT)(int status);
void platformSetAppExitHook(PlatformAppExitFnT fn);
void platformAppExit(int status);
void platformAppAbort(void);
void platformAppQuickExit(int status);
void platformAssertFail(const char *test, const char *file, int line, const char *func);
int platformAtExit(void (*fn)(void));
What exit(), abort(), _exit() (and _Exit), assert, and atexit() mean to loaded modules (see The C Library a Module Gets). The DXE export table maps them to these (the host build links every app with the same substitution for exit, abort, and atexit, HOST_APP_LDFLAGS in common.mk). exit() runs the program’s atexit handlers first; abort() and _exit() drop them; a failed assert logs its test, file, line, and function, then ends the program as abort() does. All call the hook; the shell’s hook ends only the program that is current, the way End Task does (its task, or its callback running on the shell task, is abandoned through the crash-recovery path and the program is removed without its appShutdown and without a fault message; the log says "'name' called exit (status n); ending it"). abort() reports status PLATFORM_ABORT_STATUS. With no program current, or no hook, they end the process like the C library functions (exit() after DVX’s own atexit handlers). platformAtExit returns 0, or -1 for a NULL handler.
platformLogCrashDetail
void platformLogCrashDetail(int sig, PlatformLogFnT logFn);
Log platform-specific crash diagnostics: on DOS the signal, the registers, and where the faulting EIP is ("EIP is in <module> at offset 0x<offset>", or in no module: DVX.EXE itself). Called internally from the crash handler and exposed for manual invocation.
platformOutOfMemory
void platformOutOfMemory(size_t bytes);
Out-of-memory hook for the stb_ds dynamic arrays and hash maps (arrput, hmput, shput, and friends have no error return). stb_ds_wrap.h points STBDS_OUT_OF_MEMORY at it wherever the stb_ds implementation is compiled. It logs "out of memory (N bytes) in dynamic array" via dvxLog and raises SIGSEGV, so under platformInstallCrashHandler a failed growth takes the normal crash-recovery path: the shell terminates the app that was current (its task, or its callback running on the shell task), and a failure with no app current is logged and the shell returns to its main loop. Without a recovery point (the loader, which installs the handler without one, the tools, the BASIC compiler) the process terminates. It never returns. The stb_ds patch that adds the hook is recorded in thirdparty/stb_ds.PATCHES.md.
2.22.17. VGA Splash Screen
platformSplashInit / platformSplashShutdown
void platformSplashInit(void);
void platformSplashShutdown(void);
Enter/leave VGA mode 13h (SPLASH_W x SPLASH_H x 256) used for the boot splash.
| Define | Value | Description |
|---|---|---|
SPLASH_W, SPLASH_H |
320, 200 |
Splash screen size |
SPLASH_BPP |
8 |
Bits per pixel |
SPLASH_PAL_ENTRIES |
256 |
Palette entries |
SPLASH_PAL_CHANNELS |
3 |
Bytes per palette entry (R, G, B) |
SPLASH_PAL_BYTES |
768 |
Palette size in the file |
SPLASH_PIXEL_BYTES |
64000 |
Pixel data size in the file |
SPLASH_DAC_SHIFT |
2 |
8-bit RGB to 6-bit DAC value shift |
platformSplashLoadRaw
bool platformSplashLoadRaw(const char *path);
Load and display a raw splash file (SPLASH.RAW, written by the bmp2raw tool): SPLASH_PAL_BYTES of palette (6-bit DAC values, R, G, B per entry) followed by SPLASH_PIXEL_BYTES of 8-bit pixels, top-to-bottom scanlines.
platformSplashFillRect
void platformSplashFillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint8_t color);
Fill a rectangle on the mode 13h screen with a palette index. Used to draw the progress bar during module loading.
platformSplashNearestColor
uint8_t platformSplashNearestColor(uint8_t r, uint8_t g, uint8_t b);
Palette index of the loaded splash image closest to an 8-bit RGB color, so overlays drawn on the splash (the progress bar) do not depend on the image’s palette layout. Returns 0 when no splash palette is loaded (always 0 on the host test backend).
Chapter 3. The Shell and Tasks
3.1. DVX Shell Library
The DVX shell library manages the lifecycle of DXE applications: loading, launching, tracking, and reaping. It provides the bridge between the DVX GUI compositor and dynamically loaded DXE3 application modules.
Header: shell/shellApp.h
Loaded as: bin/libs/kpunch/dvxshell/dvxshell.lib
3.1.1. App Model
The shell supports two kinds of DXE apps:
-
Callback-only (hasMainLoop = false) — appMain() runs in the shell’s task 0, creates windows, registers event callbacks, and returns immediately. The app lives through GUI callbacks. Lifecycle ends when the last window is closed (and its shellAppTaskStart work, if one runs, has ended). Simpler and cheaper (no extra stack/task).
-
Main-loop (hasMainLoop = true) — A dedicated cooperative task is created. appMain() runs in that task and can do its own polling loop, calling tsYield() to share CPU. Lifecycle ends when appMain() returns or the task is killed. Needed for terminal emulators, games, or long computations.
Both types use the same DXE interface: an exported appDescriptor and appMain function.
A task an app makes itself with tsCreate is the app’s too: it runs as the app (ctx->currentAppId, so what it allocates and the windows it opens are the app’s) and is killed when the app ends, however it ends (shellAppTaskStart is still the way to keep a callback-only app running without a window).
3.1.2. DXE Interface
Every .app DXE module must export these symbols (COFF convention uses leading underscore):
| Symbol | Type | Required |
|---|---|---|
_appDescriptor |
AppDescriptorT |
Yes |
_appMain |
int32_t (*)(DxeAppContextT *) |
Yes |
_appShutdown |
void (*)(void) |
No |
The shell resolves appDescriptor at dlopen time; if missing, the load fails with an error dialog. If its abiVersion is not the shell’s DVX_ABI_VERSION the app was built against other headers: the load fails with "This program was built for a different version of DVX and cannot run." and both numbers go to DVX.LOG; a missing appMain, and a main-loop app whose task cannot be made (a priority out of range, or no memory for its stack), are logged too. The line "Shell: loaded 'name' (id=..., mainLoop=..., entry=0x..., desc=0x...)" is written before appMain runs, so a crash in appMain finds the entry address in the log. appMain is called immediately for callback-only apps or from the new task for main-loop apps. appShutdown, if present, is called when the app ends, after its tasks still running are stopped: at a normal end (shellReapApp), and when End Task or DVX’s exit ends it (shellForceKillApp) unless it faulted, is not responding, or its kill had to wait for its code to return. It must not wait for its own tasks.
3.1.3. Callback-Only vs Main-Loop Apps
The app descriptor’s hasMainLoop flag selects between two very different lifecycles:
-
hasMainLoop = false (callback-only). The shell calls appMain directly on task 0 at dlopen time. The function creates windows, registers event callbacks, and returns. After that the app has no executing thread of its own — it exists purely through GUI callbacks dispatched by dvxUpdate. The shell reaps the app automatically when its last window closes. Best for modal tools, dialogs, and event-driven utilities.
-
hasMainLoop = true (main-loop). The shell creates a dedicated cooperative task (via tsCreate) with the descriptor’s stackSize (or TS_DEFAULT_STACK_SIZE) and priority. appMain runs in that task and can do its own work loop, calling tsYield or any GUI function that yields. The app terminates when appMain returns (the wrapper sets AppStateTerminatingE) or when forced via shellForceKillApp. Best for terminal emulators, games, and any app with continuous background work.
A main-loop app learns that the user closed its window from the window’s onClose (which usually sets a flag its loop checks). A window without one is simply destroyed, and the loop is not told; so when every window a main-loop app had is gone and none of them had an onClose — closed by the user, or destroyed by the app itself — the shell ends the app (shellEndClosedApps, before each of its yields): its tasks are paused at once, so the loop never runs with its window gone, and it is reaped as at a normal end (its tasks killed, then its appShutdown). An app that runs on without a window either sets onClose on its windows or never opens one.
Both app types use the same export interface; only the descriptor’s flags differ. Apps cannot switch modes at runtime.
3.1.4. Icon Conventions
A program’s icon is one picture: its "icon32" resource (DVX_RES_ICON, 32x32; a BMP, PNG, JPEG, or GIF). The shell reads it (shellProgramIcon, shellItemIcon, through the program cache) at the edge a caller asks for: Program Manager draws it at SHELL_PROG_ICON (32) for large icons and SHELL_PROG_ICON_SMALL (16) for small ones, both from that picture. No other icon resource is read, and Task Manager shows none. A program without an icon32 shows Program Manager’s stand-in: a raised square with the first letter of its name.
3.1.5. State Machine
App slots progress through four states:
Free -> Loaded -> Running -> Terminating -> Free
LoadedE is transient (only during shellLoadApp before the entry point is called). TerminatingE means the app’s task has exited, or a force kill was deferred (killPending) because the app’s code was still running, but cleanup has not yet occurred. The shell’s main loop reaps terminating apps each frame via shellReapApps().
3.1.6. Contents
See also: Lifecycle API (Section 3.3); Query API (Section 3.4); Starting Up (Section 3.5); Program Folders API (Section 3.6); Desktop Callbacks (Section 3.7); System Information (Section 3.8); Installed Programs (Section 3.9); Running Programs and Documents (Section 3.10); The Screen Saver (Section 3.11); File Associations (Section 3.12); BASIC Entry Points (Section 3.13); BASIC System Settings (Section 3.15).
3.2. Shell Types and Constants
3.2.2. Constants
- SHELL_APP_NAME_MAX
-
Value: 64. Maximum length of an app name string.
- SHELL_STACK_DEFAULT
-
Value: 0. Use in AppDescriptorT.stackSize to get the default task stack size.
- SHELL_DESKTOP_APP
-
Value: "apps/kpunch/progman/progman.app". Default shell app: Program Manager.
- SHELL_INI_SECTION
-
Value: "shell". DVX.INI section of the shell’s own keys.
- SHELL_INI_DESKTOP
-
Value: "desktop". [shell] key: the shell app, the program DVX starts first and exits with (SHELL_DESKTOP_APP when missing).
- SHELL_INI_WELCOME
-
Value: "welcome". [shell] key: a program started after the shell app while the key exists (see Starting Up).
- SHELL_HELP_TOPIC_MAX
-
Value: 128. Capacity of DxeAppContextT.helpTopic.
- DVX_HELP_VIEWER_APP_LITERAL
-
Value: "APPS\KPUNCH\DVXHELP\DVXHELP.APP". Path of the help viewer app.
- DVX_SYSTEM_HELP_FILE_LITERAL
-
Value: "APPS\KPUNCH\PROGMAN\DVXHELP.HLP". Path of the system help file (F1 fallback, Program Manager’s Help menu).
SHELL_APP_CALL
SHELL_APP_CALL(app, call);
Brackets a direct shell call into an app’s code (appMain of a callback-only app, appShutdown, onHelpQuery, onNewArgs). It counts the call on the calling task (shellAppCallEnter / shellAppCallLeave), so a force kill issued from inside that call is deferred until the call has returned.
3.2.3. AppDescriptorT
Exported by every DXE app as a global named appDescriptor. The shell reads it at load time to determine how to launch the app. Declare it with SHELL_APP_DESCRIPTOR, which names the global and fills abiVersion:
SHELL_APP_DESCRIPTOR(
.name = "Ticker",
.hasMainLoop = true,
.multiInstance = false,
.stackSize = SHELL_STACK_DEFAULT,
.priority = TS_PRIORITY_NORMAL
);
| Field | Type | Description |
|---|---|---|
abiVersion |
uint32_t |
DVX_ABI_VERSION the app was built with (always the first field). The shell refuses the app when it differs from its own. |
name[SHELL_APP_NAME_MAX] |
char[] |
Display name of the application. |
hasMainLoop |
bool |
false = callback-only, true = dedicated task. |
multiInstance |
bool |
true = allow multiple simultaneous instances via temp copy. |
stackSize |
int32_t |
SHELL_STACK_DEFAULT or explicit byte count for the task stack (main-loop apps). |
priority |
int32_t |
Main-loop apps: their task’s priority, TS_PRIORITY_LOW..TS_PRIORITY_HIGH (0..10); any other value makes the launch fail, and one left out is 0 (TS_PRIORITY_LOW). Callback-only apps have no task of their own: unused. |
3.2.4. DxeAppContextT
Passed as the sole argument to appMain(). Gives the app access to the shell’s GUI context and its own identity. Heap-allocated by shellLoadApp so its address is stable across reallocations of the internal app slot table (apps may safely cache the pointer in their static globals).
| Field | Type | Description |
|---|---|---|
shellCtx |
AppContextT * |
The shell’s GUI context (for creating windows, drawing, etc.). |
appId |
int32_t |
This app’s unique ID (slot index, 1-based). |
appPath[DVX_MAX_PATH] |
char[] |
Full path to the .app DXE file. |
appDir[DVX_MAX_PATH] |
char[] |
Directory containing the .app file (for loading resources). |
userDir[DVX_MAX_PATH] |
char[] |
The program’s folder in the user folder, for its settings and the files it saves (e.g. USER\APPS\KPUNCH\DVXBASIC). DVX does not make it for a C program: call shellEnsureUserDir before writing the first file there (a BASIC program’s App.User is made when it first asks for it). |
args[1024] |
char[] |
Launch arguments (empty string if none): blank-separated, one with blanks in double quotes. Walk them with dvxNextArg. A document opened through its file type arrives here (see File Associations); BASIC programs read these arguments with COMMAND$. |
helpFile[DVX_MAX_PATH] |
char[] |
Help file path (for F1 context help, and the Help menu’s shellOpenHelpFile). Before appMain the shell sets it to <app>.hlp in the .app’s directory when that file exists (else empty); appMain may change it. |
helpTopic[128] |
char[] |
Current help topic ID (updated by the app at runtime). Size is SHELL_HELP_TOPIC_MAX. |
onHelpQuery |
void (*)(void *ctx) |
Optional callback the shell fires on F1 so the app can refresh helpTopic from context. |
helpQueryCtx |
void * |
Opaque context pointer passed to onHelpQuery. |
onNewArgs |
void (*)(void *ctx, const char *args) |
Optional. Set by an app that can take new launch arguments while running. Loading a single-instance app that is already running and sets this hands it the new arguments and raises it (the load returns its app id) instead of saying it is already running; F1 hands its "helpfile [topic]" arguments to a running help viewer that sets this, and raises it, instead of loading another copy. |
newArgsCtx |
void * |
Opaque context pointer passed to onNewArgs. |
The appDir field is derived from the .app file path at load time so apps can find their own resources via relative paths. This is necessary because the working directory is shared by all apps in DOS. The user directory is mirrored from the app path in the user folder (platformAppUserDir): an app at APPS\KPUNCH\DVXBASIC\dvxbasic.app gets USER\APPS\KPUNCH\DVXBASIC. A full path inside the DVX directory (for example one picked with the Task Manager’s Run... dialog) is mirrored the same way. An app outside the DVX directory, or loaded by a bare file name, gets USER\APPS\<file name without extension>. The user folder is USER in the DVX directory unless the DVXUSER environment variable names another (see DVX Folders in the architecture guide).
3.2.5. AppStateE
| Value | Description |
|---|---|
AppStateFreeE |
Slot is available for reuse. |
AppStateLoadedE |
DXE loaded, entry point not yet called (transient). |
AppStateRunningE |
Entry point called, app is active. |
AppStateTerminatingE |
Shutdown in progress, awaiting reap. |
3.2.6. ShellAppT
Per-app slot in the shell’s app table. Slot 0 is reserved for the shell itself; apps use slots 1 and above.
| Field | Type | Description |
|---|---|---|
appId |
int32_t |
Unique ID (slot index, 1-based; 0 = shell). |
name[SHELL_APP_NAME_MAX] |
char[] |
Display name from AppDescriptorT. |
path[DVX_MAX_PATH] |
char[] |
Original DXE file path. |
tempPath[DVX_MAX_PATH] |
char[] |
Temp copy path for multi-instance (empty if not a copy). |
dxeHandle |
void * |
dlopen() handle for the DXE module. |
state |
AppStateE |
Current lifecycle state. |
hasMainLoop |
bool |
Whether this app has a dedicated task. |
mainTaskId |
uint32_t |
Task ID if hasMainLoop (0 once it has ended), else 0. |
entryFn |
int32_t (*)(DxeAppContextT *) |
Pointer to appMain. |
shutdownFn |
void (*)(void) |
Pointer to appShutdown (may be NULL). |
dxeCtx |
DxeAppContextT * |
Heap-allocated context (address stable across realloc). |
taskCodeDepth |
int32_t * |
Per task id: SHELL_APP_CALL calls into this app still open on that task’s stack. |
killPending |
bool |
A force kill was deferred; shellReapApps finishes it. |
faulted |
bool |
It crashed: its force kill runs no kill hooks (shellRegisterAppKill) and no shutdownFn. |
closeless |
bool |
A main-loop app with windows, none with an onClose, as last seen (shellEndClosedApps). |
workTaskId |
uint32_t |
The task shellAppTaskStart started for it, while that runs; else 0. |
workFn, workArg |
void (*)(void *), void * |
What that task runs. |
3.3. App Lifecycle API
3.3.2. shellLoadApp
int32_t shellLoadApp(AppContextT *ctx, const char *path);
Load and start an app from a DXE file. Returns the app ID (>= 1) on success, or -1 on error.
For callback-only apps, appMain() runs synchronously and returns before shellLoadApp returns. For main-loop apps, a cooperative task is created and the app begins running on the next tsYield().
If multiInstance is false in the app’s descriptor and the same DXE is already loaded, the running app is handed args through its onNewArgs and raised, and its app id is returned, when it sets onNewArgs; otherwise the call fails with an error dialog. If multiInstance is true, the DXE is copied to a temp file so dlopen gets an independent code and data image.
3.3.3. shellLoadAppWithArgs
int32_t shellLoadAppWithArgs(AppContextT *ctx, const char *path, const char *args);
Load and run an app with arguments. The args string is copied into DxeAppContextT.args before appMain() is called. Otherwise identical to shellLoadApp().
3.3.4. shellReapApps
bool shellReapApps(AppContextT *ctx);
Scan for and reap finished apps. Call once per frame from the main loop.
Returns true if any apps were reaped, so the caller can trigger a desktop refresh. For main-loop apps, termination is detected by the AppStateTerminatingE state (set when appMain returns, or by shellEndClosedApps). For callback-only apps, termination is detected when no windows remain for that app and its shellAppTaskStart work, if any, has ended; a task it made with tsCreate does not keep it.
3.3.5. shellReapApp
void shellReapApp(AppContextT *ctx, ShellAppT *app);
Gracefully shut down a single app. Kills its tasks that are still alive (ones it made with tsCreate, or a main loop shellEndClosedApps stopped), so none of its code runs beside the shutdown hook; calls the app’s shutdownFn (if present), as the app; destroys all windows belonging to the app; runs the libraries' cleanup hooks (shellRegisterAppCleanup); releases any widget classes, system-wide hotkeys, fonts, and timers the app registered and did not unregister (wgtUnregisterAppClasses, dvxUnregisterAppHotkeys, ...), closes the DXE handle, and frees the context. The slot returns to AppStateFreeE. The memory the app still has allocated is not freed (other code may hold it): its count is only reset (dvxMemResetApp).
3.3.6. shellForceKillApp
void shellForceKillApp(AppContextT *ctx, ShellAppT *app);
Forcibly kill an app. Used by the Task Manager "End Task" (through shellEndTask), a screen saver that would not close, DVX’s exit (shellTerminateAllApps), and crash recovery (which marks the app faulted first). First the app’s tasks are killed (a main-loop app’s, a work task shellAppTaskStart started, and any it made with tsCreate; frees their stacks, and any dispatch frames still open on them are dropped from the context’s dispatch depth), so none of its code runs beside what follows. Then, unless it faulted or is not responding (dvxAppIsHung) — a hung or faulting app’s own code cannot be trusted to run — its shutdownFn runs as it does at a normal end, so it frees what only it can (accelerator tables, context menus, its heap), and the libraries' kill hooks (shellRegisterAppKill) end what they run for the app (unless it faulted). The shell then drops every idle and desktop-update callback the app registered, destroys all of the app’s windows, runs the cleanup hooks, releases the widget classes, system-wide hotkeys, fonts, and timers the app registered, and finally closes the DXE handle (unmaps the code). Closing the DXE before destroying windows would cause callbacks into unmapped code. End Task from inside a dialog the shutdownFn opened is finished by shellReapApps once the hook returns.
If the app’s code may still be running underneath the call — End Task clicked in a dialog the app has open, a kill issued from one of the app’s own tasks, or from inside a shell call into the app — the unload is deferred: the app’s windows are hidden and queued for destruction, the slot is marked Terminating, and the shell finishes the kill (without shutdownFn) at the next safe point of its main loop, once that code has returned. Code of the app on the shell’s task that does not return but keeps DVX running — an event handler that loops on dvxUpdate, or a dialog box of its own — is not waited for: at its next frame (the frame guard, see shellTaskRun) the shell discards it, as a crash there would be, back to the innermost frame begun outside the app’s code, which returns as if done (frames between, such as another app’s handler that called into it, go too). The kill then finishes. Event-handler frames on the app’s own task do not hold the kill back, since they end with the task: an app stuck in an endless event handler is killed at once (or at the next main-loop pass).
3.3.7. shellEndTask
bool shellEndTask(AppContextT *ctx, int32_t appId);
#define SHELL_EXIT_TITLE "Exit DVX"
#define SHELL_EXIT_ASK "Are you sure you want to exit DVX?"
End a running app at once, the way Task Manager’s End Task and BASIC’s ShellRunningKill do: shellForceKillApp, then shellDesktopUpdate. Ending the shell app exits DVX, so it is never ended without a word: shellEndTask asks Exit DVX’s question first (SHELL_EXIT_TITLE / SHELL_EXIT_ASK, the question the Program Manager asks as its window closes). No changes nothing. Yes is shellRequestExit, as Exit DVX: every other app is asked to close, each with its own save prompt, and one that stays open stops the exit; only a desktop that does not respond (dvxAppIsHung) is force-killed, and its ending then exits DVX the same way (see The desktop ending). False when the app is not running or the user said No; true otherwise.
3.3.8. shellOpenHelpFile / shellOpenHelp
void shellOpenHelpFile(AppContextT *ctx, const char *helpFile, const char *topicId);
void shellOpenHelp(AppContextT *ctx, const char *args);
Show help. shellOpenHelpFile opens the help file helpFile at the topic topicId, as F1 does; it is the call for a program’s Help menu:
shellOpenHelpFile(ctx->shellCtx, ctx->helpFile, NULL); // Help > Contents
shellOpenHelpFile(ctx->shellCtx, ctx->helpFile, "myapp.settings"); // a topic
It hands shellOpenHelp the command line "helpfile [topicId]", each of the two one argument, in double quotes when it holds a blank (dvxArgAppend), so a help file whose path has blanks (C:\My Programs\MyApp\MyApp.hlp) needs nothing more. A NULL or empty topicId opens the file at its default topic. A NULL or empty helpFile opens the system help, as shellOpenHelp(ctx, "") does, and topicId is then ignored; so do a helpFile and topicId too long for one command line (SHELL_ARGS_MAX). BASIC programs have HelpView and HelpViewTopic (help.bas), which call it.
shellOpenHelp takes the command line itself: args is "helpfile [topicId]", a path with blanks in quotes; empty or NULL args open the system help. A bare path with a blank in it is two arguments there, so a program passes its help file to shellOpenHelpFile instead. Either way a running help viewer that accepts new arguments (onNewArgs) is given them and raised; otherwise a new viewer is loaded.
3.3.9. shellTaskDepthForget / shellTaskDepthShare / shellAppCodeForgetTask / shellAppCodeSave / shellAppCodeRestore
void shellTaskDepthForget(uint32_t taskId);
int32_t shellTaskDepthShare(uint32_t taskId);
void shellAppCodeForgetTask(uint32_t taskId);
int32_t *shellAppCodeSave(uint32_t taskId);
void shellAppCodeRestore(uint32_t taskId, const int32_t *saved);
The context’s dispatch depth counts event-dispatch frames on every task’s stack. shellTaskDepthShare returns one task’s share. When a task is killed its frames can never unwind: shellTaskDepthForget removes its share, and (through shellAppCodeForgetTask) the SHELL_APP_CALL calls it held. Crash recovery does the same for the crashed task, and, after a crash that went back to the main loop, for the shell’s own task too. shellAppCodeSave returns the SHELL_APP_CALL calls open on a task’s stack now, as each app’s count (an stb_ds array by app id to arrfree; NULL when there are none), and shellAppCodeRestore puts them back so: each frame of the shell’s task saves them as it begins, and a crash that lands back in that frame (see shellTaskRun) restores them, with that task’s share of the dispatch depth, so the calls made in the frames the crash discarded do not count any more.
3.3.10. shellFrameInApp
bool shellFrameInApp(int32_t appId);
True when a frame of the shell’s task began while appId was the running program (each frame’s recovery point records it): that program’s code — an event handler of it that pumps dvxUpdate, a dialog box it opened — is on the shell’s stack below, whatever program the caller runs as. shellForceKillApp asks it, so a kill from an idle handler (the screen saver’s end of a saver that would not close, a library’s) is deferred like one from a nested event loop, never unloading the program under its own code.
3.3.11. shellTaskRun
void shellTaskRun(int32_t appId, void (*body)(void *arg), void *arg);
Runs body(arg) as the whole life of the calling program task (a main-loop app’s appMain, or its shellAppTaskStart work), with a recovery point of the task’s own at its base (the crash handler finds it through platformSetCrashTarget). A crash, or exit() or abort(), in that task lands there, on the task’s own stack: the task is paused for good, and the shell’s own task ends the program at its next turn (after its yield), inside whatever loop it is in. No frame of the shell’s task is unwound, so a dialog box it has open (a callback program’s, or the shell’s) keeps its loop, and the "Application Error" box opens over it. When the code that crashed was another program’s (a callback run on this task), that program is ended too. Returns when body does.
The shell’s own task has recovery points of its own too: each frame of dvxUpdate it runs (the context’s frameGuard) sets one, and a crash, exit(), or abort() in a program’s code during a frame there (currentAppId is a program’s: a callback program’s timer, paint, or event handler, run by the loop of a dialog box open on the shell’s task, say) lands back in the innermost frame. What the frames it discarded left open is put back as it was when the frame began (the current program, the task’s dispatch frames and SHELL_APP_CALL calls, the idle and desktop-update walks), the program is ended as above, and the frame returns as if done: the frames below it go on, so the box keeps its loop and its answer still reaches the code that opened it. A crash in DVX’s own code there (no program current) still goes back to the main loop’s recovery point, which drops every frame’s.
When the program ended had a modal window of its own (a dialog box on its task), destroying it gives the modal input back to the window that was modal before it (dvxModalBegin keeps the stack), so a dialog box under it stays modal.
3.3.12. shellTerminateAllApps
void shellTerminateAllApps(AppContextT *ctx);
End all running apps. Called during shell shutdown, after the main loop has exited, so every active app is released immediately (never deferred), each as shellForceKillApp ends it: its tasks killed, then its shutdownFn unless it faulted or does not respond. By then Exit DVX (below) has already given every app except the shell app the chance to close itself; what is left is the shell app and apps that had no visible window to close.
3.3.13. shellEndClosedApps
void shellEndClosedApps(AppContextT *ctx);
Ends each main-loop app whose windows, as last seen, all had no onClose and are now all gone (destroyed or on their way out): it logs "Shell: 'name' has no window left and none had an onClose; ending it", marks the app Terminating, and pauses its tasks at once (the calling task too, when it is one of them: it never returns), and shellReapApps reaps it. The shell calls it before each of its yields, from any task’s frame, so such an app never gets a turn with its window gone.
3.3.14. Exit DVX: shellRequestExit / shellRunExitRequest / shellCloseAllApps
void shellRequestExit(void);
void shellRunExitRequest(AppContextT *ctx, int32_t keepAppId);
bool shellCloseAllApps(AppContextT *ctx, int32_t keepAppId);
Exiting DVX never closes an app without first asking it to close, the way the user would. The shell app’s Exit command (Program Manager’s File > Exit DVX and its window’s close box, after its own "Are you sure?" confirmation) calls shellRequestExit, which only records the request. The shell’s main loop calls shellRunExitRequest after every frame; when a request is pending it clears it, runs shellCloseAllApps for every app except the shell app, and calls dvxQuit only if that returns true. Otherwise DVX keeps running.
shellCloseAllApps asks the running apps to close one at a time, in app-slot order, exactly as if the user had closed their windows: for each app, its oldest visible window is raised and dvxRequestWindowClose is called on it inside a dispatch frame, so the window’s onClose runs just as it does for the close box or Alt+F4, with the reason WinCloseExitE (shellCloseApp’s: WinCloseRequestE). A C app’s onClose shows its own save prompt; a BASIC app’s form runs QueryUnload (UnloadMode vbAppWindows; for shellCloseApp vbAppTaskManager) and Unload. This repeats with the app’s next visible window until it has none left or the app has ended. Windows that hide on close (tool palettes) count as closed, and hidden windows are left alone. Apps that close are reaped normally (their shutdownFn runs). Between requests the shell keeps pumping frames (dvxUpdate, a task yield, shellReapApps), so main-loop apps can react.
A window that is still open after a request is judged as follows:
-
If the app created a window while handling the request (ctx->windowsCreated changed — its save prompt) and no dialog box is still open, the user chose to keep it (Cancel). shellCloseAllApps returns false at once: that app and every app not yet asked keep running untouched. Apps already closed stay closed.
-
If the app showed nothing and still has the window after 5 seconds, it is not responding. The shell asks "'name' is not responding to the request to close. End it and continue exiting DVX?". Yes ends it with shellForceKillApp and the exit continues; No returns false.
shellCloseAllApps also returns false, without asking any app, when a dialog box is already open (ctx->modalWindow): the dialog is raised so it can be answered first. It pumps the event loop, so call it only from the shell’s top level, never from inside a callback. An app ended from the Task Manager while the sequence runs simply counts as closed.
3.3.15. Closing one app: shellRequestAppClose / shellRunCloseRequests / shellCloseApp
void shellRequestAppClose(int32_t appId);
void shellRunCloseRequests(AppContextT *ctx);
bool shellCloseApp(AppContextT *ctx, int32_t appId);
shellCloseApp asks one app to close exactly as shellCloseAllApps asks each (the same routine): its visible windows are closed the way the user would close them, so its save prompt or QueryUnload runs, and one that does not respond is offered to be ended ("'name' is not responding to the request to close. End it?", titled Close Program). True when the app is gone or was not running; false when it kept a window or a dialog box is open. It pumps the event loop, so it belongs to the shell’s top level. shellRequestAppClose only records the request (a second request for the same app is not added; an app that ends, or is ended, before it runs has its requests dropped by shellPurgeAppCallbacks, since its slot may be reused); the main loop calls shellRunCloseRequests right after each frame, before shellRunExitRequest, and it asks the waiting apps oldest first. BASIC’s ShellRunningClose is shellRequestAppClose.
The Shell App Ending
The shell itself exits DVX when the shell app ends in any other way — its last window closed, ended from the Task Manager when it no longer responds (shellEndTask asks first), or crashed: an app-cleanup hook (shellRegisterAppCleanup) notices the shell app’s id going away, logs "Shell: the desktop ended; exiting DVX" and calls shellRequestExit, so every other app is asked to close as above. If one of them refuses, DVX keeps running and ends as soon as the last app has ended. A desktop app (C or BASIC) therefore never calls dvxQuit itself.
3.4. Query API
3.4.2. shellGetRunningApp
ShellAppT *shellGetRunningApp(int32_t appId);
As shellGetApp, but only while the app runs normally (AppStateRunningE: started, not still starting and not on its way out); NULL otherwise. The one test Exit DVX, End Task, and the shell’s BASIC calls use for "this program is running".
3.4.3. shellAppSlotCount
int32_t shellAppSlotCount(void);
Return the total number of app slots (including slot 0). Use as the iteration bound when scanning all slots. Slot 0 is the shell itself; app slots start at 1.
3.4.4. shellRunningAppCount
int32_t shellRunningAppCount(void);
Count running apps, not counting the shell itself. Includes apps in both AppStateLoadedE and AppStateRunningE states.
3.4.5. shellRunningAppId
int32_t shellRunningAppId(int32_t index);
The id of running app index, 0 .. shellRunningAppCount() - 1 in slot order (the same apps shellRunningAppCount counts); 0 out of range. BASIC: ShellRunningId.
3.4.6. shellActivateApp
bool shellActivateApp(AppContextT *ctx, int32_t appId);
Bring an app to the front, as the Task Manager’s Switch To does (it calls this): its topmost visible window that is not being destroyed is restored when minimized (dvxRestoreWindow; a maximized window stays maximized), else raised (dvxRaiseWindow), and gets the focus. False when the app has no visible window. BASIC: ShellRunningActivate.
3.5. Starting Up
shellMain brings DVX up in this order: preferences (DVX.INI), the task system, the GUI in the saved display mode, the shell app, then the start-up programs.
3.5.1. Safe Video Mode
The GUI starts in the [video] mode of DVX.INI (prefsGetVideoMode). If that mode cannot be set (dvxInit fails), or a Shift key is held down while DVX starts (read with platformKeyboardGetModifiers just before the mode is set), or DVX was started with /SAFE, the shell starts in the built-in default mode instead (DVX_DEFAULT_VIDEO_W/H/BPP: 640x480, 16 bpp or the closest mode the card has). Before the desktop loads, a message box says so and asks whether to use that mode from now on: Yes writes it to DVX.INI (prefsSetVideoMode, prefsSave); No leaves DVX.INI alone, so the saved mode is tried again next time. If the default mode fails too, DVX does not start.
3.5.2. Start-up Programs
After the shell app has loaded:
-
When the user folder cannot be written to, a message says so once: either that the user folder is in the TEMP folder (platformUserInTemp; SHELL_USER_TEMP_MSG), or, without a TEMP folder, that nothing can be saved and changed settings last until DVX exits (platformIsReadOnly; SHELL_READ_ONLY_MSG). Both suggest setting DVXUSER to a folder DVX can write to. When DVXUSER is set (platformUserEnvDir), the message names that folder instead of DVX’s disk (SHELL_USER_TEMP_ENV_MSG, SHELL_READ_ONLY_ENV_MSG). Then the loader’s notes (the Add-ons message).
-
The program named by DVX.INI [shell] welcome (SHELL_INI_WELCOME), if the key is there. The shipped DVX.INI names the Welcome window, which removes the key when the user checks "Don’t show this again", so the key itself is the "first start" flag.
-
The command given with /RUN= on the DVX command line (DVX_SWITCH_RUN): the program or document after the = and every word after it, as its arguments (re-quoted where they hold blanks), for example DVX /RUN=APPS\KPUNCH\NOTEPAD\NOTEPAD.APP C:\README.TXT. DVX’s own switches (/SAFE) go before /RUN=: platformFindSwitch stops looking at it.
Both are started with shellRunCommand, so a missing program or document is reported to the user ("Cannot find NAME.").
3.5.3. A Crash While DVX Starts
The main loop’s recovery point (setjmp; see platformInstallCrashHandler in the DVX API reference) is set only once the start is over, so the start has recovery points of its own. Each part that runs programs — loading the desktop, the start-up messages (the desktop’s idle work, such as the Startup group, can run while they are up), the Welcome program, and the /RUN= command — runs in startStep with a setjmp of its own: a program that crashes there, or calls exit() or abort(), is ended exactly as in the main loop (crashRecover: the "Application Error" box), and the start goes on with the next part. A desktop that crashes as it loads stops DVX as a desktop that fails to load does. Anywhere else before the main loop — and in a start-up part when no program was running — the crash is DVX’s own: the handler goes to the recovery point set as shellMain begins (startCrashed), which stops the platform’s interrupt services (platformServicesStop), puts the screen in text mode (platformTextMode), prints "DVX stopped while starting: something went wrong inside DVX itself. ..." with where DVX.LOG is, and returns 1. Before shellMain returns by any path, the crash handler is given no recovery point (a later fault takes the platform’s default exit) and the exit hook is removed.
3.6. Program Folders API
Each program has two folders of its own. Its user folder (ctx->userDir) is in DVX’s user folder, mirrored from its path: an app at APPS\KPUNCH\DVXBASIC\dvxbasic.app gets USER\APPS\KPUNCH\DVXBASIC. Settings and every file the program saves go there, apart from the program files, so an upgrade or a reinstall never overwrites them and backing up the user folder keeps them. Its DATA folder, beside its .app, holds the files it ships; DVX never writes there, and on a CD-ROM it cannot be written at all.
A program never writes or installs into SHARED (DVX’s own fonts, sounds, themes, and wallpapers): its own files live in its DATA folder or as resources in its .app.
3.6.1. shellEnsureUserDir
int32_t shellEnsureUserDir(const DxeAppContextT *ctx);
Make the program’s user folder, with all parent folders as needed. Returns 0 on success, -1 on failure. Call it before writing the first file there.
3.6.2. shellUserPath
void shellUserPath(const DxeAppContextT *ctx, const char *filename, char *outPath, int32_t outSize);
Build the full path of a file in the program’s user folder by joining ctx->userDir with filename ("" when it does not fit in outSize). DVX does not make the folder for a C program: call shellEnsureUserDir before writing the first file there.
// Example:
char path[DVX_MAX_PATH];
shellEnsureUserDir(ctx);
shellUserPath(ctx, "PROGMAN.INI", path, sizeof(path));
// -> "USER\APPS\KPUNCH\PROGMAN\PROGMAN.INI"
3.6.3. shellDataPath
void shellDataPath(const DxeAppContextT *ctx, const char *filename, char *outPath, int32_t outSize);
Build the full path of a file the program ships in the DATA folder beside its .app ("" when it does not fit), e.g. "APPS\ACME\MYGAME\DATA\LEVEL1.DAT". Read-only.
3.6.4. Program Cache
Program names, descriptions, and icons come from the programs' own files (their name, description, and icon32 resources), and reading them takes several file opens per program, tens of milliseconds each on a slow disk, every time DVX starts. The shell keeps what it read in PROGRAMS.CAC in the user folder, with each file’s size and time (platformFileStamp), and answers from it while a file is unchanged: shellProgramInfo, shellItemIcon, shellItemIcons, shellItemIconFile, and shellProgramIcon all go through it, so Program Manager and BASIC’s Shell calls (shell.bas: ShellProgramName$, ShellItemIcon$, ...) start without opening any program that has not changed.
A file is checked against its stamp the first time it is asked about after what is installed last changed (platformInstalledChangeCount), and whenever shellProgramScan reads names (the folder is fresh in DOS’s buffers then); a program that changed is read again, and a file that is gone loses its entry. A picture is kept as the image file’s bytes (a DVX file’s icon resource, or a picture file of up to 32 KB) and decoded for the display mode each time; bytes that turn out to be no image are noted as none.
The file is read on first use. A change is saved three seconds after the last one, 4 KB at a time in the shell’s idle time, so no frame waits for the whole write, and what is left at shutdown is saved then; the memory goes after a minute unused. It is DVX’s memory (dvxMemSetApp), whichever program’s call made it. Nothing is saved when DVX cannot save (platformIsReadOnly). Deleting PROGRAMS.CAC is harmless: it is made again. A file rewritten at the same size within two seconds keeps its stamp (DOS keeps a file’s time to two seconds), so a program changed that quickly shows its old name or icon until it changes again.
3.6.5. Random Seed File
When the cryptography library is loaded, the shell feeds keyboard and mouse event timings to its random-number generator (dvxSetInputEntropyHook) and carries generator state across runs in SECLINK.RND in the user folder: the file is read and immediately rewritten at startup, and rewritten again at shutdown. The library is found at run time; without it no seed file is written.
3.7. Desktop Callbacks
The shell wires several AppContextT event hooks (onCtrlEsc, onF1, onTitleChange, idleCallback, busyCallback, inputHere) during startup and exposes them to other DXEs via function-pointer extern and registration API. Desktop managers register a callback to refresh their display when apps come and go. The Task Manager DXE registers its Ctrl+Esc handler via the shellCtrlEscFn extern pointer (see Task Manager documentation); shellOpenTaskManager is the one way to open it.
3.7.1. Shell Event Hooks
| AppContextT field | Handler | Purpose |
|---|---|---|
idleCallback |
shellIdleDispatch |
Runs one frame of Run Minimized (shellMinimizeIdle) and every registered idle handler (see shellRegisterIdle), then yields to cooperative tasks, when dvxUpdate has no input events and no dirty rects. |
busyCallback |
shellBusyDispatch |
After a frame that painted: yields to cooperative tasks, and runs shellIdleDispatch when the idle handlers have not run for 20 ms, so a program that keeps the screen changing never starves the others, audio, or the network. |
inputHere |
shellInputHere |
Input, events, and widget timers are taken on the shell’s own task (or on any task once the shell’s has not taken them for 250 ms), so callbacks run on the shell’s task, never on another program’s stack. |
onCtrlEsc |
ctrlEscHandler |
shellOpenTaskManager. |
onF1 |
f1HelpHandler |
Opens the focused app’s helpFile/helpTopic (or the system help) in the help viewer through shellOpenHelpFile, reusing a running viewer that sets onNewArgs. |
onTitleChange |
titleChangeHandler |
Runs shellDesktopUpdate so Program Manager window lists refresh. |
3.7.2. shellRegisterDesktopUpdate
void shellRegisterDesktopUpdate(void (*updateFn)(void));
Register a callback for app state change notifications. Multiple callbacks are supported; registering the same callback again has no effect. Apps typically call this during appMain() to receive notifications. A callback may register or unregister callbacks (including itself) while notifications are being delivered. Each callback runs as the app that was current when it was registered (ctx->currentAppId), as a window’s callbacks do: what it allocates or creates is that app’s, and a crash in it ends that app.
3.7.3. shellUnregisterDesktopUpdate
void shellUnregisterDesktopUpdate(void (*updateFn)(void));
Remove a previously registered callback. Call this before app shutdown to avoid dangling function pointers.
3.7.4. shellRegisterIdle
void shellRegisterIdle(void (*fn)(void *ctx), void *ctx);
Register an idle handler invoked every idle frame by the shell main loop (and at least every 20 ms while frames keep painting), regardless of which app is foreground. Background pollers (serial and secLink) register here so their connections keep pumping while another app is in front. Registration is idempotent on the (fn, ctx) pair. The registering module MUST unregister before it is unloaded — app DXEs do this from their _appShutdown hook on a graceful exit. On a force kill (which does not run _appShutdown) the shell drops the app’s registrations itself. Each handler runs as the app that was current when it was registered (ctx->currentAppId; 0 for the shell’s own), as a window’s callbacks do: what it allocates or creates is that app’s, and a crash in it ends that app rather than counting as DVX’s own.
3.7.5. shellUnregisterIdle
void shellUnregisterIdle(void (*fn)(void *ctx), void *ctx);
Remove a previously registered idle handler. No-op if the (fn, ctx) pair is absent, so a double-unregister is harmless.
3.7.6. shellRegisterAppCleanup
typedef void (*ShellAppCleanupFnT)(int32_t appId);
void shellRegisterAppCleanup(ShellAppCleanupFnT fn);
void shellUnregisterAppCleanup(ShellAppCleanupFnT fn);
Register a function the shell calls with an app’s id whenever that app ends — normally, by End Task, or after a crash — once its windows and tasks are gone and before its module is unloaded, next to the shell’s own release of the app’s widget classes and hotkeys. A library uses it to release what the app left open with it: the networking library closes the app’s sockets this way. For library code that stays loaded; registering the same function again has no effect, and unregistering one that is not registered does nothing.
Closing a Program’s Handles When It Ends
A library that gives programs handles (ports, connections, links, transfers, databases) closes the ones a program leaves open when that program ends, however it ends, so a program that forgets one, is ended from Task Manager, or crashes leaks nothing and leaves no port or interrupt handler running. The handle belongs to the program that is running when it is opened: every program’s code runs as that program (ctx->currentAppId) — its window callbacks, its main loop, its shellAppTaskStart work, and any task it makes with tsCreate — and DVX itself is program 0, which never ends. Either way below, the release runs after the program’s windows and tasks are gone, so it must not call back into the program’s code (it may have crashed) and must not wait long.
-
The simplest: basHold(releaseFn, handle) (dvxBas.h, in the core library) as the open succeeds, and basHoldEnd(handle) first thing in the close. basHold records the running program and has the shell call releaseFn(handle) when that program ends before the close; basHoldEnd takes the hold back, so a close the program makes itself, or one from a BASIC handle table’s freeFn, never releases twice. It needs no link to the shell.
-
A library with its own table records the owner as it opens a handle (*dvxMemAppIdPtr, dvxMem.h, or ctx->currentAppId), registers one function with shellRegisterAppCleanup when it loads (its constructor runs as DVX itself) and unregisters it when it unloads, and that function closes every handle whose owner is the app that ended. The networking library does this for its sockets.
3.7.7. shellRegisterAppKill
void shellRegisterAppKill(ShellAppCleanupFnT fn);
void shellUnregisterAppKill(ShellAppCleanupFnT fn);
Register a function the shell calls with an app’s id when the app is ended by force (End Task, a screen saver that would not close, DVX exiting) while none of the app’s code is running and its windows are still there (unless its shutdownFn destroyed them) — after its tasks are killed and its shutdownFn has run, before the windows go and before the cleanup hooks. A library ends what it runs for the app the way the app’s own end would: the BASIC runtime (basrt) frees a standalone program’s VM, forms, screen, and module this way, closing its serial ports and its forms' windows, so End Task on a BASIC program leaks nothing. Not called for an app that faulted (its state cannot be trusted), nor for one whose kill had to wait until its code returned (End Task from inside the app’s own dialog: its windows went at once). Registration rules as for cleanup hooks.
3.7.8. shellAppTaskStart
int32_t shellAppTaskStart(AppContextT *ctx, const char *name, uint32_t stackSize, void (*fn)(void *arg), void *arg);
Run fn(arg) on a cooperative task of its own (stackSize bytes; 0 for the default) that belongs to the running program (ctx->currentAppId), for a long piece of a callback-only program’s work: the DVX BASIC IDE runs each program it starts this way. A callback-only program’s code runs inside the shell’s main loop, which only reaps programs that ended, carries out close and Exit requests and DOS program starts, and starts the screen saver between frames; work done in a callback holds all of that until it returns. On its own task the work leaves the main loop free. The program is the running one on the task (windows it makes are the program’s), it is not reaped while the task runs (even with all its windows closed), and ending it by force (End Task) ends the task. One at a time per program; a callback-only program’s appMain may start it. While it runs the program has a task of its own (Task Manager’s Type is Task, and shellAppGetPriority gives the task’s priority). Returns the task’s ID, or -1 when one runs already, no program is running (or starting), or no task can be made. A task the program makes with tsCreate is the program’s too (it runs as the program and is killed when the program ends), but it does not keep a callback-only program from being reaped when its last window closes.
3.7.9. shellDesktopUpdate
void shellDesktopUpdate(void);
Notify all registered desktop callbacks that app state has changed. Called internally by the shell after loading or reaping an app. Can also be called by apps that need to trigger a desktop refresh. Each call also adds one to the change counter (shellDesktopChangeCount).
3.7.10. shellDesktopChangeCount
int32_t shellDesktopChangeCount(void);
How many times shellDesktopUpdate has run (it wraps around). For a desktop that cannot take a callback — a BASIC program polls it from a Timer (ShellChangeCount) and refreshes its running-program count when the value differs from the one it saw last.
3.7.11. shellCtrlEscFn / shellOpenTaskManager
extern void (*shellCtrlEscFn)(AppContextT *ctx);
void shellOpenTaskManager(AppContextT *ctx);
shellCtrlEscFn is set by the taskmgr DXE’s constructor; NULL if the task manager is not loaded. shellOpenTaskManager calls it when it is set and does nothing otherwise; Ctrl+Esc, Program Manager’s Help > Task Manager, and BASIC’s ShellTaskManager all open Task Manager through it.
3.8. System Information
Thin wrapper around the platform layer’s hardware detection. Logs the system information at startup, and gathers it again for each display (the Program Manager’s System Information window, BASIC’s ShellSystemInfo$), so the free memory, the screen mode, and the drives are as they are then.
3.8.1. shellInfoInit
void shellInfoInit(AppContextT *ctx);
Gather all hardware information via the platform layer and log each line to DVX.LOG. Call once after dvxInit(): ctx’s screen is the one shellGetSystemInfo describes from then on.
3.8.2. shellGetSystemInfo
const char *shellGetSystemInfo(void);
The formatted system information text as it is now (platformGetSystemInfo), then a "=== Log ===" section: "Log file: " and the log’s full path (platformLogPath), or, while the log is kept in memory (DVX can write to no folder), a line saying so and the log’s latest lines (platformLogMemory), which can be read nowhere else. "" before shellInfoInit. Valid until the next call; the text is DVX’s memory (DVX_MEM_SYSTEM), whichever program asks.
3.9. Installed Programs
Finds the installed programs (every .app file under APPS, SHELL_PROG_DIR) and reads what they are called and what they look like, for launchers, file managers, and setup programs. A program’s display name and description are its "name" and "description" text resources (the capitalized file name when it has no name resource); its picture is its "icon32" resource.
| Constant | Value | Meaning |
|---|---|---|
SHELL_PROG_DIR |
"apps" |
Folder, relative to the DVX root, holding every program. |
SHELL_PROG_EXT |
".app" |
A program’s file extension. |
SHELL_PROG_DESC_MAX |
128 |
ShellProgramT.description capacity. |
SHELL_PROG_ICON |
32 |
Large icon edge in pixels. |
SHELL_PROG_ICON_SMALL |
16 |
Small icon edge in pixels. |
typedef struct {
char path[DVX_MAX_PATH];
char name[SHELL_APP_NAME_MAX];
char description[SHELL_PROG_DESC_MAX];
} ShellProgramT;
3.9.1. shellProgramScan
int32_t shellProgramScan(const char *dir, const char *skipPath, bool readInfo, ShellProgressFnT progress, void *progressCtx, ShellProgramT **outList);
Every program under dir (NULL for SHELL_PROG_DIR) and its subfolders, except skipPath (compared with platformPathSame; NULL for none), in the order found. With readInfo each entry is filled by shellProgramInfo; without it only path is set, which is fast (no program file is opened) and enough to notice programs being added or removed. progress, when not NULL, is called with progressCtx after each program (for example to keep the screen responsive). Returns the count; *outList is an array of that many entries, NULL when there are none. Free it with shellProgramListFree.
3.9.2. shellProgramInfo
void shellProgramInfo(const char *path, ShellProgramT *out);
Fill out with the program’s path, display name, and description. Always succeeds: without resources (or for a file that is not a program) the name is the file name without its extension, first letter capitalized, and the description is empty.
3.9.3. shellProgramIcon
uint8_t *shellProgramIcon(AppContextT *ctx, const char *path, int32_t edge, int32_t *outPitch);
A picture edge x edge pixels in display format, for drawing with rectCopy: a program’s icon32 resource, or any image file dvxLoadImage reads (BMP, PNG, JPEG, GIF). Other sizes are scaled (nearest pixel). Returns NULL when there is no picture. Free with dvxFreeImage.
3.9.4. shellItemIcon
uint8_t *shellItemIcon(AppContextT *ctx, const char *iconPath, const char *path, int32_t edge, int32_t *outPitch);
The icon a launcher shows for path (a program or a document), edge x edge pixels as shellProgramIcon gives them: the picture file iconPath when it is given (NULL or "" for none) and can be read; else path’s own picture — a program’s icon32, or path itself when it is a picture file; else, for a document, the icon of the program its file type opens in (shellAssocCommand). NULL when there is none; free with dvxFreeImage. Program Manager’s items (both sizes) and its Properties preview use it, so an item and its preview always show the same icon. (A BASIC program’s LOADPICTURE of a .app reads the program’s icon itself, with dvxResLoadIconData.)
3.9.5. shellItemIconFile
bool shellItemIconFile(AppContextT *ctx, const char *iconPath, const char *path, char *out, int32_t outSize);
The same rule as shellItemIcon (one implementation), naming the file the icon comes from in out: iconPath, path, or the program path’s file type opens in; false with "" when none gives a picture. dvxLoadImage of that file (BASIC LOADPICTURE) gives the icon. BASIC: ShellItemIcon$ in shell.bas.
3.10. Running Programs and Documents
One way for every program to start another (Program Manager’s items and Run..., the Task Manager’s Run..., File Manager, setup programs). A command line is a program, in quotes if it contains blanks, followed by its arguments; it is split with dvxNextArg, the same rule a program uses to read its own arguments. A document in place of a program opens in the program associated with its file type (see File Associations).
3.10.1. shellRunProgram
int32_t shellRunProgram(AppContextT *ctx, const char *program, const char *args, const char *folder);
Start program with args. A .app is loaded with shellLoadAppWithArgs, its arguments first passed through shellResolveArgs(folder, ...). A DOS program (shellIsDosProgram: .EXE, .COM, or .BAT, any case) is set to run with shellRunDos (folder is where it runs; looked for in folder first when relative). Anything else is a document: it is looked for in folder first (when relative), must exist, and is opened with shellAssocCommand’s program and arguments; when that program is a DOS program, the document goes to it by its full short name (it runs in its own folder) through shellRunDos. Problems are shown to the user in an error box (a missing document, a document type with no association; load errors come from shellLoadApp as usual). Returns the new application id, SHELL_RUN_DOS (0) for a DOS program set to run, or -1.
3.10.2. shellRunDos / shellRunDosRequest
void shellRunDos(const char *program, const char *args, const char *folder, bool pause);
void shellRunDosFor(int32_t appId, const char *program, const char *args, const char *folder, bool pause);
bool shellRunDosDone(int32_t appId, int32_t *rc);
void shellRunDosRequest(AppContextT *ctx, int32_t keepAppId);
bool shellIsDosProgram(const char *path);
Run a DOS program with DVX stepped aside (libdvx’s dvxRunDos, which takes the same program, args, folder, and pause). shellRunDos only records the request (a newer one replaces one still waiting): closing the other programs pumps the event loop, which is not safe from an event handler. The main loop calls shellRunDosRequest after shellRunExitRequest; keepAppId is the shell app, which stays. A program named with a folder must exist ("Cannot find X.", titled Run DOS Program); a bare name is looked for on the PATH by DOS. When programs other than the desktop are running, a question names them (by their program names, shellProgramInfo) and says each asks about unsaved work as it closes; No, or a program that keeps a window (shellCloseAllApps), cancels the run. A program that cannot be started is reported after DVX is back ("DVX could not run X." with the reason). The Task Manager is the shell’s own window and is not asked. Program Manager’s DOS items call shellRunDos with their "Wait for a key" setting (PmItemT.pause, PROGMAN.INI itemN.pause); shellRunProgram uses pause false.
shellRunDosFor is shellRunDos for a program that waits for the run to end (BASIC’s SHELL and ShellRunDosWait): appId is not asked to close, and shellRunDosDone(appId, &rc) turns true once the run is over, with rc the DOS program’s exit code, or -1 when it did not run (the other programs were kept, it was not found or could not start, or another request replaced it).
3.10.3. DVX.COM: DOS programs without DVX in memory
void shellRunHandOffInit(int argc, char *argv[], bool safeStart);
bool shellRunHandedOff(void);
bool shellReturnedFromDos(void);
DVX.COM, next to DVX.EXE, is how DVX is normally started (Setup’s AUTOEXEC.BAT line and its own start). It is a small real-mode program that runs DVX.EXE with DVX_SWITCH_NEXT ("/NEXT=", dvxPlat.h) naming where to leave a hand-over: TEMP when it is set, else DVX’s folder. When a run nothing waits for (shellRunDos) has closed the other programs, the shell writes DVX_NEXT_BATCH (DVXNEXT.BAT, made by libdvx’s dvxDosBatch: the folder, the program, and the pause) and DVX_NEXT_ARGS (DVXBACK.TXT: the switches to start again with) there and ends. DVX.COM, holding only a few kilobytes, runs the batch file through COMSPEC, then starts DVX.EXE again with DVX_SWITCH_BACK ("/BACK"), DVX’s own switches but DVX_SWITCH_RUN, and DVX_SWITCH_SAFE when the start before was a safe one. Without the batch file it ends with DVX’s exit code. A hand-over that cannot be written (a read-only disk, a line longer than DOS takes) falls back to running the program with DVX in memory, as does every run when DVX.EXE was started alone; a run a program waits for (shellRunDosFor) always does.
shellMain calls shellRunHandOffInit once video is up (safeStart: the start is a safe one). shellRunHandedOff is true once DVX is ending for a hand-over (no exit sound). shellReturnedFromDos is true in a start after one: the loader appends to DVX.LOG instead of starting it over, and the start-up sound, the notices, the Welcome window, Program Manager’s Startup group, and the safe-start offer to keep the video mode are skipped. BASIC’s ShellReturnedFromDos is the same.
SHELL_DOS_FILTER ("DOS programs (*.exe;*.com;*.bat)") is the file dialogs' filter for them (Run..., Program Manager’s Properties, Control Panel’s File Types). A Program Manager item for a DOS program with no icon file of its own shows SHELL_DOS_ICON (SYSTEM\DOSPROG.BMP, from config/DOSPROG.BMP).
3.10.4. shellRunCommand
int32_t shellRunCommand(AppContextT *ctx, const char *command);
shellSplitCommand, then shellRunProgram with no working folder. Returns the application id or -1 (also for an empty command).
3.10.5. shellRunDialog
bool shellRunDialog(AppContextT *ctx, const char *const *history, int32_t historyCount, char *outCommand, int32_t outSize);
The standard Run dialog: an Open box listing history (newest first, the first one preselected) with a Browse... button. Returns true with the trimmed, non-empty command in outCommand when the user chose OK; OK with an empty box does nothing. The caller runs the command (shellRunCommand) and keeps its own history. SHELL_RUN_CMD_MAX (512) is a suitable outCommand size.
3.10.6. shellSplitCommand
bool shellSplitCommand(const char *command, char *program, int32_t programSize, char *args, int32_t argsSize);
Split a command line into the program (quotes removed) and the rest, trimmed. False, with both outputs empty, when there is no program.
3.10.7. shellResolveArgs
void shellResolveArgs(const char *folder, const char *args, char *out, int32_t outSize);
Copy args to out with blanks normalized, replacing every relative argument that names an existing file inside folder by folder\name, so a program finds the files an item’s arguments name no matter where it runs. Quoted arguments keep their quotes. With an empty or NULL folder the arguments are only normalized. DVX programs share one current folder, so this is how a program item’s working folder takes effect.
3.10.8. shellMinimizeApp
void shellMinimizeApp(AppContextT *ctx, int32_t appId);
void shellMinimizeIdle(AppContextT *ctx);
Run Minimized. shellMinimizeApp minimizes every visible window of appId (an id from shellRunProgram) at once and again on each of the next SHELL_MINIMIZE_FRAMES (60) idle frames, because a program with a main loop opens its windows from its own task after it has started. Asking again for the same program starts its frames over; nothing happens for an id that is not running, and a program that ends is forgotten (an app-cleanup hook). shellMinimizeIdle is the per-frame step, called by the shell’s idle dispatch. Program Manager’s Run Minimized items and BASIC’s ShellMinimizeApp use it.
3.11. The Screen Saver
A screen saver is a program (.app, C or BASIC) in a SAVERS folder (DvxKindSaversE: SHARED\SAVERS, which DVX and add-ons fill, and the user’s SAVERS); Program Manager does not list it. After the wait with no key or mouse input (dvxIdleMs) the shell starts the chosen one with SHELL_SAVER_ARGS ("/S"). It takes the whole screen (dvxExclusiveBegin; BASIC SCREEN and FULLSCREEN ON) and draws until its window is closed; it needs no input handling of its own, since the input that wakes the screen goes to it (full-screen mode), never to the program underneath. Input SHELL_SAVER_GRACE_MS (1,000 ms) or more after it started asks each of its windows to close (dvxRequestWindowClose, as Alt+F4 does, with the reason WinCloseRequestE); one still running SHELL_SAVER_END_MS (3,000 ms) later is ended (shellForceKillApp). The log says "Shell: screen saver X started" and "... ended".
The saver does not start while a dialog box is open (ctx->modalWindow) or a program has the full screen (ctx->exclusive.owner: a game played with a joystick gives no key or mouse input). After a saver ends (or fails to start: missing, or not a program, logged and never shown in a message box) the next wait counts from then.
DVX.INI [desktop] saver is the saver’s name in SAVERS ("" or missing: none) and saverWait the minutes (SHELL_SAVER_WAIT_MIN to SHELL_SAVER_WAIT_MAX, 1 to 60; SHELL_SAVER_WAIT_DEFAULT, 10, when missing). The shell reads them at start; Control Panel’s Desktop page sets them live and stores them with OK.
void shellSaverSet(const char *name, int32_t minutes);
const char *shellSaverName(void);
int32_t shellSaverWait(void);
bool shellSaverStart(void);
bool shellSaverRunning(void);
void shellSaverStep(AppContextT *ctx);
void shellSaverFromPrefs(PrefsHandleT *h);
void shellSaverToPrefs(PrefsHandleT *h);
| Function | What it does |
|---|---|
shellSaverSet |
Choose the saver (a file in SAVERS is kept by its name there, platformKindNameOf; any other path as it is; "" or NULL: none) and the wait, clamped to the range; at once |
shellSaverName / Wait |
The settings in force |
shellSaverStart |
Start the saver now (Control Panel’s Test); only recorded, the next shellSaverStep starts it. False with none chosen or one running |
shellSaverRunning |
True while a saver runs |
shellSaverStep |
The main loop’s step (shell top level): starts the saver when due, ends a running one at input |
shellSaverFromPrefs |
Read [desktop] saver and saverWait (start, Control Panel’s Cancel) |
shellSaverToPrefs |
Write them (Control Panel’s OK and its Cancel snapshot) |
BASIC: SysScreenSaver$, SysScreenSaverWait, SysSetScreenSaver, SysScreenSaverStart, SysScreenSaverRunning, SysScreenSaverStore, SysScreenSaverLoad, and SysIdleSeconds (system.bas; see BASIC System Settings).
3.11.1. Writing a screen saver
A C saver is a main-loop program that opens a window, takes the full screen with dvxExclusiveBegin, and draws (dvxExclusivePresent8, paced with gameFrameWait) until the window’s onClose sets a flag; then it destroys the window and returns (src/savers/kpunch/starfld). A BASIC saver is a program with no form: SCREEN 13, FULLSCREEN ON, and a loop drawing with FRAMEWAIT (src/savers/kpunch/blank, marquee, mystify); closing its screen window ends it. Put the .app in SHARED\SAVERS (an add-on package’s kind saver) or the user’s SAVERS; the name Control Panel lists is the program’s (its "name" resource, a BASIC project’s Name).
3.12. File Associations
Which program opens each kind of document. One store serves every program, in two layers: the shipped list, SYSTEM\ASSOC.INI (SHELL_ASSOC_SHIPPED_PATH), and the user’s changes, ASSOC.INI in the user folder, both with the section [associations]. A type in the user’s file replaces the shipped one; an empty value there removes a shipped type. Each key is an extension without the dot, upper case; each value is a program path relative to the DVX root, optionally followed by ,arguments where %1 stands for the document:
[associations]
TXT = apps/kpunch/notepad/notepad.app
FRM = apps/kpunch/dvxbasic/dvxbasic.app,%1
Users change the types on the Control Panel’s File Types page, and a setup program registers its own types with shellAssocSet. Every change goes to the user’s file, so an upgrade’s new shipped types appear while the user’s choices stay. Both files are read through dvxPrefs and kept for lookups; a change is made in a fresh read of the user’s file (only that one type changes) and saved at once with the crash-safe rewrite, so a hand edit made while DVX runs stays, and the cached copy of the user’s file is dropped then, so the next call reads it as it is. Extension arguments may have a leading dot and any case.
3.12.1. Looking Up
bool shellAssocLookup(const char *extension, char *programPath, int32_t programPathSize);
int32_t shellAssocCount(void);
bool shellAssocGet(int32_t index, char *extension, int32_t extensionSize, char *programPath, int32_t programPathSize);
shellAssocLookup gives the stored value (program plus any ,arguments) for an extension; false when there is none, its value is empty, or the DVX program it names is not installed (an optional part of DVX left out, such as Setup or Software). shellAssocCount and shellAssocGet walk every association in file order (index 0 to count-1); the extension comes back as written in the file.
3.12.2. Opening a Document
bool shellAssocCommand(const char *documentPath, char *program, int32_t programSize, char *args, int32_t argsSize);
bool shellAssocOpenDocument(AppContextT *ctx, const char *documentPath);
shellAssocCommand builds the program and argument string that open a document: the value is split at the first comma, every %1 in the arguments becomes documentPath, and without arguments documentPath alone is passed. The path goes in double quotes when it contains a blank (dvxArgAppend), so dvxNextArg and COMMAND$(1) still return a long name such as C:\My Documents\Letter.txt whole; a template that already quotes the token ("%1") gets the path as it is. A program that opens documents takes the first argument of its DxeAppContextT.args (dvxNextArg) as the file to open when it starts; a BASIC program uses COMMAND$(1). shellAssocOpenDocument does that and starts the program; false when there is no association or the program does not start. With no association it shows nothing to the user (shellRunProgram does, for a document it cannot open); a program that does not start says why in a message box, as any start does (shellLoadAppWithArgs).
3.12.3. Changing
bool shellAssocSet(const char *extension, const char *programPath);
bool shellAssocRemove(const char *extension);
bool shellAssocNormalize(const char *extension, char *out);
shellAssocSet adds or replaces an association (programPath may carry ,arguments) and saves; false for a bad extension, an empty program, or a failed save. shellAssocRemove removes one and saves; false when it did not exist or the save failed. shellAssocNormalize writes the extension as the store keys it (SHELL_ASSOC_EXT_MAX bytes: no dot, upper case) and is false for an empty extension, one longer than eight characters, or anything but letters and digits.
3.13. BASIC Entry Points
Source: dvxshell/shellBas.c; BASIC declarations: src/include/basic/shell.bas (DECLARE LIBRARY "dvxshell").
The shell’s services for DVX BASIC programs — everything Program Manager does, so a shell app like it can be written in BASIC. Only BASIC-marshalable types: strings and LONG in, LONG or STRING out, True (-1) / False (0) for success. "This program" is the app whose code is running (ctx->currentAppId, which the shell keeps for every app’s task and window callback). A returned string stays valid until the next call of the same function. Program lists (1, 2, ...; 0 means none) and hotkeys belong to the program that made them and are released by an app-cleanup hook (shellRegisterAppCleanup) when it ends.
3.13.1. Starting programs and documents
int32_t ShellRun(const char *program, const char *args);
int32_t ShellRunProgram(const char *program, const char *args, const char *folder);
int32_t ShellRunCommand(const char *command);
void ShellRunDos(const char *program, const char *args, const char *folder, int32_t pause);
int32_t ShellRunDosWait(const char *program, const char *args, const char *folder, int32_t pause);
int32_t ShellReturnedFromDos(void);
const char *ShellRunDialog(const char *history);
void ShellMinimizeApp(int32_t appId);
int32_t ShellOpenDocument(const char *path);
ShellRunProgram is shellRunProgram (a document opens through its association; file names in args, and a relative document, are looked for in folder; "" for none), returning the new app id, -1 (shell.bas SHELL_RUN_DOS) for a DOS program set to run, or 0. ShellRun is ShellRunProgram without a folder, True when it started or a DOS program will run; the two are one launch path. ShellRunCommand is shellRunCommand (id, -1, or 0). ShellRunDos is shellRunDos (pause True or False): the DOS program runs once the calling procedure has returned and the programs besides the desktop, the caller too, have closed. ShellRunDosWait is shellRunDosFor for the calling program, pumping events (dvxWaitPump) until shellRunDosDone; it returns the exit code, or -1 when the program did not run or the caller is ending. ShellReturnedFromDos is shellReturnedFromDos. ShellRunDialog splits history at line ends (CHR$(10), a CR before it is dropped, empty lines skipped) into the list shellRunDialog shows, and returns the command chosen or "" when canceled. ShellMinimizeApp is shellMinimizeApp. ShellOpenDocument is shellAssocOpenDocument (it shows nothing when there is no association; ShellRunProgram does).
3.13.2. Installed programs
int32_t ShellProgramScan(const char *folder, const char *skipPath);
int32_t ShellProgramCount(int32_t list);
const char *ShellProgramPath(int32_t list, int32_t index);
void ShellProgramFree(int32_t list);
const char *ShellProgramName(const char *path);
const char *ShellProgramDescription(const char *path);
int32_t ShellIsProgram(const char *path);
int32_t ShellIsDosProgram(const char *path);
ShellProgramScan is shellProgramScan of folder ("" for SHELL_PROG_DIR) without skipPath ("" for none), paths only (readInfo false), so it never opens a program; it returns a list handle, 0 when nothing was found. ShellProgramCount and ShellProgramPath read it (0 / "" for a bad list or index); ShellProgramFree frees it. ShellProgramName and ShellProgramDescription are shellProgramInfo’s name and description, read one program at a time so a long list can be filled with DoEvents in between (the C progress callback). ShellIsProgram is shellIsProgram, ShellIsDosProgram shellIsDosProgram.
3.13.3. File types
const char *ShellAssocProgram(const char *extension);
const char *ShellAssocCommand(const char *document);
int32_t ShellAssocCount(void);
const char *ShellAssocExt(int32_t index);
const char *ShellAssocValue(int32_t index);
int32_t ShellAssocSet(const char *extension, const char *value);
int32_t ShellAssocRemove(const char *extension);
const char *ShellAssocNormalize(const char *extension);
ShellAssocProgram is shellAssocLookup: the stored value, the program followed by ",args" when there is a template. ShellAssocCommand is the program part of shellAssocCommand for a document. ShellAssocCount, ShellAssocExt, and ShellAssocValue enumerate shellAssocGet (0-based; "" past the end). ShellAssocSet, ShellAssocRemove, and ShellAssocNormalize are shellAssocSet, shellAssocRemove, and shellAssocNormalize ("" when the extension cannot be one). Every change is saved at once.
3.13.4. Running programs and DVX
int32_t ShellRunningCount(void);
int32_t ShellChangeCount(void);
void ShellTaskManager(void);
const char *ShellSystemInfo(void);
void ShellExitDvx(void);
ShellRunningCount is shellRunningAppCount. ShellChangeCount is shellDesktopChangeCount: a BASIC desktop polls it from a Timer in place of shellRegisterDesktopUpdate’s callback. ShellTaskManager is shellOpenTaskManager, ShellSystemInfo is shellGetSystemInfo (gathered at each call, with the log section; "" before shellInfoInit), and ShellExitDvx is shellRequestExit (every app is asked to close, then DVX quits; a desktop asks the user first).
int32_t ShellRunningId(int32_t index);
const char *ShellRunningName(int32_t appId);
const char *ShellRunningPath(int32_t appId);
int32_t ShellRunningFind(const char *program);
int32_t ShellRunningActivate(int32_t appId);
int32_t ShellRunningClose(int32_t appId);
int32_t ShellRunningKill(int32_t appId);
int32_t ShellAppIsHung(int32_t appId);
int32_t ShellAppMemory(int32_t appId);
int32_t ShellMemoryRetained(void);
The Task Manager’s operations, one routine each with it. ShellRunningId is shellRunningAppId. ShellRunningName and ShellRunningPath are the ShellAppT name and path of an app in AppStateRunningE ("" otherwise; the same state every call below requires). ShellRunningFind is shellAppFindByPath (platformPathSame rules), 0 when that app is not running. ShellRunningActivate is shellActivateApp. ShellRunningClose is shellRequestAppClose: the app is asked at the main loop’s top level, after the BASIC code has returned; True when the request was recorded. ShellRunningKill is shellEndTask (End Task: shellForceKillApp and shellDesktopUpdate, so no shutdownFn, callbacks purged, the unload deferred while the app’s code is on a stack; the desktop asks Exit DVX’s question first); the running program itself is refused (BASIC’s END ends it). ShellAppIsHung is dvxAppIsHung and ShellAppMemory dvxMemGetAppUsage (clamped to INT32_MAX; 0 for an app that is not running). ShellMemoryRetained is dvxMemGetRetained (clamped the same way): what ended apps left allocated.
3.13.5. Command lines and priority
const char *ShellCommandProgram(const char *command);
const char *ShellCommandArgs(const char *command);
int32_t ShellArgCount(const char *command);
const char *ShellArg(const char *command, int32_t index);
const char *ShellArgQuote(const char *arg);
int32_t ShellAppId(void);
int32_t ShellPriority(void);
int32_t ShellSetPriority(int32_t priority);
ShellCommandProgram and ShellCommandArgs are the two parts of shellSplitCommand (what shellRunCommand runs). ShellArgCount and ShellArg walk a command line with dvxNextArg — the tokenizer shellSplitCommand and COMMAND$(n) use — counting the program as argument 0; ShellArg drops the quotes and gives "" past the last. ShellArgQuote is the other direction (dvxArgAppend): arg as one word of a command line, in double quotes when it holds blanks, "" when it is too long for one (SHELL_ARGS_MAX). ShellAppId is ctx->currentAppId. ShellPriority and ShellSetPriority are tsGetPriority / tsSetPriority on the running program’s mainTaskId (TS_PRIORITY_LOW .. TS_PRIORITY_HIGH, shell.bas SHELL_PRIORITY_*); -1 / False for a program without a task of its own (every BASIC program has one) or a priority out of range.
3.13.6. Hotkeys
int32_t HotkeyAdd(const char *keyText);
const char *HotkeyNames(void);
int32_t HotkeyNext(void);
void HotkeyRemove(int32_t id);
const char *HotkeySystemUse(const char *keyText);
const char *HotkeyText(const char *keyText);
HotkeyAdd parses keyText with dvxAccelParse and registers it with dvxRegisterHotkey for the running program; it returns an id of its own (> 0), or 0 when keyText is not a key or dvxRegisterHotkey refuses it (it needs Ctrl or Alt unless it is a function or navigation key, a key DVX keeps for itself (dvxSystemKeyUse) is refused, and so is a key already registered). A BASIC program cannot be called back, so the hotkey’s callback queues the id for its program (up to 16 presses not yet collected); HotkeyNext returns and removes the oldest one, 0 when there is none. HotkeyRemove drops one of the running program’s hotkeys (other ids are ignored). HotkeySystemUse is dvxAccelParse followed by dvxSystemKeyUse ("" for a key DVX leaves to the programs, or text that is not a key). HotkeyText is dvxAccelParse followed by dvxAccelFormat ("" when keyText is not a key): the spelling menus show. HotkeyNames is dvxAccelKeyNames: the named keys, as an English list for a message. dvxUnregisterAppHotkeys removes a program’s hotkeys when it ends; the app-cleanup hook drops their records and queued presses.
3.13.7. This program and DVX settings
const char *ShellAppPath(void);
int32_t ShellInstanceCount(void);
void ShellLog(const char *text);
int32_t ShellSetDesktop(const char *program);
int32_t ShellSetWelcome(const char *program);
ShellAppPath is the running program’s .app path as started ("" when unknown). A BASIC program’s user folder is App.User (the folder a C program’s userDir names; every copy of a program gets the same one). ShellInstanceCount counts the running apps with the same path, this one included (a second copy of a multiInstance program loads from a temporary copy but keeps the original path). ShellLog writes one line with dvxLog. ShellSetDesktop and ShellSetWelcome set, or with "" remove, DVX.INI [shell] desktop (the shell app; SHELL_DESKTOP_APP when missing) and [shell] welcome (the program started after the desktop); both share one writer and return False (logged) when DVX.INI cannot be saved.
3.13.8. Programs folder, item icons, program groups
const char *ShellProgramsFolder(void);
const char *ShellItemIcon(const char *iconPath, const char *path);
ShellProgramsFolder is SHELL_PROG_DIR (where ShellProgramScan("") looks and a Browse for a program starts). ShellItemIcon is shellItemIconFile ("" for none). The program-group bindings (ShellGroups*, ShellGroup*, ShellItem*) are in pmModelBas.c; see Program Groups.
3.13.9. A Shell App in BASIC
A BASIC program can be the shell app ([shell] desktop, ShellSetDesktop): the shell exits DVX when it ends, so it needs no code for that; its Exit command confirms and calls ShellExitDvx. Its groups use the shell’s program-group model (Program Groups: the same PROGMAN.INI format, rules, and limits as Program Manager) through shell.bas, in its App.User folder. An icon grid is drawn on a PictureBox with PaintPicture and pictures from LOADPICTURE of ShellItemIcon$ (a .app gives its icon), with MouseDown/MouseUp for selecting and dragging and KeyDown for the keyboard. The test fixture src/test/dos/fixtures/parpm does all of this.
3.14. Program Groups
Program Manager’s groups, items, and PROGMAN.INI, as plain data with no windows, part of the shell so the C Program Manager and a shell app written in BASIC share one model (the pm prefix names it). groups[PM_INSTALLED_IDX] is the automatic Installed Programs group (pmInstalledScan: every program under SHELL_PROG_DIR, sorted by name, never saved; pmInstalledChanged tells cheaply whether a program was added or removed); the others are the user’s, saved by pmModelSave with a crash-safe rewrite in this layout:
[options] minimizeOnRun, restoreAlone, autoArrange, view, group
[groups] count
[groupN] name, count, itemM.name, itemM.program, itemM.args,
itemM.folder, itemM.icon, itemM.key, itemM.minimized,
itemM.col, itemM.row (N and M count from 1)
[run] historyN (newest first)
| Function | Description |
|---|---|
pmModelInit / pmModelLoad / pmModelSave / pmModelFree |
An empty model; load a file (one never saved gives Main and Startup; damaged entries are skipped, and the groups, or a group’s items, end at the first one the file does not have, whatever its count says; an item’s shortcut key that is no longer allowed is dropped and named, with why, in keyNotice for the user); save; free. |
pmGroupAdd / pmGroupDelete / pmGroupFind / pmGroupMove / pmGroupRename / pmGroupNameValid |
Groups (names trimmed, unique in any case, as many as memory holds; the automatic group stays first and cannot change). |
pmItemAdd / pmItemCopy / pmItemMove / pmItemDelete / pmItemReorder / pmItemPlace |
Items (a name and a program each, as many per group as memory holds; a copy has no shortcut key). |
pmItemGetField / pmItemSetField |
An item’s field by its PROGMAN.INI name (PM_FIELD_*); a key must pass pmHotkeyParse, a name or program cannot be emptied. |
pmOptionGet / pmOptionSet |
An [options] value by name (flags, view, group). |
pmArrangeGroup / pmPlaceUnplaced / pmCellItem |
Grid cells for an icon view. |
pmItemMatches / pmContainsNoCase |
Program Manager’s search. |
pmHistoryAdd |
The Run history (PM_HISTORY_MAX, newest first). |
pmHotkeyParse / pmHotkeyWhyNot |
An item shortcut: dvxAccelParse, Ctrl plus Alt or Shift so it never takes a key a program uses itself, and not a key DVX keeps for itself (dvxSystemKeyUse); "" is no shortcut. pmHotkeyWhyNot is the message for a refused one (PM_KEY_ERROR_MAX). |
pmInstalledScan / pmInstalledChanged / pmInstalledReplace |
The automatic group. |
BASIC (shell.bas, DECLARE LIBRARY "dvxshell"): ShellGroupsLoad / Save / Free / Scan / Changed / Full / Get / Set / History$ / HistoryAdd / KeyNotice$ (the model’s keyNotice: the shortcut keys pmModelLoad dropped), ShellGroupCount / Name$ / Find / Add / Delete / Rename / NameValid / Arrange / PlaceUnplaced / CellItem, ShellItemCount / Add / Get$ / Set / Delete / Copy / Move / Reorder / Place / Matches / KeyValid / KeyError$. A groups file is a handle of the program that opened it, freed when it ends (shellRegisterAppCleanup).
3.15. BASIC System Settings
Source: dvxshell/shellSysBas.c; BASIC declarations: src/include/basic/system.bas (DECLARE LIBRARY "dvxshell"); prototypes in shellApp.h.
What Control Panel changes, for DVX BASIC programs: the video mode, the system colors and themes, the wallpaper, the screen saver, text smoothing, and the mouse, each applied at once to shellContext(). Only BASIC-marshalable types; True (-1) / False (0); colors are BASIC RGB() values (&HBBGGRR, converted with wgtBasicColor); lists are 0-based. Arguments named prefs are prefs.bas handles, resolved with prefsBasHandle (dvxPrefs.h); 0 or a closed handle makes a Store or Load do nothing (a Load returns False).
int32_t SysVideoModeCount(void);
int32_t SysVideoModeWidth(int32_t index);
int32_t SysVideoModeHeight(int32_t index);
int32_t SysVideoModeBpp(int32_t index);
int32_t SysSetVideoMode(int32_t width, int32_t height, int32_t bpp);
int32_t SysColorCount(void);
const char *SysColorLabel(int32_t id);
const char *SysColorName(int32_t id);
int32_t SysColorId(const char *name);
int32_t SysGetColor(int32_t id);
void SysSetColor(int32_t id, int32_t rgb);
void SysResetColors(void);
int32_t SysLoadTheme(const char *path);
int32_t SysSaveTheme(const char *path);
void SysColorsStore(int32_t prefs);
int32_t SysColorsLoad(int32_t prefs);
int32_t SysSetWallpaper(const char *path);
const char *SysWallpaper(void);
void SysSetWallpaperMode(int32_t mode);
int32_t SysWallpaperMode(void);
void SysWallpaperStore(int32_t prefs);
int32_t SysWallpaperLoad(int32_t prefs);
const char *SysScreenSaver(void);
int32_t SysScreenSaverWait(void);
void SysSetScreenSaver(const char *fileName, int32_t minutes);
int32_t SysScreenSaverStart(void);
int32_t SysScreenSaverRunning(void);
void SysScreenSaverStore(int32_t prefs);
void SysScreenSaverLoad(int32_t prefs);
int32_t SysIdleSeconds(void);
void SysSetTextSmoothing(int32_t on);
int32_t SysTextSmoothing(void);
void SysFontsStore(int32_t prefs);
void SysFontsLoad(int32_t prefs);
void SysSetMouse(int32_t wheelDir, int32_t dblClickMs, int32_t accel, int32_t mickeys, int32_t wheelStep);
int32_t SysMouseWheelDir(void);
int32_t SysMouseDoubleClick(void);
int32_t SysMouseAccel(void);
int32_t SysMouseMickeys(void);
int32_t SysMouseWheelStep(void);
void SysMouseStore(int32_t prefs);
void SysMouseLoad(int32_t prefs);
int32_t SysFontWidth(void);
int32_t SysFontHeight(void);
int32_t SysFontFirstChar(void);
int32_t SysFontCharCount(void);
int32_t SysFontGlyphRow(int32_t code, int32_t row);
int32_t SysMouseX(void);
int32_t SysMouseY(void);
int32_t SysMouseButtons(void);
void SysSetMousePos(int32_t x, int32_t y);
int32_t SysShiftState(void);
int32_t SysSendKey(int32_t keyCode, int32_t shift);
int32_t SysScreenshot(const char *path);
const char *SysPicturePatterns(void);
int32_t SysMemoryTotalKb(void);
int32_t SysMemoryFreeKb(void);
int32_t SysLibraryLoaded(const char *name);
| Function | Calls |
|---|---|
SysVideoMode* |
dvxGetVideoModes (0 out of range) |
SysSetVideoMode |
dvxChangeVideoMode; False on -1 (also while a program is in exclusive full-screen mode) |
SysColorLabel / SysColorName |
dvxColorLabel / dvxColorName ("" for an id outside 0 .. ColorCountE - 1) |
SysColorId |
the id whose dvxColorName matches, any case; -1 for none |
SysGetColor / SysSetColor |
dvxGetColor / dvxSetColor (an unknown id: 0 / nothing) |
SysResetColors |
dvxResetColorScheme |
SysLoadTheme / SysSaveTheme |
dvxLoadTheme / dvxSaveTheme |
SysColorsStore / Load |
dvxColorsToPrefs / dvxColorsFromPrefs (Load: True when the handle had a [colors] key) |
SysSetWallpaper |
dvxSetWallpaper ("" clears) |
SysSetWallpaperMode |
dvxSetWallpaperMode with the value of prefsWallpaperChoices[mode]; other modes are ignored |
SysWallpaper / Mode |
ctx->wallpaperPath; the prefsWallpaperChoices index of ctx->wallpaperMode |
SysWallpaperStore / Load |
dvxWallpaperToPrefs / dvxWallpaperFromPrefs (Load: False when the image could not be loaded) |
SysScreenSaver / Wait |
shellSaverName / shellSaverWait |
SysSetScreenSaver |
shellSaverSet |
SysScreenSaverStart |
shellSaverStart (True when it will start) |
SysScreenSaverRunning |
shellSaverRunning |
SysScreenSaverStore / Load |
shellSaverToPrefs / shellSaverFromPrefs |
SysIdleSeconds |
dvxIdleMs / 1000 |
SysSetTextSmoothing |
dvxSetFontSmoothing (nonzero is on) |
SysTextSmoothing |
ctx->fontSmoothing (the setting; text is smoothed only above 8 bits per pixel) |
SysFontsStore / Load |
dvxFontsToPrefs / dvxFontsFromPrefs |
SysSetMouse |
dvxSetMouseConfig |
SysMouse* |
ctx->wheelDirection, dblClickMs, mouseAccel, mouseMickeys, wheelStep |
SysMouseStore / Load |
dvxMouseToPrefs / dvxMouseFromPrefs |
SysFont* |
dvxGetFont: charWidth, charHeight, firstChar, numChars; SysFontGlyphRow is glyphData[(code - firstChar) * charHeight + row] (0 outside the font) |
SysMouseX / Y / Buttons |
ctx->mouseX, mouseY, mouseButtons (MOUSE_LEFT / RIGHT / MIDDLE = vbLeftButton ...) |
SysSetMousePos |
platformMouseWarp, clamped to the screen; the next poll reports the move like the user’s |
SysShiftState |
basShiftFromMod(ctx->keyModifiers): Visual Basic’s vbShiftMask / vbCtrlMask / vbAltMask bits (1 / 2 / 4), not KEY_MOD_* |
SysSendKey |
queues (up to 64) keyCode + shift (BASIC’s bits, basModFromShift) as the BIOS stores the keystroke (platformBiosScanCode for combinations with codes of their own, KEY_EXT_FLAG keys by scan code, Ctrl+letter as its control character); a shell idle handler (shellRegisterIdle) injects one per idle frame with platformInjectKey, so each is read with its own modifiers, and releases them (platformInjectModifiers(0)) after the last |
SysScreenshot |
dvxScreenshot (BMP for .bmp, else PNG) |
SysPicturePatterns |
DVX_IMAGE_PATTERNS: the picture formats DVX reads, as file name patterns for a file dialog’s filter or FileOpsList |
SysMemoryTotalKb / FreeKb |
platformGetMemoryInfo; -1 when unknown |
SysLibraryLoaded |
dvxLibraryLoaded (the module’s ABI stamp, by its base name in any case) |
There is no binding for platformInjectMouse: on DOS it replaces the real mouse until the next call and has no way back to it, so a synthesized click would leave the pointer stuck. A program moves the pointer with SysSetMousePos and "clicks" a control by calling its event procedure or setting its value.
system.bas also holds MOUSE_WHEEL_STEP_MIN / MAX / DEFAULT, MOUSE_DBLCLICK_DEFAULT_MS, and MOUSE_SPEED_DEFAULT, and SYS_VIDEO_DEFAULT_WIDTH / HEIGHT / BPP (DVX_DEFAULT_VIDEO_W / H / BPP, the mode prefsGetVideoMode and safe mode fall back to), as CONSTs; the basdev test suite (caseIncludeConsts) checks each against dvxTypes.h.
The Store / Load routines are the ones the shell uses at start (dvxMouseFromPrefs, dvxColorsFromPrefs, dvxWallpaperFromPrefs on DVX.INI) and Control Panel uses for OK and for its Cancel snapshot (an in-memory prefsCreate handle), so the INI keys are written in one place (dvxApp.c).
3.16. libtasks — Cooperative Task Switching
Credit-based cooperative (non-preemptive) multitasking library for DOS protected mode (DJGPP/DPMI). Each task receives (priority + 1) credits per scheduling round. Tasks run round-robin, consuming one credit per turn. When all credits are exhausted, every ready task is refilled. Higher-priority tasks run proportionally more often but never starve lower ones.
Header: tasks/taskSwch.h
Loaded as: bin/libs/kpunch/libtasks/libtasks.lib
3.16.1. Why Cooperative
DOS is single-threaded with no kernel scheduler. DPMI provides no preemption primitives. The DVX GUI event model is inherently single-threaded: one compositor, one input queue, one window stack. Cooperative switching lets each task yield at safe points, avoiding synchronization primitives entirely.
3.16.2. Scheduling Semantics
Task storage is a stb_ds dynamic array. Terminated slots are recycled by tsCreate so the array does not grow unboundedly. The scheduler performs a linear scan for the next Ready task whose credit count is positive; when no task has credits left, every Ready task is refilled with (priority + 1) credits and the scan restarts.
A task’s share of the turns is its credits divided by the credits of every ready task. For example, with the main task (TS_PRIORITY_NORMAL, as tsInit makes it) and one task of each priority running, a round has 1 + 6 + 6 + 11 = 24 credits:
| Priority | Credits per round | Share in that example |
|---|---|---|
TS_PRIORITY_LOW |
1 |
~4% (1 of 24) |
TS_PRIORITY_NORMAL |
6 |
~25% (6 of 24), the main task too |
TS_PRIORITY_HIGH |
11 |
~46% (11 of 24) |
Actual share depends on the mix of priorities currently running. What the algorithm guarantees is that no ready task ever goes unscheduled — even a priority-0 task always earns at least one turn per round.
Stack Allocation
Task 0 uses the caller’s stack (no separate allocation). Every other task gets a heap-allocated stack of the size passed to tsCreate (or TS_DEFAULT_STACK_SIZE if 0 is passed; sizes below TS_MIN_STACK_SIZE are raised to it). Stacks are freed at task termination: at once by tsKill, or on the next scheduler entry after tsExit.
3.16.3. Error Codes
| Constant | Value | Description |
|---|---|---|
TS_OK |
0 |
Success |
TS_ERR_INIT |
-1 |
Task system not initialized |
TS_ERR_PARAM |
-2 |
Invalid parameter (bad task ID, priority, etc.) |
TS_ERR_NOMEM |
-4 |
Memory allocation failed |
TS_ERR_STATE |
-5 |
Invalid state transition |
3.16.4. Constants
| Constant | Value | Description |
|---|---|---|
TS_DEFAULT_STACK_SIZE |
32768 |
Default stack size per task (32 KB) |
TS_MAIN_TASK_ID |
0 |
The main task’s ID (tsInit’s caller) |
TS_MIN_STACK_SIZE |
4096 |
Smallest stack tsCreate allocates (4 KB) |
TS_NAME_MAX |
32 |
Maximum task name length including NUL |
TS_PRIORITY_LOW |
0 |
Low priority (1 credit per round) |
TS_PRIORITY_NORMAL |
5 |
Normal priority (6 credits per round) |
TS_PRIORITY_HIGH |
10 |
High priority (11 credits per round) |
3.16.5. Types
TaskStateE
Task scheduling state. Only Ready tasks participate in scheduling.
| Value | Description |
|---|---|
TaskStateReady |
Eligible for scheduling |
TaskStateRunning |
Currently executing (cosmetic; marks active task) |
TaskStatePaused |
Skipped by scheduler until explicitly resumed |
TaskStateTerminated |
Slot available for reuse |
3.16.6. tsInit
int32_t tsInit(void);
Initialize the task system. The calling context becomes task 0 (the main task). Task 0 is special: it cannot be killed or paused, and tsRecoverToMain() always returns control here. No separate stack is allocated for task 0; it uses the process stack directly.
Returns: TS_OK on success, TS_ERR_STATE if already initialized.
3.16.7. tsShutdown
void tsShutdown(void);
Shut down the task system and free all task stacks and internal storage. Safe to call even if tsInit() was never called.
3.16.8. tsCreate
int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t stackSize, int32_t priority);
Create a new task. Terminated task slots are recycled to avoid unbounded array growth. The new task starts with its creator’s context value as it is at the call (the current hook of tsSetContextHooks; 0 without one), which is also its owner for good (tsGetOwner). In DVX that value is the running program (ctx->currentAppId): a task a program makes runs as that program — what it allocates and the windows it opens are the program’s — and the shell kills it when the program ends, however it ends. A task does not keep a callback-only program from ending when its last window closes; shellAppTaskStart (shellApp.h) starts the one task that does.
| Parameter | Description |
|---|---|
name |
Task name (truncated to TS_NAME_MAX - 1 characters) |
entry |
Task entry point function |
arg |
Opaque argument passed to entry |
stackSize |
Stack size in bytes (pass 0 for TS_DEFAULT_STACK_SIZE; raised to TS_MIN_STACK_SIZE if smaller) |
priority |
Scheduling priority (TS_PRIORITY_LOW..TS_PRIORITY_HIGH, i.e. 0..10) |
Returns: Task ID (>= 0) on success, or a negative error code (TS_ERR_INIT if not initialized, TS_ERR_PARAM if entry is NULL or priority is out of range, TS_ERR_NOMEM if stack allocation failed).
3.16.9. tsYield
void tsYield(void);
Yield CPU to the next eligible ready task using credit-based round-robin. This is the sole mechanism for task switching. Every task must call this (or a GUI function that calls it) periodically, or it will monopolize the CPU.
3.16.10. tsPause
int32_t tsPause(uint32_t taskId);
Pause a task, removing it from scheduling. Cannot pause the main task (ID 0). If a task pauses itself, an implicit yield occurs.
| Parameter | Description |
|---|---|
taskId |
ID of the task to pause |
Returns: TS_OK on success, TS_ERR_INIT if not initialized, TS_ERR_PARAM on invalid ID, or TS_ERR_STATE if the task is the main task or not in a pausable state (not Running or Ready).
3.16.11. tsResume
int32_t tsResume(uint32_t taskId);
Resume a paused task. Credits are refilled so the task gets a fair share of CPU time immediately rather than waiting for the next scheduling round.
| Parameter | Description |
|---|---|
taskId |
ID of the task to resume |
Returns: TS_OK on success, TS_ERR_INIT if not initialized, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not paused.
3.16.12. tsSetPriority
int32_t tsSetPriority(uint32_t taskId, int32_t priority);
Set a task’s scheduling priority. Also refills credits so the change takes effect immediately.
| Parameter | Description |
|---|---|
taskId |
ID of the task to modify |
priority |
New priority level (TS_PRIORITY_LOW..TS_PRIORITY_HIGH, i.e. 0..10) |
Returns: TS_OK on success, TS_ERR_INIT if not initialized, TS_ERR_PARAM on invalid ID or out-of-range priority, or TS_ERR_STATE if the task is terminated.
3.16.13. tsGetPriority
int32_t tsGetPriority(uint32_t taskId);
Get a task’s current scheduling priority.
| Parameter | Description |
|---|---|
taskId |
ID of the task to query |
Returns: Priority value (0..10) on success, TS_ERR_INIT if not initialized, TS_ERR_PARAM on invalid ID.
3.16.14. tsGetState
TaskStateE tsGetState(uint32_t taskId);
Get a task’s current scheduling state.
| Parameter | Description |
|---|---|
taskId |
ID of the task to query |
Returns: TaskStateE value. Returns TaskStateTerminated for invalid IDs.
3.16.15. tsCurrentId
uint32_t tsCurrentId(void);
Get the ID of the currently executing task. Always valid while the task system is initialized.
Returns: Current task ID.
3.16.16. tsGetName
const char *tsGetName(uint32_t taskId);
Get a task’s name string.
| Parameter | Description |
|---|---|
taskId |
ID of the task to query |
Returns: Pointer to the task’s name, or NULL on invalid ID. The pointer remains valid until the task slot is reused.
3.16.17. tsGetOwner
int32_t tsGetOwner(uint32_t taskId);
Get a task’s owner: the context value its creator had when it called tsCreate (in DVX the program that made it, its appId; 0 for DVX itself). The main task’s is 0.
Returns: The owner, TS_ERR_INIT if not initialized, or TS_ERR_PARAM for an invalid ID or a free slot.
3.16.18. tsSlotCount
uint32_t tsSlotCount(void);
Every task ID is below this (TS_MAIN_TASK_ID, 0, through tsSlotCount() - 1), so a caller can walk the tasks; a free ID’s state is TaskStateTerminated. 0 before tsInit.
3.16.19. tsSetContextHooks
typedef int32_t (*TsCtxSaveFnT)(void);
typedef void (*TsCtxRestoreFnT)(int32_t value);
typedef int32_t (*TsCtxCurrentFnT)(void);
void tsSetContextHooks(TsCtxSaveFnT save, TsCtxRestoreFnT restore, TsCtxCurrentFnT current);
Make one value of the host’s behave as each task’s own. On every switch the save hook’s result is stored for the outgoing task and the restore hook is given the incoming task’s stored value; tsCreate reads the current hook (it has no side effects) for the new task’s first value and owner. Pass NULLs to unregister. The DVX shell keeps ctx->currentAppId per task this way, so allocations and windows are charged to the right program, and knows which program each task belongs to. A program never calls it.
3.16.20. tsExit
void tsExit(void);
Terminate the calling task. Must not be called from the main task (ID 0). The slot is marked for reuse immediately; the stack, which is still in use until the switch, is freed on the next entry into the scheduler. This function never returns; it performs an internal context switch to the next ready task.
3.16.21. tsKill
int32_t tsKill(uint32_t taskId);
Forcibly terminate another task. Cannot kill the main task (ID 0) or the currently running task (use tsExit() for self-termination). Safe because cooperative scheduling guarantees the target is suspended at a yield point.
| Parameter | Description |
|---|---|
taskId |
ID of the task to terminate |
Returns: TS_OK on success, TS_ERR_INIT if not initialized, TS_ERR_PARAM on invalid ID, or TS_ERR_STATE on illegal target (main task, self, or already terminated).
3.16.22. tsRecoverToMain
void tsRecoverToMain(void);
Crash recovery: force the scheduler back to the main task (ID 0). Call after longjmp from a signal handler that fired in a non-main task. The crashed task is NOT cleaned up by this call; call tsKill() afterward to free its resources. This exists because longjmp unwinds the crashed task’s stack but the scheduler state still points to it.
3.17. Task Manager
System-level task manager for DVX. Displays all running applications with a six-column ListView (Name, Title, File, Type, Memory, Status) and exposes Switch To, End Task, and Run... operations. Always accessible via Ctrl+Esc regardless of which application is focused. Persists independently of the shell app (Program Manager).
Header: shell/shellTaskMgr.h
Loaded as: bin/libs/kpunch/taskmgr/taskmgr.lib
3.17.1. Integration
The task manager is a shell-level library, not a regular DXE app. At DXE load time a GCC constructor function registers the Task Manager with the shell by setting the shellCtrlEscFn function pointer (declared extern in shell/shellApp.h). The shell invokes shellCtrlEscFn on every Ctrl+Esc keystroke; if taskmgr.lib is not loaded the pointer stays NULL and Ctrl+Esc does nothing.
The Task Manager owns its window on behalf of the shell itself (appId = 0), not any running app, which is why it survives when the shell app terminates. It registers shellTaskMgrRefresh with shellRegisterDesktopUpdate so the list refreshes live as apps load, reap, or crash.
3.17.2. Integration with libtasks
The Task Manager reads from the shell’s app slot table (shellGetApp, shellAppSlotCount) rather than from the libtasks scheduler directly; the list and the "Applications: N" status count both show the running apps. End Task calls shellEndTask, whose shellForceKillApp first kills every task of the app (tsKill): a main-loop app’s own, the task shellAppTaskStart started for it, and any it made with tsCreate. Then, unless the app faulted or is not responding, its appShutdown runs, as at a normal end, and its windows go. If the app is still inside one of its own dialogs, the unload is finished once that dialog’s code has returned; code of it that never returns but keeps DVX running (a handler that loops on dvxUpdate) is discarded at its next frame, as a crash there would be, and the app is ended then.
3.17.3. Features
-
Six-column ListView showing Name, Title, File, Type (Task for an app with a task of its own now: hasMainLoop, as every BASIC program has, or a callback-only app while the work shellAppTaskStart started for it runs; Callback for one that runs only in the callbacks DVX makes on its own task), Memory (from dvxMemGetAppUsage), and Status for every running app (the status line adds "Kept by ended programs: N KB", from dvxMemGetRetained, when ended apps left memory allocated). Status is Running, or Not responding when dvxAppIsHung reports the app has been inside one of its window callbacks for DVX_HUNG_APP_MS (5 seconds) without a modal dialog of its own open. The open window looks again every second (a shell idle handler) and refreshes the list when a row’s Type, Memory, or Status changed, and the status line’s memory figures each time.
-
Switch To button (Alt+S): raises and focuses the selected app’s topmost visible window, restoring it if minimized (shellActivateApp, which BASIC’s ShellRunningActivate calls too). Also triggered by double-clicking a row.
-
End Task button (Alt+E): force-kills the selected app via shellEndTask, as BASIC’s ShellRunningKill does. The shell app is the exception: ending it exits DVX, so shellEndTask first asks Exit DVX’s question ("Are you sure you want to exit DVX?"), and Yes exits DVX the Exit DVX way (every other app asked to close with its own save prompt; one that stays open stops the exit), force-killing only a shell app that does not respond. Every refresh keeps the selection on the same app; when that app is gone the selection moves to the row that took its place (or the new last row).
-
Run... button (Alt+R): the shell’s Run dialog (shellRunDialog, no history): a program with arguments, or a document, which opens in its associated program (shellRunCommand).
-
Status bar showing running app count plus total and used system memory.
-
Single-instance: reopening the Task Manager while it is already visible raises and focuses the existing window rather than creating a new one.
3.17.4. shellTaskMgrOpen
Open the Task Manager window, or raise it to the front if already open.
void shellTaskMgrOpen(AppContextT *ctx);
| Parameter | Description |
|---|---|
ctx |
Application context (from dvxInit). Required for window creation, stack manipulation, and registering the desktop-update callback. |
Called by the shell’s global Ctrl+Esc handler via the shellCtrlEscFn hook.
3.17.5. shellTaskMgrRefresh
Rebuild the task list display from the current shell app slot table and refresh the status bar. Registered with shellRegisterDesktopUpdate at open time so it is invoked whenever the shell detects app state changes.
void shellTaskMgrRefresh(void);
Takes no parameters. Safe to call even if the Task Manager window is not currently open (the call is a no-op in that case).
Chapter 4. Widgets
4.1. AnsiTerm
A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, DEC private modes, ANSI music, and a configurable scrollback buffer. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.
WCLASS_FIXED_FONT: it edits by columns, so its font must be fixed-pitch. Any size works (the column math uses the font’s charWidth and charHeight); a proportional font set with wgtSetFont, or inherited, is replaced by the system font when it draws.
WCLASS_SWALLOWS_ENTER: Enter is sent to the other computer even in a window with a default button.
The widget renders through two paint paths: a full paint used by the normal widget pipeline, and a fast incremental repaint (wgtAnsiTermRepaint) that pushes dirty rows directly to the window content buffer for low-latency serial echo.
Header: include/widget/ansiTerm/ansiTerm.h in the SDK (#include "ansiTerm/ansiTerm.h")
Loaded as: bin/widgets/kpunch/ansiterm/ansiterm.wgt, part of Communications. Without it there is no Terminal control and dvxAnsiTermApi() is NULL, so a program that may run without Communications checks that before it makes a terminal.
4.1.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtAnsiTerm(parent, cols, rows) |
Create an ANSI terminal widget with the given column/row dimensions. |
void wgtAnsiTermWrite(w, data, len) |
Write raw bytes into the terminal’s ANSI parser. data is a const uint8_t * buffer. Up to 4 KB is parsed at once; the rest of a longer text waits in order and is parsed 4 KB per poll (a frame each), so a long text does not hold DVX up. Clear, a resize, and a new scrollback length parse what waits first. |
void wgtAnsiTermClear(w) |
Clear the terminal screen and reset the cursor to the home position. |
void wgtAnsiTermSetComm(w, ctx, readFn, writeFn) |
Attach a communication channel. readFn and writeFn are I/O callbacks; ctx is passed as their first argument. |
void wgtAnsiTermSetScrollback(w, maxLines) |
Set the maximum number of scrollback lines, keeping the newest lines that fit (the same number changes nothing). |
int32_t wgtAnsiTermPoll(w) |
Poll the communication channel for incoming data and feed it into the parser. Returns number of bytes consumed. |
int32_t wgtAnsiTermRepaint(w, outY, outH) |
Fast repaint path that renders dirty rows directly into the window’s content buffer, bypassing the widget pipeline. Returns the number of rows repainted and the dirty region via outY/outH. |
4.1.3. API Struct (wgtRegisterApi "ansiterm")
The sApi struct exposes these function pointers:
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtAnsiTerm |
write |
wgtAnsiTermWrite |
clear |
wgtAnsiTermClear |
setComm |
wgtAnsiTermSetComm |
setScrollback |
wgtAnsiTermSetScrollback |
poll |
wgtAnsiTermPoll |
repaint |
wgtAnsiTermRepaint |
4.1.4. Extension API Struct (wgtRegisterApi "ansitermex")
Features added after the original table live in a second table so AnsiTermApiT keeps its layout for modules already built against it. dvxAnsiTermExApi() returns it (NULL when the loaded widget is older).
| Slot | Function | Description |
|---|---|---|
header |
WGT_API_HEADER |
ABI version and size, checked by wgtGetApi. |
copySelection |
bool wgtAnsiTermCopy(w) |
Copy the selection to the clipboard and clear it (a menu’s Copy). Returns false when nothing is selected. |
setPalette |
void wgtAnsiTermSetPalette(w, rgb) |
Replace the 16 attribute colors with ANSITERM_PALETTE_BYTES bytes of red, green, blue triplets (a color scheme). NULL restores the standard CGA colors. |
setMusic |
void wgtAnsiTermSetMusic(w, on) |
Recognize ANSI music (on at first). Off, ESC[M is always Delete Line and ESC[N and ESC[| do nothing. |
4.1.5. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Cols |
Integer |
Read/Write |
Number of columns. Setting it (or Rows) resizes the terminal (1-512): screen and scrollback start empty and the modes the host set (wrap, origin, cursor visible, scroll region) are reset; palette, scrollback length, and comm callbacks stay; the window is laid out again. |
Music |
Boolean |
Read/Write |
Recognize ANSI music (setMusic; True at first). |
Rows |
Integer |
Read/Write |
Number of rows. |
Scrollback |
Integer |
Read/Write |
Maximum number of scrollback lines. Setting another number keeps the newest lines that fit (the screen stays as it is); setting the same number changes nothing. |
4.1.6. Methods (BASIC Interface)
| Method | Description |
|---|---|
Clear |
Clear the terminal screen. |
Copy |
Copy the selection (copySelection); returns False when nothing is selected. |
Paste |
Send the clipboard to the comm write callback as Ctrl+V does (new lines as CR, 64-byte chunks); with no write callback, to the Send event in one piece. |
Poll |
Process any pending bytes on the attached communication channel. |
ResetColors |
The standard CGA colors again (setPalette NULL). |
SetColor |
index, color: one attribute color (0-15) from a BASIC color (&HBBGGRR, converted with wgtBasicColor). |
Write |
Write a string into the terminal (with ANSI escape processing). Dynamic (WGT_SIG_DYNAMIC) so every byte of the BASIC string arrives, NUL bytes included (wgtValueLen); the parser ignores a NUL as padding. |
4.1.7. Events
Besides the common events, three of its own, fired through wgtFireEvent (a C host gets them in onEvent with the names ANSITERM_EVT_MUSIC, ANSITERM_EVT_BELL, and ANSITERM_EVT_SEND):
| Event | Parameters | Description |
|---|---|---|
Music |
Macro As String |
An ANSI music string arrived: the BASIC PLAY text between ESC[| or ESC[N, or ESC[MF (MB, MN, ML, MS), and Ctrl+N (0x0E). For the ESC[M form the macro begins with that M command (e.g. "MFT120O4L8CDE"). Line ends are left out; a string longer than 4096 characters, an empty one, or one cut short by ESC fires nothing. |
Bell |
(none) |
A BEL character (Ctrl+G) arrived. |
Send |
Bytes As String |
Bytes for the host while no comm write callback is set (wgtAnsiTermSetComm): typed keys, a paste, and the replies to ESC[c and ESC[6n / ESC[255n. The argument is wgtValueBytes (read its length with wgtValueLen: it may hold NUL bytes). A reply waits until the byte that asked for it is parsed; keys typed while a Music, Bell, or Send handler runs go when it returns. |
The widget plays nothing itself: a handler plays the macro (BASIC: PLAY Macro; C: the music library’s musicMmlPlay). While a Music or Bell handler runs, the terminal takes no input: Poll leaves the bytes in the connection, and Write keeps them, in order, until the handler returns. A tune played in the foreground (MF) therefore holds back the text after it, as on a DOS terminal, while the window stays responsive. Bare ESC[M (no parameter) followed by anything but F, B, N, L, or S is still Delete Line. A handler may close the terminal’s window; the input after the event is then dropped.
4.1.8. Keyboard Shortcuts
Within the terminal widget:
| Key | Action |
|---|---|
Ctrl+C |
Copy selection to the clipboard (when a selection exists). |
Ctrl+V |
Send the clipboard contents to the attached write function. |
Arrows |
Send VT100 cursor escape sequences. |
Home/End |
Send VT100 Home/End sequences. |
PgUp/PgDn/Del |
Send the corresponding VT100 escape sequences. |
Shift+PgUp |
Page back through the scrollback history. |
Shift+PgDn |
Page forward through the scrollback history. |
Any key sent to the host returns the view to the live screen. The mouse wheel scrolls through the scrollback history locally; it does not send keys to the host. Clearing the screen (ESC[2J, form feed, reset, or Clear) saves the screen into the scrollback only up to its last non-blank row.
4.2. Base WidgetT (Common Properties, Events, and Operations)
4.2.1. DVX Widget System
Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in libdvx/dvxWgt.h; individual widget headers live in widgets/.
Individual widgets are documented in their own sections. See the table of contents for the full list.
4.2.2. Base WidgetT (Common Properties, Events, and Operations)
Every widget inherits from the WidgetT structure defined in libdvx/dvxWgt.h. The fields and callbacks listed here are available on all widget types.
Common Properties
| Field | Type | Description |
|---|---|---|
name |
char[32] |
Widget name for lookup via wgtFind(). |
x, y, w, h |
int32_t |
Computed geometry relative to the window content area (set by layout). |
minW, minH |
int32_t (tagged) |
Minimum size hints: the widget is never laid out smaller. Use wgtPixels(), wgtChars(), or wgtPercent() (of the inside of its container: see Percentages below). 0 = auto. A fixed width in a row (a button’s, a column of labels) is minW with weight 0. |
maxW, maxH |
int32_t (tagged) |
Maximum size constraints: the widget never grows larger; across its box a capped widget is centered. wgtPixels(), wgtChars(), or wgtPercent() (of the inside of its container). 0 = no limit. |
weight |
int32_t |
Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100. |
align |
WidgetAlignE |
Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE: where they sit along the container when none of them has a weight (with a weight the weighted children take the room and align does nothing). |
spacing |
int32_t (tagged) |
Spacing between children (containers only), wgtPixels(), wgtChars(), or wgtPercent() (of the container’s own width). WGT_GAP_DEFAULT = the class’s default; 0 = none. |
padding |
int32_t (tagged) |
Internal padding (containers only), wgtPixels(), wgtChars(), or wgtPercent() (of the container’s own width). WGT_GAP_DEFAULT = the class’s default; 0 = none. |
fgColor |
uint32_t |
Foreground color override: 0x00RRGGBB with WGT_COLOR_SET (black is WGT_COLOR_SET alone). 0 = use color scheme default. |
bgColor |
uint32_t |
Background color override: 0x00RRGGBB with WGT_COLOR_SET. 0 = none: the color scheme’s, or what the widget sits on (wgtBackColor). |
visible |
bool |
Visibility state. |
enabled |
bool |
Enabled state. Disabled widgets are grayed out and ignore input. |
readOnly |
bool |
Read-only mode: allows scrolling/selection but blocks editing. |
swallowTab |
bool |
When true, Tab key goes to the widget instead of navigating focus. |
backdrop |
bool |
Set by wgtSetBackdrop: the widget covers its parent behind the parent’s other children. |
accelKey |
char |
Lowercase accelerator character. 0 if none. |
tooltip |
const char * |
Tooltip text. NULL = none. Caller owns the string. |
contextMenu |
MenuT * |
Right-click context menu. NULL = none. Caller owns. |
userData |
void * |
Application-defined user data pointer. |
Size Specification Macros
| Macro | Description |
|---|---|
wgtPixels(v) |
Size in pixels. |
wgtChars(v) |
Size in character widths (multiplied by font charWidth). |
wgtPercent(v) |
Size as a percentage: in minW, minH, maxW, and maxH of the inside of the parent container (its width or height), in padding and spacing of the container’s own width. See Percentages below. |
Percentages. The layout measures every widget bottom-up before it knows any size, so a percentage counts as 0 when a window is measured: it never raises a widget’s minimum, a window’s fit (dvxFitWindow), its minimum size, or its scroll bars. The layout then arranges top-down and resolves each percentage against the size the container has just been given, so nested percentages compose (50% inside 50% is a quarter) and a resize resolves them again. A percentage takes only room the container has to spare beyond what was measured, so it never squeezes another widget below its minimum or makes the container overflow: padding first, then spacing, then the children’s minimums along the box; when the percentage minimums want more room than is left, each one’s share beyond its measured minimum shrinks in proportion. After that a percentage minimum acts as a pixel minimum: weights share out what is left (a weighted widget grows from its percentage minimum), and a maximum wins over a minimum. Across a box every child fills it anyway, so a percentage minimum across it adds nothing. Containers whose children fill them (TabControl pages, Splitter panes, the window’s root) take no percentage minimum from them; a WrapBox takes minW (of its inner width, at most a whole row) but not minH, and no padding or spacing in percent (its height comes from its rows). Padding and spacing in percent work in the boxes (VBox, HBox, Frame, RadioGroup, Toolbar, StatusBar, TabPage) and the ScrollPane. A widget class may give its own minimum as a percentage of the container too (WGT_METHOD_MIN_PERCENT: a BASIC UserControl’s natural size in percent); it follows every rule above, and with a percentage minW or minH as well the larger one counts.
Common Events (Callbacks)
These callback function pointers are available on every WidgetT. Set them directly on the widget struct.
| Callback | Signature | Description |
|---|---|---|
onClick |
void (*)(WidgetT *w) |
Fires on mouse click / activation, as in Visual Basic: after the release’s onMouseUp, when the release is over the widget (MouseDown, MouseUp, Click). A list’s (WCLASS_CLICK_ON_PICK) is its pick, after the press’s onMouseDown. Not for a press on the control’s chrome: its scroll bars, a list’s column headers (WGT_METHOD_HIT_CHROME). |
onDblClick |
void (*)(WidgetT *w) |
Fires on double-click (not on the control’s chrome): at the second press, after the first click’s onClick. Outside a button or a list the second press is the onDblClick alone, no onMouseDown, and its release an onMouseUp (MouseDown, MouseUp, Click, DblClick, MouseUp, as in Visual Basic). |
onChange |
void (*)(WidgetT *w) |
Fires when the widget’s value changes (text, selection, check state, etc.). |
onFocus |
void (*)(WidgetT *w) |
Fires when the widget receives keyboard focus. |
onBlur |
void (*)(WidgetT *w) |
Fires when the widget loses keyboard focus. |
onKeyPress |
void (*)(WidgetT *w, int32_t keyAscii) |
Fires for every key that has a character (its ASCII value): printable keys and also Enter, Esc, Tab, Backspace, and Ctrl+letter (1-26), after onKeyDown and before the widget acts on the key. wgtKeyReplace changes the character or (0) cancels it. |
onKeyDown |
void (*)(WidgetT *w, int32_t keyCode, int32_t shift) |
Fires on key down (the key + shift state), before onKeyPress and before the widget acts on the key, as in Visual Basic. wgtKeyReplace changes the key or (0) cancels it: no onKeyPress follows and the widget does nothing with it. |
onKeyUp |
void (*)(WidgetT *w, int32_t keyCode, int32_t shift) |
Fires on key up. |
onMouseDown |
void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Fires on mouse button press. button is that button’s MOUSE_* bit: MOUSE_LEFT (1), MOUSE_RIGHT (2), or MOUSE_MIDDLE (4), as Visual Basic’s vbLeftButton, vbRightButton, vbMiddleButton. x and y are relative to the widget’s content. A press of any button on the control’s chrome (its scroll bars and the corner between them, a list’s column headers: WGT_METHOD_HIT_CHROME) fires none, as in Visual Basic. |
onMouseUp |
void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Fires on mouse button release; button as for onMouseDown (none for the release of a press on the control’s chrome). The left release of a press goes to the widget pressed, wherever the mouse is (the press holds the mouse, as in Visual Basic), before its onClick. |
onMouseMove |
void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) |
Fires on mouse movement over the widget; button is the MOUSE_* mask of the buttons held (0 = none). None comes while a press on a control’s chrome is held (a scroll arrow held down, a thumb dragged), as in Visual Basic. |
onScroll |
void (*)(WidgetT *w, int32_t delta) |
Fires on mouse wheel scroll. |
onValidate |
bool (*)(WidgetT *w) |
Validation callback. Return false to cancel a pending write. |
onEvent |
void (*)(WidgetT *w, const char *name, WgtValueT *args, int32_t argc) |
A named event the widget fires that has no callback above (ListView ColumnClick, TextArea GutterClick, HelpView LinkClick, an event a BASIC control raises). args may be written back. |
wgtFireEvent(w, name, args, argc) fires an event by name: the names above (Click, DblClick, Change, GotFocus, LostFocus, KeyPress, KeyDown, KeyUp, MouseDown, MouseUp, MouseMove, Scroll) go to their callback, every other name to onEvent (see dvxWgt.h, Custom Events).
Generic Access
Every widget type can be created, read, written, and called by name through its interface descriptor, with values as WgtValueT — the way the BASIC form runtime and the designer drive widgets, and the way a C program uses a widget it has no header for (a BASIC control, for one):
WidgetT *list = wgtCreateByName("ListBox", parent);
WgtValueT item = wgtValueStr("first");
WgtValueT count;
wgtCallMethod(list, "AddItem", &item, 1, NULL);
wgtCallMethod(list, "ListCount", NULL, 0, &count); // count.i == 1
wgtGetProp / wgtSetProp work the same way. See dvxWgt.h, Generic Widget Access.
Common Operations
| Function | Description |
|---|---|
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) |
Initialize widgets for a window: installs the window’s onPaint, onMouse, onKey, onKeyUp, onResize, onFocus, and onBlur. Returns the root VBox container. The window’s first paint measures and lays out the widgets added to it. |
AppContextT *wgtGetContext(const WidgetT *w) |
Walk up from any widget to retrieve the AppContextT. |
void wgtInvalidate(WidgetT *w) |
Measure and lay out w’s whole window now (its scroll bars too), so geometry can be read at once, and repaint it in the next frame. Use it after a change of size or structure; widgets added since the last measure are measured by the next full paint anyway. |
void wgtInvalidatePaint(WidgetT *w) |
Mark widget for repaint only (no layout recalculation). |
void wgtSetText(WidgetT *w, const char *text) |
Set widget text (label, button, textinput, etc.). |
const char *wgtGetText(const WidgetT *w) |
Get widget text. |
void wgtSetEnabled(WidgetT *w, bool enabled) |
Enable or disable a widget. A disabled container’s widgets take no input or focus and paint disabled (as in Windows Forms; Visual Basic 6 leaves them looking enabled), and paint normally again when it is enabled, unless disabled themselves. |
void wgtSetReadOnly(WidgetT *w, bool readOnly) |
Set read-only mode. |
void wgtSetFocused(WidgetT *w) |
Set keyboard focus to a widget. |
WidgetT *wgtGetFocused(void) |
Get the currently focused widget. |
void wgtSetVisible(WidgetT *w, bool visible) |
Show or hide a widget. |
void wgtSetBackdrop(WidgetT *w, bool on) |
Make a widget its parent’s backdrop: out of the layout, covering the parent’s whole box behind its other children, never hit by the mouse (a Canvas backdrop’s drawing follows the parent’s size). See dvxWgt.h, wgtSetBackdrop. |
void wgtSetName(WidgetT *w, const char *name) |
Set widget name for lookup. |
WidgetT *wgtFind(WidgetT *root, const char *name) |
Find a widget by name in the subtree. |
void wgtDestroy(WidgetT *w) |
Destroy a widget and all its children. |
void wgtSetTooltip(WidgetT *w, const char *text) |
Set tooltip text. Pass NULL to remove. |
4.3. Box (VBox / HBox / Frame)
Container widgets that arrange their children in a vertical column (VBox), horizontal row (HBox), or a titled group box (Frame). These are the primary layout building blocks. Children are laid out using a weight-based algorithm with configurable spacing, padding, and alignment.
Frame is a labeled grouping container with a Motif-style beveled border. Its title text sits centered vertically on the top border line with a small background-filled gap behind the title, giving the classic Windows 3.1 / Motif group box appearance. Internally, Frame behaves like a VBox for layout purposes.
The widget DXE registers three separate interface entries ("vbox", "hbox", "frame") so the form designer can create each type independently.
Header: include/widget/box/box.h in the SDK (#include "box/box.h")
4.3.1. Creation
WidgetT *row = wgtHBox(parent);
WidgetT *col = wgtVBox(parent);
WidgetT *group = wgtFrame(parent, "Options");
4.3.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtVBox(parent) |
Create a vertical box container. Children stack top-to-bottom. |
WidgetT *wgtHBox(parent) |
Create a horizontal box container. Children stack left-to-right. |
WidgetT *wgtFrame(parent, title) |
Create a titled group box. Children stack vertically inside the bordered frame. The title string may include a '&' prefix for an accelerator key. |
4.3.3. API Struct (wgtRegisterApi "box")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
vBox |
wgtVBox |
hBox |
wgtHBox |
frame |
wgtFrame |
The designer also registers per-type APIs: "vbox", "hbox", and "frame" each expose a single create slot.
4.3.4. Properties
Box containers use the common WidgetT fields for layout control. There are no widget-specific properties registered with the interface system.
| Field | Description |
|---|---|
align |
Main-axis alignment of children. HBox: Start=left, Center=center, End=right. VBox: Start=top, Center=center, End=bottom. |
spacing |
Gap between children (tagged size). WGT_GAP_DEFAULT (the default): 4 pixels for VBox/HBox, 0 for Frame; wgtPixels(0) is none. |
padding |
Internal padding around children (tagged size). WGT_GAP_DEFAULT (the default): 4 pixels; wgtPixels(0) is none. |
weight |
Controls how the box itself stretches within its parent. |
Frame text is managed via the standard wgtSetText() / wgtGetText() interface (the widget has WCLASS_HAS_TEXT). BASIC code can set its title via the generic "Caption" or "Text" property.
4.4. Button
A push button with a text label. Fires onClick when pressed and released. Uses a two-phase press model: the button visually depresses on mouse-down and fires onClick only when the mouse is released while still inside the button bounds — dragging the mouse off cancels the press. Supports accelerator keys via '&' prefix in the text (e.g. "&OK" underlines 'O' and binds Alt+O).
Disabled buttons use the classic "embossed" rendering (highlight text offset by +1,+1 and shadow text at 0,0) for a chiseled appearance.
Header: include/widget/button/button.h in the SDK (#include "button/button.h")
4.4.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtButton(parent, text) |
Create a push button with the given label text. Pass NULL for no text. Text is copied into the widget. |
4.4.3. API Struct (wgtRegisterApi "button")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtButton |
4.4.4. Properties
Uses common WidgetT properties. Label text is managed via wgtSetText() / wgtGetText(). Set accelKey for keyboard shortcut (automatically parsed from '&' prefix in the text). The button is focusable (WCLASS_FOCUSABLE) and draws a focus rectangle when it holds keyboard focus.
No widget-specific properties are registered with the interface system. BASIC code sets the label via the generic "Caption" or "Text" property.
4.5. Canvas
A freeform drawing surface with a fixed-size pixel buffer stored in the display’s native pixel format. Provides drawing primitives (lines, rectangles, circles, text, individual pixels; coordinates may lie anywhere, drawing is clipped to the buffer) and supports loading BMP/PNG/JPEG/GIF files and saving BMP or PNG files (via dvxLoadImage/dvxSaveImage). Mouse interaction is available via a callback. The buffer is rendered to screen as a straight blit with no per-pixel conversion.
When the screen changes to another color depth (dvxChangeVideoMode), the canvas converts its drawing and its pen color to the new format (WGT_METHOD_ON_FORMAT_CHANGE) before anything draws on or paints it; out of memory, the drawing becomes white (or, when even that cannot be had, the canvas has none until wgtCanvasResize or wgtCanvasLoad makes one). Packed colors a program kept (wgtCanvasSetPenColor’s, wgtCanvasClear’s) are in the old format then: pack them again (packColor) or convert them (convertColor, dvxVideo.h).
Canvas coordinates are independent of widget position: (0,0) is the top-left of the canvas content, not the widget. By default the widget frames the buffer with a sunken bevel CANVAS_BORDER_WIDTH (2) pixels wide; wgtCanvasSetBorderStyle(w, CANVAS_BORDER_NONE) drops it, so the widget is exactly the buffer’s size (a drawing surface for a UserControl or a form). The frame width is the widget’s contentOffX / contentOffY, so mouse coordinates are relative to the buffer either way.
A canvas can be its parent’s backdrop (wgtSetBackdrop(cv, true), usually with CANVAS_BORDER_NONE): a picture behind the parent’s other widgets. It then takes no part in the layout, covers the parent’s whole box, paints before the other widgets (they paint over it, and repaint over it when it repaints), and passes presses to the parent. Its buffer follows the parent’s size both ways from the next layout on, keeping the top-left part of the drawing; the part it grew by is the color behind it (wgtBackColor: its own bgColor, else the parent’s), not white. DVX BASIC draws a form’s graphics on such a canvas, behind the form’s controls.
Header: include/widget/canvas/canvas.h in the SDK (#include "canvas/canvas.h")
4.5.2. API Functions
- WidgetT *wgtCanvas(parent, w, h)
-
Create a canvas with the given pixel dimensions. Buffer is initialized to white.
- void wgtCanvasClear(w, color)
-
Fill the entire canvas with a packed color.
- void wgtCanvasSetPenColor(w, color)
-
Set the drawing pen color (packed display color).
- void wgtCanvasSetPenSize(w, size)
-
Set the pen size in pixels: wgtCanvasDrawLine draws a round dot size pixels across and down at every point of the line (2 x 2 for 2, a cross of 5 for 3, 4 x 4 less its corners for 4; an even size has the point in the dot’s lower-right quarter). Clamped to 255; sizes below 1 are ignored.
- void wgtCanvasDrawLine(w, x0, y0, x1, y1)
-
Draw a line using Bresenham’s algorithm with the current pen color and size.
- void wgtCanvasDrawRect(w, x, y, width, height)
-
Draw a 1-pixel rectangle outline using the current pen color.
- void wgtCanvasFillRect(w, x, y, width, height)
-
Fill a rectangle using the current pen color.
- void wgtCanvasFillCircle(w, cx, cy, radius)
-
Fill a circle using the current pen color (integer sqrt; no FPU needed).
- void wgtCanvasSetPixel(w, x, y, color)
-
Set a single pixel to the given packed color.
- uint32_t wgtCanvasGetPixel(w, x, y)
-
Read a single pixel. Returns packed color.
- void wgtCanvasDrawText(w, x, y, text)
-
Draw text at the given canvas coordinates using the current pen color.
- void wgtCanvasDrawTextScaled(w, x, y, text, scale)
-
Draw text scale times as large (each font pixel a scale x scale block) in the pen color: titles. Scale 1 is wgtCanvasDrawText. BASIC: FontScale and Print on a PictureBox.
- void wgtCanvasSetMouseCallback(w, cb)
-
Set a mouse callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). cx/cy are canvas-relative, drag=true on mouse-move during press.
- int32_t wgtCanvasSave(w, path)
-
Save the canvas buffer to an image file: BMP when path ends in .bmp, PNG otherwise. Returns 0 on success, -1 on error.
- int32_t wgtCanvasLoad(w, path)
-
Load an image file into the canvas (resizes buffer to match). Returns 0 on success, -1 on error.
- int32_t wgtCanvasLoadData(w, data, len, name)
-
Load the picture in len bytes of an image file (as dvxLoadImageFromMemory reads them) as wgtCanvasLoad loads a file; Picture then reads name (NULL: ""). Returns 0 on success, -1 when they are not a picture.
- void wgtCanvasResize(w, newW, newH)
-
Resize the canvas buffer and relayout. The old content is discarded; the new buffer is white.
- void wgtCanvasSetBorderStyle(w, style)
-
CANVAS_BORDER_NONE (0) drops the sunken frame, any other value (CANVAS_BORDER_FIXED, 1, the default) shows it. The buffer keeps its size; the widget relays out.
- int32_t wgtCanvasGetBorderStyle(w)
-
CANVAS_BORDER_FIXED or CANVAS_BORDER_NONE.
- void wgtCanvasSetAlign(w, align)
-
Dock the canvas to an edge, Visual Basic’s PictureBox Align: CANVAS_ALIGN_NONE (0, the default), CANVAS_ALIGN_TOP (1), CANVAS_ALIGN_BOTTOM (2), CANVAS_ALIGN_LEFT (3), or CANVAS_ALIGN_RIGHT (4); any other value is CANVAS_ALIGN_NONE. From the next layout on, a Top or Bottom canvas in a column (or a Left or Right one in a row) takes nothing for its minimum along its parent’s cross axis, and its buffer follows the widget’s size there (its WGT_METHOD_LAYOUT), keeping the top-left part of what was drawn and white where it grew. Placing the widget at that edge is the host’s (the BASIC runtime moves a docked PictureBox to its form’s edge).
- int32_t wgtCanvasGetAlign(w)
-
The CANVAS_ALIGN_* the canvas is docked to.
- bool wgtCanvasGetDisplay(w, out)
-
Fill a DisplayT aimed at the canvas pixels (its backBuf; the screen’s pixel format, clipped to the canvas), so any libdvx drawing call — drawText, drawBevel, drawArrowGlyph, wmDrawScrollbarAt, rectCopyTransparent — draws on the canvas with the context’s blit ops; call wgtInvalidatePaint afterwards. False (out untouched) for a widget that is not a canvas. The BASIC DrawBevel, DrawButtonFace, DrawArrow, DrawScrollBar, DrawScrollArrow, and PrintAccel methods use it.
4.5.3. API Struct (wgtRegisterApi "canvas")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtCanvas |
clear |
wgtCanvasClear |
setPenColor |
wgtCanvasSetPenColor |
setPenSize |
wgtCanvasSetPenSize |
setMouseCallback |
wgtCanvasSetMouseCallback |
save |
wgtCanvasSave |
load |
wgtCanvasLoad |
drawLine |
wgtCanvasDrawLine |
drawRect |
wgtCanvasDrawRect |
fillRect |
wgtCanvasFillRect |
fillCircle |
wgtCanvasFillCircle |
setPixel |
wgtCanvasSetPixel |
getPixel |
wgtCanvasGetPixel |
drawText |
wgtCanvasDrawText |
resize |
wgtCanvasResize |
setBorderStyle |
wgtCanvasSetBorderStyle |
getBorderStyle |
wgtCanvasGetBorderStyle |
getDisplay |
wgtCanvasGetDisplay |
drawTextScaled |
wgtCanvasDrawTextScaled |
loadData |
wgtCanvasLoadData |
setAlign |
wgtCanvasSetAlign |
getAlign |
wgtCanvasGetAlign |
4.5.4. Properties
Drawing state (pen color, pen size) is managed by the API functions above. The BASIC interface registers these properties:
| Property | Type | Access | Description |
|---|---|---|---|
Align |
Enum |
Read/Write |
None (0, the default), Top (1), Bottom (2), Left (3), or Right (4): wgtCanvasSetAlign / wgtCanvasGetAlign. |
BorderStyle |
Enum |
Read/Write |
None (0) or FixedSingle (1, the default): wgtCanvasSetBorderStyle / wgtCanvasGetBorderStyle. |
ImageHeight |
Integer |
Read-only |
Height of the canvas buffer in pixels (0 when there is no buffer). |
ImageWidth |
Integer |
Read-only |
Width of the canvas buffer in pixels (0 when there is no buffer). |
Picture |
String |
Read/Write |
The file wgtCanvasLoad loaded, or the name wgtCanvasLoadData was given ("" when none; Clear and Resize wipe it). Setting a path loads it; setting "" clears the canvas to white. In BASIC it reads as a Picture object (see LOADPICTURE). |
4.5.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
Clear color% |
Fill the entire canvas with a color (&HBBGGRR, as RGB() makes it). |
DrawLine x0%, y0%, x1%, y1%, color% |
Draw a line between two points. |
DrawRect x%, y%, w%, h%, color% |
Draw a rectangle outline. |
DrawText x%, y%, text$ |
Draw text at the given position. |
FillCircle cx%, cy%, radius%, color% |
Fill a circle. |
FillRect x%, y%, w%, h%, color% |
Fill a rectangle. |
GetPixel(x%, y%) |
Returns the color at a pixel (&HBBGGRR). With fewer than 16 million colors on the screen it is the color the screen shows: black, white, and full colors such as RGB(255, 0, 0) read back exactly, others may differ slightly. |
Load(path$) |
Load a BMP, PNG, JPEG, or GIF image (the canvas takes its size). Returns 0 on success, -1 on error (WGT_SIG_RET_INT_STR). |
Resize w%, h% |
Resize the canvas (the drawing is cleared to white). |
Save(path$) |
Save the canvas: BMP when path$ ends in .bmp, PNG otherwise. Returns 0 on success, -1 on error (WGT_SIG_RET_INT_STR). |
SetPenColor color% |
Set the drawing color (&HBBGGRR). |
SetPenSize size% |
Set the pen size in pixels (1 to 255): the dot DrawLine draws at each point is size pixels across. |
SetPictureData(bytes$[, name$]) |
WGT_METHOD_SET_PICTURE_DATA (WGT_SIG_DYNAMIC): wgtCanvasLoadData(bytes, length, name). Returns True when the bytes are a picture. |
SetPixel x%, y%, color% |
Set a single pixel. |
4.6. Checkbox
A toggle control with a text label. Clicking toggles between checked and unchecked states. Fires onChange each time the state flips, then onClick. Supports accelerator keys (via '&' in the text) and keyboard toggle via Space when focused (Enter does not toggle it, as in Windows: a dialog box or a form gives Enter to its default button). A click is a press and a release over the box, as a button’s (WCLASS_PRESS_RELEASE, the widgetPressable helpers): the box shows pressed (its inside darkened) while the mouse button is held, and toggles at the release, after onMouseDown and onMouseUp; moving off before the release cancels it. Space and the accelerator press it the same way (widgetPressablePress), and the app loop releases it after the key’s dispatch, as a button’s keyboard click comes (sKeyPressedBtn, WGT_METHOD_ON_DRAG_END). The key’s own onKeyDown and onKeyPress come first, and wgtKeyReplace(0) there cancels the toggle.
The check mark is drawn as an "X" pattern rather than a traditional checkmark glyph. The focus rectangle wraps the label text (not the box), matching the Windows 3.1 convention.
Header: include/widget/checkbox/checkbox.h in the SDK (#include "checkbox/checkbox.h")
4.6.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtCheckbox(parent, text) |
Create a checkbox with the given label text. |
bool wgtCheckboxIsChecked(w) |
Returns true if the checkbox is checked. |
void wgtCheckboxSetChecked(w, checked) |
Set the checked state programmatically. Triggers a repaint but does NOT fire onChange. |
4.6.3. API Struct (wgtRegisterApi "checkbox")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtCheckbox |
isChecked |
wgtCheckboxIsChecked |
setChecked |
wgtCheckboxSetChecked |
4.6.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Value |
Boolean |
Read/Write |
Whether the checkbox is checked. |
Label text is managed via the standard wgtSetText() / wgtGetText() interface. BASIC code uses the generic "Caption" or "Text" property.
4.7. ComboBox
A combination of a single-line text input and a drop-down list. The user can type a value or select one from the list. When the user picks a list item, its text is copied into the edit buffer. Supports full text editing (cursor movement, selection, clipboard, undo) via the texthelp library and a popup overlay list via the listhelp library. Setting the text or picking a list item clears the undo history. Keyboard: Down, F4, or Alt+Down/Alt+Up opens the list; while it is open Down/Up move the highlight and Enter, F4, or Alt+Down/Alt+Up pick the item and close it (Esc closes without picking).
A read-only combo box (wgtSetReadOnly) ignores the editing keys (typing, Backspace, Delete, paste, cut, undo) but still allows cursor movement, selection, copy, and picking an item from the list.
Depends on "texthelp" and "listhelp" helper libraries (declared in combobox.dep).
WCLASS_FIXED_FONT: it edits by columns, so its font must be fixed-pitch. Any size works (the column math uses the font’s charWidth and charHeight); a proportional font set with wgtSetFont, or inherited, is replaced by the system font when it draws.
Header: include/widget/comboBox/comboBox.h in the SDK (#include "comboBox/comboBox.h")
4.7.1. Creation
WidgetT *cb = wgtComboBox(parent, 128);
wgtComboBoxAddItem(cb, "Arial");
wgtComboBoxAddItem(cb, "Courier");
wgtComboBoxAddItem(cb, "Times");
4.7.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtComboBox(parent, maxLen) |
Create a combo box. maxLen is the maximum editable text length (0 => default 256). |
void wgtComboBoxSetItems(w, items, count) |
Set the dropdown items from a const char ** array. Items are not copied — caller owns them. |
int32_t wgtComboBoxGetSelected(w) |
Get the index of the last selected item (-1 if the text was typed freely). |
void wgtComboBoxSetSelected(w, idx) |
Select an item by index. Copies its text into the edit buffer. |
void wgtComboBoxAddItem(w, text) |
Append an item to the owned list (strdup’d); a sorted list puts it in its place (listPopupAddItem). |
bool wgtComboBoxInsertItem(w, text, idx) |
Insert an item before item idx (0 to the count; the count appends): the selection stays on its item; the new item is the NewIndex. False, adding nothing, when idx is out of range. |
bool wgtComboBoxRemoveItem(w, idx) |
Remove the item at idx. The selection stays on the same item; removing the selected item leaves no selection (the edit text is kept). False when there is no item idx. |
bool wgtComboBoxSetItem(w, idx, text) |
Give item idx new text, keeping its number. False when there is no item idx. |
int32_t wgtComboBoxGetItemData(w, idx) |
The number of item idx (Visual Basic’s ItemData; 0 when none was set or there is no such item). |
bool wgtComboBoxSetItemData(w, idx, value) |
Set the number of item idx (it moves with the item through inserts and removals). False when there is no item idx. |
int32_t wgtComboBoxGetNewIndex(w) |
The item added last (Visual Basic’s NewIndex), -1 when an item was removed since or none was added. |
void wgtComboBoxClear(w) |
Remove all owned items and reset the selection. |
const char *wgtComboBoxGetItem(w, idx) |
Get the text of an item by index. |
int32_t wgtComboBoxGetItemCount(w) |
Get the total number of items. |
void wgtComboBoxSetMaxLength(w, maxLen) |
Change the maximum editable text length (0 => default 256); longer text is cut. |
int32_t wgtComboBoxGetMaxLength(w) |
Get the maximum editable text length. |
void wgtComboBoxSetSorted(w, sorted) |
Keep the list in order (Visual Basic’s Sorted; case ignored): true sorts the items now, each with its number, the selection on its item (listPopupSort). |
bool wgtComboBoxGetSorted(w) |
Whether the list is sorted. |
void wgtComboBoxSetTopIndex(w, idx) |
Scroll item idx to the top of the list, as far as it scrolls (Visual Basic’s TopIndex; listPopupSetTopIndex): the list opens there. The selection stays. |
int32_t wgtComboBoxGetTopIndex(w) |
The first item the list shows (where it was scrolled to). |
4.7.3. API Struct (wgtRegisterApi "combobox")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtComboBox |
setItems |
wgtComboBoxSetItems |
getSelected |
wgtComboBoxGetSelected |
setSelected |
wgtComboBoxSetSelected |
addItem |
wgtComboBoxAddItem |
removeItem |
wgtComboBoxRemoveItem |
clear |
wgtComboBoxClear |
getItem |
wgtComboBoxGetItem |
getItemCount |
wgtComboBoxGetItemCount |
setMaxLength |
wgtComboBoxSetMaxLength |
getMaxLength |
wgtComboBoxGetMaxLength |
insertItem |
wgtComboBoxInsertItem |
setItem |
wgtComboBoxSetItem |
getItemData |
wgtComboBoxGetItemData |
setItemData |
wgtComboBoxSetItemData |
getNewIndex |
wgtComboBoxGetNewIndex |
getSorted |
wgtComboBoxGetSorted |
setSorted |
wgtComboBoxSetSorted |
getTopIndex |
wgtComboBoxGetTopIndex |
setTopIndex |
wgtComboBoxSetTopIndex |
4.7.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
ListIndex |
Integer |
Read/Write |
Index of the currently selected item (-1 if none); checked: -1 to the last item, any other refused (error 380 in BASIC). |
MaxLength |
Integer |
Read/Write |
Most characters the edit field holds (0 = the default, 256); checked: below 0 refused. |
NewIndex |
Integer |
Read |
The item added last (-1: none since the last removal). |
Sorted |
Boolean |
Read/Write |
Keep the list in order (wgtComboBoxSetSorted). |
TopIndex |
Integer |
Read/Write |
The first item the list shows (wgtComboBoxSetTopIndex); checked: 0 to the last item (0 on an empty list), any other refused (error 380 in BASIC). |
Editable text is accessible via the generic "Text" property. "ListCount" is available through the ListCount method.
4.7.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddItem text$ [, index%] |
Append an item to the dropdown list, or insert it before item index% (WGT_SIG_STR and WGT_SIG_CHK_STR_INT). |
Clear |
Remove all items and clear the selection. |
ItemData(index%) [= n] |
An indexed property (WGT_SIG_IDX_GET_INT and WGT_SIG_IDX_SET_INT): the item’s number. |
List(index%) [= text$] |
Return the text of the item at the given index; assigned (WGT_SIG_IDX_SET_STR), the item’s new text. |
ListCount() |
Return the total number of items. |
RemoveItem index% |
Remove the item at the given index (WGT_SIG_CHK_INT). The selection stays on the same item; removing the selected item leaves no selection (the text is kept). |
SetItems items$ |
Replace all the items at once from a "|"-separated list ("Red|Green|Blue"; every "|" separates two items, "" empties the list). Nothing is selected afterwards. The text is kept. |
4.7.6. Events
| Callback | Description |
|---|---|
onChange |
Fires when the user types or edits the text. A pick from the list fires none, as in Visual Basic. |
onClick |
Fires when the user picks an item from the list (its text already in the field): a click on a row of the open list, each move of Up, Down, or type-ahead while it is open, Up or Down on the closed box, or a wheel notch on the closed box. Typing, and a click on the text or the arrow, fire none. |
DropDown |
The widget’s own event (wgtFireEvent, no arguments), as the list is about to open: the arrow, F4, Alt+Down, Alt+Up, or the access key. |
4.8. DataCtrl
A VB3-style Data control for database binding. Displays a visible navigation bar (|< < > >|) that connects to a SQLite database through the database library (dvxsql, loaded the first time a Data control needs it). Reads the RecordSource rows into an in-memory cache for bidirectional navigation: a Refresh reads the first 64, and the widget’s polls read the rest, about 20 ms a frame, so a big record set does not hold DVX up. Fires onChange (BASIC: Reposition) each time the current row changes so bound controls can update. Supports master-detail linking between Data controls (MasterSource / MasterField / DetailField), INSERT via AddNew, and DELETE via Delete.
RecordSource is a table name or a query: a RecordSource whose first word is SELECT, WITH, or VALUES (blanks before it skipped, any case, any blank or line break after it) is a query, anything else names a table. A query’s records are read-only: AddNew, Update, and Delete fail (wgtDataCtrlGetError says why), and an edit is dropped when the cursor moves. With a DetailField the control is a detail control: it shows the rows whose DetailField equals the master value (wgtDataCtrlSetMasterValue; the BASIC form runtime sets it from the MasterSource control’s MasterField), and none while that value is empty (the master has no current row). A query source is wrapped as a subquery for that filter so its own WHERE and ORDER BY stay valid.
UPDATE and DELETE identify the row by the KeyColumn value it had when it was loaded (KeyColumn empty, or naming no column, means the first column), so editing the key column changes the key instead of writing to another row; an UPDATE writes only the changed columns and fails (the row stays unsaved) when no database row matches. A key the quoted text match cannot find (an integer in a column without a declared type, a REAL, or NULL) is matched by its text form instead, as long as that names exactly one row. Setting a field to the value it already has is not an edit. A row made by AddNew is saved with an INSERT of the columns that are not empty: an empty one is left out, so the database gives it its default (an INTEGER PRIMARY KEY column its new number). The saved row is then read back from the database, so the cache shows the key and defaults the database gave it and later edits find it.
Pending edits are saved (after the onValidate handler, see Events) before every cursor move, AddNew, and Refresh; a move or AddNew is refused while the save fails, and Refresh discards an edit that cannot be saved. When the window holding the control closes, call wgtDataCtrlUnload before destroying it (the BASIC form runtime calls it when a form unloads, after QueryUnload and Unload, as Visual Basic’s Data control saves when its form unloads): the pending edit is saved as wgtDataCtrlUpdate saves it, the onValidate handler first (DataActionUnloadE). An edit the handler cancels or says not to save, or one whose save fails, is dropped: the row goes back to what the database holds (an AddNew row leaves the cache), nothing fires, and wgtDataCtrlGetError says why. Destroying the control drops a pending edit without saving it or running the Validate handler, since a handler may not run while the window is torn down: that is what happens to a program that destroys the window without wgtDataCtrlUnload, a program ended by force (End Task, a fault), and the windows a program leaves when it ends (a BASIC program’s at END). DVX’s log notes each edit dropped.
Every operation (Refresh, the moves, wgtDataCtrlSetCurrentRow, SetField, Update, AddNew, Delete, Unload) clears the control’s error first, and one that fails leaves why in it: the database’s own message (a missing table, a constraint the row breaks, a locked database), or the control’s own reason (no DatabaseName or RecordSource, a read-only query, no current row, no such column, the Validate handler canceled the save, out of memory). wgtDataCtrlGetError returns it, "" after a success; BASIC reads it as LastError. A move past the first or last row is not a failure (BOF and EOF tell).
The navigation logic caches the result set so there is no round-trip for MoveNext/MovePrev. Until every row is read, the query stays open on a connection of its own, which holds the database’s read lock: a write to that database from elsewhere (another program, or SQLExec) fails with "database is locked" until then. What needs the rows does not wait for the polls: MoveNext past the rows read and wgtDataCtrlSetCurrentRow beyond them read on as far as they need, and MoveLast, AddNew, Update, and Delete read the rest first (the control’s own writes would be locked out by its query too). The row count grows as rows arrive; a copy that runs out of memory part way frees the cache whole, as a failed Refresh does, and onChange then fires so bound controls clear.
Header: include/widget/dataCtrl/dataCtrl.h in the SDK (#include "dataCtrl/dataCtrl.h")
4.8.1. Creation
WidgetT *data = wgtDataCtrl(parent);
WgtValueT dbName = wgtValueStr("C:\\BOOKS.DB");
WgtValueT source = wgtValueStr("books");
WgtValueT key = wgtValueStr("id");
wgtSetProp(data, "DatabaseName", &dbName);
wgtSetProp(data, "RecordSource", &source);
wgtSetProp(data, "KeyColumn", &key);
wgtDataCtrlRefresh(data);
if (wgtDataCtrlGetError(data)[0]) {
dvxErrorBox(ctx, "Books", wgtDataCtrlGetError(data));
}
DatabaseName, RecordSource, KeyColumn, Caption, MasterSource, MasterField, and DetailField have no macros of their own: C sets and reads them as properties with wgtSetProp and wgtGetProp (by the BASIC names in the table below), as above, then calls wgtDataCtrlRefresh to read the rows.
4.8.2. API Functions
| Macro | Description |
|---|---|
WidgetT *wgtDataCtrl(parent) |
Create a Data control. |
void wgtDataCtrlRefresh(w) |
Save a pending edit, then run the RecordSource query again and rebuild the row cache (row 0 current). Fires onChange. |
void wgtDataCtrlMoveFirst(w) |
Move the cursor to the first row. |
void wgtDataCtrlMovePrev(w) |
Move the cursor to the previous row (at the first row: BOF set, the cursor stays). |
void wgtDataCtrlMoveNext(w) |
Move the cursor to the next row (at the last row: EOF set, the cursor stays). |
void wgtDataCtrlMoveLast(w) |
Move the cursor to the last row (the record set is read to its end first). |
const char *wgtDataCtrlGetField(w, colName) |
The value of a column in the current row (column name case-insensitive; "" for no row or no such column). |
void wgtDataCtrlSetField(w, colName, value) |
Set the value of a column in the current row. Marks the row dirty unless the value is unchanged. |
void wgtDataCtrlUpdate(w) |
Write the pending edit (INSERT for an AddNew row, else UPDATE) to the database, after the onValidate handler (DataActionUpdateE) agrees. Nothing (and no onValidate) without an edit. |
void wgtDataCtrlAddNew(w) |
Save a pending edit, then append a blank row and move the cursor to it. The row is dirty and new until it is saved. Refused for a query source. |
void wgtDataCtrlDelete(w) |
Delete the current row from the database and the cache (an unsaved AddNew row only from the cache), after the onValidate handler (DataActionDeleteE) agrees (not when the handler itself deletes). |
void wgtDataCtrlSetMasterValue(w, val) |
Set the master-detail filter value (used at the next Refresh). The BASIC form runtime sets it. |
int32_t wgtDataCtrlGetRowCount(w) |
The number of rows read so far (all of them once the polls have read the rest, or after MoveLast). BASIC: RecordCount. |
int32_t wgtDataCtrlGetColCount(w) |
The number of columns in the result set. BASIC: FieldCount. |
const char *wgtDataCtrlGetColName(w, col) |
A column’s name, 0 for the first ("" past the last). BASIC: FieldName. |
const char *wgtDataCtrlGetCellText(w, row, col) |
The text of any cell, both from 0, without moving the cursor ("" outside). BASIC: GetCell. |
void wgtDataCtrlSetCurrentRow(w, row) |
Move the cursor to a row (saving the pending edit first; a row out of range does nothing). BASIC: AbsolutePosition. |
int32_t wgtDataCtrlGetCurrentRow(w) |
The current row (-1 if there are no rows). BASIC: AbsolutePosition. |
uint32_t wgtDataCtrlGetGeneration(w) |
A counter that changes whenever the cached rows or cell values change (Refresh, AddNew, Delete, SetField, a saved new row read back) but not on cursor moves, nor when more rows of the record set arrive (only the row count grows then). Bound views use it to rebuild derived state only when needed. |
const char *wgtDataCtrlGetError(w) |
Why the latest operation failed, "" when it did not (see above). BASIC: LastError. |
void wgtDataCtrlUnload(w) |
The window holding the control is closing: save the pending edit as wgtDataCtrlUpdate does (onValidate first, DataActionUnloadE), or drop it when onValidate cancels or says not to save, or the save fails (see above). Does nothing from the onValidate handler. BASIC: done when the form unloads. |
DataActionE wgtDataCtrlGetValidateAction(w) |
In the onValidate handler: the operation it is called for (see Events); DataActionCancelE outside it. |
void wgtDataCtrlSetValidateAction(w, action) |
In the onValidate handler: DataActionCancelE cancels the operation; another move or DataActionAddNewE replaces a move or AddNew. A value that is no DataActionE is ignored. BASIC: Validate’s Action. |
bool wgtDataCtrlGetValidateSave(w) |
In the onValidate handler: whether the current row was changed (false outside it). BASIC: Validate’s Save. |
void wgtDataCtrlSetValidateSave(w, save) |
In the onValidate handler: false drops the row’s changes, and the operation goes on. |
4.8.3. API Struct (wgtRegisterApi "data")
| Slot | Macro |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtDataCtrl |
refresh |
wgtDataCtrlRefresh |
moveFirst |
wgtDataCtrlMoveFirst |
movePrev |
wgtDataCtrlMovePrev |
moveNext |
wgtDataCtrlMoveNext |
moveLast |
wgtDataCtrlMoveLast |
getField |
wgtDataCtrlGetField |
setField |
wgtDataCtrlSetField |
update |
wgtDataCtrlUpdate |
addNew |
wgtDataCtrlAddNew |
delete |
wgtDataCtrlDelete |
setMasterValue |
wgtDataCtrlSetMasterValue |
getRowCount |
wgtDataCtrlGetRowCount |
getColCount |
wgtDataCtrlGetColCount |
getColName |
wgtDataCtrlGetColName |
getCellText |
wgtDataCtrlGetCellText |
setCurrentRow |
wgtDataCtrlSetCurrentRow |
getCurrentRow |
wgtDataCtrlGetCurrentRow |
getGeneration |
wgtDataCtrlGetGeneration |
getError |
wgtDataCtrlGetError |
unload |
wgtDataCtrlUnload |
getValidateAction |
wgtDataCtrlGetValidateAction |
setValidateAction |
wgtDataCtrlSetValidateAction |
getValidateSave |
wgtDataCtrlGetValidateSave |
setValidateSave |
wgtDataCtrlSetValidateSave |
4.8.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
DatabaseName |
String |
Read/Write |
Path to the SQLite database file. |
RecordSource |
String |
Read/Write |
A table name, or a query (first word SELECT, WITH, or VALUES; read-only). |
KeyColumn |
String |
Read/Write |
The column that identifies a row for UPDATE and DELETE ("" or an unknown name: the first column). |
MasterSource |
String |
Read/Write |
Name of the master Data control for master-detail linking (BASIC form runtime). |
MasterField |
String |
Read/Write |
Column in the master control to read for the filter value. |
DetailField |
String |
Read/Write |
Column in this table to filter by the master value (set: a detail control). |
Caption |
String |
Read/Write |
Text displayed on the navigator bar (the RecordSource after the first successful Refresh when empty). |
BOF |
Boolean |
Read-only |
True after a MovePrevious at the first row (the cursor stays there), or when there are no rows. A move onto a row clears it. |
EOF |
Boolean |
Read-only |
True after a MoveNext at the last row (the cursor stays there), or when there are no rows. A move onto a row clears it. |
RecordCount |
Long |
Read-only |
wgtDataCtrlGetRowCount. |
FieldCount |
Integer |
Read-only |
wgtDataCtrlGetColCount. |
AbsolutePosition |
Long |
Read/Write |
wgtDataCtrlGetCurrentRow / wgtDataCtrlSetCurrentRow. |
LastError |
String |
Read-only |
wgtDataCtrlGetError. |
4.8.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddNew |
wgtDataCtrlAddNew. |
Delete |
wgtDataCtrlDelete. |
FieldName(col%) |
wgtDataCtrlGetColName. |
GetCell(row&, col%) |
wgtDataCtrlGetCellText. |
GetField(col$) |
wgtDataCtrlGetField. |
MoveFirst |
wgtDataCtrlMoveFirst. |
MoveLast |
wgtDataCtrlMoveLast. |
MoveNext |
wgtDataCtrlMoveNext. |
MovePrevious |
wgtDataCtrlMovePrev. |
Refresh |
wgtDataCtrlRefresh. |
SetField col$, v$ |
wgtDataCtrlSetField. |
Update |
wgtDataCtrlUpdate. |
4.8.6. Events
| Callback | Description |
|---|---|
onChange |
Fires when the current row changes (BASIC: Reposition, the default event). |
onValidate |
Visual Basic’s Validate: called before every operation that leaves the current row and before wgtDataCtrlUpdate writes a changed one; return false to cancel (BASIC: Validate(Action, Save)). |
The handler reads what it is called for with wgtDataCtrlGetValidateAction, a DataActionE (Visual Basic’s vbDataAction numbers): DataActionMoveFirstE, DataActionMovePreviousE, DataActionMoveNextE, DataActionMoveLastE, DataActionAddNewE, DataActionUpdateE (only for a changed row), DataActionDeleteE, DataActionBookmarkE (wgtDataCtrlSetCurrentRow), DataActionCloseE (wgtDataCtrlRefresh), DataActionUnloadE (wgtDataCtrlUnload); DataActionFindE is never passed. wgtDataCtrlGetValidateSave is true when the row was changed. It is called only when there is a current row, and not for a move past an end (BOF or EOF is set instead). The handler may:
-
cancel: return false, or wgtDataCtrlSetValidateAction(w, DataActionCancelE). The operation does not happen and the row keeps its changes (lastError: canceled); but Refresh still reads the rows again (the changes go) and wgtDataCtrlUnload drops the changes.
-
turn a move or AddNew into another move or AddNew with wgtDataCtrlSetValidateAction: that one happens instead. Another change of the action is ignored.
-
drop the changes: wgtDataCtrlSetValidateSave(w, false). The row gets back the values it was loaded with (an AddNew row leaves the cache) and the operation goes on.
Otherwise a changed row is written before the operation (Delete does not write it: the row and its changes go together).
// sCtx: the program's AppContextT, kept by appMain
static bool onValidate(WidgetT *data) {
if (wgtDataCtrlGetValidateSave(data) && dvxMessageBox(sCtx, "Books", "Save the changes?", MB_YESNO) == ID_NO) {
wgtDataCtrlSetValidateSave(data, false);
}
return true;
}
While the Validate handler runs, the moves (MoveFirst/MoveLast/MoveNext/MovePrevious, wgtDataCtrlSetCurrentRow), AddNew, Refresh, and Update on the same control are refused and return without doing anything: each would save, and therefore validate, the same row again. Delete is still allowed; Update re-checks the row after the handler returns.
4.9. DbGrid
A database grid widget that displays all records from a Data control in a scrollable, sortable table. Columns auto-populate from the Data control’s column names and can be hidden, resized (by dragging a column border), and renamed by the application. Clicking a column header sorts the display ascending/descending, in the ListView’s order: numbers (digits with a sign, a decimal point, or an exponent) by value, ahead of the cells that are not numbers, which sort as text with case ignored; equal cells keep their data order. The highlighted row is always the Data control’s current row: selecting a row moves the Data control’s cursor, and the highlight is read from the cursor whenever the grid paints. The grid’s polls follow the Data control’s rows: a change to them, and the rows of a record set that arrive a part at a time (sorted in as they come, in the order a full sort gives), are shown without a call. A cursor move is not: a C application that moves the cursor elsewhere (the Data control’s own buttons or API) calls wgtDbGridRefresh (or wgtInvalidatePaint on the grid) from the Data control’s onChange; the form runtime does this for BASIC programs. The grid reads directly from the Data control’s cached rows, so there is no separate copy of the data. Re-binding the same Data control (as the form runtime does on every Reposition) keeps the sort order and column settings while the column set is unchanged (the sort order and automatic widths are rebuilt when the Data control’s rows or values changed), and a width set by dragging a column border is kept like one set with wgtDbGridSetColumnWidth. An automatic column width fits the header and the first 200 rows. Cell and header text is clipped to its column.
The grid supports alternating row shading, vertical and horizontal scrollbars, keyboard navigation (arrows, Page Up/Down, Home, End), and double-click activation (fires onDblClick; so does Enter). The mouse wheel scrolls the view without moving the record cursor.
Header: include/widget/dbGrid/dbGrid.h in the SDK (#include "dbGrid/dbGrid.h")
4.9.1. Creation
WidgetT *data = wgtDataCtrl(parent);
WidgetT *grid = wgtDbGrid(parent);
wgtDbGridSetDataWidget(grid, data);
4.9.2. API Functions
| Macro | Description |
|---|---|
WidgetT *wgtDbGrid(parent) |
Create a database grid widget. |
void wgtDbGridSetDataWidget(w, dataWidget) |
Bind the grid to a Data control. Auto-populates columns from the Data control’s column names. |
void wgtDbGridRefresh(w) |
Re-read the Data control’s state and repaint the grid. The sort index and automatic column widths are rebuilt only when the Data control’s rows or values changed since the last build; a cursor move just repaints. |
void wgtDbGridSetColumnVisible(w, fieldName, visible) |
Show or hide a column by field name. |
void wgtDbGridSetColumnHeader(w, fieldName, header) |
Set a display header for a column (overrides the field name). |
void wgtDbGridSetColumnWidth(w, fieldName, width) |
Set a column’s width (tagged size, 0 = auto). |
int32_t wgtDbGridGetSelectedRow(w) |
Get the selected data row: the bound Data control’s current row (-1 if unbound or no rows). |
void wgtDbGridSetSelectedRow(w, row) |
Move the bound Data control’s cursor to a data row (clamped to the row range). A negative row is ignored. |
4.9.3. API Struct (wgtRegisterApi "dbgrid")
| Slot | Macro |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtDbGrid |
setDataWidget |
wgtDbGridSetDataWidget |
refresh |
wgtDbGridRefresh |
setColumnVisible |
wgtDbGridSetColumnVisible |
setColumnHeader |
wgtDbGridSetColumnHeader |
setColumnWidth |
wgtDbGridSetColumnWidth |
getSelectedRow |
wgtDbGridGetSelectedRow |
setSelectedRow |
wgtDbGridSetSelectedRow |
4.9.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
GridLines |
Boolean |
Read/Write |
Whether to draw grid lines between cells (default: true). |
SelectedRow |
Integer |
Read/Write |
The bound Data control’s current row (-1 if none). Setting it moves the Data cursor. |
4.9.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
Refresh |
wgtDbGridRefresh. |
SetColumnVisible field$, visible |
wgtDbGridSetColumnVisible. |
SetColumnHeader field$, header$ |
wgtDbGridSetColumnHeader. |
SetColumnWidth field$, width% |
wgtDbGridSetColumnWidth (width% in pixels, 0 = auto). |
4.9.6. Events
| Event | Description |
|---|---|
Click |
onClick: fires for every click on the rows or the empty space below them, at the release over the grid after onMouseUp (the press moves the current row; a press on a column header, a column border, or a scroll bar is the grid’s chrome and fires none, nor onMouseDown or onMouseUp: widgetPressOnChrome), and when the arrow, page, Home, or End keys move the current row. |
DblClick |
onDblClick: fires on the second press of a double click on the rows or the empty space below them (not on a column header, a column border, or a scroll bar), and for Enter. Default event. |
4.10. Dropdown
A drop-down list that displays a single selected item and expands to a popup list when clicked. Unlike ComboBox, the user cannot type free text — only list items can be selected. Keyboard: while closed, Down/Up change the selection and type-ahead (the lists' rule, widgetTypeAheadFind: keys typed quickly make up a prefix, Space included) picks the item; F4 or Alt+Down/Alt+Up open the list. As in Windows, Space and Enter do not open it: Enter is left to the window’s default button (a dialog box’s, or one set with dvxSetWindowButtons). While open, Down/Up move the highlight and type-ahead jumps to a matching item, and Enter, Space, F4, or Alt+Down/Alt+Up select the highlighted item and close the list (Esc closes without selecting); the selection changes once, as the list closes, so a caller acting on it (the file dialog’s drive list) acts on the item taken only. The mouse wheel scrolls the open list, and steps the selection one item a notch on the closed box. Ctrl and Alt chords never change the selection. The popup overlay is rendered above all other widgets via the widget paint overlay mechanism.
Depends on the "listhelp" helper library (declared in dropdown.dep).
Header: include/widget/dropdown/dropdown.h in the SDK (#include "dropdown/dropdown.h")
4.10.1. Creation
WidgetT *dd = wgtDropdown(parent);
wgtDropdownAddItem(dd, "Red");
wgtDropdownAddItem(dd, "Green");
wgtDropdownAddItem(dd, "Blue");
4.10.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtDropdown(parent) |
Create a dropdown list. |
void wgtDropdownSetItems(w, items, count) |
Set the list from a caller-owned const char ** array. |
int32_t wgtDropdownGetSelected(w) |
Get the index of the selected item (-1 if none). |
void wgtDropdownSetSelected(w, idx) |
Set the selected item by index. |
void wgtDropdownAddItem(w, text) |
Append an owned item (strdup’d); a sorted list puts it in its place (listPopupAddItem). |
bool wgtDropdownInsertItem(w, text, idx) |
Insert an item before item idx (0 to the count; the count appends): the selection stays on its item; the new item is the NewIndex. False, adding nothing, when idx is out of range. |
bool wgtDropdownRemoveItem(w, idx) |
Remove the item at idx. The selection stays on the same item; removing the selected item leaves no selection. False when there is no item idx. |
bool wgtDropdownSetItem(w, idx, text) |
Give item idx new text, keeping its number. False when there is no item idx. |
int32_t wgtDropdownGetItemData(w, idx) |
The number of item idx (Visual Basic’s ItemData; 0 when none was set or there is no such item). |
bool wgtDropdownSetItemData(w, idx, value) |
Set the number of item idx (it moves with the item through inserts and removals). False when there is no item idx. |
int32_t wgtDropdownGetNewIndex(w) |
The item added last (Visual Basic’s NewIndex), -1 when an item was removed since or none was added. |
void wgtDropdownClear(w) |
Remove all owned items. |
const char *wgtDropdownGetItem(w, idx) |
Get the text of an item by index. |
int32_t wgtDropdownGetItemCount(w) |
Get the total number of items. |
void wgtDropdownSetSorted(w, sorted) |
Keep the list in order (Visual Basic’s Sorted; case ignored): true sorts the items now, each with its number, the selection on its item (listPopupSort). |
bool wgtDropdownGetSorted(w) |
Whether the list is sorted. |
void wgtDropdownSetTopIndex(w, idx) |
Scroll item idx to the top of the list, as far as it scrolls (Visual Basic’s TopIndex; listPopupSetTopIndex): the list opens there. The selection stays. |
int32_t wgtDropdownGetTopIndex(w) |
The first item the list shows (where it was scrolled to). |
4.10.3. API Struct (wgtRegisterApi "dropdown")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtDropdown |
setItems |
wgtDropdownSetItems |
getSelected |
wgtDropdownGetSelected |
setSelected |
wgtDropdownSetSelected |
addItem |
wgtDropdownAddItem |
removeItem |
wgtDropdownRemoveItem |
clear |
wgtDropdownClear |
getItem |
wgtDropdownGetItem |
getItemCount |
wgtDropdownGetItemCount |
insertItem |
wgtDropdownInsertItem |
setItem |
wgtDropdownSetItem |
getItemData |
wgtDropdownGetItemData |
setItemData |
wgtDropdownSetItemData |
getNewIndex |
wgtDropdownGetNewIndex |
getSorted |
wgtDropdownGetSorted |
setSorted |
wgtDropdownSetSorted |
getTopIndex |
wgtDropdownGetTopIndex |
setTopIndex |
wgtDropdownSetTopIndex |
4.10.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
ListIndex |
Integer |
Read/Write |
Index of the currently selected item (-1 if none); checked: -1 to the last item, any other refused (error 380 in BASIC). |
NewIndex |
Integer |
Read |
The item added last (-1: none since the last removal). |
Sorted |
Boolean |
Read/Write |
Keep the list in order (wgtDropdownSetSorted). |
TopIndex |
Integer |
Read/Write |
The first item the list shows (wgtDropdownSetTopIndex); checked: 0 to the last item (0 on an empty list), any other refused (error 380 in BASIC). |
4.10.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddItem text$ [, index%] |
Append an item to the drop-down list, or insert it before item index% (WGT_SIG_STR and WGT_SIG_CHK_STR_INT). |
Clear |
Remove all items. |
ItemData(index%) [= n] |
An indexed property (WGT_SIG_IDX_GET_INT and WGT_SIG_IDX_SET_INT): the item’s number. |
List(index%) [= text$] |
Return the text of the item at the given index; assigned (WGT_SIG_IDX_SET_STR), the item’s new text. |
ListCount() |
Return the total number of items. |
RemoveItem index% |
Remove the item at the given index (WGT_SIG_CHK_INT). The selection stays on the same item; removing the selected item leaves no selection. |
SetItems items$ |
Replace all the items at once from a "|"-separated list ("Red|Green|Blue"; every "|" separates two items, "" empties the list). Nothing is selected afterwards. |
4.10.6. Events
| Callback | Description |
|---|---|
onChange |
Fires when the user’s pick changed the selected item. |
onClick |
Fires for every pick, after onChange: a row of the open list (even the selected one), another item taken with the keys as the list closes, the keys or a wheel notch on the closed box, as for Visual Basic’s drop-down list ComboBox. The press that opens the list fires none. |
DropDown |
The widget’s own event (wgtFireEvent, no arguments), as the list is about to open: a press on the box, F4, Alt+Down, Alt+Up, or the access key. |
4.11. HelpView
One topic of a compiled help file, shown the way DVX Help shows it — DVX Help itself uses this widget. Headings (three levels), word-wrapped paragraphs and list items, notes (info, tip, and warning), code blocks and tables (preformatted), pictures (left, centered, or right), horizontal rules and links, in a scrolling pane, in the theme’s colors. Text re-wraps when the widget changes width.
Links take the keyboard focus (Tab) and are followed with a click, Enter, or Space: the widget keeps the link’s target topic ID (wgtHelpViewGetLinkTarget) and calls the link callback with it. The widget does not change topic by itself; the callback usually finds the topic (hlpFileFindTopic) and shows it, which may rebuild the pane from inside the link’s own handler. Everything a topic shows is copied when it is shown, so the help file may be closed afterwards.
The help file is read with the help file library (hlpfile/hlpFile.h).
Header: include/widget/helpView/helpView.h in the SDK (#include "helpView/helpView.h")
BASIC name: HelpPane (see the HelpPane control in the BASIC reference)
Depends on: hlpfile.lib
4.11.1. Creation
HlpFileT *file = hlpFileOpen("MYAPP.HLP");
WidgetT *view = wgtHelpView(parent);
view->weight = WGT_WEIGHT_FILL;
wgtHelpViewSetLinkCallback(view, onLink);
wgtHelpViewShowTopic(view, file, hlpFileStartTopic(file, NULL));
static void onLink(WidgetT *w, const char *target) {
wgtHelpViewShowTopic(w, file, hlpFileFindTopic(file, target));
}
4.11.2. Macros
| Macro | Description |
|---|---|
wgtHelpView(parent) |
Create an empty help view. |
wgtHelpViewShowTopic(w, file, topic) |
Show topic (0 .. hlpFileTopicCount - 1) of an open help file, scrolled to the top. A NULL file or a topic out of range shows nothing. |
wgtHelpViewClear(w) |
Show nothing. |
wgtHelpViewGetTopic(w) |
The topic shown, -1 for none. |
wgtHelpViewGetLinkTarget(w) |
The target topic ID of the last link followed ("" before any). |
wgtHelpViewSetLinkCallback(w, fn) |
Call fn(w, target) when a link is followed. Signature: void (*fn)(WidgetT *w, const char *target); target is valid during the call. After it (unless it rebuilt the pane), the HelpView fires its own event LinkClick (Topic As String) with wgtFireEvent, which reaches the widget’s onEvent (BASIC: CtrlName_LinkClick). |
4.12. Image
Displays a bitmap image. Can be created from raw pixel data or loaded from a file on disk (BMP/PNG/etc. via dvxLoadImage). Supports optional scaling down to fit the widget and transparent color keys for chroma-key style masking (also when scaled). A disabled image is drawn grayscale; its transparent color key still applies. When the screen changes to another color depth (dvxChangeVideoMode) the picture and its key color are converted to the new format (out of memory, the picture goes and Picture reads "").
Header: include/widget/image/image.h in the SDK (#include "image/image.h")
4.12.1. Creation
WidgetT *img = wgtImageFromFile(parent, "logo.bmp");
// or from raw pixels:
// WidgetT *img = wgtImage(parent, pixelData, w, h, pitch);
4.12.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtImage(parent, data, w, h, pitch) |
Create from raw pixel data (in display’s native format). |
WidgetT *wgtImageFromFile(parent, path) |
Create by loading an image file. |
void wgtImageSetData(w, data, imgW, imgH, pitch) |
Replace the displayed image with new raw pixel data. |
void wgtImageLoadFile(w, path) |
Replace by loading a new file. Static but exposed via the API struct. |
bool wgtImageLoadData(w, data, len, name) |
Replace with the picture in len bytes of an image file (as dvxLoadImageFromMemory reads them); Picture then reads name (NULL: ""). False (the image unchanged) when they are not a picture. |
void wgtImageSetTransparent(w, hasTransparency, keyColor) |
Set chroma-key color (packed, in the display format). Pixels matching keyColor are not drawn. |
void wgtImageSetStretch(w, stretch) |
Stretch on or off (the BASIC Stretch property): an image larger than the widget is scaled down to fit. The widget relays out. |
4.12.3. API Struct (wgtRegisterApi "image")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtImage |
fromFile |
wgtImageFromFile |
setData |
wgtImageSetData |
loadFile |
wgtImageLoadFile |
setTransparent |
wgtImageSetTransparent |
loadData |
wgtImageLoadData |
setStretch |
wgtImageSetStretch |
4.12.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Picture |
String |
Read/Write |
Setting writes a file path (loads image). Reading returns the path of the loaded file (also set by wgtImageFromFile), or the name wgtImageLoadData was given; in BASIC the path comes as a Picture object, which stands for the path where a value is needed (see LOADPICTURE); wgtImageSetData clears it. Setting "" clears the image and the path; a file that cannot be loaded leaves both unchanged. |
Stretch |
Boolean |
Read/Write |
When true, an image larger than the widget is scaled down to fit (aspect preserved, nearest neighbor); a smaller image stays at natural size, and the widget asks for no minimum size of its own. When false, shown at natural size. Changing it relayouts the widget (wgtImageSetStretch). |
ImageWidth |
Integer |
Read-only |
Width of the currently loaded image in pixels. |
ImageHeight |
Integer |
Read-only |
Height of the currently loaded image in pixels. |
MaskColor |
Integer |
Read/Write |
The transparent color as a BASIC color (&HBBGGRR), converted with wgtImageSetTransparent. |
UseMaskColor |
Boolean |
Read/Write |
Whether pixels of MaskColor are left out (wgtImageSetTransparent’s hasTransparency). |
4.12.5. Methods
| Method | Description |
|---|---|
SetPictureData(bytes$[, name$]) |
WGT_METHOD_SET_PICTURE_DATA (WGT_SIG_DYNAMIC): wgtImageLoadData(bytes, length, name). Returns True when the bytes are a picture. |
Setting Picture loads a new image; the BASIC form runtime shows a LOADPICTUREDATA picture through SetPictureData.
4.13. ImageButton
A clickable button that displays an image instead of text. Has the same press/release visual feedback and focus handling as a regular Button. Can be created from raw pixel data or loaded from an image file. Typically used to populate a Toolbar.
As an Image does, it takes a transparent key color (its pixels of that color show the button face) and Stretch (a picture larger than the inside of the bevel is scaled down to fit it, aspect kept, and the button asks only for its bevel as its minimum size); a disabled button draws its picture grayscale, the key color still transparent. When the screen changes to another color depth (dvxChangeVideoMode) the picture and its key color are converted to the new format (out of memory, the picture goes and Picture reads "").
Header: include/widget/imageButton/imgBtn.h in the SDK (#include "imageButton/imgBtn.h")
4.13.1. Creation
WidgetT *btn = wgtImageButtonFromFile(parent, "icons/save.bmp");
btn->onClick = onSaveClicked;
4.13.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtImageButton(parent, data, w, h, pitch) |
Create from raw pixel data (in display’s native format). |
WidgetT *wgtImageButtonFromFile(parent, path) |
Create by loading an image file. |
void wgtImageButtonSetData(w, data, imgW, imgH, pitch) |
Replace the image with new raw pixel data. |
void wgtImageButtonLoadFile(w, path) |
Replace the image by loading a new file. |
bool wgtImageButtonLoadData(w, data, len, name) |
Replace the image with the picture in len bytes of an image file (as dvxLoadImageFromMemory reads them); Picture then reads name (NULL: ""). False (the image unchanged) when they are not a picture. |
void wgtImageButtonSetTransparent(w, hasTransparency, keyColor) |
Set the transparent key color (packed, in the display format): with hasTransparency, the picture’s pixels of keyColor show the button face. BASIC MaskColor and UseMaskColor. |
void wgtImageButtonSetStretch(w, stretch) |
Stretch on or off: a picture larger than the inside of the bevel is scaled down to fit it. The widget relays out. BASIC Stretch. |
4.13.3. API Struct (wgtRegisterApi "imagebutton")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtImageButton |
fromFile |
wgtImageButtonFromFile |
setData |
wgtImageButtonSetData |
loadFile |
wgtImageButtonLoadFile |
loadData |
wgtImageButtonLoadData |
setTransparent |
wgtImageButtonSetTransparent |
setStretch |
wgtImageButtonSetStretch |
4.13.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Picture |
String |
Read/Write |
Setting writes a file path (loads image). Reading returns the path of the loaded file (also set by wgtImageButtonFromFile), or the name wgtImageButtonLoadData was given; in BASIC the path comes as a Picture object, which stands for the path where a value is needed (see LOADPICTURE); wgtImageButtonSetData clears it. Setting "" clears the image and the path; a file that cannot be loaded leaves both unchanged. |
ImageWidth |
Integer |
Read-only |
Width of the currently loaded image in pixels. |
ImageHeight |
Integer |
Read-only |
Height of the currently loaded image in pixels. |
MaskColor |
Integer |
Read/Write |
The transparent color as a BASIC color (&HBBGGRR), converted with wgtImageButtonSetTransparent. |
Stretch |
Boolean |
Read/Write |
When true, a picture larger than the inside of the bevel is scaled down to fit it (aspect preserved, nearest neighbor); the button’s minimum size is its bevel alone. Changing it relayouts the widget (wgtImageButtonSetStretch). |
UseMaskColor |
Boolean |
Read/Write |
Whether pixels of MaskColor show the button face (wgtImageButtonSetTransparent’s hasTransparency). |
4.13.5. Methods
| Method | Description |
|---|---|
SetPictureData(bytes$[, name$]) |
WGT_METHOD_SET_PICTURE_DATA (WGT_SIG_DYNAMIC): wgtImageButtonLoadData(bytes, length, name). Returns True when the bytes are a picture. |
Setting Picture loads a new image; the BASIC form runtime shows a LOADPICTUREDATA picture through SetPictureData.
4.14. Label
A static text label. Does not accept keyboard focus directly, but supports accelerator keys that forward focus to the next focusable sibling (WCLASS_FOCUS_FORWARD). Useful for describing other widgets. Supports left, center, and right text alignment. The label fills its rectangle before drawing: with its own bgColor if set, else the nearest ancestor’s bgColor, else the face of a Toolbar it sits in, else the scheme’s content background.
Header: include/widget/label/label.h in the SDK (#include "label/label.h")
4.14.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtLabel(parent, text) |
Create a text label. |
void wgtLabelSetAlign(w, align) |
Set the text alignment (AlignStartE = left, AlignCenterE = center, AlignEndE = right) and repaint. Out-of-range values are ignored. |
WidgetAlignE wgtLabelGetAlign(w) |
Get the current text alignment (AlignStartE for a widget that is not a label). |
void wgtLabelSetWordWrap(w, wrap) |
Wrap the text at the label’s width hint (minW) and make the label as tall as its lines (true), or keep it one line as wide as its text (false, the default). Without a width hint a wrapping label stays one line. Lays the window out again. |
bool wgtLabelGetWordWrap(w) |
Whether the label wraps its text. |
4.14.3. API Struct (wgtRegisterApi "label")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtLabel |
setAlign |
wgtLabelSetAlign |
setWordWrap |
wgtLabelSetWordWrap |
getAlign |
wgtLabelGetAlign |
getWordWrap |
wgtLabelGetWordWrap |
4.14.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Alignment |
Enum (Left, Right, Center) |
Read/Write |
Text alignment within the label, in Visual Basic’s numbers (Left 0, Right 1, Center 2: mapped to and from WidgetAlignE); a number past them refused (error 380 in BASIC). |
WordWrap |
Boolean |
Read/Write |
wgtLabelSetWordWrap / wgtLabelGetWordWrap: the text wraps at the label’s Width (minW). |
Label text is managed via the standard wgtSetText() / wgtGetText() interface. BASIC code uses the generic "Caption" or "Text" property. Place an '&' before a character in the caption to mark an accelerator key.
4.15. ListBox
A scrollable list of text items. Supports single and multi-select modes (Visual Basic’s: extended, where Shift-click selects a range and Ctrl-click toggles, and simple, where a click toggles), a sorted list (Visual Basic’s Sorted), a check box before each item (Visual Basic’s Style Checkbox), drag-to-reorder, mouse wheel scroll (the view only: the selection stays, as in Visual Basic), and keyboard navigation (Up/Down/PgUp/PgDn/Home/End, and type-ahead on printable keys: widgetTypeAheadFind, where keys typed quickly make up a prefix). A horizontal scrollbar appears when the box is laid out narrower than its widest item (a maxW below it); it and Left/Right scroll a character at a time. The bars follow widgetScrollbarNeeds. Depends on the "listhelp" helper library (declared in listbox.dep).
Items can be set from a caller-owned array (wgtListBoxSetItems, which keeps a pointer to it) or managed with AddItem/InsertItem/RemoveItem/SetItem/Clear. Those on a list set from an array first copy that array, so they change the list without modifying the caller’s; drag-to-reorder also works on the copy. Each item has a number of the caller’s (Visual Basic’s ItemData: 0 until set) that moves with it through inserts, removals, and drags, and the list remembers the item added last (Visual Basic’s NewIndex: -1 after a removal, Clear, or SetItems). A sorted list (wgtListBoxSetSorted) puts an added item in its place (listItemsAddIndex: case ignored, after the ones that sort the same), an inserted one at its index, and sorts its own copy of a caller’s array.
Header: include/widget/listBox/listBox.h in the SDK (#include "listBox/listBox.h")
4.15.1. Creation
WidgetT *lb = wgtListBox(parent);
wgtListBoxAddItem(lb, "Alpha");
wgtListBoxAddItem(lb, "Beta");
wgtListBoxAddItem(lb, "Gamma");
4.15.2. API Functions
- WidgetT *wgtListBox(parent)
-
Create a list box.
- void wgtListBoxSetItems(w, items, count)
-
Set items from a caller-owned const char ** array.
- int32_t wgtListBoxGetSelected(w)
-
Get the primary selected index (-1 if none).
- void wgtListBoxSetSelected(w, idx)
-
Set the selected index. Scrolls the item into view.
- void wgtListBoxSetMultiSelect(w, multi)
-
Enable or disable multi-select mode (true: LISTBOX_MULTI_EXTENDED).
- void wgtListBoxSetMultiSelectMode(w, mode)
-
LISTBOX_MULTI_NONE, LISTBOX_MULTI_SIMPLE (a click selects or deselects its item, Shift makes no range), or LISTBOX_MULTI_EXTENDED (Visual Basic’s MultiSelect 0, 1, 2; any other number is none). The selection starts again from the current item.
- int32_t wgtListBoxGetMultiSelectMode(w)
-
The LISTBOX_MULTI_* mode.
- void wgtListBoxSetSorted(w, sorted)
-
Keep the items in order (Visual Basic’s Sorted): true sorts the items now, each with its number and selection.
- bool wgtListBoxGetSorted(w)
-
Whether the list is sorted.
- void wgtListBoxSetTopIndex(w, idx)
-
Scroll item idx to the top, as far as the list scrolls (Visual Basic’s TopIndex); the selection stays.
- int32_t wgtListBoxGetTopIndex(w)
-
The first item shown.
- void wgtListBoxSetStyle(w, style)
-
LISTBOX_STYLE_STANDARD or LISTBOX_STYLE_CHECKBOX (Visual Basic’s Style): a check box before each item, whose check mark is the item’s selection (the functions below), every item unchecked; the current item (wgtListBoxGetSelected) is a single selection whatever the MultiSelect mode, which is kept for Standard. A click on an item’s box, or on the current item, and Space check or uncheck it, each firing the "ItemCheck" event (onEvent, the item’s index) before onClick. Rows are at least the box’s height.
- int32_t wgtListBoxGetStyle(w)
-
The LISTBOX_STYLE_* style.
- bool wgtListBoxIsItemSelected(w, idx)
-
Returns true if the item is selected (multi-select mode) or checked (Style Checkbox).
- void wgtListBoxSetItemSelected(w, idx, selected)
-
Select or deselect a specific item (multi-select mode), or check or uncheck it (Style Checkbox), firing nothing.
- void wgtListBoxSelectAll(w)
-
Select every item (multi-select mode), or check every item (Style Checkbox).
- void wgtListBoxClearSelection(w)
-
Deselect all items (Style Checkbox: uncheck them).
- void wgtListBoxSetReorderable(w, r)
-
Enable drag-to-reorder of items.
- void wgtListBoxAddItem(w, text)
-
Append an owned item (strdup’d); a sorted list puts it in its place.
- bool wgtListBoxInsertItem(w, text, idx)
-
Insert an item before item idx (0 to the count; the count appends). The items from idx on move down with their selection; the new item is the NewIndex. False, adding nothing, when idx is out of range.
- bool wgtListBoxRemoveItem(w, idx)
-
Remove the item at idx. Items after it keep their selection; removing the current item leaves no current item. False when there is no item idx.
- bool wgtListBoxSetItem(w, idx, text)
-
Give item idx new text, keeping its selection and number. False when there is no item idx.
- int32_t wgtListBoxGetItemData(w, idx)
-
The number of item idx (0 when none was set or there is no such item).
- bool wgtListBoxSetItemData(w, idx, value)
-
Set the number of item idx. False when there is no item idx.
- int32_t wgtListBoxGetNewIndex(w)
-
The item added last, -1 when an item was removed since or none was added.
- void wgtListBoxClear(w)
-
Remove all owned items.
- const char *wgtListBoxGetItem(w, idx)
-
Get the text of an item by index.
- int32_t wgtListBoxGetItemCount(w)
-
Get the total number of items.
4.15.3. API Struct (wgtRegisterApi "listbox")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtListBox |
setItems |
wgtListBoxSetItems |
getSelected |
wgtListBoxGetSelected |
setSelected |
wgtListBoxSetSelected |
setMultiSelect |
wgtListBoxSetMultiSelect |
isItemSelected |
wgtListBoxIsItemSelected |
setItemSelected |
wgtListBoxSetItemSelected |
selectAll |
wgtListBoxSelectAll |
clearSelection |
wgtListBoxClearSelection |
setReorderable |
wgtListBoxSetReorderable |
addItem |
wgtListBoxAddItem |
removeItem |
wgtListBoxRemoveItem |
clear |
wgtListBoxClear |
getItem |
wgtListBoxGetItem |
getItemCount |
wgtListBoxGetItemCount |
insertItem |
wgtListBoxInsertItem |
setItem |
wgtListBoxSetItem |
getItemData |
wgtListBoxGetItemData |
setItemData |
wgtListBoxSetItemData |
getNewIndex |
wgtListBoxGetNewIndex |
getMultiSelectMode |
wgtListBoxGetMultiSelectMode |
setMultiSelectMode |
wgtListBoxSetMultiSelectMode |
getSorted |
wgtListBoxGetSorted |
setSorted |
wgtListBoxSetSorted |
getTopIndex |
wgtListBoxGetTopIndex |
setTopIndex |
wgtListBoxSetTopIndex |
getStyle |
wgtListBoxGetStyle |
setStyle |
wgtListBoxSetStyle |
4.15.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
ListIndex |
Integer |
Read/Write |
Index of the currently selected item; checked (WgtPropDescT checked): -1 to the last item, any other refused (error 380 in BASIC). |
MultiSelect |
Enum |
Read/Write |
None, Simple, or Extended (wgtListBoxSetMultiSelectMode). |
NewIndex |
Integer |
Read |
The item added last (-1: none since the last removal). |
Sorted |
Boolean |
Read/Write |
Keep the items in order (wgtListBoxSetSorted). |
Style |
Enum |
Read/Write |
Standard or Checkbox (wgtListBoxSetStyle). |
TopIndex |
Integer |
Read/Write |
The first item shown (wgtListBoxSetTopIndex); checked: 0 to the last item (0 on an empty list), any other refused. |
4.15.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddItem text$ [, index%] |
Append an item, or insert it before item index% (WGT_SIG_STR and WGT_SIG_CHK_STR_INT, one method of each argument count). |
Clear |
Remove all items. |
ClearSelection |
Deselect all items. |
IsItemSelected(index%) |
Returns True if the item is selected (Selected’s read, WGT_SIG_IDX_GET_BOOL). |
ItemData(index%) [= n] |
An indexed property (WGT_SIG_IDX_GET_INT and WGT_SIG_IDX_SET_INT): the item’s number. |
List(index%) [= text$] |
Return the text of the item at the given index; assigned (WGT_SIG_IDX_SET_STR), the item’s new text. |
ListCount() |
Return the total number of items. |
RemoveItem index% |
Remove the item at the given index (WGT_SIG_CHK_INT). Items after it keep their selection; removing the selected item leaves no selection. |
SelectAll |
Select all items. |
Selected(index%) [= b] |
An indexed property (WGT_SIG_IDX_GET_BOOL and WGT_SIG_IDX_SET_BOOL): whether the item is selected (Style Checkbox: checked); assigned, a multi-select list’s item alone, a Checkbox list’s check mark (firing ItemCheck when it changes), another list’s selection (True selects it, False deselects it when it is the selected one). |
SetItemSelected index%, sel |
Selected’s assignment as a method (WGT_SIG_ITEM_INT_BOOL), firing no ItemCheck: an index there is no item for is refused (error 381 in BASIC). |
SetItems spec$ |
Bulk-load items from a pipe-delimited string (e.g. "Red|Green|Blue"); replaces existing items. Every "|" separates two items ("a|" is "a" and an empty item); "" empties the list. |
SetMultiSelect multi |
Enable or disable multi-select mode. |
SetReorderable r |
Enable or disable drag-to-reorder. |
4.15.6. Events
| Callback | Description |
|---|---|
onClick |
Fires when the user picks an item, after onChange: a click on an item, even the one already selected (after onMouseDown), a selection moved with the keys, or Space in multi-select mode. A click on the scroll bars or below the items fires none. |
onDblClick |
Fires when an item is double-clicked (the second click fires no onClick; onChange first when it picked another item). A double click on a scroll bar fires none (the list’s chrome: widgetPressOnChrome). |
onChange |
Fires when the user’s pick changed the selection (not for a click on the item already selected), and after a drag-reorder. |
ItemCheck |
A custom event (onEvent, one argument: the item’s index): a Checkbox list’s check mark changed by a click or Space (between onChange and onClick), or by the BASIC Selected(i) assignment. |
4.16. ListView
A multi-column list with sortable headers. The mouse wheel scrolls the view, the selection staying, as in Visual Basic. Supports single and multi-selection, column alignment, header click sorting, column resizing (drag a header border; double-click it to fit the contents), and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell). wgtListViewSetColumns keeps a pointer to the caller’s column array (and its titles), and wgtListViewSetData a pointer to the caller’s cell array (and its strings): both must stay valid while the list uses them, so make them static or allocate them, never locals of a function that returns. AddItem, RemoveRow, Clear, SetCell, and drag-to-reorder work on a copy of the cells the widget makes first, so the caller’s array is never modified.
Sorting and drag-to-reorder are exclusive: enabling reorder clears the sort, and while reorder is enabled wgtListViewSetSort and header clicks do not sort. A column width set by dragging or double-clicking a header border is kept when the data changes, until new columns are set. A wgtPercent column width is a percentage of the list’s width inside its border, resolved again whenever that width changes.
A column sorts numerically when both cells are numbers (digits with a sign, a decimal point, or an exponent; blanks around them are ignored), and numbers come before the cells that are not; the others sort as text with case ignored. Equal cells keep their data order.
Header: include/widget/listView/listView.h in the SDK (#include "listView/listView.h")
4.16.1. Creation
// static: the list keeps these pointers
static const ListViewColT sCols[] = {
{ "Name", wgtChars(20), ListViewAlignLeftE },
{ "Size", wgtChars(10), ListViewAlignRightE }
};
static const char *sCells[] = { "file.txt", "1234", "readme.md", "5678" };
WidgetT *lv = wgtListView(parent);
wgtListViewSetColumns(lv, sCols, 2);
wgtListViewSetData(lv, sCells, 2);
4.16.2. Column Definition
typedef struct {
const char *title;
int32_t width; // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
ListViewAlignE align; // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
} ListViewColT;
4.16.3. Sort Direction
typedef enum {
ListViewSortNoneE,
ListViewSortAscE,
ListViewSortDescE
} ListViewSortE;
4.16.4. Macros
| Macro | Description |
|---|---|
wgtListView(parent) |
Create a list view. |
wgtListViewSetColumns(w, cols, count) |
Define columns from an array of ListViewColT. The list keeps the pointer: cols must outlive it (or the next SetColumns). |
wgtListViewSetData(w, cellData, rowCount) |
Set row data. cellData is a flat const char ** array of size rowCount * colCount. The list keeps the pointer (until it copies the cells for an AddItem, RemoveRow, Clear, SetCell, or reorder): the array and its strings must outlive it. |
wgtListViewGetSelected(w) |
Get the index of the selected row (-1 if none). |
wgtListViewSetSelected(w, idx) |
Set the selected row by index (outside the list = none) and scroll it into view. |
wgtListViewSetSort(w, col, dir) |
Set the sort column and direction. A column outside the defined columns, or ListViewSortNoneE, clears the sort. Ignored while reorder is enabled. |
wgtListViewGetSortCol(w) |
The column the list is sorted by (-1 when unsorted): the last wgtListViewSetSort or header click. |
wgtListViewGetSortDir(w) |
The sort direction (ListViewSortNoneE when unsorted). |
wgtListViewSetHeaderClickCallback(w, cb) |
Set a callback for header clicks. Signature: void (*cb)(WidgetT *w, int32_t col, ListViewSortE dir). After it, the ListView fires its own event ColumnClick (Column As Integer, 0-based) with wgtFireEvent, which reaches the widget’s onEvent (BASIC: CtrlName_ColumnClick). |
wgtListViewSetMultiSelect(w, multi) |
Enable or disable multi-selection. |
wgtListViewGetMultiSelect(w) |
Whether multi-selection is on. |
wgtListViewIsItemSelected(w, idx) |
Check if a specific row is selected. |
wgtListViewSetItemSelected(w, idx, selected) |
Select or deselect a specific row. |
wgtListViewSelectAll(w) |
Select all rows. |
wgtListViewClearSelection(w) |
Deselect all rows. |
wgtListViewSetReorderable(w, reorderable) |
Enable drag-to-reorder of rows. |
wgtListViewAddItem(w, text) |
Add a row with text in its first column (the list keeps its own copy of the cells from then on). |
wgtListViewInsertItem(w, text, row) |
Insert a row before data row row (0 to the row count; the count appends), text in its first column: the rows from row on move down with their selection, and a sorted list shows it in its place. False, adding nothing, without columns or with row out of range. |
wgtListViewRemoveRow(w, row) |
Remove a data row. False when there is no row row. |
wgtListViewClear(w) |
Remove all rows. |
wgtListViewGetCell(w, row, col) |
The text of a cell ("" outside the list). |
wgtListViewSetCell(w, row, col, text) |
Set the text of a cell. |
wgtListViewGetRowCount(w) |
The number of rows. |
4.16.5. Events
- onClick
-
Fires when the user picks a row, after onChange and ItemClick: a click on a row, even the one already selected (after onMouseDown), a selection moved with the keys, or Space in multi-select mode. A click below the rows fires onClick alone, as Visual Basic’s ListView raises Click there; a click on a column header or the scroll bars fires none.
- ItemClick
-
The widget’s own event (wgtFireEvent, Item As Integer: the data row, as wgtListViewGetSelected numbers it), between onChange and onClick for every row pick.
- onDblClick
-
Fires on the second press of a double click on the rows or below them (the second press fires no onClick): on a row onChange and ItemClick come first when it picked another row. A double click on a column header (which sorts twice), a header border (which fits the column), or a scroll bar fires neither onClick nor onDblClick, and no press there fires onMouseDown or onMouseUp, as in Visual Basic; a press there never counts as the first of a double click. Enter fires it too, when there is a current row. A handler that should act only on a row checks wgtListViewGetSelected.
- onChange
-
Fires when the user’s pick changed the selection (not for a click on the row already selected), and after a drag-reorder.
4.16.6. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
ListIndex |
Integer |
Read/Write |
Index of the currently selected row; checked: -1 to the last row, any other refused (error 380 in BASIC). |
MultiSelect |
Boolean |
Read/Write |
Multi-selection (wgtListViewSetMultiSelect, wgtListViewGetMultiSelect). |
SortColumn |
Integer |
Read/Write |
The sort column (-1 when unsorted). Setting it sorts by that column in the current order (ascending when unsorted); -1 unsorts; checked: a column the list does not have is refused. |
SortOrder |
Integer |
Read/Write |
The sort order (0 none, 1 ascending, 2 descending). Setting it re-sorts the current column; an unsorted list stays unsorted; checked: another number is refused. |
4.16.7. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddItem text$ [, index%] |
Add a row (sets first column text), or insert it before data row index% (WGT_SIG_STR and WGT_SIG_CHK_STR_INT). |
Clear |
Remove all rows. |
ClearSelection |
Deselect all rows. |
GetCell(row%, col%) |
Returns the text of a cell (WGT_SIG_IDX2_GET_STR: a cell there is none for is refused, error 381 in BASIC). |
IsItemSelected(index%) |
Check if a specific row is selected (Selected’s read, WGT_SIG_IDX_GET_BOOL). |
ListCount() |
Returns the number of rows (the same as RowCount). |
RemoveItem index% |
Remove a row by index (WGT_SIG_CHK_INT). Rows after it keep their selection; removing the selected row leaves no selection. |
RowCount() |
Returns the number of rows. |
SelectAll |
Select all rows. |
Selected(index%) [= b] |
An indexed property (WGT_SIG_IDX_GET_BOOL and WGT_SIG_IDX_SET_BOOL): whether the data row is selected; assigned, a multi-select list’s row alone, another list’s selection. |
SelectedRows() |
Returns the selected rows' numbers separated by spaces ("" when none). |
SetCell row%, col%, text$ |
Set the text of a cell (WGT_SIG_ITEM_INT_INT_STR: a cell there is none for is refused, error 381 in BASIC). |
SetColumns spec$ |
Define columns from a pipe-delimited spec string ("Name,Width|Name,Width"). |
SetItemSelected idx%, sel |
Selected’s assignment as a method (WGT_SIG_ITEM_INT_BOOL): a row there is none for is refused (error 381 in BASIC). |
SetMultiSelect multi |
Enable or disable multi-selection. |
SetReorderable reorderable |
Enable or disable drag-to-reorder. |
SetRows text$ |
Replace all rows at once: rows separated by CHR$(10), cells by CHR$(9). |
SetSort col%, dir% |
Set the sort column and direction (0=none, 1=ascending, 2=descending). An invalid column or direction clears the sort; ignored while reorder is enabled. |
4.17. ProgressBar
A visual indicator of progress, displayed as a filled bar. Supports both horizontal and vertical orientations. Value ranges from 0 to 100.
Header: include/widget/progressBar/progress.h in the SDK (#include "progressBar/progress.h")
4.17.1. Creation
| Macro | Description |
|---|---|
wgtProgressBar(parent) |
Create a horizontal progress bar. |
wgtProgressBarV(parent) |
Create a vertical progress bar. |
4.17.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtProgressBar(parent) |
Create a horizontal progress bar. |
WidgetT *wgtProgressBarV(parent) |
Create a vertical progress bar. |
void wgtProgressBarSetValue(w, val) |
Set the progress value (0-100). Clamped to 0..maxValue. |
int32_t wgtProgressBarGetValue(w) |
Get the current progress value. |
void wgtProgressBarSetVertical(w, v) |
Make the bar vertical (true) or horizontal (false); the layout is redone. |
bool wgtProgressBarGetVertical(w) |
True when the bar is vertical. |
4.17.3. API Struct (wgtRegisterApi "progressbar")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtProgressBar |
createV |
wgtProgressBarV |
setValue |
wgtProgressBarSetValue |
getValue |
wgtProgressBarGetValue |
setVertical |
wgtProgressBarSetVertical |
getVertical |
wgtProgressBarGetVertical |
4.18. Radio Button
A mutually exclusive selection control. Radio buttons are normally placed inside a radio group container, which holds the selected index. Radio buttons placed directly in any other container (as BASIC forms do) form a group with their radio siblings, each button keeping its own selected state. Only one radio button within a group can be selected at a time. A button’s index is its position among the radio buttons of its container, so it stays correct when buttons are added or destroyed. A new radio group holds index 0, so its first button starts selected; radio buttons placed in any other container start with none selected.
Header: include/widget/radio/radio.h in the SDK (#include "radio/radio.h")
4.18.1. Creation
WidgetT *grp = wgtRadioGroup(parent);
WidgetT *r1 = wgtRadio(grp, "Option A");
WidgetT *r2 = wgtRadio(grp, "Option B");
4.18.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtRadioGroup(parent) |
Create a radio group container. |
WidgetT *wgtRadio(parent, text) |
Create a radio button inside a group. |
void wgtRadioGroupSetSelected(group, idx) |
Select the radio button at index idx of the group; a negative idx selects none. An index past the group’s buttons selects none now, and the button added at that index later. |
int32_t wgtRadioGroupGetSelected(group) |
Index of the selected radio button among group’s radio children (group may be a RadioGroup or any container), or -1 when no button is selected (an empty group, or an index past its buttons). |
int32_t wgtRadioGetIndex(w) |
Get the index of this radio button within its group. |
bool wgtRadioIsSelected(w) |
True when this radio button is the selected one. |
void wgtRadioSetSelected(w, selected) |
Select this button (clearing its siblings), or deselect it leaving none selected. Fires no event. |
wgtRadioGroupSetSelected and wgtRadioSetSelected repaint the affected buttons and do not fire onChange. Arrow-key navigation moves focus through the standard focus path, so the blur/focus callbacks fire.
A selection by the user fires onChange (on the group, or on a button with no group) and then the button’s onClick, from the mouse and the keyboard alike, as Visual Basic’s OptionButton gives Click for both. Choosing the button that is already selected changes nothing and fires neither (Visual Basic raises Click only when the button’s Value becomes True). A click is a press and a release over the button, as a button’s (WCLASS_PRESS_RELEASE, the widgetPressable helpers): it shows pressed (its inside darkened) while the mouse button is held and is selected at the release, after onMouseDown and onMouseUp; moving off before the release cancels it. The arrow keys select the button they move to at once; Space and the accelerator press the focused button, and the app loop releases it after the key’s dispatch (sKeyPressedBtn, WGT_METHOD_ON_DRAG_END). The key’s own onKeyDown and onKeyPress come first, and wgtKeyReplace(0) there cancels it.
4.18.3. API Struct (wgtRegisterApi "radio")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
group |
wgtRadioGroup |
create |
wgtRadio |
groupSetSelected |
wgtRadioGroupSetSelected |
getIndex |
wgtRadioGetIndex |
isSelected |
wgtRadioIsSelected |
setSelected |
wgtRadioSetSelected |
groupGetSelected |
wgtRadioGroupGetSelected |
4.18.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Value |
Boolean |
Read/Write |
True when this button is selected. Setting True selects it and clears its siblings; setting False deselects it. |
OptionIndex |
Integer |
Read-only |
Index of this radio button within its group. |
Caption is managed via the standard wgtSetText() / wgtGetText() interface (WCLASS_HAS_TEXT).
4.18.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
GetSelected() |
The index of the selected radio button of this button’s group, -1 when none (called on a group, wgtRadioGroupGetSelected). |
SetSelected idx% |
Select the radio button at index idx% within this button’s group (called on a group, within that group); -1 selects none (WGT_SIG_ITEM_INT: an index there is no button for is refused, error 381 in BASIC). |
4.18.6. Events
| Callback | Description |
|---|---|
onClick |
Fires on the radio button the user selected (mouse click, arrow key, Space, or accelerator), after onChange; not when it was already selected. |
onChange |
Fires when the user selects a button that was not selected: on the group, or on the button when it has no group. |
4.19. RichEdit
A text box for styled text: runs in fonts, sizes, styles, and colors, in paragraphs aligned left, centered, or right, edited with the keyboard and the mouse, with undo and redo, a clipboard that keeps styles between RichEdit controls, find, and RTF in and out. The document is a RichTextT of the richtext library (richtext/richText.h); a style’s family "" and size 0 are the widget’s own font (wgtSetFont, or its container’s) and RICHEDIT_COLOR_DEFAULT its fgColor, so such text follows the widget.
Each paragraph is laid out by a text flow of its own (dvxFlow.h): an edit lays out only the paragraphs it touched, and the paragraphs' tops are kept for binary searches from an offset or a row. The widget polls (WCLASS_NEEDS_POLL) and has a quick repaint (WGT_METHOD_QUICK_REPAINT): an edit that left every paragraph’s height alone, a caret or selection move, and the caret’s blink repaint only the rows they touched, painted straight into the window’s content buffer (widgetQuickPaintBegin); a change of height, a scroll, or a new width repaints the widget. Undo keeps for each edit what it replaced and the length it put in its place (alignment changes keep the old alignments); typed characters join one step; 100 steps are kept.
Depends on the "texthelp" (word boundaries, the caret blink time, scroll bar drags) and "richtext" libraries (declared in richedit.dep).
Header: include/widget/richEdit/richEdit.h in the SDK (#include "richEdit/richEdit.h")
4.19.1. Creation
WidgetT *re = wgtRichEdit(parent);
wgtSetText(re, "Dear friend,");
wgtRichEditSetSelStart(re, 0);
wgtRichEditSetSelLength(re, 4);
wgtRichEditSetSelStyle(re, FONT_STYLE_BOLD, FONT_STYLE_BOLD);
wgtRichEditSetSelColor(re, DVX_RGB(0, 0, 160));
4.19.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtRichEdit(parent) |
Create an empty rich edit box. |
const char *wgtRichEditGetRtf(w) |
The whole text as RTF (valid until the next call that returns RTF). |
void wgtRichEditSetRtf(w, rtf) |
Replace the whole text from RTF (plain text when it is not RTF); undo is emptied. |
const char *wgtRichEditGetSelRtf(w) |
The selection as RTF. |
void wgtRichEditSetSelRtf(w, rtf) |
Replace the selection from RTF. |
int32_t wgtRichEditGetSelStart(w) / SetSelStart |
Where the selection starts; setting it places the caret. |
int32_t wgtRichEditGetSelLength(w) / SetSelLength |
The selection’s length; setting it selects from SelStart. |
const char *wgtRichEditGetSelText(w) / SetSelText |
The selection’s text; setting it replaces the selection with plain text. |
const char *wgtRichEditGetSelFontName(w) |
The selection’s family (the widget’s own when it uses that). |
int32_t wgtRichEditGetSelFontSize(w) |
The selection’s pixel size (as opened: the nearest the family has). |
void wgtRichEditSetSelFont(w, family, size) |
The family (NULL: unchanged; "": the widget’s) and size (0: unchanged). |
uint32_t wgtRichEditGetSelStyle(w) |
The selection’s FONT_STYLE_* bits. |
void wgtRichEditSetSelStyle(w, style, mask) |
Make the bits in mask style’s. |
uint32_t wgtRichEditGetSelColor(w) / SetSelColor |
0x00RRGGBB or RICHEDIT_COLOR_DEFAULT. |
int32_t wgtRichEditGetSelAlign(w) / SetSelAlign |
FLOW_ALIGN_* of the selection’s paragraphs. |
bool wgtRichEditCanUndo(w) / CanRedo |
Whether there is a step to undo or redo. |
void wgtRichEditUndo(w) / Redo |
Undo or redo a step. |
void wgtRichEditCut(w) / Copy / Paste |
The clipboard (plain text there; the styled copy kept for a paste of the same text). |
void wgtRichEditSelectAll(w) |
Select everything. |
int32_t wgtRichEditFind(w, text, matchCase) |
Select the next match from the selection’s end, around past the end; its offset or -1. |
int32_t wgtRichEditLoadFile(w, path) |
Load RTF or plain text; 0 or -1. |
int32_t wgtRichEditSaveFile(w, path) |
Save RTF (path ending in .rtf) or plain text; 0 or -1. |
The style and alignment setters change the selection, or with none, the style typing uses next (alignment: the caret’s paragraph); each change is an undo step and fires Change. wgtGetText / wgtSetText are the plain text, a line per paragraph. RICHEDIT_EVT_SELCHANGE ("SelChange") is fired with wgtFireEvent when the selection or the caret moves.
4.19.3. API Struct (wgtRegisterApi "richedit")
The slots are the functions above in order: create, getRtf, setRtf, getSelRtf, setSelRtf, getSelStart, setSelStart, getSelLength, setSelLength, getSelText, setSelText, getSelFontName, getSelFontSize, setSelFont, getSelStyle, setSelStyle, getSelColor, setSelColor, getSelAlign, setSelAlign, canUndo, canRedo, undo, redo, cut, copy, paste, selectAll, find, loadFile, and saveFile.
4.19.4. BASIC Interface
Properties: TextRTF and SelRTF (wgtRichEditGetRtf / SetRtf, GetSelRtf / SetSelRtf), SelStart, SelLength, SelText, SelBold, SelItalic, SelUnderline, SelStrikethru (one FONT_STYLE_* bit of SetSelStyle each), SelColor (a BASIC color; -1 for ForeColor), SelFontName and SelFontSize (wgtRichEditSetSelFont with the other part left alone), SelAlignment (an ENUM in Visual Basic’s order, Left 0, Right 1, Center 2, mapped to and from FLOW_ALIGN_*), and the read-only CanUndo and CanRedo. SelStart, SelLength, and SelFontSize are checked (WgtPropDescT checked): below 0 (below 1 for the size) refused, error 380 in BASIC. Methods: Undo, Redo, Cut, Copy, Paste, SelectAll, Find (WGT_SIG_DYN_1_2: text$ and an optional matchCase, any case without it), LoadFile, and SaveFile. Event: SelChange; default event Change.
4.19.5. Methods Used
PAINT, CALC_MIN_SIZE (20 by 4 characters of its font, with border and scroll bar), ON_MOUSE, ON_KEY, ON_DRAG_UPDATE, ON_DRAG_END, ON_WHEEL, ON_FOCUS, ON_BLUR, POLL, QUICK_REPAINT, GET_TEXT, SET_TEXT, CLEAR_SELECTION, DESTROY. Flags: WCLASS_FOCUSABLE, WCLASS_NEEDS_POLL, WCLASS_SWALLOWS_ENTER (Enter starts a new paragraph, even in a dialog box).
4.20. RichLabel
Text in many fonts, styles, and colors, wrapped and aligned paragraph by paragraph. The text is built by calls: wgtRichLabelSetFont, wgtRichLabelSetStyle, and wgtRichLabelSetColor choose what the following wgtRichLabelAddText uses; wgtRichLabelAddLineBreak starts a new line and wgtRichLabelAddParagraph a new paragraph with its own alignment. Text starts in the widget’s own font (wgtSetFont, or its container’s). The widget is laid out at its width hint (minW, which BASIC’s Width sets), wrapping at spaces (a word too wide for a line breaks inside it); without one each paragraph is one line. Every line is as tall as the tallest font on it, its text standing on one baseline. Not focusable; drawn the same enabled or not. It fills its rectangle as a Label does: with the nearest explicit bgColor, else the content background. Built on the text flow in libdvx (dvxFlow.h).
Header: include/widget/richLabel/richLbl.h in the SDK (#include "richLabel/richLbl.h")
4.20.1. Creation
WidgetT *rl = wgtRichLabel(parent);
wgtRichLabelSetFont(rl, "DejaVu Serif", 18);
wgtRichLabelSetStyle(rl, FONT_STYLE_BOLD);
wgtRichLabelAddText(rl, "Chapter One");
wgtRichLabelAddParagraph(rl, FLOW_ALIGN_LEFT);
wgtRichLabelSetFont(rl, "", 0);
wgtRichLabelSetStyle(rl, 0);
wgtRichLabelAddText(rl, "It was a ");
wgtRichLabelSetColor(rl, DVX_RGB(160, 0, 0));
wgtRichLabelAddText(rl, "dark");
wgtRichLabelSetColor(rl, RICHLABEL_COLOR_DEFAULT);
wgtRichLabelAddText(rl, " and stormy night.");
4.20.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtRichLabel(parent) |
Create an empty rich label. |
void wgtRichLabelClear(w) |
Remove all text; the font, style, and color chosen go back to the widget’s. |
void wgtRichLabelSetFont(w, family, size) |
The font family and pixel size of the text added next ("" and 0: the widget’s own). |
void wgtRichLabelSetStyle(w, style) |
FONT_STYLE_BOLD, ITALIC, UNDERLINE, and STRIKE bits for the text added next. |
void wgtRichLabelSetColor(w, rgb) |
0x00RRGGBB color of the text added next; RICHLABEL_COLOR_DEFAULT: the widget’s fgColor (else the scheme’s). |
void wgtRichLabelAddText(w, text) |
Add text in the font, style, and color chosen. |
void wgtRichLabelAddLineBreak(w) |
Start a new line in the same paragraph. |
void wgtRichLabelAddParagraph(w, align) |
Start a new paragraph aligned FLOW_ALIGN_LEFT (0), FLOW_ALIGN_CENTER (1), or FLOW_ALIGN_RIGHT (2), as a Label’s alignment; others are ignored. |
Setting the font, style, or color changes only the text added afterwards.
4.20.3. API Struct (wgtRegisterApi "richlabel")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtRichLabel |
clear |
wgtRichLabelClear |
setFont |
wgtRichLabelSetFont |
setStyle |
wgtRichLabelSetStyle |
setColor |
wgtRichLabelSetColor |
addText |
wgtRichLabelAddText |
addLineBreak |
wgtRichLabelAddLineBreak |
addParagraph |
wgtRichLabelAddParagraph |
4.20.4. Methods (BASIC Interface)
| Method | Arguments | Description |
|---|---|---|
Clear |
(none) |
wgtRichLabelClear |
SetFont |
family, size |
wgtRichLabelSetFont |
SetStyle |
style |
wgtRichLabelSetStyle |
SetColor |
color |
A BASIC color (RGB()); -1 for ForeColor |
AddText |
text |
wgtRichLabelAddText |
AddLineBreak |
(none) |
wgtRichLabelAddLineBreak |
AddParagraph |
alignment |
wgtRichLabelAddParagraph |
4.21. ScrollPane
A scrollable container that provides vertical and/or horizontal scrollbars when its content exceeds the visible area. Its children stack top to bottom as in a VBox: each is as wide as the content (the pane’s width, or the widest child’s minimum width when that is wider), extra height goes to the children with a weight, and a child with a maxW is centered in the width it does not take (maxW and maxH percentages are of the content’s width and height, as a box’s are). A single VBox or HBox child holding the rest is the usual layout. A click on content that does not handle the mouse itself (a label, an image, or empty space) gives the scroll pane the keyboard focus, so the arrow and page keys scroll it.
Header: include/widget/scrollPane/scrlPane.h in the SDK (#include "scrollPane/scrlPane.h")
4.21.1. Creation
WidgetT *sp = wgtScrollPane(parent);
WidgetT *content = wgtVBox(sp);
// add children to content...
4.21.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtScrollPane(parent) |
Create a scroll pane container. |
void wgtScrollPaneScrollToChild(sp, child) |
Scroll so that the given child widget is visible. |
void wgtScrollPaneScrollToTop(w) |
Scroll back to the top-left of the content and re-lay out. |
void wgtScrollPaneSetNoBorder(w, noBorder) |
When true, removes the border around the scroll pane. |
int32_t wgtScrollPaneGetScrollTop(w) |
Vertical scroll position in pixels. |
void wgtScrollPaneSetScrollTop(w, pos) |
Set the vertical scroll position; the layout clamps it to the content. |
int32_t wgtScrollPaneGetScrollLeft(w) |
Horizontal scroll position in pixels. |
void wgtScrollPaneSetScrollLeft(w, pos) |
Set the horizontal scroll position; the layout clamps it to the content. |
Padding and spacing are the common WidgetT padding / spacing fields (WGT_GAP_DEFAULT, the default, is none); wgtSetPaddingPx / wgtSetSpacingPx set them in pixels, or as a size from wgtChars or wgtPercent (of the pane’s own width, out of the room it has to spare). A child’s minH in percent is of the content’s height, out of the room the content has to spare (see wgtsys.dhs, Percentages).
When the user moves the scroll position (scrollbar arrows and trough, dragging a thumb, the arrow, page, Home, and End keys) the scroll pane fires onChange (widgetFireChange) after the position is clamped; the setters, wgtScrollPaneScrollToTop, and scrolling a focused child into view do not. BASIC sees it as the ScrollPane’s Change event.
4.21.3. API Struct (wgtRegisterApi "scrollpane")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtScrollPane |
scrollToChild |
wgtScrollPaneScrollToChild |
setNoBorder |
wgtScrollPaneSetNoBorder |
scrollToTop |
wgtScrollPaneScrollToTop |
getScrollLeft |
wgtScrollPaneGetScrollLeft |
setScrollLeft |
wgtScrollPaneSetScrollLeft |
getScrollTop |
wgtScrollPaneGetScrollTop |
setScrollTop |
wgtScrollPaneSetScrollTop |
4.21.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
NoBorder |
Boolean |
Read/Write |
Whether the border around the scroll pane is hidden. |
Padding |
Integer |
Read/Write |
Pixels between the edge and the children (wgtGetPaddingPx / wgtSetPaddingPx). |
Spacing |
Integer |
Read/Write |
Pixels between the children (wgtGetSpacingPx / wgtSetSpacingPx). |
ScrollTop |
Integer |
Read/Write |
Vertical scroll position in pixels. |
ScrollLeft |
Integer |
Read/Write |
Horizontal scroll position in pixels. |
4.22. Separator
A visual dividing line used to separate groups of widgets. Available in horizontal and vertical orientations.
Header: include/widget/separator/separatr.h in the SDK (#include "separator/separatr.h")
4.22.1. API Functions
| Function | Description |
|---|---|
WidgetT *wgtSeparator(parent) |
Create a separator oriented from the parent: vertical in a horizontal container, horizontal otherwise. |
WidgetT *wgtHSeparator(parent) |
Create a horizontal separator line. |
WidgetT *wgtVSeparator(parent) |
Create a vertical separator line. |
bool wgtSeparatorIsVertical(w) |
True for a vertical line. |
void wgtSeparatorSetVertical(w, v) |
Turn the line vertical (true) or horizontal (false); the window lays out again. |
4.22.2. API Struct (wgtRegisterApi "separator")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
hSeparator |
wgtHSeparator |
vSeparator |
wgtVSeparator |
create |
wgtSeparator |
isVertical |
wgtSeparatorIsVertical |
setVertical |
wgtSeparatorSetVertical |
The BASIC Line control is registered as interface "line" with its own one-slot API (create = wgtSeparator).
4.23. Slider
A horizontal slider (track bar) for selecting an integer value within a range. The user drags the thumb or clicks the track to change the value.
Header: include/widget/slider/slider.h in the SDK (#include "slider/slider.h")
4.23.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtSlider(parent, minVal, maxVal) |
Create a slider with the given integer range. |
void wgtSliderSetValue(w, value) |
Set the slider value programmatically (clamped to Min..Max). |
int32_t wgtSliderGetValue(w) |
Get the current slider value. |
4.23.3. API Struct (wgtRegisterApi "slider")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtSlider |
setValue |
wgtSliderSetValue |
getValue |
wgtSliderGetValue |
4.23.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Max |
Integer |
Read/Write |
Highest value; lowering it below Min lowers Min too. |
Min |
Integer |
Read/Write |
Lowest value; raising it above Max raises Max too. |
Value |
Integer |
Read/Write |
Current slider value; checked: outside Min..Max refused (error 380 in BASIC). Listed after Max and Min, so the designer writes and the form loader sets the range first. |
4.24. Spacer
An invisible widget used for layout purposes. By default it has weight=100, so it absorbs available extra space. Useful for pushing other widgets apart or aligning them to edges.
Header: include/widget/spacer/spacer.h in the SDK (#include "spacer/spacer.h")
4.24.1. Creation
WidgetT *row = wgtHBox(parent);
wgtButton(row, "OK");
wgtSpacer(row); // pushes Cancel to the right
wgtButton(row, "Cancel");
4.24.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtSpacer(parent) |
Create an invisible spacer widget. |
4.24.3. API Struct (wgtRegisterApi "spacer")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtSpacer |
4.25. Spinner
A numeric input with up/down buttons for incrementing and decrementing a value within a range. Supports both integer and floating-point (real) modes.
Typing, Backspace/Delete, paste, cut, and undo start an edit of the text; Enter or focus loss commits it and Esc cancels it. Undo (Ctrl+Z) covers edits of the typed text only: every reformat from the value (creation, SetText, commit, step) empties the undo slot. A paste that is not a valid number is rolled back.
WCLASS_FIXED_FONT: it edits by columns, so its font must be fixed-pitch. Any size works (the column math uses the font’s charWidth and charHeight); a proportional font set with wgtSetFont, or inherited, is replaced by the system font when it draws.
Header: include/widget/spinner/spinner.h in the SDK (#include "spinner/spinner.h")
4.25.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtSpinner(parent, minVal, maxVal, step) |
Create a spinner with the given integer range and step size. |
void wgtSpinnerSetValue(w, value) |
Set the integer value. |
int32_t wgtSpinnerGetValue(w) |
Get the current integer value; an edit in progress is parsed but not committed. |
void wgtSpinnerSetRange(w, minVal, maxVal) |
Set the range for both modes (the real range starts as the creation range). |
void wgtSpinnerSetStep(w, step) |
Set the integer step size. |
void wgtSpinnerSetRealMode(w, enable) |
Switch to floating-point mode. |
double wgtSpinnerGetRealValue(w) |
Get the current floating-point value. |
void wgtSpinnerSetRealValue(w, value) |
Set the floating-point value. |
void wgtSpinnerSetRealRange(w, minVal, maxVal) |
Set the floating-point range only (call after wgtSpinnerSetRange). |
void wgtSpinnerSetRealStep(w, step) |
Set the floating-point step size. |
void wgtSpinnerSetDecimals(w, decimals) |
Set the number of decimal places displayed in real mode. |
4.25.3. API Struct (wgtRegisterApi "spinner")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtSpinner |
setValue |
wgtSpinnerSetValue |
getValue |
wgtSpinnerGetValue |
setRange |
wgtSpinnerSetRange |
setStep |
wgtSpinnerSetStep |
setRealMode |
wgtSpinnerSetRealMode |
getRealValue |
wgtSpinnerGetRealValue |
setRealValue |
wgtSpinnerSetRealValue |
setRealRange |
wgtSpinnerSetRealRange |
setRealStep |
wgtSpinnerSetRealStep |
setDecimals |
wgtSpinnerSetDecimals |
4.25.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Value |
Integer |
Read/Write |
Current integer value (in real mode the real value as a whole number); checked: outside the range refused (error 380 in BASIC). |
RealMode |
Boolean |
Read/Write |
Whether floating-point mode is active. |
Decimals |
Integer |
Read/Write |
Number of decimal places displayed in real mode; checked: 0 to SPINNER_MAX_DECIMALS. |
RealValue |
Double |
Read/Write |
The floating-point value; checked: in real mode outside the real range refused. |
4.25.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
SetRange min%, max% |
Set the range (integer and real mode). |
SetRealRange min#, max# |
The real range (WGT_SIG_DYN_2: Doubles, which no fixed signature takes). |
SetRealStep step# |
The real step size (WGT_SIG_DYN_1). |
SetStep step% |
Set the integer step size. |
4.26. Splitter
A two-pane container with a draggable divider. The user drags the splitter bar to resize the two panes. Can be oriented vertically (left/right panes) or horizontally (top/bottom panes). Add exactly two children.
The divider starts at 0, which the layout moves to the first pane’s minimum size (at least 20 pixels): until wgtSplitterSetPos or the user moves it, the first pane is as small as it can be. Every layout keeps the divider where both panes get at least their minimum size (and 20 pixels).
Header: include/widget/splitter/splitter.h in the SDK (#include "splitter/splitter.h")
4.26.1. Creation
WidgetT *sp = wgtSplitter(parent, true); // vertical = left|right
WidgetT *left = wgtVBox(sp);
WidgetT *right = wgtVBox(sp);
4.26.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtSplitter(parent, vertical) |
Create a splitter. vertical=true for left/right panes (vertical divider), false for top/bottom. |
void wgtSplitterSetPos(w, pos) |
Set the divider position in pixels from the leading edge (clamped at the next layout, as above). Fires no event. |
int32_t wgtSplitterGetPos(w) |
Get the current divider position in pixels. |
void wgtSplitterSetVertical(w, vertical) |
Change the orientation (true = left/right panes); the position is kept and clamped to the new axis at the next layout. |
bool wgtSplitterGetVertical(w) |
True when the panes are side by side. |
4.26.3. API Struct (wgtRegisterApi "splitter")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtSplitter |
setPos |
wgtSplitterSetPos |
getPos |
wgtSplitterGetPos |
setVertical |
wgtSplitterSetVertical |
getVertical |
wgtSplitterGetVertical |
4.26.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Position |
Integer |
Read/Write |
Divider position in pixels. |
Vertical |
Boolean |
Read/Write |
True (default): panes side by side. False: panes above and below. |
4.27. StatusBar
A horizontal bar typically placed at the bottom of a window for displaying status text and informational widgets. Children are laid out horizontally, each inside a 1-pixel sunken panel border. Padding defaults to 1 pixel and spacing to 2 pixels; the common padding/spacing fields override them.
Header: include/widget/statusBar/statBar.h in the SDK (#include "statusBar/statBar.h")
4.27.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtStatusBar(parent) |
Create a status bar container. |
4.27.3. API Struct (wgtRegisterApi "statusbar")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtStatusBar |
4.27.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Alignment |
Enum (Left, Center, Right) |
Read/Write |
Where the children sit along the bar when they do not fill it (the align field). |
Padding |
Integer |
Read/Write |
The padding field in pixels (1 unless set; wgtGetPaddingPx / wgtSetPaddingPx). |
Spacing |
Integer |
Read/Write |
The spacing field in pixels (2 unless set; wgtGetSpacingPx / wgtSetSpacingPx). |
4.28. TabControl
A tabbed container that displays one page at a time with clickable tabs along the top. Each tab page is a container that holds its own child widgets.
Header: include/widget/tabControl/tabCtrl.h in the SDK (#include "tabControl/tabCtrl.h")
4.28.1. Creation
WidgetT *tabs = wgtTabControl(parent);
WidgetT *page1 = wgtTabPage(tabs, "General");
WidgetT *page2 = wgtTabPage(tabs, "Advanced");
// add children to page1, page2...
4.28.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtTabControl(parent) |
Create a tab control. |
WidgetT *wgtTabPage(parent, title) |
Add a tab page with the given title. Returns the page container widget. |
void wgtTabControlSetActive(w, idx) |
Set the active tab by index (0-based). Negative selects the first tab; an index past the last page selects the last page (with no pages yet it is kept and clamped at layout, so it may be set before the pages are added). Closes a popup owned by a control on the hidden page and moves focus off that page; does not fire onChange. |
int32_t wgtTabControlGetActive(w) |
Get the index of the active tab. |
4.28.3. API Struct (wgtRegisterApi "tabcontrol")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtTabControl |
page |
wgtTabPage |
setActive |
wgtTabControlSetActive |
getActive |
wgtTabControlGetActive |
4.28.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
TabIndex |
Integer |
Read/Write |
Index of the currently active tab (0-based); checked: below 0, or past the last tab once there are tabs, refused (error 380 in BASIC). |
4.28.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddPage title$ |
Add a new tab page with the given title. |
GetActive() |
Returns the index of the active tab. |
SetActive idx% |
Set the active tab by index (0-based), as TabIndex does but without its events (WGT_SIG_ITEM_INT: an index past the pages is refused, error 381 in BASIC; wgtTabControlSetActive clamps it). |
4.29. TextInput / TextArea
Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization (built-in BASIC and help-source colorizers, the BASIC one shared with the DVX BASIC IDE), line numbers, find/replace, line markers, and gutter clicks.
WCLASS_FIXED_FONT: it edits by columns, so its font must be fixed-pitch. Any size works (the column math uses the font’s charWidth and charHeight); a proportional font set with wgtSetFont, or inherited, is replaced by the system font when it draws.
WCLASS_SWALLOWS_ENTER (TextArea only): Enter starts a new line even in a dialog box or a form with a default button. In a single-line input there, Enter presses the default button and the input never sees it.
Header: include/widget/textInput/textInpt.h in the SDK (#include "textInput/textInpt.h")
4.29.1. Creation
| Macro | Description |
|---|---|
wgtTextInput(parent, maxLen) |
Create a single-line text input. maxLen is the maximum number of characters (0 => default 256). |
wgtPasswordInput(parent, maxLen) |
Create a password input (characters displayed as bullets). |
wgtMaskedInput(parent, mask) |
Create a masked input field. The mask string defines the input format ('#' digit, 'A' letter, '*' any printable; other characters are literals). The mask is copied. Setting the text keeps the mask layout: text with the mask’s shape fills it slot by slot, other text fills the slots in order. |
wgtTextArea(parent, maxLen) |
Create a multi-line text area. maxLen is the most characters it holds (0 => TEXTAREA_DEFAULT_MAX_LEN, 65536, the same default as BASIC’s TextArea; at most TEXT_EDIT_MULTI_MAX_LEN, 262144). |
4.29.2. API Functions (TextArea-specific)
- void wgtTextAreaAppendText(w, text)
-
Append text to the end of the buffer (as much as fits) and repaint. The cursor and the selection stay as they were, onChange does not fire, and the undo slot is emptied (as wgtSetText empties it).
- void wgtTextAreaSetColorize(w, fn, ctx)
-
Set a syntax colorization callback. The callback receives each line and fills a color index array.
- void wgtTextAreaGoToLine(w, line)
-
Scroll to the given line number and select the whole line.
- void wgtTextAreaSetAutoIndent(w, enable)
-
Enable or disable automatic indentation on newline.
- void wgtTextAreaSetShowLineNumbers(w, show)
-
Show or hide line numbers in the gutter.
- void wgtTextAreaSetCaptureTabs(w, capture)
-
When true, Tab key inserts a tab/spaces instead of moving focus.
- void wgtTextAreaSetTabWidth(w, width)
-
Set the tab stop width in characters (below 1 counts as 1) and repaint.
- void wgtTextAreaSetUseTabChar(w, useChar)
-
When true, insert literal tab characters; when false, insert spaces.
- bool wgtTextAreaFindNext(w, needle, caseSens, fwd)
-
Search from the cursor and select the match (a forward match at the cursor counts; repeating moves past it). Returns true if found.
- int32_t wgtTextAreaReplaceAll(w, needle, repl, caseSens)
-
Replace all occurrences. Returns the number of replacements made.
- bool wgtTextAreaReplaceSelection(w, needle, repl, caseSens, fwd)
-
If the current selection matches needle, replace it, then find the next occurrence in direction fwd. Returns true if anything was replaced or found.
- void wgtTextAreaSetLineMarker(w, line, gutterRgb, backRgb)
-
Mark 1-based line: a dot of gutterRgb (0xRRGGBB) in the line-number gutter and / or the line’s background in backRgb; TEXTAREA_MARKER_NONE leaves a part out, both NONE removes the marker. Markers keep their line numbers when the text changes (the owner moves them). The DVX BASIC IDE marks breakpoints and the paused line this way.
- void wgtTextAreaClearLineMarkers(w)
-
Remove every line marker.
- void wgtTextAreaSetSyntaxMode(w, mode)
-
Use a built-in colorizer: "bas" / "basic" (BASIC: the compiler’s keyword list, date literals by the lexer’s shape rule, &H / &O and exponent numbers, REM and ' comments; the IDE’s code editor uses it), "dhs" / "help" (help source), or "custom" (each painted line goes to the "Colorize" event through wgtFireEvent: args LineText and Colors, a string of one digit per character, "0" = TEXT_SYNTAX_DEFAULT; the host writes the TEXT_SYNTAX_* digits back into Colors; the BASIC Colorize event; the answers are kept with the line text, 64 lines, so a line drawn again unchanged does not fire it again, and setting the mode again drops them); NULL or "" turns coloring off.
- int32_t wgtTextAreaGetCursorLine(w)
-
The cursor’s line (1 = the first; 1 for a widget that is not a text area).
- int32_t wgtTextAreaGetCursorCol(w)
-
The cursor’s column (1 = the start of the line; a tab counts as one character).
- void wgtTextAreaSetGutterClick(w, fn)
-
Set a callback for gutter clicks, fn(w, line) with the 1-based line (e.g. for breakpoint toggling).
- int32_t wgtTextAreaGetWordAtCursor(w, buf, bufSize)
-
Copy the word under the cursor into buf. Returns its length.
- void wgtTextAreaSetSyntaxColors(w, colors, count)
-
Set the color palette used by the colorizer (0xRRGGBB per TEXT_SYNTAX_ index; 0 = the default).
- void wgtTextAreaCursorToEnd(w)
-
Move the cursor to the very end of the buffer (past the last character).
- void wgtTextAreaSetCursor(w, line, col)
-
Move the cursor to 1-based line/column without selecting; scrolls it into view. Out-of-range values clamp to the text.
- int32_t wgtTextInputGetSelStart(w)
-
The selection’s start (0-based), or the cursor when nothing is selected.
- int32_t wgtTextInputGetSelLength(w)
-
Characters selected (0 = none).
- const char *wgtTextInputGetSelText(w)
-
The selected text, valid until the next call.
- void wgtTextInputSetSelStart(w, start)
-
Cursor to offset start (below 0 counts as 0, past the text the end), nothing selected.
- void wgtTextInputSetSelLength(w, length)
-
Select length characters from SelStart (clamped to the text; below 0 selects none).
- void wgtTextInputSetSelText(w, text)
-
Replace the selection (or insert at the cursor) with text, as much as fits (a text box leaves out line breaks, a masked box fills its slots); fires onChange.
- void wgtTextInputCut(w), wgtTextInputCopy(w), wgtTextInputPaste(w), wgtTextInputSelectAll(w), wgtTextInputUndo(w)
-
The Ctrl+X / C / V / A / Z commands. A text box runs them through its own key handler (a password box neither copies nor cuts, a masked box keeps its mask); Cut, Paste, and Undo change nothing in a read-only box or area and otherwise fire onChange.
The selection, clipboard, and undo calls take a text box or a text area alike. For a text area the header also names them wgtTextAreaGetSelStart, wgtTextAreaGetSelLength, wgtTextAreaGetSelText, wgtTextAreaSetSelStart, wgtTextAreaSetSelLength, wgtTextAreaSetSelText, wgtTextAreaCut, wgtTextAreaCopy, wgtTextAreaPaste, wgtTextAreaSelectAll, and wgtTextAreaUndo: the same calls (and the same API slots) under the text area’s names. Given any other widget they do nothing (the getters return 0 or "").
4.29.3. API Struct (wgtRegisterApi "textinput")
The combined "textinput" API exposes all four constructors plus the TextArea functions, then the selection and clipboard functions for both kinds (inputGetSelStart ... inputUndo), then getCursorCol and appendText (wgtTextAreaGetCursorCol, wgtTextAreaAppendText). The designer uses per-type APIs registered under the names "textbox" (single-line) and "textarea" (multi-line), each exposing only the header and a create slot. Every API struct starts with a header (WGT_API_HEADER: ABI version and size, checked by wgtGetApi).
4.29.4. Properties (BASIC Interface)
Text is managed via the generic "Text" property. TextBox exposes:
| Property | Type | Access | Description |
|---|---|---|---|
MaxLength |
Integer |
Read/Write |
Characters the box holds (its buffer size less one). Setting it gives a new buffer of that size (0 = TEXT_EDIT_DEFAULT_MAX_LEN, at most TEXT_EDIT_SINGLE_MAX_LEN), the text cut to fit; a masked box keeps its mask’s length. Checked: below 0 refused (error 380 in BASIC). |
PasswordChar |
String |
Read/Write |
"" for a plain box; one character makes it a password box (as wgtPasswordInput, which shows a small bullet) showing that character for each one typed. Ignored on a masked box. |
Mask |
String |
Read/Write |
"" for a plain box; a mask makes the live box a masked input (as wgtMaskedInput) holding what fits of its text; "" makes it plain again with the formatted text and its earlier MaxLength. Replaces PasswordChar. |
SelStart |
Integer |
Read/Write |
wgtTextInputGetSelStart / wgtTextInputSetSelStart; checked: below 0 refused (error 380 in BASIC), past the text the end. |
SelLength |
Integer |
Read/Write |
wgtTextInputGetSelLength / wgtTextInputSetSelLength; checked: below 0 refused. |
SelText |
String |
Read/Write |
wgtTextInputGetSelText / wgtTextInputSetSelText. |
TextBox methods: Copy, Cut, Paste, SelectAll, and Undo (wgtTextInputCopy ...).
TextArea exposes:
| Property | Type | Access | Description |
|---|---|---|---|
CursorLine |
Integer |
Read-only |
Current cursor line number (1-based). |
CursorCol |
Integer |
Read-only |
Current cursor column (1-based, in characters). |
LineCount |
Integer |
Read-only |
Number of lines. |
SelStart |
Integer |
Read/Write |
Selection start offset (0-based), or the cursor’s when none; setting it moves the cursor there (past the text: the end). Checked: below 0 refused (error 380 in BASIC). |
SelLength |
Integer |
Read/Write |
Characters selected; setting it selects from SelStart, as many as there are. Checked: below 0 refused. |
SelText |
String |
Read/Write |
The selection; setting it replaces it (textEditMultiReplaceSel), firing Change. |
MaxLength |
Integer |
Read/Write |
The most characters the area holds; setting it makes a new buffer (0 = TEXTAREA_DEFAULT_MAX_LEN, as wgtTextArea’s maxLen 0; at most TEXT_EDIT_MULTI_MAX_LEN) with the text cut to fit. Checked: below 0 refused. |
4.29.5. Methods (BASIC Interface, TextArea)
| Method | Description |
|---|---|
AppendText text$ |
wgtTextAreaAppendText. |
ClearLineMarkers |
wgtTextAreaClearLineMarkers. |
Copy / Cut / Paste / SelectAll / Undo |
The Ctrl+C / X / V / A / Z commands (the texthelp textEditMulti* functions the key handler runs); Cut, Paste, and Undo fire Change and do nothing when read-only. |
CursorToEnd |
wgtTextAreaCursorToEnd. |
FindNext needle$, caseSensitive, forward |
Search from the cursor (a match at the cursor counts; repeating moves past it). Returns True if found. |
GetLine(line%) |
Returns a line’s text (1-based), "" past the end. |
GetSyntaxColor(index%) |
Returns an index’s color (BASIC &HBBGGRR), -1 for the foreground. |
GetWordAtCursor() |
Returns the word under the cursor. |
GoToLine line% |
Scroll to a line and select it. |
ReplaceAll needle$, replacement$, caseSensitive |
Replace all occurrences. Returns the count. |
ReplaceSelection(needle$, repl$, caseSens, fwd) |
wgtTextAreaReplaceSelection (WGT_SIG_STR_STR_BOOL_BOOL). |
SetAutoIndent enabled |
Enable or disable automatic indentation on newline. |
SetCaptureTabs enabled |
When True, Tab inserts whitespace instead of moving focus. |
SetCursor line%, col% |
Move the cursor to a 1-based line and column without selecting. |
SetLineMarker line%, gutter&, back& |
wgtTextAreaSetLineMarker with BASIC colors (&HBBGGRR, -1 = TEXTAREA_MARKER_NONE). |
SetShowLineNumbers show |
Show or hide line numbers in the gutter. |
SetSyntaxColor index%, color& |
One palette entry (BASIC color, -1 = the default). |
SetSyntaxMode mode$ |
Activate built-in syntax highlighting (e.g. "dhs", "bas"; "" to disable). |
SetTabWidth width% |
Set the tab stop width in characters. |
SetUseTabChar useChar |
When True, Tab inserts a literal tab; when False, spaces. |
4.29.6. Events
| Callback | Description |
|---|---|
onChange |
Fires when the text content changes. |
The common onKeyDown and onKeyPress callbacks come first for each key, and wgtKeyReplace(0) in them cancels it. A text box or area never calls onValidate (the Data control does).
The TextArea interface lists the event GutterClick (LineNumber As Integer, 1-based). The TextArea fires it with wgtFireEvent after its gutter-click callback, so it reaches the widget’s onEvent (the form runtime’s CtrlName_GutterClick); the gutter takes clicks when either the callback or onEvent is set.
4.30. Timer
A non-visual widget that fires its onChange callback at a regular interval. Useful for animations, polling, and periodic updates. A new timer is running; call wgtTimerStop to keep it dormant.
Intervals are counted on DVX’s clock (platformClock), which on a PC moves in BIOS ticks of about 55 ms (18.2 a second), and the event loop checks the timers once a frame. A timer fires at the first tick at which its whole interval has passed, so every interval comes out as a whole number of ticks: 100 ms fires about every 110 ms, and anything up to 55 ms about every 55 ms.
Header: include/widget/timer/timer.h in the SDK (#include "timer/timer.h")
4.30.1. Creation
WidgetT *tmr = wgtTimer(parent, 1000, true); // 1 second, repeating
tmr->onChange = onTimerTick;
4.30.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtTimer(parent, intervalMs, repeat) |
Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot. |
void wgtTimerStart(w) |
Start the timer. |
void wgtTimerStop(w) |
Stop the timer. |
void wgtTimerSetInterval(w, intervalMs) |
Change the timer interval and restart the countdown. An interval of 0 or less never fires. |
int32_t wgtTimerGetInterval(w) |
Returns the current interval in milliseconds. |
bool wgtTimerIsRunning(w) |
Returns true if the timer is currently running. |
bool wgtTimerGetRepeat(w) |
Returns true for a repeating timer, false for a one-shot. |
void wgtTimerSetRepeat(w, repeat) |
Make the timer repeating or one-shot from its next fire on (a running countdown is kept). |
void wgtUpdateTimers(void) |
Global tick function. Called by the event loop to advance all active timers. |
4.30.3. API Struct (wgtRegisterApi "timer")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtTimer |
start |
wgtTimerStart |
stop |
wgtTimerStop |
setInterval |
wgtTimerSetInterval |
isRunning |
wgtTimerIsRunning |
updateTimers |
wgtUpdateTimers |
getInterval |
wgtTimerGetInterval |
getRepeat |
wgtTimerGetRepeat |
setRepeat |
wgtTimerSetRepeat |
testReset |
wgtTimerTestReset (present only in host test builds, DVX_HOST_TEST) |
4.30.4. Events
| Callback | Description |
|---|---|
onChange |
Fires each time the timer elapses (the BASIC layer surfaces this as the "Timer" event). A one-shot timer is stopped before the callback runs, so the callback may restart it. |
4.30.5. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Enabled |
Boolean |
Read/Write |
Whether the timer is running. Reading returns the running state (wgtTimerIsRunning); writing starts or stops it (wgtTimerStart / wgtTimerStop). |
Interval |
Integer |
Read/Write |
Timer interval in milliseconds. Setting it restarts the countdown; 0 disables firing; checked: below 0 refused (error 380 in BASIC). |
Repeat |
Boolean |
Read/Write |
True (the default) for a repeating timer, False for a one-shot (wgtTimerGetRepeat / wgtTimerSetRepeat). |
4.31. Toolbar
A horizontal container for toolbar buttons and controls. Typically placed at the top of a window. Children (usually ImageButtons or Buttons) are laid out horizontally with toolbar-appropriate spacing: 2 pixels of padding and spacing by default, overridable through the common padding/spacing fields.
Header: include/widget/toolbar/toolbar.h in the SDK (#include "toolbar/toolbar.h")
4.31.1. Creation
WidgetT *tb = wgtToolbar(parent);
wgtImageButtonFromFile(tb, "icons/save.bmp");
wgtImageButtonFromFile(tb, "icons/open.bmp");
4.31.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtToolbar(parent) |
Create a toolbar container. |
The toolbar paints the window face behind its children and reports it through its class’s WGT_METHOD_GET_FACE, so wgtBackColor of a widget inside it (a Label’s fill) is that face.
4.31.3. API Struct (wgtRegisterApi "toolbar")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtToolbar |
4.31.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Alignment |
Enum (Left, Center, Right) |
Read/Write |
Where the children sit along the bar when they do not fill it (the align field). |
Padding |
Integer |
Read/Write |
The padding field in pixels (2 unless set; wgtGetPaddingPx / wgtSetPaddingPx). |
Spacing |
Integer |
Read/Write |
The spacing field in pixels (2 unless set; wgtGetSpacingPx / wgtSetSpacingPx). |
4.32. TreeView
A hierarchical tree control with expandable/collapsible nodes. Supports single and multi-selection and drag-to-reorder. Tree items are added as children of the TreeView or of other tree items to create nested hierarchies. Printable keys are type-ahead over the visible items, the lists' rule (widgetTypeAheadText: keys typed quickly make up a prefix). Depends on the "listhelp" helper library (declared in treeview.dep).
Header: include/widget/treeView/treeView.h in the SDK (#include "treeView/treeView.h")
4.32.1. Creation
WidgetT *tv = wgtTreeView(parent);
WidgetT *root = wgtTreeItem(tv, "Root");
WidgetT *child = wgtTreeItem(root, "Child");
4.32.2. API Functions
| Function | Description |
|---|---|
WidgetT *wgtTreeView(parent) |
Create a tree view control. |
WidgetT *wgtTreeItem(parent, text) |
Add a tree item as a child of the tree view or another tree item. |
WidgetT *wgtTreeViewGetSelected(w) |
Get the currently selected tree item (NULL if none). |
void wgtTreeViewSetSelected(w, item) |
Set the selected tree item (expanding its ancestors and scrolling it into view). Items of other trees are ignored. |
void wgtTreeViewSetMultiSelect(w, multi) |
Enable or disable multi-selection. Turning it off clears the per-item selection. |
void wgtTreeViewSetReorderable(w, reorderable) |
Enable drag-to-reorder of items. |
void wgtTreeItemSetExpanded(w, expanded) |
Expand or collapse a tree item. Collapsing an item over the current item moves the current item to w and fires onChange; otherwise it fires nothing. |
bool wgtTreeItemIsExpanded(w) |
Check if a tree item is expanded. |
bool wgtTreeItemIsSelected(w) |
Check if a tree item is selected (single-select: it is the selected item). |
void wgtTreeItemSetSelected(w, selected) |
Select or deselect a tree item. In single-select mode this sets or clears the tree’s selected item. |
4.32.3. API Struct (wgtRegisterApi "treeview")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wgtTreeView |
getSelected |
wgtTreeViewGetSelected |
setSelected |
wgtTreeViewSetSelected |
setMultiSelect |
wgtTreeViewSetMultiSelect |
setReorderable |
wgtTreeViewSetReorderable |
item |
wgtTreeItem |
itemSetExpanded |
wgtTreeItemSetExpanded |
itemIsExpanded |
wgtTreeItemIsExpanded |
itemIsSelected |
wgtTreeItemIsSelected |
itemSetSelected |
wgtTreeItemSetSelected |
4.32.4. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
ListIndex |
Integer |
R/W |
Depth-first index of the current node, -1 when none; checked (an index there is no node for is refused: error 380 in BASIC). Setting it selects the node as a click would, without Change (as Visual Basic raises no NodeClick for a selection the code makes); SetItemSelected and SetExpanded fire none either. The C calls wgtTreeViewSetSelected and wgtTreeItemSetSelected fire onChange; wgtTreeItemSetExpanded fires it only when collapsing moves the current item. |
4.32.5. Methods (BASIC Interface)
| Method | Description |
|---|---|
AddChildItem parentIdx%, text$ |
Add a child node under the node at the given index. |
AddItem text$ |
Add a root-level node. |
Clear |
Remove all nodes. |
GetItemTag(index%) |
Returns the text SetItemTag stored on the node ("" when none). |
GetItemText(index%) |
Returns the text of the node at the given depth-first index. |
HasChildren(index%) |
Returns True if the node has nodes under it. |
IsExpanded(index%) |
Returns True if the node is expanded. |
IsItemSelected(index%) |
Returns True if the node is selected. |
ItemCount() |
Returns the total number of nodes. |
ItemDepth(index%) |
Returns how many nodes the node is under (0 at the root level). |
ItemParent(index%) |
Returns the index of the node’s parent (-1 at the root level). |
RemoveItem index% |
Remove the node and every node under it (destroys the item widgets). |
SetExpanded index%, expanded |
Expand or collapse the node (collapsing moves a hidden selection to the node). |
SetItemSelected index%, selected |
Select or deselect the node (single-select: sets or clears the selection). |
SetItemTag index%, tag$ |
Keep a string with the node ("" frees it). |
SetItemText index%, text$ |
Change the node’s text. |
SetMultiSelect multi |
Enable or disable multi-selection. |
SetReorderable reorderable |
Enable or disable drag-to-reorder. |
The methods taking a node’s index are checked (WGT_SIG_KIND_ITEM: AddChildItem, RemoveItem, SetExpanded, SetItemSelected, SetItemTag, and SetItemText; WGT_SIG_KIND_INDEX_GET: GetItemTag, GetItemText, HasChildren, IsExpanded, IsItemSelected, ItemDepth, and ItemParent): an index there is no node for is refused, nothing done (error 381 in BASIC).
4.32.6. Events
| Callback | Description |
|---|---|
onClick |
Fires for a press on the tree that is not on a scroll bar, after onMouseDown: on a node (after onChange and NodeClick), on a node’s expand box (after Expand or Collapse), or below the nodes (alone), as Visual Basic’s TreeView Click. The keys fire none. The second press of a double click fires onDblClick instead when the tree has one. |
NodeClick |
The widget’s own event (wgtFireEvent, Node As Integer: the node’s depth-first index): a click on a node, even the current one, or a move to another node with the keys, after onChange. |
Expand |
The widget’s own event (Node As Integer): the user opened the node (its expand box, a double click on the node, Right, or Enter). |
Collapse |
The widget’s own event (Node As Integer): the user closed the node (its expand box, a double click on the node, Left, or Enter). |
onDblClick |
Fires when a tree item is double-clicked (a double click on a scroll bar fires none, and a press on a scroll bar fires no onMouseDown or onMouseUp either; a press on a node just after one on a scroll bar is never the second of a double click). A double click on an item with items under it opens or closes the item first, as a Windows TreeView does (the item’s own onChange, then Expand or Collapse: widgetFireDoublePick). |
onChange |
Fires when the user changes the current node or the selected set (including Space toggles in multi-select mode), and after a drag-reorder. The mouse wheel scrolls the view, changing nothing. |
4.33. WrapBox
A flow/wrap layout container that arranges children left-to-right, wrapping to the next row when the available width is exceeded. Each row’s height is the maximum child height in that row. Supports configurable spacing between items and rows, and per-row alignment for short rows.
Header: include/widget/wrapBox/wrapBox.h in the SDK (#include "wrapBox/wrapBox.h")
4.33.1. Creation
WidgetT *wrap = wgtWrapBox(parent);
wgtButton(wrap, "Tag 1");
wgtButton(wrap, "Tag 2");
wgtButton(wrap, "Tag 3");
4.33.2. API Functions
| Function | Description |
|---|---|
wgtWrapBox(parent) |
Create a wrap box container. Macro that calls the registered "wrapbox" create slot. |
4.33.3. API Struct (wgtRegisterApi "wrapbox")
| Slot | Function |
|---|---|
header |
WGT_API_HEADER (ABI version and size, checked by wgtGetApi) |
create |
wrapBoxCreate |
4.33.4. Properties (Common Container Fields)
WrapBox uses the common WidgetT container fields for layout control:
| Property | Description |
|---|---|
spacing |
Gap between children in both the horizontal and vertical directions (tagged size). Default is 4 pixels; wgtPixels(0) is none. |
padding |
Internal padding around children (tagged size). Default is 2 pixels; wgtPixels(0) is none. |
4.33.5. Properties (BASIC Interface)
| Property | Type | Access | Description |
|---|---|---|---|
Alignment |
Enum (Left, Center, Right) |
Read/Write |
Row alignment for rows that do not fill the full width. |
Padding |
Integer |
Read/Write |
The padding field in pixels (wgtGetPaddingPx / wgtSetPaddingPx). |
Spacing |
Integer |
Read/Write |
The spacing field in pixels (wgtGetSpacingPx / wgtSetSpacingPx). |
Chapter 5. Text, Lists, and Help Files
5.1. Text Help Library
Shared text editing infrastructure library for DVX widget DXEs. Provides cursor blink management, cross-widget selection clearing, word boundary logic, and a complete single-line text editing engine. Used by TextInput, Spinner, ComboBox, AnsiTerm, and other widgets that need text editing behavior.
Header: texthelp/textHelp.h
Loaded as: bin/libs/kpunch/texthelp/texthelp.lib
5.1.1. How Widgets Use This Library
Widget DXEs that implement text editing delegate to textHelp for the four high-cost behaviors:
-
Cursor blink. The library tracks a 250 ms blink timer in a static global and the focused widget reads sCursorBlinkOn (exposed via libdvx) when repainting.
-
Selection clearing. When a widget gains focus it calls clearOtherSelections(self) so only one widget ever has an active text selection.
-
Word boundaries. isWordChar, wordStart/wordEnd, and wordBoundaryLeft/wordBoundaryRight implement the logic for double-click word selection and Ctrl+Left/Right navigation in a uniform way.
-
Single-line editing engine. A single-line widget (TextInput, Spinner, ComboBox) embeds a TextEditSingleT (buffer, cursor, scroll offset, selection, undo slot) and hands it to widgetTextEditOnKey, widgetTextEditMouseClick, and widgetTextEditDragUpdateLine. widgetTextEditPaintLine draws a line from an explicit buffer so a widget can paint substitute text (password bullets).
The multi-line engine (TextArea) works the same way with a TextEditMultiT: widgetTextEditMultiOnKey(w, key, mod, te, visRows, visCols, opts) runs a key on it. Its clipboard and undo commands are functions of their own, which the keys and a TextArea’s Copy / Cut / Paste / SelectAll / Undo / SelText run alike: textEditMultiCopy (false when nothing is selected), textEditMultiCut, textEditMultiPaste, textEditMultiReplaceSel(te, text, textLen) (replaces the selection or inserts at the cursor, as much as fits, undo saved first), textEditMultiSelectAll, and textEditMultiUndo (a second one is redo). The editing ones return true when the text changed; the caller then fires Change, scrolls to the cursor, and repaints.
5.1.2. Constants
| Constant | Value | Description |
|---|---|---|
TEXT_INPUT_PAD |
3 |
Pixel padding inside text editing fields. |
TEXT_EDIT_UNDO_NONE |
-1 |
Undo length meaning "no snapshot". Set it at creation and whenever the text is replaced wholesale. |
TEXT_EDIT_DEFAULT_MAX_LEN |
256 |
Capacity in characters of a single-line editor created with maxLen <= 0; also the BASIC default for TextBox and ComboBox. |
TEXT_EDIT_SINGLE_MAX_LEN |
32767 |
Largest capacity of a single-line editor; a larger maxLen is reduced to it. |
TEXT_EDIT_MULTI_MAX_LEN |
262144 |
Largest capacity of a multi-line editor (textEditMultiInit). |
TEXT_CURSOR_BLINK_MS |
250 |
Caret blink half-period in milliseconds. |
5.2. wgtUpdateCursorBlink
Advances the cursor blink timer. When the blink interval (TEXT_CURSOR_BLINK_MS, 250 ms) elapses, toggles the global sCursorBlinkOn flag and invalidates the currently focused widget for repaint. Registered automatically at library load time via a constructor function that sets the sCursorBlinkFn pointer.
void wgtUpdateCursorBlink(void);
Takes no arguments and returns nothing. Called by the core event loop.
5.3. clearOtherSelections
Clears the text selection on whichever widget previously had one, unless that widget is the one passed as the argument. Tracks the last selected widget in a static pointer for O(1) lookup instead of walking the widget tree. Validates that the previous widget’s window is still in the window stack before touching it, so stale pointers from closed windows are handled safely. If the previous selection was in a different window, that window gets a full repaint to clear the stale highlight.
void clearOtherSelections(WidgetT *except);
| Parameter | Type | Description |
|---|---|---|
except |
WidgetT * |
The widget that now owns the selection. Its selection is preserved. |
5.4. isWordChar
Returns true if the character is alphanumeric or underscore. Used by word boundary functions to define what constitutes a "word" for double-click selection and Ctrl+arrow navigation.
bool isWordChar(char c);
| Parameter | Type | Description |
|---|---|---|
c |
char |
The character to test. |
Returns true if c is alphanumeric (a-z, A-Z, 0-9) or underscore.
5.5. wordEnd
Scans forward from the given position, returning the index of the first non-word character. Used to find the right boundary of a word for double-click word selection.
int32_t wordEnd(const char *buf, int32_t len, int32_t pos);
| Parameter | Type | Description |
|---|---|---|
buf |
const char * |
The text buffer to scan. |
len |
int32_t |
Length of the text in the buffer. |
pos |
int32_t |
Starting position (character index). |
Returns the index one past the last word character.
5.6. wordStart
Scans backward from the given position, returning the index of the first character of the current word. Used to find the left boundary of a word for double-click word selection.
int32_t wordStart(const char *buf, int32_t pos);
| Parameter | Type | Description |
|---|---|---|
buf |
const char * |
The text buffer to scan. |
pos |
int32_t |
Starting position (character index). |
Returns the index of the first character of the word containing pos.
5.7. wordBoundaryLeft
Finds the left word boundary for Ctrl+Left navigation. Skips non-word characters first, then skips word characters, leaving the cursor at the start of the previous word.
int32_t wordBoundaryLeft(const char *buf, int32_t pos);
| Parameter | Type | Description |
|---|---|---|
buf |
const char * |
The text buffer to scan. |
pos |
int32_t |
Starting position (character index). |
Returns the index of the previous word boundary. Returns 0 if pos is already at or before the start of the buffer.
5.8. wordBoundaryRight
Finds the right word boundary for Ctrl+Right navigation. Skips word characters first, then skips non-word characters, leaving the cursor at the start of the next word.
int32_t wordBoundaryRight(const char *buf, int32_t len, int32_t pos);
| Parameter | Type | Description |
|---|---|---|
buf |
const char * |
The text buffer to scan. |
len |
int32_t |
Length of the text buffer. |
pos |
int32_t |
Starting position (character index). |
Returns the index of the next word boundary. Returns len if pos is already at or past the end of the buffer.
5.9. textEditSaveUndo
Capture a snapshot of the current buffer contents and cursor position into an undo buffer. Called by the single-line engine before every destructive operation (insert, delete, paste, cut). Truncates to bufSize - 1 characters so the null terminator always fits.
void textEditSaveUndo(char *buf, int32_t len,
int32_t cursor, char *undoBuf,
int32_t *pUndoLen, int32_t *pUndoCursor,
int32_t bufSize);
| Parameter | Type | Description |
|---|---|---|
buf |
char * |
Source buffer to snapshot. |
len |
int32_t |
Current length of source contents. |
cursor |
int32_t |
Current cursor position to save. |
undoBuf |
char * |
Destination undo buffer. If NULL the call is a no-op. |
pUndoLen |
int32_t * |
[out] Length of saved undo contents. |
pUndoCursor |
int32_t * |
[out] Saved cursor position. |
bufSize |
int32_t |
Size of the destination undo buffer including the null terminator. |
5.10. textEditUndoSwap
Exchange the live buffer with the undo snapshot (single-slot undo; a second swap is redo). buf and undoBuf must both be bufSize bytes. Returns false and changes nothing when there is no snapshot (*pUndoLen is TEXT_EDIT_UNDO_NONE). On success *pCursor is the restored cursor, clamped to the restored length, and the undo slot holds the previous text and cursor.
bool textEditUndoSwap(char *buf, int32_t bufSize,
int32_t *pLen, int32_t *pCursor, char *undoBuf,
int32_t *pUndoLen, int32_t *pUndoCursor);
Two related helpers:
| Function | Description |
|---|---|
textEditCopyText |
int32_t textEditCopyText(char *buf, int32_t bufSize, const char *text). Copy text into buf (truncated to bufSize - 1), terminate it, and return the length. Writes only the copied bytes. |
textEditMoveCursor |
void textEditMoveCursor(int32_t newPos, bool shift, int32_t *pCursor, int32_t *pSelStart, int32_t *pSelEnd). Move a single-line cursor; with shift extend the selection (anchoring at the old cursor), otherwise clear it. The selection pointers may be NULL. |
5.11. TextEditSingleT
Per-editor state of a single-line field. selStart/selEnd are -1 when nothing is selected; undoLen is TEXT_EDIT_UNDO_NONE until the first edit takes a snapshot.
typedef struct TextEditSingleT {
char *buf;
char *undoBuf;
int32_t bufSize;
int32_t len;
int32_t cursorPos;
int32_t scrollOff;
int32_t selStart;
int32_t selEnd;
int32_t undoLen;
int32_t undoCursor;
} TextEditSingleT;
| Function | Description |
|---|---|
bool textEditSingleInit(TextEditSingleT *te, int32_t maxLen) |
Allocate buf and undoBuf for maxLen characters plus the terminator (TEXT_EDIT_DEFAULT_MAX_LEN when maxLen <= 0, at most TEXT_EDIT_SINGLE_MAX_LEN): empty text, no selection, no undo snapshot. Returns false (both pointers NULL) when allocation fails. |
void textEditSingleFree(TextEditSingleT *te) |
Free both buffers. |
bool textEditSingleResize(TextEditSingleT *te, int32_t maxLen) |
New buffers for maxLen characters (same rule as Init) holding the old text, cut to fit. Returns false, leaving the field as it was, when allocation fails. |
void textEditSingleSetText(TextEditSingleT *te, const char *text) |
Replace the text (NULL = empty, truncated to the buffer): cursor at the end, view scrolled home, no selection, undo slot emptied. |
bool textEditSingleClearSelection(TextEditSingleT *te) |
Drop the selection. Returns true when a non-empty selection was cleared. |
void textEditSingleSelRange(const TextEditSingleT *te, int32_t *lo, int32_t *hi) |
The selection as [lo, hi), clamped to the text; lo == hi == the cursor when nothing is selected. |
bool textEditSingleReplaceSel(TextEditSingleT *te, const char *text, int32_t textLen) |
Replace the selection (or insert at the cursor) with text, its newlines dropped and cut to what fits; the cursor after it, nothing selected, the old text in the undo slot. Returns false, with nothing changed, when nothing is selected and nothing fits. The key handler’s typing and Ctrl+V use it, and a text box’s SelText. |
bool textEditKeyEdits(int32_t key) |
True for keys that modify the text (printable characters, Backspace, Delete, Ctrl+V, Ctrl+X, Ctrl+Z). Read-only editors drop these before calling the engine. |
int32_t textEditVisibleChars(int32_t fieldWidth, const BitmapFontT *font) |
Whole columns visible in a field fieldWidth pixels wide, inside the text padding. |
void textEditScrollToCursor(int32_t cursor, int32_t visibleChars, int32_t *pScrollOff) |
Adjust a horizontal scroll offset so the cursor is inside the visible columns. |
uint32_t textEditDefaultSyntaxRgb(uint8_t idx) |
Default syntax color (0x00RRGGBB) for a TEXT_SYNTAX_* index; 0 for TEXT_SYNTAX_DEFAULT, which uses the caller’s foreground. |
The key handler, the drag update, and the widgets' paint code all use textEditVisibleChars, so they agree on the visible width.
5.12. widgetTextEditDragUpdateLine
Called during mouse drag to extend the selection in a single-line text field. Converts a viewport-relative pixel x coordinate to a character position and updates the cursor and selection end accordingly. Auto-scrolls the text when the mouse moves past the left or right visible edge.
void widgetTextEditDragUpdateLine(TextEditSingleT *te, int32_t vx, int32_t leftEdge, int32_t maxChars, const BitmapFontT *font);
| Parameter | Type | Description |
|---|---|---|
te |
TextEditSingleT * |
[in/out] Editor state: cursorPos, scrollOff, and selEnd are updated. |
vx |
int32_t |
Mouse x position in viewport coordinates. |
leftEdge |
int32_t |
Pixel x of the left edge of the text area. |
maxChars |
int32_t |
Maximum visible characters in the field. |
font |
const BitmapFontT * |
Bitmap font used for character width. |
5.13. widgetTextEditMouseClick
Handles mouse click events for single-line text widgets. Converts pixel coordinates to a character position using the font’s character width. Detects multi-click sequences via the core multiClickDetect() function:
-
Single click — places the cursor and begins a potential drag selection.
-
Double click — selects the word under the cursor (if wordSelect is true), or selects all text.
-
Triple click — selects all text in the field.
void widgetTextEditMouseClick(WidgetT *w, TextEditSingleT *te, int32_t vx, int32_t vy, int32_t textLeftX, const BitmapFontT *font, bool wordSelect, bool dragSelect);
| Parameter | Type | Description |
|---|---|---|
w |
WidgetT * |
The widget receiving the click. |
te |
TextEditSingleT * |
[in/out] Editor state: cursorPos, selStart, and selEnd are set. |
vx |
int32_t |
Mouse x in viewport coordinates. |
vy |
int32_t |
Mouse y in viewport coordinates. |
textLeftX |
int32_t |
Pixel x of the left edge of the text area. |
font |
const BitmapFontT * |
Bitmap font for character width calculation. |
wordSelect |
bool |
If true, double-click selects word; if false, selects all. |
dragSelect |
bool |
If true, single-click begins drag selection. |
5.14. widgetTextEditOnKey
The core single-line text editing engine. Processes a single keystroke and updates the editor’s buffer, cursor, scroll offset, selection, and undo state. Shared by TextInput, Spinner, and ComboBox.
void widgetTextEditOnKey(WidgetT *w, int32_t key, int32_t mod, TextEditSingleT *te, int32_t fieldWidth);
| Parameter | Type | Description |
|---|---|---|
w |
WidgetT * |
The widget receiving the key event. |
key |
int32_t |
Key code (ASCII for printable, control code, or scan|0x100 for extended). |
mod |
int32_t |
Modifier flags (KEY_MOD_SHIFT, etc.). |
te |
TextEditSingleT * |
[in/out] Editor state. Ctrl+Z does nothing while undoLen is TEXT_EDIT_UNDO_NONE. |
fieldWidth |
int32_t |
Field width in pixels including the text padding (subtracted internally). 0 = use widget width. |
5.14.1. Supported Keys
| Key | Action |
|---|---|
Printable |
Insert character at cursor (replaces selection if active). |
Backspace |
Delete character before cursor or delete selection. |
Delete |
Delete character after cursor or delete selection. |
Left |
Move cursor left. With Shift, extend selection. |
Right |
Move cursor right. With Shift, extend selection. |
Ctrl+Left |
Move cursor to previous word boundary. With Shift, extend selection. |
Ctrl+Right |
Move cursor to next word boundary. With Shift, extend selection. |
Home |
Move cursor to start. With Shift, extend selection. |
End |
Move cursor to end. With Shift, extend selection. |
Ctrl+A |
Select all text. |
Ctrl+C |
Copy selection to clipboard. |
Ctrl+V |
Paste from clipboard (newlines stripped). |
Ctrl+X |
Cut selection to clipboard. |
Ctrl+Z |
Undo (swaps current and undo buffers). |
Fires w->onChange after any mutation (insert, delete, paste, cut, undo). Automatically adjusts scroll offset to keep cursor visible after every operation.
5.15. widgetTextEditPaintLine
Renders a single line of text with optional selection highlighting and a blinking cursor. Splits the visible text into up to three segments (pre-selection, selection, post-selection) and draws each with appropriate colors. The selection highlight uses the menu highlight colors from the color scheme. The cursor is drawn as a one-pixel vertical line when sCursorBlinkOn is true.
void widgetTextEditPaintLine(
DisplayT *d, const BlitOpsT *ops,
const BitmapFontT *font,
const ColorSchemeT *colors,
int32_t textX, int32_t textY,
const char *buf, int32_t visLen,
int32_t scrollOff, int32_t cursorPos,
int32_t selStart, int32_t selEnd,
uint32_t fg, uint32_t bg,
bool showCursor,
int32_t cursorMinX, int32_t cursorMaxX);
| Parameter | Type | Description |
|---|---|---|
d |
DisplayT * |
Display context for drawing. |
ops |
const BlitOpsT * |
Blit operations table for the current pixel format. |
font |
const BitmapFontT * |
Bitmap font for text rendering. |
colors |
const ColorSchemeT * |
Color scheme (used for selection highlight colors). |
textX |
int32_t |
Pixel x of the start of visible text. |
textY |
int32_t |
Pixel y of the text baseline. |
buf |
const char * |
Visible portion of the text buffer (buf + scrollOff). |
visLen |
int32_t |
Number of visible characters to draw. |
scrollOff |
int32_t |
Scroll offset (used to map selection to visible range). |
cursorPos |
int32_t |
Absolute cursor position in the full buffer. |
selStart |
int32_t |
Selection start (-1 if no selection). |
selEnd |
int32_t |
Selection end (-1 if no selection). |
fg |
uint32_t |
Foreground (text) color. |
bg |
uint32_t |
Background color. |
showCursor |
bool |
Whether to draw the cursor (false when widget lacks focus). |
cursorMinX |
int32_t |
Left clipping bound for cursor drawing. |
cursorMaxX |
int32_t |
Right clipping bound for cursor drawing. |
5.16. List Helper Library
Shared helper routines for dropdown and list-based widget DXEs (ListBox, Dropdown, ComboBox, ListView). Provides the owned-string item list, the single/multi-select model, drag-reorder helpers, the dropdown popup (state, geometry, painting, hit testing, and keyboard handling), dropdown arrow rendering, text measurement in any font (fixed-pitch or proportional), keyboard navigation, type-ahead search, popup scrollbar hit testing (with the same thumb geometry the window manager paints), and the icon view rules of Program Manager’s view, which BASIC icon views share through listhelp.bas.
Header: listhelp/listHelp.h
Loaded as: bin/libs/kpunch/listhelp/listhelp.lib
5.16.1. Constants
| Constant | Value | Description |
|---|---|---|
DROPDOWN_BTN_WIDTH |
16 |
Width of the dropdown arrow button in pixels. |
DROPDOWN_MAX_VISIBLE |
8 |
Maximum number of items visible in a popup list before scrolling. |
DROPDOWN_MIN_CHARS |
8 |
Minimum text-area width of a dropdown/combobox, in characters. |
DROPDOWN_BEVEL_W |
2 |
Bevel width of the dropdown/combobox text area and drop button. |
DROPDOWN_ARROW_ROWS |
4 |
Rows in the drop-arrow triangle. |
POPUP_BORDER |
2 |
Popup list border width; items start this far inside the popup. |
POPUP_SCROLLBAR_W |
SCROLLBAR_WIDTH |
Popup vertical scrollbar width (mirrors the core window-manager scrollbar width). |
LIST_REORDER_LINE_H |
2 |
Thickness of the drag-reorder insertion line. |
5.16.2. ListItemsT (owned-string item list)
Item list shared by ListBox, Dropdown, and ComboBox. items points either at a caller-owned array (isOwned false) or at owned, an stb_ds array of strdup’d strings (isOwned true). maxW caches the widest item’s width in pixels of the font widthFont stamps (not measured yet when it stamps none); listItemsMaxWidth returns it, measuring every item again when asked for another font, and the mutators keep it current incrementally. NULL entries in a caller’s array read as empty strings. Each item has a number of the program’s (Visual Basic’s ItemData): data, an stb_ds array as long as the list once one is set (NULL: all 0), which moves with its item. newIndex is the item added last (Visual Basic’s NewIndex), -1 after a removal, a clear, or a new list, and from listItemsInit. sorted (Visual Basic’s Sorted) makes an added item go in its place in the list’s order.
typedef struct {
const char **items;
char **owned;
int32_t *data;
FontStampT widthFont;
int32_t count;
int32_t maxW;
int32_t newIndex;
bool isOwned;
bool sorted;
} ListItemsT;
typedef void (*ListItemsMovedFnT)(void *ctx, int32_t from, int32_t dest);
bool listItemsAdd(ListItemsT *li, const BitmapFontT *font, const char *text);
int32_t listItemsAddIndex(const ListItemsT *li, const char *text);
void listItemsAdopt(ListItemsT *li);
bool listItemsClear(ListItemsT *li);
bool listItemsData(const ListItemsT *li, int32_t idx, int32_t *out);
void listItemsFree(ListItemsT *li);
const char *listItemsGet(const ListItemsT *li, int32_t idx);
void listItemsInit(ListItemsT *li);
bool listItemsInsert(ListItemsT *li, const BitmapFontT *font, int32_t idx, const char *text);
int32_t listItemsMaxWidth(ListItemsT *li, const BitmapFontT *font);
void listItemsMove(ListItemsT *li, int32_t from, int32_t dest);
bool listItemsRemove(ListItemsT *li, const BitmapFontT *font, int32_t idx);
bool listItemsSet(ListItemsT *li, const BitmapFontT *font, int32_t idx, const char *text);
void listItemsSetData(ListItemsT *li, int32_t idx, int32_t value);
bool listItemsSetExternal(ListItemsT *li, const BitmapFontT *font, const char **items, int32_t count);
bool listItemsSetSpec(ListItemsT *li, const BitmapFontT *font, const char *spec);
void listItemsSort(ListItemsT *li, ListItemsMovedFnT moved, void *ctx);
listItemsAddIndex is where an added item goes: in a sorted list after the items that sort before it or the same (case ignored, as a Visual Basic sorted ListBox orders them), else the end; listItemsAdd adds there, so listItemsSetSpec loads a sorted list in order. listItemsSort puts the items in order (the same rule; items that sort the same keep their order), each with its number and newIndex following its item, by moves it reports to moved (NULL: none) so the caller’s selection follows (listSelFollow, listIndexAfterMove). listItemsInit starts an empty list (newIndex -1); a list in zeroed memory must be given it. listItemsInsert puts text before item idx, which must be 0 to the count (the count appends; listItemsAdd is that), and makes it newIndex; listItemsMove moves item from to index dest (both in range), its number with it, and newIndex follows its item; listItemsSet gives item idx (in range) new text, keeping its number. listItemsData gives item idx’s number in *out (0 when none was set), false and 0 when there is no item idx; listItemsSetData sets one (idx in range), making the numbers at the first. The mutators first adopt (deep-copy) a caller’s array, so they change the list without modifying it. listItemsSetExternal keeps the previously owned strings until the next adopt, clear, or free, because the new array may point into them, and never reads the caller’s previous array (it may be freed already). The mutators measure in font, the widget’s own (wgtFont), and return true when the widest item’s width changed, i.e. when the widget’s minimum width changed and it needs a relayout rather than just a repaint. listItemsGet returns "" for an index out of range. listItemsSetSpec replaces the items with the pieces of a "Red|Green|Blue" spec (LIST_ITEMS_SEP; every "|" separates, so "a|" is "a" and an empty item, and "" empties the list): BASIC’s SetItems.
widgetAdoptOwnedStrings(owned, src, count) builds the deep copy that adoption uses (complete before the old strings are freed, so src may alias them) and widgetFreeOwnedStrings(owned) frees every string of an owned array and empties it. ListView uses both for its row-major cell copy.
5.16.3. ListSelT (selection model)
Selection state shared by ListBox and ListView. cursor is the current (keyboard) item and anchor the start of Shift ranges; bits holds one byte per item in multi-select mode. Every index is a data index; functions that take a display index also take an optional display-to-data order map (NULL = identity) so a sorted view selects what the user sees as a contiguous range.
typedef struct {
uint8_t *bits;
int32_t cursor;
int32_t anchor;
bool multi;
bool simple;
} ListSelT;
multi with simple is Visual Basic’s simple multiple selection (MultiSelect 1): a click selects or deselects its item alone and Shift makes no range; multi alone is the extended one (MultiSelect 2).
| Function | Description |
|---|---|
listSelInit(s) / listSelFree(s) |
Initialize (no cursor, no anchor) / free the bits. |
listSelReset(s, count) |
Rebuild the bits from scratch: all clear except the cursor item. |
listSelInsert(s, newCount, idx) |
An item was inserted at idx: existing selections are kept, cursor/anchor shift. |
listSelRemove(s, oldCount, idx) |
The item at idx was removed: bits close the gap, cursor/anchor shift; a removed cursor/anchor becomes -1. |
listSelReorder(s, from, dest) |
Drag-reorder moved an item: its bit moves with it and it becomes the cursor. |
listSelFollow(s, from, dest) |
The program moved an item (a sort): its bit moves with it, and the cursor and anchor stay on their items. |
listSelClick(s, count, order, disp, shift, ctrl) |
Mouse selection: plain, Ctrl (toggle), or Shift (range from the anchor); with simple, any click toggles its item. True when the cursor or any item’s selection changed (the list’s onChange then). |
listSelMove(s, count, order, disp, shift) |
Keyboard cursor move; Shift selects the range from the anchor (not with simple). True when the cursor or any item’s selection changed. |
listSelKey(s, count, key, mod) |
Multi-select Ctrl+A (ListSelKeyAllE) and Space (ListSelKeyToggleE); ListSelKeyNoneE otherwise. |
listSelSetCursor(s, count, idx) |
Programmatic selection: idx becomes the only selected item. |
listSelSetAll / listSelSetItem |
Set every bit / one bit; return false when there are no selection bits (not multi-select, or an empty list) or idx is out of range. |
listSelIsSelected(s, count, idx) |
Bit state in multi-select mode, idx == cursor otherwise. |
listDisplayRowOf(order, count, dataIdx) |
Display row of a data index (-1 if none). |
listIndexAfterRemove(idx, removed) |
Where an index ends up after a removal (-1 if it was removed). |
listIndexAfterMove(idx, from, dest) |
Where an index ends up after an item moved. |
listIndexSettable(idx, count) |
True when idx is -1 (none) to count - 1: what Visual Basic’s ListIndex takes (a widget’s BASIC ListIndex refuses any other). |
listTopIndexSettable(idx, count) |
True when idx is an item (0 on an empty list): what Visual Basic’s TopIndex takes (a widget’s BASIC TopIndex refuses any other). |
5.16.4. Drag-Reorder Helpers
void listReorderCancel(WidgetT *w, int32_t *pDragIdx, int32_t *pDropIdx);
int32_t listReorderDest(int32_t from, int32_t to, int32_t count);
void listReorderMove(void *base, size_t elemSize, int32_t from, int32_t dest);
void listReorderTrack(int32_t relY, int32_t rowH, int32_t visibleRows, int32_t count, int32_t *pScrollPos, int32_t *pDropIdx);
void listReorderPaint(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t top, int32_t w, int32_t h, int32_t rowH, int32_t scrollPos, int32_t dropIdx, uint32_t color);
listReorderCancel abandons an item drag when the list changes under it (an item is removed or the items are replaced): it resets both indices and, when w is dragging an item, ends the drag so the rest of the mouse motion is ignored. listReorderDest maps a drag from item from to insertion point to (0..count) to the item’s final index, or -1 when the drop is a no-op. listReorderMove moves one element of any size in place (a ListView row is colCount pointers). listReorderTrack updates the drop index from the pointer position and auto-scrolls one row when the pointer is on the first or last visible row. listReorderPaint draws the insertion line.
5.16.5. ListPopupT (dropdown popup)
Popup state shared by Dropdown and ComboBox: the item list plus the selected item, the hovered item, the popup scroll position, and whether it is open.
typedef struct {
ListItemsT items;
int32_t selectedIdx;
int32_t hoverIdx;
int32_t scrollPos;
bool open;
} ListPopupT;
| Function | Description |
|---|---|
listPopupInit(p) |
No selection, no hover, closed. |
listPopupAddItem / listPopupRemoveItem |
Item list edits; the selection and hover stay on the same item (-1 when it is removed). AddItem puts the item where listItemsAddIndex says (a sorted list’s place for it). |
listPopupSort(w, p) |
Put the items in order (listItemsSort), the selection and hover on their items: Sorted made True. |
listPopupInsertItem(w, p, idx, text) |
Insert before item idx (0 to the count); the selection and hover stay on their items. |
listPopupSetItem(w, p, idx, text) |
Give item idx new text (listItemsSet). |
listPopupSetItemData(p, idx, value) |
Set item idx’s number (listItemsSetData). |
(the four that take an index) |
listPopupInsertItem, listPopupRemoveItem, listPopupSetItem, and listPopupSetItemData return false, doing nothing, for an index out of range. |
listPopupClearItems / listPopupSetItems |
Replace the items; an out-of-range selection becomes -1. A sorted popup sorts its copy of the items listPopupSetItems gives it. |
listPopupSetItemsSpec(w, p, spec) |
Replace the items with a "Red|Green|Blue" spec (listItemsSetSpec); nothing is selected. |
listPopupOpen(w, p) |
Open at the popup’s scroll position (where listPopupSetTopIndex put it, or where it was left), the selection hovered and scrolled into view when it is out of it. |
listPopupSetTopIndex(w, p, idx) |
Item idx at the top of the list (Visual Basic’s TopIndex), as far as it scrolls (near the end the last item stays at the bottom); the list opens there, and an open one scrolls now. The scroll position (scrollPos) is the TopIndex to read. |
listPopupDropDown(w, p) |
The user opens the list (a click, F4, Alt+Down, Alt+Up, the access key): the control’s DropDown event (LISTPOPUP_EVT_DROPDOWN, wgtFireEvent) first, as Visual Basic raises it, then listPopupOpen. False when the handler destroyed widgets (the list stays shut). |
listPopupClose(w, p) |
WGT_METHOD_CLOSE_POPUP body. |
listPopupCommit(p) |
Close and make the hovered item the selection (listPopupTakeHover); true when that changed the selection. |
listPopupTakeHover(p) |
Make the hovered item the selection, the list staying open (a ComboBox makes each key move in its open list a pick, as Visual Basic’s does); true when that changed the selection. |
listPopupNavKey(p, key) |
Up/Down move the hover item, a printable key jumps to the next matching item. |
listPopupOnWheel(w, p, delta) |
WGT_METHOD_ON_WHEEL body: an open list scrolls by the wheel step a notch, moving nothing; a closed one steps the choice one item a notch through the control’s own Down and Up keys. True when taken. |
listPopupOnMouse(w, p, vx, vy) |
Click while open: ListPopupHitScrollE (scrollbar), ListPopupHitItemE (item selected, closed), or ListPopupHitNoneE (closed). |
listPopupItemAt(p, font, popY, vy) |
Item under vy, or -1 on the border or past the last item. |
listPopupPaint(w, p, ...) |
Overlay paint; uses the window content height, the same source as the hit test. |
listPopupDrawFrame(d, ops, colors, w, bg, down) |
Sunken text area plus the drop button and arrow. |
listPopupCalcMinSize(w, font, p) |
Minimum size from the widest item in font. |
listPopupEnsureVisible(p) |
Scroll the hover item into view. |
listPopupVisibleCount(itemCount) |
Rows the popup shows (1..DROPDOWN_MAX_VISIBLE). |
5.16.6. widgetDrawDropdownArrow
Draw the triangular dropdown arrow glyph centered at a given position.
void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops, int32_t centerX, int32_t centerY, uint32_t color);
| Parameter | Description |
|---|---|
d |
Display context. |
ops |
Blit operations vtable for the active pixel depth. |
centerX |
Horizontal center of the arrow in backbuffer coordinates. |
centerY |
Vertical center of the arrow in backbuffer coordinates. |
color |
Pre-packed pixel color for the arrow. |
5.16.7. widgetMaxItemWidth
Scan an array of strings and return the width in pixels of the widest item in a font.
int32_t widgetMaxItemWidth(const BitmapFontT *font, const char **items, int32_t count);
| Parameter | Description |
|---|---|
font |
Font the items are drawn in (fixed-pitch or proportional). |
items |
Array of null-terminated string pointers (NULL entries count as empty). |
count |
Number of items in the array. |
Returns the width of the widest item, or 0 if count is zero.
5.16.8. listTextFit
How many leading characters of text fit whole in maxW pixels of font: the part of an item a list draws when the item is cut to its column. Stops at the end of the text; 0 when maxW is too narrow for the first character.
int32_t listTextFit(const BitmapFontT *font, const char *text, int32_t maxW);
5.16.9. widgetNavigateIndex
Compute a new selected index from a navigation key press. Handles Up, Down, Home, End, Page Up, and Page Down.
int32_t widgetNavigateIndex(int32_t key, int32_t current, int32_t count, int32_t pageSize);
| Parameter | Description |
|---|---|
key |
Keyboard scancode (Up, Down, Home, End, PgUp, PgDn). |
current |
Currently selected index. |
count |
Total number of items in the list. |
pageSize |
Number of visible items (used for PgUp/PgDn step size). |
Returns the new index, clamped to [0, count-1]. Returns -1 for unrecognized keys so callers can detect whether the key was consumed.
5.16.10. widgetGridNavigateIndex
The same keys in a grid of count items laid out row by row, columns items per row (icon views): Left and Right step through the items in order, Up, Down, Page Up, and Page Down move by rows (pageRows rows a page) the way widgetNavigateIndex moves through a list — it is called on the row numbers — keeping the column, or landing on the last item when the row below is shorter; Home and End go to the first and last item. With nothing selected (current below 0) every one of these keys goes to the first item. With one column it gives what widgetNavigateIndex gives.
int32_t widgetGridNavigateIndex(int32_t key, int32_t current, int32_t count, int32_t columns, int32_t pageRows);
Returns the new index, or -1 for any other key.
5.16.11. widgetDropdownPopupRect
Calculate the screen rectangle for a dropdown popup list, positioning it below the owning widget and clamping to screen bounds.
void widgetDropdownPopupRect(const WidgetT *w, const BitmapFontT *font, int32_t contentH, int32_t itemCount, int32_t *popX, int32_t *popY, int32_t *popW, int32_t *popH);
| Parameter | Description |
|---|---|
w |
The widget that owns the popup (Dropdown, ComboBox, etc.). |
font |
Bitmap font used for item text (determines row height). |
contentH |
Height of the widget’s content area in pixels. |
itemCount |
Total number of items in the list. |
popX |
Output: popup X position (screen coordinates). |
popY |
Output: popup Y position (screen coordinates). |
popW |
Output: popup width in pixels. |
popH |
Output: popup height in pixels. |
The popup is sized to show up to DROPDOWN_MAX_VISIBLE items.
5.16.12. widgetPaintPopupList
Render a popup item list with highlight, scrolling, and beveled border. When itemCount exceeds DROPDOWN_MAX_VISIBLE, draws a vertical scrollbar on the right edge sized according to scrollPos.
void widgetPaintPopupList(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, int32_t popX, int32_t popY, int32_t popW, int32_t popH, const char **items, int32_t itemCount, int32_t hoverIdx, int32_t scrollPos);
| Parameter | Description |
|---|---|
d |
Display context. |
ops |
Blit operations vtable. |
font |
Bitmap font for rendering item text. |
colors |
Color scheme for background, text, and highlight colors. |
popX |
Popup X position (from widgetDropdownPopupRect). |
popY |
Popup Y position. |
popW |
Popup width. |
popH |
Popup height. |
items |
Array of null-terminated item strings. |
itemCount |
Total number of items. |
hoverIdx |
Index of the highlighted (hovered/selected) item, or -1 for none. |
scrollPos |
Index of the first visible item (scroll offset). |
5.16.13. widgetTypeAheadFind
The lists' type-ahead, the Windows rule that ListBox, ListView, TreeView, Dropdown, ComboBox’s list, and Program Manager’s icons all follow: the keys typed in one list less than LIST_TYPEAHEAD_MS (1000) apart make up the text looked for, so "ma" goes to the first item starting with "ma", counting from the current item itself (an item that still matches stays). A first key, or one letter typed again and again, goes to the next item starting with that letter, wrapping around. Case does not matter. list is any pointer naming the list (its widget): a key typed in another list starts afresh.
#define LIST_TYPEAHEAD_MS 1000
#define LIST_TYPEAHEAD_MAX 32
typedef const char *(*ListItemTextFnT)(const void *ctx, int32_t idx);
int32_t widgetTypeAheadFind(const void *list, char ch, const char **items, int32_t itemCount, int32_t currentIdx);
int32_t widgetTypeAheadFindAt(const void *list, char ch, int32_t itemCount, int32_t currentIdx, ListItemTextFnT textOf, const void *ctx);
const char *widgetTypeAheadText(const void *list, char ch, int32_t *outStart);
bool widgetTypeAheadHas(const char *prefix, const char *text);
widgetTypeAheadFind looks in items[] (NULL entries never match) from currentIdx (-1: none) and returns the item, or -1 when none matches. widgetTypeAheadFindAt is the same with each item’s text from textOf(ctx, idx) (ListView passes its rows in display order). A list that is not indexed (a tree) asks widgetTypeAheadText for the text to look for, with *outStart 0 when the look starts at the current item itself and 1 when at the one after it, and tests each item with widgetTypeAheadHas (text starts with prefix, case-insensitive; NULL text never matches). BASIC: ListSelTypeAhead (listhelp.bas), with the selection handle naming the list.
5.16.14. widgetTypeAheadMatch
True when text starts with ch (case-insensitive). NULL text never matches.
bool widgetTypeAheadMatch(char ch, const char *text);
5.16.15. widgetTypeAheadSearch
One key alone, with no memory of the keys before it. Scans items forward from currentIdx + 1, wrapping around, for the next item whose first character matches ch (case-insensitive). The widgets use widgetTypeAheadFind; BASIC’s ListTypeAhead is this.
int32_t widgetTypeAheadSearch(char ch, const char **items, int32_t itemCount, int32_t currentIdx);
| Parameter | Description |
|---|---|
ch |
Character to match (case-insensitive). |
items |
Array of null-terminated item strings. |
itemCount |
Number of items in the array. |
currentIdx |
Currently selected index (search starts at currentIdx + 1 and wraps). |
Returns the index of the next matching item, or -1 if no match is found or itemCount is not positive.
5.16.16. widgetPopupScrollbarClick
Hit-test a popup scrollbar click. Tests whether the (x, y) coordinate falls on the popup’s vertical scrollbar track; if so, updates scrollPos for up/down arrow clicks or page-up/page-down clicks in the trough. No-op on the thumb itself (callers handle drag separately).
bool widgetPopupScrollbarClick(int32_t x, int32_t y, int32_t popX, int32_t popY, int32_t popW, int32_t popH, int32_t itemCount, int32_t visibleItems, int32_t *scrollPos);
| Parameter | Description |
|---|---|
x |
Click X in the popup’s coordinate space. |
y |
Click Y in the popup’s coordinate space. |
popX |
Popup X origin. |
popY |
Popup Y origin. |
popW |
Popup width. |
popH |
Popup height. |
itemCount |
Total number of items. |
visibleItems |
Number of visible rows in the popup. |
scrollPos |
[in/out] Current scroll offset; updated in place when the click hits the scrollbar. |
Returns true if the click landed on the scrollbar (even if scrollPos was not changed, for example clicking the thumb), false if the click was in the item list area. When itemCount is less than or equal to DROPDOWN_MAX_VISIBLE, always returns false (there is no scrollbar).
5.16.17. Icon Views
The rules of an icon view with large icons, small icons, or a list: Program Manager’s view (progman/pmView.c) is built on them, and so are icon views written in BASIC (listhelp.bas ListIcon...), so both look and behave alike. They cover each view’s cell and where an item’s picture and name go in it, the grid inside a sunken frame with a scroll bar only when the rows do not fit (which narrows the grid), the two label lines under a large icon, the arrow keys among items in order or in cells of their own (gaps allowed), the scroll bar (a control’s, as ListBox’s: arrows, trough, thumb drag), when a press becomes a drag, the scrolling and the target cell while dragging, and where a dropped item lands. Positions are pixels from the view’s top left (ListIconGridT) or the cell’s (ListIconCellT).
| Constant | Value | Description |
|---|---|---|
LIST_ICON_FRAME |
2 |
Sunken frame around the view. |
LIST_ICON_PAD |
2 |
Cell edge to its picture; inside of the frame to the empty text. |
LIST_ICON_LARGE |
32 |
Large icon edge. |
LIST_ICON_SMALL |
16 |
Small icon edge. |
LIST_ICON_LABEL_GAP |
2 |
Large icon to its label. |
LIST_ICON_LABEL_LINES |
2 |
Label lines under a large icon. |
LIST_ICON_TEXT_GAP |
4 |
Small icon to its name. |
LIST_ICON_LARGE_CELL_W |
80 |
Large icon cell width. |
LIST_ICON_SMALL_CHARS |
14 |
Name beside a small icon, in characters. |
LIST_ICON_LIST_CHARS |
24 |
The list’s name column, in characters. |
LIST_ICON_COLUMN_GAP |
1 |
The list’s name column to its detail column, in characters. |
LIST_ICON_DRAG_SLOP |
4 |
Pixels a press moves (either way) before it drags. |
LIST_ICON_WHEEL_ROWS |
1 |
Rows a wheel notch scrolls. |
LIST_ICON_LINE_ROWS |
1 |
Rows an arrow key or a scroll bar arrow moves. |
LIST_ICON_SB_W |
WGT_SB_W |
The scroll bar’s width: a control’s (ListBox’s). |
LIST_ICON_NO_CELL |
-1 |
No cell (outside the grid). |
LIST_ICON_BY_ORDER |
-1 |
listIconGrid rowsTaken: the items fill the grid in order. |
typedef enum { ListIconLargeE, ListIconSmallE, ListIconListE, ListIconViewCountE } ListIconViewE;
typedef enum { ListIconScrollNoneE, ListIconScrollMovedE, ListIconScrollThumbE } ListIconScrollE;
typedef struct {
int32_t cellW; // a list row spans the grid
int32_t cellH;
int32_t pictureX; // the picture, pictureSize square
int32_t pictureY;
int32_t pictureSize;
int32_t textX; // the name (large icons: each line centered, textX 0)
int32_t textY;
int32_t nameChars; // its length (a large icon's: per line)
int32_t detailX; // the list's detail column, 0 in the other views
} ListIconCellT;
typedef struct {
ListIconCellT cell;
int32_t innerX; // inside the frame, less the scroll bar
int32_t innerY;
int32_t innerW;
int32_t innerH;
int32_t cols;
int32_t rowsVisible; // rows shown whole
int32_t totalRows;
int32_t maxScroll; // the largest top row
int32_t emptyX; // the empty view's text
int32_t emptyY;
bool needSb; // the scroll bar stands right of innerW, innerH tall
} ListIconGridT;
void listIconCellLayout(ListIconViewE view, int32_t charW, int32_t charH, int32_t innerW, ListIconCellT *out);
void listIconGrid(ListIconViewE view, int32_t charW, int32_t charH, int32_t viewW, int32_t viewH, int32_t count, int32_t rowsTaken, ListIconGridT *out);
int32_t listIconGridMetric(const ListIconGridT *g, ListIconMetricE metric);
int32_t listIconCellAt(const ListIconGridT *g, int32_t x, int32_t y, int32_t scrollRow, int32_t *outCol, int32_t *outRow);
void listIconLabelSplit(const char *name, int32_t maxChars, int32_t *len1, const char **line2, int32_t *len2);
int32_t listIconNavigate(int32_t key, int32_t current, const int32_t *cols, const int32_t *rows, int32_t count, int32_t gridCols, int32_t pageRows);
bool listIconDragStarted(int32_t dx, int32_t dy);
int32_t listIconDragScroll(const ListIconGridT *g, int32_t y, int32_t scrollRow);
int32_t listIconDropCell(const ListIconGridT *g, int32_t x, int32_t y, int32_t scrollRow, int32_t *outCol, int32_t *outRow);
int32_t listIconDropDest(int32_t from, int32_t cell, int32_t count);
ListIconScrollE listIconScrollPress(const ListIconGridT *g, int32_t x, int32_t y, int32_t *pScrollRow, int32_t *outGrab);
int32_t listIconScrollDrag(const ListIconGridT *g, int32_t y, int32_t grab);
| Function | Description |
|---|---|
listIconCellLayout |
The cell of a view whose grid is innerW wide. Large icons: LIST_ICON_LARGE_CELL_W wide, the picture centered at the top, two label lines under it. Small icons and the list: a row as tall as the font or the small picture (plus padding), the picture then the name; the list’s row spans the grid and adds a detail column. |
listIconGrid |
The grid of a view viewW x viewH (frame included) holding count items: laid out without a scroll bar first, with one LIST_ICON_SB_W wide (narrowing the grid) only when the rows do not fit. rowsTaken is LIST_ICON_BY_ORDER for items in order (count / columns rows, rounded up) or the rows items placed in cells of their own take. |
listIconGridMetric |
One value of a grid by ListIconMetricE (ListIconCellWE ... ListIconWheelRowsE; the scroll bar as 1 / 0; 0 for an unknown metric). The BASIC binding reads the grid through it. |
listIconCellAt |
The cell number (row * cols + col) under x, y of a view scrolled to scrollRow, with its column and row; LIST_ICON_NO_CELL outside the grid or right of the last column. |
listIconLabelSplit |
A large icon’s two label lines maxChars wide: the first ends at the last blank that fits (else it is cut at maxChars), the second starts after the blanks there and is cut to maxChars. *line2 points into name; *len2 is 0 when the name fits one line. |
listIconNavigate |
The item an arrow key, Home, End, PgUp, or PgDn moves to when item i stands in cell (cols[i], rows[i]): Left / Right the nearest before / after in reading order, Up / Down the nearest row above / below with the closest column, PgUp / PgDn the same pageRows away, Home / End the first / last in reading order; with no current item the first. For items in order it gives what widgetGridNavigateIndex gives. -1 for another key or when no item is that way. |
listIconDragStarted |
True when a press has moved LIST_ICON_DRAG_SLOP pixels either way. |
listIconDragScroll |
The top row after a drag move to y: one row up above the grid, one down below it. |
listIconDropCell |
The cell a dragged item would drop on with the pointer at x, y, held inside the grid’s height (listIconCellAt). |
listIconScrollPress |
A left press at x, y: ListIconScrollNoneE left of the scroll bar or without one; else widgetScrollbarApplyHit — an arrow moves *pScrollRow LIST_ICON_LINE_ROWS, the trough a page (ListIconScrollMovedE), the thumb is grabbed (ListIconScrollThumbE, *outGrab how far below its top). |
listIconScrollDrag |
The top row with the grabbed thumb dragged to y (widgetScrollbarThumbDragScroll). |
listIconDropDest |
Items in order: the index an item dragged from `from` takes when dropped on cell number cell (that cell’s, the last for a cell past the end); -1 when that changes nothing or from / cell is out of range. |
charW and charH are the caller’s character metrics (a font’s charWidth and charHeight, or numbers from BASIC, which has no font handle here): rows are a line tall, and a name field or column N characters wide is N * charW. A large icon’s label is cut by characters (nameChars, listIconLabelSplit): exact for a fixed-pitch font, an estimate for a proportional one.
Program Manager’s pmView.c draws the scroll bar with widgetDrawScrollbarV; a BASIC icon view draws the same bar with DrawScrollBar’s control argument True.
5.17. List Helper Library: BASIC
5.17.1. BASIC
src/include/basic/listhelp.bas gives BASIC programs — above all UserControls that draw a list or an icon view themselves — the rules of this library (listHelpBas.c), so their lists behave like ListBox and ListView. A selection handle (1, 2, ...; 0 = none) holds a ListSelT and the item count it covers; display order is data order (no order map). Each handle records the program that made it; the shell’s app-cleanup hook frees what a program leaves open.
| BASIC | C it calls |
|---|---|
ListSelCreate(multi, count), ListSelFree, ListSelReset(h, count), ListSelCount(h) |
listSelInit + listSelReset; listSelFree; listSelReset then listSelSetCursor (a cursor past the end becomes -1). |
ListSelClick h, index, shift |
listSelClick; shift is the event’s Shift (vbShiftMask = range, vbCtrlMask = toggle). |
ListSelKey(h, keyCode, shift) |
listSelKey: LISTSEL_KEY_NONE, LISTSEL_KEY_ALL (Ctrl+A), LISTSEL_KEY_TOGGLE (Space). |
ListSelNavigate(h, keyCode, shift, columns, pageRows) |
widgetGridNavigateIndex from the cursor, then listSelMove; the new cursor, or -1 when the key does not move it. |
ListSelMove h, index, shift |
listSelMove. |
ListSelCursor(h), ListSelSetCursor h, index |
ListSelT.cursor; listSelSetCursor. |
ListSelIsSelected(h, index), ListSelSelectedCount(h) |
listSelIsSelected; how many are. |
ListSelSetItem h, index, selected; ListSelSetAll h, selected |
listSelSetItem; listSelSetAll. |
ListSelInsert h, index; ListSelRemove h, index |
listSelInsert / listSelRemove (the handle’s count follows). |
ListSelReorder h, fromIndex, dest |
listSelReorder. |
ListSelFollow h, fromIndex, dest |
listSelFollow. |
ListSelSetSimple h, simple |
ListSelT.simple: True makes a multi-selection’s clicks Visual Basic’s simple ones. |
ListReorderDest(fromIndex, toSlot, count) |
listReorderDest. |
ListNavigateIndex(keyCode, current, count, pageSize) |
widgetNavigateIndex. |
ListGridNavigate(keyCode, current, count, columns, pageRows) |
widgetGridNavigateIndex. |
ListSelTypeAhead(sel, ch, items) |
widgetTypeAheadFind over items separated by CHR$(10), from the selection’s current item; the handle names the list. |
ListTypeAhead(ch, items, current) |
widgetTypeAheadSearch over items separated by CHR$(10). |
ListTypeAheadMatch(ch, text) |
widgetTypeAheadMatch. |
ListIconMetric(mode, metric, cw, ch, w, h, count, rowsTaken) |
listIconGrid, then listIconGridMetric; LISTICON_SCROLLBAR as True / False. |
ListIconCellAt(mode, cw, ch, w, h, count, rowsTaken, topRow, x, y) |
listIconGrid, then listIconCellAt. |
ListIconDragScroll(mode, cw, ch, w, h, count, rowsTaken, topRow, y) |
listIconGrid, then listIconDragScroll. |
ListIconDropCell(mode, cw, ch, w, h, count, rowsTaken, topRow, x, y) |
listIconGrid, then listIconDropCell. |
ListIconDropDest(fromIndex, cell, count) |
listIconDropDest. |
ListIconDragStarted(dx, dy) |
listIconDragStarted. |
ListIconLabel$(name, maxChars, lineNo) |
listIconLabelSplit: line 1 or 2 ("" for any other line number or a line the name does not need). |
ListIconNavigate(keyCode, current, cells, columns, pageRows) |
listIconNavigate over cells given as text: each item’s column and row, every number separated by a comma. |
ListIconScrollPress(mode, cw, ch, w, h, count, rowsTaken, topRow, x, y) |
listIconScrollPress: the new top row, -1 when not on the scroll bar. |
ListIconScrollGrab(mode, cw, ch, w, h, count, rowsTaken, topRow, x, y) |
listIconScrollPress: the grab offset when the thumb is hit, else -1. |
ListIconScrollDrag(mode, cw, ch, w, h, count, rowsTaken, grab, y) |
listIconScrollDrag. |
An icon view’s grid is figured from the view’s size on each call (no handle). The LISTSEL_KEY_ and LISTICON_ CONSTs of listhelp.bas are compared with ListSelKeyE, ListIconViewE, LIST_ICON_BY_ORDER, and ListIconMetricE by a formrt test.
5.18. Styled Text Library
Styled text and RTF in and out: the document of the RichEdit widget, and of its undo steps and clipboard. A RichTextT is text in code page 437 with '\n' between paragraphs, covered by runs — each from an offset to the next run’s, in a style (font family, pixel size, bold, italic, underline, strike-through, and color) — and one alignment per paragraph. It needs no widget: a program can build, edit, and convert styled text with it alone.
Header: richtext/richText.h
Loaded as: bin/libs/kpunch/richtext/richtext.lib
5.18.1. Types
| Type | Fields |
|---|---|
RichStyleT |
family (FONT_FAMILY_MAX; "" = the default family), size (pixels; 0 = the default size), style (FONT_STYLE_*), color (0x00RRGGBB or RICH_COLOR_DEFAULT) |
RichRunT |
start (the first character’s offset), style (an index in RichTextT.styles) |
RichTextT |
text, runs, styles, aligns: stb_ds arrays; the text has no NUL, the first run starts at 0, styles[0] is the default style, one alignment (FLOW_ALIGN_*) per paragraph |
RichChangeT |
set (RICH_SET_FAMILY, RICH_SET_SIZE, RICH_SET_COLOR), styleMask (the FONT_STYLE_* bits to set to to.style’s), to (the new values) |
The default family, size, and color are a RichEdit control’s own font and ForeColor, so text in them follows the control. Styles are interned: one look is one index, so neighboring runs never share a style and no run covers nothing (but the one of an empty text). Running out of memory ends the program, as stb_ds does everywhere in DVX.
5.18.2. Constants
| Constant | Value | Description |
|---|---|---|
RICH_COLOR_DEFAULT |
FLOW_COLOR_DEFAULT |
A run in the default color |
RICH_TAB_SPACES |
4 |
The spaces a tab in plain text or RTF becomes (DVX text has no tabs) |
RICH_SET_FAMILY |
0x0001 |
RichChangeT.set: change the family |
RICH_SET_SIZE |
0x0002 |
RichChangeT.set: change the size |
RICH_SET_COLOR |
0x0004 |
RichChangeT.set: change the color |
5.18.3. Styled Text
void richTextInit(RichTextT *rt);
void richTextClear(RichTextT *rt);
void richTextFree(RichTextT *rt);
int32_t richTextLength(const RichTextT *rt);
int32_t richTextIntern(RichTextT *rt, const RichStyleT *style);
int32_t richTextRunAt(const RichTextT *rt, int32_t offset);
int32_t richTextStyleAt(const RichTextT *rt, int32_t offset);
int32_t richTextParaCount(const RichTextT *rt);
int32_t richTextParaOf(const RichTextT *rt, int32_t offset);
int32_t richTextParaStart(const RichTextT *rt, int32_t para);
int32_t richTextParaEnd(const RichTextT *rt, int32_t para);
int32_t richTextAlign(const RichTextT *rt, int32_t para);
void richTextSetAlign(RichTextT *rt, int32_t first, int32_t last, int32_t align);
void richTextCopy(const RichTextT *src, int32_t from, int32_t to, RichTextT *dst);
int32_t richTextReplace(RichTextT *rt, int32_t from, int32_t to, const RichTextT *what);
int32_t richTextInsertPlain(RichTextT *rt, int32_t at, const char *text, int32_t len, int32_t style);
void richTextFromPlain(RichTextT *rt, const char *text, int32_t len, const RichStyleT *style);
void richTextRestyle(RichTextT *rt, int32_t from, int32_t to, const RichChangeT *change);
RichStyleT richStyleChanged(const RichStyleT *style, const RichChangeT *change);
| Function | Description |
|---|---|
richTextInit / Clear |
An empty text: one empty, left-aligned paragraph in the default style. Free releases the arrays. |
richTextIntern |
The index of a style, added when the text has none like it. |
richTextRunAt |
The run the character at an offset is in (at the end, the last run); richTextStyleAt its style. |
richTextPara* |
Paragraph count; the paragraph an offset is in (its '\n' belongs to it); where one starts and ends (its '\n' or the text’s end); its alignment. |
richTextCopy |
A range as a text of its own: its characters, runs, the styles they use, and the alignments of the paragraphs it touches. |
richTextReplace |
Replace a range with a text (NULL deletes). Joined paragraphs keep the first one’s alignment; each paragraph the new text starts takes its alignment from it. Returns the length inserted. |
richTextInsertPlain |
Insert plain text in a style: '\r' dropped, a tab as RICH_TAB_SPACES spaces, '\n' starting a paragraph aligned as the one it is in. |
richTextFromPlain |
The whole text as plain text in one style, made the default style. |
richTextRestyle |
Apply a RichChangeT to a range; richStyleChanged applies one to a single style. |
Undo works by these: before a change, richTextCopy saves the range it replaces; undoing replaces what the change put there with the saved copy. A copy taken, deleted, and put back gives the text it came from exactly — characters, runs, styles, and alignments.
5.18.4. RTF
bool richRtfIs(const char *text, int32_t len);
char *richRtfWrite(const RichTextT *rt, const char *defaultFamily, int32_t *outLen);
bool richRtfRead(RichTextT *rt, const char *text, int32_t len);
richRtfWrite returns a NUL-terminated RTF document (malloc’d; NULL when out of memory): a font table whose font 0 is defaultFamily (the default family is written as font 0 with no size, and read back as the default), a color table whose entry 0 is the default color, then each paragraph as \pard and its alignment, ended by \par, each run as \plain and its whole style. ASCII characters are themselves; the rest are \uN with a '?' for readers without Unicode. richRtfRead replaces rt with what an RTF document holds and returns false, leaving rt alone, when the text is not RTF.
The subset read: \fonttbl and \f, \fs (half points; a pixel is taken as 3/4 point, so \fs24 is 16 pixels), \b, \i, \ul, \strike, and their ends, \ulnone, \plain, \colortbl and \cf, \par, \pard, \ql, \qc, \qr (\qj as left; \line as a new paragraph), \tab, \'hh (Windows-1252), \uN with \ucN, the escapes \\ \{ \} \~ \_, and quotes and dashes as their ASCII forms. Characters are stored as code page 437, '?' for those it lacks. Destinations such as \info, \stylesheet, \pict, headers, footers, and every \* group are skipped.
5.19. Styled Text Library: BASIC
Source: richtext/richTextBas.c; BASIC declarations: src/include/basic/richtext.bas (DECLARE LIBRARY "richtext").
const char *RtfToText(const char *rtf);
const char *TextToRtf(const char *text);
RtfToText$ is the text of an RTF document, a line per paragraph (text that is not RTF comes back as it is); TextToRtf$ is plain text as RTF in the system font, a paragraph per line. A result stays valid until the next call. The RichEdit control’s TextRTF, SelRTF, LoadFile, and SaveFile cover RTF in a control.
5.20. Help File Library
Reads compiled DVX help files (.hlp, written by the help compiler dvxhlpc or HelpCompile): topics, the table of contents, the keyword index, each topic’s content records in order, pictures, and full-text search. DVX Help, the HelpView widget (BASIC HelpPane), and BASIC’s hlpfile.bas all read help files through it, so they find, search, and show topics the same way.
Header: hlpfile/hlpFile.h (the file format: hlpfile/hlpFormat.h, shared with the help compiler)
Loaded as: bin/libs/kpunch/hlpfile/hlpfile.lib
5.20.1. Opening and Topics
A file is an opaque HlpFileT. Strings returned point into the file’s string table and stay valid until hlpFileClose.
| Function | Description |
|---|---|
hlpFileOpen(path) |
Open a help file; NULL when it cannot be read or is not a help file. The header, topic directory, strings, table of contents, index, and search index are read at once; topic content and pictures are read when asked for. |
hlpFileClose(f) |
Close it (NULL is ignored). |
hlpFileTopicCount(f) |
Number of topics. |
hlpFileTopicId(f, topic) / Title(f, topic) |
A topic’s ID (what links and HelpTopic name) and title; "" out of range. |
hlpFileFindTopic(f, topicId) |
The topic with that ID, or -1. |
hlpFileStartTopic(f, topicId) |
The topic to open for "file [topic]": topicId (NULL or "" for none), else the file’s .default topic, else the first; -1 for a file with no topics. |
hlpFileString(f, offset) |
A string table entry ("" out of range). |
hlpFileTocCount(f) / hlpFileToc(f, i) |
Table of contents entries (HlpTocEntryT: title string, topic or HLP_NO_TOPIC for a section heading, depth, HLP_TOC_EXPANDED flag). |
hlpFileIndexCount(f) / hlpFileIndex(f, i) |
Keyword index entries (HlpIndexEntryT: keyword string, topic), sorted. |
5.20.2. Records and Pictures
hlpFileForEachRecord(f, topic, fn, userData) calls fn(hdr, payload, userData) for each record of a topic in order (HLP_REC_TEXT, HEADING1 .. 3, LIST_ITEM, NOTE with its HLP_NOTE_ kind in hdr->flags, CODE, TABLE, IMAGE with its HLP_IMG_ alignment, LINK, HRULE); the payload is NUL-terminated. fn returns false to stop. hlpRecordLink gives a link record’s target topic ID and display text (the target when the text is empty); hlpRecordImage its picture’s place in the file, and hlpFileReadImage the picture itself: the image file as the compiler took it in (BMP, PNG, JPEG, or GIF), malloc’d, for dvxLoadImageAlpha. Reading a picture inside the record walk is safe.
hlpWrapText(text, cols) wraps flowing text at cols columns (at least HLP_MIN_WRAP_COLS) as the viewer does, a malloc’d copy with '\n' at the wrap points.
5.20.3. Search
hlpFileSearch(f, query, matches) finds the topics whose title or text (paragraphs, headings, lists, notes, code, tables, and the text links show) contains every word of query (any case, separated by blanks), plus those with an index keyword containing the whole query, setting matches[topic] (hlpFileTopicCount bytes) and returning the count (-1 on a failure). The query is not changed. The compiler’s trigram index narrows the candidates first; the trigram characters (hlpTrigramSymbol) and the record types searched (hlpRecordSearchable) are defined once in hlpFormat.h for both. Words with no three letters or digits in a row cannot use the index, so then only titles and keywords are searched.
uint8_t *matches = malloc(hlpFileTopicCount(f));
int32_t n = hlpFileSearch(f, "serial port", matches);
for (int32_t t = 0; n > 0 && t < hlpFileTopicCount(f); t++) {
if (matches[t]) {
printf("%s\n", hlpFileTopicTitle(f, t));
}
}
free(matches);
5.21. Help File Library: BASIC
5.21.1. BASIC
src/include/basic/hlpfile.bas declares the BASIC functions (hlpFileBas.c): HlpOpen, HlpClose, HlpTopicCount, HlpTopicId$, HlpTopicTitle$, HlpFindTopic, HlpStartTopic, HlpTocCount, HlpTocTitle$, HlpTocTopic, HlpTocDepth, HlpTocExpanded, HlpIndexCount, HlpIndexKeyword$, HlpIndexTopic, HlpSearch, HlpSearchTopic, HlpLoadTopic, HlpRecordType, HlpRecordFlags, HlpRecordText$, HlpRecordLink$, HlpRecordImageSave, and HlpWrap$, with the HLP_REC_, HLP_NOTE_, and HLP_IMG_ constants of hlpFormat.h.
A handle (a small number, 0 = none) is an open file plus what the program last asked of it — HlpSearch keeps the topics found for HlpSearchTopic, HlpLoadTopic copies a topic’s records for the HlpRecord functions — since BASIC cannot take a callback or a byte array. Each handle records the program that opened it; the shell’s app-cleanup hook closes what a program leaves open when it ends. hlpFileBasHandle(handle) gives the HlpFileT behind a handle to C code (the HelpPane control’s ShowTopic uses it). A returned string stays valid until the next call returning one (the BASIC runtime copies it at once).
Chapter 6. Files, Printing, and Databases
6.1. File Operations Library
Attributes, folder listing, path helpers, and recursive copy/move/delete jobs with progress, Cancel, and conflict handling. The File Manager and Setup are user interfaces over this library; any program can use it. Drives, free space, and wildcard filters come from the platform layer (dvxPlat.h): platformDriveList, platformDiskSpace, and platformFilterMatch.
Header: fileops/fileOps.h
Loaded as: bin/libs/kpunch/fileops/fileops.lib
6.1.1. DOS Disk Errors
On DOS, touching a drive with no disk (or a write-protected or removed one) raises a critical error, which would normally wait at an "Abort, Retry, Fail" prompt on the hidden text screen. DVX installs a critical-error handler at startup (platformInit) that answers Fail, so every call here, and your own disk code, simply gets an error (errno) instead. platformDriveList never touches the media at all (IOCTL calls only), so listing drives costs nothing even with empty drives.
6.1.2. Big Disks and Long File Names
Disks past 2 GB report their real size and free space: platformDiskSpace asks DOS with the FAT32 call first and falls back to the older one, which stops near 2 GB. File sizes are 64-bit (FileOpsEntryT.size, fileOpsTreeSize, the job byte counts); a FAT32 file reaches 4 GB - 1 byte, and platformStatSize reads it correctly where stat’s st_size would be negative. Where a long-name driver is running (Windows, DOSLFN) and covers the drive (platformLongNames), listings show long names, jobs copy and move them, attributes and renames work on them, fileOpsValidateName accepts them, and fileOpsPathNormalize keeps their case; elsewhere the 8.3 rules apply.
6.1.3. Attributes and Dates
| Function | Description |
|---|---|
fileOpsGetAttr(path, &attr) |
FILEOPS_ATTR_READONLY/HIDDEN/SYSTEM/ARCHIVE bits. Elsewhere than DOS: read-only = no write permission, hidden = a dot-file. |
fileOpsSetAttr(path, attr) |
Set the FILEOPS_ATTR_EDITABLE bits (elsewhere than DOS only read-only applies). |
fileOpsSetTime(path, mtime) |
Set a file’s modification time. |
6.1.4. Listing, Names, and Paths
- fileOpsListDir(dir, filter, &entries, &count)
-
Read a folder into an FileOpsEntryT array (name, size, mtime, isDir). Files not matching filter (platformFilterMatch: wildcards * and ?, several patterns separated by ';', ',', or blanks; "*.*" and an empty filter match everything) are left out; folders always stay. Free with fileOpsListFree. False (errno set, nothing to free) when the folder cannot be read or the whole list does not fit in memory (ENOMEM): a listing is never partial.
- fileOpsListSort(entries, count, col, descending)
-
Folders first, then by FileOpsSortNameE/SizeE/TypeE/DateE; ties by name.
- fileOpsExtension(name)
-
Extension without the dot, "" when none.
- fileOpsTypeName(entry, out, size)
-
"Folder", "Program" (.APP), "TXT File", "File".
- fileOpsFormatSize(bytes, out, size)
-
"1,234,567".
- fileOpsFormatDate(t, out, size)
-
"YYYY-MM-DD HH:MM" in local time.
- fileOpsParseDate(text, &t)
-
The time fileOpsFormatDate’s text stands for ("YYYY-MM-DD HH:MM", optionally ":SS"), local time; false for anything else, a date that does not exist included.
- fileOpsTreeSize(path, &bytes, &files, &folders)
-
Total size of a file or of a folder and everything in it (the folders inside it; a measure job run to its end). False when part of it cannot be read; the totals then cover what was read.
- fileOpsMakeDir(dir, name, err, errSize)
-
Create a folder; a reason in err on failure.
- fileOpsRename(dir, oldName, newName, err, errSize)
-
Rename within a folder; refuses a name already in use (the item’s own name in another case, or its 8.3 alias, is not: platformSameFile, and platformRename gives it that name).
- fileOpsSaveText(path, text, len, pump, ctx, &failed, err, size)
-
Save text safely, every line end (LF, or CR LF) as CR LF: into the scratch file beside path (platformPathSibling, PLATFORM_TMP_EXT), which then takes its place (platformReplaceFile), so a failed save leaves the old file as it was. The text is written 16 KB at a time; while a long save writes, pump(ctx) (a FileOpsPumpT; NULL for none) is called every 50 ms, with the scratch file closed, to let DVX go on as DVX’s other long jobs do; a pump that returns false ends the pumping, not the save. False with errno, the FileOpsSaveStepE that failed (FileOpsSaveOpenE, FileOpsSaveWriteE, FileOpsSaveReplaceE), and a reason in err; the scratch file is gone.
- fileOpsValidateName(dir, name, err, errSize)
-
Check a new name for folder dir by the rules of its disk (platformValidateFilename): on DOS long names where the drive takes them (platformLongNames), else 8.3; never a device name.
- fileOpsPathJoin(out, size, dir, name)
-
dir + separator + name in native separators (platformPathJoin: no doubled separator; an absolute name stands alone); false when it does not fit.
- fileOpsPathParent(path, out, size)
-
Parent folder, in native separators; false at a root.
- fileOpsPathIsRoot(path)
-
True for "C:\", "C:", or "/".
- fileOpsPathIsInside(path, dir)
-
True when path is dir or below it (platformPathIsUnder).
- fileOpsPathSame(a, b)
-
Same place (platformPathSame: separators equal, case ignored, a trailing separator ignored).
- fileOpsPathNormalize(path, out, size)
-
Canonical absolute form of an existing folder (DOS: upper case, except names on a disk with long names, which keep their case).
6.1.5. Jobs
A job copies, moves, deletes, or measures (FileOpsMeasureE: counts the files, folders, and bytes, changing nothing) any number of files and folders (recursively):
FileOpsJobT *job = fileOpsJobCreate(FileOpsCopyE, "C:\\BACKUP");
fileOpsJobAddSource(job, "C:\\DOCS\\LETTER.TXT");
fileOpsJobAddSource(job, "C:\\DOCS\\PHOTOS");
for (;;) {
FileOpsStepE step = fileOpsJobStep(job);
if (step == FileOpsStepDoneE || step == FileOpsStepCancelledE) {
break;
}
if (step == FileOpsStepAskE) {
// fileOpsJobMessage(job): "... already exists" or "... is read-only"
fileOpsJobAnswer(job, FileOpsAnswerAllE);
} else if (step == FileOpsStepErrorE) {
fileOpsJobAnswer(job, FileOpsAnswerSkipE);
}
// show progress, tsYield(), honor a Cancel button here
}
fileOpsJobFree(job);
Each fileOpsJobStep does one bounded piece of work: read a few dozen entries of a folder (a big folder takes several steps), copy one FILEOPS_COPY_CHUNK of one file, or delete one item. A cooperative program yields between steps.
| Step result | Meaning |
|---|---|
FileOpsStepBusyE |
More work to do. |
FileOpsStepAskE |
A destination file exists, or a file to delete is read-only. Answer Yes, No, All, or Cancel. |
FileOpsStepErrorE |
Something failed; fileOpsJobMessage says why. Answer Retry, Skip, or Cancel. |
FileOpsStepDoneE |
Finished. |
FileOpsStepCancelledE |
Stopped by Cancel. |
Until it is answered, the job keeps returning the same question. The next step tries the item again and applies the answer if it fails again; an item that goes through leaves the answer unused (it is never kept for a later question). Cancel stops at once, without trying again. What the job does:
-
Scan: each folder is read once and its files are counted, so fileOpsJobProgress (FileOpsProgressT: files and bytes done and total, folders inside the sources, percent, current path) is accurate while the transfer runs. A folder that fails part way keeps nothing of what was read before the question.
-
Measure: only the scan, and it asks nothing: a folder it cannot read is skipped and counted in FileOpsProgressT.unread (what was read of it stays counted).
-
Copy: folders are created before their contents, files are copied in chunks and keep their date and attributes (plus Archive). A read-only destination is made writable before it is replaced.
-
Move: a top-level item whose destination does not exist yet is renamed in one go. Otherwise each file is copied and then its source removed, and the emptied source folders are removed at the end. A folder that still holds skipped items is kept.
-
Delete: files first, deepest first, then folders; read-only files ask first.
-
Copying or moving a folder into itself, or a file onto itself, is an error; moving an item to where it already is does nothing.
-
fileOpsJobCancel makes the next step stop, removing a partly copied file; fileOpsJobFree does the same for a job that was not finished.
fileOpsJobClearAttr(job, attr), called before the first step, clears those attribute bits on every file a copy or move writes: Setup passes FILEOPS_ATTR_READONLY, because every file on a CD-ROM is read-only and the installed copies must not be.
fileOpsJobRun(job, callbacks) runs a job to the end instead: progress(job, ctx) is called after every step (return false to cancel) and ask(job, kind, message, ctx) answers questions. With no callbacks, existing files are kept (No) and failing items are skipped.
6.1.6. BASIC
src/include/basic/fileops.bas declares the BASIC functions (fileOpsBas.c): whole trees at once (FileOpsCopyTree, FileOpsMoveTree, FileOpsDeleteTree: a job run to its end, letting DVX and the program’s events go on through dvxWaitPump at the first step and every 50 ms after; when the first pump says stop the job runs on without pumps, when a later one does the program is ending and the call is canceled), drives and disks (FileOpsDriveList$, FileOpsDriveType (the PlatformDriveTypeE of platformDriveList, CONSTs FILEOPS_DRIVE_*; -1 for no such drive), FileOpsBootDrive$ (platformBootDrive, "" when none), FileOpsFreeKb, FileOpsFreeBytes, and FileOpsTotalBytes (platformDiskSpace), FileOpsIsWritable (platformDirIsWritable), FileOpsReadOnlySystem (platformIsReadOnly), FileOpsTempDir$ (platformTempDir, "" when none)), DVX’s folders (FileOpsUserDir$ (platformUserDir), FileOpsUserPath$ (platformUserPath, "" when it does not fit), FileOpsUserInTemp (platformUserInTemp), and for the kinds of DvxKindE (CONSTs FILEOPS_KIND_*) FileOpsKindDir$ (platformKindDir), FileOpsKindBrowseDir$ (platformKindBrowseDir), FileOpsKindFind$ (platformKindFind), FileOpsKindName$ (platformKindNameOf), and FileOpsKindList (platformKindReadDir as a listing, sorted by name; "" or 0 for a kind out of range)), folder listings (FileOpsList, FileOpsListCount, FileOpsListSort, FileOpsListFind, FileOpsListFolders (a new listing of a listing’s folders, by name, from memory), FileOpsListName$, FileOpsListIsFolder, FileOpsListSize, FileOpsListRows$, FileOpsListFree), paths and names (FileOpsPathNormalize$, FileOpsPathParent$, FileOpsPathJoin$, FileOpsPathSame, FileOpsPathIsRoot, FileOpsPathIsAbsolute (platformPathIsAbsolute), FileOpsPathIsInside, FileOpsPathSep$ (DVX_PATH_SEP), FileOpsPathNative$ (platformPathNative), FileOpsFilterMatch (platformFilterMatch), FileOpsBaseName$, FileOpsExtension$), files and folders (FileOpsMakeDir, FileOpsMakePath (platformMkdirRecursive), FileOpsRename, FileOpsError$, FileOpsTempPath$ and FileOpsReplaceFile (an atomic save: platformPathSibling + platformReplaceFile), FileOpsSaveText (fileOpsSaveText: a whole text saved that way with CR LF line ends, letting DVX and the program’s events go on through dvxWaitPump while a long text is written, returning 0 or the BASIC error number the VM’s file statements give for the cause, from the VM’s own header-only basFileErr.h, and FILEOPS_REPLACE_ERROR when the swap fails), FileOpsValidName (platformValidateFilename for a name in a folder), FileOpsValidLongName and FileOpsValidShortName (platformValidateLongName / platformValidateShortName, the rules alone), FileOpsLongNames (platformLongNames), FileOpsShortPath$ (platformShortPath, "" when it does not fit), FileOpsIsFolder, FileOpsGetAttr, FileOpsSetAttr, FileOpsModified$, FileOpsSetModified (fileOpsParseDate + fileOpsSetTime), FileOpsTreeSize (a measure job pumping as the whole-tree calls do) with FileOpsTreeBytes / FileOpsTreeFiles / FileOpsTreeFolders, FileOpsFormatSize$), and jobs (FileOpsJobCreate (FILEOPS_COPY, FILEOPS_MOVE, FILEOPS_DELETE, or FILEOPS_MEASURE), FileOpsJobAddSource, FileOpsJobClearAttr (masked to FILEOPS_ATTR_EDITABLE), FileOpsJobRunFor, FileOpsJobMessage$, FileOpsJobAnswer, FileOpsJobCancel, FileOpsJobCurrent$, FileOpsJobFilesDone, FileOpsJobFilesTotal, FileOpsJobFoldersTotal, FileOpsJobUnread, FileOpsJobPercent, FileOpsJobBytesDone, FileOpsJobBytesTotal (FileOpsProgressT; byte counts are DOUBLE), FileOpsJobFree). The fileops.bas CONSTs mirror fileOps.h and dvxPlat.h; the basdev test suite (caseIncludeConsts) checks each against its C value.
Listings and jobs are handles (small numbers, 0 = none) into a table owned by the library; each records the app that made it, and the shell’s app-cleanup hook frees what an app leaves open when it ends. FileOpsJobRunFor(job, ms) steps the job until the time is used or it needs an answer, so a BASIC Timer can run it without blocking the program. A returned string stays valid until the next call returning one (the BASIC runtime copies it at once). Single files are handled by the built-in FILECOPY, KILL, NAME, MKDIR, RMDIR, GETATTR, and SETATTR statements.
6.2. Printing Library
Printer ports and print jobs, text laid out on pages, pictures for dot-matrix and laser printers, the printer settings, and the common Print and Page Setup dialogs. Notepad, Image Viewer, Icon Editor, the Control Panel’s Printer page, and BASIC’s LPRINT all print through it; any program can.
Header: print/print.h
Loaded as: bin/libs/kpunch/print/print.lib; the PostScript printers' driver, with their text faces and vector pages, is bin/libs/kpunch/print/drivers/ps.drv, which the library loads the first time a PostScript printer is used (until then printVecBegin is false for every document).
6.2.1. Settings
The printer is chosen once for everything, in DVX.INI [printer] (the Control Panel’s Printer page and the Page Setup dialog edit it): where output goes (PrintDestE: LPT1 to LPT3, COM1 to COM4, or a file), a serial port’s speed and handshake (baud, PrintHandshakeE), the printer model (PrintModelE: text only; Epson 9-pin or 24-pin, each with a black or a color ribbon; HP LaserJet at 150 dpi; HP LaserJet III or DeskJet at 300 dpi; HP DeskJet 500C; HP DeskJet 550C and later; PostScript, black or color; Apple ImageWriter II, black or color), and the page setup (PrintPageSetupT).
| Function | Description |
|---|---|
printSettingsLoad(&s) |
Read DVX.INI into a PrintSettingsT (defaults for anything missing; a page setup that cannot work is replaced by the defaults as a whole). |
printSettingsSave(&s) |
Write it back; false when the file could not be saved. |
printSettingsRead(h, &s) / Write(h, &s) |
The same on a preferences handle you already have open. |
printSettingsDefaults(&s) |
LPT1, text only, PRINTER.PRN, 80 columns, margins 3 lines / 5 columns, tab 8, wrap, header "&f", footer "Page &p". |
printPageSetupProblem(&ps) |
NULL when the page setup can be used, else the reason (a static buffer). |
printPageLines(&ps, model) |
Lines per page used: the set value, or the model’s usual length (66; 60 for the LaserJet, DeskJet, and PostScript models). |
printDestChoices[] / printModelChoices[] |
The labels and INI spellings (PrefsChoiceT), indexed by PrintDestE / PrintModelE. |
printDestLabel(d) / printModelLabel(m) |
The label of one choice (for programs that look the library up by name). |
printDeviceProblem(dest, file) |
NULL when the destination can be used, else why not (printing to a file needs its name). |
printDeviceStore(h, model, dest, file) |
Put model, destination, and file into the [printer] section of h (its port, file, and model keys alone; the page setup and every other key stay as they are; the caller saves h). The Control Panel’s OK and print.bas use it. |
printSerialStore(h, baud, handshake) |
The same for a serial port’s speed and handshake (the baud and handshake keys alone); false for a speed printBaudRate does not offer or a handshake out of range. |
printFilePath(file, out, size) |
The file a printout into file goes to: a name without a folder (PRINTER.PRN too) is in the user folder (platformUserPath), since DVX’s own folder may be read-only; any other path as it is. printJobOpen opens it; the Browse... buttons start in its folder. |
printModelProblem(model) |
NULL when DVX can print on the model (text only, or its driver is there), else the reason for the user (a static buffer): a PostScript model when the PostScript driver file is missing. The ready-made prints and the BASIC Printer object show it instead of printing. |
6.2.2. Jobs and Printer Problems
A job sends bytes to a printer port or into a file. On DOS a parallel port is driven through the BIOS printer service (INT 17h); a byte is sent only when a status check says the printer is ready, so the BIOS never waits by itself. A serial port (COM1 to COM4, for serial printers such as the ImageWriter II) is opened through the serial library when the job starts, at the speed and handshake in the settings (8 data bits, no parity, 1 stop bit); its interrupt handler sends from a buffer as the printer’s handshake allows (XON / XOFF, or the printer’s DTR seen on the computer’s CTS, or on its DSR as Apple’s cable wires it), the port is busy while the buffer is well filled, and when the job closes it waits for the buffer to empty before closing the port. A PrintPortOpsT’s open, pending, and close (NULL for none) are these steps. While the printer is busy the job calls the idle hook; a printer busy for PRINT_BUSY_TIMEOUT_MS (10 seconds), out of paper, off line, or reporting an error is a problem, and so is a file that cannot be written (disk full). A problem goes to the ask hook: Retry tries again, Cancel ends the job and every later write fails at once.
PrintHooksT hooks = { myAsk, myIdle, NULL, myState };
char err[PRINT_MSG_MAX];
PrintJobT *job = printJobOpen(PrintDestLpt1E, NULL, &hooks, err, sizeof(err));
if (!job) {
// err: "This computer has no port LPT1."
} else {
printJobPuts(job, "Hello, printer\r\n\f");
printJobClose(job); // true when everything was sent
}
| Hook | Called |
|---|---|
ask(ctx, message) |
For a problem; return PrintAnswerRetryE or PrintAnswerCancelE. NULL cancels. |
idle(ctx) |
While the printer is busy, and after every PRINT_YIELD_BYTES bytes (4096 into a file). Return false to cancel. NULL calls tsYield, so other programs keep running. |
finished(ctx, closing) |
When a write that called idle returns, and (closing true) when the job is freed. |
printJobWrite returns once every byte was taken, or false when the job is canceled. printJobBytes gives the count sent, printJobCancelled whether it was canceled. printJobCancel cancels a job whose output is to be thrown away: nothing more is sent, and printJobClose does not wait for the printer (the BASIC runtime does this for a program ended from the Task Manager). printStatusProblem(status, afterWrite, where, out, size) turns BIOS status bits (PRINT_STATUS_*) into the message the user sees. printSetPortOps replaces the port services (present / status / write) with your own, as the tests do to play a printer that is busy or out of paper; NULL restores the real ones. Elsewhere than DOS the real ports always exist, are always ready, and append to lpt1.prn .. lpt3.prn in the working directory.
6.2.3. Text
printTextJob(job, model, text, len, &pageSetup, &info) prints plain text on pages. Lines end with LF or CR LF; a form feed in the text starts a new page. Each printed line starts with marginLeft blanks and ends with CR LF, tabs are expanded to tabWidth, other control characters print as blanks, and a line longer than the text width is wrapped at the last blank before it (a word longer than a whole line is split) or, with wrap off, cut off. Every page ends with a form feed. For the Epson, LaserJet, DeskJet, and ImageWriter models the printer’s reset command comes first (the ImageWriter’s also sets its switches), and for the LaserJet, DeskJet, and ImageWriter models it comes last too. A PostScript printer prints no plain text, so on the PostScript models the pages are PostScript: Courier as large as lets the page setup’s columns fill 8 inches and its lines 10, a show per line (CP437 letters and signs in ISO Latin-1; line and block characters as -, |, +, and #).
A page is marginTop lines with the header in their middle line, the text, then marginBottom lines with the footer in their middle line. Header and footer codes: &f file name (PrintTextInfoT.title), &p page number, &n number of pages, &d date, &t time (PrintTextInfoT.date / time, or today and now), && an ampersand; &l, &c, and &r put what follows at the left, center, or right (text before any of them is centered). printFormatHeader expands a header for one page.
PrintTextInfoT also chooses a page range (firstPage, lastPage; 0 = all) and the number of copies. printTextPageCount returns the number of pages text takes. A page setup printPageSetupProblem refuses (a page too narrow or too wide for its margins, a header or footer without its terminating zero) prints nothing: printTextJob returns false without sending anything, and printTextPageCount returns 0.
6.2.4. Documents: Pictures and Drawn Pages
A document is pages of dot graphics on a picture-printing model. printDocOpen(job, model) starts one on a job (the document owns the job from then on, and printDocClose closes it). Each page is the whole printable area (8 by 10 inches): printDocPage(doc, fn, ctx) asks the program’s PrintBandFnT for it a band at a time, top down, as R, G, B bytes at the printer’s resolution (the band comes white), and printDocPicture(doc, rgb, w, h, pitch) prints a picture scaled to the largest size that fits, keeping its shape. Only one band of the page is ever in memory, so a page costs the same however large it is. The document and the buffers a page is made in are held for the program that prints (basHold, as the job is), so a program ended from the Task Manager while its printer is busy has them freed.
| Function | Description |
|---|---|
printModelPage(model, &info) |
The page a model prints on (PrintPageInfoT: dots per inch across and down, the printable area in dots, color or not, and vector: a PostScript printer, which can draw the page itself); false for text only. info may be NULL to ask only whether the model prints pictures. |
printDocOpen(job, model) |
Start a document; NULL (the job closed) for a text-only model. |
printDocInfo(doc, &info) |
The document’s page. |
printDocPage(doc, fn, ctx) |
Print a page the program draws. fn(ctx, rgb, width, y0, rows) fills rows y0 to y0 + rows - 1; false from it stops the page. |
printDocPicture(doc, rgb, w, h, pitch) |
Print a picture as a page. |
printDocCancel(doc) |
Cancel the job (printJobCancel): nothing more is sent, and printDocClose then neither waits for the printer nor asks about it (the BASIC runtime does this to the Printer object’s document for Printer.KillDoc, and when its program is ended from the Task Manager). |
printDocCancelled(doc) |
True when the job was canceled. |
printDocClose(doc) |
End the document and close its job; true when every page printed. After a failure every later page fails at once. |
printUiDocOpen(ctx, title, &choice) |
A document on the printer in the settings, at a Print dialog answer’s destination (NULL: the settings'), with the Printing window up until it closes and the Retry box; tells the user why when it cannot open. Copies are the program’s: print each page as often as wanted. |
printUiDocClose(ctx, doc) |
Close it, telling the user of a failure (not of a cancel). |
Each band is dithered to the printer’s inks with an ordered pattern (4x4, 17 levels, on the dot-matrix printers and the 150 dpi LaserJet; 8x8, 65 levels, at 300 dpi). A black-only printer prints the brightness. A color printer prints cyan, magenta, and yellow from the red, green, and blue; with black ink as well, black takes what the three have in common (full undercolor removal). Each ink is dithered with its own offset of the pattern, so dots of different inks do not land on each other in a regular way, and the pattern follows the row’s place on the page, so it runs on from band to band.
static bool drawBand(void *ctx, uint8_t *rgb, int32_t width, int32_t y0, int32_t rows) {
// a red bar one inch down, a quarter inch high
const PrintPageInfoT *pi = (const PrintPageInfoT *)ctx;
for (int32_t r = 0; r < rows; r++) {
int32_t y = y0 + r;
if (y >= pi->dpiY && y < pi->dpiY + pi->dpiY / 4) {
for (int32_t x = 0; x < width; x++) {
uint8_t *p = rgb + ((r * width) + x) * 3;
p[0] = 0xFF;
p[1] = 0;
p[2] = 0;
}
}
}
return true;
}
PrintDocT *doc = printUiDocOpen(ctx, "Report", NULL);
PrintPageInfoT pi;
if (doc) {
printDocInfo(doc, &pi);
printDocPage(doc, drawBand, &pi);
printUiDocClose(ctx, doc);
}
6.2.5. Vector Pages
On a PostScript printer (PrintPageInfoT.vector) a page can be drawn by the printer itself, as lines, curves, fills, and its own letters, instead of being sent as dots: sharper at any size, and much smaller. printVecBegin(doc) starts such a page and printVecEnd(doc) prints it; in between, the drawing calls below go to the printer as they are made. Coordinates are the page’s dots (y down, a dot’s center at whole numbers, so a shape covers the same dots it would in a band), colors are 0xRRGGBB (gray on the black-and-white model), and widths are in dots. printVecBegin is false, and the drawing calls do nothing, on a printer that cannot or a document that failed; a raster page (printDocPage, printDocPicture) is refused while a vector page is open, and printDocClose ends one left open.
| Function | Description |
|---|---|
printVecBegin(doc), printVecEnd(doc) |
Start a vector page; print it (false when it did not print). |
printVecLine(doc, x0, y0, x1, y1, color, width, dash) |
A line, round at the ends; dash is a 16-step pattern from its top bit (0xFFFF solid), a step a dot along the line’s longer side, as BASIC’s LINE style. |
printVecRect(doc, x0, y0, x1, y1, color, fill) |
A filled box, corners inclusive. |
printVecEllipseFill(doc, cx, cy, rx, ry, color, fill) |
A filled ellipse, out to the dots rx and ry from its center. |
printVecEllipse(doc, cx, cy, rx, ry, color, width, dash, arc, start, end) |
An ellipse’s outline, or (arc) the part from start to end radians counterclockwise; dash as printVecLine’s, along the outline from angle 0. |
printVecDot(doc, x, y, color, width) |
A round dot width dots across. |
printVecText(doc, font, x, y, text, len, color) |
Text with the top of its line at (x, y), with the font’s underline and strike-through. |
printVecImage(doc, rgb, w, h, sx, sy, sw, sh, dx, dy, dw, dh) |
The part sx, sy, sw, sh of a picture (R, G, B bytes) stretched over the dots dx, dy, dw, dh by the printer. |
A fill (PrintFillE) is solid or a hatch of lines one dot wide every PRINT_HATCH_DOTS (8) dots, horizontal, vertical, either diagonal, or crossed, lined up across the page as BASIC’s FillStyle hatches are. The pen (its color, width, and dashes) and the font are sent only when they change, and each of the printer’s faces is made Latin-1 the first time the document uses it.
A font opened for a vector page (printFontOpen with page.vector set) is the printer’s own Helvetica, Times, or Courier in the style asked for (FONT_STYLE_BOLD, FONT_STYLE_ITALIC): Courier for a fixed-pitch family or one with Mono or Courier in its name, Times for one with Serif, Times, Roman, Tinos, or Ledger in it (but not Sans), else Helvetica. It is exactly the size asked for, and printFontWidth, printFontHeight (1.2 times the size), and printFontAscent measure the printer’s letters by Adobe’s published widths, so text placed with them lines up as it prints. It draws only with printVecText (printFontSpans and printFontDraw draw nothing with it); for DVX’s own letters drawn in bands on a PostScript printer, open the font with vector cleared in a copy of the page.
6.2.6. Text on a Page
A page a program draws can carry text in any font family (dvxText.h) at a size in points. printFontOpen(&page, family, decipoints, style) gives a PrintFontT for a page’s resolution (its PrintPageInfoT): the size is in tenths of a point (120 for 12 points), the style any FONT_STYLE_ bits, underline and strike-through included. The font is the family’s smallest strike at least as large as the size in printer dots (12 points is 50 dots at 300 dpi, 30 at 180), else its largest, scaled to the size across and down apart, since a 9-pin printer’s dots are not square. Scaled down (or up one way only), a strike pixel becomes the dots it covers, and every pixel row and column of the strike still marks a dot, so thin strokes stay. Scaled up both ways, each dot is sampled between the four strike pixels around its center and drawn when at least half covered, so edges come out smooth rather than in steps.
The base set’s files carry print sizes beside their screen sizes (mkfont’s print key; see Making Fonts): DejaVu Sans, Serif, and Sans Mono in every style at 25 to 100 pixels, about 6 to 24 points at 300 dpi and 10 to 40 at 180, so those families print crisp at those sizes. Other families, and larger text, are scaled up from their largest size.
| Function | Description |
|---|---|
printFontOpen(&page, family, decipoints, style) |
The font; NULL when out of memory or for a size of 0 or less. printFontClose gives it up. |
printFontAscent(font), printFontHeight(font) |
Dots from the top of a line to its baseline, and to the next line. |
printFontWidth(font, text, len) |
Dots across len characters of text. |
printFontSpans(font, x, y, text, len, top, bottom, fn, ctx) |
The text with the top of its line at (x, y) as runs of dots (PrintSpanFnT fn(ctx, x0, x1, y)), only rows top to bottom: a line that misses them is skipped at once, so a page drawn band by band costs little for the lines elsewhere. |
printFontDraw(font, x, y, text, len, color, rgb, width, y0, rows) |
The same painted in color (0xRRGGBB) into the band a PrintBandFnT is filling. |
Positions are worked out in the strike’s pixels from the start of the text and only then turned into dots, so printFontWidth and what is drawn always agree.
6.2.7. Printer Drivers
- Epson 9-pin (ESC/P)
-
120 x 72 dots per inch (ESC * 1), 8-row bands, paper fed with ESC J; blank bands only feed paper, and each pass stops after its last black dot.
- Epson 24-pin (ESC/P)
-
180 x 180 dots per inch (ESC * 39, 3 bytes per column), 24-row bands.
- HP LaserJet (PCL)
-
150 dots per inch raster graphics, one uncompressed row transfer per dot row (every LaserJet understands it), trailing white bytes left out.
- HP LaserJet III or DeskJet (300 dpi)
-
300 dots per inch (PCL 5, and PCL 3 on DeskJets): each row packed (compression mode 2, TIFF PackBits) and blank rows skipped (ESC * b n Y) instead of sent, so a page with white space on it costs next to nothing.
- Epson 9-pin / 24-pin color
-
As the black ones, with a four-color ribbon: a pass of the head for each ink with ESC r n choosing its band of the ribbon, yellow first and black last (dark ink does not smear into the light ones).
- HP DeskJet 500C
-
As the 300 dpi LaserJet, in three planes (ESC * r -3 U: cyan, magenta, yellow; black is the three together): ESC * b n V for each plane of a row but the last, ESC * b n W for the last.
- HP DeskJet 550C and later
-
As the 500C, in four planes (ESC * r -4 U: black, cyan, magenta, yellow).
- PostScript
-
Level 2 at 300 dpi: each band an imagemask of its black dots, packed (RunLengthDecode, the same PackBits) and in ASCII85, which any port carries; a band with no ink is not sent. The 8 by 10 inch area is centered across the paper the printer has loaded, half an inch from its top.
- PostScript (color)
-
As PostScript, each band a colorimage of 4 bits a dot (cyan, magenta, yellow, black) from the dithered planes. Both PostScript models also draw vector pages (see Vector Pages).
- Apple ImageWriter II
-
144 x 144 dots per inch: 144 across (ESC p), and down by two passes of the 8 graphics wires 1/144 inch apart (the even rows of a 16-row band, a 1/144-inch line feed, the odd rows, then ESC T 15 and a line feed). A line is ESC G nnnn and its columns (bit 0 the top dot), placed at its first dot (ESC F nnnn). The document resets the printer (ESC c) and sets its switches whatever its DIP switches say: no line feed after CR, 8-bit data, no perforation skip; then unidirectional printing (ESC >), which keeps the passes in line.
- Apple ImageWriter II (color)
-
As the ImageWriter II with the four-color ribbon: a line for each ink with ESC K n choosing its band, yellow first and black last, CR between them.
The drivers are inside the library: each holds its resolution, the printable size in dots, the band height, the dither size, its inks, the text reset strings and usual page length, and begin / band / end functions that write the printer’s commands. A new printer family is one more driver.
6.2.8. Dialogs and Ready-Made Printing
| Function | Description |
|---|---|
printDialog(ctx, title, pageCount, &choice) |
The common Print dialog: print to a port or a file, copies and, when pageCount > 0, all pages or a range. Starts from the settings; true with the PrintChoiceT filled when the user chose Print. |
printPageSetupDialog(ctx) |
The Page Setup dialog; saves the page setup to DVX.INI. |
printUiText(ctx, text, title, askFirst) |
Print text with the page setup on the printer in the settings (the Print dialog first when askFirst). |
printUiTextChoice(ctx, text, title, &choice) |
Print text on the destination, copies, and page range of a PrintChoiceT (a Print dialog answer, or one the program filled; NULL: the printer in the settings, every page, one copy) without asking; printUiText ends here. |
printUiTextSetup(ctx, text, title, &choice, &ps) |
printUiTextChoice with the program’s own page setup (NULL: the one in the settings), which leaves the user’s as it is. A page setup printPageSetupProblem refuses is told to the user and nothing prints. printTextPageCount(text, len, &ps, model) counts its pages for the Print dialog. |
printUiImageFile(ctx, path, title, askFirst) |
Print a picture file (BMP, PNG, JPEG, GIF). |
printUiWindow(ctx, win, askFirst) |
Print a window’s contents as a picture. |
printUiJobOpen(ctx, title, &choice) |
A job with the user interface hooks at a PrintChoiceT’s destination, a file with its name too (NULL: the settings'), for output the program formats itself (printJobWrite, or printTextJob with its own page setup); close it with printJobClose. NULL, after telling the user why, when it cannot be opened. |
printUiOpenPort(ctx, port) |
A job with the user interface hooks on a printer port (PrintDestE’s numbers: 0 to 2 LPT1 to LPT3, 3 to 6 COM1 to COM4) or, for PRINT_PORT_DEFAULT, the printer in the settings (its file too). NULL for a file or any other number, and when the port cannot be opened (the reason is logged, not shown). BASIC’s LPRINT and OPEN "LPT1:" print through it. |
Jobs opened by these ask about printer problems with a Retry / Cancel message box. While a write waits, a modal Printing window with a Cancel button appears (from the first wait to the end of the job for text, a picture, a document, or a printUiJobOpen job; after half a second of waiting for a printUiOpenPort job) and the whole desktop keeps running under it. Problems are told to the user; the functions return true only when everything was printed. Pictures need a printer model that prints them; on a text-only printer the user is told to choose the model in the Control Panel.
6.2.9. BASIC
BASIC’s Printer object (the form runtime, formPrinter.c) is built on the calls above: it records a page’s drawing, prints it with printUiDocOpen / printDocPage (each band drawn again from the record), and prints text with printFontOpen and printFontDraw; on a PostScript printer it draws the record once more as a vector page (printVec*), in the printer’s own faces; its document goes where the program’s last PrintChoose chose (printBasChoice, the running program’s own answer only).
src/include/basic/print.bas declares PrintTextDialog, PrintText, PrintPictureDialog, PrintPicture, PrintPageSetup, PrintCanPrintPictures, and PrintCanPrintColor (printModelPage). For serial printers it declares PrintDestIsSerial (printDestIsSerial), PrintBaudRate (printBaudRate), PrintHandshakeCount / PrintHandshakeLabel$ (printHandshakeLabel), PrintSettingBaud / PrintSettingHandshake (printSettingsRead), and PrintSerialStore (printSerialStore). For the printer settings it also declares PrintModelCount / PrintModelLabel$, PrintModelProblem$ (printModelProblem, "" when there is none), PrintDestCount / PrintDestLabel$ / PrintDestIsFile, PrintFilePath$ (printFilePath, "" when it does not fit), PrintSettingModel / PrintSettingDest / PrintSettingFile$ (printSettingsRead on a prefs.bas handle, through prefsBasHandle), PrintSettingsProblem$ (printDeviceProblem), and PrintSettingsStore (printDeviceStore).
| BASIC | C it calls |
|---|---|
PrintPageSetting(prefs, field), PrintPageText$(prefs, field) |
printSettingsRead on a prefs.bas handle: one PrintPageSetupT field by name (Lines, Columns, MarginTop, MarginBottom, MarginLeft, MarginRight, TabWidth, Wrap; Header, Footer). |
PrintPageSetupProblem$(lines, ..., footer) |
printPageSetupProblem ("" when usable). |
PrintPageSettingsStore(prefs, lines, ..., footer) |
printSettingsWrite of the page part (the printer part as read); False when printPageSetupProblem objects. |
PrintPageLines(prefs, model) |
printPageLines. |
PrintPageCount(text) |
printTextPageCount with the settings in DVX.INI. |
PrintPageCountSetup(text, lines, ..., footer) |
printTextPageCount with the program’s own page setup (given as for PrintPageSetupProblem$) on the printer in DVX.INI; 0 when printPageSetupProblem objects. |
PrintTextPages(text, title, first, last, copies) |
printUiTextChoice on the destination in the settings. |
PrintTextSetup(text, title, lines, ..., footer) |
printUiTextSetup with the program’s own page setup, at the printer, pages, and copies of the program’s last PrintChoose (printBasChoice), else on the printer in the settings, every page, once. |
PrintChoose(title, pageCount), PrintChoiceDest, PrintChoiceFile$, PrintChoiceCopies, PrintChoiceFirst, PrintChoiceLast |
printDialog; the readers return the PrintChoiceT of the last PrintChoose. |
PrintForm(form), PrintFormDialog(form) |
printUiWindow on a loaded form’s window (these two live in the BASIC runtime, which knows the forms). |
PrintPortPresent(port), PrintPortStatus(port) |
printPortPresent / printPortStatus; port 1-3 is LPT1-LPT3, 4-7 COM1-COM4. |
PrintStatusProblem$(status, afterWrite, where) |
printStatusProblem ("" when the status shows none). |
print.bas also has CONSTs for the PRINT_STATUS_ bits and the page setup limits and defaults (PRINT_LINES_STANDARD ... PRINT_COPIES_MAX); a formrt test compares them with print.h. The BASIC runtime gives the library the GUI context (printBasSetContext) when a program starts, and runs LPRINT, LPRINT USING, and OPEN "LPT1:" / "PRN" through printUiOpenPort, printJobWrite, and printJobClose. See the BASIC language reference (LPRINT, File I/O, Include Libraries).
6.3. dvxSql — SQL Database Interface
High-level wrapper around SQLite3 for DVX applications. Manages database connections and result set cursors via integer handles so BASIC code never touches raw pointers. All handles are 1-based; 0 indicates an error or invalid handle.
Header: sql/dvxSql.h
6.3.1. SQLite Wrapping
dvxSql wraps the bundled SQLite 3.53.4 amalgamation (sql/thirdparty/sqlite3/sqlite3.c and sqlite3.h; origin, checksum, and build options in sql/thirdparty/sqlite3/DVX-VERSION.md). It manages two internal dynamic tables keyed by 1-based handles:
-
Database table: each slot holds a sqlite3 * plus a per-database error string and affected-row count.
-
Cursor table: each slot holds a sqlite3_stmt *, the owning database handle, and EOF tracking.
Growing either table doubles its capacity. Closed slots are recycled by subsequent dvxSqlOpen or dvxSqlQuery calls, keeping handle values stable for the caller.
6.3.2. SQLite Build and File Layer
SQLite is compiled with the options listed in sql/thirdparty/sqlite3/sqliteOpts.mk (the host test build uses the same list). The ones that change what programs see:
-
Double-quoted text is always an identifier (SQLITE_DQS=0): write string literals in single quotes. SELECT "abc" fails with "no such column: abc".
-
The JSON functions, WAL journal mode, loadable extensions, shared cache, UTF-16 APIs, and deprecated APIs are left out. PRAGMA journal_mode = WAL leaves the database in rollback-journal (DELETE) mode.
-
Temporary tables, sorts, and statement journals are kept in memory (PRAGMA temp_store = FILE switches a connection to temporary files).
-
New databases use 1 KB pages; each connection caches up to 512 KB. Existing databases keep their own page size.
-
LIKE never matches BLOB values.
The DOS port is SQLite’s SQLITE_OS_OTHER build with a small DVX file layer, the "dvx" VFS in sql/dvxSqlVfs.c (the stock unix layer does not build under DJGPP). It uses the POSIX file calls, so the host tests run the same code:
-
Files are opened in binary mode. A file that cannot be opened for writing (read-only attribute or medium) opens read-only; writes then fail with "attempt to write a readonly database".
-
Journals keep 8.3 names: the database’s name with an extension of N and two characters worked out from the database’s own extension (DATA.DB uses DATA.NJG, DATA.DAT uses DATA.NIT, an extensionless DATA uses DATA.NPF), so databases that differ only in extension each have their own journal. A few pairs of extensions give the same journal name: the second of such a pair is refused when opened, with the reason as the error text. A file that has a journal’s name but is not a journal is never written over or deleted; a change to the database fails until it is moved away. A link to a database, or another spelling of its path, is the same database with the same lock and journal.
-
Paths are made absolute and canonical (relative names join the current directory, backslashes become forward slashes, "." and ".." are resolved), so every spelling of one file is the same database.
-
Locking is in-process: DOS is single user, but two connections inside DVX (two programs, or a Data control and BASIC code) can share a file. Any number may read; one may write. A write while another connection is writing, or a commit while another connection has a query open, fails with "database is locked"; retry after the other side finishes (dvxSqlFreeResult releases a query’s read lock). Nothing is locked at the DOS level, so do not share a database with another program outside DVX.
-
Temporary files, when used, are SQLxxxxx.TMP in the directory named by TMPDIR, TEMP, or TMP (else the current directory) and are deleted when closed.
-
Randomness comes from the cryptography library’s generator (secRngBytes) when that library is loaded, else from platformEntropyStamp mixed with the time of day.
Databases written by the SQLite 3.5.6 that earlier DVX releases bundled open, read, and write unchanged. Files created now use the current file format, which SQLite 3.5.6 cannot read.
6.3.3. Handle Model
Database and cursor handles are int32_t values. A successful open or query returns a handle greater than zero. Handle 0 is reserved as the invalid/error sentinel. Closing a database automatically finalizes all cursors that belong to it, so callers do not need to track cursor lifetimes per-database.
6.3.4. Connection Lifecycle
-
dvxSqlOpen allocates a handle and calls sqlite3_open. The database file is created if it does not exist.
-
Use dvxSqlExec for DDL and non-query DML. On success, dvxSqlAffectedRows returns the row count for the last call on this handle.
-
Use dvxSqlQuery to obtain a cursor over a SELECT. Iterate with dvxSqlNext and read columns with dvxSqlFieldText, dvxSqlFieldInt, dvxSqlFieldDbl, or dvxSqlFieldByName.
-
Call dvxSqlFreeResult when the cursor is no longer needed. Call dvxSqlClose when the database is no longer needed; any cursors still open on that database are finalized automatically.
-
A database belongs to the program that opened it: when the program ends, however it ends (End Task or a crash too), a database it did not close is closed (dvxSqlAbandon, so a statement left running is undone).
6.3.5. Common Patterns
-
Parameterize user input with dvxSqlEscape before interpolating into SQL strings.
-
Check dvxSqlError(db) for the last error on a handle; its message is stable until the next operation on the same database.
-
dvxSqlFieldByName matches column names case-insensitively, suitable for most real-world schemas.
See also: Cursor Operations (Section 6.5); Utility Functions (Section 6.6); Example (Section 6.7).
6.4. Database Operations
6.4.1. dvxSqlOpen
int32_t dvxSqlOpen(const char *path);
| Parameter | Description |
|---|---|
path |
Path to the database file. |
Returns a database handle greater than 0 on success, or 0 on error (null path, open failure, or no memory to grow the handle table). After a failed open, dvxSqlError(0) returns the reason (for example "unable to open database file (No such file or directory)"). The database belongs to the program that opened it: one it does not close is closed when it ends.
6.4.2. dvxSqlClose
void dvxSqlClose(int32_t db);
Close a database and free all associated resources. Any open cursors belonging to this database are automatically finalized.
| Parameter | Description |
|---|---|
db |
Database handle returned by dvxSqlOpen. |
Safe to call with an invalid handle (no-op).
6.4.3. dvxSqlAbandon
void dvxSqlAbandon(int32_t db);
Close a database at once, also while a statement runs on it. It is for a caller that is gone: a program ended by force while a statement’s pump let other work run (see dvxSqlSetPump), so the statement never returns. Every statement of the database is finalized, its cursors are freed, and the database is closed; what the running statement changed is not kept. DVX does this for each database a program left open when the program ends. With no statement running it is the same as dvxSqlClose.
| Parameter | Description |
|---|---|
db |
Database handle returned by dvxSqlOpen. |
Safe to call with an invalid handle (no-op).
6.4.4. dvxSqlExec
bool dvxSqlExec(int32_t db, const char *sql);
Execute one or more SQL statements that return no result rows. Suitable for DDL (CREATE TABLE, DROP TABLE, etc.) and DML (INSERT, UPDATE, DELETE). Every statement in sql runs, one after another, within this one call; give the database a pump (dvxSqlSetPump) when that may take long.
| Parameter | Description |
|---|---|
db |
Database handle. |
sql |
SQL statement(s) to execute. |
Returns true on success, false on error. On failure, the error message is available via dvxSqlError. On success, the affected row count is available via dvxSqlAffectedRows.
6.4.5. dvxSqlError
const char *dvxSqlError(int32_t db);
Return the last error message for a database handle. The returned string is stored internally and valid until the next operation on the same handle.
| Parameter | Description |
|---|---|
db |
Database handle. |
Returns the error string, or "Invalid database handle" if the handle is invalid. Messages are SQLite’s own (for example "no such table: x" or "database is locked"); when a file could not be opened, read, or written, the operating system’s reason follows in parentheses. Handle 0 (what a failed dvxSqlOpen returns) reports why the most recent open failed; after a successful open it is invalid again.
6.4.6. dvxSqlAffectedRows
int32_t dvxSqlAffectedRows(int32_t db);
Return SQLite’s count of the rows the most recent INSERT, UPDATE, or DELETE changed, as of the last successful dvxSqlExec call on this handle. A statement of another kind (COMMIT, CREATE TABLE, a SELECT) leaves the count as it was: after INSERT ... and then COMMIT, it is still the INSERT’s.
| Parameter | Description |
|---|---|
db |
Database handle. |
Returns the row count, or 0 if the handle is invalid.
6.4.7. dvxSqlSetPump
typedef bool (*DvxSqlPumpFnT)(int32_t db);
void dvxSqlSetPump(int32_t db, DvxSqlPumpFnT pump);
Give a database a pump, or take it away (NULL; a database opens without one). While a statement runs on the database (in dvxSqlExec, dvxSqlQuery, or dvxSqlNext, whose first step of a sorted or grouped query reads every row), the pump is called with the database’s handle every 1000 SQLite virtual machine instructions or so (a step that reads many rows calls it many times). It can let other work run, for example a frame of DVX’s. Returning false stops the statement: the call fails, dvxSqlError says "interrupted", and what the statement changed is undone.
| Parameter | Description |
|---|---|
db |
Database handle. |
pump |
The function to call, or NULL for none. |
The code a pump runs may use other databases, open and close them, as always. Its calls on the database whose statement is running are refused, as are any calls made from the pump on it:
-
dvxSqlExec, dvxSqlQuery, and dvxSqlNext fail, and dvxSqlError says "A statement is still running on this database".
-
The field functions of that database’s cursors return "" or 0.
-
dvxSqlFreeResult and dvxSqlClose are carried out when the running statement ends. The cursor or database can no longer be used from then on.
DVX BASIC gives every database a program opens a pump (see SQLOpen in the BASIC reference). The Data control’s own connections have none.
6.5. Cursor Operations
Result set cursors are created by dvxSqlQuery and must be freed with dvxSqlFreeResult when no longer needed. A new cursor is positioned before the first row; call dvxSqlNext to advance to the first row before reading field values.
6.5.1. dvxSqlQuery
int32_t dvxSqlQuery(int32_t db, const char *sql);
Execute a SELECT query and return a cursor handle for iterating the results. The cursor is positioned before the first row. Only the first statement in sql is run; anything after it is ignored.
| Parameter | Description |
|---|---|
db |
Database handle. |
sql |
SQL SELECT statement. |
Returns a cursor handle greater than 0 on success, or 0 on error (invalid handle, null SQL, SQL that is empty or only a comment, SQL syntax error, another statement still running on the database, or no memory to grow the cursor table). On failure, the error message is available via dvxSqlError on the database handle.
6.5.2. dvxSqlNext
bool dvxSqlNext(int32_t rs);
Advance the cursor to the next row.
| Parameter | Description |
|---|---|
rs |
Cursor handle returned by dvxSqlQuery. |
Returns true if a row is now available for reading. False when the cursor has reached the end, the handle is invalid, the step failed (dvxSqlError on the database says why, and the cursor is at its end), or another statement is still running on the database (the cursor stays where it was).
6.5.3. dvxSqlEof
bool dvxSqlEof(int32_t rs);
Test whether the cursor is past the last row.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
Returns true if the cursor is exhausted or the handle is invalid, false otherwise.
6.5.4. dvxSqlFieldCount
int32_t dvxSqlFieldCount(int32_t rs);
Return the number of columns in the result set.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
Returns the column count, or 0 if the handle is invalid.
6.5.5. dvxSqlFieldName
const char *dvxSqlFieldName(int32_t rs, int32_t col);
Return the name of a column by index.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
col |
Column index (0-based). |
Returns the column name, or "" if the handle or index is invalid.
6.5.6. dvxSqlFieldText
const char *dvxSqlFieldText(int32_t rs, int32_t col);
Return the value of a column as a string.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
col |
Column index (0-based). |
Returns the text value, or "" if the handle or index is invalid or the value is NULL.
6.5.7. dvxSqlFieldByName
const char *dvxSqlFieldByName(int32_t rs, const char *name);
Return the value of a column identified by name as a string. The name match is case-insensitive.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
name |
Column name (case-insensitive). |
Returns the text value, or "" if the handle is invalid, the name is NULL, or no column with that name exists.
6.5.8. dvxSqlFieldInt
int32_t dvxSqlFieldInt(int32_t rs, int32_t col);
Return the value of a column as a 32-bit integer.
| Parameter | Description |
|---|---|
rs |
Cursor handle. |
col |
Column index (0-based). |
Returns the integer value, or 0 if the handle or index is invalid.
6.6. Utility Functions
6.6.1. dvxSqlEscape
int32_t dvxSqlEscape(const char *src, char *dst, int32_t dstSize);
Escape a string for safe inclusion in SQL string literals. Doubles single quotes so that O’Brien becomes O''Brien.
| Parameter | Description |
|---|---|
src |
Source string to escape. |
dst |
Destination buffer for the escaped string. |
dstSize |
Size of the destination buffer in bytes. |
Returns the length of the escaped string (not including the null terminator), or -1 if the buffer was too small or any parameter is NULL/invalid.
6.7. Example Usage
6.7.1. Creating a Table and Inserting Data
int32_t db = dvxSqlOpen("mydata.db");
if (!db) {
// handle error
}
dvxSqlExec(db, "CREATE TABLE IF NOT EXISTS contacts ("
"id INTEGER PRIMARY KEY, "
"name TEXT, "
"phone TEXT)");
dvxSqlExec(db, "INSERT INTO contacts (name, phone) "
"VALUES ('Alice', '555-0100')");
6.7.2. Querying and Iterating Results
int32_t rs = dvxSqlQuery(db, "SELECT id, name, phone FROM contacts");
if (!rs) {
dvxLog("Contacts: %s", dvxSqlError(db));
}
while (dvxSqlNext(rs)) {
int32_t id = dvxSqlFieldInt(rs, 0);
const char *name = dvxSqlFieldText(rs, 1);
const char *phone = dvxSqlFieldText(rs, 2);
// Show the row: add it to a ListView, say
dvxLog("Contacts: %d: %s -- %s", (int)id, name, phone);
}
dvxSqlFreeResult(rs);
dvxSqlClose(db);
Chapter 7. Serial Links, Encryption, and Transfers
7.1. Serial Stack
-
rs232 (the serial library, serial.lib) — ISR-driven UART driver with ring buffers and flow control
-
packet (the secure link library, seclink.lib) — HDLC framing, CRC-16, Go-Back-N ARQ (reliable delivery)
-
security (the cryptography library, crypto.lib) — X25519 key exchange, XChaCha20-Poly1305, SHA-256/HMAC/HKDF, SHA-256 DRBG (and Ed25519, Diffie-Hellman, and XTEA-CTR for other uses)
-
secLink (the secure link library, seclink.lib) — authenticated handshake, channel multiplexing, per-packet encryption and MAC
The serial and cryptography libraries are part of every DVX; the secure link library comes with Communications.
Loaded as: bin/libs/kpunch/serial/serial.lib (rs232)
7.1.1. Layered Architecture
+--------------------------------------------------+ | Application | | | | secLinkSend() -- send on channel, opt. encrypt | | secLinkPoll() -- receive + dispatch | +--------------------------------------------------+ | secLink (handshake, channels, sealed frames) | +--------------------------------------------------+ | packet (HDLC framing, CRC-16, Go-Back-N ARQ) | +--------------------------------------------------+ | security -- X25519, XChaCha20-Poly1305, DRBG | | (used by secLink during handshake) | +--------------------------------------------------+ | rs232 (ISR-driven UART, 2048-byte rings) | +--------------------------------------------------+ | UART hardware (8250 / 16450 / 16550 / 16550A) | +--------------------------------------------------+
The security layer is invoked by secLink during the X25519 handshake and to seal and open every encrypted packet. It has no runtime coupling to rs232 or packet, so it can be used standalone for cryptographic operations independent of the serial stack.
7.2. RS-232 UART Driver
ISR-driven serial port driver supporting up to 4 simultaneous COM ports. A shared ISR drains UART FIFOs into per-port ring buffers (2048 bytes, power-of-2 for fast index wrapping). An interrupt the interrupt controller misses (its edge lost, seen under a flood in DOSBox, which then stops delivering received bytes) cannot stall a port: rs232Read, rs232WriteBuf, and rs232GetTxBuffered find the UART still holding an interrupt up and turn its interrupt enable off and on, which raises a fresh one, so a port that is polled at all never stays stuck. Flow control (XON/XOFF, RTS/CTS, DTR/DSR) operates within the ISR using watermark thresholds. All ISR data structures are DPMI-locked to prevent page faults. XON/XOFF bytes are queued for the transmit interrupt instead of being written over a byte still in the transmit register, and every cached register (IER, MCR) is changed with interrupts off so the ISR and the application never lose each other’s updates.
Header: serial/rs232.h
7.2.1. Port Constants
| Constant | Value | Description |
|---|---|---|
RS232_COM1 |
0 |
First serial port. |
RS232_COM2 |
1 |
Second serial port. |
RS232_COM3 |
2 |
Third serial port. |
RS232_COM4 |
3 |
Fourth serial port. |
RS232_NUM_PORTS |
4 |
Total number of supported COM ports. |
7.2.2. Handshake Modes
| Constant | Value | Description |
|---|---|---|
RS232_HANDSHAKE_NONE |
0 |
No flow control. |
RS232_HANDSHAKE_XONXOFF |
1 |
Software flow control (XON/XOFF characters). |
RS232_HANDSHAKE_RTSCTS |
2 |
Hardware flow control via RTS/CTS lines. |
RS232_HANDSHAKE_DTRDSR |
3 |
Hardware flow control via DTR/DSR lines. |
7.2.3. UART Types
Detected automatically by probing the scratch register and FIFO capability.
| Constant | Value | Description |
|---|---|---|
RS232_UART_UNKNOWN |
0 |
Detection failed. |
RS232_UART_8250 |
1 |
Original IBM PC UART. No FIFO. |
RS232_UART_16450 |
2 |
Has scratch register, no FIFO. |
RS232_UART_16550 |
3 |
Has FIFO but buggy (rare). |
RS232_UART_16550A |
4 |
Working 16-byte FIFO. Most common in 486+ hardware. |
7.2.4. Error Codes
| Constant | Value | Description |
|---|---|---|
RS232_SUCCESS |
0 |
Operation succeeded. |
RS232_ERR_UNKNOWN |
-1 |
Unknown error. |
RS232_ERR_NOT_OPEN |
-2 |
Port is not open. |
RS232_ERR_ALREADY_OPEN |
-3 |
Port is already open. |
RS232_ERR_NO_UART |
-4 |
No UART detected at port address. |
RS232_ERR_INVALID_PORT |
-5 |
Invalid port number. |
RS232_ERR_INVALID_BASE |
-6 |
Invalid base I/O address. |
RS232_ERR_INVALID_IRQ |
-7 |
Invalid IRQ number. |
RS232_ERR_INVALID_BPS |
-8 |
Invalid baud rate. |
RS232_ERR_INVALID_DATA |
-9 |
Invalid data bits value. |
RS232_ERR_INVALID_PARITY |
-10 |
Invalid parity character. |
RS232_ERR_INVALID_STOP |
-11 |
Invalid stop bits value. |
RS232_ERR_INVALID_HANDSHAKE |
-12 |
Invalid handshake mode. |
RS232_ERR_INVALID_FIFO |
-13 |
Invalid FIFO threshold. |
RS232_ERR_NULL_PTR |
-14 |
NULL pointer argument. |
RS232_ERR_IRQ_NOT_FOUND |
-15 |
Could not detect IRQ for port. |
RS232_ERR_LOCK_MEM |
-16 |
DPMI memory lock failed. |
RS232_ERR_NO_MEMORY |
-17 |
No memory for the port’s buffers. |
7.2.5. rs232Open
Open a COM port with the specified line parameters.
int32_t rs232Open(int32_t com, int32_t bps, int32_t dataBits, char parity, int32_t stopBits, int32_t handshake);
| Parameter | Description |
|---|---|
com |
Port index (RS232_COM1..RS232_COM4). |
bps |
Baud rate (e.g. 9600, 19200, 38400, 57600, 115200). |
dataBits |
Data bits per character (5, 6, 7, or 8). |
parity |
Parity mode: 'N' (none), 'O' (odd), 'E' (even), 'M' (mark), 'S' (space). |
stopBits |
Stop bits (1 or 2). |
handshake |
Flow control mode (RS232_HANDSHAKE_*). |
Returns RS232_SUCCESS or a negative error code. The port’s I/O base comes from the BIOS’s table, unless rs232SetBase set one for the port (a port the BIOS does not list opens only that way). The UART type is probed once here (RS232_ERR_NO_UART when nothing answers at the port address, or there is no address); only a 16550A gets its FIFO enabled and is fed 16 bytes per transmit interrupt, every other UART one byte.
The open port belongs to the program that opened it: when that program ends, however it ends (End Task or a crash too), a port it did not close is closed, so its interrupt handler does not run on until DVX exits.
7.2.6. rs232Close
Close a COM port and release its ISR resources. The modem control lines are left as they are: closing never drops DTR or RTS, so a modem stays connected and the next program to open the port can carry on. To hang up, call rs232SetDtr(com, false) before closing; the line stays down after the close. Opening a port raises DTR and RTS.
int32_t rs232Close(int32_t com);
7.2.7. rs232Read
Non-blocking read from the receive ring buffer.
int32_t rs232Read(int32_t com, char *data, int32_t len);
| Parameter | Description |
|---|---|
com |
Port index. |
data |
Buffer to receive data. |
len |
Maximum bytes to read. |
Returns the number of bytes actually read (may be less than len).
7.2.8. rs232Write
Blocking polled write directly to UART transmit holding register. Bypasses the TX ring buffer. Polls LSR_TX_HOLD_EMPTY before writing each byte (the check and the write happen with interrupts off, so a flow-control byte from the ISR is never overwritten), so it takes as long as the bytes take on the wire. Use for small, immediate writes where order matters; the packet layer uses rs232WriteBuf instead, so it never waits.
int32_t rs232Write(int32_t com, const char *data, int32_t len);
Returns the number of bytes actually written (may be less than len while flow control holds the line), or a negative error code (RS232_ERR_INVALID_PORT, RS232_ERR_NOT_OPEN, RS232_ERR_NULL_PTR).
7.2.9. rs232WriteBuf
Non-blocking write to the transmit ring buffer. The ISR drains buffered data to the UART asynchronously, through the transmit-hold-empty interrupt.
int32_t rs232WriteBuf(int32_t com, const char *data, int32_t len);
Returns the number of bytes actually queued (may be less than len if the buffer is full).
7.2.10. rs232Set
Change all line parameters on an open port. Internally calls rs232SetBps, rs232SetData, rs232SetParity, rs232SetStop, and rs232SetHandshake in sequence. Returns RS232_SUCCESS on success or the first negative error code encountered.
int32_t rs232Set(int32_t com, int32_t bps, int32_t dataBits, char parity, int32_t stopBits, int32_t handshake);
7.2.11. Configuration Getters
| Function | Returns |
|---|---|
rs232GetBase(com) |
I/O base address. |
rs232GetBps(com) |
Current baud rate (int32_t). |
rs232GetData(com) |
Data bits setting (5-8). |
rs232GetParity(com) |
Parity character: 'n', 'o', 'e', 'm', or 's' (lowercase). |
rs232GetStop(com) |
Stop bits setting (1 or 2). |
rs232GetHandshake(com) |
Handshake mode (RS232_HANDSHAKE_*). |
rs232GetIrq(com) |
IRQ number. |
rs232GetUartType(com) |
UART type probed when the port was opened (RS232_UART_*). |
rs232GetParity returns a lowercase character on success. Callers comparing against uppercase constants must use either both cases or tolower().
7.2.12. Status Getters
| Function | Returns |
|---|---|
rs232GetRxBuffered(com) |
Bytes waiting in the receive ring buffer. |
rs232GetTxBuffered(com) |
Bytes waiting in the transmit ring buffer. |
rs232GetCts(com) |
CTS line state (0 or 1). |
rs232GetDcd(com) |
DCD (carrier detect) line state (0 or 1), as last reported by the modem status interrupt. |
rs232GetDsr(com) |
DSR line state (0 or 1). |
rs232GetDtr(com) |
DTR line state (0 or 1). |
rs232GetRts(com) |
RTS line state (0 or 1). |
rs232GetLsr(com) |
Line status register value as last read; RS232_LSR_OVERRUN, RS232_LSR_PARITY_ERR, RS232_LSR_FRAME_ERR, and RS232_LSR_BREAK are its error bits. |
rs232GetMcr(com) |
Modem control register value. |
rs232GetMsr(com) |
Modem status register value; RS232_MSR_RI is the ring indicator. |
7.2.13. Configuration Setters
| Function | Description |
|---|---|
rs232SetBase(com, base) |
Set the I/O base address every later rs232Open of the port uses, instead of the one in the BIOS’s table: for a port the BIOS does not list (it cannot be opened otherwise) or lists wrong. Returns RS232_ERR_ALREADY_OPEN for an open port. |
rs232SetBps(com, bps) |
Change baud rate. |
rs232SetData(com, dataBits) |
Change data bits. |
rs232SetParity(com, parity) |
Change parity mode. |
rs232SetStop(com, stopBits) |
Change stop bits. |
rs232SetHandshake(com, handshake) |
Change flow control mode. Releases any throttle the old mode applied (raises RTS/DTR or sends XON) and starts the transmit side from the live CTS/DSR line. |
rs232SetIrq(com, irq) |
Move an open port to another IRQ (for a wrong auto-detection). Interrupt enables and DTR/RTS are kept. |
rs232SetMcr(com, mcr) |
Set modem control register directly. |
rs232SetDtr(com, dtr) |
Set DTR line state. The state is kept when the port is closed (dropping DTR is how a modem is hung up). |
rs232SetBreak(com, on) |
Hold the transmit line in the break (spacing) state (on = true) or release it. The caller times the break, typically 250-500 ms. |
rs232SetRts(com, rts) |
Set RTS line state. The state is kept when the port is closed. |
rs232SetFifoThreshold(com, thr) |
Set FIFO trigger level (1, 4, 8, or 14 bytes) or 0 to turn the FIFO off. Levels other than 0 return RS232_ERR_INVALID_FIFO unless the UART is a 16550A. rs232Open sets 8 on a 16550A (the 8 free bytes allow 0.7 ms of interrupt latency at 115200 bps; 14 allows only 0.17 ms) and 0 on other UARTs. |
7.3. Cryptography Library
Cryptographic primitives for DVX programs and libraries (the secure link, the package library, the network, and the shell’s random seed use them): the X25519 key exchange (RFC 7748), XChaCha20-Poly1305 authenticated encryption, Ed25519 signatures (RFC 8032), 1024-bit Diffie-Hellman key exchange (RFC 2409 Group 2), XTEA block cipher in CTR mode, SHA-256, HMAC-SHA256, and HKDF-SHA256, and a SHA-256 based random number generator. X25519, XChaCha20-Poly1305, and Ed25519 are Monocypher’s (thirdparty/monocypher, BSD license); the library keeps only the parts of it these functions use.
XTEA requires no lookup tables and compiles to approximately 20 instructions per round, making it suitable for 486-class hardware where AES S-box tables would thrash the 8KB cache. SHA-256 needs only 32-bit arithmetic and a 256-byte constant table.
Loaded as: bin/libs/kpunch/crypto/crypto.lib
Headers: crypto/security.h, crypto/secHash.h, crypto/secCurve.h
7.3.1. Constants
| Constant | Value | Description |
|---|---|---|
SEC_DH_KEY_SIZE |
128 |
Size of a DH public key or shared secret in bytes (1024 bits). |
SEC_XTEA_KEY_SIZE |
16 |
Size of an XTEA key in bytes (128 bits). |
SEC_RNG_SEED_SIZE |
32 |
Bytes stored in a seed file. |
SEC_SHA256_SIZE |
32 |
SHA-256 digest size. |
SEC_SHA256_BLOCK_SIZE |
64 |
SHA-256 block size. |
SEC_HKDF_MAX_OUT |
8160 |
Largest HKDF output (255 digests). |
SEC_X25519_KEY_SIZE |
32 |
An X25519 secret key, public key, or shared secret. |
SEC_AEAD_KEY_SIZE |
32 |
An XChaCha20-Poly1305 key. |
SEC_AEAD_NONCE_SIZE |
24 |
An XChaCha20-Poly1305 nonce. |
SEC_AEAD_TAG_SIZE |
16 |
The Poly1305 tag. |
SEC_ED25519_SEED_SIZE |
32 |
The random bytes an Ed25519 key pair is made from. |
SEC_ED25519_SECRET_SIZE |
64 |
An Ed25519 secret key (the seed, then the public key). |
SEC_ED25519_PUBLIC_SIZE |
32 |
An Ed25519 public key. |
SEC_ED25519_SIG_SIZE |
64 |
An Ed25519 signature. |
SEC_X25519_JOB_WORDS |
72 |
Size of a SecX25519JobT in 32-bit words. |
SEC_X25519_PENDING |
1 |
SecX25519Step (BASIC): more of the work to do. |
7.3.2. Error Codes
| Constant | Value | Description |
|---|---|---|
SEC_SUCCESS |
0 |
Operation succeeded. |
SEC_ERR_PARAM |
-1 |
Invalid parameter. |
SEC_ERR_NOT_READY |
-2 |
DH context not ready (keys not generated or secret not computed). |
SEC_ERR_IO |
-3 |
Seed file could not be read or written. |
7.3.3. RNG Functions
A SHA-256 hash DRBG over a 32-byte entropy pool. secRngAddEntropy hashes new bytes into the pool and never discards what is already there, so it is safe to call at any time, before or after the first output. Each output block is a hash of the pool and a counter; after every request the pool is re-hashed so earlier output cannot be recomputed from a later state.
The first secRngBytes call gathers hardware entropy automatically. On DOS that is 256 samples of the PIT counter, each taken after a busy wait sized by the previous sample, with the full time stamp counter on CPUs that have one (Pentium and later), else with the BIOS tick count. On a CPU without a time stamp counter the samples depend mostly on the PIT phase and time of day, which an observer can narrow down, so applications should feed user-input timings to secRngAddEntropy and keep a seed file: call secRngLoadSeed at startup and secRngSaveSeed at shutdown. Host builds read /dev/urandom.
Under the DVX shell this is automatic: the shell loads the seed file SECLINK.RND in the user folder at startup, feeds the timing of every key press and mouse event to secRngAddEntropy, and saves a fresh seed at shutdown. Applications only need their own calls when they run without the shell.
void secRngAddEntropy(const uint8_t *data, int32_t len);
void secRngBytes(uint8_t *buf, int32_t len);
int32_t secRngGatherEntropy(uint8_t *buf, int32_t len);
int secRngLoadSeed(const char *path);
int secRngSaveSeed(const char *path);
void secSecureZero(void *ptr, int len);
| Function | Description |
|---|---|
secRngAddEntropy |
Hash bytes into the pool (key timings, mouse positions, anything unpredictable). |
secRngBytes |
Generate pseudorandom bytes. |
secRngGatherEntropy |
Fill buf with condensed hardware entropy (one fresh gather per 32 bytes). Returns the byte count (0 if a host build cannot read its random device). |
secRngLoadSeed |
Mix a seed file into the pool, then immediately rewrite it with fresh output so a seed is never used twice. SEC_SUCCESS or SEC_ERR_IO. |
secRngSaveSeed |
Write SEC_RNG_SEED_SIZE bytes of fresh output for the next run. SEC_SUCCESS or SEC_ERR_IO. |
secSecureZero |
Zero memory in a way the compiler cannot optimize away (for key material). |
7.3.4. Hash Functions
void secSha256(const uint8_t *data, int32_t len, uint8_t digest[32]);
void secSha256Init(SecSha256T *ctx);
void secSha256Update(SecSha256T *ctx, const uint8_t *data, int32_t len);
void secSha256Final(SecSha256T *ctx, uint8_t digest[32]);
void secHmacSha256(const uint8_t *key, int32_t keyLen, const uint8_t *data, int32_t len, uint8_t mac[32]);
void secHmacInit(SecHmacT *h, const uint8_t *key, int32_t keyLen);
void secHmacUpdate(SecHmacT *h, const uint8_t *data, int32_t len);
void secHmacFinal(SecHmacT *h, uint8_t mac[32]);
int secHkdf(const uint8_t *salt, int32_t saltLen, const uint8_t *ikm, int32_t ikmLen, const uint8_t *info, int32_t infoLen, uint8_t *okm, int32_t okmLen);
bool secConstTimeEqual(const void *a, const void *b, int32_t len);
SHA-256 follows FIPS 180-4, HMAC RFC 2104, and HKDF RFC 5869 (extract and expand; a NULL or empty salt means 32 zero bytes). secHkdf returns SEC_ERR_PARAM for okmLen outside 1..SEC_HKDF_MAX_OUT. secConstTimeEqual compares without revealing where the inputs differ; use it for every MAC check.
7.3.5. Diffie-Hellman Key Exchange
1024-bit DH with 256-bit private exponents using the RFC 2409 Group 2 safe prime. The modular exponentiation is a Montgomery ladder with branch-free operand swaps, so its timing does not depend on the private key.
SecDhT *secDhCreate(void);
int secDhGenerateKeys(SecDhT *dh);
int secDhGetPublicKey(SecDhT *dh, uint8_t *buf, int *len);
int secDhComputeSecret(SecDhT *dh, const uint8_t *remotePub, int len);
int secDhGetSecret(SecDhT *dh, uint8_t *buf, int *len);
void secDhDestroy(SecDhT *dh);
| Function | Description |
|---|---|
secDhCreate |
Allocate a new DH context. |
secDhGenerateKeys |
Generate a private exponent and public key from the DRBG. |
secDhGetPublicKey |
Copy the local public key into buf. *len receives the key size. |
secDhComputeSecret |
Compute the shared secret from the remote public key. Keys outside [2, p-2] are rejected with SEC_ERR_PARAM (0, 1, and p-1 would force a trivially known secret). |
secDhGetSecret |
Copy the shared secret (SEC_DH_KEY_SIZE big-endian bytes) into buf. It is input for a key derivation function such as secHkdf, never a key by itself. |
secDhDestroy |
Securely zero and free the DH context. |
Typical usage order: secDhCreate, secDhGenerateKeys, exchange public keys, secDhComputeSecret, secDhGetSecret, secHkdf, secDhDestroy.
7.3.6. XTEA-CTR Cipher
XTEA in counter mode. Encrypt and decrypt are the same operation (XOR with keystream). The counter must never repeat with the same key.
SecCipherT *secCipherCreate(const uint8_t *key);
void secCipherCrypt(SecCipherT *c, uint8_t *data, int len);
void secCipherSetCounter(SecCipherT *c, uint64_t counter);
void secCipherDestroy(SecCipherT *c);
| Function | Description |
|---|---|
secCipherCreate |
Allocate a cipher context with a 128-bit key. Returns NULL on allocation failure or NULL key. Initial counter is zero. |
secCipherCrypt |
Encrypt or decrypt data in place. The 64-bit counter increments by one every 8 bytes (one XTEA block). |
secCipherSetCounter |
Position the 64-bit block counter (secLink derives it from the frame sequence number). |
secCipherDestroy |
Securely zero the cipher context (key and counter state) and free its memory. |
secCipherCreate returns NULL if the key pointer is NULL or allocation fails. secCipherCrypt is a no-op when any of c/data is NULL or len <= 0.
7.3.7. X25519 Key Exchange
Elliptic-curve Diffie-Hellman on Curve25519 (crypto/secCurve.h). Each side makes a secret key from 32 random bytes (secRngBytes), sends its public key, and combines its secret key with the other side’s public key; both get the same 32-byte secret. One call takes about a sixth of a second on a 486 (fixtures/bncurve on the emulated 486DX2-66: 165 ms), so a program that must stay responsive does it a slice at a time with a SecX25519JobT (the secure link does).
void secX25519PublicKey(uint8_t *publicKey, const uint8_t *secretKey);
bool secX25519(uint8_t *shared, const uint8_t *secretKey, const uint8_t *peerPublic);
void secX25519JobStart(SecX25519JobT *job, const uint8_t *secretKey, const uint8_t *peerPublic);
bool secX25519JobStep(SecX25519JobT *job);
bool secX25519JobResult(SecX25519JobT *job, uint8_t *out);
void secX25519JobWipe(SecX25519JobT *job);
secX25519 is false when the peer’s key gives an all-zero secret (one of the few keys that give everyone the same secret: a cheating peer). The secret is input for a key derivation function such as secHkdf, never a key by itself.
A job is the same computation in nine slices of about 20 ms each on a 486 (eight of the ladder, then the inversion): secX25519JobStart begins it (peerPublic NULL makes the public key of secretKey), secX25519JobStep does a slice and is true once there is nothing left, secX25519JobResult writes the result (false as secX25519 is, or before the job is done) and wipes the job, and secX25519JobWipe drops one. A SecX25519JobT is the caller’s (no allocation); the slicing is a small DVX patch to Monocypher (thirdparty/monocypher/DVX-VERSION.md).
7.3.8. XChaCha20-Poly1305
Authenticated encryption: the data is encrypted and a 16-byte tag proves it, and some associated data sent in the clear, unchanged.
void secAeadLock(const uint8_t *key, const uint8_t *nonce, const uint8_t *ad, int32_t adLen, uint8_t *data, int32_t len, uint8_t *tag);
bool secAeadUnlock(const uint8_t *key, const uint8_t *nonce, const uint8_t *ad, int32_t adLen, uint8_t *data, int32_t len, const uint8_t *tag);
Both work in place. secAeadUnlock decrypts only when the tag matches; otherwise it returns false and leaves data as it was. A key and nonce pair must never seal two different messages: a counter in the nonce (the secure link uses its frame number) or a fresh random nonce (24 bytes is enough to pick at random) keeps them apart.
7.3.9. Ed25519 Signatures
Public-key signatures (RFC 8032, with SHA-512), as the package library uses for add-on packages.
void secEd25519KeyPair(uint8_t *secretKey, uint8_t *publicKey, uint8_t *seed);
void secEd25519Sign(uint8_t *sig, const uint8_t *secretKey, const uint8_t *msg, int32_t len);
bool secEd25519Check(const uint8_t *sig, const uint8_t *publicKey, const uint8_t *msg, int32_t len);
secEd25519KeyPair makes the 64-byte secret key (the seed followed by the public key) and the public key from 32 random bytes, and wipes the seed. secSign.c holds these three and secCurve.c the rest, so a program that links the sources in (the host proxy) can leave the signatures out.
7.3.10. BASIC
src/include/basic/security.bas (DECLARE LIBRARY "crypto") declares the BASIC functions (crypto/secBas.c). Keys, data, and results are BINARY STRING (pointer and length in, a result buffer and length out), so every byte value passes; the result buffer is wiped before it is reused. A handle (1, 2, ...; 0 = none) is a key exchange, a cipher, or an incremental SHA-256 / HMAC; each records the program that made it and the shell’s app-cleanup hook frees (and wipes) what a program leaves open.
| BASIC | C it calls |
|---|---|
SecRandom$(count), SecAddEntropy bytes |
secRngBytes; secRngAddEntropy. |
SecDhCreate() |
secDhCreate + secDhGenerateKeys. |
SecDhPublicKey$(h), SecDhSecret$(h) |
secDhGetPublicKey; secDhGetSecret ("" before SecDhComputeSecret). |
SecDhComputeSecret(h, remotePublicKey) |
secDhComputeSecret: SEC_OK or a SEC_ERR_ code. |
SecDhFree h |
secDhDestroy. |
SecCipherCreate(key) |
secCipherCreate; 0 unless key is SEC_XTEA_KEY_SIZE bytes. |
SecCipherCrypt$(h, bytes) |
secCipherCrypt on a copy. |
SecCipherSetCounter h, counter |
secCipherSetCounter (a DOUBLE: exact up to 2^53). |
SecCipherFree h |
secCipherDestroy. |
SecSha256$(bytes); SecSha256Open, SecSha256Add, SecSha256End$ |
secSha256; secSha256Init / Update / Final (End frees the handle). |
SecHmac$(key, bytes); SecHmacOpen, SecHmacAdd, SecHmacEnd$ |
secHmacSha256; secHmacInit / Update / Final. |
SecHkdf$(salt, secret, info, length) |
secHkdf ("" for a length outside 1..SEC_HKDF_MAX_OUT). |
SecEqual(a, b) |
secConstTimeEqual (False for different lengths). |
SecX25519PublicKey$(secretKey) |
secX25519PublicKey ("" unless the key is SEC_X25519_KEY_SIZE bytes). |
SecX25519$(secretKey, otherPublicKey) |
secX25519 ("" for a wrong size or a refused key). |
SecX25519Start(secretKey, otherPublicKey) |
secX25519JobStart in a handle ("" otherPublicKey: the public key); 0 for wrong sizes. |
SecX25519Step(h); SecX25519End$(h); SecX25519Free h |
secX25519JobStep (SEC_X25519_PENDING, then SEC_OK); secX25519JobResult (frees the handle); secX25519JobWipe. |
SecAeadLock$(key, nonce, extra, bytes) |
secAeadLock on a copy: the ciphertext, then the tag. |
SecAeadUnlock$(key, nonce, extra, sealed) |
secAeadUnlock on a copy ("" when the tag does not match). |
SecEd25519KeyPair$(seed) |
secEd25519KeyPair: the secret key (the program’s seed is not wiped). |
SecEd25519PublicKey$(secretKey) |
The public key (the secret key’s last SEC_ED25519_PUBLIC_SIZE bytes). |
SecEd25519Sign$(secretKey, bytes) |
secEd25519Sign. |
SecEd25519Check(signature, publicKey, bytes) |
secEd25519Check (False for wrong sizes). |
The SEC_ CONSTs of security.bas are compared with security.h, secHash.h, and secCurve.h by a formrt test, which also calls every function for real.
7.4. Secure Link Library
Top-level API composing all three lower layers (rs232, packet, security) into a single interface. Provides an authenticated key exchange, channel multiplexing (0-127), and per-packet encryption with integrity protection over a reliable serial link.
Loaded as: bin/libs/kpunch/seclink/seclink.lib (part of Communications; needs the serial and cryptography libraries). The packet transport below it is in the same library.
Header: seclink/secLink.h
See also: Packet Transport (Section 7.5); End-to-End Example (Section 7.6); RS-232 UART Driver (the serial library) (Section 7.2); Cryptography Library (Section 7.3).
7.4.1. Protocol (version 3)
Every packet starts with a type byte:
| Type | Layout | Purpose |
|---|---|---|
HELLO |
type, version, flags, X25519 public key (32 bytes) |
Starts a key exchange. Flag bit 0: passphrase in use. |
CONFIRM |
type, HMAC-SHA256 (32 bytes) |
Proves both sides derived the same keys. |
PLAIN |
type, channel, payload |
Clear application data. |
CIPHER |
type, channel, ciphertext, tag (16 bytes) |
Encrypted, authenticated application data. |
Handshake packets are never delivered to the application, and application data is never taken as key material. A HELLO is kept whenever it arrives, so the side that starts first is never missed.
Key exchange: X25519 (RFC 7748). An X25519 takes about a sixth of a second on a 486, so each poll computes a ninth of one (about 20 ms there): first the side’s public key, then the shared secret once both HELLOs are in, so the handshake never holds up other programs for long. A peer key that gives an all-zero secret fails the exchange (SECLINK_ERR_HANDSHAKE).
Key derivation: HKDF-SHA256 with salt = SHA-256(passphrase) (32 zero bytes without one), input = the X25519 shared secret, and info = "DVX secLink v3" followed by the lower then the higher public key. The output supplies a 32-byte sending key for each direction plus a confirmation key; the side with the lower public key sends with the "low" key. Directions never share a key.
Confirmation: each side sends HMAC(confirmation key, SHA-256(lower HELLO + higher HELLO) + role byte). A different passphrase, a passphrase on only one side, or a modified HELLO makes the check fail on both sides with SECLINK_ERR_AUTH. A side that has a passphrase never accepts a peer without one.
Encrypted frames: XChaCha20-Poly1305. Each direction numbers its encrypted frames with an implicit 64-bit sequence number that is never sent; a frame’s nonce is that number, little-endian, followed by 16 zero bytes. The type and channel bytes are authenticated (associated data), the payload is encrypted, and the 16-byte Poly1305 tag follows it. Every frame is sealed on its own, so tampered, replayed, or injected frames fail the tag, are dropped and counted (secLinkGetDropped), and later frames still verify.
Without a passphrase the link is encrypted and integrity-protected but not authenticated: an active attacker in the middle could run two separate exchanges. Use the same passphrase on both sides to rule that out.
Clear frames are accepted only until the first session is established. From then on, until secLinkClose, a clear frame is delivered only on a channel marked plaintext with secLinkSetChannelPlain — even after the session was dropped by a packet-layer reset or a failed re-key, which someone on the line can cause; so neither can turn a protected channel into a clear one. A re-key HELLO on a running session whose protocol version or passphrase flag cannot match is dropped (and counted) without ending the session.
7.4.2. Constants
| Constant | Value | Description |
|---|---|---|
SECLINK_PROTOCOL_VERSION |
3 |
Version carried in HELLO; a mismatch fails the handshake. |
SECLINK_FRAME_HDR_SIZE |
2 |
Type byte plus channel byte. |
SECLINK_MAC_SIZE |
16 |
Poly1305 tag on encrypted frames (SEC_AEAD_TAG_SIZE). |
SECLINK_MAX_PAYLOAD |
237 |
Maximum payload per send (PKT_MAX_PAYLOAD minus header and tag), clear or encrypted. |
SECLINK_MAX_CHANNEL |
127 |
Highest valid channel number. |
SECLINK_NUM_CHANNELS |
128 |
Array size needed to hold one slot per channel (SECLINK_MAX_CHANNEL + 1). |
SECLINK_CHAN_BUF_SIZE |
4096 |
Recommended per-channel receive buffer size for callers that buffer inbound data between the receive callback and an application read. |
7.4.3. Error Codes
| Constant | Value | Description |
|---|---|---|
SECLINK_SUCCESS |
0 |
Operation succeeded. |
SECLINK_ERR_PARAM |
-1 |
Invalid parameter (NULL pointer, bad channel, bad length). |
SECLINK_ERR_SERIAL |
-2 |
Serial port closed or disconnected (secLinkPoll). |
SECLINK_ERR_HANDSHAKE |
-4 |
Handshake failed: invalid public key, protocol version mismatch, reflected HELLO, a dead port or a line that died once the peer answered, or the peer reset mid-exchange. |
SECLINK_ERR_NOT_READY |
-5 |
No session keys yet (encrypted send attempted). |
SECLINK_ERR_SEND |
-6 |
Packet send failed, the peer stopped acknowledging, or a non-blocking send found the window full. |
SECLINK_ERR_TIMEOUT |
-7 |
The peer did not complete the handshake within 30 seconds (secLinkHandshake; the exchange stays pending), or the line went silent before it answered at all (secLinkHandshakeStep). |
SECLINK_ERR_AUTH |
-8 |
Passphrase mismatch, passphrase on only one side, or tampering. |
SECLINK_PENDING |
1 |
secLinkHandshakeStep only: the exchange is still running. |
7.4.4. SecLinkRecvT
Receive callback type. Delivers plaintext with the channel number. encrypted is true when the frame arrived encrypted and its tag verified, false for a clear frame.
typedef void (*SecLinkRecvT)(void *ctx, const uint8_t *data, int len, uint8_t channel, bool encrypted);
7.4.5. secLinkOpen
Open a secure serial link. Opens the COM port via rs232Open and creates a packet layer (default window size) with an internal receive dispatcher. The handshake must be performed separately via secLinkHandshake before encrypted data can be sent.
SecLinkT *secLinkOpen(int com, int32_t bps, int dataBits, char parity, int stopBits, int handshake, SecLinkRecvT callback, void *ctx);
| Parameter | Description |
|---|---|
com |
COM port index (RS232_COM1..RS232_COM4). |
bps |
Baud rate. |
dataBits |
Data bits per character (5-8). |
parity |
Parity mode ('N', 'O', 'E', 'M', 'S', or lowercase). |
stopBits |
Stop bits (1 or 2). |
handshake |
Flow control mode (RS232_HANDSHAKE_*), but not RS232_HANDSHAKE_XONXOFF: the frames carry the XON and XOFF bytes as data, and the serial driver would take them out of the stream (the connection library refuses it). |
callback |
Called when a packet is received, after verification and decryption. The data pointer is valid only during the callback. |
ctx |
User pointer passed to the callback. |
Returns an opaque SecLinkT handle, or NULL on failure (allocation failure, rs232Open error, or pktOpen error). On failure all partially initialized resources are cleaned up.
7.4.6. secLinkOpenStream
Open a secure link over a byte stream (see pktOpenStream) instead of a COM port, e.g. a TCP connection to the host proxy’s listening port. Everything else — handshake, passphrase, channels, sending, and polling — is the same as for a COM port link. secLinkClose does not close the stream; the caller closes it afterwards.
SecLinkT *secLinkOpenStream(const PktStreamT *stream, SecLinkRecvT callback, void *ctx);
7.4.7. secLinkClose
Close the link and free all associated resources: wipe the key material, close the packet layer and the COM port, and free the link. Safe to call with a NULL link (no-op). Safe to call from inside the receive callback: the close then happens when the outermost secLink call returns, and no further packets are delivered.
A link belongs to the program that opened it. When that program ends, however it ends (End Task or a crash too), a link it did not close has its COM port (or its packet layer over a stream) let go and its keys wiped at once; from then on every call on it fails as on a dead line, and secLinkClose frees it.
void secLinkClose(SecLinkT *link);
7.4.8. secLinkSetPassphrase
Set the shared passphrase for the next handshake. NULL or "" clears it. Only SHA-256 of the text is kept. Set it before calling secLinkHandshake; both sides must use the same passphrase, or both none. An exchange already in progress (for example one left pending by a timed-out secLinkHandshake) was started with the old setting, so it is abandoned: the next secLinkHandshake starts a fresh one.
int secLinkSetPassphrase(SecLinkT *link, const char *pass);
Returns SECLINK_SUCCESS or SECLINK_ERR_PARAM for a NULL link.
7.4.9. secLinkHandshake
Run the authenticated X25519 key exchange. Waits, polling the packet layer, until both CONFIRM messages have been checked, or until 30 seconds pass. Between two polls it gives the others their turn (pktYield): the other programs keep running, and so does DVX when the caller is a program with its own main loop (hasMainLoop), which runs on a task of its own. A window callback runs on DVX’s own task, so DVX waits with it there: a callback-only program runs the exchange with secLinkHandshakeStep from a timer instead.
int secLinkHandshake(SecLinkT *link);
Behavior:
-
A fresh X25519 key pair is made from the DRBG and our HELLO is sent. If the peer’s HELLO already arrived (it started first), the shared secret follows on the next poll.
-
The X25519 secret key is wiped as soon as the session keys are derived (forward secrecy).
-
After SECLINK_ERR_TIMEOUT the exchange stays pending: it still completes during secLinkPoll if the peer shows up, and calling secLinkHandshake again resumes the wait without sending a new key.
-
On a ready link it negotiates fresh session keys. A peer that is already ready (or has an exchange pending) answers automatically from secLinkPoll.
-
Encrypted traffic under the previous keys that was sent before the new HELLO is still accepted; encrypted sends are refused (SECLINK_ERR_NOT_READY) until the new exchange completes.
Returns SECLINK_SUCCESS, SECLINK_ERR_PARAM, SECLINK_ERR_HANDSHAKE, SECLINK_ERR_TIMEOUT, or SECLINK_ERR_AUTH. When the peer confirms (or rejects) and hangs up in the same poll — a proxy exits as soon as it sees a passphrase mismatch — the exchange’s outcome is reported, not the disconnect.
7.4.10. secLinkHandshakeStep
Non-blocking handshake for callers that run their own event loop.
int secLinkHandshakeStep(SecLinkT *link);
Starts an exchange on an idle link (never handshaken, or dropped by a peer reset), polls once, and returns SECLINK_SUCCESS once the link is ready, SECLINK_PENDING (1) while the exchange is still running, or the error that ended it (the same codes as secLinkHandshake). SECLINK_ERR_TIMEOUT here means the packet layer gave up on the line (PKT_LINK_TIMEOUT_MS) while the peer had not answered at all; the caller’s own limit is its to keep. A failed exchange keeps returning its error; secLinkHandshake starts a new one.
7.4.11. secLinkSend
Send data on a channel, optionally encrypted and authenticated.
int secLinkSend(SecLinkT *link, const uint8_t *data, int len, uint8_t channel, bool encrypt, bool block);
| Parameter | Description |
|---|---|
link |
Connection handle from secLinkOpen. |
data |
Plaintext payload. |
len |
Payload length. Must be in 1..SECLINK_MAX_PAYLOAD. |
channel |
Logical channel number (0..SECLINK_MAX_CHANNEL). |
encrypt |
If true, seal (encrypt and tag) before sending (requires a completed handshake). |
block |
If true, wait (pumping the receive callback, and giving the others their turn between two polls, as secLinkHandshake does) until the transmit window has space, at most PKT_SEND_TIMEOUT_MS without an acknowledgment. If false, return SECLINK_ERR_SEND immediately when the window is full (what a window callback should use). |
Returns SECLINK_SUCCESS on success or a negative error code (SECLINK_ERR_PARAM, SECLINK_ERR_NOT_READY, SECLINK_ERR_SEND).
A frame takes its sequence number only once window space is guaranteed, and is queued without pumping in between, so frames always reach the wire in sequence order. The receive callback may itself send (blocking or not), including encrypted.
Once session keys exist the receiver drops clear frames unless it marked the channel plaintext with secLinkSetChannelPlain.
7.4.12. secLinkSendBuf
Send an arbitrarily large buffer by splitting into SECLINK_MAX_PAYLOAD chunks, each sent as secLinkSend with block true: it waits (the others running meanwhile, as for secLinkHandshake) until all of it is queued.
int secLinkSendBuf(SecLinkT *link, const uint8_t *data, int len, uint8_t channel, bool encrypt);
Returns SECLINK_SUCCESS or the first error encountered.
7.4.13. secLinkSetChannelPlain
Allow (plain = true) or refuse (plain = false, the default) clear frames on a channel once session keys exist. Before the first handshake clear frames are always accepted.
int secLinkSetChannelPlain(SecLinkT *link, uint8_t channel, bool plain);
Returns SECLINK_SUCCESS or SECLINK_ERR_PARAM for a bad link or channel.
7.4.14. secLinkPoll
Poll for incoming data. Drains the serial port, processes frames and retransmits, completes pending handshake steps, verifies and decrypts data frames, and forwards them to the callback.
int secLinkPoll(SecLinkT *link);
Returns the number of packets delivered by the packet layer this call, SECLINK_ERR_PARAM if link is NULL, or SECLINK_ERR_SERIAL when the port is closed or disconnected. Must be called frequently in the main loop.
If the remote packet layer resets, the session keys are dropped (the link is no longer ready) and a new handshake is needed. Clear frames stay refused on protected channels (see Protocol).
7.4.15. secLinkIsReady
Check whether the handshake is complete and the link is ready for encrypted traffic. Cleartext sends do not require the link to be ready.
bool secLinkIsReady(SecLinkT *link);
7.4.16. secLinkGetDropped
Number of received frames dropped since open: bad tag (tampered, replayed, or injected), clear frames on a protected channel, encrypted frames without session keys, and malformed frames.
int32_t secLinkGetDropped(SecLinkT *link);
Returns the count or SECLINK_ERR_PARAM when link is NULL.
7.4.17. secLinkGetPending
Get the number of unacknowledged packets in the transmit window. Delegates directly to pktGetPending on the underlying packet connection. Useful for non-blocking send loops to decide when to throttle.
int secLinkGetPending(SecLinkT *link);
Returns the pending count on success or SECLINK_ERR_PARAM when link is NULL.
7.5. Packet Transport
Reliable, ordered packet delivery over an RS-232 serial link. Uses HDLC-style byte-stuffed framing for frame delimiting, CRC-16-CCITT for error detection, and Go-Back-N ARQ with a configurable sliding window for retransmission.
Header: seclink/packet.h
7.5.1. Constants
| Constant | Value | Description |
|---|---|---|
PKT_MAX_PAYLOAD |
255 |
Maximum bytes per packet payload. |
PKT_DEFAULT_WINDOW |
4 |
Default sliding window size (unacknowledged frames in flight). |
PKT_MAX_WINDOW |
8 |
Maximum sliding window size. |
7.5.2. Error Codes
| Constant | Value | Description |
|---|---|---|
PKT_SUCCESS |
0 |
Operation succeeded. |
PKT_ERR_INVALID_PARAM |
-1 |
Invalid parameter (NULL handle, bad data pointer, length out of range). |
PKT_ERR_TX_FULL |
-2 |
Transmit window is full (non-blocking send only). |
PKT_ERR_DISCONNECTED |
-3 |
Serial port returned a negative read (disconnect/error), or the connection was closed from its own callback. |
PKT_ERR_TIMEOUT |
-4 |
A blocking send got no acknowledgment for PKT_SEND_TIMEOUT_MS (15000 ms). |
7.5.3. PktRecvCallbackT
Callback type for received packets.
typedef void (*PktRecvCallbackT)(void *ctx,
const uint8_t *data, int len);
| Parameter | Description |
|---|---|
ctx |
User context pointer (passed to pktOpen). |
data |
Payload bytes (valid only during the callback). |
len |
Payload length. |
7.5.4. pktOpen
Open a packetized connection over an already-open COM port. Only one packet connection may exist on a given COM port at a time; a second pktOpen call on the same port returns NULL to avoid silent framing corruption.
PktConnT *pktOpen(int com, int windowSize,
PktRecvCallbackT callback, void *callbackCtx);
| Parameter | Description |
|---|---|
com |
COM port index (RS232_COM1..RS232_COM4). Must already be open via rs232Open. |
windowSize |
Sliding window size (1..PKT_MAX_WINDOW). Pass 0 for PKT_DEFAULT_WINDOW. Values greater than PKT_MAX_WINDOW are clamped. |
callback |
Called when a complete, CRC-verified, in-order packet is received. The data pointer is valid only during the callback. |
callbackCtx |
User pointer passed to the callback. |
Returns an opaque PktConnT handle, or NULL on failure (invalid port, duplicate open, or allocation failure).
7.5.5. pktOpenStream
Open a packetized connection over any byte stream instead of a COM port — a TCP socket, for example. The stream is described by non-blocking calls and a context pointer, copied into the connection. Any number of stream connections may be open.
typedef struct {
int32_t (*read)(void *ctx, uint8_t *buf, int32_t len);
int32_t (*write)(void *ctx, const uint8_t *data, int32_t len);
void *ctx;
int32_t (*pending)(void *ctx);
} PktStreamT;
PktConnT *pktOpenStream(const PktStreamT *stream, int windowSize, PktRecvCallbackT callback, void *callbackCtx);
| Member | Description |
|---|---|
read |
Up to len bytes into buf: the count, 0 when nothing has arrived, negative when the stream is gone (pktPoll then reports PKT_ERR_DISCONNECTED). |
write |
Bytes taken from data (0 = none right now), negative when the stream is gone. Frames wait in the connection’s transmit queue, and each pktPoll hands the stream what it takes; a frame that finds no room in the queue is dropped (a data frame is sent again by its retransmit timer). |
ctx |
Passed to the calls. |
pending |
Bytes taken but not yet on the wire (NULL: the stream does not say). Retransmit timers wait while there are any and their count keeps moving: a count that stays the same for 2 seconds (flow control holding the line) no longer holds them. |
Returns the handle, or NULL for a NULL stream or call, or on allocation failure. pktClose never closes the stream.
7.5.6. pktClose
Close a packetized connection and release its registry slot. Does not close the underlying COM port. The caller is responsible for calling rs232Close separately when no longer needed. May be called from inside the receive callback: the connection is then freed when the outermost pktPoll returns (which reports PKT_ERR_DISCONNECTED). A connection belongs to the program that opened it: one the program leaves open is closed when the program ends, however it ends.
void pktClose(PktConnT *conn);
7.5.7. pktSend
Send a data packet. The payload is copied into an internal retransmit slot before transmission, so the caller may reuse the supplied buffer immediately.
int pktSend(PktConnT *conn, const uint8_t *data,
int len, bool block);
| Parameter | Description |
|---|---|
conn |
Connection handle from pktOpen. |
data |
Payload bytes (1..PKT_MAX_PAYLOAD). |
len |
Payload length. |
block |
If true, wait for transmit window space via pktWaitSpace (the others run meanwhile). If false, return PKT_ERR_TX_FULL immediately when the window is full. |
Returns PKT_SUCCESS on success, PKT_ERR_INVALID_PARAM for NULL/out-of-range input, PKT_ERR_TX_FULL for a non-blocking call with a full window, PKT_ERR_DISCONNECTED if the serial port drops during a blocking wait, or PKT_ERR_TIMEOUT if the peer stops acknowledging. A frame the port accepts only partially (flow control) is completed before the call returns.
7.5.8. pktPoll
Poll for incoming data, process received frames, and handle retransmits. Must be called frequently in the main loop. The callback is invoked synchronously for each complete, CRC-verified, in-order data frame and may call pktSend or pktPoll again: received bytes are consumed from a per-connection buffer, so a nested call continues the same byte stream in order. After a gap in the sequence only one NAK is sent until the missing frame arrives (go-back-N resends the whole window on one NAK).
int pktPoll(PktConnT *conn);
Returns the number of valid data packets delivered to the callback this call, or PKT_ERR_INVALID_PARAM if conn is NULL, or PKT_ERR_DISCONNECTED if the serial layer returned a negative read.
7.5.9. pktReset
Reset the local connection state (sequence numbers, transmit slots, RX state machine) and send a RST frame to the remote side. The remote’s RST handler clears its own state (discarding its unacknowledged frames), runs its reset callback, and answers with a RST reply. A RST reply that answers no reset of ours is ignored. Useful for recovering from a desynchronized connection.
int pktReset(PktConnT *conn);
Returns PKT_SUCCESS on success or PKT_ERR_INVALID_PARAM if conn is NULL.
7.5.10. pktCanSend
Check whether there is room in the transmit window for another packet. Returns false when conn is NULL or the transmit window is full.
bool pktCanSend(PktConnT *conn);
7.5.11. pktGetPending
Get the number of unacknowledged packets currently in the transmit window. Ranges from 0 (all sent packets acknowledged) to windowSize (window full).
int pktGetPending(PktConnT *conn);
Returns the pending count on success, or PKT_ERR_INVALID_PARAM if conn is NULL.
7.5.12. pktSetResetCallback
Register a callback run when the remote side resets the connection (its unacknowledged frames are gone at that point, so an upper layer with per-frame state must resynchronize). The callback receives the ctx passed to pktOpen. NULL removes it.
typedef void (*PktResetCallbackT)(void *ctx);
void pktSetResetCallback(PktConnT *conn, PktResetCallbackT callback);
7.5.13. pktWaitSpace
Poll until the transmit window has room, with a pktYield between two polls. The wait restarts whenever an acknowledgment frees a slot, so only a peer that stops acknowledging times out.
int pktWaitSpace(PktConnT *conn);
Returns PKT_SUCCESS, PKT_ERR_INVALID_PARAM, PKT_ERR_DISCONNECTED, or PKT_ERR_TIMEOUT after PKT_SEND_TIMEOUT_MS without progress.
7.5.14. pktYield and pktSetYield
What every wait of this library does between two polls: pktWaitSpace, pktSend with block, secLinkHandshake, secLinkSend with block, and secLinkSendBuf. In DVX it is tsYield, so the other programs keep running while one waits (and DVX too, when the waiting program has its own main loop); outside DVX (the host proxy) it does nothing. pktSetYield replaces it for every connection, for a program with its own way of keeping things going; NULL restores the default.
typedef void (*PktYieldFnT)(void);
void pktSetYield(PktYieldFnT fn);
void pktYield(void);
7.6. End-to-End Example
Below is the session of a secure BBS client: it opens COM1, runs the authenticated key exchange, and then shuttles terminal traffic over a single encrypted channel. It demonstrates the typical serial stack usage: load the RNG seed file, open the link, set the passphrase, run the handshake, then enter a poll and send loop. It belongs to a program with its own main loop (hasMainLoop = true), whose appMain calls bbsSession: on the program’s own task the waits in secLinkHandshake and secLinkSendBuf let DVX and the other programs run.
#include "dvxPlat.h"
#include "taskSwch.h"
#include "rs232.h"
#include "security.h"
#include "secLink.h"
#include <stdbool.h>
#include <string.h>
#define CHAN_TERMINAL 0
#define SEED_FILE "SECLINK.RND"
static bool sQuit = false; // set by the window's onClose
static void onPacket(void *ctx, const uint8_t *data, int len, uint8_t channel, bool encrypted) {
(void)ctx;
if (channel == CHAN_TERMINAL && encrypted) {
// Show the len bytes of data in the program's window (a Terminal
// control, say).
}
}
// The session, run from appMain on the program's own task.
static int32_t bbsSession(void) {
// Carry entropy over from the last run (hardware entropy is
// gathered automatically; feed key timings with secRngAddEntropy).
secRngLoadSeed(SEED_FILE);
// Open the link at 115200 8N1 with RTS/CTS flow control.
SecLinkT *link = secLinkOpen(RS232_COM1, 115200, 8, 'N', 1, RS232_HANDSHAKE_RTSCTS, onPacket, NULL);
if (!link) {
dvxLog("BBS: secLinkOpen failed");
return -1;
}
// Authenticated key exchange. The proxy must use the same passphrase.
secLinkSetPassphrase(link, "shared secret words");
if (secLinkHandshake(link) != SECLINK_SUCCESS) {
dvxLog("BBS: handshake failed");
secLinkClose(link);
return -1;
}
// Send an encrypted banner, then relay the user's typing.
const char *hello = "Hello, secure BBS!\r\n";
secLinkSendBuf(link, (const uint8_t *)hello, (int)strlen(hello), CHAN_TERMINAL, true);
while (!sQuit) {
// Deliver any incoming packets to onPacket().
if (secLinkPoll(link) < 0) {
break;
}
// Forward what the user typed (kept by the window's key
// handler) with secLinkSend(link, bytes, n, CHAN_TERMINAL, true,
// true), then give the others their turn.
tsYield();
}
secLinkClose(link);
secRngSaveSeed(SEED_FILE);
return 0;
}
Notes:
-
secLinkOpen internally calls rs232Open and pktOpen. secLinkClose tears them down in reverse order.
-
The DRBG gathers hardware entropy on first use. On a CPU without a time stamp counter that alone is guessable; the seed file and user-input timings (secRngAddEntropy) are what make the X25519 keys unpredictable.
-
secLinkPoll must be called frequently to drain the RX ring buffer, process ACKs, and dispatch received packets to the callback.
-
For bulk transfers larger than SECLINK_MAX_PAYLOAD (237 bytes), use secLinkSendBuf which splits the data into chunks automatically.
-
A callback-only program runs on DVX’s own task, where every wait holds DVX up: it calls secLinkHandshakeStep and secLinkPoll from a timer, and sends with block false. The connection library (conn.h) does all of this for a terminal-style link.
-
A link the program leaves open has its port let go when the program ends, however it ends (see secLinkClose).
7.7. Connection Library
One interface for byte-stream connections: a serial port, a modem with an AT command dialer, the secure link to the DVX host proxy (over a COM port or over the network), and Telnet. Every call is non-blocking: connOpen starts the connection (looking the host name up, dialing, TCP connect, key exchange) and connPoll moves it along, fills the receive buffer, and sends what connWrite queued. Call connPoll as often as you can (every frame). A host name is looked up in the background (connPoll asks how far the lookup got); a dotted address needs no lookup.
A connection belongs to the program that created it: when the program ends, however it ends (End Task or a crash too), a connection it did not destroy is destroyed (a modem hangs up, and the port, link, or socket is let go).
Loaded as: bin/libs/kpunch/conn/conn.lib (needs the serial, secure link, and transfer libraries — the transfer library for its BASIC functions; the networking library, for Telnet and a secure link over the network, is looked up when such a connection starts)
Header: conn/conn.h
7.7.1. Connection Types
- ConnSerialE
-
A COM port with the given speed, data bits, parity, stop bits, and flow control (none, XON/XOFF, RTS/CTS). Open at once.
- ConnModemE
-
The COM port, then the init string (waits for OK), then dial prefix + phone number. CONNECT opens the connection; BUSY, NO ANSWER, and NO CARRIER dial again after redialDelay seconds, up to redialCount more times; NO DIAL TONE and ERROR end it. An empty phone number opens the port for typing AT commands. When the carrier (DCD) has been seen and drops, the connection ends. Closing drops DTR, which makes the modem hang up. Everything the modem says is also delivered as received data.
- ConnSecureE
-
The secure link (secLink): the key exchange runs in the background, authenticated when a passphrase is set (both sides must use the same one, or none). Only encrypted, authenticated data on channel 0 is delivered. With host empty it runs on the COM port; with host set it runs over a TCP connection to host:tcpPort (the proxy’s listening port, 2323 by default), through secLinkOpenStream. On the COM port it cannot use XON/XOFF flow control (the frames carry the XON and XOFF bytes as data, and the serial driver would take them out of the stream): connOpen then returns CONN_ERR_PARAM with the status "The secure link cannot use XON/XOFF flow control: choose None or RTS/CTS".
- ConnTelnetE
-
TCP to host:tcpPort with Telnet (RFC 854). Negotiated: the host may ECHO and SUPPRESS-GO-AHEAD; BINARY both ways; TERMINAL-TYPE answered "ANSI"; NAWS sends the size given to connSetWindowSize (80 x 25 until then, sent again on every change). Other options are refused, and an option is only answered when its state changes. 0xFF is doubled on the way out and undoubled on the way in; outside binary mode a lone CR goes out as CR NUL and CR NUL comes in as CR.
The Telnet protocol itself is a separate filter (connTelnet.c) that only moves bytes, so it is tested byte for byte without a network.
7.7.2. ConnConfigT
| Field | Meaning |
|---|---|
type |
ConnTypeE. |
comPort |
RS232_COM1 .. RS232_COM4. |
bps, dataBits, parity |
Line settings (parity 'N', 'E', 'O', 'M', or 'S'). |
stopBits, flow |
1 or 2 stop bits; RS232_HANDSHAKE_* flow control. |
initString, dialPrefix |
Modem: sent before dialing (empty = none); dial command such as ATDT. |
phone |
Modem: the number (empty = no dialing). |
redialCount, redialDelay |
Modem: extra attempts and the seconds between them. |
passphrase |
Secure link: the shared secret (empty = none). |
host, tcpPort |
Telnet; secure link over the network (host set) or over the COM port (host empty). A name or a dotted address. |
7.7.3. Functions
| Function | Description |
|---|---|
ConnT *connCreate(void) |
Allocate a closed connection. |
void connDestroy(c) |
Close and free. A connection the program does not destroy is destroyed when the program ends, however it ends. |
void connConfigDefaults(cfg) |
COM1, 9600 8N1, no flow control, ATZ, ATDT. |
int32_t connOpen(c, cfg, nowMs) |
Start connecting (cfg is copied). CONN_OK, CONN_ERR_PARAM, CONN_ERR_PORT, or CONN_ERR_NO_NET (Telnet, or a secure link over the network, without the networking library); connStatus explains. A network host is looked up and connected to while connPoll runs (never waiting inside one call), so later failures (the host not found, refused, no answer within 30 seconds, connection lost, host closed it) end the connection with the reason in connStatus. |
void connPoll(c, nowMs) |
Dial, key exchange, receive, send, timers. |
int32_t connRead(c, buf, max) |
Take received bytes (0 when none). |
int32_t connWrite(c, data, len) |
Queue bytes to send; returns the count accepted (0 while not open or when the 8 KB send buffer is full). |
int32_t connPending(c) |
Bytes queued (here and in the layer below) not yet sent. |
bool connSendBreak(c, nowMs) |
Hold a break for 300 ms (serial and modem). |
void connClose(c) |
Close; a modem hangs up. |
ConnStateE connState(c) |
ConnClosedE, ConnOpeningE (dialing, key exchange), or ConnOpenE. |
const char *connStatus(c) |
What is happening, or why the connection ended, in plain words. |
uint32_t connStatusSerial(c) |
Changes whenever the status text changes. |
void connSetWindowSize(c, cols, rows) |
The terminal size for Telnet’s NAWS (sent now if the host asked for it). |
bool connTypeAvailable(type) |
True for every ConnTypeE value but ConnTelnetE when the networking library is not installed (an optional part of DVX; connections over the network then end at once with CONN_ERR_NO_NET). conn.lib does not import the networking library: it looks its calls up when a network connection starts. |
bool connCanBreak(type) |
True for serial and modem. |
const char *connErrorText(err) |
Text for a connOpen result. |
7.7.4. Example
ConnT *c = connCreate();
ConnConfigT cfg;
connConfigDefaults(&cfg);
cfg.type = ConnModemE;
snprintf(cfg.phone, sizeof(cfg.phone), "555-0100");
connOpen(c, &cfg, nowMs());
// every frame:
connPoll(c, nowMs());
n = connRead(c, buf, sizeof(buf));
A Telnet session is the same with cfg.type = ConnTelnetE, cfg.host = "bbs.example.org", and cfg.tcpPort = 23.
A file transfer runs over a connection by giving the transfer library connRead, connWrite, and connPending as its XferIoT callbacks (ZMODEM over Telnet works: 0xFF bytes are escaped by the Telnet filter).
7.8. Connections from BASIC
Add conn.bas to a BASIC project (and xfer.bas for transfers): connBas.c gives BASIC the connection library by handle, plus what a terminal program needs around it. The Terminal program is written this way.
| Function | Description |
|---|---|
ConnCreate() |
A closed connection with connConfigDefaults; a handle, or 0. |
ConnSetSerial h, com, bps, data, parity$, stop, flow |
COM port 1-4 and its framing (flow: CONN_FLOW_NONE, _XONXOFF, _RTSCTS; a secure link on the COM port cannot use _XONXOFF). |
ConnSetModem h, init$, prefix$, phone$, redials, delay |
The modem’s commands and redialing. |
ConnSetHost h, host$, port |
Telnet; the secure link over the network ("" = over the COM port). |
ConnSetPassphrase h, pass$ |
The secure link’s passphrase, forgotten once ConnOpen used it. |
ConnSetWindowSize h, cols, rows |
connSetWindowSize. |
ConnSetXferWindow h, bytes |
XferOptionsT.rxWindow of the transfers started later: 0 = no limit, up to XFER_WINDOW_MAX; -1 (the default) = by the line, see below. |
ConnOpen(h, type) |
connOpen with type and the settings so far. |
ConnErrorText$(code) |
connErrorText of a ConnOpen result. |
ConnPoll h |
One step: connPoll, then the running transfer (canceled when the line drops), else what arrived to the attached Terminal (see below). Call it from a Timer. |
ConnState, ConnStatus$, ConnStatusSerial |
connState, connStatus, connStatusSerial. |
ConnWrite(h, bytes$), ConnRead$(h), ConnPending(h) |
Bytes out and in without a Terminal: connWrite / connRead with BINARY STRING data, so every byte value passes. |
ConnCanBreak(type), ConnSendBreak(h) |
connCanBreak, connSendBreak. |
ConnTypeAvailable(type) |
connTypeAvailable: False for CONN_TELNET when Networking is not installed (a secure link over the network needs it too). |
ConnClose h, ConnFree h |
Close (a modem hangs up); close and free the handle. |
ConnAttach(h, ctrl$), ConnDetach h |
Show the connection on a Terminal control, and send what is typed there. The control is found as the program’s code naming it alone finds it: called from a form’s code, that form’s first, else the one loaded form’s that has one (error 1001 when several have). |
ConnSetEcho h, on; ConnSetAnswerback h, text$ |
Local echo (Enter as CR LF); the reply to ENQ. |
ConnCapture(h, path$) |
Append what arrives to path ("" stops). True while capturing. |
ConnZmodemRequest(h) |
True once after a ZMODEM sender started (xferDetectFeed). |
ConnSendFiles(h, proto, files$, escapeCtl, resume) |
Send files (one path per line). An xfer.bas handle, with XFER_FAILED and the reason when it could not start; 0 when the line is not open or busy. |
ConnReceiveFiles(h, proto, target$, exists, escapeCtl) |
Receive (exists: XFER_EXIST_). |
ConnPoll with a Terminal attached does what the C Terminal’s heartbeat did: it reads up to 4 KB, appends them to the capture file, answers each ENQ with the answerback (ENQ itself is not shown), stops at a ZMODEM start frame (the rest of what was read is dropped, and ConnZmodemRequest becomes True), and writes the rest to the Terminal. While a transfer started on the connection runs (or waits for XferAnswer), ConnPoll moves it along instead, nothing reaches the Terminal, and typing is dropped; a transfer on a line that is no longer open is canceled. The receive window of a ZMODEM download on a serial or modem line without flow control is 2 KB, so a slow frame never loses data, unless the program set one with ConnSetXferWindow.
The Terminal binding goes through the form runtime (basFormRtTermBind, basFormRtTermUnbind, and basFormRtTermForget in basrt, looked up when ConnAttach first needs them): the runtime finds the control by the program’s rule for a name alone (basVmFindCtrl) and unbinds a Terminal whose form unloads, and tells the library, so a connection never writes to a freed control. Every handle belongs to the program that made it; whatever it leaves open is closed (a modem hangs up, a capture file is closed, a transfer canceled) when it ends or is ended.
7.9. File Transfer Library
XMODEM, XMODEM-1K, YMODEM, and ZMODEM senders and receivers that work over any byte stream: a serial port, the secure link, and later a network connection. The engines are non-blocking state machines: start a transfer with read and write callbacks, then call xferPoll with the current time in milliseconds as often as you can (every frame). A poll hands queued output to the transport, consumes the input that has arrived, and runs the timeouts. Nothing blocks and nothing touches the screen, so a program stays responsive and draws its own progress.
Loaded as: bin/libs/kpunch/xfer/xfer.lib (needs the serial library only for the BASIC functions)
Header: xfer/xfer.h
See also: C API (Section 7.10); Protocol details (Section 7.11); Using transfers from BASIC (Section 7.12).
7.9.1. Example
static int32_t ioRead(void *ctx, uint8_t *buf, int32_t max) { return connRead((ConnT *)ctx, buf, max); }
static int32_t ioWrite(void *ctx, const uint8_t *d, int32_t len) { return connWrite((ConnT *)ctx, d, len); }
XferT *x = xferCreate();
XferIoT io = { conn, ioRead, ioWrite, NULL };
XferOptionsT opt;
xferOptionsDefaults(&opt);
opt.exists = XferExistRenameE;
xferStartReceive(x, XferZmodemE, &io, &opt, "DOWNLOAD", nowMs());
// every frame:
if (xferPoll(x, nowMs()) != XferRunningE) {
printf("%s\n", xferProgress(x)->message);
}
7.10. File Transfer C API
7.10.1. Types
7.10.2. Enumerations
| Enumeration | Values |
|---|---|
XferProtoE |
XferXmodemE (128-byte blocks, CRC or checksum), XferXmodem1kE (1K blocks), XferYmodemE (batch with names and sizes; block 0 carries every file-information field: size, date 0 = unknown, mode 0 = a DOS file, serial 0, files and bytes left, so receivers such as lrz never read unset fields), XferZmodemE (batch, streaming, CRC-32, resume). |
XferStatusE |
XferIdleE, XferRunningE, XferAskingE (waiting for xferAnswer), XferDoneE, XferFailedE, XferCancelledE. |
XferExistE |
XferExistAskE, XferExistRenameE (store as NAME~1.EXT), XferExistResumeE (ZMODEM: continue a shorter file; otherwise rename), XferExistOverwriteE, XferExistSkipE (ZMODEM skips the file; YMODEM receives and discards it). |
7.10.3. Functions
- XferT *xferCreate(void)
-
Allocate an idle transfer (NULL when out of memory).
- void xferDestroy(x)
-
Close any open file and free the transfer. A transfer belongs to the program that created it: one the program does not destroy is destroyed when the program ends, however it ends (its file is closed; nothing more is sent).
- void xferOptionsDefaults(opt)
-
Ask when a file exists, no window limit, no extra escaping, no resume request.
- bool xferStartSend(x, proto, io, opt, paths, count, now)
-
Send count files (XMODEM sends the first). False, with the reason in the message, when a file cannot be opened or is larger than 2 GB. opt may be NULL.
- bool xferStartReceive(x, proto, io, opt, target, now)
-
XMODEM: target is the file to create. YMODEM and ZMODEM: target is the folder for the files.
- XferStatusE xferPoll(x, now)
-
Move the transfer along. now is a millisecond clock (wrapping is fine).
- void xferCancel(x)
-
Send the cancel sequence to the other side and end with XferCancelledE.
- void xferAnswer(x, action, now)
-
Answer XferAskingE: XferExistResumeE, RenameE, OverwriteE, or SkipE.
- const XferProgressT *xferProgress(x)
-
Progress and outcome.
- bool xferDetectFeed(d, byte)
-
Feed received terminal bytes; true when a ZMODEM sender’s start frame (ZRQINIT) has arrived, so a terminal can start a ZMODEM receive by itself.
- void xferSafeName(name, longNames, out)
-
Reduce a sender’s file name to a safe one: no path, no drive, no DOS device name (CON, PRN, COM1, and so on get a leading _). With longNames (the receiving disk takes long names, platformLongNames) a long name keeping its case, blanks, and dots, where a character a long name cannot hold becomes _ and leading blanks and trailing dots and blanks go (RECEIVED when nothing is left); otherwise an 8.3 name of portable characters in upper case. out holds XFER_NAME_MAX bytes (PLATFORM_LONG_NAME_MAX + 1).
- int32_t xferSplitList(list, paths)
-
Split a list of files to send, one path per line (LF or CR LF, empty lines skipped), in place into paths[XFER_MAX_FILES]; the count. ConnSendFiles and XferSendFiles use it.
- uint16_t xferCrc16(data, len)
-
CRC-16/XMODEM (polynomial 0x1021).
- uint32_t xferCrc32(data, len)
-
CRC-32 (IEEE 802.3), as ZMODEM uses it.
- int32_t xferBasNew(&x)
-
For the BASIC functions of other libraries: a new xfer.bas handle owning a new idle transfer (in x) that belongs to the running program; 0 when no handle is free. The library starts the transfer over its own transport; the program follows it with the Xfer functions (the connection library’s ConnSendFiles and ConnReceiveFiles work this way).
- XferT *xferBasTransfer(handle)
-
The transfer of an xfer.bas handle, or NULL once the program closed it or ended.
7.10.4. Files
Received names are made safe with xferSafeName and stored in the receive folder. An existing file is never replaced silently: XferOptionsT.exists decides, and with XferExistAskE the transfer pauses in XferAskingE (the other side waits) until xferAnswer. A failed or canceled XMODEM or YMODEM download deletes its partial file. A ZMODEM download keeps it, so the same file can be continued later: the receiver continues a shorter file of the same name when the sender asks for it (resume) or when exists is XferExistResumeE.
7.11. Protocol Details
7.11.1. XMODEM and XMODEM-1K
Packets are SOH (128 bytes) or STX (1024 bytes), the block number and its complement, the data, and a CRC-16 or a one-byte checksum. The receiver asks for CRC mode with 'C' every 3 seconds and falls back to checksums (NAK) after three tries, unless the sender has already started. Every packet is answered with ACK or NAK; two CANs cancel. After 10 failed tries of one packet the transfer gives up and cancels the other side. A damaged packet is refused only once the line has been quiet for a second, so the rest of it cannot be mistaken for the next packet. An EOT counts only when the line stays quiet after it (a stray 0x04 inside a damaged packet does not end the file early). A sender whose 1K block fails three times sends that block and the rest of the file in 128-byte blocks. XMODEM pads the last block with 0x1A (SUB); the receiver keeps the padding because the protocol does not carry the file size.
7.11.2. YMODEM
A batch of files, always with CRC and 1K blocks (a tail of at most 128 bytes goes in a 128-byte block). Block 0 carries the file name and size before each file (the long name when it fits in the 128-byte block beside the other fields, else the 8.3 name), and an empty block 0 ends the batch. The receiver refuses the first EOT of each file and accepts the second, and cuts the padding using the size.
7.11.3. ZMODEM
Headers are sent in hex (to start and answer) or binary with CRC-16 or CRC-32; data travels in subpackets with a CRC over the data and the frame end. ZDLE escaping protects ZDLE, DLE, XON, and XOFF (with and without the high bit), and a CR after '@'; with escapeCtl every control character is escaped (the sender announces it with ZSINIT; the receiver asks for it in ZRINIT). Five CANs in a row cancel.
The sender streams: it keeps at most 8 KB unacknowledged, asks for a progress acknowledgment every 4 KB, honors the receiver’s buffer size (a receiver without flow control should set rxWindow to what its hardware buffer holds, so a slow frame never loses data), and builds a subpacket only when the transport has sent nearly everything it was given (XferIoT.pending). On an error the receiver sends ZRPOS with the last good position; the sender goes back there and halves its subpacket size (down to 64 bytes), then doubles it again after eight clean subpackets. A sender that gets no acknowledgment for the window goes back to the last acknowledged position. File names (long names as they are) travel in the ZFILE subpacket with the size and the files and bytes left in the batch, which the receiver shows as batch progress. Commands from the other side (ZCOMMAND) are never run.
Files are at most 2 GB (sizes and positions are 32-bit): a send refuses a larger file, a size offered past 2 GB reads as unknown, and a receive that passes 2 GB stops with "A file larger than 2 GB cannot be transferred". A file already on the disk is never mistaken for a missing one, whatever its size.
Interoperability: the engines are tested against lrz and lsz (lrzsz 0.12.20) in both directions for every protocol, including escaping, resume, and long file names.
7.12. File Transfers from BASIC
Add xfer.bas (and comm.bas, for SerOpen) to a BASIC project to send and receive files over a serial port. Start a transfer, then call XferPoll often, for example from a Timer, until it no longer returns XFER_RUNNING. While it runs, do not read the port yourself and keep it detached from any Terminal control. Received files never replace existing ones: the new file gets a new name.
Transfers over a connection (conn.bas: ConnSendFiles, ConnReceiveFiles) are the same handles, with the options a terminal needs (what to do with an existing file — XFER_EXIST_ASK stops in XFER_ASKING for XferAnswer —, escaping every control character, continuing interrupted files); ConnPoll moves them along. Every handle belongs to the program that made it: whatever a program leaves open is canceled and freed when it ends.
| Function | Description |
|---|---|
XferSendFile(com, proto, path) |
Send one file over COM port com (1-4). Returns a handle, or 0. |
XferSendFiles(com, proto, files, escapeCtl, resumeFiles) |
Send a batch, one path per line (xferSplitList), with the ZMODEM options ConnSendFiles takes. Returns a handle, or 0. |
XferReceive(com, proto, target) |
Receive: XMODEM into the file target; YMODEM and ZMODEM into the folder target; a file already there is renamed. Returns a handle, or 0. |
XferReceiveFiles(com, proto, target, exists, escapeCtl) |
Receive with an XFER_EXIST_ action for files already there (XFER_EXIST_ASK: XFER_ASKING and XferAnswer) and ZMODEM control escaping. |
XferPoll(handle) |
Move the transfer along. Returns XFER_RUNNING, XFER_ASKING, XFER_DONE, XFER_FAILED, or XFER_CANCELLED. |
XferStatus(handle) |
The same, without moving it along (XFER_IDLE for a bad handle). |
XferSending(handle), XferProtocol(handle) |
True for a send; the protocol. |
XferBytes(handle), XferSize(handle) |
Bytes of the current file done, and its size (-1 when unknown). |
XferFile$(handle) |
The file being transferred, as stored on this computer. |
XferFileIndex(handle), XferFileCount(handle) |
Which file of the batch (from 0), and how many (-1 while unknown). |
XferBatchBytes(handle), XferBatchSize(handle) |
Bytes of the whole batch done, and its size (-1 when unknown). |
XferResumedAt(handle), XferErrors(handle) |
Where the current file continued from; retries so far. |
XferAskSize(handle), XferCanResume(handle) |
XFER_ASKING: the size of the file already there; True when XFER_EXIST_RESUME can continue it. |
XferAskRemoteSize(handle) |
XFER_ASKING: the size the sender offers (XferProgressT.askRemoteSize; -1 when unknown). |
XferAnswer handle, action |
Answer XFER_ASKING with XFER_EXIST_RENAME, _RESUME, _OVERWRITE, or _SKIP. |
XferMessage$(handle) |
How the transfer ended, or why it failed. |
XferCancel handle |
Stop a running transfer (the other side is told). |
XferClose handle |
Free the handle. |
XferCrc16(bytes), XferCrc32(bytes) |
xferCrc16 / xferCrc32 of a BINARY STRING (every byte value counts); the CRC-32 as a LONG (negative when its top bit is set). |
XferSafeName$(fileName, folder) |
xferSafeName: the name a receive into folder stores a sender’s file name as (a long name where folder’s disk takes them, else 8.3). |
XFER_WINDOW_MAX (xfer.bas) is the largest ZMODEM receive window conn.bas’s ConnSetXferWindow takes.
Protocols: XFER_XMODEM, XFER_XMODEM1K, XFER_YMODEM, XFER_ZMODEM. At most eight transfers run at once (XFER_MAX_FILES files in one batch).
Dim h As Long
If SerOpen(1, 115200, 8, "N", 1, SER_HANDSHAKE_RTSCTS) Then
h = XferReceive(1, XFER_ZMODEM, "C:\DOWNLOAD")
End If
Sub Timer1_Timer ()
If h <> 0 Then
If XferPoll(h) <> XFER_RUNNING Then
Print XferFile$(h); ": "; XferMessage$(h)
XferClose h
h = 0
End If
End If
End Sub
Chapter 8. Networking and the Web
8.1. Networking Library
TCP/IP for DVX programs with the standard BSD socket API: a C programmer who knows sockets writes DVX network code the usual way. IPv4 today; the types and constants for IPv6 (AF_INET6, sockaddr_in6, sockaddr_storage) are defined so code can be written for both.
Loaded as: bin/libs/kpunch/dvxnet/dvxnet.lib (needs the shell, the task switcher, and the core library)
Headers: dvxnet/dvxNet.h (settings and status), and the standard headers in dvxnet/include: sys/socket.h, netinet/in.h, netinet/tcp.h, arpa/inet.h, netdb.h, sys/select.h, poll.h, sys/ioctl.h, and errno.h (the C library’s plus the network codes). Put the include directory on the compiler’s include path ahead of the C library’s. In the SDK they are in include/net, and a project Makefile that sets NET = 1 gets them (see SDK Quick Start).
See also: The socket API (Section 8.2); Waiting, polling, and cooperative multitasking (Section 8.3); Settings and status (dvxNet.h) (Section 8.4); How it works (Section 8.5); Networking from BASIC (Section 8.6).
8.1.1. Hardware
The network card is reached through a DOS packet driver (FTP Software’s specification) loaded before DVX, for example NE2000.COM 0x60 3 0x300 for an NE2000 at I/O 300h, IRQ 3. dvxnet finds it on software interrupts 60h to 80h (or the one set in DVX.INI) and registers for IPv4 and ARP frames. Any card with a packet driver works, and so do SLIP/PPP links through the usual packet-driver shims.
Without a packet driver the library still runs: 127.0.0.1 works (programs can talk to each other), and connections elsewhere fail with ENETUNREACH.
8.1.2. Example
#include <arpa/inet.h>
#include <netdb.h>
#include <sys/socket.h>
#include <unistd.h>
struct addrinfo hints = { 0 };
struct addrinfo *res;
int fd;
hints.ai_family = AF_INET;
hints.ai_socktype = SOCK_STREAM;
if (getaddrinfo("bbs.example.org", "telnet", &hints, &res) == 0) {
fd = socket(res->ai_family, res->ai_socktype, res->ai_protocol);
if (connect(fd, res->ai_addr, res->ai_addrlen) == 0) {
send(fd, "hello\r\n", 7, 0);
}
close(fd);
freeaddrinfo(res);
}
8.1.3. License of the TCP/IP stack
The protocol engine is lwIP 2.2.1, unmodified, under the 3-clause BSD license:
Copyright (c) 2001, 2002 Swedish Institute of Computer Science. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
8.2. The Socket API
Standard names, arguments, and meanings. A socket is an ordinary file descriptor: read(), write(), and close() work on it, as do fcntl(F_GETFL/F_SETFL, O_NONBLOCK), ioctl(FIONBIO, FIONREAD), select(), and poll().
| Function | Notes |
|---|---|
socket(AF_INET, SOCK_STREAM or SOCK_DGRAM, 0) |
Starts the network with the saved settings the first time. EAFNOSUPPORT for other families (AF_INET6 included, for now). |
bind, listen, accept |
listen’s backlog is capped at SOMAXCONN (16). An unbound socket listens on a free port. Accepted sockets are blocking (O_NONBLOCK is not inherited, as on Linux). |
connect |
Blocking: waits for the connection (SO_SNDTIMEO limits the wait: EINPROGRESS). Non-blocking: EINPROGRESS, then poll/select for writable and read SO_ERROR (ECONNREFUSED, ETIMEDOUT, ...). UDP: sets the default peer; AF_UNSPEC removes it. |
send, recv, sendto, recvfrom |
Flags MSG_PEEK, MSG_DONTWAIT, MSG_WAITALL (TCP), MSG_NOSIGNAL (accepted; there are no signals). MSG_OOB: EOPNOTSUPP. A blocking TCP send returns when everything is queued. recv returns 0 at the end of the stream. UDP messages longer than the buffer are cut; up to 8192 bytes are sent. |
shutdown(SHUT_RD, SHUT_WR, SHUT_RDWR) |
As usual; the other side reads the end of the stream after SHUT_WR. |
close |
An orderly close in the background; unread received data makes it a reset (as on BSD). |
setsockopt / getsockopt |
SO_REUSEADDR, SO_KEEPALIVE, SO_BROADCAST, SO_RCVTIMEO, SO_SNDTIMEO, TCP_NODELAY; SO_ERROR, SO_TYPE, SO_ACCEPTCONN, SO_RCVBUF, SO_SNDBUF (read only: 5840 for TCP, 8192 for UDP); SO_LINGER is accepted and reads as off. Others: ENOPROTOOPT. |
getsockname, getpeername |
IPv4 addresses. |
select, poll |
Sockets report real readiness (POLLIN, POLLOUT, POLLERR, POLLHUP); other descriptors always count as ready. |
getaddrinfo, freeaddrinfo, gai_strerror |
AF_INET or AF_UNSPEC; names, dotted addresses, "localhost"; service numbers or the common names (telnet, http, ftp, smtp, domain, echo, ...). AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV. |
gethostbyname, gethostbyaddr, h_errno |
gethostbyaddr does no reverse lookup: the name is the dotted address. |
getnameinfo |
Numeric host and service; NI_NAMEREQD gives EAI_NONAME. |
gethostname |
The computer name from the network settings. |
inet_pton, inet_ntop |
AF_INET (AF_INET6: EAFNOSUPPORT). |
inet_addr, inet_aton, inet_ntoa |
BSD forms (a.b.c.d, a.b.c, a.b, a; decimal, octal, or hex). |
htonl, htons, ntohl, ntohs |
Inline in <netinet/in.h>; also real functions for code built without optimization. |
8.2.1. Error Codes
errno.h adds the network codes: EWOULDBLOCK (the same as EAGAIN), EINPROGRESS, EALREADY, ENOTSOCK, EDESTADDRREQ, EMSGSIZE, EPROTOTYPE, ENOPROTOOPT, EPROTONOSUPPORT, ESOCKTNOSUPPORT, EOPNOTSUPP (ENOTSUP), EPFNOSUPPORT, EAFNOSUPPORT, EADDRINUSE, EADDRNOTAVAIL, ENETDOWN, ENETUNREACH, ENETRESET, ECONNABORTED, ECONNRESET, ENOBUFS, EISCONN, ENOTCONN, ESHUTDOWN, ETIMEDOUT, ECONNREFUSED, EHOSTDOWN, EHOSTUNREACH. The C library’s strerror() does not know them; netErrorText(errno) gives plain words for them.
8.3. Waiting and Multitasking
8.3.1. Waiting, Polling, and Cooperative Multitasking
DVX runs programs cooperatively, so a call that has to wait never stops the system: blocking connect, accept, recv, send (with a full buffer), select, poll, and name lookups wait by running the network and then letting the other tasks run (tsYield), again and again, until they can return. Other programs, and other connections, keep working meanwhile.
The network also runs from the shell’s idle time, so connections progress (and data arrives) while a program is busy with other things; every socket call runs it too. A program that polls non-blocking sockets in its own loop needs nothing else.
Right after the network starts, DHCP needs a moment to get an address. Blocking connect and sendto calls, and name lookups, wait for it (up to 20 seconds) instead of failing, so a program started together with DVX can connect at once. A non-blocking socket does not wait.
A program that must not wait at all, not even inside one call, looks a name up with netLookupStart and netLookupPoll (dvxNet.h) instead of getaddrinfo: each poll only looks, and the lookup waits for DHCP’s first address too, so a non-blocking connect to the address it finds goes at once. DVX’s own web requests (http) and Terminal connect this way.
NetLookupT lk;
uint32_t addr;
int32_t rc;
netLookupStart(&lk, "bbs.example.org");
// Each frame, or from a timer:
rc = netLookupPoll(&lk, &addr);
if (rc == 0) {
// addr (network order): connect a non-blocking socket to it
} else if (rc != NET_LOOKUP_BUSY) {
// gai_strerror(rc) says why
}
8.4. Network Settings and Status
8.4.1. Settings and Status (dvxNet.h)
The settings live in DVX.INI, section [network]: dhcp (true/false), address, netmask, gateway, dns1, dns2, hostname, and vector (auto or 0x60-0x80). The Control Panel’s Network page edits them.
| Function | Description |
|---|---|
int32_t netStart(void) |
Start with the saved settings unless running: NET_OK, NET_ERR_NO_DRIVER (the stack runs anyway, for 127.0.0.1), NET_ERR_CONFIG, or NET_ERR_NO_MEMORY. Socket calls do this themselves. |
void netStop(void) |
Stop (the packet driver is released). Every socket’s connection ends, but its descriptor stays its program’s until the program closes it (or ends): every other call on it fails with ENETDOWN, and the number is never handed to a file or socket opened meanwhile. DVX does this while a DOS program runs, too. |
int32_t netRestart(void) |
Stop, then start with the saved settings (after they changed). |
void netPoll(void) |
Take received frames, run the timers, send. Called from the shell’s idle time and by every socket call. |
void netLookupStart(NetLookupT *lk, const char *name) |
Start looking a name (or a dotted address) up without waiting. |
int32_t netLookupPoll(NetLookupT *lk, uint32_t *addr) |
NET_LOOKUP_BUSY, 0 with the address (network order), or an EAI_* code; never waits. |
void netLookupCancel(NetLookupT *lk) |
Give up a lookup that has not ended. |
void netGetStatus(NetStatusT *status) |
State (NetStoppedE, NetNoDriverE, NetConfiguringE, NetUpE), plain-words message, addresses, name servers, host name, packet driver name, interrupt and hardware address, packet and byte counters, frames lost while DVX was busy, open sockets. |
const char *netStateText(int32_t state) |
Plain words for a state. |
const char *netErrorText(int32_t err) |
Plain words for an errno value, network codes included, or for the EAI_* code of a failed lookup. |
void netConfigDefaults(NetConfigT *cfg) |
DHCP, find the driver, host name DVX. |
void netConfigLoad(NetConfigT *cfg) |
Read DVX.INI [network]. |
void netConfigFromPrefs(h, cfg) |
Read [network] from an open preferences handle. |
void netConfigToPrefs(h, cfg) |
Store cfg as [network] in an open handle (the caller saves). |
bool netConfigEqual(a, b) |
True when two configurations are the same settings (the Control Panel restarts the network only when they differ). |
const char *netConfigProblem(cfg) |
NULL when usable, else why not in plain words (bad address or mask, name, interrupt). |
bool netParseAddress(text, &addr) |
Strict dotted IPv4 (four decimal parts 0-255) to network byte order. |
void netCloseAppSockets(int32_t appId) |
Close every socket of that app and free the net.bas settings handles it left (the shell calls this when an app ends). |
Name servers set in the settings are used even with DHCP; left empty, the DHCP server’s are used.
8.5. How the Networking Library Works
8.5.1. How It Works
lwIP runs without threads (NO_SYS), configured only by port/lwipopts.h: TCP MSS 1460 with a 4-segment window, 16 TCP connections, 24 KB of stack memory for data being sent and 20 receive buffers, DHCP, DNS (2 servers), ARP, ICMP (ping answers), IP fragments, loopback. Nothing runs lwIP at interrupt time.
The receive ring holds 16 frames. A burst larger than that while DVX is busy loses frames (counted as "lost" in the status); TCP sends them again.
On the host the same sources are built into the "net" test suite: a fake packet driver passes frames through the real ring to a second copy of the stack in another process, which plays DHCP, DNS, and echo server.
8.6. Networking from BASIC
net.bas declares simple functions over the socket API (netBas.c): HostLookup$, HostLookupStart / Poll / Result$ / Close, HostName$, NetAddress$, NetError$, TcpConnect, TcpConnectStart / Poll, TcpListen, TcpAccept, TcpSend, TcpSendSome, TcpPending, TcpRecv$, TcpPeek$ (recv with MSG_PEEK), TcpConnected, TcpShutdown, TcpPeer$, TcpLocalPort, TcpSetNoDelay, TcpSetKeepAlive, TcpClose, UdpOpen, UdpSend, UdpRecv$, UdpFrom$, UdpClose. A handle is the socket’s descriptor + 1, so 0 means failure. Only TcpConnect (up to 20 seconds), HostLookup$, and TcpSend wait; everything else returns at once, so a program polls from a Timer. The other socket options need no binding: TcpListen sets SO_REUSEADDR and UdpOpen SO_BROADCAST, the stack takes SO_LINGER and the buffer sizes without effect (closing finishes in the background; the buffers are fixed), and no BASIC call waits on a receive, so SO_RCVTIMEO does nothing for it. TcpSend, TcpRecv$, UdpSend, and UdpRecv$ pass their data as BINARY STRING (pointer and length), so every byte value goes through. See the BASIC language reference, Include Libraries.
| BASIC | C it calls |
|---|---|
HostName$(address) |
getnameinfo: the address itself, as this stack does not look names of addresses up; "" when it is not an address. |
TcpShutdown(handle) |
shutdown(SHUT_WR); True when done. |
TcpPeer$(handle) |
getpeername, as "address:port" ("" when not connected). |
TcpLocalPort(handle) |
getsockname: the local port (-1 for a bad handle). |
TcpSetNoDelay(handle, enable) |
setsockopt(IPPROTO_TCP, TCP_NODELAY); True when done. |
TcpSetKeepAlive(handle, enable) |
setsockopt(SOL_SOCKET, SO_KEEPALIVE); True when done. |
NetStop |
netStop (every program’s connections end; each program still closes its handles). |
The network settings and status (what the Control Panel’s Network page shows) are reachable too, over the functions of dvxNet.h:
| BASIC | C it calls |
|---|---|
NetConfigLoad(prefs) |
netConfigFromPrefs on a prefs.bas handle (prefsBasHandle; 0 = the defaults) into a new settings handle, which also keeps the settings as read. |
NetConfigGet$ / NetConfigSet |
One field by name: dhcp, vector, address, netmask, gateway, dns1, dns2, hostname (text; yes / no as "-1" / "0"). |
NetConfigProblem$(cfg) |
netConfigProblem ("" when usable). |
NetConfigChanged(cfg) |
netConfigEqual against the settings as read. |
NetConfigStore(cfg, prefs) |
netConfigToPrefs into a prefs.bas handle. |
NetConfigFree(cfg) |
Free the handle. |
NetVectorCount / NetVector(i) |
The packet driver interrupt choices: 0 (find it), then NET_VECTOR_FIRST..NET_VECTOR_LAST. |
NetRestart() |
netRestart; True for NET_OK. |
netBasStreamRead / netBasStreamWrite |
A net.bas TCP handle as a byte stream that never waits, for another library’s BASIC functions (comm.bas’s CommOpenTcp runs the secure packet link over it): bytes read or taken (0 = none now), negative once the connection has closed or failed. |
NetState() |
netGetStatus’s state (NetStateE; BASIC’s NET_STATE_STOPPED, _NO_DRIVER, _CONFIGURING, _UP). |
NetStatus$(field) |
netGetStatus, one field as text: message, up, link, dhcp, address, netmask, gateway, dns1, dns2, hostname, driver, mac, vector, sockets, rxpackets, rxbytes, rxdropped, txpackets, txbytes. |
Settings handles (1 to 16, 0 = none) belong to the program that made them; netCloseAppSockets frees what a program left.
8.7. HTTP Library
An HTTP/1.1 client: GET, POST, and other requests to a web server over the network library’s sockets, run a step at a time like the transfer and package jobs, so a program draws its progress and stays responsive. Software talks to the package server with it.
Header: http/http.h
Loaded as: bin/libs/kpunch/http/http.lib (it needs the network library, dvxnet)
BASIC: http.bas (HttpOpen, HttpStart, HttpRunFor, HttpStatus, HttpBody$, ...).
8.7.1. A Request
HttpT *h = httpCreate("GET", "http://example.com/v1/catalogue");
if (h && httpStart(h, nowMs)) {
while (httpPoll(h, nowMs) == HttpBusyE) {
// draw progress (httpProgress), yield to other programs
}
}
// HttpDoneE: httpStatus(h) is 200, 404, ...; httpBody(h, &len) the reply
// HttpFailedE: httpMessage(h) says why
httpFree(h);
nowMs is a millisecond clock (PLATFORM_TICKS_TO_MS(platformClock())); it may wrap. Each httpPoll does one bounded piece of work: start connecting, send, or read up to 4 KB; on DOS it also lets the network stack run. Every request says Connection: close.
| Function | Description |
|---|---|
httpCreate(method, url) |
A request; NULL when out of memory. |
httpHeaderAdd(h, name, value) |
A header to send (before starting). |
httpBodySet(h, data, len, contentType) |
A body to send (copied); Content-Length is sent for it, and for any POST or PUT. |
httpSaveTo(h, path, resume) |
The body to a file instead of memory; with resume, a part already there is kept and the rest asked for (a Range request). |
httpTimeoutSet(h, ms) |
Give up after ms without progress (HTTP_TIMEOUT_DEFAULT_MS, 30 seconds, to start with). |
httpStart(h, nowMs) |
False (httpMessage) for an address that is not http://. |
httpPoll(h, nowMs) |
HttpBusyE, HttpDoneE, or HttpFailedE. |
httpProgress(h, &done, &total) |
Bytes of the body so far (counting a resumed file’s first part), and the whole, HTTP_SIZE_UNKNOWN until the server says. |
httpStatus(h), httpHeader(h, name) |
The reply’s status and its headers (any case). |
httpBody(h, &len) |
The body in memory, NUL-terminated; len its length. "" and 0 when it went to a file, before the reply is done (HttpDoneE), or after a failure. |
httpUrl(h) |
Where the reply came from, after redirects. |
httpUrlParse(url, &parts, err, size) |
Split an address into host, port, and path. |
8.7.2. What Comes Back
Any status is an answer (HttpDoneE): the program decides what 404 or 500 means. HttpFailedE is for no answer: a bad address, a name that cannot be found, no connection, silence past the timeout, a reply that is not HTTP, or one cut short. Bodies may be sized (Content-Length), chunked, or end when the server closes; they go to memory up to HTTP_MEMORY_MAX (1 MB), past which the request fails — save big ones to a file. Redirects (301, 302, 303, 307, 308) are followed, HTTP_REDIRECTS_MAX (5) at most; after a 303, or a 301 or 302 of a POST, the request becomes a GET without its body. A redirect to another computer or port is sent without the Authorization, Proxy-Authorization, and Cookie headers, and fails when the request would carry its body there. 1xx replies are passed over for the answer after them. A length or chunk size that is not a plain number fails the request before any file is touched. A resumed file is added to only when the reply’s Content-Range is the rest asked for; otherwise the whole file is fetched again. A resume cannot tell that the file on the server changed: add an If-Range header, or check the whole file afterwards. Nothing is encrypted: anyone on the network between the two computers can read what is sent.
Saving to a file: only a 2xx body is written to it. A resumed download that the server answers with 206 is appended to the part there; one it answers with 200 (it will not resume) starts the file again; 416 (asked for past the end: the file was already whole) leaves it as it is. Any other status’s body — an error page — goes to memory and the file stays as it was, so a download can be resumed later. Check the file afterwards (its size and SHA-256, as the package library does) before using it.
Only plain http:// works: there is no encryption, so send nothing secret, and check what comes back by its signature or hash.
8.8. JSON Library
Reads JSON text — a web service’s reply, a settings file — into a tree, finds values in it by path, and quotes text for JSON of your own. The package server’s replies are read with it.
Header: json/json.h
Loaded as: bin/libs/kpunch/json/json.lib
BASIC: json.bas (JsonParse, JsonText$, JsonNumber, JsonCount, JsonKey$, JsonQuote$, ...).
8.8.1. Reading
jsonParse(text, len, err, errSize) reads a document and returns it (NULL when it is not JSON: err says why and on which line; jsonFree frees it). Its nodes are numbered from 0, the root. jsonFind(doc, node, path) finds a node from another: a path is member names and [index]es, such as packages[3].version, [0], or "" (the node itself); members match by exact name, the first when a name repeats. JSON_NO_NODE stands for a node that is not there, and every function accepts it.
| Function | Description |
|---|---|
jsonType(doc, node) |
JsonNullE, JsonBoolE, JsonNumberE, JsonStringE, JsonArrayE, JsonObjectE; JsonNoneE for no node. |
jsonText(doc, node) |
A string’s text ("" for anything else). |
jsonNumber(doc, node) |
A number’s value, a double (0 for anything else). |
jsonBool(doc, node) |
True only for true. |
jsonCount(doc, node) |
An array’s items or an object’s members (0 for anything else). |
jsonChild(doc, node, index) |
Item or member index, in order. |
jsonKey(doc, node) |
A member’s name ("" for anything else). |
Strings are held decoded into DVX text (code page 437): the escapes \n, \t, \", \\, \/, \b, \f, \r, and \u (surrogate pairs included) and UTF-8 sequences become their characters, with '?' for a character DVX does not have; other bytes pass through. Arrays and objects nest JSON_DEPTH_MAX (64) deep at most.
char err[JSON_ERR_MAX];
JsonDocT *doc = jsonParse(text, len, err, sizeof(err));
for (int32_t i = 0; doc && i < jsonCount(doc, jsonFind(doc, 0, "packages")); i++) {
int32_t pkg = jsonChild(doc, jsonFind(doc, 0, "packages"), i);
printf("%s %s\n", jsonText(doc, jsonFind(doc, pkg, "id")), jsonText(doc, jsonFind(doc, pkg, "version")));
}
jsonFree(doc);
8.8.2. Writing
jsonQuote(text, out, outSize) writes text as a JSON string — quotes, escapes, control characters and characters from 128 on as \u escapes of their Unicode code points, so the result is plain ASCII — and returns the length it needs (as snprintf does), so a NULL out with size 0 measures it.
Chapter 9. Packages
9.1. Package Library
Add-on packages: the .DPK file format, manifests, Ed25519 keys and signatures, the packages installed in a DVX folder, the keys DVX trusts, planning what an install or removal takes, and installing and removing a package a step at a time. Software, Package Builder, the IDE’s File > Make Package, DVXPKG.EXE, the build machine’s dvxpkg, and Setup all use it.
Header: pkg/pkg.h (it includes the others below)
Loaded as: bin/libs/kpunch/pkg/pkg.lib, and bin/libs/kpunch/pkg/writer/writer.drv when a package is made (below)
BASIC: pkg.bas (sessions, offers, plans, install and remove jobs, building, signing, and keys; PkgFileOwner$ is pkgDbOwner).
9.1.1. A Package
A package is NAME.DPK: a ZIP read front to back, whose first entry is PACKAGE.INI, the manifest; then PACKAGE.SIG when the publisher signed it; then the files, named relative to the DVX folder with / between parts.
[package]
format = 1
id = acme.chess ; vendor.name, each 1..8 of a-z 0-9 _
name = Chess
version = 1.2.0
kind = app ; one of the kinds in the table below
summary = Play chess against the computer.
publisher = Acme Games ; also author, licence, homepage
dvx = 1.0.0 ; the oldest DVX it runs on
abi = 10 ; programs, libraries, widgets: DVX_ABI_VERSION
[depends]
acme.cards = 1.0.0 ; id = the oldest version that will do
[files]
APPS/ACME/CHESS/CHESS.APP = 61234 <SHA-256, 64 hex digits>
Every file is listed with its size and SHA-256 and every listed file is in the package, so the one signature over the manifest’s bytes covers everything. Each kind keeps to its own folders (pkgKindFolder gives the folder for an id; pkgFileAllowed checks a name):
| Kind | Folder |
|---|---|
app, help |
APPS/VENDOR/NAME (help may also go beside a library or widget of its name) |
library, widget |
LIBS/VENDOR/NAME, WIDGETS/VENDOR/NAME |
font, bank |
SHARED/FONTS/VENDOR, SHARED/BANKS/VENDOR |
theme, wallpaper |
SHARED/THEMES/VENDOR, SHARED/WPAPER/VENDOR |
sound |
SHARED/SOUNDS/VENDOR |
saver |
SHARED/SAVERS/VENDOR (a screen saver: a program, so it needs abi) |
bundle |
no files: a set of packages, its dependencies |
system |
DVX itself (kpunch.dvx): anywhere but the user folder |
Every kind but bundle may also add files to SYSTEM (a DOS program run at the prompt, say), but not to SYSTEM/KEYS (the keys DVX trusts) or SYSTEM/PACKAGES (the package records, PKG_DB_DIR), which only DVX itself writes. A file there that another package has is refused when the package is installed, as anywhere (pkgPlanInstall), so an add-on still cannot replace one of DVX’s.
9.1.2. Manifests (pkgManifest.h)
| Function | Description |
|---|---|
pkgManifestParse(text, len, &m, err, size) |
A manifest’s text; then pkgManifestCheck before trusting it. |
pkgManifestCheck(&m, err, size) |
The id, the kind’s rules, every file’s name and folder, nothing listed twice, no dependency on itself. |
pkgManifestFormat(&m, &len) |
The text (CR LF lines), malloc’d. |
pkgTemplateRead(path, &m, err, size) |
A template: a manifest whose format and [files] a build writes, so it may leave them out; other sections are ignored. |
pkgKindFolder(kind, id, out, size) |
The folder a package id of kind keeps its files in (APPS/ACME/CHESS); false for bundle and system. |
pkgKindIsCode(kind) |
Programs, libraries, and widgets: their manifests need an abi. |
pkgIdValid(id), pkgIdSplit(id, vendor, name) |
Package ids. |
pkgVersionParse, pkgVersionFormat, pkgVersionCompare |
major.minor.patch versions. |
9.1.3. Keys and Signatures (pkgSign.h)
A key pair is NAME.KEY (public: id, name, public key) and NAME.SEC (secret: id, name, seed), small INI files. A key’s id is the first 8 bytes of its public key’s SHA-256, so a signature names its key. The repository key that signs DVX’s own packages is kept offline; the server never holds a secret key.
| Function | Description |
|---|---|
pkgRandomBytes(buf, len) |
Random bytes for a seed: the security library’s generator topped up with fresh hardware entropy. |
pkgKeyWrite(seed, name, base, &key, err, size) |
Make a pair from seed and write BASE.KEY and BASE.SEC. |
pkgKeyRead, pkgSecretRead, pkgSigRead |
Read a key, secret key, or signature file. |
pkgSign(&secret, msg, len, &sig) |
Sign bytes (a manifest’s). |
pkgSigCheck(&sig, &key, msg, len) |
True when key made sig over the bytes. |
pkgSecretWipe(&secret) |
Clear a secret key from memory once it has signed. |
9.1.4. Building and Reading Packages (pkgDpk.h)
| Function | Description |
|---|---|
pkgDpkBuild(&templ, folder, out, secret, err, size) |
Build from a template and every file under folder, named relative to it (a folder laid out like the DVX folder); secret NULL: unsigned. A program, library, or widget without abi gets DVX_ABI_VERSION. |
pkgDpkBuildFiles(&templ, files, count, out, secret, err, size) |
The same from a list of PkgDpkFileT (the name in the package, the file it comes from). |
pkgDpkFolderFiles(folder, prefix, &files) |
Every file under folder as that list, named prefix/...; pkgDpkFilesFree frees it. |
pkgDpkReadInfo(path, &info, err, size) |
The manifest and PACKAGE.SIG, checked; pkgDpkInfoFree. |
pkgDpkCheckFiles(path, &info, err, size) |
Every file’s size and SHA-256 against the manifest, all at once. |
pkgDpkCheckStart(path, &info, err, size) |
The same as a job: pkgDpkJobStep a piece at a time, pkgDpkJobPercent by bytes read (BASIC’s PkgVerifyStart). |
pkgDpkSign(path, &secret, detached, err, size) |
Sign into the package, or beside it as NAME.SIG. |
pkgDpkSigner(&info, detached, keys, count) |
Which of keys made the signature (or the detached one). |
PkgManifestT templ;
PkgSecretT secret;
char err[PKG_ERR_MAX];
bool ok;
ok = pkgTemplateRead("CHESS.INI", &templ, err, sizeof(err)) && pkgSecretRead("ACME.SEC", &secret, err, sizeof(err));
ok = ok && pkgDpkBuild(&templ, "STAGE", "CHESS.DPK", &secret, err, sizeof(err));
pkgSecretWipe(&secret);
pkgManifestFree(&templ);
9.1.5. Installed Packages and Trust (pkgDb.h, pkgTrust.h)
Each installed package has a record, SYSTEM/PACKAGES/VENDOR/NAME.INI: its manifest as installed, whether it was chosen or only needed by another, and how it was signed (PkgInstalledT’s howSigned, a PkgSignedE): by a key DVX trusted (signer = its id), by a key DVX did not trust (signed = untrusted: not checked), by a key DVX trusted whose signature did not fit (signed = unfit), not at all, or (setup = yes) put there by Setup with DVX, from DVX’s own disks, when no signature was checked. pkgOfferSigned says the same of an offer. pkgDbLoad reads them all; pkgDbFind, pkgDbOwner (who has a file), pkgDbPut, and pkgDbDrop keep them. Setup writes the records of DVX’s own packages (kpunch.dvx and the rest it installs) from its package, with every file.
pkgKeyringLoad reads the keys DVX trusts: SYSTEM/KEYS (DVX’s own) and the user’s KEYS folder (publishers the user chose); pkgKeyringAdd trusts another, and pkgKeyringRemove(ring, userDir, idText, err, size) stops trusting one of the user’s (its files in KEYS are deleted; a SYSTEM key stays). pkgTrustOf says how far a package is trusted (PkgTrustSystemE, PkgTrustUserE, PkgTrustNoneE), pkgKeyringFind which trusted key has an id, and pkgKeyringIsSystem whether a key id is one of SYSTEM’s. The rules the planner keeps (pkgOfferAllowed, which pkgOpInstall keeps again): kpunch.* packages must be signed by a SYSTEM key; a package from the package server (an offer read with pkgOfferScanStart’s fromServer) must be signed by a SYSTEM key too, and one that is not signed, is signed by another key, or whose signature by a SYSTEM key does not fit is refused, saying which; an upgrade of a version that was installed with a trusted key’s signature (howSigned PkgSignedTrustedE) must be signed by that same key (or a SYSTEM key), while a version installed unsigned, or signed by a key DVX did not trust, may be replaced by any package the other rules let in; a package from a file that no trusted key signed is installed only after a warning.
9.1.6. ZIP Files (pkgZip.h)
The reader goes front to back through a ZIP from a read callback (pkgZipFileRead over a FILE *), never seeking; each entry’s data goes, inflated, to a write callback in steps, and its size and CRC-32 are checked at its end. pkgZipProblemText says why a step failed, as the end of a sentence. The writer makes a ZIP the reader takes: pkgZipCreate, pkgZipBeginFile or pkgZipBeginMem, pkgZipStep until each is in, pkgZipFinish (pkgZipAbort removes a half-made one). pkgZipDosTime and pkgZipDosStamp turn ZIP dates into times and back.
A plain ZIP job (PkgZipJobT, pkgZipJob.c) does a whole archive a step at a time, for a program that keeps drawing:
| Function | Description |
|---|---|
pkgZipJobRead(path, dir, err, size) |
Read a ZIP to its end, every entry checked; with dir, unpack each under it (folders made, files dated as in the ZIP; a name with a drive, a leading '/', or ".." fails it). |
pkgZipJobCreate(path, names, sources, count, err, size) |
Make a ZIP of count files: names[i] in the ZIP from the file sources[i]. |
pkgZipJobStep(job, maxWork) |
PkgZipJobMoreE, PkgZipJobDoneE, or PkgZipJobFailedE (pkgZipJobMessage says why). |
pkgZipJobEntries(job, &count) |
The entries read or written so far. |
pkgZipJobCurrent, pkgZipJobPercent |
The entry it is on; how far it is (bytes of the ZIP read, or of the files added). |
pkgZipJobFree(job) |
Stop and free it: a ZIP being made, or a file being unpacked, is removed. |
pkgHexEncode and pkgHexDecode (pkgFormat.h) turn bytes into hex digits and back, as manifests, keys, and the package server write SHA-256s and key ids.
9.1.7. The Package Writer Module
Writing ZIPs (miniz’s deflate) and making keys and signatures (Ed25519 signing) are used only when a package is made, so in DVX they are a module of their own, writer.drv in LIBS\KPUNCH\PKG\WRITER, which pkg.lib loads the first time a program makes a ZIP, a key, or a signature (pkgZipCreate, pkgKeyMake, or pkgSign, directly or through pkgKeyWrite, the .DPK and ZIP jobs, and BASIC’s PkgBuildStart, PkgSignStart, PkgKeygen, PkgSignData, and PkgZipCreateStart); it stays until pkg.lib is unloaded. Nothing changes for a program: the calls keep their names (pkgWriterMod.c passes them on; pkgWriter.h has the module’s descriptor). Without the module (a damaged installation) pkgZipCreate gives NULL and a key or signature made is all zeros, which nothing accepts; DVX.LOG says the writer is missing. Reading, checking, and installing packages never load it. Programs that link the library in whole (DVXPKG.EXE, the build machine’s dvxpkg, the tests) compile pkgZipWrite.c and pkgSignMake.c instead of the module.
9.1.8. Planning (pkgPlan.h)
An offer (PkgOfferT) is a package that can be installed: pkgOfferRead reads one file, pkgOffersFor reads a file and every package in its folder (what it may need), pkgOffersInFolder a whole folder; pkgOfferScanStart reads them a step at a time, and with fromServer marks each as from the package server (what a fetch put in its folder). pkgPlanInstall(db, offers, count, wanted, wantedCount, &plan) plans installing the offers wanted with everything they need, in the order they go in, each checked (the DVX and ABI it needs, files another package has, a newer version installed, the signing rules); plan.err says why when it fails, plan.bytes is what it unpacks, plan.room the most free disk space installing needs at once (each package’s files are all unpacked before the old version’s go), and plan.stale lists the add-ons an update of DVX itself would leave unable to load. pkgPlanDependents lists the installed packages that need some going (they go too); pkgPlanOrphans those only they needed.
9.1.9. Installing and Removing (pkgOp.h)
pkgOpInstall(db, offer, explicitly) (or pkgOpInstallFile(db, path, ring, explicitly) for a file read now) and pkgOpRemove(db, id, removeChanged) make an operation; pkgOpStep runs it a bounded piece at a time (PKG_OP_STEP bytes) until PkgOpDoneE or PkgOpFailedE (pkgOpMessage says why), with pkgOpProgress for a progress bar (64-bit byte counts: a package’s files are each less than 4 GB, but not all together). Installing unpacks every file into a new scratch file beside where it goes (never a file that is already there, nor a name the package installs), checking each against the manifest, and only then swaps them all in, setting the files they replace aside; then it writes the record, and only once the record is written do the files set aside go (should a swap or the record fail, every file is put back as it was). Last it removes what an older version had that this one does not. What the swap will do is written first to SYSTEM\PACKAGES\PKGOP.JNL, so an install that a crash interrupts is undone, or finished when its record was written, the next time pkgDbLoad reads the records (pkgOpRecover); one install swaps at a time, and another that reaches its swap meanwhile fails and says so. Removing deletes the files unchanged since they were installed (all of them with removeChanged), the folders that leaves empty, and last the record, so a removal that fails can be asked for again; pkgOpKept lists the changed files a removal or an upgrade left, and pkgOpUndeleted the files it could not delete (or read to check), named as in the manifest (pkgNameShown gives a name with the platform’s separator, as people are shown it). pkgOpStop or pkgOpFree before the swap cancels an install (pkgOpMessage then says nothing); after it, the operation is finished first.
9.1.10. The Package Tool
DVXPKG.EXE (DVX’s SYSTEM folder) and bin/dvxpkg (the SDK, on the build machine) take the same commands:
dvxpkg build TEMPLATE.INI FOLDER OUT.DPK [KEY.SEC] dvxpkg sign NAME.DPK KEY.SEC [-d] dvxpkg verify NAME.DPK [-s NAME.SIG] [KEY.KEY ...] dvxpkg info NAME.DPK dvxpkg check NAME.DPK dvxpkg describe NAME.DPK dvxpkg keygen "Key name" BASE dvxpkg install NAME.DPK [-r DVXDIR] [-y] dvxpkg record NAME.DPK DVXDIR [-n] dvxpkg remove VENDOR.NAME [-r DVXDIR] [-f] dvxpkg list [-r DVXDIR] dvxpkg sealkey BASE dvxpkg sealcert KEY.SEC BASE.SLP BASE.SLC dvxpkg sealcheck BASE.SLK BASE.SLC KEY.KEY dvxpkg sealaccept BASE.SLK HELLO ACCEPT SESSION dvxpkg unseal SESSION REQUEST TEXT dvxpkg seal SESSION TEXT REPLY dvxpkg sealhello BASE.SLC KEY.KEY HELLO STATE dvxpkg sealopen STATE ACCEPT SESSION dvxpkg sealto SESSION TEXT REQUEST dvxpkg unsealreply SESSION REPLY TEXT
The last ten are a package server’s sealing (pkgSeal.h: what an account or the operator sends is sealed, because DVX has no TLS). sealkey makes a server’s sealing key, on the server (the server runs it the first time it starts): BASE.SLK, its secret, which never leaves the server, and BASE.SLP, its public half. It never writes over a key that is there. sealcert certifies BASE.SLP with the repository’s signing key KEY.SEC, where that key is kept, so that every DVX takes the key: BASE.SLC, which goes back to the server. sealcheck is the server’s check that the certificate is of its key and that KEY.KEY signed it. sealaccept, unseal, and seal are the server’s side: sealaccept answers a client’s hello with ACCEPT and writes the session (SESSION: secret; the server keeps it in memory); unseal opens the session’s next request into TEXT, once; seal seals TEXT as that request’s reply. Both update SESSION. sealhello, sealopen, sealto, and unsealreply are a client’s side, for a computer that is not running DVX: sealhello checks the certificate against KEY.KEY and makes the hello; sealopen makes the session from the server’s accept; sealto seals TEXT as the session’s next request; unsealreply opens the reply.
record writes a package’s installed record into a DVX folder whose files came another way (marked as Setup’s: no signature was checked), and prints the record’s name; with -n the package is recorded as needed by another (it goes when nothing needs it any more), not chosen. The release build records every package of DVX’s in Setup’s package that way (DVX itself, the base fonts, the optional bundles and their members: src/packages.ini), every file with its size and SHA-256, so an update from the package server replaces them as it would any package’s, removing the files the new version dropped.
On DOS, DVXPKG remove is the way out when an add-on keeps DVX from starting (DVX /SAFE, or holding Shift, also starts DVX without add-ons). The SDK’s make package builds NAME.dpk from a project (sdk.mk’s PKG_* settings), and the IDE’s File > Make Package from a BASIC project.
9.2. Package Server Library
The client of a DVX package server: what it offers (its catalog), what it has that is newer than the packages installed (DVX itself among them), and fetching packages, with everything they need that is not installed, into a download folder of the fetches' own (the user folder’s DOWNLOAD\SOFTWARE for PkgNetOpen; Terminal saves its downloads in DOWNLOAD); and, with an account on the server, publishing packages and listing what the account has sent; and making that account, and resetting its password, with the codes the server mails. All of it is plain HTTP, since DVX has no encryption: what is installed loses nothing by that (a package is trusted for its repository signature, never for the way it arrived), but an account’s email, password, and session token cross the network readable, and a signature protects none of them, so a program that asks for the password should say so, as Software does. In the download folder the package library reads them as from the server (pkgOfferScanStart with fromServer) and plans and installs them like any package file, but only those DVX’s own key signed. Software uses it for its Available and Updates pages.
Header: pkgnet/pkgNet.h
Loaded as: bin/libs/kpunch/pkgnet/pkgnet.lib (it needs the package, HTTP, and JSON libraries)
BASIC: pkgnet.bas (PkgNetOpen, PkgNetOpenIn for another DVX folder or download folder, PkgNetCatalogue, PkgNetUpdates, PkgNetFetch, PkgNetRunFor, PkgNetRows$, PkgNetField$ — PKG_FIELD_SHA256 and PKG_FIELD_REPO_SIGNED give a catalog entry’s sha256 and repoSigned —, PkgNetUpload, PkgNetMine, PkgNetRegister, PkgNetVerify, PkgNetRecover, PkgNetReset, PkgNetReply$, PkgNetUrlOf$ for the address a host name and port make, ...), with pkg.bas’s PkgOfferServerStart to read what was fetched for planning.
9.2.1. A Fetch
PkgNetT *n = pkgNetCreate(server, "", downloadDir);
const char *ids[] = { "acme.chess" };
if (n && pkgNetFetchStart(n, ids, 1, nowMs)) {
while (pkgNetPoll(n, nowMs) == PkgNetBusyE) {
// draw progress (pkgNetProgress, pkgNetCurrent), yield
}
}
// PkgNetDoneE: plan and install from pkgNetDir(n) (pkgPlan.h); once installed, pkgNetClear(n)
// PkgNetFailedE: pkgNetMessage(n) says why
pkgNetFree(n);
One job at a time; each poll does one piece of it (a piece of a request, or a slice of checking a file). nowMs is a millisecond clock, as for the HTTP library.
| Function | Description |
|---|---|
pkgNetCreate(server, root, dir) |
A client of the server at server ("http://host[:port]"), for the DVX folder root ("" the current one), fetching into dir, a folder of the fetches' own ("" none: a fetch then fails saying the user folder’s path is too long). When a fetch is done, the packages and signatures an earlier fetch left in dir go; a file whose name a fetch does not give is never touched. |
pkgNetCatalogueStart(n, nowMs) |
Read the catalog: every package the server offers, at its newest version. |
pkgNetUpdatesStart(n, nowMs) |
Ask what is newer than the packages installed (this DVX’s version and ABI are sent with the list). |
pkgNetFetchStart(n, ids, count, nowMs) |
Fetch packages by id, with what they need that is not installed in a version that will do. |
pkgNetPoll(n, nowMs) |
PkgNetBusyE, PkgNetDoneE, or PkgNetFailedE. |
pkgNetCancel(n) |
Stop the job; a download stopped part way is kept to resume. |
pkgNetEntries(n, &count) |
The answer: the catalog (after reading it or fetching) or the updates, as PkgNetEntryT (the manifest’s fields and needs, the package file’s size and SHA-256, and whether the repository signed it). |
pkgNetDb(n) |
The installed packages, as the last job read them. |
pkgNetProgress(n, &done, &total) |
A fetch’s bytes so far and in all (uint64_t: all the packages may be more than 4 GB). |
pkgNetCurrent(n), pkgNetMessage(n) |
The package the job is on, and why it failed. |
pkgNetDir(n), pkgNetClear(n) |
The download folder, and removing what the last fetch put there (once it is installed). |
pkgNetConfigRead(&c), pkgNetConfigWrite(&c) |
DVX.INI’s [packages]: server (a host name), port, user (an account’s email), and password (scrambled by prefsSetSecret), as a PkgNetConfigT (the defaults: PKGNET_SERVER_DEFAULT, port 80, no account). DVX’s own server and port 80 are written empty, so a change of PKGNET_SERVER_DEFAULT reaches the DVX.INI files already out there. |
pkgNetConfigUrl(&c, out, size) |
The address they make: "http://host", with ":port" when not 80 (an empty host is DVX’s own server, port 0 the usual one, and "http://host/" is taken for its host). A host written "https://host" stays so, and the job then fails saying DVX has no encryption. |
pkgNetAccountSet(n, user, password) |
The account the handle’s account jobs use. |
pkgNetUploadStart(n, path, nowMs) |
Publish the package file at path for the server’s review. |
pkgNetMineStart(n, nowMs), pkgNetMine(n, &count) |
What the account has sent, each version with its state (pending, approved, rejected, withdrawn) and the review’s note. |
pkgNetRegisterStart(n, email, password, nowMs) |
Ask the server for an account: it mails email a code. |
pkgNetVerifyStart(n, email, code, nowMs) |
Give the server that code: the account is ready. |
pkgNetRecoverStart(n, email, nowMs) |
Ask the server to mail email a code to reset its account’s password with. |
pkgNetResetStart(n, email, code, password, nowMs) |
Give the server that code with the account’s new password. |
pkgNetReply(n) |
What the server said to the last of those four that ended well ("" after any other job, or one that failed). |
9.2.2. What a Fetch Checks
Each package fetched must have exactly the size and SHA-256 the catalog gives; one that does not is removed and the fetch fails. The repository’s signature of it is fetched beside it (NAME.SIG); one the catalog says the repository has not signed is not fetched at all ("The package server has no signature of Name by DVX’s key, so it cannot be installed."). Read with pkgOfferScanStart’s fromServer (pkg.bas: PkgOfferServerStart), each package is an offer from the server, which the planner (and pkgOpInstall again) takes only when a key in SYSTEM\KEYS, DVX’s own repository key, signed it, whatever the catalog says: one that is not signed, is signed by another key (even one the user trusts), or whose signature by DVX’s key does not fit is refused, the reason saying which (pkgOfferAllowed). The server itself is never trusted: it is plain HTTP, and only the signatures count.
Each package’s file is named from its id and version (eight hex digits, a DOS name), so a download that stops part way (NAME.PRT) goes on from where it stopped the next time the same version is fetched, and one fetched before (not yet cleared) is checked again rather than downloaded again. When a fetch is done, the packages and signatures an earlier fetch left in the download folder are removed, so they are not read with this fetch’s; the parts of downloads that stopped stay. Only files named as a fetch names them are removed: a file anyone else put in the folder stays, whatever its name ends in.
Every message pkgNetMessage gives is a sentence. A request the server refused says "The package server answered code (its message) to the request", naming the request: "the request for its catalog", "the request for the updates", "the download of Name", "the request for the signature of Name", "the request to sign in", "the upload of File", or "the request for the list of your packages". A register, verify, recover, or reset the server refused gives the server’s own message instead, as "The package server says: its message." (see Making an Account).
What a package needs that no version on the server will do for is left for the planner to name. Installing what was fetched is the package library’s job: read the folder’s offers, plan, and run the install as a job.
9.2.3. An Account
The account’s jobs sign in first (POST /v1/account/login) when the handle has no session yet, keep the session for the handle’s later jobs, and sign in once more when the server answers that the session has gone. A wrong email or password fails the job saying so. The password is DVX.INI’s (prefsGetSecret); the session’s token is kept only in memory and wiped, with the password, when the handle is freed.
9.2.4. What an Account Sends Is Sealed
DVX has no TLS, so every request that names an account or carries its session (signing in, the account’s list, an upload, and the four requests below) is sealed (pkgSeal.h: X25519, HKDF, and XChaCha20-Poly1305), and so is its answer. The first of them on a handle reads the server’s sealing key’s certificate (GET /v1/sealkey), checks that one of DVX’s own keys signed it (a SYSTEM key of the keyring), makes a key of its own for the session, and sends its public half (POST /v1/sealstart); the server answers with a session key of its own and a proof that it holds the sealing key. The session’s keys come from both session keys and the sealing key: three X25519 operations run a slice a poll, about half a second of a 486DX2-66 in all. The keys last as long as the handle and are kept in memory only, at both ends, so what is recorded off the network stays unreadable even to someone who takes the server’s sealing key later. Each sealed request after that costs a few milliseconds. It goes as POST /v1/sealed (its method, path, session token, and body inside), and an upload as POST /v1/upload with the package as its body and the sealed lines, the package’s SHA-256 among them, in the X-DVX-Seal header. Requests are counted, and the server takes each count once.
The server keeps a session for a while after its last request. When it answers that it no longer has one (410), the handle makes a new session and sends the request again, once, without the job failing.
A server with no sealing key, or with one no DVX key signed, is not signed in to: the job fails ("The package server’s sealing key is not signed by DVX’s key, so DVX does not sign in to it.") and nothing of the account is sent. An answer that does not open (it was changed on the way, or is not that server’s) fails the job, and the keys are made again for the next. The catalog, updates, downloads, and signatures are not sealed: they are public, and a package is trusted for its signature.
9.2.5. Making an Account
An account is made, and its password reset, with codes the server mails to the account’s address; these four jobs need no session, and do not use or change the handle’s account (pkgNetAccountSet). Each is one request, which the server answers with a message.
pkgNetRegisterStart(n, "you@example.com", password, nowMs); // POST /v1/account/register
// ... poll to PkgNetDoneE: pkgNetReply(n) is what the server said; the mail brings a code
pkgNetVerifyStart(n, "you@example.com", "ABCD-EFGH", nowMs); // POST /v1/account/verify
// ... poll to PkgNetDoneE: "Your account is ready."
pkgNetRegisterStart asks for an account for an email address with a password; the server mails the address a code of eight letters and digits, shown in two groups ("ABCD-EFGH"), and pkgNetVerifyStart with that code makes the account one that can sign in. Asking again for an account that is not ready yet replaces its password and sends a new code, which retires the old one. For a forgotten password, pkgNetRecoverStart asks the server to mail a code, and pkgNetResetStart gives it with the new password; the account’s sessions end, so a handle signed in with the old password signs in again when given the new one (pkgNetAccountSet). The server takes a code in capitals or small letters, with its hyphen or without.
When the job is PkgNetDoneE, pkgNetReply is the server’s message: "Your account is ready.", "Your password has been changed.", or, for a register or a recover, a sentence that is the same whether the address has an account or not (the server does not say which addresses have accounts, so no mail is the only sign that an address already has one, or has none to recover). When the server refuses, the job is PkgNetFailedE and pkgNetMessage is "The package server says: " and the server’s message, made a sentence: an address that is none, a password too short (DVX’s own server wants 10 characters), a code that is wrong, used, or too old (one answer for all three; on DVX’s own server a register’s code is good for two days, a recover’s for two hours, and either stops working after five wrong tries), or too many tries (HTTP 429). A refusal with no message says what the server answered, naming "the request for an account", "the request to finish your account", "the request for a code to reset your password", or "the request to change your password".
Software’s File > Package Server window does all of this with its Create Account and Forgot Password buttons.
Chapter 10. Sound, Music, Joysticks, and Games
10.1. Sound Library
Sound for DVX programs through whatever sound hardware the computer has: sampled sound from WAV and VOC files, tones and noise, and streams a program feeds itself (music, speech). Every program opens its own audio context; any number of programs play at the same time through one mixer, and everything a program opened is stopped and released when it ends, normally, killed, or crashed.
Header: audio/audio.h (programs), audio/audioDrv.h (sound drivers)
Loaded as: bin/libs/kpunch/audio/audio.lib, drivers in bin/libs/kpunch/audio/drivers/*.drv
10.1.1. Contexts and the Device
AudioCtxT *audio = audioOpen(); // NULL: no driver could start
int32_t voice = audioPlayFile(audio, "BOOM.WAV", AUDIO_VOLUME_MAX, AUDIO_PAN_CENTER, false);
if (voice < 0) {
dvxLog("no boom: %s", audioErrorText(voice));
}
...
audioClose(audio); // or let the program end
The first audioOpen starts the sound device and the last audioClose stops it; the driver modules it used stay loaded, and the next first audioOpen tries them first (no other driver is loaded or probed) while DVX.INI’s driver choice is the same. In between, after AUDIO_IDLE_CLOSE_SEC (10) seconds with nothing playing, the device’s output is closed so it costs no CPU time (desktop sounds would otherwise keep it mixing silence), and the next sound opens it again with the same driver before it starts, so nothing of it is lost; audioGetInfo still reports the device. Every voice counts as playing while it is there, silent or not: an open stream (also one with nothing written, and music.lib’s music on a stream), an open note queue (also an empty one), and a paused voice keep the output open, and the mixer running, until they are closed. A program that keeps a note queue open for its whole life (as the game template does) keeps the output open that long; close a queue or stream when it will be quiet for a while. Functions returning int32_t give AUDIO_OK or a voice id (above 0) on success and a negative AUDIO_ERR_* code on failure; audioErrorText says what a code means. audioGetInfo describes the device: the driver’s name and description, the mixing rate it achieved, its output bits and channels, the voice limit, and whether it plays sampled sound (hasDac), has a hardware synthesizer (hasSynth), or plays tones on a hardware tone generator (hasTone, the PC speaker). audioGetStats counts mixed blocks and frames, stream underruns, clipped samples, dropped voices, and the voices playing.
None of the functions may be called from an interrupt, with one exception: the FM, MIDI port, and wavetable calls named in their sections (audioFmAlloc, audioFmFree, audioFmWrite, audioFmRawWrite, audioMidiPut, and the wavetable voice calls) may also be called from a timer callback (platformTimerAdd), as music playback does. Every call takes NULL for its context, sample, stream, note queue, or recording: it does nothing and returns AUDIO_ERR_ARG (AUDIO_ERR_VOICE for a voice call), 0, false, or an empty format.
10.1.2. Samples and Voices
audioSampleLoad (file), audioSampleLoadMem (memory), and audioSampleCreate (raw PCM in an AudioFormatT: rate, 8 bits unsigned or 16 bits signed, 1 or 2 channels) make an AudioSampleT; audioSampleFree frees it and stops the voices playing it. audioPlay(sample, volume, pan, loop) plays it on a new voice; audioPlayFile loads a file and plays it, freeing the sample when the voice ends.
| Setting | Range |
|---|---|
volume |
0 .. AUDIO_VOLUME_MAX (256) |
pan |
AUDIO_PAN_LEFT (-256) .. AUDIO_PAN_RIGHT (256); center plays at full volume on both sides and panning turns the other side down |
pitch |
AUDIO_PITCH_MIN (64) .. AUDIO_PITCH_MAX (1024), AUDIO_PITCH_NORMAL (256) = recorded speed |
audioVoiceSetVolume, audioVoiceSetPan, audioVoiceSetPitch, audioVoicePause, audioVoiceStop, and audioVoiceIsPlaying take the context and the voice id; a voice id of another context, or of a voice that has ended, gives AUDIO_ERR_VOICE. audioVoicePause(ctx, voice, paused) holds a sample’s or a stream’s voice where it is (it stays playing, silent, and takes nothing from its stream) or lets it go on; a tone or a note queue gives AUDIO_ERR_ARG. audioStopAll stops every sample and tone of a context.
audioSetEndFn(ctx, fn, userData) asks for a call when a voice of ctx ends, with the reason: AUDIO_END_FINISHED (played out), AUDIO_END_STOPPED (stopped, or its sample or stream went away), or AUDIO_END_DROPPED (the voice limit made room for a louder sound). The call comes from audioPump or the shell’s idle time, as the program that owns the context, never from an interrupt. The mixer runs up to one buffer (about 50 ms) ahead of what is heard, so a notification can come that much before the sound has finished playing.
10.1.3. Tones
audioTone(ctx, wave, hz, volume, ms) plays a square (AUDIO_WAVE_SQUARE), triangle (AUDIO_WAVE_TRIANGLE), or noise (AUDIO_WAVE_NOISE) tone of hz (AUDIO_TONE_MIN_HZ 20 to AUDIO_TONE_MAX_HZ 20000) for ms milliseconds, or until stopped when ms is 0. For noise, hz is how fast the noise changes: higher sounds brighter. audioVoiceSetFrequency changes a playing tone. When the computer has an FM chip (and DVX.INI [audio] fmTones is not false), a square or triangle tone plays on a free FM voice (a square as a carrier modulated at twice its pitch, which gives odd harmonics like a square wave; a triangle as a sine) at up to the chip’s highest note (about 6,200 Hz); when every FM voice is taken it is mixed like any sound. Its voice id, volume, pan, pitch, and end notification work the same either way. On a device with a DAC tones are mixed like any sound; on the PC speaker in its tones mode the loudest square or triangle tone playing is sounded by the timer chip.
10.1.4. Note Queues
AudioNotesT *tune = NULL;
audioNotesOpen(audio, AUDIO_WAVE_SQUARE, AUDIO_VOLUME_MAX, &tune);
audioNotesAdd(tune, 440 * AUDIO_MILLIHZ_PER_HZ, 250000); // A for 1/4 s
audioNotesAdd(tune, 0, 50000); // a rest
A note queue plays tones and rests one after the other, each lasting exactly as long as asked (its length is counted in output frames from the time queued since the queue last went quiet, so many short notes do not drift). audioNotesAdd(notes, milliHz, us) appends a tone of milliHz thousandths of a hertz (AUDIO_TONE_MIN_HZ to AUDIO_TONE_MAX_HZ, or 0 for a rest) lasting us microseconds; up to AUDIO_NOTES_MAX entries may wait (AUDIO_ERR_BUSY beyond). audioNotesSetTone(notes, wave, level) sets the waveform and loudness (0..AUDIO_VOLUME_MAX, a share of the queue’s volume) of the entries added from then on — each entry plays in its own, so a tune changes them in time — and a tone generator plays a tone at level 0 as a rest. audioNotesQueued says how many entries have not finished (and how many of them are tones), audioNotesSpace how many more fit, audioNotesClear silences the queue at once. The queue plays on its own voice (audioNotesVoice, for volume and pan) that the voice limit never drops, in the mixer or on the PC speaker’s tone generator (never on the FM chip); it is silent while empty. music.lib plays QBasic’s PLAY and SOUND through note queues.
10.1.5. Streams
AudioFormatT fmt = { 22050, 16, 2 };
AudioStreamT *stream = NULL;
audioStreamOpen(audio, &fmt, 250, fillMusic, &player, &stream);
audioStreamOpen(ctx, fmt, bufferMs, fill, userData, &stream) opens a stream of any rate from AUDIO_RATE_MIN (4000) to AUDIO_RATE_MAX (48000), 8 or 16 bits, mono or stereo, with a buffer of bufferMs milliseconds (0: 250). It plays at once on its own voice (audioStreamVoice), silence until samples arrive. Without fill the program writes samples with audioStreamWrite, which takes as many frames as fit and returns how many; audioStreamSpace and audioStreamQueued tell how much room and how much sound are left. With fill, the library asks for samples whenever the buffer has room: fill(stream, buf, frames, userData) writes up to frames frames in the stream’s format and returns how many. Fill functions run from audioPump and the shell’s idle time; a program that keeps the desktop busy every frame should call audioPump once a frame. Once a stream holds 100 ms of sound, a pump fills it for 15 ms at most (STREAM_FILL_BUDGET_US) and the next pump goes on, so a fill function that takes its time (a module rendered, a file read) does not hold DVX up after a start, a seek, or a stall. A stream that runs dry plays silence and counts underruns. audioStreamEnd says no more frames will come after those written (a fill function may call it with its last ones): the fill function is not asked again, and once the stream has played what it holds its voice ends as a sample’s does (AUDIO_END_FINISHED to the end function), with nothing counted as an underrun; the stream stays open until audioStreamClose. Without it a stream that has played its last frame runs on in silence, counting underruns, until it is closed. audioStreamFlush drops what the stream holds and has not played yet (a seek or a stop is heard at once; the two frames the mixer has read ahead still play). audioStreamClose stops and frees it.
audioDrv.h also declares, for audio.lib and the libraries built on it (music.lib), audioDecode (a WAV or VOC file in memory as 16-bit frames), audioConvert (8- or 16-bit frames as 16-bit ones), and audioWavParse(head, headBytes, fileBytes, &fmt, &dataAt, &dataBytes) (a WAV file’s format and where its frames are, from its first bytes: the frames are clamped to the file and whole; AUDIO_ERR_FORMAT for anything but a RIFF WAVE file, AUDIO_ERR_UNSUPPORTED, AUDIO_ERR_CORRUPT).
10.1.6. Recording
AudioFormatT fmt = { 22050, 16, 1 };
AudioRecT *rec = NULL;
if (audioRecFile(audio, "TALK.WAV", &fmt, AUDIO_REC_MIC, &rec) == AUDIO_OK) {
// ... later: keep it, or throw it away (TALK.WAV stays as it was)
if (keep) {
audioRecClose(rec);
} else {
audioRecCancel(rec);
}
}
audioRecOpen(ctx, fmt, source, bufferMs, &rec) records from the card’s microphone, line, or CD input (AUDIO_REC_MIC, AUDIO_REC_LINE, AUDIO_REC_CD; AudioInfoT.canRecord, and recSources with bit 1 << source for each the card has) into a buffer of bufferMs (0: AUDIO_REC_MS_DEFAULT, 2 seconds; AUDIO_REC_MS_MIN to AUDIO_REC_MS_MAX). fmt asks for a rate, 8 or 16 bits, and mono or stereo (0: AUDIO_RATE_DEFAULT, AUDIO_REC_BITS_DEFAULT, mono) and comes back as what the card records: its nearest rate, and its own bits and channels when it cannot do the ones asked (a card before the SB Pro records 8-bit mono). The program takes the frames with audioRecRead(rec, pcm, frames) before the buffer fills; audioRecQueued says how many wait, audioRecLost how many were dropped because the buffer was full (whole blocks, so the frames stay in order), audioRecFrames how many were taken, and audioRecPeak the loudest sample since it was last asked, in percent (a level meter). audioRecFile(ctx, path, fmt, source, &rec) records into a WAV file instead: the library writes the frames as they come (audioPump and the shell’s idle time) into a scratch file beside path (the PLATFORM_TMP_EXT sibling, on the same disk), and at audioRecClose writes the sizes and, once all of it was written, swaps it in for path (platformReplaceFile). A file already at path is not touched until then: a recording that cannot start, or is not all written, leaves it as it was and removes the scratch file. Everything that can be checked (the arguments, another recording, the card and its input, and that path may be replaced: not a folder or a read-only file, platformCanReplaceFile) is checked before the scratch file is made (AUDIO_ERR_WRITE when path may not be replaced or the scratch file cannot be made). path is made absolute when the recording starts, so a change of folder while it runs does not move it. audioRecClose stops and returns AUDIO_ERR_WRITE when the file could not all be written or swapped in; that recording is thrown away. audioRecCancel(rec) stops and throws the recording away on purpose: the scratch file is removed and a file already at path stays as it was, byte for byte (a recording into memory just goes). Both give the card back and free rec. audioRecPause(rec) pauses the recording and audioRecResume(rec) goes on with it: while it is paused nothing is taken, the blocks the card records being dropped as they come (not counted by audioRecLost), so the frames after the pause follow the last ones taken before it with nothing between, and audioRecFrames, audioRecQueued, and the file leave the paused time out. The frames taken before the pause are still written or read; a pause takes effect at the card’s next block (a few hundredths of a second), and the card stays taken for recording meanwhile, so nothing plays. Pausing a paused recording, or resuming a running one, does nothing; both return AUDIO_OK, AUDIO_ERR_ARG for NULL, or AUDIO_ERR_ENDED for a recording a DOS program ended. audioWavHeader(out, fmt, dataBytes) writes the AUDIO_WAV_HEADER_BYTES of a WAV header for programs writing their own files.
The Sound Blasters (sb), Windows Sound System boards (wss), and the Gravis UltraSound (gus) record; the DACs on the printer port, the PC speaker, and null do not. Most cards record or play, not both, so recording takes the card: its output closes (as after a silence), voices already playing hold where they are, and a new voice gets AUDIO_ERR_BUSY (the desktop’s sounds are skipped) until the recording ends and the held voices play on. One recording at a time for all of DVX (another gets AUDIO_ERR_BUSY). Closing the context (the program’s end) ends the recording as audioRecClose does: a recording into a file is completed and kept. A DOS program run with DVX stepped aside (audioSuspend; usually by the program that waits on it, shellRunDosFor, as the others are asked to close first) ends it the same way, but rec stays the program’s: audioRecEnded(rec) is then true, nothing more is recorded, another recording may start, audioRecFormat, audioRecFrames, and audioRecLost tell what it was, and a recording into memory still gives the frames it had not given (audioRecRead, audioRecQueued). The program frees it with audioRecClose, which returns what its end gave (AUDIO_OK, or AUDIO_ERR_WRITE when its file could not all be written), or audioRecCancel, which returns AUDIO_ERR_ENDED: it is too late to throw it away, and a file it completed stays. Closing the context frees it too. A pause asks nothing of the driver: sb.drv, wss.drv, and gus.drv (on the GF1’s sampling or a MAX’s codec) all keep the card recording, and audioRecPush drops the blocks their interrupts hand on until the recording resumes (audioRecRing is NULL meanwhile), so no driver’s transfer is stopped and started again.
10.1.7. FM Synthesizer
int32_t v = audioFmAlloc(audio); // AUDIO_ERR_NO_VOICE: all taken
audioFmWrite(audio, v, AUDIO_FM_CAR_LEVEL, 0);
audioFmWrite(audio, v, AUDIO_FM_FNUM_LOW, fnum & 0xFF);
audioFmWrite(audio, v, AUDIO_FM_KEY_BLOCK, AUDIO_FM_KEY_ON | (block << AUDIO_FM_BLOCK_SHIFT) | (fnum >> AUDIO_FM_FNUM_HI_SHIFT));
audioFmFree(audio, v); // key off, back to everyone
An OPL2 (9 voices) or OPL3 (18 voices, each playing left, right, or both) found by the opl driver is shared by every program: audioFmAlloc(ctx) takes a two-operator voice (the least recently given back first, so a released note’s tail is cut last) and returns its id, AUDIO_ERR_NO_VOICE when all are taken, AUDIO_ERR_BUSY while a program has the whole chip, AUDIO_ERR_NO_SYNTH without a chip. audioFmWrite(ctx, voice, reg, value) sets a register of the voice’s channel, numbered as for the first channel of an OPL2 (AUDIO_FM_MOD_CHAR 20h, AUDIO_FM_CAR_CHAR 23h, levels 40h/43h, attack 60h/63h, sustain 80h/83h, waveforms E0h/E3h, AUDIO_FM_FNUM_LOW A0h, AUDIO_FM_KEY_BLOCK B0h, AUDIO_FM_FEEDBACK C0h); the library adds the channel’s offsets and bank. On an OPL3 a feedback value without an output bit (AUDIO_FM_OUT_LEFT, AUDIO_FM_OUT_RIGHT) plays on both sides. Frequencies: hz = fnum x AUDIO_FM_CHIP_HZ (49,716) x 2^block / 2^20. audioFmFree keys the voice off and gives it back; closing the context gives back all of its voices. audioFmGetInfo tells the chip, its voices, and how many are free.
audioFmRawAcquire(ctx) gives one program the whole chip: every voice the others hold is keyed off and taken back (their tones go on in the mixer), new voices are refused, and audioFmRawWrite(ctx, reg, value) sets any register (bank x AUDIO_FM_BANK_REGS + index). A second program asking gets AUDIO_ERR_BUSY. audioFmRawRelease (or closing the context) silences the chip, sets it up again, and gives its voices back to everyone.
audioFmAlloc, audioFmFree, audioFmWrite, and audioFmRawWrite may also be called from a timer callback (platformTimerAdd); music.lib plays MIDI that way.
10.1.8. Wavetable Synthesizer
uint32_t addr = 0;
int32_t v = audioWtAlloc(audio); // AUDIO_ERR_NO_VOICE: all taken
AudioWtVoiceT note;
audioWtMemAlloc(audio, frames * 2, 16, &addr);
audioWtUpload(audio, addr, pcm, frames, 16);
audioWtNoteInit(¬e); // a plain note: no envelope, the filter open
note.addr = addr;
note.end = frames;
note.bits = 16;
audioWtStart(audio, v, ¬e); // pitch 0: AUDIO_WT_PITCH_RATE (44,100) frames a second
A wavetable synthesizer (a Gravis UltraSound’s GF1, a Sound Blaster AWE32’s or AWE64’s EMU8000) plays samples from its own memory, and its voices and memory are shared by every program. audioWtGetInfo tells the chip (description, voices, free voices, memory, the largest free block, what it does itself: AUDIO_WT_ENVELOPES, AUDIO_WT_LFOS, AUDIO_WT_FILTER, AUDIO_WT_EFFECTS, AUDIO_WT_8BIT for 8-bit samples, AUDIO_WT_BANK_256K when a 16-bit sample must not cross a 256 KB boundary, AUDIO_WT_ROM for a General MIDI sample ROM; and its level, the centibels a voice at full volume is louder than full-scale digital sound, measured: 0 on a GUS, whose digital sound plays on its own voices, 76 on an AWE). audioWtMemAlloc(ctx, bytes, bits, &addr) takes memory for samples of bits bits (AUDIO_ERR_NO_ROOM when no free block is large enough), audioWtUpload(ctx, addr, frames, count, bits) copies 16-bit frames into it at bits, audioWtMemFree gives it back. audioWtAlloc(ctx) takes a voice (the least recently given back first), audioWtStart(ctx, voice, note) starts it on a note (AUDIO_ERR_ARG for a sample in a ROM the chip does not have; AudioWtVoiceT: the sample’s address, or AUDIO_WT_ADDR_ROM with an address in the ROM, and in frames from there the one it starts from (offset: before the loop or inside it), its loop, and its end; pitch in cents, 0 for AUDIO_WT_PITCH_RATE (44,100) frames a second; attenuation in centibels; pan; the filter, reverb and chorus; both envelopes in timecents; both LFOs; audioWtNoteInit makes a plain one, with no envelope or LFO shaping it, the filter open, no effects, centered, at full volume, for the caller to set the sample on), audioWtUpdate changes what its what bits say (AUDIO_WT_SET_PITCH, _VOLUME, _PAN, _FILTER, _EFFECTS, _LFO), audioWtRelease lets the key up, audioWtStop stops it at once, audioWtActive is false once it is silent, audioWtFree gives it back. The chip does what its flags say; the program does the rest by updating the voice as the note goes on. Closing the context gives back its voices and its memory. The voice calls may be made from a timer callback (music.lib plays SoundFont MIDI and modules that way); the memory calls may not.
10.1.9. MIDI Port
With DVX.INI [audio] midi = mpu401 the mpu401 driver opens an MPU-401 (or compatible, such as a Sound Blaster 16’s) in UART mode, for an external synthesizer such as a Roland MT-32 or SC-55. The port belongs to one program at a time: audioMidiAcquire(ctx) (AUDIO_ERR_BUSY when another has it, AUDIO_ERR_NO_SYNTH without a port), audioMidiPut(ctx, byte) sends a byte and returns AUDIO_ERR_BUSY when the port cannot take one yet (send it again later; it may be called from a timer callback), audioMidiRelease gives it back (closing the context does too). audioMidiGetInfo tells whether there is a port and whether it is in use. music.lib uses the port for MIDI music.
10.1.10. MIDI Input
With DVX.INI [audio] midiIn = mpu401 the same port also brings in what a MIDI keyboard or another instrument plays (the port is shared with MIDI music when midi = mpu401 too). One program reads it at a time: audioMidiInOpen(ctx) (AUDIO_ERR_NO_SYNTH when there is no MIDI input, AUDIO_ERR_BUSY when another program reads it), audioMidiInClose(ctx) (closing the context does it too, and a DOS program run with DVX stepped aside closes it). A timer reads the port AUDIO_MIDI_IN_HZ (1,000) times a second into a buffer of AUDIO_MIDI_IN_BYTES with the time each byte came; audioMidiInRead(ctx, &msg) gives the next whole message, oldest first (false when none waits): AudioMidiMsgT has its status (a channel message 80h..EFh, the kind and the channel, or system common F1h..F3h), data1, data2, length (1 to 3 bytes), and ms, when its first byte came in milliseconds since audioMidiInOpen. Running status is filled in; clock and active-sensing bytes are dropped and system exclusive messages skipped. audioMidiInClock(ctx) is the time now on that clock, and audioMidiInLost(ctx) the bytes dropped because the buffer was full (the program read too late). audioMidiGetInfo says whether there is MIDI input (inPresent) and whether a program reads it (inOwned). music.lib plays what comes in (musicMidiSend) and records it into MIDI files (musicMidiRecordNew); the Sound Recorder does both.
10.1.11. Volume and the Voice Limit
audioSetMasterVolume sets the volume of all sound (DVX.INI [audio] volume, in percent, sets it when the device starts); audioSetVolume sets the volume of everything one context plays. At most the voice limit (DVX.INI [audio] voices, 1 to AUDIO_VOICES_MAX, default 16) plays at once. Starting another sample or tone then stops the quietest one playing (it ends with AUDIO_END_DROPPED); when the new sound would itself be the quietest it is not started (AUDIO_ERR_NO_VOICE). Streams are never dropped.
10.1.12. Files
WAV: uncompressed PCM, 8-bit unsigned or 16-bit signed, mono or stereo, 4000 to 48000 Hz; WAVE_FORMAT_EXTENSIBLE with the PCM sub-format is accepted, other chunks are skipped, and a data chunk that claims more bytes than the file holds plays what is there. VOC (Creative Voice File, header checksum checked): sound blocks with 8-bit unsigned samples, continuation, silence, extended (rate and stereo for the next sound block), and new-format blocks with 8-bit or 16-bit PCM; markers and text are skipped, and a repeated section plays once. Compressed sound (ADPCM, 24-bit, floating point) gives AUDIO_ERR_UNSUPPORTED, a damaged file AUDIO_ERR_CORRUPT, a file that is neither AUDIO_ERR_FORMAT.
10.1.13. The Mixer
All sound is mixed in 16-bit integers at the rate the device achieved (the mixer never assumes the rate it asked for: a Sound Blaster Pro asked for 22,050 Hz plays at 22,222 Hz), and every source is resampled to it with linear interpolation. Gains combine volume, pan, context volume, and master volume; the sum is clipped to 16 bits. The mixer runs from the sound card’s own interrupt (at the end of each half buffer of about 23 ms), or from the timer service for devices without one, so sound keeps playing however busy the programs are. It uses no floating point and touches only memory pinned for interrupts (sample and stream buffers are pinned when they are made). A 486’s multiplies are slow, so the mixer does none whose result is known: a sound at the device’s rate is copied frame for frame without interpolating, a mono one is worked out once for both sides, and a centered mono one scaled once. Measured on an emulated 486DX2-66 at 22,050 Hz, eight mono sounds at the device’s rate take about 19 percent of the CPU, eight at half of it (interpolated) about 30 percent.
10.1.14. Settings
DVX.INI section [audio]:
| Key | Meaning |
|---|---|
driver |
auto (default: find the hardware), or a driver name: wss, sb, gus, lpt, speaker, null |
rate |
mixing rate asked for, 4000 to 48000 (default 22050) |
bits |
0 (the device’s best), 8, or 16 |
channels |
0 (the device’s best), 1, or 2 |
voices |
voices mixed at once, 1 to 32 (default 16); with all in use a new sound stops the quietest only when it is louder, else it does not play (AUDIO_ERR_NO_VOICE), and music never stops another sound |
volume |
master volume in percent (default 100) |
speakerPcm |
true: sampled sound on the PC speaker (see below); default false |
fmTones |
false: tones always in the mixer, never on FM voices; default true |
oplPort |
the FM chip’s port, hex (default 388; empty: the default) |
midi |
where MIDI music plays (music.lib): auto (default: a wavetable synthesizer with its SoundFont, else the FM chip, else the software synthesizer), mpu401 (as auto when the port was not found or is busy), fm, software, softwave (the SoundFont in software) |
soundFont |
the SoundFont for wavetable MIDI (music.lib): a name in the banks folders or a path, or an UltraSound’s ULTRASND.INI; not set, the standard one, KPUNCH\DVXGM.SF2 (Control Panel’s Sounds page picks it) |
wssPort |
the Windows Sound System board’s port, hex (any; then only that one is tried); not set or empty: 530, 604, E80, and F40 are tried in that order |
wssIrq |
its IRQ: 7 (default), 9, 10, or 11 |
wssDma |
its DMA channel: 0, 1 (default), or 3 |
gusVoices |
voices the Gravis UltraSound runs, 14 to 32 (default 28: 22,050 Hz output; fewer, a higher rate) |
lptDac |
the parallel port DAC: auto (default: a Disney Sound Source, else a Stereo-on-1), covox, disney, stereo |
lptPort |
its port, hex (not set or empty: LPT1) |
midiIn |
where MIDI input comes from: none (default) or mpu401 (the MPU-401 port) |
mpuPort |
the MPU-401’s port, hex (default 330; empty: the default); the port is only looked for with midi or midiIn = mpu401 |
mpuMode |
what is on the MPU-401 (music.lib): gm (default), mt32, or raw |
midiBank |
the OP2 instrument bank for FM MIDI (music.lib): its name in SHARED\BANKS or the user’s BANKS folder (an add-on’s as VENDOR\NAME), or a path from the DVX folder; not set, the bundled one (Control Panel’s Sounds page picks it) |
A settings screen reads and writes the keys it offers through the library, so the key names live in one place (audio.h, Settings; prefs is a copy of DVX.INI the caller loads and saves): audioSettingDriver(prefs) (AUDIO_DRIVER_AUTO when missing), audioSettingMidi(prefs) (an index in audioMidiChoices, auto when missing or unknown), audioSettingMidiIn(prefs) (an index in audioMidiInChoices, none when missing or unknown), audioSettingModules(prefs) (an index in audioModulesChoices, wavetable when missing or unknown), audioSettingVolume(prefs) (percent, clamped to 0..100, 100 when missing), and audioSettingsStore(prefs, driver, midi, modules, volume) writes all four (an empty driver stores auto, a midi index out of range stores auto, a modules index out of range wavetable); audioSettingMidiInStore(prefs, midiIn) writes midiIn (an index out of range stores none), which takes effect when the device next starts; audioSettingSpeakerPcm(prefs) and audioSettingSpeakerPcmStore(prefs, on) read and write speakerPcm (AUDIO_INI_SPEAKER_PCM, false when missing). After saving DVX.INI, audioOutputRefresh() closes the sound output at the first moment nothing plays, instead of after AUDIO_IDLE_CLOSE_SEC of silence, so the next sound opens it with the new settings (rate, bits, channels, and the device’s own keys such as speakerPcm); the driver itself stays until DVX next starts. audioMidiChoices[AUDIO_MIDI_CHOICE_COUNT] holds the midi choices in list order, each with its label for people and the name stored (a PrefsChoiceT, dvxPrefs.h); audioMidiInChoices[AUDIO_MIDI_IN_CHOICE_COUNT] the midiIn choices, audioModulesChoices[AUDIO_MODULES_CHOICE_COUNT] the modules choices (wavetable: on a wavetable synthesizer’s voices when it is free and the module fits there; software: always mixed in software). audioPercentToVolume(percent) turns a percent into 0..AUDIO_VOLUME_MAX for audioSetMasterVolume. The device reads the driver and volume through the same functions when it starts. The Control Panel’s Sounds page uses all of these.
10.1.15. Desktop Sounds
The library plays the sounds DVX makes for its events (dvxPlaySound in dvxApp.h): when it loads it sets DVX’s sound hook to audioDeskPlay(event, wait). The file of each event is read from DVX.INI [sounds] at the first sound: the key is audioDeskKey(event) and the value a WAV or VOC file, empty or missing for none: a name alone is found in the sound folders (the user folder’s SOUNDS first, then SHARED\SOUNDS: platformKindFind), anything else is a path; audioDeskReload makes the next sound read the section again (the Control Panel calls it after saving). Each event’s file is decoded at its first sound and kept until then, so a window opening or a message box does not read the disk. The sounds play on a context of the library’s own, so no program’s end cuts one short, at full volume under the master volume. When no sound device starts, the sounds stay silent without trying again until the next reload. With wait the call returns once the sound has played (at most 5 seconds), running dvxWaitPump meanwhile (a BASIC program’s events go on); after the exit sound further events are quiet (DVX is ending). audioDeskLabel(event) names an event for people, audioDeskPlayFile(path) plays any file the same way (to try one out). audioDeskFile(prefs, event) reads an event’s file from a copy of DVX.INI ("" for none) and audioDeskSetFile(prefs, event, path) sets it; the library’s own reading of [sounds] goes through audioDeskFile too. The default set, made by DVX’s own sound generator at build time, is in SHARED\SOUNDS.
| Key | Event |
|---|---|
default |
the default beep (dvxBeep; a message box without an icon) |
startup |
DVX started |
exit |
DVX is ending |
error |
a message box with MB_ICONERROR |
warning |
MB_ICONWARNING |
question |
MB_ICONQUESTION |
information |
MB_ICONINFO |
windowOpen |
a window opened (not a dialog) |
windowClose |
a window closed (not a dialog) |
10.1.16. Drivers
- sb
-
Sound Blaster family by DSP version: 1.x (8-bit single-cycle), 1.5 / 2.0 (8-bit auto-init, high-speed above 23,000 Hz on 2.0), Pro and Pro 2 (8-bit stereo at 11,025 or 22,050 Hz), 16 (8- or 16-bit, mono or stereo, any rate from 5,000 to 44,100 Hz). It records with the same modes' input commands (sbRecordPlan): before the Pro the microphone only, 8-bit mono up to 13,000 Hz (15,000 on DSP 2.01, high-speed above 13,000); the Pro and the 16 also the line and CD inputs (mixer 0Ch; 3Dh / 3Eh with the microphone at full on the 16), recording what they play; the mixer registers it changes are put back when it stops. The port, IRQ, and DMA channels come from the BLASTER variable (e.g. SET BLASTER=A220 I5 D1 H5); without it an SB16 is found at 220h or 240h and asked for its IRQ and DMA. If no interrupt arrives from the card within half a second (a wrong IRQ), the next driver is tried.
- speaker
-
The PC speaker. By default tones only: the timer chip plays the loudest square or triangle tone as a square wave, with no interrupts and no CPU cost; sampled sound and noise are not heard. With speakerPcm = true it plays everything by pulse-width modulation: the timer interrupt runs at 22,096 Hz and each interrupt sets the next pulse (about 5.7 bits). That costs a lot of CPU time: 22,096 interrupts a second plus the mixing. A 486DX2-66 spends a large share of its time on it (estimated 10 to 15 percent for the interrupts alone on plain DOS, much more under a memory manager or Windows) and can lose interrupts, which slows the sound and the DVX clock down. Meant for Pentium-class machines.
- wss
-
A Windows Sound System board (an AD1848 codec or its kin: Microsoft’s, Crystal CS4231 / CS4248, Aztech, OPTi in WSS mode) at wssPort: 8- or 16-bit, mono or stereo, the codec’s nearest rate, double-buffered by auto-init DMA on wssIrq and wssDma (set through the board’s configuration register; a Plug and Play board set up by its own utility must be on the ones DVX.INI names). It records the same way (the codec’s capture on the same DMA channel): the line input, AUX1 (the CD on WSS boards), or the microphone with its 20 dB boost, putting back the inputs it found. Tried before the Sound Blaster, which such a board often also has.
- gus
-
A Gravis UltraSound, found through the ULTRASND variable (port, DMA channels, IRQs: SET ULTRASND=220,1,1,11,5): digital sound on two of its voices from a ring at the top of its memory, refilled by DMA at each half, and its wavetable synthesizer on the rest (gusVoices active in all). It records from the microphone or the line input on ULTRASND’s second DMA channel (the first when the second is not given): an UltraSound MAX (board version 10 or 11) through its CS4231 codec, as a Windows Sound System board records (8- or 16-bit, mono or stereo, the codec’s rates), any other board with the GF1’s own sampling (8-bit, mono or stereo, 5,510 to 44,100 Hz, each half started from the terminal count of the one before, since the GF1 does not run on by itself); no emulator DVX is tested on records on a GUS, so this follows Linux’s drivers. Tried after a Sound Blaster beside it, which then plays the digital sound while the GUS plays music (guswt).
- lpt
-
A DAC on the parallel port (lptDac, lptPort): a Covox Speech Thing (used only when lptDac = covox: it cannot be found), a Disney Sound Source (a FIFO at a fixed 7 kHz, topped up by the timer), or a Stereo-on-1. 8-bit at most 11,048 Hz; the Covox and the Stereo-on-1 take a timer interrupt for every frame.
- null
-
No sound device: plays nothing, but voices still run their course and end, so programs behave the same.
- opl
-
(synthesizer) The OPL2 or OPL3 FM chip of an AdLib or Sound Blaster at 388h (oplPort), found by the AdLib timer test (timer 1 must overflow at its fastest count and not at its slowest, which also tells the AdLib-compatible timers of a Gravis UltraSound, which has no FM, from a chip); the status register tells an OPL2 from an OPL3. Register writes are timed by status reads (3.3 and 23 us on an OPL2) with interrupts off around each index/data pair. Closing zeroes every register.
- awe
-
(synthesizer) The EMU8000 of a Sound Blaster AWE32 or AWE64 (BLASTER’s E, else A + 400h), set up as Creative’s programmer’s guide gives: 30 voices (two carry the FM chip’s sound), its memory in 512 KB steps, envelopes, LFOs, filter, reverb and chorus in hardware, and its 1 MB General MIDI sample ROM.
- gus, guswt
-
(synthesizer) The Gravis UltraSound’s voices playing samples from its memory, with the library running the envelopes and LFOs: gus.drv’s own when it plays the digital sound too, else guswt.drv (the GUS beside another sound device, all its voices for music).
- mpu401
-
(synthesizer) An MPU-401 MIDI port in UART mode at mpuPort, only with midi or midiIn = mpu401: reset (FFh, answered FEh; tried twice, since a port left in UART mode takes the first FFh as data), then UART mode (3Fh). Bytes are sent when the port says it is ready (a short wait, else the caller sends later); input the port has waiting then is kept for get, the MIDI input’s timer (64 bytes; more is dropped while nobody reads it). Closing sends All Notes Off on every channel and resets the port.
audioDriverNames(names, max) lists the short names of the sound drivers installed, the one tried first first (for a settings screen; AUDIO_DRIVERS_MAX is the most DVX’s own callers ask for).
Sound drivers are tried in this order: the one DVX.INI names, then from the highest priority down (Windows Sound System, Sound Blaster, Gravis UltraSound, parallel port DAC, PC speaker, null). The first that starts is used. Synthesizer drivers are opened with the sound device, beside it: the sound device’s own first (the GUS’s), then of each kind (FM chip, MIDI port, wavetable) the first that finds its hardware, and they close with the device. The sound device’s description and hasSynth in AudioInfoT tell whether there is a synthesizer.
10.1.17. Writing a Driver
A driver is a driver module (see dvxDrv.h in the API reference): <name>.drv in bin/libs/kpunch/audio/drivers, built by the audio Makefile from each drivers/<name>/ folder, that exports one AudioDriverT named audioDriver, written with AUDIO_DRIVER(name, AUDIO_PRIORITY_*, .open = ..., .play = ..., .close = ...). The descriptor carries DVX_ABI_VERSION; a driver built for another version is refused. audio.lib loads the drivers when the first program opens sound, keeps the one that starts (and the synthesizers that find their hardware) and unloads the rest; when the last program closes sound it closes them but keeps their modules for the next device, which opens them again first (so open and close must work more than once). The drivers' names (audioDriverNames) are read once a session. open detects the hardware and fills AudioDrvInfoT (description, achieved rate, bits, channels, hasDac, hasSynth, a hardware tone function) without making a sound; play starts output; close stops it and releases everything, after which the mixer is not called again. After a few seconds of silence audio.lib calls close and later open and play again on the same driver, so open must work more than once and must not make a sound (the driver’s module stays loaded in between). A driver whose card records also sets AudioDrvInfoT.recSources and gives recordStart(want, source, got) and recordStop: recordStart is called with the output closed and takes the card for recording (its own DMA buffer and interrupt; the format the card records in got), its interrupt then calls audioRecPush(src, bytes) with each block recorded (whole frames; a block that does not fit is dropped and counted), and recordStop gives everything back as close does (sb.drv, wss.drv, and gus.drv use their close for both; the AD1848 codec’s routines a Windows Sound System board and an UltraSound MAX share are codec/codecHw.c). A pause (audioRecPause) asks nothing of the driver: its card goes on recording, and audioRecPush drops the blocks until the recording resumes. While playing, the driver calls audioMixRender(buffer, frames) for each block of output from its own interrupt, or calls audioClockStart to have the timer service drive the mixer (the output is thrown away) when it only plays tones or nothing. Code and data an interrupt touches must be pinned: audioLockSpan pins a module’s listed functions and data (a module’s code comes before its data, so one span covers them), and the library is built without hot/cold function splitting and without loops turned into library calls. Interrupt code must not call the C library, DVX, or DOS and must not use floating point. audio.lib stops the device from a shutdown hook if DVX ends without closing it. A driver reads its own keys in [audio] from the copy of DVX.INI its open is given (AudioDrvConfigT.prefs); audioSettingPort(prefs, key, defaultPort) reads a port key (hexadecimal: 220, 0x220, and 220h are all 220h) and gives defaultPort for a key that is missing, empty, or no port, so a driver never probes port 0.
A synthesizer driver exports an AudioSynthDriverT named audioSynth instead, written with AUDIO_SYNTH_DRIVER(name, priority, .kind = AUDIO_SYNTH_FM, AUDIO_SYNTH_MIDI, or AUDIO_SYNTH_WAVETABLE, .open = ..., .close = ..., then .write, .put, or the wavetable functions). open detects the hardware, fills AudioSynthDrvInfoT (description; for FM the voices and whether it is stereo; for a wavetable synthesizer its voices, memory, AUDIO_WT_* flags, and level, 0 when it is as loud as the digital sound or not known) and leaves it silent; close silences it. write(reg, value) sets an FM register (bank x AUDIO_FM_BANK_REGS + index) and must keep the index/data pair together (audioIrqOff / audioIrqRestore); put(byte) sends a MIDI byte, returning false when the port is not ready; a MIDI driver whose port receives also has get(&byte), the next byte the port has (false when none), which the MIDI input’s timer calls (mpu401.drv keeps what put finds waiting for get). A wavetable driver has upload(addr, frames, count, bits) (program time; addresses as audioWtMemAlloc gives them) and start, update, release, stop, and active for its voices (numbered from 0, as audio.lib hands them out); it plays a note as AudioWtVoiceT gives it, in its own units. write, put, and the voice functions run at interrupt time too (timer callbacks), so they follow the rules above and are pinned by the driver. A sound driver whose card also has a synthesizer (the GUS) points AudioDrvInfoT.synth at its own AudioSynthDriverT, which is opened before the others.
10.1.18. BASIC
src/include/basic/sound.bas (DECLARE LIBRARY "audio"): PlayWave(fileName), PlayWaveLoop(fileName), PlayTone(frequency, milliseconds, volume), PlayNoise(frequency, milliseconds, volume) return a voice number (0 on failure: SoundError$ says why); StopWave(voice), StopAllSounds, SoundPlaying(voice), SoundVolume(percent), SoundInfo$ (the device, e.g. "Sound Blaster 16 (DSP 4.05) at 220h, 22050 Hz, 16-bit stereo"). Volumes are percent. Each BASIC program plays through its own context, closed when it ends.
For a settings program (the Control Panel’s Sounds page): SoundEventCount, SoundEventLabel$(eventIdx), SoundEventKey$(eventIdx) (audioDeskLabel / audioDeskKey; events numbered from 0 in DvxSoundE order); SoundEventFile$(prefs, eventIdx) and SoundSetEventFile(prefs, eventIdx, fileName) (audioDeskFile / audioDeskSetFile); SoundEventsReload (audioDeskReload); SoundTestFile(fileName) (audioDeskPlayFile, a name alone found in the sound folders as the events' files are: a voice number, or 0 with SoundError$); SoundFolder$ (SHARED\SOUNDS, the sounds DVX ships; FileOpsKindDir$ and FileOpsKindList give the user’s too); SoundMasterVolume and SoundSetMasterVolume(percent) (audioGetMasterVolume / audioSetMasterVolume in percent); SoundDriverCount (reads audioDriverNames, at most AUDIO_DRIVERS_MAX) and SoundDriverName$(index); SoundDriverAuto$ (AUDIO_DRIVER_AUTO); SoundMidiCount and SoundMidiLabel$(index) (audioMidiChoices); SoundMidiInCount and SoundMidiInLabel$(index) (audioMidiInChoices); SoundModulesCount and SoundModulesLabel$(index) (audioModulesChoices); SoundSettingDriver$(prefs), SoundSettingMidi(prefs), SoundSettingMidiIn(prefs), SoundSettingModules(prefs), SoundSettingVolume(prefs), SoundSettingsStore(prefs, driver, midi, modules, volume), SoundSettingMidiInStore(prefs, midiIn), SoundSettingSpeakerPcm(prefs), and SoundSettingSpeakerPcmStore(prefs, onOff) (the audioSetting functions); SoundOutputRefresh (audioOutputRefresh). prefs is a prefs.bas handle (prefsBasHandle, dvxPrefs.h); a handle that is not open reads the defaults and stores nothing.
The rest of audio.h, in percent: PlayTriangle (audioTone with AUDIO_WAVE_TRIANGLE); SoundGetVolume (audioGetVolume); SoundCaps(field) (audioGetInfo: "dac", "synth", "tone", "running", "record" True / False; "voices" = voiceLimit, "rate", "bits", "channels", "recordsources"; any case, 0 for another field); SoundStats(field) (audioGetStats: "renders", "frames", "underruns", "clipped", "dropped", "playing"); SoundDriver$ (AudioInfoT.driver); SoundPlayEvent(eventIdx, wait) (dvxPlaySound / dvxPlaySoundWait, so the hook audioDeskPlay plays it; CONSTs SOUND_EVENT_* in DvxSoundE order).
Samples: SoundLoad(fileName) (audioSampleLoad), SoundLoadData(bytes AS BINARY STRING) (audioSampleLoadMem), and SoundCreate(pcm AS BINARY STRING, rate, bits, channels) (audioSampleCreate; frames = bytes / frame size, a trailing partial frame ignored) return a sound number; SoundFree (audioSampleFree), SoundLength (audioSampleInfo, in milliseconds), SoundRate, SoundBits, and SoundChannels (audioSampleInfo’s format), SoundPlay(sound, volume, pan, loopIt) (audioPlay; pan -100..100 scaled to AUDIO_PAN_LEFT..AUDIO_PAN_RIGHT). Voices: SoundSetVolume, SoundSetPan, SoundSetPitch(voice, percent) (25..400 percent of AUDIO_PITCH_NORMAL, clamped), and SoundSetFrequency(voice, hz) (the audioVoiceSet functions), SoundPause(voice) and SoundResume(voice) (audioVoicePause; a sound’s or a stream’s voice); the result is kept for SoundError$.
Ends: the program’s context has audioSetEndFn set to audioBasEnded, which keeps the last BAS_ENDED_MAX (64) ended voices; SoundEnded gives the program’s next one (0 for none) and SoundEndReason the AudioEndE of the one it gave last (CONSTs SOUND_END_*).
Note queues: NotesOpen(wave, volume) (audioNotesOpen; CONSTs SOUND_WAVE_* for AudioWaveE), NotesAdd(queue, hertz AS DOUBLE, milliseconds AS DOUBLE) (audioNotesAdd in millihertz and microseconds), NotesSetTone(queue, wave, volume) (audioNotesSetTone, the volume a percent of AUDIO_VOLUME_MAX), NotesQueued, NotesSpace, NotesVoice, NotesClear, NotesClose; numbered 1..64 like sounds.
Streams (push only): SoundStreamOpen(rate, bits, channels, bufferMs) (audioStreamOpen without a fill function), SoundStreamWrite(stream, pcm AS BINARY STRING) (audioStreamWrite of the whole frames; returns the bytes taken), SoundStreamSpace / SoundStreamQueued (frames), SoundStreamVoice, SoundStreamEnd (audioStreamEnd: no more will be written; the voice ends, SoundEnded tells, once what is held has played), SoundStreamFlush (audioStreamFlush), SoundStreamClose.
Recording, one per program (audioRecFile, or audioRecOpen into memory when fileName is ""): RecordStart(fileName, rate, bits, channels, inputSource) (True / False with SoundError$; 0 for the defaults), RecordRead$(maxBytes) AS BINARY STRING (audioRecRead of the whole frames that fit, into a buffer the next call reuses) and RecordQueued (audioRecQueued, in bytes), RecordStop (audioRecClose; True when a file was all written), RecordCancel (audioRecCancel; True when it was thrown away, False with AUDIO_ERR_ENDED for one a DOS program ended), RecordPause and RecordResume (audioRecPause, audioRecResume; True, or False with AUDIO_ERR_ARG when the program has no recording and AUDIO_ERR_ENDED for one a DOS program ended), Recording (True while it records, paused or not: False once a DOS program ended it, which stays the program’s until RecordStop, RecordCancel, or the next RecordStart), RecordLength (milliseconds recorded, written or waiting: the paused time is left out), RecordLevel (audioRecPeak), RecordLost, RecordRate, RecordBits, RecordChannels (audioRecFormat), with CONSTs RECORD_MIC, RECORD_LINE, RECORD_CD (AUDIO_REC_*) and SoundCaps "record" and "recordsources".
FM: FmInfo$(field) (audioFmGetInfo: "description", "voices", "free", "stereo", "owned" as text), FmAlloc, FmWrite(voice, reg, value) (True / False), FmFree, FmRawAcquire, FmRawWrite(reg, value), FmRawRelease, with CONSTs FM_* for the AUDIO_FM_* values and FM_BANK_REGS (AUDIO_FM_BANK_REGS).
Wavetable: WtInfo$(field) (audioWtGetInfo: "description", "voices", "free", "memory", "freememory" (the largest free block), "freetotal" (freeTotal: all that is free), "level", and the flags "envelopes", "lfos", "filter", "effects", "8bit", "rom" as text), WtMemAlloc(bytes, bits) (an address, -1 for no room), WtUpload(address, pcm AS BINARY STRING, bits) (16-bit mono samples), WtMemFree, WtAlloc (the voice’s note made plain: audioWtNoteInit), WtShape(voice, field, value) (an AudioWtVoiceT envelope, LFO, filter, or effects field by name — "volattack", "modlfofreq", "filterfc", "reverb", ...; int16_t fields clamped — kept in the voice’s note, with audioWtUpdate at once on a sounding note for AUDIO_WT_SET_FILTER, _EFFECTS, and _LFO fields), WtStart(voice, address, startFrame, endFrame, loopStart, loopEnd, loopMode, bits, pitch, attenuation, pan) (the voice’s note with the sample and these set; a negative address is AUDIO_WT_ADDR_ROM's, CONST WT_ADDR_ROM; pitch in cents, attenuation in centibels, pan -100..100 scaled to AUDIO_WT_PAN_MAX), WtSetPitch, WtSetAttenuation, WtSetPan (audioWtUpdate of the note kept for the voice; True / False), WtRelease, WtStop, WtActive, WtFree.
The MIDI port, declared in music.bas: MidiPortInfo$(field) (audioMidiGetInfo: "description", "present", "owned", "input", "inputowned"), MidiAcquire, MidiPut(byteValue) (False on AUDIO_ERR_BUSY: send it again), MidiRelease; its input: MidiInOpen (True / False with SoundError$), MidiInClose, MidiInMessage (audioMidiInRead: the message packed as status + data1 * 256 + data2 * 65536, AUDIO_MIDI_PACKED_*, or MIDI_NONE, -1), MidiInTime (the ms of the message MidiInMessage gave last), MidiInClock (audioMidiInClock), MidiInLost, with CONSTs MIDI_NOTE_OFF to MIDI_PITCH_BEND, MIDI_KIND_MASK, and MIDI_CHANNEL_MASK.
CONSTs SOUND_PAN_*, SOUND_PITCH_* (percent), SOUND_RATE_* (AUDIO_RATE_*), and SOUND_STREAM_MS_* (AUDIO_STREAM_MS_*).
Sound, stream, and note queue numbers are 1..64 per kind, valid only for the program that got them; audioClose of a BASIC context forgets its numbers and ended voices (audioBasForget) as it frees the samples, streams, and queues. BINARY STRING parameters arrive as a pointer and a byte count (two C parameters; see the DECLARE LIBRARY rules in the BASIC reference).
10.2. Music Library
Music for DVX programs on whatever sound hardware the computer has: tracker modules (MOD, S3M, XM, IT), Standard MIDI Files (types 0, 1, and 2; a type 2 file’s sequences play one after another), WAV and VOC sound files, and live MIDI a program sends itself. Every music belongs to the program that loaded it and is stopped and freed when the program ends, however it ends; any number of programs may play music at the same time.
Header: music/music.h. Loaded as: bin/libs/kpunch/music/music.lib (needs audio.lib); the tracker module player (libxmp-lite) is bin/libs/kpunch/music/players/xmp.drv, which music.lib loads when a module is opened and lets go a minute after the last one closes; the General MIDI instrument bank for FM is bin/libs/kpunch/music/genmidi.op2, and the General MIDI SoundFont for wavetable music is an add-on (SHARED\BANKS\KPUNCH\DVXGM.SF2).
10.2.1. Playing a File
MusicT *tune = NULL;
int32_t rc = musicLoad("THEME.MID", &tune); // or musicLoadMem(data, size, &tune)
if (rc != MUSIC_OK) {
dvxLog("%s", musicErrorText(rc));
} else {
musicSetEndFn(tune, onTuneEnd, NULL);
musicPlay(tune, false); // true: loop until stopped
}
musicLoad and musicLoadMem tell the kind by the contents: a WAV or VOC sound file (MUSIC_KIND_SOUND) or a MIDI file (or a RIFF RMID file around one) by its header, anything else is offered to the module player. A WAV or VOC file loaded by its path is read from the disk as it plays (only its header is read at the load), so a long recording needs no memory; a WAV or VOC given in memory is decoded into memory (audioDecode). Errors: MUSIC_ERR_OPEN (unreadable file), MUSIC_ERR_FORMAT (not music DVX plays), MUSIC_ERR_UNSUPPORTED (a sound file that is compressed or not 8- or 16-bit; its text is audio.lib’s), MUSIC_ERR_CORRUPT, MUSIC_ERR_NO_MEMORY, MUSIC_ERR_NO_DEVICE (no sound device could start), MUSIC_ERR_BANK (MIDI with no usable instrument bank and no MPU-401 port). Nothing plays until musicPlay(music, loop), which plays from the current position (the start after a load or a stop; a music that played to its end starts over). musicPause / musicResume, musicStop (back to the start), musicIsPlaying, musicSetVolume (0..MUSIC_VOLUME_MAX, per music; the master volume applies too - on the FM chip and the MPU-401 port as it was when the music started or its volume was last set), musicGetPosition / musicSetPosition (milliseconds), musicGetInfo (kind, where it plays, a description of the device, title, length, position, state; the title is a module’s own, a MIDI file’s sequence name (the first track’s name, control characters as spaces), and none for a sound), and musicFree complete the set. musicSetEndFn(music, fn, userData) asks for a call when a music that does not loop plays to its end; it comes in the shell’s idle time as the program that owns the music, never from an interrupt.
musicLoadMacro(macro, &music) makes a MIDI music from a music macro string (the language PLAY takes, below): its notes play on the General MIDI instruments its I commands name, the piano for notes before any I or after I0, and it is then played, paused, and freed like a MIDI file (MUSIC_ERR_MACRO for a mistake in the string). musicSetBank(music, bank) plays one MIDI music on another instrument bank than DVX.INI’s choice: bank names it as midiBank and soundFont do ("" the standard OP2 bank, NULL DVX.INI’s choices again). A SoundFont (.SF2 or .SBK) or an UltraSound’s ULTRASND.INI is for wavetable music (the FM bank stays DVX.INI’s), any other bank for the FM synthesizers. The bank is read at once, so a missing or damaged one is MUSIC_ERR_BANK there and then; it must come before the music’s first musicPlay (MUSIC_ERR_ARG for a module, live MIDI, or a music that has played). Control Panel’s Instruments Test is musicLoadMacro and musicSetBank.
Setting the position of a MIDI file sends the instruments and controllers set before that point (no notes). A module goes to the start of the pattern that holds the time; a sound goes to the frame.
10.2.2. Where Music Plays
A module plays on the wavetable synthesizer’s own voices (a Gravis UltraSound’s, an AWE32’s or AWE64’s) when there is one and no other music plays on it (one music at a time, MIDI or a module; a stopped one gives it up): its samples go into the chip’s memory and libxmp’s voices are played on the chip’s, nothing mixed in software (MUSIC_OUT_WAVE; see Modules). Otherwise libxmp-lite renders it into a stream of the sound device (16-bit stereo at the device’s rate, 400 ms of buffer, linear interpolation), so it plays on any device that plays sampled sound (MUSIC_OUT_STREAM): with DVX.INI [audio] modules = software (audioModulesChoices; the Control Panel’s Sounds page), when the module has more channels than the chip has voices or a stereo sample, or when its samples do not fit in the chip’s memory (the SoundFont kept there for MIDI gives way first).
A sound always plays on a stream (MUSIC_OUT_STREAM) at its own rate and channels, 16-bit, with the same 400 ms of buffer; the mixer converts it to the device’s rate. A pause, a seek, or a stop of any music on a stream is heard at once: the stream’s voice is held where it is (audioVoicePause) and, for a seek or a stop, what it holds is dropped (audioStreamFlush).
MIDI goes to the best synthesizer there is, decided at the first musicPlay (or musicMidiOpen), with DVX.INI [audio] midi:
| midi | MIDI plays on |
|---|---|
auto |
a wavetable synthesizer (a Gravis UltraSound, a Sound Blaster AWE32 or AWE64) when there is one, no other music is using it, and its SoundFont loads; else the FM chip (OPL2 / OPL3) when there is one and no program has taken the whole chip; else the software synthesizer |
mpu401 |
the MPU-401 port (mpuPort, default 330h) when it was found and no other music is using it; else as auto |
fm |
the FM chip when there is one and it is free; else the software synthesizer |
software |
the software synthesizer |
softwave |
the SoundFont software synthesizer (below); else the software synthesizer |
On the FM chip and the MPU-401 port the song is played by the timer service (500 times a second), so it keeps time however busy the programs are. On the FM chip every note takes a voice from audio.lib’s shared pool; when none is free the note plays on the software synthesizer instead, which then runs beside the chip (its stream is always open for that). The software synthesizer runs in the stream’s fill function (the shell’s idle time), 64 frames between event checks, 150 ms ahead of what is heard; a program that keeps the desktop busy every frame should call audioPump once a frame, as for any stream.
10.2.3. General MIDI on FM
Instruments come from an OP2 bank (the DMX "GENMIDI" format: 128 melodic instruments and 47 percussion instruments for notes 35 to 81, each one or two two-operator voices, with a note offset, a fixed note for percussion, and a detune for the second voice). DVX ships Freedoom’s GENMIDI bank (see Licenses below); DVX.INI [audio] midiBank (MUSIC_INI_BANK) names another OP2 file instead: a bank in SHARED\BANKS or the user’s BANKS folder by its name (an add-on package’s as VENDOR\NAME), or any OP2 file by its path from the DVX folder, for example a bank made with an OPL editor. DVX also ships DMXOPL and DMXOPL3 (MIT, by ConSiGno and Sneakernets) in SHARED\BANKS, made to sound like a Roland Sound Canvas. Control Panel’s Sounds page lists the banks to choose from. A bank that is not there falls back to the bundled one (MUSIC_BANK_DEFAULT). DVX.INI’s choice is read as each MIDI music starts, so a new choice reaches the next one; a music keeps the bank it started with, and a bank is freed with the last music playing on it.
What is played: note on / off, velocity, program change, channel volume (CC7), expression (CC11), pan (CC10: left, both, or right on an OPL3 and the software synthesizer), sustain pedal (CC64), pitch bend with the bend range from RPN 0 (default 2 semitones), all notes off (CC123, CC120), reset controllers (CC121), and General MIDI System On (a reset). Channel 10 plays percussion. Loudness is velocity x volume x expression x the music’s volume on a 40 log10 curve, added as attenuation to the voice’s level. OP2 banks are tuned for DMX, which sounds note n where MIDI has note n + 12, so notes are played an octave up from the bank’s offsets. Not played: modulation (CC1), aftertouch, the FM chip’s own rhythm mode, four-operator voices.
10.2.4. The Software Synthesizer
When there is no FM chip (or it is busy), MIDI plays on DVX’s own software FM synthesizer: an integer two-operator FM chip modeled on the OPL2 (the same log-sine and exponential tables, waveforms 0 to 3, feedback, the chip’s envelope rates and key scaling, key scale level, tremolo, and vibrato) with 24 voices, rendering at the device’s rate into a stream. It is driven with the same bank and the same register values as the chip, so music sounds alike on both. The host tests compare it with emu8950, an accurate OPL2 emulator, for several patches: pitch, loudness over time, and harmonics agree closely. Cost on a 486: roughly 1 to 2 percent of a 486DX2-66 per sounding voice at 22,050 Hz.
10.2.5. SoundFonts on a Wavetable Synthesizer
A wavetable synthesizer (audio.lib’s gus and guswt drivers for a Gravis UltraSound, awe for the EMU8000 of a Sound Blaster AWE32 or AWE64) plays recorded instruments from its own memory. Its instruments come from a SoundFont, DVX.INI [audio] soundFont (MUSIC_INI_SOUND_FONT), named as midiBank names an OP2 bank; not set, the standard one (MUSIC_SOUND_FONT_DEFAULT, KPUNCH\DVXGM.SF2: DVX’s General MIDI SoundFont add-on, made from FluidR3_GM by mksf, about 3.4 MB). SoundFont 2 files are read in full; SoundFont 1 (.SBK, the AWE32’s own) as far as it is known (it has no public specification). soundFont may also name a Gravis UltraSound’s ULTRASND.INI by its path, which plays that folder’s .PAT patches as instruments; and where the standard SoundFont is not installed, the patches in the folder ULTRADIR names play (musicPatchSetPath), else the AWE’s own bank for its sample ROM (musicRomBankPath: SFBANK\SYNTHGM.SF2 or SYNTHGM.SBK in the folder SOUND names, as Creative’s drivers installed it). Control Panel’s Sounds page lists all of these.
A song loads only the samples its notes play (the bank selects, programs, and notes are looked at first), each with the frames a chip’s interpolation reads after it, into memory the synthesizer gives every program a share of; what a song loaded stays for the next while it fits, and room is made by giving up the samples used longest ago. When the samples still do not fit (a size they cannot fit at, even in the whole of the synthesizer’s memory, is not tried) they are all loaded again smaller: 8-bit where the chip plays it, then at half the rate, then a quarter; at the least, the ones that do not fit are left out. Notes the bank lacks, or whose samples were left out, play on the FM chip or the software synthesizer, as do the notes beyond the synthesizer’s voices. One music plays on the wavetable synthesizer at a time (another meanwhile plays on FM); its samples are kept 60 seconds after the last music (MUSIC_FONT_KEEP_SEC), and the SoundFont itself (its headers, a GUS patch set’s files) for the whole session, so a later song does not read them again. Live MIDI loads a program’s samples once it is chosen, one at a time in the idle time after (a whole instrument at once would hold DVX up), at the best quality that fits beside the samples already loaded; until they are in, its notes play on the FM chip. A SoundFont made for an AWE’s General MIDI ROM (ROM samples) plays from the card’s ROM with nothing loaded; on any other synthesizer its notes go to FM.
The AWE runs the SoundFont’s envelopes, LFOs, filter, and reverb and chorus sends itself; on the GUS the library runs the envelopes and LFOs (its volume and pitch changed as the note goes on), without a filter or effects.
10.2.6. The SoundFont Software Synthesizer
With DVX.INI [audio] midi = softwave, MIDI plays from the SoundFont in software on any device that plays sampled sound: the song’s samples are read into memory at their own rates and mixed into the music’s stream (linear interpolation, the envelopes and LFOs as on the GUS, no filter or effects), with the software FM synthesizer beside it for the notes the bank lacks. It needs the memory for the song’s samples (a General MIDI song of ten instruments and a drum kit about 360 KB of DVXGM’s) and more CPU time than FM.
10.2.7. The MPU-401 Port
With DVX.INI [audio] midi = mpu401, MIDI goes out of the MPU-401 port (audio.lib’s mpu401 driver) to an external synthesizer, one music at a time (a second MIDI music meanwhile plays on the FM chip or the software synthesizer). Bytes are queued and sent by the timer as fast as the port takes them, with a 40 ms pause after every system exclusive message (first-generation MT-32s lose data without it). The music’s volume scales every channel volume (CC7) sent. DVX.INI [audio] mpuMode says what is on the port:
- gm
-
A General MIDI synthesizer (Roland SC-55 and the like): the music as it is, after a General MIDI System On message.
- mt32
-
A Roland MT-32 (or CM-32L, LAPC-I) playing General MIDI music: the melodic channels move to the MT-32’s eight parts (MIDI channels 2 to 9, in the order they are first used; a ninth channel shares the last part), percussion stays on channel 10, programs go through a General MIDI to MT-32 timbre table (our own nearest-sound choice), pan is mirrored (the MT-32 pans the other way), the bend range is set to 2 semitones by system exclusive messages at the start (and RPN 0 changes it the same way, since the MT-32 has no RPNs), and what it does not understand (other RPNs and NRPNs, bank select, reverb and chorus depth, aftertouch, system exclusive messages that are not Roland’s) is left out.
- raw
-
Anything: the music exactly as it is, nothing added (for music written for an MT-32, with its own set-up messages).
Stopping, pausing, or freeing a music sends sustain off and all notes off on every channel the synthesizer hears.
10.2.8. Live MIDI
MusicT *keys = NULL;
musicMidiOpen(&keys); // plays at once
musicMidiProgram(keys, 0, 73); // flute on channel 0
musicMidiNoteOn(keys, 0, 60, 100); // middle C
musicMidiNoteOff(keys, 0, 60);
musicMidiOpen opens a music with no file that plays at once, on the same synthesizer a MIDI file would use. musicMidiNoteOn, musicMidiNoteOff, musicMidiProgram, musicMidiControl, and musicMidiPitchBend (-8192..8191) send channel messages (channels 0 to 15, data 0 to 127) to it, or to a MIDI file that is playing (for dynamic game scores); MUSIC_ERR_ARG for a module or a value out of range. musicMidiSend(music, status, data1, data2) sends any channel message as MIDI input brings it (audioMidiInRead: status 80h..EFh with the channel in it; a data byte the message does not use is ignored), so what a keyboard plays sounds as it comes (MIDI thru).
10.2.9. Recording MIDI
MusicMidiRecordT *take = NULL;
AudioMidiMsgT msg;
musicMidiRecordNew(&take);
while (audioMidiInRead(audio, &msg)) { // each tick, while recording
musicMidiSend(keys, msg.status, msg.data1, msg.data2);
musicMidiRecordAdd(take, msg.ms, msg.status, msg.data1, msg.data2);
}
musicMidiRecordSave(take, "SONG.MID");
musicMidiRecordFree(take);
A MIDI recording keeps channel messages with their times (musicMidiRecordAdd(rec, ms, status, data1, data2), ms from the recording’s start; a time before the last message’s counts as the last’s; MUSIC_ERR_ARG for anything but a channel message) and musicMidiRecordSave(rec, path) writes them as a Standard MIDI File: type 0, one track of 1,000 ticks a quarter note at 60 quarter notes a minute, so a tick is a millisecond. A note still held at the end is let go there, and a sustain pedal still down let up, so the file never leaves a note sounding. musicMidiRecordPause(rec, ms) pauses the recording at ms and musicMidiRecordResume(rec, ms) goes on at ms (the clock musicMidiRecordAdd is given, as AudioMidiMsgT.ms or audioMidiInClock gives it): a message timed in between is not kept (MUSIC_OK all the same), and a later one is moved earlier by the time paused, so the recording goes on with no gap; the notes held when the pause begins are let go there, and a sustain pedal down let up, so nothing hangs on across it. musicMidiRecordTime(rec, ms) is the recording’s own time at ms (ms less the time paused before it; where the pause began, while it is paused): a clock to show while recording. Pausing a paused recording, or resuming one not paused, does nothing. MUSIC_ERR_WRITE when the file cannot be written. The file is written all or nothing (platformWriteFile: into a scratch file beside path, then swapped in), so a file already at path stays as it was when the new one cannot all be written. musicMidiRecordCount and musicMidiRecordLength (the last message’s time) say what it holds; musicMidiRecordFree frees it, and a program’s recordings are freed when it ends. A recording freed without a save writes nothing, so a take nobody keeps is thrown away by freeing it: no file is touched (the Sound Recorder’s No does this). musicLoad plays the file. The music macros (below) are written into MIDI files by the same code.
10.2.10. Modules
MOD (ProTracker and compatibles), S3M, XM, and IT through libxmp-lite 4.7.3 (thirdparty/libxmp-lite with DVX’s patches, listed in its DVX-VERSION.md; formats only, no depackers or ProWizard). Stereo separation is 50 percent (softer than the Amiga’s hard left and right). The whole module is held in memory. libxmp works out pitches with floating point, so it plays modules in the shell’s idle time, never at interrupt time; on a 486SX (no maths coprocessor) that goes through floating point emulation and is slow. On a stream libxmp mixes every channel in software (linear interpolation, three multiplies a channel a frame).
On a wavetable synthesizer (musicModHw.c) libxmp mixes nothing: DVX’s hardware voice patch has it report each of its voices as every tick starts (the sample, where it is, its rate, volume, pan, and the loop it is in), and only move them on. Those ticks are made up to 400 ms ahead in the idle time, as the synthesizer’s notes, and the music timer plays them on time (500 times a second: a note starts within 2 ms of its time). A voice starts on the chip where libxmp starts or moves it (a note, a sample offset, a retrigger, another sample or loop); otherwise its pitch, volume, and pan follow libxmp’s each tick, and the chip’s own interpolation plays it. The samples are stored as they are (an 8-bit one 8-bit where the chip plays those, as a GUS does), else all 8-bit; a way of storing them that cannot fit in the synthesizer’s free memory is not tried (nothing is uploaded for nothing), and a module that fits in neither plays mixed in software. A big module loads giving way to DVX’s other tasks between its samples (a DVX patch to libxmp, 0002-load-hook), and a file of no music kind is refused by its first bytes, without being read whole. What libxmp allocates while a module loads is noted (another patch, 0003-alloc-hooks, sends libxmp’s allocations through musicXmp.c), so a program ended from the Task Manager while its module loads has all of it freed: the module part made, and libxmp’s own buffers for the load. A WAV or VOC file plays as it is read. The chips loop only forward, so a ping-pong loop is stored unrolled: its way back after its end, each frame where libxmp reads it (an Impulse Tracker module’s way back a frame shorter, as Impulse Tracker plays it). What the chips cannot do plays near enough: a ping-pong sustain loop goes forward, a sample played backwards with no loop goes forward, and Impulse Tracker’s filters are not heard; a voice the chip has none free for (a program holds the rest) is not heard. A voice at full volume plays 8 dB down, with the chip’s level (AudioWtInfoT) taken off too, so a module is about as loud as libxmp mixes it. A pause stops the voices, and the play goes on from the tick that was playing; musicGetPosition is the tick being heard.
Measured on an emulated 486DX2-66 at 22,050 Hz, a 4-channel MOD with all four channels sounding takes about 49 percent of the CPU mixed in software and about 14 percent on a Gravis UltraSound’s voices, most of that libxmp’s own work each tick (about 1.3 ms of the 20).
10.2.11. Music Macros
MusicMmlT *tune = NULL;
musicMmlOpen(&tune);
musicMmlPlay(tune, "MB T140 O3 L8 CDEC CDEC EFG4 EFG4");
A macro queue plays tunes written in QBasic’s music macro language (the commands are listed in music.h and in the BASIC language reference: notes A-G with sharps and flats, N, O, > and <, L, P, dots, T, MN / ML / MS, MF / MB, and QB64’s V (volume) and @ (waveform: 1 square, 3 triangle, 5 noise)). musicMmlPlay parses the whole string first; a mistake anywhere returns MUSIC_ERR_MACRO and queues nothing. The settings last from one string to the next. musicMmlTone queues a square-wave tone of milliHz thousandths of a hertz (0: silence) for us microseconds (QBasic’s SOUND). musicMmlQueued counts the notes not yet played, musicMmlStop silences the queue, musicMmlBusy says whether a caller that follows QBasic should still wait (foreground mode: until everything has played; background: while more than MUSIC_MML_BACKGROUND_MAX notes wait) and moves the queue along. A queue belongs to the program that opened it and is freed when that program ends.
Timing is QBasic’s: a whole note is four beats of 60 / T seconds, each dot adds half again, and a note sounds for 7/8 (MN), all (ML), or 3/4 (MS) of its length. Octave 3 starts at middle C; octave 3’s A is 440 Hz. The notes play on an audio.lib note queue, each to the exact sample in its own waveform and volume (audioNotesSetTone; on the PC speaker as square tones, V0 silent); V also scales an instrument’s velocity. DVX’s own I command (I1 to I128) plays the notes that follow on that General MIDI instrument: each run of such notes becomes a small MIDI file that plays like any MIDI music (on the synthesizer DVX.INI [audio] midi chooses); I0 returns to tones. Runs play one after the other; when the instruments cannot play (no instrument bank, no device) the run plays as tones.
10.2.12. Several Programs at Once
Every music plays through one audio context of the library’s own; audio.lib mixes all streams, so modules and software MIDI of any number of programs play together. FM voices are shared with every program’s tones and FM music; the MPU-401 port serves one music, and so does the wavetable synthesizer (MIDI or a module). When a program ends, its musics stop and are freed and their FM voices and the port are given back; the others go on.
10.2.13. BASIC
src/include/basic/music.bas (DECLARE LIBRARY "music"): MusicLoad(fileName), MusicLoadData(bytes AS BINARY STRING) (musicLoadMem), and MusicMidiOpen() return a music number (0 on failure: MusicError$ says why); MusicPlay(music, loopIt), MusicStop, MusicPause, MusicResume, MusicPlaying, MusicEnded (True once after the music played to its end: each number’s musicSetEndFn sets a flag that MusicPlay and MusicEnded clear), MusicVolume(music, percent), MusicPosition, MusicLength, MusicSeek(music, ms), MusicFree; live MIDI MusicNoteOn(music, channel, note, velocity), MusicNoteOff, MusicProgram, MusicControl, MusicPitchBend with channels 1 to 16 (10 for drums), and MusicMidiSend(music, midiMsg) (musicMidiSend of a message packed as MidiInMessage gives it, AUDIO_MIDI_PACKED_*). MIDI recordings: MidiRecordNew (a recording number, 0 when all 8 are in use), MidiRecordAdd(recording, milliseconds, midiMsg), MidiRecordCount, MidiRecordLength, MidiRecordPause(recording, milliseconds), MidiRecordResume(recording, milliseconds), MidiRecordTime(recording, milliseconds) (musicMidiRecordPause, Resume, and Time; a time before 0 counts as 0), MidiRecordSave(recording, fileName) (True / False with MusicError$), MidiRecordFree. A number only works for the program that got it. MusicLoadMacro(macro) (musicLoadMacro, a music number) and MusicSetBank(music, bank) (musicSetBank, "" the standard bank, a SoundFont or an ULTRASND.INI for wavetable music; MusicError$ says when it is missing or damaged); MusicPatchSet$ and MusicRomBank$ (musicPatchSetPath, musicRomBankPath: "" when there is none). MusicGetVolume(music) (musicGetVolume in percent) and MusicInfo$(music, field) (musicGetInfo: "title", "output", "kind" = "module" / "midi" / "live" / "sound" for MusicKindE, "where" = "" / "stream" / "mpu401" / "fm" / "software" / "wave" / "softwave" for MusicOutputE, "paused" and "looping" as "-1" / "0"; any case, "" for another field). music.bas also declares the raw MIDI port calls of audio.lib (MidiPortInfo$, MidiAcquire, MidiPut, MidiRelease) and its MIDI input (MidiInOpen, MidiInClose, MidiInMessage, MidiInTime, MidiInClock, MidiInLost, and the MIDI_* CONSTs); see the sound library.
The BASIC runtime itself calls musicBasBeep, musicBasSound(hz, ticks), musicBasPlay(macro), musicBasPlayCount, and musicBasBusy for the statements BEEP, SOUND, and PLAY and the PLAY(n) function; each BASIC program has its own macro queue. QBasic’s X command and "=" numbers (given with VARPTR$) are filled in by the BASIC runtime before musicBasPlay is called, so the macro language itself has neither. SOUND’s duration is in clock ticks (18.2 a second) and 0 stops the queue; BEEP is 800 Hz for a quarter second.
10.2.14. Licenses
libxmp-lite (Extended Module Player Lite), (C) 1996-2026 Claudio Matsuoka and Hipolito Carraro Jr, MIT license:
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.
The DVX General MIDI SoundFont add-on (DVXGM.SF2) is made from FluidR3_GM by Frank Wen (MIT license); its notice is installed beside it (SHARED\BANKS\KPUNCH\DVXGM.TXT).
The DMXOPL 1.11 instrument bank is by ConSiGno, and DMXOPL3 by Sneakernets (MIT license); each one’s license and credits are installed beside it (SHARED\BANKS\DMXOPL.TXT and DMXOPL3.TXT).
The GENMIDI instrument bank is from Freedoom 0.13.0, Copyright (C) 2001-2024 Contributors to the Freedoom project. All rights reserved. BSD 3-clause license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the Freedoom project nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
10.3. Joystick Library
Game controllers for DVX programs behind one API, whatever the hardware: the devices the drivers found, axes calibrated to -32768..32767 with a dead zone round the center, buttons, hats, read when the program wants (polled) or delivered as events. A program’s handles close when it ends, however it ends. Calibration and the other settings live in DVX.INI [joystick]; the Control Panel’s Game Controllers page sets them.
Header: joystick/joystick.h
Loaded as: bin/libs/kpunch/joystick/joystick.lib, drivers in bin/libs/kpunch/joystick/drivers/*.drv (joyport.drv, joykeys.drv), loaded only when a program first asks for devices.
10.3.1. Reading a Joystick
if (joyCount() > 0) {
int32_t stick = joyOpen(ctx, 0); // device 0, owned by the calling program
JoyStateT st;
if (joyRead(stick, &st) && st.connected) {
shipX += st.axes[0] / 4096; // -8..7
firing = (st.buttons & 1) != 0;
}
}
joyCount() is the number of devices (the first call of any joystick function finds them); joyGetInfo(device, &info) describes one: name, id (the driver’s name and unit number, "gameport0", which prefixes the device’s DVX.INI keys), axisCount, buttonCount, hatCount, axisPresent (bit n set when axis n answers; a missing axis reads 0), and caps (JOY_CAP_CALIBRATE for analog axes, JOY_CAP_KEYBOARD for the keyboard joystick).
joyOpen(ctx, device) returns a handle owned by ctx->currentAppId, or -1. joyOpenShared(ctx, device) returns the calling program’s shared handle on the device, opening it the first time (for code with no place to keep a handle; the BASIC functions use it). joyClose closes a handle; a program’s handles are closed for it when it ends.
joyRead(handle, &st) fills a JoyStateT: axes[] (JOY_AXIS_MIN..JOY_AXIS_MAX, 0 inside the dead zone), hats[] (JOY_HAT_CENTERED or degrees clockwise from up), buttons (bit n = button n), and connected (false when the device stopped answering; everything then reads neutral). A button that went down and up again since the handle last looked reads as down once, so a quick tap between two reads is not lost. joyButtonPressed(handle, button) asks the same about one button. joyButtonWentDown(handle, button) only asks whether the button went down since the last time this function asked about it (a press counter of its own, apart from joyRead’s).
The keyboard joystick (JOY_CAP_KEYBOARD) reads neutral for a handle whose program has no window with the focus, so keys typed into another program do not steer the game.
10.3.2. Events
joySetEventFn(handle, fn, userData) delivers the device’s changes from now on: JoyEventAxisE when an axis moved by at least JOY_EVENT_AXIS_STEP or reached the center or an end, JoyEventButtonDownE / JoyEventButtonUpE (a tap between two polls gives both), JoyEventHatE. fn runs in program context as the handle’s program (ctx->currentAppId is its id), so DVX calls are fine. Events are delivered by joyPump, which the shell calls on every idle frame; a program with its own main loop that repaints every frame (so the shell is never idle) calls joyPump itself or reads with joyRead. joyPump is not reentrant: an event function that runs a modal dialog gets its remaining events after it returns. A NULL fn stops the events.
10.3.3. Polling and CPU Cost
While at least one handle is open, a timer-service callback marks a poll due [joystick] pollHz times a second (JOY_POLL_HZ_DEFAULT 60, JOY_POLL_HZ_MIN 10 to JOY_POLL_HZ_MAX 200) and runs the drivers' tick hooks (the game port latches button presses there). The poll itself runs in program context, the next time a program reads (joyRead, joyButtonPressed, joyGetRaw) or the shell is idle, so however often a program reads there are at most pollHz polls a second. With no handle open nothing is polled and the timer is removed.
A game port poll waits for the slowest connected axis to run out: about 0.6 ms with the stick centered, up to about 1.2 ms at an end. At 60 polls a second that is about 4 to 7 percent of the processor’s time on any machine, whatever its speed, while a program has a joystick open; the timer interrupt’s part (one port read) is negligible. The keyboard joystick costs nothing measurable.
10.3.4. Calibration and Settings
joyGetRaw(device, &raw) returns the last raw poll (driver units: microseconds for the game port). joyGetCalibration / joySetCalibration get and set an axis’s JoyAxisCalT (min, center, max in raw units; min < center < max): min..center maps to -32768..0, center..max to 0..32767, clamped. A NULL calibration forgets it. An axis never calibrated ranges automatically: centered on the reading taken when the device was found, starting at center / 8 .. center * 2 and widening as the stick moves. joyGetDeadZone / joySetDeadZone get and set the device’s dead zone in percent (0..JOY_DEADZONE_MAX, default JOY_DEADZONE_DEFAULT 8). joyAxisScale(cal, raw) and joyDeadZoneApply(value, percent) are the two steps as plain functions.
Settings changed through the library take effect at once and reach DVX.INI only through joySettingsStore(prefs) (the caller saves the file); joySettingsLoad(prefs) replaces them all, e.g. to undo. joySettingGet / joySettingSet read and write single values. The [joystick] keys:
| Key | Value |
|---|---|
pollHz |
Polls a second (10 to 200, default 60). |
fallback |
auto (default): the keyboard joystick only when no other device is found; always; never. |
gameport.mode |
twoSticks (default) or fourAxes: one joystick using all four axes and buttons (flight sticks with a throttle or rudder). |
keyboard.up ... keyboard.right, keyboard.button1 ... keyboard.button4 |
Key names (joyKeyName: Up, Down, Left, Right, LCtrl, RCtrl, LShift, RShift, LAlt, RAlt, Space, Enter, Tab, Backspace, Insert, Delete, Home, End, PgUp, PgDn, Keypad0 to Keypad9, A to Z, 0 to 9). Defaults: the arrows, Left Ctrl, Space, Left Shift, Z. |
<id>.axis<n> |
min,center,max: axis n of the device with that id, e.g. gameport0.axis0 = 40,560,1150. |
<id>.deadZone |
The device’s dead zone in percent. |
Two settings are offered as lists: joyChoices(which, &count) returns the choices of JoyChoiceGamePortE (gameport.mode: "Two joysticks", "One joystick with 4 axes") or JoyChoiceFallbackE (fallback: "When no joystick is found", "Always", "Never") in list order, each a PrefsChoiceT (dvxPrefs.h) with its label for people and the name stored; joyChoiceGet(which) is the index of the current one (the default for a missing or unknown value) and joyChoiceSet(which, index) stores one. The keyboard joystick’s keys go by slot (0 to JOY_KBD_SLOT_COUNT - 1 in JOY_KBD_SLOT_NAMES order: up, down, left, right, button1 to button4): joyKbdSlotGet(slot) is the joyKeyName index of the slot’s key (its default key when the setting names no known key), joyKbdSlotSet(slot, keyIndex) stores one; the keyboard driver reads its keys through joyKbdSlotGet. joyKeyIndex(name) finds a key name’s index (joyKeyFind its raw code). The Control Panel’s Game Controllers page uses these, so the stored names and the defaults live only in the library.
joyRescan() looks for devices again (a joystick plugged in later, a changed gameport.mode); it works only while no handle is open and returns -1 otherwise. joyRescanApp(appId) closes every handle of that program first (joyAppCleanup) and then rescans, for a program that holds handles itself (the BASIC JoyRescan; the Control Panel closes its one handle and calls joyRescan).
10.3.5. The Game Port Driver
joyport.drv drives the standard PC game port at I/O port 201h. Writing to the port starts four one-shot timers, one per axis; each runs for a time proportional to its axis’s resistance (about 24 us plus 11 us per kilohm). The driver times them against the platform’s microsecond clock (platformMicros) with interrupts left enabled, so the port never holds up the timer, the sound card, or the mouse: each sample reads the port and the clock, and an axis whose fall can only be placed in a window wider than JOYPORT_GAP_US (40 us; an interrupt ran in between) keeps its previous value for that poll. A measurement gives up after JOYPORT_TIMEOUT_US (3 ms). At the probe an axis that does not run out, or runs out in under 10 us (some cards read 0 for an unconnected axis), is missing. At run time an axis that times out three polls in a row is left out of the measurement, so an unplugged stick does not cost the timeout every poll, and is tried again every 60 polls; a stick all of whose axes time out reads as not connected. Buttons A1, A2, B1, B2 are read at every poll and sampled by the timer interrupt, so short presses are latched.
In the default mode the port makes up to two joysticks (A with axes 0-1 and buttons 0-1, B with axes 2-3 and buttons 2-3; either may be missing); in the four-axis mode one joystick with four axes and four buttons.
10.3.6. The Keyboard Joystick
joykeys.drv is a fallback driver: a joystick made of keys (two axes: full deflection while a key is held, the center with both or neither; four buttons), read from the held-key table, so games work without joystick hardware. It is listed only when no other device is found, unless [joystick] fallback says always or never.
10.3.7. Writing a Driver
A driver is a driver module (see dvxDrv.h in the API reference): a file <name>.drv in bin/libs/kpunch/joystick/drivers, built by the joystick Makefile from each drivers/<name>/ folder, that exports one JoyDriverT named joyDriver, written with JOY_DRIVER(name, priority, .flags = ..., .probe = ..., .info = ..., .poll = ..., .tick = ..., .settingsChanged = ...). Nothing lists drivers and nothing loads them at startup: the first time a program asks for devices (the GUI and the timer service are running by then), and at every joyRescan, the library loads them all, probes them from the highest priority down (JOY_PRIORITY_PORT, ..., JOY_PRIORITY_KEYBOARD), probes the fallback drivers only when the fallback setting asks for them, and unloads every driver that found no device. The descriptor carries DVX_ABI_VERSION; a driver built for another version, one without probe, info, or poll, or one whose name a higher priority driver already has is skipped and logged.
| Member | Meaning |
|---|---|
hdr.name |
Lower case, no blanks ("gameport"); the prefix of the device ids and of the driver’s own [joystick] keys. |
hdr.priority |
Probing order (JOY_PRIORITY_*); devices are numbered in that order. |
flags |
JOY_DRIVER_FALLBACK for a stand-in like the keyboard joystick. |
probe() |
Find the units; return how many. Called right after the driver is loaded. |
info(unit, out) |
Describe one unit (name, counts, axisPresent, caps); the library fills in id. |
poll(raw, units) |
Read every unit now, in program context: raw[0..units-1]. Set axisValid for each axis measured (the others keep their last value), buttons held now, pressed for buttons that went down since the last poll, hats (JOY_HAT_CENTERED when not pushed), and connected. Axes are raw units with JOY_CAP_CALIBRATE, else JOY_AXIS_MIN..JOY_AXIS_MAX. |
tick() |
NULL, or called INSIDE THE TIMER INTERRUPT at the poll rate while a handle is open. The timer service’s rules apply; the driver pins the code and data it touches with platformLockRegion and releases them with platformUnlockRegion when its module is unloaded (a destructor), so rescans do not pile up locked memory. |
settingsChanged() |
NULL, or re-read the driver’s settings (joySettingGet) after they changed. |
Up to JOY_MAX_DRIVERS drivers in use get their tick called. A driver is loaded again at every probe, so it must not rely on state kept from an earlier load; set its hardware up in probe (or a constructor).
10.3.8. BASIC
src/include/basic/joystick.bas declares JoyCount, JoyName$, JoyAxes, JoyButtons, JoyX, JoyY, JoyAxis, JoyButton, and JoyHat. Joystick, axis, button, and hat numbers start at 1; each function reads through the calling program’s shared handle. Events: JoyWatch(joy, watching) sets (or clears) that handle’s joySetEventFn, which keeps the program’s changes, the last BAS_EVENTS_MAX (64); JoyEvent gives the next as JoyEventKindE + JOY_BAS_EVENT_FIRST (JOY_BAS_EVENT_NONE for none; CONSTs JOY_EVENT_*), and JoyEventJoy, JoyEventIndex (both from 1), and JoyEventValue the one it gave last. joyBasForget drops a program’s kept changes when it ends.
For a settings program (the Control Panel’s Game Controllers page) it also declares: JoyHats, JoyAxisPresent(joy, axis), JoyCanCalibrate(joy) (JoyInfoT hatCount, axisPresent, JOY_CAP_CALIBRATE); JoyConnected(joy) (joyRead’s connected); JoyRescan (joyRescanApp for the calling program: its own handles and STICK readings go first; -1 while another program has a joystick open); JoyRawAxis(joy, axis) and JoyRawButtons(joy) (joyGetRaw); JoySetCalibration(joy, axis, minV, centerV, maxV) and JoyClearCalibration(joy, axis) (joySetCalibration); JoyDeadZone / JoySetDeadZone (joyGetDeadZone / joySetDeadZone); JoyChoiceCount(which), JoyChoiceLabel$(which, index), JoyChoice(which), JoySetChoice(which, index) with JOY_CHOICE_GAMEPORT = 0 and JOY_CHOICE_FALLBACK = 1 (JoyChoiceE; joyChoices / joyChoiceGet / joyChoiceSet); JoyKeyCount and JoyKeyName$(index); JoyKbdSlotCount, JoyKbdSlot(slot), JoySetKbdSlot(slot, keyIndex) (joyKbdSlotGet / Set); JoySetting$(key, defaultValue) and JoySetSetting(key, value) ("" removes; joySettingGet / Set); JoySettingsLoad(prefs) and JoySettingsStore(prefs) with a prefs.bas handle (prefsBasHandle); JoyCalibration(joy, axis, part) (joyGetCalibration; part JOY_CAL_MIN / JOY_CAL_CENTER / JOY_CAL_MAX, joystick.h; 0 when joyGetCalibration fails); JoyIsKeyboard(joy) (JOY_CAP_KEYBOARD); JoyKeyIndex(keyName), JoyKeyCode(index), JoyKeyNameOf$(rawCode) (joyKeyIndex / joyKeyCode / joyKeyNameOf). CONSTs JOY_DEADZONE_DEFAULT / _MAX, JOY_POLL_HZ_DEFAULT / _MIN / _MAX, and JOY_KEY_POLL_HZ mirror joystick.h. Lists (choices, keys, slots) are numbered from 0; True is -1.
The BASIC runtime calls joyBasStick(n) and joyBasStrig(n) for QBasic’s STICK and STRIG. Joystick A is device 0 (axes 0-1, buttons 0 and 1); joystick B is device 1, or axes 2-3 and buttons 2-3 of device 0 when it is the only device and has more than two axes. STICK(0) reads A’s X and remembers A’s Y and B’s X and Y for STICK(1) to STICK(3) (per program, forgotten when it ends); positions are 1 to 200 ((value - JOY_AXIS_MIN) x 199 / 65535 + 1), 0 without that joystick. Even STRIG numbers use joyButtonWentDown (0 A button 1, 2 B button 1, 4 A button 2, 6 B button 2), odd ones the state joyRead reports; True is -1.
10.4. Game Helpers Library
Frame pacing, held keys, program-owned timers, and nearest-color lookup for programs that run like games in a DVX window. It builds on the core’s game input windows, held-key table, timer service, and high-resolution clock (see Writing Games for DVX).
Header: game/game.h
Loaded as: bin/libs/kpunch/game/game.lib
10.4.1. Frame Pacing
GameFramePacerT pacer;
gameFrameInit(&pacer, 70);
while (running) {
uint32_t missed = gameFrameWait(&pacer); // 0 when on time
updateGame(missed + 1); // catch the game logic up
drawFrame();
}
gameFrameInit(p, hz) starts pacing at hz frames a second (1 to GAME_FRAME_MAX_HZ, 1000; out of range is clamped) with frame 0 beginning now. gameFrameWait waits until the next frame begins and returns the number of frames that were missed. While it waits it gives the time to the other programs (tsYield), so call it from a program with its own main loop (hasMainLoop), never from a window callback. Frame n begins at start + n / hz on platformMicros, so the pace does not drift however long it runs. When the frame after the next one has already begun (the caller was busy), the frames in between are skipped, not caught up: gameFrameWait returns at once with how many, and GameFramePacerT.missed keeps the total. A frame that starts late but within its own time counts as on time.
gameFrameNext(p, &missed) does the same without the waiting: it moves on to the next frame (skipping and counting missed ones the same way) and returns the platformMicros time that frame begins, for a caller that waits its own way. The BASIC runtime uses it for the FRAMEWAIT statement, keeping the desktop running while it waits.
10.4.2. Held Keys
gameKeyIsDown(win, rawCode) is true while the key is held down and win has the keyboard focus. Keys are named by raw code (KEY_RAW_CODE, KEY_RAW_* in dvxTypes.h). The held-key table starts over whenever the focus moves, so a key pressed while another window had the focus is not seen until it repeats.
10.4.3. Timers
gameTimerAdd(ctx, hz, fn, userData) is platformTimerAdd for the calling program (ctx->currentAppId): the timer is removed when the program ends, however it ends. fn runs inside the timer interrupt; read the rules at the Timer Service in the platform reference before writing one. Remove it with platformTimerRemove.
10.4.4. Colors on a 256-Color Desktop
On an 8-bit desktop every window shares the desktop palette (dvxGetDisplay(ctx)->palette; NULL at 15 bits and more). A game with its own colors draws the nearest desktop entries.
| Function | Description |
|---|---|
gamePalNearest(pal, r, g, b) |
The entry of the 256-entry palette pal (R, G, B bytes) closest to the color: smallest squared RGB distance, lowest index on a tie. An exact search of all 256 entries. |
gamePalCacheInit(c, pal) |
Record pal in the cache c and empty it. GamePalCacheT is about 37 KB: allocate it. |
gamePalCacheLookup(c, r, g, b) |
The entry nearest to the center of the color’s 15-bit cell (5 bits per channel), searched once per cell and then remembered, so every color in a cell gets the same answer. |
gamePalCacheSync(c, pal) |
Start over (and return true) when pal differs from the recorded palette; call it once a frame if the palette can change. |
10.4.5. BASIC
src/include/basic/game.bas declares GameKeyDown(keyCode), True while the key is held and one of the calling program’s windows has the focus, with GAMEKEY_* constants for common keys; GameKeyClear (platformKeyStateClear, only while the calling program’s window has the focus); GameWaitRetrace (platformVideoWaitRetrace); and FrameMissed(), the missed count of the BASIC runtime’s own FRAMEWAIT pacer (GameFramePacerT.missed since FRAMEWAIT last started at a new rate; 0 before the first FRAMEWAIT). The BASIC runtime gives the library the GUI context (gameBasSetContext) when a program starts, and runs FRAMEWAIT on gameFrameInit / gameFrameNext.
Chapter 11. DVX BASIC from C
11.1. BASIC Runtime Library
Stack-based p-code virtual machine and value system for DVX BASIC. Embeddable: the host provides I/O and UI callbacks. No DVX GUI dependencies in the core runtime.
Headers: apps/dvxbasic/runtime/vm.h, apps/dvxbasic/runtime/values.h
See also: Virtual Machine (vm.h) (Section 11.3).
11.2. Value System
Tagged union value type for the VM evaluation stack, variables, and array elements. Strings, arrays, and UDT instances are reference-counted for automatic memory management without a garbage collector.
Header: apps/dvxbasic/runtime/values.h
11.2.1. Type Tags
| Constant | Value | C Union Field | Description |
|---|---|---|---|
BAS_TYPE_INTEGER |
0 |
intVal |
16-bit signed integer. |
BAS_TYPE_LONG |
1 |
longVal |
32-bit signed integer. |
BAS_TYPE_SINGLE |
2 |
sngVal |
32-bit float. |
BAS_TYPE_DOUBLE |
3 |
dblVal |
64-bit float. |
BAS_TYPE_STRING |
4 |
strVal |
Reference-counted dynamic string. |
BAS_TYPE_BOOLEAN |
5 |
boolVal |
True (-1) or False (0). |
BAS_TYPE_ARRAY |
6 |
arrVal |
Reference-counted array. |
BAS_TYPE_UDT |
7 |
udtVal |
Reference-counted user-defined type. |
BAS_TYPE_OBJECT |
8 |
objVal |
Opaque host pointer (form, control). |
BAS_TYPE_REF |
9 |
ref |
Reference (ByRef argument): ref.target is the variable, element, or field it names; ref.owner keeps that storage alive. |
A reference only ever lives in a call’s parameters (a ByRef parameter, a ParamArray element). Read through it with basValDeref, which returns the value a reference names (or the value itself). refKind says what ref.owner is: BAS_REF_SLOT (none: a global, local, or form variable), BAS_REF_ARRAY (the array, counted and locked so REDIM, ERASE, and a store that would replace the array raise error 10), BAS_REF_UDT (the TYPE instance holding the field), BAS_REF_OBJECT (the class instance holding the member variable), or BAS_REF_CELL (a BasRefCellT holding both the locked array and the TYPE instance, for a field of an array element). refType is the target’s declared type (stores convert to it) and refLen the length of a STRING * n target (basRefFixedLen); for an object target (refType BAS_TYPE_OBJECT) refLen says instead which class a stored object must be of, read with basRefObjCheck (BAS_OBJ_CHECK_ANY: any). basValCopy and basValRelease count the owner.
11.2.2. BasValueT
Tagged union holding any BASIC value.
struct BasValueTag {
uint8_t type; // BAS_TYPE_*
uint8_t refType : 5; // BAS_TYPE_REF: the target's declared type
uint8_t refKind : 3; // BAS_TYPE_REF: BasRefKindE
uint16_t refLen; // BAS_TYPE_REF: STRING * n length (0 = none); of an object target, the class it takes (basRefObjCheck)
union {
int16_t intVal;
int32_t longVal;
float sngVal;
double dblVal;
BasStringT *strVal;
int16_t boolVal;
BasArrayT *arrVal;
BasUdtT *udtVal;
void *objVal;
BasObjectT *instVal;
struct {
void *owner;
BasValueT *target;
} ref;
};
};
BasValueT *basValDeref(const BasValueT *v); // inline: what a reference names, else v
11.2.3. Value Constructors
BasValueT basValInteger(int16_t v);
BasValueT basValLong(int32_t v);
BasValueT basValSingle(float v);
BasValueT basValDouble(double v);
BasValueT basValString(BasStringT *s);
BasValueT basValStringFromC(const char *text);
BasValueT basValBool(bool v);
BasValueT basValObject(void *obj);
Each returns a BasValueT with the appropriate type tag set. basValString increments the string’s reference count.
11.2.4. Value Lifetime
BasValueT basValCopy(BasValueT v);
void basValRelease(BasValueT *v);
| Function | Description |
|---|---|
basValCopy |
Copy a value. Increments reference count for strings, arrays, and UDTs. |
basValRelease |
Release a value. Decrements reference count and frees if it reaches zero. |
11.2.5. Type Conversion
BasValueT basValToDouble(BasValueT v);
BasValueT basValToString(BasValueT v);
int32_t basValToInt32(BasValueT v);
basValToDouble and basValToString return a new value of the target type. The original is not released; the caller manages both lifetimes.
basValToInt32 gives a number taken as a whole number — an argument of a built-in, a property’s value, a count, an index — as Visual Basic converts one, CLng’s rule: a fraction rounds half to even (2.5 is 2, 3.5 is 4). A value past the Long range (or NaN) sets basValOverflowUsed and gives the nearest Long (NaN: 0); the VM raises error 6 (Overflow) once the instruction is done, in place of any error the instruction raised with the nearest Long, as Visual Basic raises Overflow converting the argument before the call runs. A native function reading a whole number from a BASIC value uses it.
11.2.6. Value Utilities
| Function | Description |
|---|---|
basValToNumber(v) |
Convert any numeric value to double. |
basValFormatString(v) |
Return a new ref-counted string representation of v, as CStr gives it ("0.25"). |
basValPrintDigits(v) |
basValFormatString’s text, but a number between -1 and 1 without the 0 before its point (".25"), as PRINT, STR$, and WRITE # show it. |
basValPrintString(v) |
PRINT’s text for v: basValPrintDigits’s, a number with a space before it (where its sign goes) and after it (" .25 "). |
basValIsTruthy(v) |
True if non-zero number or non-empty string. |
basValCompare(a, b) |
Compare two values. Returns -1, 0, or 1. |
basValCompareCI(a, b) |
Case-insensitive comparison (OPTION COMPARE TEXT). |
basValPromoteType(a, b) |
Determine common type for binary ops (e.g. Integer + Single -> Single). |
11.2.7. BasStringT
Reference-counted string with flexible array member for inline storage.
typedef struct {
int32_t refCount;
int32_t len;
int32_t cap;
char data[];
} BasStringT;
String Functions
| Function | Description |
|---|---|
basStringNew(text, len) |
Allocate from a C string. refCount starts at 1. |
basStringAlloc(cap) |
Allocate an empty string with given capacity. |
basStringRef(s) |
Increment reference count. Returns s. |
basStringUnref(s) |
Decrement reference count. Frees when it reaches zero. |
basStringConcat(a, b) |
Concatenate two strings. Returns a new string (refCount 1). |
basStringSub(s, start, len) |
Extract a substring. Returns a new string (refCount 1). |
basStringCompare(a, b) |
Compare. Returns <0, 0, >0 (like strcmp). |
basStringCompareCI(a, b) |
Case-insensitive compare. |
The global basEmptyString is a singleton that is never freed.
11.2.8. BasArrayT
Reference-counted multi-dimensional array (up to BAS_ARRAY_MAX_DIMS = 8 dimensions).
typedef struct {
int32_t refCount;
int32_t locks; // references naming an element: REDIM, ERASE, and replacing the array raise error 10 while any exist
uint8_t elementType;
bool holdsRefs; // some element is a reference (a ParamArray's arguments passed by reference)
bool fixedSize; // declared with constant bounds: ERASE resets its elements, REDIM raises error 10
uint16_t fixedLen; // elements declared STRING * n: n (0: none)
int32_t dims; // 0: a dynamic array without bounds yet (DIM a(), ERASE)
int32_t lbound[BAS_ARRAY_MAX_DIMS];
int32_t ubound[BAS_ARRAY_MAX_DIMS];
int32_t totalElements;
BasValueT *elements;
} BasArrayT;
A program’s stores into an element are converted to elementType and, with fixedLen, padded with spaces or cut to that many characters; a native function that stores into an element should do the same. A fixedSize array keeps its bounds: a native function should change its elements in place rather than give the caller another array. A dynamic array the program has not given bounds yet has dims 0 and no elements (its bounds and elements raise error 9). The elements are kept with the last subscript changing fastest; FOR EACH and PUT go in the order Visual Basic keeps an array, the first subscript fastest.
Array Functions
| Function | Description |
|---|---|
basArrayNew(dims, lbounds, ubounds, type) |
Allocate an array. refCount starts at 1. |
basArrayNewUndimensioned(type) |
Allocate a dynamic array without bounds (dims 0). refCount starts at 1. |
basArrayFree(arr) |
Free all elements and release the array. |
basArrayRef(arr) |
Increment reference count. |
basArrayUnref(arr) |
Decrement reference count. Frees at zero. |
basArrayIndex(arr, indices, ndims) |
Compute flat index from multi-dimensional indices. Returns -1 if out of bounds. |
11.3. Virtual Machine
Stack-based p-code interpreter. Executes compiled BASIC bytecode modules. The host provides I/O, UI, SQL, and external library callbacks. The VM has no DVX dependencies; it can be embedded in any C program.
Header: apps/dvxbasic/runtime/vm.h
11.3.1. VM Limits
| Constant | Value | Description |
|---|---|---|
BAS_VM_STACK_SIZE |
256 |
Evaluation stack depth. |
BAS_VM_CALL_STACK_SIZE |
64 |
Maximum call nesting depth. |
BAS_VM_MAX_GLOBALS |
512 |
Global variable slots. |
BAS_VM_MAX_LOCALS |
64 |
Local variables per stack frame. |
BAS_VM_MAX_MEMBER_VARS |
65536 |
Member variables per class object; variables per form (their opcodes' 16-bit index). |
BAS_VM_MAX_FOR_DEPTH |
32 |
Maximum nested FOR loop depth. |
BAS_VM_MAX_FILES |
16 |
Open file channels (1-based). |
11.3.2. BasVmResultE
Result codes returned by basVmRun and basVmStep.
| Code | Value | Description |
|---|---|---|
BAS_VM_OK |
0 |
Program completed normally. |
BAS_VM_HALTED |
1 |
HALT instruction reached. |
BAS_VM_ERROR |
2 |
Runtime error. |
BAS_VM_STACK_OVERFLOW |
3 |
Evaluation stack overflow. |
BAS_VM_STACK_UNDERFLOW |
4 |
Evaluation stack underflow. |
BAS_VM_CALL_OVERFLOW |
5 |
Call stack overflow. |
BAS_VM_DIV_BY_ZERO |
6 |
Division by zero. |
BAS_VM_TYPE_MISMATCH |
7 |
Type mismatch in operation. |
BAS_VM_OUT_OF_MEMORY |
8 |
Memory allocation failed. |
BAS_VM_BAD_OPCODE |
9 |
Unknown opcode encountered. |
BAS_VM_FILE_ERROR |
10 |
File I/O error. |
BAS_VM_SUBSCRIPT_RANGE |
11 |
Array subscript out of range. |
BAS_VM_STEP_LIMIT |
12 |
Step limit reached (not an error). |
BAS_VM_BREAKPOINT |
13 |
Breakpoint or step completed (not an error). |
11.3.3. Lifecycle
BasVmT *basVmCreate(void);
void basVmDestroy(BasVmT *vm);
void basVmLoadModule(BasVmT *vm, BasModuleT *module);
void basVmReset(BasVmT *vm);
| Function | Description |
|---|---|
basVmCreate |
Allocate and initialize a new VM instance. |
basVmDestroy |
Destroy the VM and free all resources. |
basVmLoadModule |
Load a compiled module (BasModuleT) into the VM. |
basVmReset |
Reset to initial state (clear stack, globals, PC). |
11.3.4. Execution
BasVmResultE basVmRun(BasVmT *vm);
BasVmResultE basVmStep(BasVmT *vm);
void basVmSetStepLimit(BasVmT *vm, int32_t limit);
| Function | Description |
|---|---|
basVmRun |
Execute the loaded module until it ends, halts, yields, errors, or hits a breakpoint/step limit. |
basVmStep |
Execute a single instruction and return. Useful for debugger stepping. |
basVmSetStepLimit |
Set maximum instructions per basVmRun call. 0 = unlimited (default). Returns BAS_VM_STEP_LIMIT when reached. |
11.3.5. I/O Callbacks
The host provides these callbacks for PRINT, INPUT, and DoEvents statements.
void basVmSetPrintCallback(BasVmT *vm, BasPrintFnT fn, void *ctx);
void basVmSetInputCallback(BasVmT *vm, BasInputFnT fn, void *ctx);
void basVmSetDoEventsCallback(BasVmT *vm, BasDoEventsFnT fn, void *ctx);
bool basVmAtSliceEnd(const BasVmT *vm);
Callback Types
typedef void (*BasPrintFnT)(void *ctx, const char *text, bool newline);
typedef bool (*BasInputFnT)(void *ctx, const char *prompt,
char *buf, int32_t bufSize);
typedef bool (*BasDoEventsFnT)(void *ctx);
| Type | Description |
|---|---|
BasPrintFnT |
Called for PRINT output. text is null-terminated. newline indicates line advance. |
BasInputFnT |
Called for INPUT. Fill buf (up to bufSize-1 chars). Return true on success, false on cancel. |
BasDoEventsFnT |
Called for DoEvents and the waits that act like it (SLEEP, the sound and FRAMEWAIT waits, FileCopy, DIR$): run the program’s pending events and return. Also called at each slice end of a running handler, when basVmAtSliceEnd(vm) is true: then give DVX and the other programs their turn but run none of the program’s own events, which wait for DoEvents or the handler’s end as in Visual Basic (basFormRtUpdate does this by itself). Return false to stop the program. |
11.3.6. UI Callbacks
For form and control integration. The VM resolves all UI operations through these callbacks, keeping it independent of any specific GUI toolkit.
void basVmSetUiCallbacks(BasVmT *vm, const BasUiCallbacksT *ui);
BasUiCallbacksT
| Field | Signature | Description |
|---|---|---|
getProp |
BasValueT (*)(ctx, ctrlRef, propName) |
Get a control property value. |
setProp |
void (*)(ctx, ctrlRef, propName, value) |
Set a control property. |
setPropArgs |
void (*)(ctx, ctrlRef, propName, args, argc, value) |
Assign an indexed property (List1.ItemData(i) = n): its index arguments, then the value. NULL: such an assignment raises error 438. |
callMethod |
BasValueT (*)(ctx, ctrlRef, methodName, args, argc) |
Call a method on a control. |
createCtrl |
void *(*)(ctx, formRef, typeName, ctrlName) |
Create a control on a form. |
findCtrl |
void *(*)(ctx, formRef, ctrlName, outErr) |
Find a control by name on formRef, or (NULL) on the one loaded form with it (*outErr 1001 when several). |
findCtrlIdx |
void *(*)(ctx, formRef, ctrlName, index, outErr) |
Find a control array element, as findCtrl. |
loadCtrl |
bool (*)(ctx, formRef, name, index, unload) |
Load (unload false) or Unload of element index of the control array or menu control array name on formRef, or (NULL) on the one loaded form with that name; errors (360, 340, 362, 343, 1001) raised with basVmLibraryError. False when the form has no control or menu item of that name. NULL: Load / Unload of an element raises error 1000. |
loadForm |
void *(*)(ctx, formName) |
Load a form by name. |
unloadForm |
void (*)(ctx, formRef) |
Unload a form. |
showForm |
void (*)(ctx, formRef, modal) |
Show a form (modal or modeless). |
hideForm |
void (*)(ctx, formRef) |
Hide a form (keep in memory). |
msgBox |
int32_t (*)(ctx, message, flags) |
Display a message box. |
inputBox |
BasStringT *(*)(ctx, prompt, title, defaultText) |
Display an input box. |
loadFormText |
void *(*)(ctx, text) |
LoadFormText: a form from .frm text (its own copy when the name is loaded), NULL when it does not load. |
ctx |
void * |
User pointer passed to all callbacks. |
11.3.7. SQL Callbacks
For database integration.
void basVmSetSqlCallbacks(BasVmT *vm, const BasSqlCallbacksT *sql);
BasSqlCallbacksT
| Field | Signature | Description |
|---|---|---|
sqlOpen |
int32_t (*)(path) |
Open a database. Returns handle. |
sqlClose |
void (*)(db) |
Close a database. |
sqlExec |
bool (*)(db, sql) |
Execute a non-query SQL statement. |
sqlError |
const char *(*)(db) |
Get last error message. |
sqlQuery |
int32_t (*)(db, sql) |
Execute a query. Returns result set handle. |
sqlNext |
bool (*)(rs) |
Advance to next row. |
sqlEof |
bool (*)(rs) |
Check if at end of result set. |
sqlFieldCount |
int32_t (*)(rs) |
Get number of columns. |
sqlFieldName |
const char *(*)(rs, col) |
Get column name by index. |
sqlFieldText |
const char *(*)(rs, col) |
Get column value as text by index. |
sqlFieldByName |
const char *(*)(rs, name) |
Get column value as text by name. |
sqlFieldInt |
int32_t (*)(rs, col) |
Get column value as integer. |
sqlFieldDbl |
double (*)(rs, col) |
Get column value as double. |
sqlFreeResult |
void (*)(rs) |
Free a result set. |
sqlAffectedRows |
int32_t (*)(db) |
Get number of rows affected by last statement. |
11.3.8. External Library Callbacks
For DECLARE LIBRARY support. The VM resolves external functions at runtime via the host.
void basVmSetExternCallbacks(BasVmT *vm,
const BasExternCallbacksT *ext);
BasExternCallbacksT
The compiler converts every argument to its declared parameter type, so callExtern receives values whose type is the declared type. The stock basExternCall pushes cdecl stack words by that type: STRING as a char pointer, a BINARY STRING (binaryMask bit i set for argument i) as the char pointer followed by an int32_t length, SINGLE as one 4-byte float, DOUBLE as 8 bytes, everything else as one int32_t. When binaryMask has BAS_EXTERN_BINARY_RET the result is a BINARY STRING: an int32_t * is pushed last and the result is that many bytes at the returned pointer. DOUBLE and SINGLE returns are read from the x87 ST(0) register; INTEGER returns keep only the low 16 bits.
| Field | Signature | Description |
|---|---|---|
resolveExtern |
void *(*)(ctx, libName, funcName) |
Resolve a native function by library and symbol name. Cached after first call. |
callExtern |
BasValueT (*)(ctx, funcPtr, libName, funcName, args, argc, retType, binaryMask) |
Call a resolved native function, marshaling arguments and return value. |
ctx |
void * |
User pointer passed to both callbacks. |
A native SUB is called with OP_CALL_EXTERN like a FUNCTION and leaves a dummy result on the stack; a call written as a statement drops it, as it drops a FUNCTION’s result. A SUB’s retType is INTEGER, so no floating-point result is read for it.
void *basVmFindCtrl(BasVmT *vm, const char *name, int32_t *outErr);
void basVmLibraryError(BasVmT *vm, int32_t errNum);
bool basVmLibraryErrorText(BasVmT *vm, int32_t errNum, const char *text);
int32_t basVmHostWorkBegin(BasVmT *vm);
void basVmHostWorkEnd(BasVmT *vm, int32_t depth);
A native function given a control’s name finds the control with basVmFindCtrl as the program’s code naming it alone finds it: called from a form’s code, that form’s control first, else the one loaded form’s that has one; NULL when none has one, and when several forms have one, with *outErr BAS_ERR_AMBIGUOUS_CONTROL (1001). basVmLibraryError raises a BASIC error where the program called the native function, once the function returns (ON ERROR traps it there); the function itself returns as usual. basVmLibraryErrorText does the same with text as the error’s description (Err.Description, and what the program’s error box shows) in place of the number’s standard message; it returns false, raising nothing, when no native function or host property or method is running (the host’s own work, such as loading a form), for the caller to report the problem itself. A host’s getProp, setProp, and callMethod (BasUiCallbacksT), and its showForm, hideForm, createCtrl, and createCtrlEx, raise an error the same way, where the program used the property or method: the form runtime’s Print, for one, raises error 13 for an array or a TYPE record, its drawing methods error 5 for a bad argument with the details as the description, and an unknown property or method error 438. Work of the host’s own in the middle of such a call — parsing a .frm as a form loads, the wait of a modal Show — goes between basVmHostWorkBegin and basVmHostWorkEnd (given what the first returned): what goes wrong there is not raised where the program made the call (basVmLibraryErrorText answers false), while program code run meanwhile raises its own errors as always.
Terminal Controls for Libraries
A library’s BASIC functions can show a byte stream on a Terminal control the way SerAttach and CommAttach do (the connection library’s ConnAttach is one). The form runtime (formrt.h, exported from basrt) keeps the binding safe:
typedef int32_t (*BasTermWriteFnT)(void *ctx, const uint8_t *data, int32_t len);
typedef void (*BasTermUnbindFnT)(void *ctx);
WidgetT *basFormRtTermBind(const char *ctrlName, void *ctx, BasTermWriteFnT writeFn, BasTermUnbindFnT onUnbind);
void basFormRtTermUnbind(void *ctx);
void basFormRtTermForget(void *ctx);
basFormRtTermBind finds the Terminal control ctrlName as the program’s code naming it alone finds it (basVmFindCtrl: from a form’s code that form’s first, else the one loaded form’s that has one, and when several forms have one, error 1001 raised where the program called the library), ends whatever fed it before (a serial port, a packet link, another binding) and ctx’s own earlier binding, sends what is typed there to writeFn, and returns the widget for the library to write what arrives to (NULL when there is no Terminal of that name). When the control goes away — its form unloads, it is removed, another binding takes it — the runtime ends the binding and calls onUnbind(ctx): the library must forget the widget. basFormRtTermUnbind ends a binding the library no longer wants; basFormRtTermForget drops it without touching the widget, for a library whose program was ended (its windows are already gone). A library outside basrt looks these up with dlsym when it first needs them.
11.3.9. Form Context
Set the active form context during event dispatch.
void basVmSetCurrentForm(BasVmT *vm, void *formRef);
void basVmSetCurrentFormVars(BasVmT *vm,
BasValueT *vars, int32_t count);
11.3.10. Collections for the Host
A host hands BASIC a Collection of its own objects (the form runtime’s Form.Controls) with these; basValInstance of the new Collection takes its one reference.
BasObjectT *basVmCollectionNew(BasVmT *vm);
int32_t basVmCollectionAdd(BasObjectT *coll, BasValueT item, const char *key); // key NULL: none; 0 or the BASIC error number
11.3.11. Control Types and the Design Surface
formrt/formDesign.c holds what a form designer needs, shared by the DVX BASIC IDE’s designer and by designer.bas (DECLARE LIBRARY "basrt": CtlTypeCount, CtlTypeName, CtlTypeFlags, CtlTypeNamePrefix, CtlTypeDefaultEvent, CtlTypeTooltip, CtlTypeIconFile, CtlTypeNaturalSize, CtlPropCount, CtlPropName, CtlPropType, CtlPropEnum, CtlMethodList, CtlEventList, CtlEventParams, CtlTypeEventParams, and FrmFormName, FrmControlNames, FrmCode, ClsClassName over the basRes.h scanners). CtlTypeTooltip and CtlTypeIconFile fall back to a UserControl’s header (its Description; its ToolboxIcon file, basUcIconPath) when the type has no widget file:
| Function | Description |
|---|---|
basCtlIface(typeName) |
The widget interface of a BASIC type name, or NULL. |
basCtlPropAt(typeName, idx, out) / basCtlPropFind(...) |
A type’s properties as BasCtlPropT (name, type, readable, writable, enum names): the runtime table’s ("Form", "Menu", or the common one), the widget’s own winning on a name, then the widget’s others. The IDE’s properties window uses basCtlPropFind. |
basCtlMethodAt / basCtlEventAt(typeName, idx) |
A type’s methods (the widget’s, then the common ones) and events (the master BAS_EVENT_LIST's for that kind of object, then the widget’s); the IDE’s event list uses basCtlEventAt. |
basCtlEventParams(typeName, eventName) |
The parameter list of a handler of a type’s event: the widget’s own (WgtEventDescT params), else the master list’s; typeName NULL searches every widget after the master list, BAS_UC_OBJECT ("UserControl", the object in a UserControl’s own code) has BAS_UC_EVENT_LIST's alone. The IDE’s handler skeletons, CtlEventParams, and CtlTypeEventParams. |
basCtlDefaultEvent, basCtlNamePrefix, basCtlIsContainer |
As the toolbox and designer need them. |
basCtlNaturalSize(typeName, outW, outH) |
The size a new control of the type starts at: a UserControl’s header Width and Height (basUcIfaceHeader; pixels, or a wgtPercent or wgtChars size). False, the outputs untouched, for a type with no header. The IDE’s designer places a UserControl so, and CtlTypeNaturalSize gives the same as .ctl header text (frmSizeText). |
basCtlResPath(typeName, resBase, resName, size) |
The widget file and the (suffixed) resource name of its toolbox icon (BAS_CTL_RES_ICON) or tooltip (BAS_CTL_RES_NAME). |
basCtlTypeAt(rt, idx) |
The idx-th control type rt sees (basUcIfaceVisible; rt NULL: a C host) in alphabetical order of BASIC name, NULL past the end. The IDE’s toolbox and CtlTypeName list the types in this order; the registry’s own (wgtIfaceAt) is the order the widget files loaded in. |
basDsgnHandleOrigin / basDsgnHandleAt / basDsgnCursorAt |
Selection handle geometry: where handle h of a widget is, the resize handle under a point, the mouse pointer there. |
basDsgnPaintHandles(ctx, win, w) |
Paints a widget’s eight selection handles over a window’s painted content. |
basDsgnPropertyChanged(w, propName) |
The code of UserControl widget w called PropertyChanged: a form in DesignMode holding it raises DesignPropertyChanged (CtrlName, PropertyName). formCtl.c calls it beside the C hook (basUcSetPropChangedHook). |
basDsgnWidgetHit(w, x, y) |
True when a point is on a visible widget. |
Form.DesignMode replaces the form window’s mouse, key, paint, and cursor handlers while it is True (the controls get no input, and fireCtrlEvent drops their events), raises DesignMouse, DesignKey, and DesignPropertyChanged, and paints DesignSelection’s handles after the widgets. Form.Controls, Control.Parent / Container, and MoveBefore (basFormRtMoveControl) are dispatched there too.
11.3.12. UserControls for a Host
formrt/formCtl.c registers UserControls (widget classes written in BASIC) with the widget system. A program’s own controls (basFormRtRegisterCtl: the stub’s and the IDE’s runs) and a designer’s (basCtlLoadDesign) get private registry keys, the class name plus a serial, so the same project running and being designed, or two programs, never share one; a control file’s (basCtlLoadFile) keeps its name. Resolve names through these instead of wgtGetIface:
| Function | Description |
|---|---|
basCtlLoadDesign(rt, module, headers, count, path) |
Designer rt’s controls (rt: a BASIC program designing forms, compiler.bas CompDesignControls; NULL: a C host, the IDE): the .ctl headers' classes of module (the caller keeps it until basCtlUnloadDesign or rt’s end), run without the module-level code, App.Path the folder of path. Returns how many were registered (a name a native or installed control has, or rt’s own control has, is not). The set rt registered before is let go first. |
basCtlUnloadDesign(rt) |
Lets designer rt’s controls go (their widgets keep their last picture and run no more code). False while their code runs. basUcRuntimeEnd lets a program’s go when it ends. |
basUcIconPath(iface, out, outSize) |
The ToolboxIcon picture file of a control file’s or a designer’s UserControl: the header’s name in the folder of the path it was registered with (the project’s, for a designer’s). False when it names none or iface is no such control. |
basUcResolveType(rt, typeName) |
The registry key of a BASIC type name in rt’s program: its own UserControl first (its program’s or the ones it registered for design; rt NULL: the C host’s design controls), else wgtResolveTypeName — never another owner’s private control (NULL then). |
basUcOwnIface(rt, typeName) |
The interface of rt’s own UserControl (its program’s or a design one; rt NULL: the C host’s design controls), NULL for none. basCtlIface looks here first, for the current program (basFormRtCurrent). |
basUcIfaceVisible(rt, iface) |
False when iface is a private UserControl of another owner; a list of control types (basCtlTypeAt) leaves those out. |
basUcIfaceHeader(iface) |
The parsed header (BasUcHeaderT: name, size, BackColor, ToolboxIcon, Description, DefaultEvent) of a UserControl’s interface, NULL for any other. |
basUcSetPropChangedHook(fn) |
fn(widget, propName) runs when a control’s code calls PropertyChanged: a C designer reads its property sheet again (a BASIC one gets DesignPropertyChanged, basDsgnPropertyChanged). |
basDsgnSetDesignWindow(win, on) / basDsgnIsDesignWindow |
Marks a window as a designer’s (unmark it when it is destroyed): UserControls on it see UserMode False and get no user input. |
11.3.13. Stack Access
Push and pop values on the evaluation stack for host integration.
bool basVmPush(BasVmT *vm, BasValueT val);
bool basVmPop(BasVmT *vm, BasValueT *val);
Both return true on success, false on stack overflow/underflow.
11.3.14. Error Reporting
const char *basVmGetError(const BasVmT *vm);
Returns the current error message string. Valid after basVmRun returns BAS_VM_ERROR, and after a call of a SUB from the host (an event handler) that an untrapped error stopped.
The form runtime ends the program on every untrapped error, in module-level code and in event handlers alike (basFormRtRuntimeError for errors the runtime finds where the program cannot trap them — a .frm that does not load — the same path for the VM’s own; what the program’s use of a property or method gets wrong it raises with basFormRtRaiseText, as a trappable error with Visual Basic’s number, its details as Err.Description): the error is logged to DVX.LOG (summary line, details indented), the VM halts (ended), the runtime is marked terminated so its event loop ends, and the BASIC Runtime Error box shows it — unless the host set suppressErrorDialog (the IDE), which reports it itself. The VM’s message ("Runtime error 11 on line 8: Division by zero") stays readable with basVmGetError.
11.3.15. Sub/Function Calls from Host
Call a SUB or FUNCTION by its code address from host code.
bool basVmCallSub(BasVmT *vm, int32_t codeAddr);
bool basVmCallSubWithArgs(BasVmT *vm, int32_t codeAddr,
const BasValueT *args, int32_t argCount);
bool basVmCallSubWithArgsOut(BasVmT *vm, int32_t codeAddr,
BasObjectT *me, const BasValueT *args, int32_t argCount,
BasValueT *outArgs, int32_t outCount);
int32_t basVmCtrlEventSinks(BasVmT *vm, void *ctrlRef,
const char *eventName, BasCtrlSinkT *out, int32_t max);
- basVmCallSub
-
Call a SUB with no arguments.
- basVmCallSubWithArgs
-
Call a SUB with arguments pushed onto the stack frame.
- basVmCallSubWithArgsOut
-
Call a SUB with Me = me (a class instance; NULL: none) whose first outCount parameters are references to outArgs (set to the arguments first; each must hold a valid value): what the SUB stores in them is there when it returns, also after an error.
- basVmCtrlEventSinks
-
The handlers (BasCtrlSinkT: the procedure, and the form, form variables, or class instance it runs for) that event eventName of control ctrlRef reaches through WithEvents variables declared As a control type holding it, or (ctrlRef a form’s own object, for the form’s event) As a form holding that form instance by any reference to it (the sameObject callback decides), at most max into out. Returns how many. A host fires the event to the control’s or form’s own handler, then to these, each getting the ByRef arguments as the handlers before it left them; it holds a reference to each instance while any handler runs.
All three calls push a call frame, execute until the SUB returns, then restore the previous execution state. Return true on normal completion, false on error or if the VM is not idle.
11.3.16. Debugger API
void basVmSetBreakpoints(BasVmT *vm,
int32_t *lines, int32_t count);
void basVmStepInto(BasVmT *vm);
void basVmStepOver(BasVmT *vm);
void basVmStepOut(BasVmT *vm);
void basVmRunToCursor(BasVmT *vm, int32_t line);
void basVmClearStepState(BasVmT *vm);
void basVmSetBreakpointCallback(BasVmT *vm,
BasBreakpointFnT fn, void *ctx);
void basVmSetDebugPaused(BasVmT *vm, bool paused);
void basVmResume(BasVmT *vm);
void basVmStop(BasVmT *vm);
int32_t basVmGetCurrentLine(const BasVmT *vm);
int32_t basVmGetErrorLine(const BasVmT *vm);
void basVmSetAppPaths(BasVmT *vm, const char *path, const char *user, const char *data);
| Function | Description |
|---|---|
basVmSetBreakpoints |
Set the breakpoint list (sorted array of source line numbers, host-owned memory). |
basVmStepInto |
Break at the next OP_LINE instruction. |
basVmStepOver |
Break when call depth returns to the current level. |
basVmStepOut |
Break when call depth drops below the current level. |
basVmRunToCursor |
Break when execution reaches the specified source line. |
basVmClearStepState |
Cancel a pending step or run-to-cursor request. |
basVmSetBreakpointCallback |
The pause notification for SUBs the host calls (see below). |
basVmSetDebugPaused |
Break mode on or off: while on, basVmCallSub refuses to run event handlers. |
basVmResume |
Leave break mode; a handler paused at a breakpoint carries on. |
basVmStop |
Stop a debugged program: step state cleared, breakpoints detached, break mode ended, the running code unwinds. |
basVmGetCurrentLine |
Get the current source line number (from the last OP_LINE instruction). |
basVmGetErrorLine |
The source line where the current runtime error was raised (0: none). |
basVmSetAppPaths |
Set App.Path, App.User (the program’s user folder, made on first use), and App.Data. |
The breakpoint callback notifies the host when a breakpoint fires during nested sub calls:
typedef void (*BasBreakpointFnT)(void *ctx, int32_t line);
11.3.17. BasModuleT
Compiled module produced by the BASIC compiler and loaded into the VM.
typedef struct {
uint8_t *code;
int32_t codeLen;
BasStringT **constants;
int32_t constCount;
int32_t globalCount;
int32_t entryPoint;
int32_t entryLocals;
BasValueT *dataPool;
int32_t dataCount;
BasProcEntryT *procs;
int32_t procCount;
BasFormVarInfoT *formVarInfo;
int32_t formVarInfoCount;
BasSlotInitT *globalInits;
int32_t globalInitCount;
BasSlotInitT *localInits;
int32_t localInitCount;
BasLineNumberT *lineNumbers;
int32_t lineNumberCount;
BasClassInfoT *classes;
int32_t classCount;
BasEnumInfoT *enums;
int32_t enumCount;
BasWithEventsT *withEvents;
int32_t withEventsCount;
BasFileCodeT *fileCode;
int32_t fileCodeCount;
BasCtrlTypeT *ctrlTypes;
int32_t ctrlTypeCount;
BasDebugVarT *debugVars;
int32_t debugVarCount;
BasDebugUdtDefT *debugUdtDefs;
int32_t debugUdtDefCount;
} BasModuleT;
| Field | Description |
|---|---|
code |
P-code bytecode array. |
codeLen |
Length of bytecode in bytes. |
constants |
String constant pool. |
constCount |
Number of string constants. |
globalCount |
Number of global variable slots needed. |
entryPoint |
PC of the first instruction (module-level code). |
entryLocals |
Local slots the module-level code’s frame needs (a form’s and a class’s set-up code record theirs in BasFormVarInfoT and BasClassInfoT initLocals, a procedure its localCount). |
dataPool |
DATA statement value pool (for READ). |
dataCount |
Number of values in the data pool. |
procs |
Procedure table (SUBs and FUNCTIONs). |
procCount |
Number of procedures. |
formVarInfo |
Per-form variable counts and init code addresses. |
formVarInfoCount |
Number of forms with form-scoped variables. |
globalInits |
The starting type of each typed global slot (kept in a release build). |
globalInitCount |
Number of global slot entries. |
localInits |
The starting type of each typed local slot, per procedure (BasProcEntryT initFirst / initCount). |
localInitCount |
Number of local slot entries. |
lineNumbers |
The program’s QBasic line numbers in source order (ERL reports them). |
lineNumberCount |
Number of line numbers. |
classes |
Class modules and UserControls (BasClassInfoT): members, events, Implements maps. |
classCount |
Number of classes. |
enums |
The Enums UserControl properties are declared As (BasEnumInfoT: member names and values in declaration order; a class member’s enumIdx names one), so a host shows and stores such a property by member name. Kept in a release build. |
enumCount |
Number of Enums. |
withEvents |
WithEvents variables and their handlers (classIdx BAS_WITHEVENTS_CONTROL: a variable declared As a control type; BAS_WITHEVENTS_FORM: As Form; BAS_WITHEVENTS_FORM_OF(f): As form f of formVarInfo, which also hears the Events that form’s code declares; the handlers of all three name their events by constants of the pool). |
withEventsCount |
Number of WithEvents variables. |
fileCode |
The code of each of the project’s files (BasFileCodeT start and end, file number 1 first): a lookup by name (basModuleFindProc) finds the caller’s file’s own procedure first. |
fileCodeCount |
Number of files. |
ctrlTypes |
The control types installed in DVX the program declares something As (a control file in WIDGETS: its name), checked by name when an object is stored there. |
ctrlTypeCount |
Number of installed control types. |
debugVars |
Variable names and metadata for the debugger. |
debugVarCount |
Number of debug variable entries. |
debugUdtDefs |
UDT type definitions for the debugger. |
debugUdtDefCount |
Number of debug UDT definitions. |
11.4. BASIC Development Library
basdev.lib is the DVX BASIC compiler and what a development tool builds on it: the build pipeline (basBuild.h), the compile-time Control.Member validator (basValidate.h), the debugger’s view of a paused program (basDebug.h), the SUB / FUNCTION scanner (basProcs.h), and the .frm model (frmModel.h) the IDE’s designer works on. The DVX BASIC IDE uses it, and BASIC programs reach it through compiler.bas, debug.bas, and designer.bas’s Frm* functions (basDevBas.c and frmModelBas.c hold their entry points). It also carries the STUB and noicon resources every build inside DVX uses (BAS_BUILD_STUB_CARRIER). It needs basrt.lib, which holds the run host (basRunHost.h) the IDE, the standalone stub, and debug.bas share.
Headers: apps/dvxbasic/basBuild.h, apps/dvxbasic/basdev/basValidate.h, apps/dvxbasic/basdev/basDebug.h, apps/dvxbasic/basdev/basProcs.h, apps/dvxbasic/basdev/basSource.h, apps/dvxbasic/basdev/basHelpMap.h, apps/dvxbasic/basdev/basProject.h, apps/dvxbasic/basdev/frmModel.h, apps/dvxbasic/formrt/basRunHost.h
11.4.1. Compiling (basBuild.h)
- basBuildAddSource
-
Append one file to a BasProjectSourceT the way a project is built: a module in BEGINMODULE, a class module’s code in BEGINCLASS, a UserControl’s code in BEGINCLASS ... USERCONTROL (its header is kept in ctlTexts), a form’s code section in BEGINFORM with its controls (the .frm text is kept in frmTexts), a lone program unwrapped. Records the file in the source map.
- basBuildConcatProject
-
Read every file an open .dbp names (modules, class modules, UserControls, forms) into a BasProjectSourceT through basBuildAddSource.
- basBuildCompile
-
Compile source into a BasModuleT that carries the project information it is given (a BasProjectInfoT, NULL for none: basBuildProjectInfo makes it from a project’s metadata), the App object’s values and Err.Source’s project name, with OPTION EXPLICIT and an optional BasCtrlValidatorT. A BasCompileErrorT says why it failed: BAS_COMPILE_ERROR (line, column, message), BAS_COMPILE_NO_MEMORY, or BAS_COMPILE_NO_MODULE. An optional unit callback runs after each statement or procedure compiled (basCompilerSetUnitFn), so a long compile can let other work go on.
- basBuildErrorText
-
A compiler message without its "Line N, Col M: " prefix.
- basBuildMapLine
-
Line of the concatenated source to file and file line.
- basBuildMapFileLine
-
File and file line to the line of the concatenated source (names compared as DOS does: any case, / and \ alike).
- basBuildSpecFromProject
-
Fill a BasBuildSpecT’s project metadata from an open .dbp.
- basBuildProjectName
-
The name a project goes by: its Name, else "BASIC App". A program’s NAME resource, the name of its screen window (App.Title), and the project name basBuildCompile gives its module are this.
- basBuildProjectInfo
-
A BasProjectInfoT (one text per BasProjectInfoE: Name, Version, Publisher, Description, Copyright, Trademarks, Product, Comments) from a BasBuildSpecT’s project metadata, the name basBuildProjectName’s: what basBuildCompile gives the module.
- basBuildApp
-
Build an .app from a module, the .frm texts, and the .ctl headers (ctlSources). A NULL selfPath takes the stub from BAS_BUILD_STUB_CARRIER (this library).
- basBuildControl
-
Build a control file (.wgt, resources only) from a control project’s module and .ctl headers: the module, each header as CTLn with its toolbox icon24 and name resources, the project’s metadata, and help file. The IDE’s Make Control and CompBuildApp of a control project.
- basBuildIsControlProject
-
True when an open .dbp is a control project ([Project] Type = Control).
- basBuildWrapForPath
-
The kind of a project file by its extension.
11.4.2. Validating Control Members (basValidate.h)
A BasValidatorT (zeroed) collects the forms, controls, and menu items of the .frm texts basValidateScanFrm parses; its onCode hook also receives each form’s code section, so one parse serves both. basValidateCallbacks fills the BasCtrlValidatorT the compiler takes; pass &validator.compiler as basBuildCompile’s liveCompiler so a control name resolves on the form whose code is compiled. Member names are checked against the loaded widget interfaces (WgtIfaceT) and the form runtime’s own property tables. badTypes lists controls whose type no loaded widget library registers (BAS_VALIDATE_BAD_TYPE_FMT formats one). The command-line compiler does not validate: no widget library is loaded there.
11.4.3. Debugging (basDebug.h)
Every function takes the paused program’s VM (or NULL when there is none). The ones that run a snippet (basDbgEval, basDbgExec, basDbgSetVar, basDbgRunSnippet) take a BasDbgPumpT too (NULL for none): its fn(ctx) runs between the snippet’s slices, so a long snippet lets other work go on (the IDE shows a frame with input held off; compiler.bas lets the other tasks run).
| Function | Description |
|---|---|
basDbgCurProcIdx |
The compiled procedure the paused VM is in (-1: module level). |
basDbgProcNameForPc |
Procedure name holding a code address (BAS_DBG_MODULE_FRAME before every procedure); a form’s procedure as Form.Proc. |
basDbgVarVisible |
Whether a debug variable is in scope where the VM is paused (QBasic rules: SHARED, STATIC, form, and member variables). |
basDbgFindVar |
The visible debug variable of a name. |
basDbgVarSlot |
The live value slot of a debug variable. |
basDbgResolvePath |
The live slot of var, var(i, j), var.field, or var(i).field (a TYPE field or a class member). |
basDbgFormatValue |
Display text of a value (strings quoted, #dates#, array bounds, class names, Collection item counts). |
basDbgLocals |
The visible variables as rows (name, type, value) through a BasDbgRowFnT. |
basDbgCallStack |
The call stack as rows (procedure, line); a form’s procedure as Form.Proc. |
basDbgEval |
A watch: a variable path read directly, any other expression compiled and run as a snippet. |
basDbgExec |
An Immediate-window line: assignment to the paused program’s variable, a statement, or an expression to print. |
basDbgSetVar |
Set a variable path to the value of an expression (scalars). |
basDbgSnippetVm |
Compile a snippet whose globals are the paused program’s visible variables, with their values copied in. |
basDbgRunSnippet |
Run a snippet in bounded slices (an endless loop is abandoned). |
basDbgAppendDropping |
Append to a fixed output buffer, dropping the oldest lines. |
11.4.4. Procedures (basProcs.h)
basProcDeclAt, basProcSkipToEnd, and basProcNameFromDecl find the SUB / FUNCTION blocks of source text without compiling it (BAS_PROC_KW_END_SUB / BAS_PROC_KW_END_FUNCTION end them). The IDE’s one-procedure-at-a-time editor and CompProcList$ use them.
11.4.5. Source Text (basSource.h)
Source text read with the compiler’s lexer, line by line, on text that need not compile: basSourceTokens reports every token with its kind (BasSrcKindE: keyword, identifier, string, number, date, symbol, comment, error), line, column, and source span; basSourceInCode tells whether an offset is code (not in a string literal or a comment); basSourceRename renames a form or control (oldName followed by '.' or '_' as a whole word), optionally only in code; basSourceWithEvents and basSourceClassEvents report the WithEvents variables and the Events of a class module or a form’s code. The IDE’s rename (ideRenameInCode, also after the Menu Editor renames items) and its Object / Event lists use them; compiler.bas has CompTokens$, CompInCode, CompRenameInCode$, CompWithEvents$, and CompClassEvents$.
11.4.6. Help Topics (basHelpMap.h)
basHelpKeywordTopic gives the DVX BASIC help topic of a keyword or built-in function (NULL for none) and basHelpCtrlTopic the topic of a control type (BAS_HELP_CTRL_PREFIX and the type name in lower case): what F1 opens in the IDE, and CompHelpTopic$ / CompHelpCtrlTopic$.
11.4.7. Projects (basProject.h)
The project (.dbp) model: PrjStateT with its file list (PrjFileT: path relative to the project’s folder, kind — PrjFileKindE: module, class module, UserControl ([Controls], .ctl), or form, in compile order — edit buffer) and settings, prjLoad / prjSave (one table of [Project] / [Settings] / [Package] keys and [Resources] Strings drives load, save, prjFieldGet, and prjFieldSet; [Project] Type = Control makes a control project, prjIsControlProject), prjNew, prjAddFile, prjRemoveFile, prjRenameFile (disk and project together), prjFileIndexByPath, prjKindForPath (the build’s rule, basBuildWrapForPath), prjKindWrap, prjClassName (a class module’s or UserControl’s class name), prjReadFileText, the fonts the program carries ([Fonts]: prjAddFont, prjRemoveFont, prjFontCount, prjFontPath; the build makes them FONTn font resources, basBuildSpecT fonts), the files it carries as resources ([Resources]: prjAddResource, prjRemoveResource, prjResourceCount, prjResourcePath, with the string table in stringTable; the build makes them RES:KEY resources and STRINGS, basBuildSpecT resFiles and stringTable, checked with basBuildResCheck), and the source map of the last compile (prjMapLine, prjMapFileLine). The IDE keeps only its Project window and Properties dialog (ideProject.c); compiler.bas has ProjOpen, ProjNew, ProjSave, ProjClose, ProjPath$, ProjFileCount, ProjFile$, ProjFilePath$, ProjFileKind, ProjFileFind, ProjAddFile, ProjRemoveFile, ProjRenameFile, ProjFontCount, ProjFont$, ProjAddFont, ProjRemoveFont, ProjResourceCount, ProjResource$, ProjAddResource, ProjRemoveResource, ProjGet$, and ProjSet; CompKeywordClass and CompKeywordReserved expose the keyword table’s flags.
A UserControl’s header (the Begin UserControl block of a .ctl) is read and changed key by key, every other line of the text kept: prjCtlKeyAt / prjCtlKeyFind give the keys (PrjCtlKeyT: name and PrjCtlValueE kind — Name, the control’s name on the Begin line, then Width, Height, CanGetFocus, BackColor, ToolboxIcon, Description, DefaultEvent), prjCtlHeaderGet the value the control takes (its default when the header leaves the key out), prjCtlHeaderSet a malloc’d copy of the text with one key changed, added before End, or removed (an empty value), written as its kind is (a text in quotes, a color &HBBGGRR&, True or False), and prjCtlNew the text of a new UserControl (its header with Width and Height, Option Explicit, an empty UserControl_Paint written with PRJ_HANDLER_FMT and PRJ_PRIVATE, the form the IDE writes event handlers in). The IDE’s File > New UserControl and Properties window use them; compiler.bas has ProjCtlNew$, ProjCtlHeader$, ProjCtlSetHeader$, and ProjCtlKeys$ (the keys and their kinds, prjCtlKeyAt order).
11.4.8. Running a Program (basRunHost.h, in basrt.lib)
basRunHostCreate makes the VM and form runtime for a module from a BasRunSpecT: App.Path, App.User (from the program’s file: its folder in the user folder), App.Data (the DATA folder beside it), COMMAND$, the print, input, and DoEvents callbacks, the screen window’s name, the help file, where LoadResPicture, LoadResData, and LoadResString read the program’s resources (resFile: its .app, or its project’s .dbp, whose [Resources] files are read from the project’s folder; NULL: the program’s file), whether runtime errors show their own box, whether it is a standalone program (the stub’s own: the runtime owns the module and frees it with itself), and whether it ends with its program (endWithApp: the IDE’s runs, on a task of their own). A standalone runtime and one made with endWithApp are ended through the shell’s kill hook, shellRegisterAppKill, when the program they run for is ended by force; basdev ends its runs itself. A runtime made on one task and run on another (the IDE makes it in a menu command and runs it on a work task, shellAppTaskStart) is moved with basFormRtAdopt, and basFormRtYield lets the other tasks run once without running any of the program’s events. basRunHostRegisterFrm registers a .frm text, basRunHostLoadStartupForm loads and shows the startup form (the program’s other forms load when its code first refers to them), basRunHostSlice runs module code once under the step limit (an error’s message and line are always set afterwards), basRunHostAlive says whether the event-loop phase goes on, basRunHostTagBreak puts BAS_RUN_BREAK_TAG on the captions while paused, and basRunHostDestroy ends it. The runtime made inside another program’s code does not become the current runtime (basFormRtCurrent / basFormRtSetCurrent); each of these calls makes it current while its code runs.
VM accessors a debugger host uses (vm.h): basVmSetAppPaths, basVmSetBreakpointCallback, basVmSetDebugPaused, basVmResume, basVmStop, basVmClearStepState, basVmGetCurrentLine, basVmGetErrorLine.
11.4.9. From BASIC
compiler.bas and debug.bas declare the entry points (see Include Libraries in the BASIC language reference). Source sets, modules, and runs are handles freed with their program. A run is polled: RunPoll runs the child for a bounded time and never waits. A pause in the child’s module code returns RUN_PAUSED; a pause inside one of its event handlers (or its forms' Load code, inside RunStart) waits in place while the child pumps DVX events, so the caller’s Timer and menus can step, continue, or stop it; RunPoll called from there returns at once. RunFree while the child’s code is on the stack stops it at once and releases it at the next library call after that code has unwound.
CompDesignControls registers a source set’s UserControls for the calling program’s design forms (basCtlLoadDesign with its runtime, the current one: a child run’s own when the child calls it) and holds the module — one of the caller’s own handles; another program’s is refused — until CompDesignRelease, the next CompDesignControls, or the end of that runtime (appEnded for a program, runDestroyHost for a child run), CompModuleFree meanwhile only marking it.
11.5. The .frm Model
A form file as data, with no widgets and no windows: the form’s properties, its controls (type, name, control array index, parent, the built-in size and state fields, and every other "Key = Value" pair as text), its menu items, and its code section. frmModelLoad reads .frm text (through frmParse) and frmModelWrite writes the canonical text the DVX BASIC IDE saves. The IDE’s designer, properties window, menu editor, and copy and paste all work on this model and keep only their live widgets on the side (each control’s userData); designer.bas binds it for BASIC programs (the Frm* functions, basdev/frmModelBas.c).
Header: apps/dvxbasic/basdev/frmModel.h (part of basdev.lib)
11.5.1. Types
| Type | Description |
|---|---|
FrmModelT |
A form: name, caption, width / height / left / top, padding, spacing, windowState, layout, helpTopic, contextMenu, centered / autoSize / resizable, controls (stb_ds array of FrmCtrlT pointers in tree order: each control directly followed by its children), menuItems (stb_ds array), props (other runtime form properties that were set: Icon, Tag, MousePointer, the Font properties ...), code (malloc’d, NULL = none), dirty (changed by an edit since it was made or loaded). |
FrmCtrlT |
A control: name, typeName, parentName + parentIndex (the parent’s control array index, so a child of one member of a container array belongs to that member), index (FRM_NO_INDEX: not in an array), left, top, width (MinWidth), height (MinHeight), maxWidth, maxHeight, weight, dragMode, helpTopic, visible, enabled, props (stb_ds array of FrmPropT: every other key, unquoted), userData (the caller’s; the model never reads it and loads, copies, and pastes start it at NULL). |
FrmMenuItemT |
A menu item: caption ("-" for a separator), name, shortcut, shortcutText, level (0: a menu-bar menu or a popup; 1: its items; 2+: submenus), id (an editor identity, see frmModelMenuReplace), checked, checkable (Checked was written), radioCheck, enabled, visible (False on a level-0 item: a popup menu). |
FrmPropT |
One stored "Key = Value": name, value. |
FrmIntPropT |
One built-in integer property (Left, Top, MinWidth alias Width, MinHeight alias Height, MaxWidth, MaxHeight, Weight, DragMode): name, alias, offset into FrmCtrlT, saveRule (FRM_SAVE_ALWAYS / IF_NONZERO / IF_POSITIVE). |
Only values somebody set are stored and written: a property a control has by default (a PictureBox’s BorderStyle, a TextBox’s MaxLength) is not in the model and not in the file. Values are written in the canonical form for their widget interface type, or for a key the widget does not know, for their type in the runtime’s common property table (STRING quoted, BOOL True / False, INT a number, FLOAT and ENUM unquoted); other keys are written as quoted strings. The limits come from the parser’s: FRM_MAX_NEST_DEPTH control levels, FRM_MAX_MENU_LEVEL menu levels, and no property line longer than FRM_MAX_LINE_LEN - 1 characters (the writer fails with FRM_WRITE_LINE_TOO_LONG rather than write one the parser would cut).
11.5.2. Loading and Writing
| Function | Description |
|---|---|
frmModelNew(name) |
A blank form with the runtime form’s defaults. |
frmModelLoad(text, len) |
The model of .frm text; NULL when it is not a form (no Begin Form, frmParse refuses it, two controls share a name and index) or out of memory. A Key = Value line is the innermost open block’s, also after the blocks inside it, as the runtime reads it; a child names its container by the container’s final Index. Of several OptionButtons of one container saved with Value True, the last keeps it. |
frmModelFree(m) |
Frees the model, its controls, and menus. |
frmModelWrite(m, buf, bufSize) |
The .frm text into buf: its length, or FRM_WRITE_TOO_LARGE / FRM_WRITE_LINE_TOO_LONG (never a partial text). |
frmModelWriteSize(m) |
A buffer size that always holds the text. |
frmModelText(m, &len) |
The text in a new malloc’d string; NULL with len set to the FRM_WRITE_* code. |
frmModelSetCode(m, code) |
Replaces the code section. |
frmCodeSection(trailing, len, &outLen) |
The code section of the text after a form’s End (blank lines skipped, the first code line keeps its indent). |
frmModelFromForm(rt, form) |
A model of a loaded form as it is now: its properties, its controls in their containers with each property that differs from a new control of the type (compared with one made in a hidden window; the six Font properties of the form and of each control that has a font of its own), its menus; no code. What FormText$ writes. |
11.5.3. Properties
| Function | Description |
|---|---|
frmModelFormProp(m, name, out, size) |
A form property as text (an unset design property gives "", "0", or "False"); false for run-time-only ones (Visible, DesignMode, DesignSelection, object properties). |
frmModelSetFormProp(m, name, value) |
Sets one from text; Name renames the form; an empty value takes an optional one out. |
frmCtrlPropText(ctrl, name, out, size) |
A control property as the control holds it (Name, Index, the built-in integers, HelpTopic, Visible / Enabled unless the widget defines them, the stored ones). |
frmCtrlSetPropText(ctrl, key, value) |
Applies one the way the loader does (a VB TabIndex is dropped unless the widget defines it). |
frmModelSetCtrlProp(m, ctrl, name, value) |
The same with an editor’s rules: Name renames the control (frmModelRenameCtrl), Index makes an array member (or none) after frmModelIndexCheck’s checks (false when refused), then the OptionButton group rule. |
frmCtrlGetProp / frmCtrlSetProp / frmCtrlRemoveProp |
The stored properties. |
frmIntPropAt / frmIntPropFind / frmIntPropGet / Set |
The built-in integer table. |
frmIfaceProp(typeName, propName) |
The widget interface property of a type, NULL when none. |
11.5.4. Font Properties
FontName, FontSize, FontBold, FontItalic, FontUnderline, and FontStrikethru (BAS_PROP_FONT*) are in both the form table and the common control table. They are one font, a DvxFontChoiceT (dvxDlg.h: family, size in pixels, FONT_STYLE_* flags), and the widget’s font (wgtFont, wgtSetFont) is the only place they live: a read gives the font the object draws with (a form’s is its root widget’s), a write gives it that font with the one part changed. The .frm loader collects a block’s Font properties and opens one font when the block’s properties are read, so their order in the file does not matter. Helpers in formrt.h, for loaders and designers that hold them as .frm text:
| Function | Description |
|---|---|
basFontPropAt(idx) |
The Font property names in .frm order (FontName, FontSize, then the flags), NULL past the end. |
basFontPropIs(name) |
True for a Font property name (any case). |
basFontChoiceOf(font, out) |
A BitmapFontT as the properties name it (dvxFontFamilyOf, pixelSize, style). |
basFontPropText(choice, name, out, size) |
One property of a choice as .frm text (the family, the size, True / False). |
basFontPropSetText(choice, name, text) |
Sets one property of a choice from .frm text. |
11.5.5. Editing Controls
| Function | Description |
|---|---|
frmModelAddCtrl(m, typeName, name, parent) |
Adds a control as the last child of parent (NULL: the form); name "" or NULL gives a free one (frmModelAutoName); Caption = its name. NULL when the name is taken or parent cannot hold it. |
frmModelRemoveCtrl(m, ctrl) |
Removes ctrl and its subtree. |
frmModelRenameCtrl(m, ctrl, newName) |
Renames ctrl alone, as Visual Basic does: an element of a control array leaves it with its Index (an element of an array of the new name) and the other elements keep the name. Its children follow it, and once no control keeps the old name the DataSource / MasterSource of a renamed Data control too. False when newName is "" or another control’s, the form’s, or a menu item’s (frmModelJoinArray joins another control’s array). Identifier rules are the caller’s. |
frmModelMakeArrayMember(m, ctrl, index) |
Gives a control array index; its children follow. |
frmModelIndexCheck(m, ctrl, text, &index, reason, size) |
The designer’s Index edit with Visual Basic’s checks: "" (no array) or 0 to 32767 that no other control of the name has; a control whose name others share keeps an Index, and gets none while one of them has none. False with the reason. |
frmModelJoinArray(m, ctrl, name) |
Rename ctrl to the name of other controls of its type, an element of their control array (a lone control of that name becomes element 0, ctrl takes the next Index; an element of another array leaves that one), as Visual Basic does on such a rename. |
frmModelMoveCtrl(m, ctrl, before) |
Moves ctrl with its subtree before a sibling (NULL: after the last). |
frmModelReparent(m, ctrl, parent) |
Makes ctrl the last child of another container (refuses cycles, non-containers, and too deep a nesting). |
frmModelSibling(m, idx, dir) |
The sibling next to a control (+1 after its subtree, -1 before). |
frmModelFindCtrl / CtrlPos / FindParent / CtrlDepth |
Lookups. |
frmModelIsDescendant / SubtreeEnd / NormalizeOrder |
The tree order. |
frmModelNameInUse / AutoName / OptionSelected |
Names and the OptionButton group rule. |
frmModelCtrlText(m, ctrl, &len) |
ctrl and its children as .frm control blocks (a copy for the Clipboard). |
frmModelCtrlsFromText(text, len) |
Copied blocks read into a scratch model. |
frmModelInsertTree(m, src, srcRoot, parent, name, index) |
Moves a subtree out of the scratch model into m: the root takes name / index (NULL: its own name when free, else a free one); a child whose name is taken gets a free one, the members of one array together; children follow their renamed parents. |
11.5.6. Menus
The frmMenu* functions work on any stb_ds array of FrmMenuItemT (an editor’s working copy as well as m->menuItems) and keep the levels a tree.
| Function | Description |
|---|---|
frmMenuItemInit(mi) |
A blank item (enabled, visible, level 0). |
frmMenuInsert(&items, at, level) |
Inserts a blank item; the level is clamped so the menus stay a tree. |
frmMenuRemove(&items, idx) |
Removes an item with its subtree. |
frmMenuMove(&items, idx, dir) |
Moves an item with its subtree past its previous / next sibling; its new position or FRM_NO_INDEX. |
frmMenuIndent(items, idx, delta) |
Indents / outdents an item with its subtree (at most one level below the item above, not past FRM_MAX_MENU_LEVEL). |
frmMenuSubtreeEnd / CheckLevels / StripBlank / AutoName |
Tree helpers; AutoName makes mnuSep1 ... or "mnu" plus the caption’s letters and digits. |
frmMenuPropText / frmMenuSetPropText |
Menu properties as text (Checked makes a check item). |
frmModelMenuValidate(m, items, reason, size) |
The checks before items replace m’s menus (levels; every name set, an identifier as the compiler takes one, not the form’s or a control’s, unique; every Shortcut a key): the first bad item and the reason. |
frmModelMenuReplace(m, items) |
Replaces m’s menus by a copy; ContextMenu bindings follow renamed items, matched by id (give every item id = position + 1 before editing). |
frmModelSetMenuProp(m, idx, key, value) |
Sets an item’s property; a Name rename refuses a taken name and ContextMenu bindings follow. |
// Load a form, rename a control, add a label inside a frame, save.
FrmModelT *m = frmModelLoad(text, len);
if (m) {
int32_t at = frmModelFindCtrl(m, "Frame1", FRM_NO_INDEX);
int32_t cmd = frmModelFindCtrl(m, "Command1", FRM_NO_INDEX);
FrmCtrlT *frame = (at >= 0) ? m->controls[at] : NULL;
FrmCtrlT *lbl = frmModelAddCtrl(m, "Label", "", frame);
int32_t outLen = 0;
if (cmd >= 0) {
frmModelRenameCtrl(m, m->controls[cmd], "cmdOk");
}
frmModelSetCtrlProp(m, lbl, "Caption", "Name:");
char *out = frmModelText(m, &outLen);
// write out[0 .. outLen) to the file
free(out);
frmModelFree(m);
}
Index
# A B C D E F G H I J K L M N O P R S T U V W X Y Z
#
A
- ABI stamp, 1.11. DXE Module System
- ABI version, 2.2. dvxTypes.h — Shared Type Definitions
- AccelEntryT, 2.2. dvxTypes.h — Shared Type Definitions
- Accelerator Tables, 1.12. Event Model
- accelParse, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- AccelTableT, 2.2. dvxTypes.h — Shared Type Definitions
- accept, 8.2. The Socket API
- Add-on packages, 9.1. Package Library
- ANSI Music, 4.1. AnsiTerm
- AnsiTerm, 4.1. AnsiTerm
- ANSITERM_EVT_BELL, 4.1. AnsiTerm
- ANSITERM_EVT_MUSIC, 4.1. AnsiTerm
- ANSITERM_EVT_SEND, 4.1. AnsiTerm
- AnsiTermExApiT, 4.1. AnsiTerm
- Anti-aliasing, 1.13. Font System
- API Reference, 2.1. DVX GUI API Reference
- AppContextT, 2.12. dvxApp.h — Layer 5: Application API
- AppDescriptorT, 3.2.2. Constants
- AppStateE, 3.2.2. Constants
- Architecture, 1.1. DVX Architecture Overview
- Assembly, 1.15. Platform Layer
- assert, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- ASSOC.INI, 3.12. File Associations
- atexit, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- audio, 10.1. Sound Library
- audio.h, 10.1. Sound Library
- AUDIO_WT_PITCH_RATE, 10.1. Sound Library
- audioClose, 10.1. Sound Library
- audioDecode, 10.1. Sound Library
- audioDeskFile, 10.1. Sound Library
- audioDeskPlay, 10.1. Sound Library
- audioDeskPlayFile, 10.1. Sound Library
- audioDeskSetFile, 10.1. Sound Library
- audioDriverNames, 10.1. Sound Library
- AudioDriverT, 10.1. Sound Library
- audioDrv.h, 10.1. Sound Library
- audioFmAlloc, 10.1. Sound Library
- audioFmRawAcquire, 10.1. Sound Library
- audioFmWrite, 10.1. Sound Library
- audioGetInfo, 10.1. Sound Library
- AudioInfoT, 10.1. Sound Library
- audioMidiAcquire, 10.1. Sound Library
- audioMidiChoices, 10.1. Sound Library
- audioMidiInOpen, 10.1. Sound Library
- audioMidiInRead, 10.1. Sound Library
- AudioMidiMsgT, 10.1. Sound Library
- audioModulesChoices, 10.1. Sound Library
- audioNotesAdd, 10.1. Sound Library
- audioNotesOpen, 10.1. Sound Library
- audioNotesSetTone, 10.1. Sound Library
- AudioNotesT, 10.1. Sound Library
- audioOpen, 10.1. Sound Library
- audioPercentToVolume, 10.1. Sound Library
- audioPlay, 10.1. Sound Library
- audioPlayFile, 10.1. Sound Library
- audioRecCancel, 10.1. Sound Library
- audioRecClose, 10.1. Sound Library
- audioRecEnded, 10.1. Sound Library
- audioRecFile, 10.1. Sound Library
- audioRecOpen, 10.1. Sound Library
- audioRecPause, 10.1. Sound Library
- audioRecPush, 10.1. Sound Library
- audioRecRead, 10.1. Sound Library
- audioRecResume, 10.1. Sound Library
- audioSampleLoad, 10.1. Sound Library
- audioSettingModules, 10.1. Sound Library
- audioSettingsStore, 10.1. Sound Library
- audioStreamEnd, 10.1. Sound Library
- audioStreamFlush, 10.1. Sound Library
- audioStreamOpen, 10.1. Sound Library
- audioStreamWrite, 10.1. Sound Library
- AudioSynthDriverT, 10.1. Sound Library
- audioTone, 10.1. Sound Library
- audioVoicePause, 10.1. Sound Library
- audioWavHeader, 10.1. Sound Library
- audioWavParse, 10.1. Sound Library
- audioWtAlloc, 10.1. Sound Library
- audioWtMemAlloc, 10.1. Sound Library
- audioWtNoteInit, 10.1. Sound Library
- audioWtStart, 10.1. Sound Library
- audioWtUpload, 10.1. Sound Library
- AudioWtVoiceT, 10.1. Sound Library
B
- Backbuffer, 1.3. Display Pipeline
- basArrayNew, 11.2. Value System
- BasArrayT, 11.1. BASIC Runtime Library, 11.2. Value System
- basBuildAddSource, 11.4. BASIC Development Library
- basBuildCompile, 11.4. BASIC Development Library
- basBuildMapFileLine, 11.4. BASIC Development Library
- basBuildProjectInfo, 11.4. BASIC Development Library
- basBuildProjectName, 11.4. BASIC Development Library
- basDbgEval, 11.4. BASIC Development Library
- basDbgExec, 11.4. BASIC Development Library
- basDbgLocals, 11.4. BASIC Development Library
- basdev, 11.4. BASIC Development Library
- basFontChoiceOf, 11.5. The .frm Model
- basFontPropText, 11.5. The .frm Model
- basFormRtTermBind, 7.8. Connections from BASIC
- basHelpKeywordTopic, 11.4. BASIC Development Library
- BASIC Development Library, 11.4. BASIC Development Library
- BASIC Runtime, 11.1. BASIC Runtime Library
- BasModuleT, 11.1. BASIC Runtime Library, 11.3. Virtual Machine
- basProject.h, 11.4. BASIC Development Library
- BasProjectInfoT, 11.4. BASIC Development Library
- basRunHostCreate, 11.4. BASIC Development Library
- basRunHostSlice, 11.4. BASIC Development Library
- basSourceRename, 11.4. BASIC Development Library
- basSourceTokens, 11.4. BASIC Development Library
- basStringNew, 11.2. Value System
- BasStringT, 11.1. BASIC Runtime Library, 11.2. Value System
- BasUdtT, 11.2. Value System
- basValCopy, 11.2. Value System
- basValidateScanFrm, 11.4. BASIC Development Library
- basValRelease, 11.2. Value System
- BasValueT, 11.1. BASIC Runtime Library, 11.2. Value System
- basVmCallSub, 11.3. Virtual Machine
- basVmCreate, 11.3. Virtual Machine
- basVmDestroy, 11.3. Virtual Machine
- BasVmResultE, 11.3. Virtual Machine
- basVmRun, 11.3. Virtual Machine
- basVmStep, 11.3. Virtual Machine
- BasVmT, 11.1. BASIC Runtime Library, 11.3. Virtual Machine
- BBS Client, 7.6. End-to-End Example
- Bevel, 1.14.1. Pixel Format
- BevelStyleT, 2.2. dvxTypes.h — Shared Type Definitions
- Bitmap Font, 1.13. Font System
- BitmapFontT, 1.13. Font System, 2.2. dvxTypes.h — Shared Type Definitions, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- BlitOpsT, 1.3. Display Pipeline, 2.2. dvxTypes.h — Shared Type Definitions
- Boot Sequence, 1.11. DXE Module System
- BSD sockets, 8.1. Networking Library
- Build, 1.16.1. Cross-Compilation
- Button, 4.4. Button
C
- C Library, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- Cancel button, 2.12. dvxApp.h — Layer 5: Application API
- Canvas, 4.5. Canvas
- Canvas backdrop, 4.5. Canvas
- CANVAS_BORDER_FIXED, 4.5. Canvas
- CANVAS_BORDER_NONE, 4.5. Canvas
- CANVAS_BORDER_WIDTH, 4.5. Canvas
- Checkbox, 4.6. Checkbox
- Chrome, 1.4.1. WindowT Structure
- clearOtherSelections, 5.3. clearOtherSelections
- Clipboard, 5.14. widgetTextEditOnKey
- Color Dialog, 2.15. dvxDlg.h — Modal Dialogs
- ColorIdE, 2.2. dvxTypes.h — Shared Type Definitions
- Colors, 1.14.1. Pixel Format
- ColorSchemeT, 1.14.1. Pixel Format, 2.2. dvxTypes.h — Shared Type Definitions
- COM Port, 7.2. RS-232 UART Driver
- ComboBox, 4.7. ComboBox
- Common Events, 4.2.1. DVX Widget System
- Common Properties, 4.2.1. DVX Widget System
- compiler.bas, 11.4. BASIC Development Library
- Compositing, 1.3. Display Pipeline
- conn, 7.7. Connection Library
- conn.bas, 7.8. Connections from BASIC
- ConnAttach, 7.8. Connections from BASIC
- ConnConfigT, 7.7. Connection Library
- ConnCreate, 7.8. Connections from BASIC
- connect, 8.2. The Socket API
- Connection, 7.7. Connection Library
- ConnPoll, 7.8. Connections from BASIC
- connSetWindowSize, 7.7. Connection Library
- convertColor, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- convertPixels, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- Cooperative, 1.12. Event Model
- Cooperative Multitasking, 3.16. libtasks — Cooperative Task Switching
- Cooperative multitasking, 8.3.1. Waiting, Polling, and Cooperative Multitasking
- Covox, 10.1. Sound Library
- CP437, 1.13. Font System, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- Crash Recovery, 1.11. DXE Module System
- CRC, 7.11.1. XMODEM and XMODEM-1K
- CRC-16, 7.5. Packet Transport
- Critical Error Handler, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- Cross-Compilation, 1.16.1. Cross-Compilation
- Cursor, 1.12. Event Model
- Cursor Blink, 5.2. wgtUpdateCursorBlink
- Cursor Shapes, 2.3. dvxCur.h — Cursor Definitions
- CURSOR_ARROW, 2.3. dvxCur.h — Cursor Definitions
- CURSOR_BUSY, 2.3. dvxCur.h — Cursor Definitions
- CURSOR_NO_DROP, 2.3. dvxCur.h — Cursor Definitions
- CursorT, 2.2. dvxTypes.h — Shared Type Definitions
- Custom Dialogs, 2.15. dvxDlg.h — Modal Dialogs
D
- DataActionE, 4.8. DataCtrl
- Database, 6.3. dvxSql — SQL Database Interface
- Database Binding, 4.8. DataCtrl
- Database Grid, 4.9. DbGrid
- DataCtrl, 4.8. DataCtrl
- DbGrid, 4.9. DbGrid
- debug.bas, 11.4. BASIC Development Library
- Default button, 2.12. dvxApp.h — Layer 5: Application API
- Desktop sounds, 10.1. Sound Library
- DFN, 1.13. Font System, 2.5. dvxText.h — Fonts
- dfnCp437, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- dfnFromUnicode, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- dfnTextFromUnicode, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- dfnTextToUnicode, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- Dialer, 7.7. Connection Library
- Dialogs, 1.6. Modal Dialogs (dvxDlg.h)
- Diffie-Hellman, 7.3. Cryptography Library
- Dirty Rects, 1.3. Display Pipeline
- dirtyListAdd, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- dirtyListClear, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- dirtyListInit, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- dirtyListMerge, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- DirtyListT, 1.3. Display Pipeline, 2.2. dvxTypes.h — Shared Type Definitions
- Disabled windows, 2.12. dvxApp.h — Layer 5: Application API
- Disney Sound Source, 10.1. Sound Library
- Display Pipeline, 1.3. Display Pipeline
- DisplayT, 1.3. Display Pipeline, 2.2. dvxTypes.h — Shared Type Definitions
- DJGPP, 1.1. DVX Architecture Overview
- DOS programs, 2.12. dvxApp.h — Layer 5: Application API, 3.10. Running Programs and Documents
- Double Buffer, 1.3. Display Pipeline
- Double-Click, 1.12. Event Model
- DPK files, 9.1. Package Library
- DPMI, 1.1. DVX Architecture Overview
- Drag Feedback, 2.12. dvxApp.h — Layer 5: Application API
- Drag Select, 5.12. widgetTextEditDragUpdateLine
- drawArrowGlyph, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawBevel, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawChar, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawFocusRect, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawFocusRectDots, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawHLine, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawInit, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawMaskedBitmap, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawScrollbar, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawScrollbarArrow, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawScrollbarArrowButton, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawTermRow, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawText, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawTextAccel, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawTextN, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawTextScaled, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- drawVLine, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- DRBG, 7.3. Cryptography Library
- Driver Modules, 2.13. dvxDrv.h — Driver Modules
- Dropdown, 4.10. Dropdown
- DVX, 1.1. DVX Architecture Overview
- DVX API, 2.1. DVX GUI API Reference
- DVX SDK, About This Reference
- DVX Shell, 3.1. DVX Shell Library
- DVX.COM, 3.10. Running Programs and Documents
- DVX_ABI_STAMP, 2.2. dvxTypes.h — Shared Type Definitions
- DVX_ABI_VERSION, 1.11. DXE Module System, 2.2. dvxTypes.h — Shared Type Definitions
- DVX_BUTTON_BOX_MAX, 2.15. dvxDlg.h — Modal Dialogs
- DVX_DRIVER_HDR, 2.13. dvxDrv.h — Driver Modules
- DVX_FNV_BASIS, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- DVX_HEX_DIGITS, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- DVX_HOTKEY_NONE, 2.12. dvxApp.h — Layer 5: Application API
- DVX_HUNG_APP_MS, 2.12. dvxApp.h — Layer 5: Application API
- DVX_IMAGE_PATTERNS, 2.12. dvxApp.h — Layer 5: Application API
- DVX_MEM_SYSTEM, 2.18.1. dvxMem.h — Per-App Memory Tracking
- DVX_SWITCH_BACK, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer, 3.10. Running Programs and Documents
- DVX_SWITCH_NEXT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer, 3.10. Running Programs and Documents
- DVX_SWITCH_RUN, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- dvxAccelFormat, 2.12. dvxApp.h — Layer 5: Application API
- dvxAccelKeyNames, 2.12. dvxApp.h — Layer 5: Application API
- dvxAccelParse, 2.12. dvxApp.h — Layer 5: Application API
- dvxAddAccel, 2.12. dvxApp.h — Layer 5: Application API
- dvxApp, 1.2. Five-Layer Architecture
- dvxApp.h, 2.12. dvxApp.h — Layer 5: Application API
- dvxAppHungForget, 2.12. dvxApp.h — Layer 5: Application API
- dvxAppIsHung, 2.12. dvxApp.h — Layer 5: Application API
- dvxApplyColorScheme, 2.12. dvxApp.h — Layer 5: Application API
- dvxArgAppend, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- dvxBeep, 2.12. dvxApp.h — Layer 5: Application API
- dvxButtonBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxCalloc, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxCascadeWindows, 2.12. dvxApp.h — Layer 5: Application API
- dvxChangeVideoMode, 2.12. dvxApp.h — Layer 5: Application API
- dvxChoiceDialog, 2.15. dvxDlg.h — Modal Dialogs
- dvxClipboardClear, 2.12. dvxApp.h — Layer 5: Application API
- dvxClipboardCopy, 2.12. dvxApp.h — Layer 5: Application API
- dvxClipboardGet, 2.12. dvxApp.h — Layer 5: Application API
- dvxCloseMenu, 2.12. dvxApp.h — Layer 5: Application API
- dvxColorDialog, 2.15. dvxDlg.h — Modal Dialogs
- dvxColorLabel, 2.12. dvxApp.h — Layer 5: Application API
- dvxColorName, 2.12. dvxApp.h — Layer 5: Application API
- dvxColorsFromPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxColorsToPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxComp, 1.2. Five-Layer Architecture
- dvxComp.h, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- dvxContentDisplay, 2.12. dvxApp.h — Layer 5: Application API
- dvxCrc16, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- dvxCreateAccelTable, 2.12. dvxApp.h — Layer 5: Application API
- dvxCreateWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxCreateWindowCentered, 2.12. dvxApp.h — Layer 5: Application API
- dvxCur.h, 2.3. dvxCur.h — Cursor Definitions
- dvxDestroyWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxDialogAddField, 2.15. dvxDlg.h — Modal Dialogs
- dvxDialogAddOkCancel, 2.15. dvxDlg.h — Modal Dialogs
- dvxDialogCreate, 2.15. dvxDlg.h — Modal Dialogs
- dvxDialogEnd, 2.15. dvxDlg.h — Modal Dialogs
- dvxDialogRun, 2.15. dvxDlg.h — Modal Dialogs
- dvxDlg.h, 2.15. dvxDlg.h — Modal Dialogs
- dvxDosBatch, 2.12. dvxApp.h — Layer 5: Application API
- dvxDragCursorSet, 2.12. dvxApp.h — Layer 5: Application API
- dvxDragFeedbackHide, 2.12. dvxApp.h — Layer 5: Application API
- dvxDragImageShow, 2.12. dvxApp.h — Layer 5: Application API
- dvxDragOutlineShow, 2.12. dvxApp.h — Layer 5: Application API
- dvxDraw, 1.2. Five-Layer Architecture
- dvxDraw.h, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- DvxDriverClassT, 2.13. dvxDrv.h — Driver Modules
- DvxDriverHeaderT, 2.13. dvxDrv.h — Driver Modules
- dvxDriverKeep, 2.13. dvxDrv.h — Driver Modules
- DvxDriverModT, 2.13. dvxDrv.h — Driver Modules
- dvxDriversFree, 2.13. dvxDrv.h — Driver Modules
- dvxDriversLoad, 2.13. dvxDrv.h — Driver Modules
- dvxDriverUnload, 2.13. dvxDrv.h — Driver Modules
- dvxDrv.h, 2.13. dvxDrv.h — Driver Modules
- dvxEndian.h, 2.19. dvxEndian.h — Byte Order
- DvxEntropyHookT, 2.12. dvxApp.h — Layer 5: Application API
- dvxErrorBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxExclusiveBegin, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveBlitOps, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveDisplay, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveEnd, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveFlush, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveMirror, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusivePresent8, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveSetPalette, 2.12. dvxApp.h — Layer 5: Application API
- dvxExclusiveWaitRetrace, 2.12. dvxApp.h — Layer 5: Application API
- dvxFileDialog, 2.15. dvxDlg.h — Modal Dialogs
- dvxFitWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxFitWindowH, 2.12. dvxApp.h — Layer 5: Application API
- dvxFitWindowW, 2.12. dvxApp.h — Layer 5: Application API
- dvxFlow.h, 2.6. dvxFlow.h — Flowing Text
- dvxFlowAddText, 2.6. dvxFlow.h — Flowing Text
- dvxFlowCaret, 2.6. dvxFlow.h — Flowing Text
- dvxFlowCreate, 2.6. dvxFlow.h — Flowing Text
- dvxFlowHitTest, 2.6. dvxFlow.h — Flowing Text
- dvxFlowLayout, 2.6. dvxFlow.h — Flowing Text
- dvxFlowLineOf, 2.6. dvxFlow.h — Flowing Text
- dvxFlowPaint, 2.6. dvxFlow.h — Flowing Text
- dvxFlowPaintSel, 2.6. dvxFlow.h — Flowing Text
- dvxFnvByte, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- dvxFnvBytes, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- dvxFont.h, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- dvxFontAddFile, 2.5. dvxText.h — Fonts
- dvxFontAddMemory, 2.5. dvxText.h — Fonts
- dvxFontAddResources, 2.5. dvxText.h — Fonts
- DvxFontChoiceT, 2.15. dvxDlg.h — Modal Dialogs
- dvxFontClose, 2.5. dvxText.h — Fonts
- dvxFontDialog, 2.15. dvxDlg.h — Modal Dialogs
- dvxFontFamilyCount, 2.5. dvxText.h — Fonts
- dvxFontFamilyFixed, 2.5. dvxText.h — Fonts
- dvxFontFamilyName, 2.5. dvxText.h — Fonts
- dvxFontFamilyOf, 2.5. dvxText.h — Fonts
- dvxFontLicence, 2.5. dvxText.h — Fonts
- dvxFontOpen, 2.5. dvxText.h — Fonts
- dvxFontRebuildStep, 2.5. dvxText.h — Fonts
- dvxFontRemoveOwner, 2.5. dvxText.h — Fonts
- dvxFontRescan, 2.5. dvxText.h — Fonts
- dvxFontRetain, 2.5. dvxText.h — Fonts
- dvxFontSetSmooth, 2.5. dvxText.h — Fonts
- dvxFontsFromPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxFontSizes, 2.5. dvxText.h — Fonts
- dvxFontSmooth, 2.5. dvxText.h — Fonts
- dvxFontSmoothBegin, 2.5. dvxText.h — Fonts
- dvxFontsToPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxFree, 1.10. Per-App Memory Tracking (dvxMem.h), 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxFreeAccelTable, 2.12. dvxApp.h — Layer 5: Application API
- dvxFreeImage, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetBe16, 2.19. dvxEndian.h — Byte Order
- dvxGetBe32, 2.19. dvxEndian.h — Byte Order
- dvxGetBlitOps, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetColor, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetColors, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetDisplay, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetFocusedWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetFont, 2.12. dvxApp.h — Layer 5: Application API
- dvxGetLe16, 2.19. dvxEndian.h — Byte Order
- dvxGetLe32, 2.19. dvxEndian.h — Byte Order
- dvxGetVideoModes, 2.12. dvxApp.h — Layer 5: Application API
- DVXGM.SF2, 10.2. Music Library
- dvxHash.h, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- dvxHexValue, 2.20.1. dvxHash.h — Hashes, Checksums, and Hex Digits
- dvxHideWindow, 2.12. dvxApp.h — Layer 5: Application API
- DvxHotkeyFnT, 2.12. dvxApp.h — Layer 5: Application API
- dvxIdleMs, 2.12. dvxApp.h — Layer 5: Application API
- dvxImageInfo, 2.12. dvxApp.h — Layer 5: Application API
- dvxImageInfoFromMemory, 2.12. dvxApp.h — Layer 5: Application API
- dvxInfoBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxInit, 2.12. dvxApp.h — Layer 5: Application API
- dvxInputBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxIntInputBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxInvalidateRect, 2.12. dvxApp.h — Layer 5: Application API
- dvxInvalidateWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxLibraryLoaded, 2.12. dvxApp.h — Layer 5: Application API
- dvxLoadImage, 2.12. dvxApp.h — Layer 5: Application API
- dvxLoadImageAlpha, 2.12. dvxApp.h — Layer 5: Application API
- dvxLoadImageFromMemory, 2.12. dvxApp.h — Layer 5: Application API
- dvxLoadTheme, 2.12. dvxApp.h — Layer 5: Application API
- dvxLog, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- dvxLowerWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxMalloc, 1.10. Per-App Memory Tracking (dvxMem.h), 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMaximizeWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxMem.h, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMemGetAppUsage, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMemGetRetained, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMemResetApp, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMemSetApp, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxMenuBarChanged, 2.12. dvxApp.h — Layer 5: Application API
- dvxMessageBox, 2.15. dvxDlg.h — Modal Dialogs
- dvxMinimizeWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxModalBegin, 2.12. dvxApp.h — Layer 5: Application API
- dvxModalEnd, 2.12. dvxApp.h — Layer 5: Application API
- dvxMouseFromPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxMouseToPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxMoveWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxnet, 8.1. Networking Library
- dvxNet.h, 8.4.1. Settings and Status (dvxNet.h)
- dvxPal.h, 2.7.1. dvxPal.h — 256-Color Palette for 8-bit Mode
- DVXPKG, 9.1. Package Library
- dvxPlat.h, 1.15. Platform Layer, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- dvxPlaySound, 2.12. dvxApp.h — Layer 5: Application API
- dvxPlaySoundWait, 2.12. dvxApp.h — Layer 5: Application API
- dvxPrefs.h, 2.17.1. dvxPrefs.h — INI Preferences System
- dvxPrefsBas.c, 2.17.1. dvxPrefs.h — INI Preferences System
- dvxPromptSave, 2.15. dvxDlg.h — Modal Dialogs
- dvxPutBe32, 2.19. dvxEndian.h — Byte Order
- dvxPutLe16, 2.19. dvxEndian.h — Byte Order
- dvxPutLe32, 2.19. dvxEndian.h — Byte Order
- dvxQuit, 2.12. dvxApp.h — Layer 5: Application API
- dvxRaiseWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxRealloc, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxRegisterHotkey, 2.12. dvxApp.h — Layer 5: Application API
- dvxRemoveAccel, 2.12. dvxApp.h — Layer 5: Application API
- dvxRequestWindowClose, 2.12. dvxApp.h — Layer 5: Application API
- dvxRes.h, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResAppend, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResClose, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResetColorScheme, 2.12. dvxApp.h — Layer 5: Application API
- dvxResFind, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- DvxResHandleT, 1.7. Resource System (dvxRes.h), 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResizeWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxResLoadData, 2.12. dvxApp.h — Layer 5: Application API
- dvxResLoadIcon, 2.12. dvxApp.h — Layer 5: Application API
- dvxResLoadIconData, 2.12. dvxApp.h — Layer 5: Application API
- dvxResLoadText, 2.12. dvxApp.h — Layer 5: Application API
- dvxResOpen, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResRead, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxResRemove, 2.16.1. dvxRes.h — DXE-Embedded Resource System
- dvxRestoreWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxRun, 2.12. dvxApp.h — Layer 5: Application API
- dvxRunDos, 2.12. dvxApp.h — Layer 5: Application API
- dvxSaveImage, 2.12. dvxApp.h — Layer 5: Application API
- dvxSaveTheme, 2.12. dvxApp.h — Layer 5: Application API
- dvxScreenshot, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetBusy, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetColor, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetFontSmoothing, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetInputEntropyHook, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetMenuCaption, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetMenuEnabled, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetMenuVisible, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetMouseConfig, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetSoundHook, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetTitle, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWaitPump, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWallpaper, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWallpaperMode, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWindowButtons, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWindowEnabled, 2.12. dvxApp.h — Layer 5: Application API
- dvxSetWindowIcon, 2.12. dvxApp.h — Layer 5: Application API
- dvxShowWindow, 2.12. dvxApp.h — Layer 5: Application API
- dvxShutdown, 2.12. dvxApp.h — Layer 5: Application API
- DvxSoundE, 2.12. dvxApp.h — Layer 5: Application API
- DvxSoundHookT, 2.12. dvxApp.h — Layer 5: Application API
- dvxSql, 6.3. dvxSql — SQL Database Interface
- dvxSqlAbandon, 6.4.1. dvxSqlOpen
- dvxSqlAffectedRows, 6.4.1. dvxSqlOpen
- dvxSqlClose, 6.4.1. dvxSqlOpen
- dvxSqlEof, 6.5. Cursor Operations
- dvxSqlError, 6.4.1. dvxSqlOpen
- dvxSqlEscape, 6.6.1. dvxSqlEscape
- dvxSqlExec, 6.4.1. dvxSqlOpen
- dvxSqlFieldByName, 6.5. Cursor Operations
- dvxSqlFieldCount, 6.5. Cursor Operations
- dvxSqlFieldDbl, 6.5. Cursor Operations
- dvxSqlFieldInt, 6.5. Cursor Operations
- dvxSqlFieldName, 6.5. Cursor Operations
- dvxSqlFieldText, 6.5. Cursor Operations
- dvxSqlFreeResult, 6.5. Cursor Operations
- dvxSqlNext, 6.5. Cursor Operations
- dvxSqlOpen, 6.4.1. dvxSqlOpen
- DvxSqlPumpFnT, 6.4.1. dvxSqlOpen
- dvxSqlQuery, 6.5. Cursor Operations
- dvxSqlSetPump, 6.4.1. dvxSqlOpen
- dvxStrdup, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxStrndup, 2.18.1. dvxMem.h — Per-App Memory Tracking
- dvxSystemKeyUse, 2.12. dvxApp.h — Layer 5: Application API
- dvxText.h, 2.5. dvxText.h — Fonts
- dvxTextHash, 2.12. dvxApp.h — Layer 5: Application API
- dvxTileWindows, 2.12. dvxApp.h — Layer 5: Application API
- dvxTileWindowsH, 2.12. dvxApp.h — Layer 5: Application API
- dvxTileWindowsV, 2.12. dvxApp.h — Layer 5: Application API
- dvxTypes.h, 2.2. dvxTypes.h — Shared Type Definitions
- dvxUnregisterAppHotkeys, 2.12. dvxApp.h — Layer 5: Application API
- dvxUnregisterHotkey, 2.12. dvxApp.h — Layer 5: Application API
- dvxUpdate, 2.12. dvxApp.h — Layer 5: Application API
- DVXUSER, 1.9. DVX Folders (dvxPlat.h)
- dvxVideo, 1.2. Five-Layer Architecture
- dvxVideo.h, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- dvxWaitPump, 2.12. dvxApp.h — Layer 5: Application API
- dvxWallpaperFromPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxWallpaperToPrefs, 2.12. dvxApp.h — Layer 5: Application API
- dvxWgt.h, 2.14. dvxWgt.h — Widget System
- dvxWgtP.h, 2.21. dvxWgtP.h — Widget Plugin API
- dvxWindowScreenshot, 2.12. dvxApp.h — Layer 5: Application API
- dvxWm, 1.2. Five-Layer Architecture
- dvxWm.h, 2.11. dvxWm.h — Layer 4: Window Manager
- DXE, 1.11. DXE Module System
- DXE Application Loading, 3.1. DVX Shell Library
- DXE Resources, 1.7. Resource System (dvxRes.h)
- DXE3, 1.11. DXE Module System
- dxe3gen, 1.16.1. Cross-Compilation
- DxeAppContextT, 3.2.2. Constants
- Dynamic Loading, 1.11. DXE Module System
E
- Ed25519, 7.3. Cryptography Library
- EINPROGRESS, 8.2. The Socket API
- EMU8000, 10.1. Sound Library
- Event Dispatch, 1.12. Event Model
- Events, 1.12. Event Model
- EWOULDBLOCK, 8.2. The Socket API
- Exit DVX, 3.3.1. shellAppInit
F
- FAT32, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- File Associations, 3.12. File Associations
- File Dialog, 1.6. Modal Dialogs (dvxDlg.h)
- File Transfer, 7.9. File Transfer Library
- fileops, 6.1. File Operations Library
- fileops.bas, 6.1. File Operations Library
- fileOpsJobClearAttr, 6.1. File Operations Library
- fileOpsJobCreate, 6.1. File Operations Library
- fileOpsJobRun, 6.1. File Operations Library
- fileOpsJobStep, 6.1. File Operations Library
- FileOpsJobT, 6.1. File Operations Library
- fileOpsListDir, 6.1. File Operations Library
- fileOpsParseDate, 6.1. File Operations Library
- Flexbox, 1.5. Widget System
- Flowing text, 2.6. dvxFlow.h — Flowing Text
- flushRect, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- Folders, 1.9. DVX Folders (dvxPlat.h)
- Font, 2.4.1. dvxFont.h — Embedded Bitmap Font Data
- Font families, 2.5. dvxText.h — Fonts
- Font files, 1.13. Font System
- Font licenses, 2.5. dvxText.h — Fonts
- Font properties ©, 11.5. The .frm Model
- Font smoothing, 1.13. Font System, 2.5. dvxText.h — Fonts
- Fonts, 1.13. Font System
- Frame, 4.3. Box (VBox / HBox / Frame)
- FRAMEWAIT, 10.4. Game Helpers Library
- FrmCtrlT, 11.5. The .frm Model
- FrmMenuItemT, 11.5. The .frm Model
- frmModelFromForm, 11.5. The .frm Model
- frmModelLoad, 11.5. The .frm Model
- FrmModelT, 11.5. The .frm Model
- frmModelText, 11.5. The .frm Model
- frmModelWrite, 11.5. The .frm Model
- Full-screen exclusive mode, 2.12. dvxApp.h — Layer 5: Application API
G
- game, 10.4. Game Helpers Library
- game port, 10.3. Joystick Library
- game.bas, 10.4. Game Helpers Library
- game.h, 10.4. Game Helpers Library
- gameFrameInit, 10.4. Game Helpers Library
- gameFrameNext, 10.4. Game Helpers Library
- GameFramePacerT, 10.4. Game Helpers Library
- gameFrameWait, 10.4. Game Helpers Library
- GameKeyDown, 10.4. Game Helpers Library
- gameKeyIsDown, 10.4. Game Helpers Library
- gamePalCacheInit, 10.4. Game Helpers Library
- gamePalCacheLookup, 10.4. Game Helpers Library
- gamePalCacheSync, 10.4. Game Helpers Library
- GamePalCacheT, 10.4. Game Helpers Library
- gamePalNearest, 10.4. Game Helpers Library
- gameTimerAdd, 10.4. Game Helpers Library
- General MIDI, 10.2. Music Library
- GENMIDI, 10.2. Music Library
- getaddrinfo, 8.2. The Socket API
- Go-Back-N, 7.5. Packet Transport
- Gravis UltraSound, 10.1. Sound Library
- Gravis UltraSound patches, 10.2. Music Library
H
- HBox, 4.3. Box (VBox / HBox / Frame)
- HDLC, 7.1. Serial Stack, 7.5. Packet Transport
- help
- Technical Reference, How This Book Is Organized
- Help menu, 3.3.1. shellAppInit
- HelpView, 4.11. HelpView
- HelpViewLinkFnT, 4.11. HelpView
- Hit Testing, 1.4.1. WindowT Structure
- HKDF, 7.3. Cryptography Library
- .hlp file format, 5.20. Help File Library
- hlpfile, 5.20. Help File Library
- hlpfile.bas, 5.21.1. BASIC
- hlpFileForEachRecord, 5.20. Help File Library
- hlpFileOpen, 5.20. Help File Library
- hlpFileReadImage, 5.20. Help File Library
- hlpFileSearch, 5.20. Help File Library
- hlpFileStartTopic, 5.20. Help File Library
- HlpFileT, 5.20. Help File Library
- hlpFormat.h, 5.20. Help File Library
- HlpOpen, 5.21.1. BASIC
- hlpWrapText, 5.20. Help File Library
- HMAC, 7.3. Cryptography Library
- HotkeyAdd, 3.13. BASIC Entry Points
- HotkeyNames, 3.13. BASIC Entry Points
- HotkeyNext, 3.13. BASIC Entry Points
- HotkeyRemove, 3.13. BASIC Entry Points
- Hotkeys, 2.12. dvxApp.h — Layer 5: Application API
- HotkeySystemUse, 3.13. BASIC Entry Points
- HotkeyText, 3.13. BASIC Entry Points
- http, 8.7. HTTP Library
- HTTP, 8.7. HTTP Library
- http.bas, 8.7. HTTP Library
- httpCreate, 8.7. HTTP Library
- httpPoll, 8.7. HTTP Library
- httpSaveTo, 8.7. HTTP Library
I
- Image, 4.12. Image
- ImageButton, 4.13. ImageButton
- INI files, 1.8. Preferences System (dvxPrefs.h)
- Input, 1.12. Event Model
- Input Box, 1.6. Modal Dialogs (dvxDlg.h)
- INT 16h, 1.15. Platform Layer
- INT 17h, 6.2. Printing Library
- INT 24h, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- INT 33h, 1.15. Platform Layer
- ISO, 1.16.1. Cross-Compilation
- isWordChar, 5.4. isWordChar
- IT, 10.2. Music Library
- ItemCheck, 4.15. ListBox
J
- JOY_DRIVER, 10.3. Joystick Library
- JoyAxisCalT, 10.3. Joystick Library
- joyAxisScale, 10.3. Joystick Library
- joyBasStick, 10.3. Joystick Library
- joyButtonPressed, 10.3. Joystick Library
- joyButtonWentDown, 10.3. Joystick Library
- JoyChoiceE, 10.3. Joystick Library
- joyChoiceGet, 10.3. Joystick Library
- joyChoices, 10.3. Joystick Library
- joyChoiceSet, 10.3. Joystick Library
- joyClose, 10.3. Joystick Library
- joyCount, 10.3. Joystick Library
- joyDeadZoneApply, 10.3. Joystick Library
- JoyDriverT, 10.3. Joystick Library
- JoyEventT, 10.3. Joystick Library
- joyGetCalibration, 10.3. Joystick Library
- joyGetDeadZone, 10.3. Joystick Library
- joyGetInfo, 10.3. Joystick Library
- joyGetRaw, 10.3. Joystick Library
- JoyInfoT, 10.3. Joystick Library
- joyKbdSlotGet, 10.3. Joystick Library
- joyKbdSlotSet, 10.3. Joystick Library
- joyKeyIndex, 10.3. Joystick Library
- joyOpen, 10.3. Joystick Library
- joyOpenShared, 10.3. Joystick Library
- joyPump, 10.3. Joystick Library
- JoyRawT, 10.3. Joystick Library
- joyRead, 10.3. Joystick Library
- joyRescan, 10.3. Joystick Library
- joyRescanApp, 10.3. Joystick Library
- joySetCalibration, 10.3. Joystick Library
- joySetDeadZone, 10.3. Joystick Library
- joySetEventFn, 10.3. Joystick Library
- joySettingGet, 10.3. Joystick Library
- joySettingSet, 10.3. Joystick Library
- joySettingsLoad, 10.3. Joystick Library
- joySettingsStore, 10.3. Joystick Library
- JoyStateT, 10.3. Joystick Library
- joystick, 10.3. Joystick Library
- joystick.bas, 10.3. Joystick Library
- joystick.h, 10.3. Joystick Library
- json, 8.8. JSON Library
- JSON, 8.8. JSON Library
- json.bas, 8.8. JSON Library
- jsonFind, 8.8. JSON Library
- jsonParse, 8.8. JSON Library
- jsonQuote, 8.8. JSON Library
K
- Key Handling, 5.14. widgetTextEditOnKey
- Keyboard, 1.12. Event Model
L
- Label, 4.14. Label
- Layers, 1.2. Five-Layer Architecture
- Layout, 1.5. Widget System, 4.3. Box (VBox / HBox / Frame)
- Layout Engine, 1.5. Widget System
- LFB, 1.3. Display Pipeline, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- libtasks, 3.16. libtasks — Cooperative Task Switching
- libxmp-lite, 10.2. Music Library
- Linear Framebuffer, 1.3. Display Pipeline
- ListBox, 4.15. ListBox
- LISTBOX_MULTI_SIMPLE, 4.15. ListBox
- LISTBOX_STYLE_CHECKBOX, 4.15. ListBox
- listhelp, 5.16. List Helper Library
- listhelp.bas, 5.17.1. BASIC
- listIconGrid, 5.16. List Helper Library
- ListIconGridT, 5.16. List Helper Library
- listIconLabelSplit, 5.16. List Helper Library
- ListItemsT, 5.16. List Helper Library
- ListPopupT, 5.16. List Helper Library
- listReorderMove, 5.16. List Helper Library
- ListSelCreate, 5.17.1. BASIC
- ListSelT, 5.16. List Helper Library
- listTextFit, 5.16. List Helper Library
- ListView, 4.16. ListView
- ListViewColT, 4.16. ListView
- ListViewSortE, 4.16. ListView
- Loaded fonts, 1.13. Font System
- Long File Names, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- lwIP, 8.1. Networking Library
M
- Makefile, 1.16.1. Cross-Compilation
- Master-Detail, 4.8. DataCtrl
- Memory Tracking, 1.10. Per-App Memory Tracking (dvxMem.h), 1.11. DXE Module System
- Menu System, 1.4.1. WindowT Structure
- MenuBarT, 2.2. dvxTypes.h — Shared Type Definitions
- MenuItemT, 2.2. dvxTypes.h — Shared Type Definitions
- Menus, 1.4.1. WindowT Structure
- MenuT, 2.2. dvxTypes.h — Shared Type Definitions
- Message Box, 1.6. Modal Dialogs (dvxDlg.h)
- MIDI, 10.2. Music Library
- MIDI input, 10.1. Sound Library
- MIDI recording, 10.2. Music Library
- MidiInMessage, 10.1. Sound Library
- MidiInOpen, 10.1. Sound Library
- MidiRecordNew, 10.2. Music Library
- MidiRecordPause, 10.2. Music Library
- MidiRecordResume, 10.2. Music Library
- MidiRecordTime, 10.2. Music Library
- Minimized Windows, 1.4.1. WindowT Structure
- mkcd.sh, 1.16.1. Cross-Compilation
- mkfont, 1.13. Font System
- MOD, 10.2. Music Library
- Modal windows, 2.12. dvxApp.h — Layer 5: Application API
- Modem, 7.7. Connection Library
- Modules, 1.11. DXE Module System
- Modules on the wavetable synthesizer, 10.2. Music Library
- Monocypher, 7.3. Cryptography Library
- Mouse, 1.12. Event Model
- Mouse Click, 5.13. widgetTextEditMouseClick
- Mouse Wheel, 1.12. Event Model
- MPU-401, 10.1. Sound Library
- MT-32, 10.2. Music Library
- Multi-Click, 5.13. widgetTextEditMouseClick
- music, 10.2. Music Library
- Music macro language, 10.2. Music Library
- music.bas, 10.2. Music Library
- music.h, 10.2. Music Library
- MUSIC_ERR_UNSUPPORTED, 10.2. Music Library
- MUSIC_ERR_WRITE, 10.2. Music Library
- MUSIC_KIND_SOUND, 10.2. Music Library
- musicBasPlay, 10.2. Music Library
- MusicInfoT, 10.2. Music Library
- musicLoad, 10.2. Music Library
- MusicLoad, 10.2. Music Library
- musicLoadMacro, 10.2. Music Library
- MusicLoadMacro, 10.2. Music Library
- musicMidiNoteOn, 10.2. Music Library
- musicMidiOpen, 10.2. Music Library
- musicMidiRecordNew, 10.2. Music Library
- musicMidiRecordPause, 10.2. Music Library
- musicMidiRecordResume, 10.2. Music Library
- musicMidiRecordSave, 10.2. Music Library
- musicMidiRecordTime, 10.2. Music Library
- musicMidiSend, 10.2. Music Library
- MusicMidiSend, 10.2. Music Library
- musicMmlOpen, 10.2. Music Library
- musicMmlPlay, 10.2. Music Library
- MusicMmlT, 10.2. Music Library
- musicModHw, 10.2. Music Library
- MusicPatchSet$, 10.2. Music Library
- musicPatchSetPath, 10.2. Music Library
- musicPlay, 10.2. Music Library
- MusicPlay, 10.2. Music Library
- MusicRomBank$, 10.2. Music Library
- musicRomBankPath, 10.2. Music Library
- musicSetBank, 10.2. Music Library
- MusicSetBank, 10.2. Music Library
- musicStop, 10.2. Music Library
N
- net.bas, 8.6. Networking from BASIC
- NetConfigT, 8.4.1. Settings and Status (dvxNet.h)
- netGetStatus, 8.4.1. Settings and Status (dvxNet.h)
- netLookupStart, 8.3.1. Waiting, Polling, and Cooperative Multitasking
- netPoll, 8.3.1. Waiting, Polling, and Cooperative Multitasking
- netRestart, 8.4.1. Settings and Status (dvxNet.h)
- netStart, 8.4.1. Settings and Status (dvxNet.h)
- NetStatusT, 8.4.1. Settings and Status (dvxNet.h)
- Networking, 8.1. Networking Library
- Not responding, 2.12. dvxApp.h — Layer 5: Application API
O
- onChange, 4.2.1. DVX Widget System
- onClick, 4.2.1. DVX Widget System
- onEvent, 2.14. dvxWgt.h — Widget System
- onKeyDown, 4.2.1. DVX Widget System
- onKeyPress, 4.2.1. DVX Widget System
- onMouseDown, 4.2.1. DVX Widget System
- OP2, 10.2. Music Library
- OPL, 10.1. Sound Library
P
- Package server, 9.2. Package Server Library
- PACKAGE.INI, 9.1. Package Library
- packColor, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- packColorRgb, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- packet, 7.5. Packet Transport
- Packet driver, 8.1. Networking Library
- Palette, 2.7.1. dvxPal.h — 256-Color Palette for 8-bit Mode
- Path Separators, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PC speaker, 10.1. Sound Library
- Picture formats, 2.12. dvxApp.h — Layer 5: Application API
- Pixel Format, 1.14.1. Pixel Format
- PixelFormatT, 1.14.1. Pixel Format, 2.2. dvxTypes.h — Shared Type Definitions
- pkg, 9.1. Package Library
- pkg.bas, 9.1. Package Library
- pkgDpkBuild, 9.1. Package Library
- pkgDpkBuildFiles, 9.1. Package Library
- pkgDpkSign, 9.1. Package Library
- pkgKeyringLoad, 9.1. Package Library
- pkgnet, 9.2. Package Server Library
- pkgnet.bas, 9.2. Package Server Library
- pkgNetCreate, 9.2. Package Server Library
- pkgNetFetchStart, 9.2. Package Server Library
- pkgNetPoll, 9.2. Package Server Library
- pkgNetRecoverStart, 9.2. Package Server Library
- pkgNetRegisterStart, 9.2. Package Server Library
- pkgNetReply, 9.2. Package Server Library
- pkgNetResetStart, 9.2. Package Server Library
- pkgNetVerifyStart, 9.2. Package Server Library
- pkgOpInstall, 9.1. Package Library
- pkgOpRemove, 9.1. Package Library
- pkgPlanInstall, 9.1. Package Library
- pktClose, 7.5. Packet Transport
- pktDrv, 8.5.1. How It Works
- pktOpen, 7.5. Packet Transport
- pktOpenStream, 7.5. Packet Transport
- pktPoll, 7.5. Packet Transport
- pktSend, 7.5. Packet Transport
- pktSetYield, 7.5. Packet Transport
- PktStreamT, 7.5. Packet Transport
- pktWaitSpace, 7.5. Packet Transport
- pktYield, 7.5. Packet Transport
- Platform Layer, 1.15. Platform Layer, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PLATFORM_LONG_NAME_MAX, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformAppExit, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformAtExitRun, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformBankChunk, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformBootDrive, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformCanReplaceFile, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformClock, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformDirIsWritable, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformDiskSpace, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformDosRun, 2.12. dvxApp.h — Layer 5: Application API
- platformDriveCurDir, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformDriveErrno, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformDriveList, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlatformDriveT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformEntropyStamp, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformFileStamp, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformFilterMatch, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformFindSwitch, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformFlushRect, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformInjectScan, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformIrqRestore, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformIrqSave, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformIsReadOnly, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyboardRead, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyEventRead, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlatformKeyEventT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyHookInit, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyIsDown, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyStateClear, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformKeyStateGet, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformLockRegion, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformLogMemory, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformLogPath, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformLongNameChar, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformLongNames, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformMicros, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformModuleClose, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformMousePoll, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformNormalizeFKeyScan, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathAbsolute, 2.12. dvxApp.h — Layer 5: Application API
- platformPathDirName, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathIsAbsolute, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathIsRoot, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathIsSep, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathIsUnder, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathJoin, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathNative, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathParent, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathSame, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathSibling, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformPathTidy, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformReplaceFile, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformScratchFile, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformServicesStop, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSetAppExitHook, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSetCrashTarget, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSetLogLimit, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSetLogMemory, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSetReadOnly, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformShortPath, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformShutdownHookAdd, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformShutdownHookRemove, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSplashNearestColor, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlatformStampT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformStatSize, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformSuspendHookAdd, 2.12. dvxApp.h — Layer 5: Application API
- platformTempDir, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTextMode, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTimerAdd, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTimerAddFast, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlatformTimerFnT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTimerRemove, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTimerRemoveOwner, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTimerStats, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlatformTimerStatsT, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformTruePath, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformUnlockRegion, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformUserEnvDir, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformValidateLongName, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformValidateShortName, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformVideoInit, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformVideoReadBack, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformWalkDir, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- platformWriteFile, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- PlayTone, 10.1. Sound Library
- PlayWave, 10.1. Sound Library
- pmGroupMove, 3.14. Program Groups
- pmHotkeyParse, 3.14. Program Groups
- pmHotkeyWhyNot, 3.14. Program Groups
- pmInstalledScan, 3.14. Program Groups
- pmItemGetField, 3.14. Program Groups
- pmModel.h, 3.14. Program Groups
- pmModelLoad, 3.14. Program Groups
- pmModelSave, 3.14. Program Groups
- PmModelT, 3.14. Program Groups
- poll, 8.2. The Socket API
- Polling, 1.12. Event Model
- Preferences, 1.8. Preferences System (dvxPrefs.h), 2.17.1. dvxPrefs.h — INI Preferences System
- prefs.bas, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsAccelChoices, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsApplyChanges, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsBasHandle, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsChoiceIndex, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsChoiceIndexOfValue, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsChoiceLabels, 2.17.1. dvxPrefs.h — INI Preferences System
- PrefsChoiceT, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsDvxIniShared, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetBool, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetChoice, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetInt, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetSecret, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetString, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsGetVideoMode, 2.17.1. dvxPrefs.h — INI Preferences System
- PrefsHandleT, 1.8. Preferences System (dvxPrefs.h), 2.17.1. dvxPrefs.h — INI Preferences System
- prefsKeyName, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsLoad, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsLoadFailed, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsMemorySaves, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSave, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSetBool, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSetInt, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSetSecret, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSetString, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsSetVideoMode, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsWallpaperChoices, 2.17.1. dvxPrefs.h — INI Preferences System
- prefsWheelDirChoices, 2.17.1. dvxPrefs.h — INI Preferences System
- print, 6.2. Printing Library
- Print sizes, 6.2. Printing Library
- printDialog, 6.2. Printing Library
- printDocOpen, 6.2. Printing Library
- printDocPage, 6.2. Printing Library
- printDocPicture, 6.2. Printing Library
- PrintDocT, 6.2. Printing Library
- printFontOpen, 6.2. Printing Library
- PrintFontT, 6.2. Printing Library
- printJobOpen, 6.2. Printing Library
- PrintJobT, 6.2. Printing Library
- printJobWrite, 6.2. Printing Library
- printModelPage, 6.2. Printing Library
- printPageSetupDialog, 6.2. Printing Library
- printTextJob, 6.2. Printing Library
- printUiDocOpen, 6.2. Printing Library
- printUiJobOpen, 6.2. Printing Library
- printUiText, 6.2. Printing Library
- printUiTextSetup, 6.2. Printing Library
- printVecBegin, 6.2. Printing Library
- prjLoad, 11.4. BASIC Development Library
- PrjStateT, 11.4. BASIC Development Library
- PROGMAN.INI, 3.14. Program Groups
- Program fonts, 2.5. dvxText.h — Fonts
- ProgressBar, 4.17. ProgressBar
R
- Radio, 4.18. Radio Button
- RadioGroup, 4.18. Radio Button
- Read-only Media, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- Receive ring, 8.5.1. How It Works
- RecordCancel, 10.1. Sound Library
- Recording, 10.1. Sound Library
- RecordPause, 10.1. Sound Library
- RecordResume, 10.1. Sound Library
- RecordStart, 10.1. Sound Library
- RecordStop, 10.1. Sound Library
- rectCopy, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- rectCopyGrayscale, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- rectFill, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- rectIntersect, 2.10. dvxComp.h — Layer 3: Dirty Rectangle Compositor
- RectT, 2.2. dvxTypes.h — Shared Type Definitions
- rep movsd, 1.15. Platform Layer
- rep stosl, 1.15. Platform Layer
- resetClipRect, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- Resources, 1.7. Resource System (dvxRes.h), 2.16.1. dvxRes.h — DXE-Embedded Resource System
- RichChangeT, 5.18. Styled Text Library
- RichEdit, 4.19. RichEdit
- RichLabel, 4.20. RichLabel
- richRtfRead, 5.18. Styled Text Library
- richRtfWrite, 5.18. Styled Text Library
- RichRunT, 5.18. Styled Text Library
- RichStyleT, 5.18. Styled Text Library
- richtext, 5.18. Styled Text Library
- richtext.bas, 5.19. Styled Text Library: BASIC
- richTextCopy, 5.18. Styled Text Library
- richTextReplace, 5.18. Styled Text Library
- richTextRestyle, 5.18. Styled Text Library
- RichTextT, 5.18. Styled Text Library
- RS-232, 7.1. Serial Stack
- rs232, 7.2. RS-232 UART Driver
- rs232Close, 7.2. RS-232 UART Driver
- rs232GetDcd, 7.2. RS-232 UART Driver
- rs232Open, 7.2. RS-232 UART Driver
- rs232Read, 7.2. RS-232 UART Driver
- rs232SetBreak, 7.2. RS-232 UART Driver
- rs232Write, 7.2. RS-232 UART Driver
- RTF, 5.18. Styled Text Library
- RtfToText$, 5.19. Styled Text Library: BASIC
- Run dialog, 3.10. Running Programs and Documents
- Run Minimized, 3.10. Running Programs and Documents
- /RUN=, 3.5. Starting Up
S
- S3M, 10.2. Music Library
- /SAFE, 3.5. Starting Up
- Safe Video Mode, 3.5. Starting Up
- SBK, 10.2. Music Library
- Screen saver, 3.11. The Screen Saver
- ScrollbarT, 2.2. dvxTypes.h — Shared Type Definitions
- ScrollPane, 4.21. ScrollPane
- secAeadLock, 7.3. Cryptography Library
- secAeadUnlock, 7.3. Cryptography Library
- secCipherCreate, 7.3. Cryptography Library
- secDhCreate, 7.3. Cryptography Library
- secEd25519Check, 7.3. Cryptography Library
- secEd25519Sign, 7.3. Cryptography Library
- secLink, 7.1. Serial Stack, 7.4. Secure Link Library
- secLinkClose, 7.4. Secure Link Library
- secLinkHandshake, 7.4. Secure Link Library
- secLinkHandshakeStep, 7.4. Secure Link Library
- secLinkOpen, 7.4. Secure Link Library
- secLinkOpenStream, 7.4. Secure Link Library
- secLinkPoll, 7.4. Secure Link Library
- secLinkSend, 7.4. Secure Link Library
- secLinkSendBuf, 7.4. Secure Link Library
- secLinkSetChannelPlain, 7.4. Secure Link Library
- secLinkSetPassphrase, 7.4. Secure Link Library
- secRngAddEntropy, 7.3. Cryptography Library
- secRngBytes, 7.3. Cryptography Library
- secRngLoadSeed, 7.3. Cryptography Library
- Security, 7.3. Cryptography Library
- security.bas, 7.3. Cryptography Library
- secX25519, 7.3. Cryptography Library
- select, 8.2. The Socket API
- Selection, 5.3. clearOtherSelections
- Selection Highlight, 5.15. widgetTextEditPaintLine
- Separator, 4.22. Separator
- Serial, 7.1. Serial Stack
- Serial Example, 7.6. End-to-End Example
- setClipRect, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- SF2, 10.2. Music Library
- SHA-256, 7.3. Cryptography Library
- SHARED, 1.9. DVX Folders (dvxPlat.h)
- Shared Library, 5.1. Text Help Library
- shell.bas, 3.13. BASIC Entry Points
- SHELL_APP_DESCRIPTOR, 3.2.2. Constants
- SHELL_APP_NAME_MAX, 3.2.2. Constants
- SHELL_DESKTOP_APP, 3.2.2. Constants
- SHELL_DOS_FILTER, 3.10. Running Programs and Documents
- SHELL_DOS_ICON, 3.10. Running Programs and Documents
- SHELL_INI_WELCOME, 3.5. Starting Up
- SHELL_RUN_DOS, 3.10. Running Programs and Documents
- SHELL_SAVER_ARGS, 3.11. The Screen Saver
- SHELL_STACK_DEFAULT, 3.2.2. Constants
- shellActivateApp, 3.4.1. shellGetApp
- shellApp.h, 3.1. DVX Shell Library
- ShellAppCleanupFnT, 3.7. Desktop Callbacks
- shellAppCodeForgetTask, 3.3.1. shellAppInit
- shellAppCodeRestore, 3.3.1. shellAppInit
- shellAppCodeSave, 3.3.1. shellAppInit
- shellAppFindByPath, 3.4.1. shellGetApp
- ShellAppId, 3.13. BASIC Entry Points
- shellAppInit, 3.3.1. shellAppInit
- ShellAppIsHung, 3.13. BASIC Entry Points
- ShellAppMemory, 3.13. BASIC Entry Points
- ShellAppPath, 3.13. BASIC Entry Points
- shellAppSlotCount, 3.4.1. shellGetApp
- ShellAppT, 3.2.2. Constants
- shellAppTaskStart, 3.7. Desktop Callbacks
- ShellArg, 3.13. BASIC Entry Points
- ShellArgCount, 3.13. BASIC Entry Points
- ShellArgQuote, 3.13. BASIC Entry Points
- shellAssocCommand, 3.12. File Associations
- ShellAssocCommand, 3.13. BASIC Entry Points
- shellAssocCount, 3.12. File Associations
- ShellAssocCount, 3.13. BASIC Entry Points
- ShellAssocExt, 3.13. BASIC Entry Points
- shellAssocGet, 3.12. File Associations
- shellAssocLookup, 3.12. File Associations
- shellAssocNormalize, 3.12. File Associations
- ShellAssocNormalize, 3.13. BASIC Entry Points
- shellAssocOpenDocument, 3.12. File Associations
- ShellAssocProgram, 3.13. BASIC Entry Points
- shellAssocRemove, 3.12. File Associations
- ShellAssocRemove, 3.13. BASIC Entry Points
- shellAssocSet, 3.12. File Associations
- ShellAssocSet, 3.13. BASIC Entry Points
- ShellAssocValue, 3.13. BASIC Entry Points
- ShellChangeCount, 3.13. BASIC Entry Points
- shellCloseAllApps, 3.3.1. shellAppInit
- shellCloseApp, 3.3.1. shellAppInit
- ShellCommandArgs, 3.13. BASIC Entry Points
- ShellCommandProgram, 3.13. BASIC Entry Points
- shellCtrlEscFn, 3.7. Desktop Callbacks
- shellDataPath, 3.6. Program Folders API
- shellDesktopChangeCount, 3.7. Desktop Callbacks
- shellDesktopUpdate, 3.7. Desktop Callbacks
- shellEndClosedApps, 3.3.1. shellAppInit
- shellEndTask, 3.3.1. shellAppInit
- shellEnsureUserDir, 3.6. Program Folders API
- ShellExitDvx, 3.13. BASIC Entry Points
- shellForceKillApp, 3.3.1. shellAppInit
- shellFrameInApp, 3.3.1. shellAppInit
- shellGetApp, 3.4.1. shellGetApp
- shellGetRunningApp, 3.4.1. shellGetApp
- shellGetSystemInfo, 3.8. System Information
- ShellGroupsLoad, 3.14. Program Groups
- shellInfoInit, 3.8. System Information
- ShellInstanceCount, 3.13. BASIC Entry Points
- shellIsDosProgram, 3.10. Running Programs and Documents
- ShellIsDosProgram, 3.13. BASIC Entry Points
- shellIsProgram, 3.9. Installed Programs
- ShellIsProgram, 3.13. BASIC Entry Points
- shellItemIcon, 3.9. Installed Programs
- shellItemIconFile, 3.9. Installed Programs
- shellLoadApp, 3.3.1. shellAppInit
- shellLoadAppWithArgs, 3.3.1. shellAppInit
- ShellLog, 3.13. BASIC Entry Points
- ShellMemoryRetained, 3.13. BASIC Entry Points
- shellMinimizeApp, 3.10. Running Programs and Documents
- ShellMinimizeApp, 3.13. BASIC Entry Points
- ShellOpenDocument, 3.13. BASIC Entry Points
- shellOpenHelp, 3.3.1. shellAppInit
- shellOpenHelpFile, 3.3.1. shellAppInit
- shellOpenTaskManager, 3.7. Desktop Callbacks
- ShellPriority, 3.13. BASIC Entry Points
- ShellProgramCount, 3.13. BASIC Entry Points
- ShellProgramDescription, 3.13. BASIC Entry Points
- ShellProgramFree, 3.13. BASIC Entry Points
- shellProgramIcon, 3.9. Installed Programs
- shellProgramInfo, 3.9. Installed Programs
- shellProgramListFree, 3.9. Installed Programs
- ShellProgramName, 3.13. BASIC Entry Points
- ShellProgramPath, 3.13. BASIC Entry Points
- shellProgramScan, 3.9. Installed Programs
- ShellProgramScan, 3.13. BASIC Entry Points
- ShellProgramT, 3.9. Installed Programs
- shellReapApp, 3.3.1. shellAppInit
- shellReapApps, 3.3.1. shellAppInit
- shellRegisterAppCleanup, 3.7. Desktop Callbacks
- shellRegisterAppKill, 3.7. Desktop Callbacks
- shellRegisterDesktopUpdate, 3.7. Desktop Callbacks
- shellRegisterIdle, 3.7. Desktop Callbacks
- shellRequestAppClose, 3.3.1. shellAppInit
- shellRequestExit, 3.3.1. shellAppInit
- shellResolveArgs, 3.10. Running Programs and Documents
- shellReturnedFromDos, 3.10. Running Programs and Documents
- ShellReturnedFromDos, 3.13. BASIC Entry Points
- ShellRun, 3.13. BASIC Entry Points
- shellRunCloseRequests, 3.3.1. shellAppInit
- shellRunCommand, 3.10. Running Programs and Documents
- ShellRunCommand, 3.13. BASIC Entry Points
- shellRunDialog, 3.10. Running Programs and Documents
- ShellRunDialog, 3.13. BASIC Entry Points
- shellRunDos, 3.10. Running Programs and Documents
- ShellRunDos, 3.13. BASIC Entry Points
- shellRunDosDone, 3.10. Running Programs and Documents
- shellRunDosFor, 3.10. Running Programs and Documents
- shellRunDosRequest, 3.10. Running Programs and Documents
- ShellRunDosWait, 3.13. BASIC Entry Points
- shellRunExitRequest, 3.3.1. shellAppInit
- shellRunHandedOff, 3.10. Running Programs and Documents
- shellRunHandOffInit, 3.10. Running Programs and Documents
- ShellRunningActivate, 3.13. BASIC Entry Points
- shellRunningAppCount, 3.4.1. shellGetApp
- shellRunningAppId, 3.4.1. shellGetApp
- ShellRunningClose, 3.13. BASIC Entry Points
- ShellRunningCount, 3.13. BASIC Entry Points
- ShellRunningFind, 3.13. BASIC Entry Points
- ShellRunningId, 3.13. BASIC Entry Points
- ShellRunningKill, 3.13. BASIC Entry Points
- ShellRunningName, 3.13. BASIC Entry Points
- ShellRunningPath, 3.13. BASIC Entry Points
- shellRunProgram, 3.10. Running Programs and Documents
- ShellRunProgram, 3.13. BASIC Entry Points
- shellSaverFromPrefs, 3.11. The Screen Saver
- shellSaverName, 3.11. The Screen Saver
- shellSaverRunning, 3.11. The Screen Saver
- shellSaverSet, 3.11. The Screen Saver
- shellSaverStart, 3.11. The Screen Saver
- shellSaverStep, 3.11. The Screen Saver
- shellSaverToPrefs, 3.11. The Screen Saver
- shellSaverWait, 3.11. The Screen Saver
- ShellSetDesktop, 3.13. BASIC Entry Points
- ShellSetPriority, 3.13. BASIC Entry Points
- ShellSetWelcome, 3.13. BASIC Entry Points
- shellSplitCommand, 3.10. Running Programs and Documents
- ShellSystemInfo, 3.13. BASIC Entry Points
- shellTaskDepthForget, 3.3.1. shellAppInit
- shellTaskDepthShare, 3.3.1. shellAppInit
- ShellTaskManager, 3.13. BASIC Entry Points
- shellTaskMgrOpen, 3.17. Task Manager
- shellTaskMgrRefresh, 3.17. Task Manager
- shellTaskRun, 3.3.1. shellAppInit
- shellTerminateAllApps, 3.3.1. shellAppInit
- shellUnregisterAppCleanup, 3.7. Desktop Callbacks
- shellUnregisterAppKill, 3.7. Desktop Callbacks
- shellUnregisterDesktopUpdate, 3.7. Desktop Callbacks
- shellUnregisterIdle, 3.7. Desktop Callbacks
- shellUserPath, 3.6. Program Folders API
- signal, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- sleep, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- Slider, 4.23. Slider
- socket, 8.2. The Socket API
- Sockets, 8.1. Networking Library
- softwave, 10.2. Music Library
- sound, 10.1. Sound Library
- Sound Blaster, 10.1. Sound Library
- Sound Blaster AWE32, 10.1. Sound Library
- sound.bas, 10.1. Sound Library
- SoundFont, 10.2. Music Library
- SoundInfo$, 10.1. Sound Library
- SoundModulesLabel$, 10.1. Sound Library
- SoundPause, 10.1. Sound Library
- SoundResume, 10.1. Sound Library
- SoundSettingsStore, 10.1. Sound Library
- SoundStreamEnd, 10.1. Sound Library
- SoundStreamFlush, 10.1. Sound Library
- Spacer, 4.24. Spacer
- Spinner, 4.25. Spinner
- Splitter, 4.26. Splitter
- SQL, 6.3. dvxSql — SQL Database Interface
- SQLite, 6.3. dvxSql — SQL Database Interface
- StatusBar, 4.27. StatusBar
- Stereo-on-1, 10.1. Sound Library
- STICK, 10.3. Joystick Library
- STRIG, 10.3. Joystick Library
- Submenus, 1.4.1. WindowT Structure
- SYNTHGM.SBK, 10.2. Music Library
- SYS_VIDEO_DEFAULT_WIDTH, 3.15. BASIC System Settings
- SysColorId, 3.15. BASIC System Settings
- SysColorsStore, 3.15. BASIC System Settings
- SysFontsStore, 3.15. BASIC System Settings
- SysGetColor, 3.15. BASIC System Settings
- SysIdleSeconds, 3.15. BASIC System Settings
- SysLibraryLoaded, 3.15. BASIC System Settings
- SysLoadTheme, 3.15. BASIC System Settings
- SysMemoryFreeKb, 3.15. BASIC System Settings
- SysMemoryTotalKb, 3.15. BASIC System Settings
- SysMouseButtons, 3.15. BASIC System Settings
- SysMouseStore, 3.15. BASIC System Settings
- SysMouseX, 3.15. BASIC System Settings
- SysMouseY, 3.15. BASIC System Settings
- SysPicturePatterns$, 3.15. BASIC System Settings
- SysSaveTheme, 3.15. BASIC System Settings
- SysScreenSaver$, 3.15. BASIC System Settings
- SysScreenSaverStart, 3.15. BASIC System Settings
- SysScreenshot, 3.15. BASIC System Settings
- SysSendKey, 3.15. BASIC System Settings
- SysSetColor, 3.15. BASIC System Settings
- SysSetMouse, 3.15. BASIC System Settings
- SysSetMousePos, 3.15. BASIC System Settings
- SysSetScreenSaver, 3.15. BASIC System Settings
- SysSetTextSmoothing, 3.15. BASIC System Settings
- SysSetVideoMode, 3.15. BASIC System Settings
- SysSetWallpaper, 3.15. BASIC System Settings
- SysShiftState, 3.15. BASIC System Settings
- system, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- system.bas, 3.15. BASIC System Settings
- SysTextSmoothing, 3.15. BASIC System Settings
- SysVideoModeCount, 3.15. BASIC System Settings
- SysWallpaperStore, 3.15. BASIC System Settings
T
- TabControl, 4.28. TabControl
- TabPage, 4.28. TabControl
- Task Manager, 3.17. Task Manager
- Task Switching, 3.16. libtasks — Cooperative Task Switching
- taskSwch.h, 3.16. libtasks — Cooperative Task Switching
- TCP/IP, 8.1. Networking Library
- Telnet, 7.7. Connection Library
- Terminal, 4.1. AnsiTerm
- Text Editing, 5.1. Text Help Library, 5.14. widgetTextEditOnKey
- Text Rendering, 1.13. Font System, 5.15. widgetTextEditPaintLine
- TextArea, 4.29. TextInput / TextArea
- TEXTAREA_DEFAULT_MAX_LEN, 4.29. TextInput / TextArea
- TEXTAREA_MARKER_NONE, 4.29. TextInput / TextArea
- textEditCopyText, 5.10. textEditUndoSwap
- textEditDefaultSyntaxRgb, 5.11. TextEditSingleT
- textEditKeyEdits, 5.11. TextEditSingleT
- textEditMoveCursor, 5.10. textEditUndoSwap
- textEditSaveUndo, 5.9. textEditSaveUndo
- textEditScrollToCursor, 5.11. TextEditSingleT
- textEditSingleClearSelection, 5.11. TextEditSingleT
- textEditSingleFree, 5.11. TextEditSingleT
- textEditSingleInit, 5.11. TextEditSingleT
- textEditSingleReplaceSel, 5.11. TextEditSingleT
- textEditSingleResize, 5.11. TextEditSingleT
- textEditSingleSelRange, 5.11. TextEditSingleT
- textEditSingleSetText, 5.11. TextEditSingleT
- TextEditSingleT, 5.11. TextEditSingleT
- textEditUndoSwap, 5.10. textEditUndoSwap
- textEditVisibleChars, 5.11. TextEditSingleT
- TextFlowT, 2.6. dvxFlow.h — Flowing Text
- textHelp, 5.1. Text Help Library
- TextInput, 4.29. TextInput / TextArea
- TextToRtf$, 5.19. Styled Text Library: BASIC
- textWidth, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- textWidthAccel, 2.9. dvxDraw.h — Layer 2: Drawing Primitives
- Theming, 1.14.1. Pixel Format
- Timer, 4.30. Timer
- Timer Service, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
- Toolbar, 4.31. Toolbar
- TreeItem, 4.32. TreeView
- TreeView, 4.32. TreeView
- tsYield, 8.3.1. Waiting, Polling, and Cooperative Multitasking
U
- UART, 7.2. RS-232 UART Driver
- ULTRASND.INI, 10.2. Music Library
- Undo, 5.9. textEditSaveUndo, 5.10. textEditUndoSwap, 5.14. widgetTextEditOnKey
- User folder, 1.9. DVX Folders (dvxPlat.h)
- usleep, 2.22.1. platform/dvxPlat.h — Platform Abstraction Layer
V
- VBE, 1.15. Platform Layer
- VBox, 4.3. Box (VBox / HBox / Frame)
- Vector Pages, 6.2. Printing Library
- VESA, 1.15. Platform Layer, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- videoInit, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- VideoModeInfoT, 2.2. dvxTypes.h — Shared Type Definitions
- videoShutdown, 2.8. dvxVideo.h — Layer 1: VESA VBE Video Backend
- VOC, 10.2. Music Library
- VT100, 4.1. AnsiTerm
W
- WAV, 10.2. Music Library
- Wavetable MIDI, 10.2. Music Library
- Wavetable synthesizer, 10.1. Sound Library
- WCLASS_CLICK_ON_PICK, 2.14. dvxWgt.h — Widget System
- WCLASS_FIXED_FONT, 2.14. dvxWgt.h — Widget System
- WCLASS_ONE_LINE, 2.14. dvxWgt.h — Widget System
- WCLASS_RAISES_EVENTS, 2.14. dvxWgt.h — Widget System
- WCLASS_SWALLOWS_ENTER, 2.14. dvxWgt.h — Widget System
- Web requests, 8.7. HTTP Library
- Welcome Program, 3.5. Starting Up
- WGT_API_HEADER, 2.14. dvxWgt.h — Widget System
- WGT_COLOR_SET, 2.14. dvxWgt.h — Widget System
- WGT_DYN_ACCESS, 2.14. dvxWgt.h — Widget System
- WGT_IFACE_DOUBLE, 2.14. dvxWgt.h — Widget System
- WGT_METHOD_ON_FOCUS, 2.14. dvxWgt.h — Widget System
- WGT_METHOD_ON_KEY_UP, 2.14. dvxWgt.h — Widget System
- WGT_METHOD_ON_MOUSE_EVENT, 2.14. dvxWgt.h — Widget System
- WGT_SIG_DYNAMIC, 2.14. dvxWgt.h — Widget System
- wgtAnsiTerm, 4.1. AnsiTerm
- wgtAnsiTermClear, 4.1. AnsiTerm
- wgtAnsiTermCopy, 4.1. AnsiTerm
- wgtAnsiTermPoll, 4.1. AnsiTerm
- wgtAnsiTermRepaint, 4.1. AnsiTerm
- wgtAnsiTermSetComm, 4.1. AnsiTerm
- wgtAnsiTermSetMusic, 4.1. AnsiTerm
- wgtAnsiTermSetPalette, 4.1. AnsiTerm
- wgtAnsiTermSetScrollback, 4.1. AnsiTerm
- wgtAnsiTermWrite, 4.1. AnsiTerm
- WgtApiHeaderT, 2.14. dvxWgt.h — Widget System
- WgtApiPrefixT, 2.14. dvxWgt.h — Widget System
- wgtBasicColor, 2.14. dvxWgt.h — Widget System
- wgtButton, 4.4. Button
- wgtCallMethod, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtCanvas, 4.5. Canvas
- wgtCanvasClear, 4.5. Canvas
- wgtCanvasDrawLine, 4.5. Canvas
- wgtCanvasDrawRect, 4.5. Canvas
- wgtCanvasDrawText, 4.5. Canvas
- wgtCanvasDrawTextScaled, 4.5. Canvas
- wgtCanvasFillCircle, 4.5. Canvas
- wgtCanvasFillRect, 4.5. Canvas
- wgtCanvasGetBorderStyle, 4.5. Canvas
- wgtCanvasGetDisplay, 4.5. Canvas
- wgtCanvasGetPixel, 4.5. Canvas
- wgtCanvasLoad, 4.5. Canvas
- wgtCanvasLoadData, 4.5. Canvas
- wgtCanvasResize, 4.5. Canvas
- wgtCanvasSave, 4.5. Canvas
- wgtCanvasSetBorderStyle, 4.5. Canvas
- wgtCanvasSetMouseCallback, 4.5. Canvas
- wgtCanvasSetPenColor, 4.5. Canvas
- wgtCanvasSetPenSize, 4.5. Canvas
- wgtCanvasSetPixel, 4.5. Canvas
- wgtChars, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtCheckbox, 4.6. Checkbox
- wgtCheckboxIsChecked, 4.6. Checkbox
- wgtCheckboxSetChecked, 4.6. Checkbox
- wgtColorFromBasic, 2.14. dvxWgt.h — Widget System
- wgtColorToBasic, 2.14. dvxWgt.h — Widget System
- wgtComboBox, 4.7. ComboBox
- wgtComboBoxAddItem, 4.7. ComboBox
- wgtComboBoxClear, 4.7. ComboBox
- wgtComboBoxGetItemData, 4.7. ComboBox
- wgtComboBoxGetMaxLength, 4.7. ComboBox
- wgtComboBoxGetNewIndex, 4.7. ComboBox
- wgtComboBoxGetSelected, 4.7. ComboBox
- wgtComboBoxGetSorted, 4.7. ComboBox
- wgtComboBoxGetTopIndex, 4.7. ComboBox
- wgtComboBoxInsertItem, 4.7. ComboBox
- wgtComboBoxRemoveItem, 4.7. ComboBox
- wgtComboBoxSetItem, 4.7. ComboBox
- wgtComboBoxSetItemData, 4.7. ComboBox
- wgtComboBoxSetItems, 4.7. ComboBox
- wgtComboBoxSetMaxLength, 4.7. ComboBox
- wgtComboBoxSetSelected, 4.7. ComboBox
- wgtComboBoxSetSorted, 4.7. ComboBox
- wgtComboBoxSetTopIndex, 4.7. ComboBox
- wgtCreateByName, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtDataCtrl, 4.8. DataCtrl
- wgtDataCtrlAddNew, 4.8. DataCtrl
- wgtDataCtrlDelete, 4.8. DataCtrl
- wgtDataCtrlGetError, 4.8. DataCtrl
- wgtDataCtrlGetField, 4.8. DataCtrl
- wgtDataCtrlGetValidateAction, 4.8. DataCtrl
- wgtDataCtrlGetValidateSave, 4.8. DataCtrl
- wgtDataCtrlMoveFirst, 4.8. DataCtrl
- wgtDataCtrlMoveNext, 4.8. DataCtrl
- wgtDataCtrlRefresh, 4.8. DataCtrl
- wgtDataCtrlSetField, 4.8. DataCtrl
- wgtDataCtrlSetValidateAction, 4.8. DataCtrl
- wgtDataCtrlSetValidateSave, 4.8. DataCtrl
- wgtDataCtrlUnload, 4.8. DataCtrl
- wgtDataCtrlUpdate, 4.8. DataCtrl
- wgtDbGrid, 4.9. DbGrid
- wgtDbGridGetSelectedRow, 4.9. DbGrid
- wgtDbGridRefresh, 4.9. DbGrid
- wgtDbGridSetColumnHeader, 4.9. DbGrid
- wgtDbGridSetColumnVisible, 4.9. DbGrid
- wgtDbGridSetColumnWidth, 4.9. DbGrid
- wgtDbGridSetDataWidget, 4.9. DbGrid
- wgtDbGridSetSelectedRow, 4.9. DbGrid
- wgtDestroy, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtDropdown, 4.10. Dropdown
- wgtDropdownAddItem, 4.10. Dropdown
- wgtDropdownClear, 4.10. Dropdown
- wgtDropdownGetItemData, 4.10. Dropdown
- wgtDropdownGetNewIndex, 4.10. Dropdown
- wgtDropdownGetSelected, 4.10. Dropdown
- wgtDropdownGetSorted, 4.10. Dropdown
- wgtDropdownGetTopIndex, 4.10. Dropdown
- wgtDropdownInsertItem, 4.10. Dropdown
- wgtDropdownRemoveItem, 4.10. Dropdown
- wgtDropdownSetItem, 4.10. Dropdown
- wgtDropdownSetItemData, 4.10. Dropdown
- wgtDropdownSetItems, 4.10. Dropdown
- wgtDropdownSetSelected, 4.10. Dropdown
- wgtDropdownSetSorted, 4.10. Dropdown
- wgtDropdownSetTopIndex, 4.10. Dropdown
- WgtDynIfaceT, 2.14. dvxWgt.h — Widget System
- wgtFind, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtFindByBasName, 2.14. dvxWgt.h — Widget System
- wgtFireEvent, 2.14. dvxWgt.h — Widget System
- wgtFont, 2.14. dvxWgt.h — Widget System
- wgtFontFor, 2.14. dvxWgt.h — Widget System
- wgtFrame, 4.3. Box (VBox / HBox / Frame)
- wgtGetApi, 2.14. dvxWgt.h — Widget System
- wgtGetContext, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtGetDebugLayout, 2.14. dvxWgt.h — Widget System
- wgtGetFocused, 2.14. dvxWgt.h — Widget System
- wgtGetIface, 2.14. dvxWgt.h — Widget System
- wgtGetIfaceOf, 2.14. dvxWgt.h — Widget System
- wgtGetPaddingPx, 2.14. dvxWgt.h — Widget System
- wgtGetProp, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtGetSpacingPx, 2.14. dvxWgt.h — Widget System
- wgtGetText, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtHBox, 4.3. Box (VBox / HBox / Frame)
- wgtHelpView, 4.11. HelpView
- wgtHelpViewClear, 4.11. HelpView
- wgtHelpViewGetLinkTarget, 4.11. HelpView
- wgtHelpViewGetTopic, 4.11. HelpView
- wgtHelpViewSetLinkCallback, 4.11. HelpView
- wgtHelpViewShowTopic, 4.11. HelpView
- wgtHSeparator, 4.22. Separator
- wgtIfaceCallMethod, 2.14. dvxWgt.h — Widget System
- wgtIfaceFindEvent, 2.14. dvxWgt.h — Widget System
- wgtIfaceFindMethod, 2.14. dvxWgt.h — Widget System
- wgtIfaceFindMethodArgs, 2.14. dvxWgt.h — Widget System
- wgtIfaceFindProp, 2.14. dvxWgt.h — Widget System
- wgtIfaceGetProp, 2.14. dvxWgt.h — Widget System
- wgtIfaceGetPropText, 2.14. dvxWgt.h — Widget System
- wgtIfaceIsLater, 2.14. dvxWgt.h — Widget System
- WgtIfaceLoadFnT, 2.14. dvxWgt.h — Widget System
- wgtIfaceMethodArgs, 2.14. dvxWgt.h — Widget System
- wgtIfaceSetProp, 2.14. dvxWgt.h — Widget System
- wgtIfaceSetPropText, 2.14. dvxWgt.h — Widget System
- wgtIfaceSetType, 2.14. dvxWgt.h — Widget System
- WgtIfaceT, 1.5. Widget System
- wgtImage, 4.12. Image
- wgtImageButton, 4.13. ImageButton
- wgtImageButtonFromFile, 4.13. ImageButton
- wgtImageButtonLoadData, 4.13. ImageButton
- wgtImageButtonLoadFile, 4.13. ImageButton
- wgtImageButtonSetData, 4.13. ImageButton
- wgtImageButtonSetStretch, 4.13. ImageButton
- wgtImageButtonSetTransparent, 4.13. ImageButton
- wgtImageFromFile, 4.12. Image
- wgtImageLoadData, 4.12. Image
- wgtImageLoadFile, 4.12. Image
- wgtImageSetData, 4.12. Image
- wgtImageSetStretch, 4.12. Image
- wgtImageSetTransparent, 4.12. Image
- wgtInitWindow, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtInvalidate, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtInvalidatePaint, 2.14. dvxWgt.h — Widget System
- wgtKeyReplace, 2.14. dvxWgt.h — Widget System
- wgtLabel, 4.14. Label
- wgtLabelGetAlign, 4.14. Label
- wgtLabelGetWordWrap, 4.14. Label
- wgtLabelSetAlign, 4.14. Label
- wgtLabelSetWordWrap, 4.14. Label
- wgtLayout, 2.14. dvxWgt.h — Widget System
- wgtListBox, 4.15. ListBox
- wgtListBoxAddItem, 4.15. ListBox
- wgtListBoxClear, 4.15. ListBox
- wgtListBoxClearSelection, 4.15. ListBox
- wgtListBoxGetItemData, 4.15. ListBox
- wgtListBoxGetMultiSelectMode, 4.15. ListBox
- wgtListBoxGetNewIndex, 4.15. ListBox
- wgtListBoxGetSelected, 4.15. ListBox
- wgtListBoxGetSorted, 4.15. ListBox
- wgtListBoxGetStyle, 4.15. ListBox
- wgtListBoxGetTopIndex, 4.15. ListBox
- wgtListBoxInsertItem, 4.15. ListBox
- wgtListBoxIsItemSelected, 4.15. ListBox
- wgtListBoxRemoveItem, 4.15. ListBox
- wgtListBoxSelectAll, 4.15. ListBox
- wgtListBoxSetItem, 4.15. ListBox
- wgtListBoxSetItemData, 4.15. ListBox
- wgtListBoxSetMultiSelect, 4.15. ListBox
- wgtListBoxSetMultiSelectMode, 4.15. ListBox
- wgtListBoxSetReorderable, 4.15. ListBox
- wgtListBoxSetSelected, 4.15. ListBox
- wgtListBoxSetSorted, 4.15. ListBox
- wgtListBoxSetStyle, 4.15. ListBox
- wgtListBoxSetTopIndex, 4.15. ListBox
- wgtListView, 4.16. ListView
- wgtListViewClearSelection, 4.16. ListView
- wgtListViewGetMultiSelect, 4.16. ListView
- wgtListViewGetSelected, 4.16. ListView
- wgtListViewGetSortCol, 4.16. ListView
- wgtListViewGetSortDir, 4.16. ListView
- wgtListViewInsertItem, 4.16. ListView
- wgtListViewSelectAll, 4.16. ListView
- wgtListViewSetColumns, 4.16. ListView
- wgtListViewSetData, 4.16. ListView
- wgtListViewSetHeaderClickCallback, 4.16. ListView
- wgtListViewSetMultiSelect, 4.16. ListView
- wgtListViewSetReorderable, 4.16. ListView
- wgtListViewSetSelected, 4.16. ListView
- wgtListViewSetSort, 4.16. ListView
- wgtMaskedInput, 4.29. TextInput / TextArea
- WgtMouseActionE, 2.14. dvxWgt.h — Widget System
- wgtPaint, 2.14. dvxWgt.h — Widget System
- wgtParseBool, 2.14. dvxWgt.h — Widget System
- wgtPasswordInput, 4.29. TextInput / TextArea
- wgtPercent, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtPixels, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtProgressBar, 4.17. ProgressBar
- wgtProgressBarGetValue, 4.17. ProgressBar
- wgtProgressBarGetVertical, 4.17. ProgressBar
- wgtProgressBarSetValue, 4.17. ProgressBar
- wgtProgressBarSetVertical, 4.17. ProgressBar
- wgtProgressBarV, 4.17. ProgressBar
- wgtRadio, 4.18. Radio Button
- wgtRadioGetIndex, 4.18. Radio Button
- wgtRadioGroup, 4.18. Radio Button
- wgtRadioGroupGetSelected, 4.18. Radio Button
- wgtRadioGroupSetSelected, 4.18. Radio Button
- wgtRadioIsSelected, 4.18. Radio Button
- wgtRadioSetSelected, 4.18. Radio Button
- wgtRegisterApi, 2.14. dvxWgt.h — Widget System
- wgtRegisterClass, 2.14. dvxWgt.h — Widget System
- wgtRegisterIface, 2.14. dvxWgt.h — Widget System
- wgtRegisterIfaceLater, 2.14. dvxWgt.h — Widget System
- wgtResolveSize, 2.14. dvxWgt.h — Widget System
- wgtResolveTypeName, 2.14. dvxWgt.h — Widget System
- wgtRichEdit, 4.19. RichEdit
- wgtRichEditGetRtf, 4.19. RichEdit
- wgtRichEditSetSelStyle, 4.19. RichEdit
- wgtRichLabel, 4.20. RichLabel
- wgtRichLabelAddText, 4.20. RichLabel
- wgtRichLabelSetFont, 4.20. RichLabel
- wgtScrollPane, 4.21. ScrollPane
- wgtScrollPaneGetScrollLeft, 4.21. ScrollPane
- wgtScrollPaneGetScrollTop, 4.21. ScrollPane
- wgtScrollPaneScrollToChild, 4.21. ScrollPane
- wgtScrollPaneScrollToTop, 4.21. ScrollPane
- wgtScrollPaneSetNoBorder, 4.21. ScrollPane
- wgtScrollPaneSetScrollLeft, 4.21. ScrollPane
- wgtScrollPaneSetScrollTop, 4.21. ScrollPane
- wgtSeparator, 4.22. Separator
- wgtSeparatorIsVertical, 4.22. Separator
- wgtSeparatorSetVertical, 4.22. Separator
- wgtSetBackdrop, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSetDebugLayout, 2.14. dvxWgt.h — Widget System
- wgtSetEnabled, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSetFocused, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSetFont, 2.14. dvxWgt.h — Widget System
- wgtSetName, 2.14. dvxWgt.h — Widget System
- wgtSetPaddingPx, 2.14. dvxWgt.h — Widget System
- wgtSetProp, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSetReadOnly, 2.14. dvxWgt.h — Widget System
- wgtSetSpacingPx, 2.14. dvxWgt.h — Widget System
- wgtSetText, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSetTooltip, 2.14. dvxWgt.h — Widget System
- wgtSetVisible, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- wgtSigDynamic, 2.14. dvxWgt.h — Widget System
- wgtSigInfo, 2.14. dvxWgt.h — Widget System
- WgtSigInfoT, 2.14. dvxWgt.h — Widget System
- wgtSlider, 4.23. Slider
- wgtSliderGetValue, 4.23. Slider
- wgtSliderSetValue, 4.23. Slider
- wgtSpacer, 4.24. Spacer
- wgtSpinner, 4.25. Spinner
- wgtSpinnerGetRealValue, 4.25. Spinner
- wgtSpinnerGetValue, 4.25. Spinner
- wgtSpinnerSetDecimals, 4.25. Spinner
- wgtSpinnerSetRange, 4.25. Spinner
- wgtSpinnerSetRealMode, 4.25. Spinner
- wgtSpinnerSetRealRange, 4.25. Spinner
- wgtSpinnerSetRealStep, 4.25. Spinner
- wgtSpinnerSetRealValue, 4.25. Spinner
- wgtSpinnerSetStep, 4.25. Spinner
- wgtSpinnerSetValue, 4.25. Spinner
- wgtSplitter, 4.26. Splitter
- wgtSplitterGetPos, 4.26. Splitter
- wgtSplitterGetVertical, 4.26. Splitter
- wgtSplitterSetPos, 4.26. Splitter
- wgtSplitterSetVertical, 4.26. Splitter
- wgtStatusBar, 4.27. StatusBar
- wgtTabControl, 4.28. TabControl
- wgtTabControlGetActive, 4.28. TabControl
- wgtTabControlSetActive, 4.28. TabControl
- wgtTabPage, 4.28. TabControl
- wgtTextArea, 4.29. TextInput / TextArea
- wgtTextAreaAppendText, 4.29. TextInput / TextArea
- wgtTextAreaClearLineMarkers, 4.29. TextInput / TextArea
- wgtTextAreaCopy, 4.29. TextInput / TextArea
- wgtTextAreaCursorToEnd, 4.29. TextInput / TextArea
- wgtTextAreaCut, 4.29. TextInput / TextArea
- wgtTextAreaFindNext, 4.29. TextInput / TextArea
- wgtTextAreaGetCursorCol, 4.29. TextInput / TextArea
- wgtTextAreaGetSelStart, 4.29. TextInput / TextArea
- wgtTextAreaGoToLine, 4.29. TextInput / TextArea
- wgtTextAreaPaste, 4.29. TextInput / TextArea
- wgtTextAreaReplaceAll, 4.29. TextInput / TextArea
- wgtTextAreaReplaceSelection, 4.29. TextInput / TextArea
- wgtTextAreaSelectAll, 4.29. TextInput / TextArea
- wgtTextAreaSetAutoIndent, 4.29. TextInput / TextArea
- wgtTextAreaSetColorize, 4.29. TextInput / TextArea
- wgtTextAreaSetCursor, 4.29. TextInput / TextArea
- wgtTextAreaSetGutterClick, 4.29. TextInput / TextArea
- wgtTextAreaSetLineMarker, 4.29. TextInput / TextArea
- wgtTextAreaSetSelText, 4.29. TextInput / TextArea
- wgtTextAreaSetShowLineNumbers, 4.29. TextInput / TextArea
- wgtTextAreaSetSyntaxMode, 4.29. TextInput / TextArea
- wgtTextAreaUndo, 4.29. TextInput / TextArea
- wgtTextInput, 4.29. TextInput / TextArea
- wgtTextInputCut, 4.29. TextInput / TextArea
- wgtTextInputGetSelStart, 4.29. TextInput / TextArea
- wgtTextInputPaste, 4.29. TextInput / TextArea
- wgtTextInputSetSelText, 4.29. TextInput / TextArea
- wgtTimer, 4.30. Timer
- wgtTimerGetRepeat, 4.30. Timer
- wgtTimerIsRunning, 4.30. Timer
- wgtTimerSetInterval, 4.30. Timer
- wgtTimerSetRepeat, 4.30. Timer
- wgtTimerStart, 4.30. Timer
- wgtTimerStop, 4.30. Timer
- wgtToolbar, 4.31. Toolbar
- wgtTreeItem, 4.32. TreeView
- wgtTreeItemIsExpanded, 4.32. TreeView
- wgtTreeItemIsSelected, 4.32. TreeView
- wgtTreeItemSetExpanded, 4.32. TreeView
- wgtTreeItemSetSelected, 4.32. TreeView
- wgtTreeView, 4.32. TreeView
- wgtTreeViewGetSelected, 4.32. TreeView
- wgtTreeViewSetMultiSelect, 4.32. TreeView
- wgtTreeViewSetReorderable, 4.32. TreeView
- wgtTreeViewSetSelected, 4.32. TreeView
- wgtUnregisterAppClasses, 2.14. dvxWgt.h — Widget System
- wgtUnregisterClass, 2.14. dvxWgt.h — Widget System
- wgtUnregisterIface, 2.14. dvxWgt.h — Widget System
- wgtUpdateCursorBlink, 5.2. wgtUpdateCursorBlink
- wgtUpdateTimers, 4.30. Timer
- wgtValueBool, 2.14. dvxWgt.h — Widget System
- wgtValueBytes, 2.14. dvxWgt.h — Widget System
- wgtValueDouble, 2.14. dvxWgt.h — Widget System
- wgtValueFloat, 2.14. dvxWgt.h — Widget System
- wgtValueInt, 2.14. dvxWgt.h — Widget System
- wgtValueLen, 2.14. dvxWgt.h — Widget System
- wgtValueStr, 2.14. dvxWgt.h — Widget System
- WgtValueT, 2.14. dvxWgt.h — Widget System
- wgtValueToBool, 2.14. dvxWgt.h — Widget System
- wgtValueToFloat, 2.14. dvxWgt.h — Widget System
- wgtValueToInt, 2.14. dvxWgt.h — Widget System
- wgtValueToText, 2.14. dvxWgt.h — Widget System
- wgtVBox, 4.3. Box (VBox / HBox / Frame)
- wgtVSeparator, 4.22. Separator
- wgtWrapBox, 4.33. WrapBox
- Widget API, 1.5. Widget System
- Widget Base, 4.2.1. DVX Widget System
- widgetAddChild, 2.21. dvxWgtP.h — Widget Plugin API
- widgetAlloc, 2.21. dvxWgtP.h — Widget Plugin API
- widgetCallbackTarget, 2.21. dvxWgtP.h — Widget Plugin API
- WidgetClassT, 1.5. Widget System, 2.14. dvxWgt.h — Widget System
- widgetClosePopup, 2.21. dvxWgtP.h — Widget Plugin API
- widgetDestroyChildren, 2.21. dvxWgtP.h — Widget Plugin API
- widgetDrawDropdownArrow, 5.16. List Helper Library
- widgetDrawScrollbarH, 2.21. dvxWgtP.h — Widget Plugin API
- widgetDrawScrollbarV, 2.21. dvxWgtP.h — Widget Plugin API
- widgetDropdownPopupRect, 5.16. List Helper Library
- widgetFindByAccel, 2.21. dvxWgtP.h — Widget Plugin API
- widgetFindNextFocusable, 2.21. dvxWgtP.h — Widget Plugin API
- widgetFindPrevFocusable, 2.21. dvxWgtP.h — Widget Plugin API
- widgetFireDoublePick, 2.14. dvxWgt.h — Widget System
- widgetFirePick, 2.14. dvxWgt.h — Widget System
- widgetGridNavigateIndex, 5.16. List Helper Library
- widgetHitTest, 2.21. dvxWgtP.h — Widget Plugin API
- widgetIsEnabledChain, 2.21. dvxWgtP.h — Widget Plugin API
- widgetKeyTo, 2.21. dvxWgtP.h — Widget Plugin API
- widgetMaxItemWidth, 5.16. List Helper Library
- widgetNavigateIndex, 5.16. List Helper Library
- widgetPaintPopupList, 5.16. List Helper Library
- widgetPressablePress, 2.21. dvxWgtP.h — Widget Plugin API
- widgetPressableRelease, 2.21. dvxWgtP.h — Widget Plugin API
- widgetPressOnChrome, 2.14. dvxWgt.h — Widget System
- widgetQuickPaintBegin, 2.21. dvxWgtP.h — Widget Plugin API
- widgetRestoreFocus, 2.21. dvxWgtP.h — Widget Plugin API
- Widgets, 1.5. Widget System
- widgetScrollbarApplyHit, 2.21. dvxWgtP.h — Widget Plugin API
- widgetScrollbarNeeds, 2.21. dvxWgtP.h — Widget Plugin API
- widgetScrollbarPressStep, 2.21. dvxWgtP.h — Widget Plugin API
- WidgetT, 1.5. Widget System, 2.14. dvxWgt.h — Widget System, 4.2.1. DVX Widget System
- widgetTextEditDragUpdateLine, 5.12. widgetTextEditDragUpdateLine
- widgetTextEditMouseClick, 5.13. widgetTextEditMouseClick
- widgetTextEditOnKey, 5.14. widgetTextEditOnKey
- widgetTextEditPaintLine, 5.15. widgetTextEditPaintLine
- widgetUsesEnter, 2.21. dvxWgtP.h — Widget Plugin API
- Window, 1.4.1. WindowT Structure
- Window Stack, 1.4.1. WindowT Structure
- Windows Sound System, 10.1. Sound Library
- WindowStackT, 2.2. dvxTypes.h — Shared Type Definitions
- WindowT, 1.4.1. WindowT Structure, 2.2. dvxTypes.h — Shared Type Definitions
- wmAddMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmAddMenuBar, 2.11. dvxWm.h — Layer 4: Window Manager
- wmAddMenuItem, 2.11. dvxWm.h — Layer 4: Window Manager
- wmAddSubMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmClampWindowPos, 2.11. dvxWm.h — Layer 4: Window Manager
- wmClearMenuItems, 2.11. dvxWm.h — Layer 4: Window Manager
- wmCreateMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmCreateWindow, 2.11. dvxWm.h — Layer 4: Window Manager
- wmDestroyWindow, 2.11. dvxWm.h — Layer 4: Window Manager
- wmDragBegin, 2.11. dvxWm.h — Layer 4: Window Manager
- wmDrawChrome, 2.11. dvxWm.h — Layer 4: Window Manager
- wmDrawScrollbarAt, 2.11. dvxWm.h — Layer 4: Window Manager
- wmFreeMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmHitTest, 2.11. dvxWm.h — Layer 4: Window Manager
- wmInit, 2.11. dvxWm.h — Layer 4: Window Manager
- wmInsertMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMaximize, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuBarLayout, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuBarShown, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuContains, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuFindItemInMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuItemSetCheckedInMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuItemSetEnabled, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMenuItemSetEnabledInMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMinimize, 2.11. dvxWm.h — Layer 4: Window Manager
- wmMinWindowSize, 2.11. dvxWm.h — Layer 4: Window Manager
- wmRaiseWindow, 2.11. dvxWm.h — Layer 4: Window Manager
- wmReallocContentBuf, 2.11. dvxWm.h — Layer 4: Window Manager
- wmRemoveMenu, 2.11. dvxWm.h — Layer 4: Window Manager
- wmRemoveMenuItem, 2.11. dvxWm.h — Layer 4: Window Manager
- wmResizeBegin, 2.11. dvxWm.h — Layer 4: Window Manager
- wmRestore, 2.11. dvxWm.h — Layer 4: Window Manager
- wmSetFocus, 2.11. dvxWm.h — Layer 4: Window Manager
- wmSetIconData, 2.11. dvxWm.h — Layer 4: Window Manager
- wmUpdateContentRect, 2.11. dvxWm.h — Layer 4: Window Manager
- Word Boundary, 5.7. wordBoundaryLeft, 5.8. wordBoundaryRight
- Word Select, 5.13. widgetTextEditMouseClick
- wordBoundaryLeft, 5.7. wordBoundaryLeft
- wordBoundaryRight, 5.8. wordBoundaryRight
- wordEnd, 5.5. wordEnd
- wordStart, 5.6. wordStart
- WrapBox, 4.33. WrapBox
- WtInfo$, 10.1. Sound Library
- WtStart, 10.1. Sound Library
X
- X25519, 7.1. Serial Stack, 7.3. Cryptography Library
- XChaCha20-Poly1305, 7.1. Serial Stack, 7.3. Cryptography Library
- xfer, 7.9. File Transfer Library
- xfer.bas, 7.12. File Transfers from BASIC
- xferAnswer, 7.10.1. Types
- xferCancel, 7.10.1. Types
- xferCreate, 7.10.1. Types
- xferDetectFeed, 7.10.1. Types
- XferIoT, 7.10.1. Types
- XferOptionsT, 7.10.1. Types
- xferPoll, 7.10.1. Types
- XferPoll, 7.12. File Transfers from BASIC
- xferProgress, 7.10.1. Types
- XferProgressT, 7.10.1. Types
- XferReceive, 7.12. File Transfers from BASIC
- XferReceiveFiles, 7.12. File Transfers from BASIC
- XferSendFile, 7.12. File Transfers from BASIC
- XferSendFiles, 7.12. File Transfers from BASIC
- xferSplitList, 7.12. File Transfers from BASIC
- xferStartReceive, 7.10.1. Types
- xferStartSend, 7.10.1. Types
- XM, 10.2. Music Library
- XMODEM, 7.9. File Transfer Library
- XTEA, 7.3. Cryptography Library
- XTEA-CTR, 7.3. Cryptography Library
Y
- YMODEM, 7.9. File Transfer Library
Z
- Z-Order, 1.4.1. WindowT Structure
- ZDLE, 7.11.1. XMODEM and XMODEM-1K
- ZMODEM, 7.9. File Transfer Library
- ZRPOS, 7.11.1. XMODEM and XMODEM-1K