CXL and TCXL compatible text library¶
CXL was Mike Smedley's shareware C library for DOS text-mode programs, from 1987 to 1990: windows with borders and shadows, pull-down menus, data entry forms, pick lists, context-sensitive help, keyboard, mouse, printer and EMS support, and string utilities. TCXL 5.5 was its successor under new names. Many programs from the time were written for it.
libcxl.a is a new implementation of that API, so such programs build
with clang-dos in every memory model. It is written from the published
manuals only, under the AGPL-3.0-only license; no CXL or TCXL code is in
it, and the internal record layouts, file formats and algorithms are its
own.

What is covered¶
The target is CXL 5.2, every documented function and global:
| Header | Contents |
|---|---|
<cxldef.h> |
cxlver, biosver, machid, the equipment-word functions, clockcal, extmem, expmem, timer, delay_, sound_, beep, tabstop, sysdate, systime, randfile, fcrypt |
<cxlvid.h> |
_vinfo, videoinit, adapter detection (including DESQview), direct video output, cursor, ssave/srestore, box_, screen and window files, CGA snow-free access |
<cxlkey.h> |
getxch, the key buffer (kbput, kbputs), setonkey, kbstat, getns, inputsf, waitkeyt |
<cxlmou.h> |
the ms* mouse functions and mssupport (mouse as arrow keys, as a pointer, or both) |
<cxlwin.h> |
windows, menus, forms, help, pick lists (wpickstr, wpickfile, wselstr, wpickattr) and window input and output |
<cxlstr.h> |
the str* functions and the cvt* field conversions |
<cxlprn.h> |
the lprint* printer functions, scrndump, windump |
<cxlems.h> |
the ems* LIM EMS functions |
wpickstr and wselstr take the initelem argument added in CXL 5.1.
Calls written for 5.0, without it, also compile: macros in <cxlwin.h>
count the arguments (define CXL_NO_50_CALLS to turn this off).
TCXL 5.5 names come from <tcxl.h> (and the TCXL header names,
<tcxlwin.h>, <tcxlmnu.h>, ..., which include it). It maps the renamed
functions of the TCXL manual's Appendix H onto the CXL ones, and adds the
TCXL types (IntT, ChrP, WndT, ...), constants (BOX_DBL, MNU_PUL,
FLD_UPR, ...), the Key_* key codes of <tcxlcod.h>, and these
TCXL-only functions: WpopUp, Wcenter, Werror, WputCen, Wputrj,
Wprtrj, Wprtns, Wprtsw, wprtf, WdupChrA, WdupStrA,
VcurHid, VcurSet, TcxlInit, TcxlTerm, EntFld and FldLoc.
Functions that return a CXL W_* error return TCXL's ERR_NUL,
ERR_ARG or ERR_MEM instead, with the detail in TcxlErr.
Not provided from TCXL: its internal records (WdfT, MdfT and the
rest), the functions that take VposT positions, MSpress, MSstat and
MSmove.
Building old programs¶
- Header names are lower case (
cxlwin.h); DOS does not mind either way. - clang spells
faras__far. Code that saysfarbuilds with-Dfar=__far(likewise-Dnear=__near,-Dhuge=__huge). - Old compilers defined
NULLas0, and programs passed it forintarguments such as the menu help category. clang makes that an error;-Wno-int-conversionlets it through. - Compiler library functions that are not part of CXL (Turbo C's
findfirst, Microsoft's<direct.h>) are not supplied bylibcxl.a;<dirent.h>hasopendir/readdir. - Large programs need the medium or large model, as with the compilers of the time.
The CXL 5.0 demonstration program builds and runs this way in the medium
and large models with only a stand-in for Turbo C's findfirst.
Choices where the manuals are silent¶
The manuals describe behavior, not formats or algorithms. Where a program could notice, the library does this:
wmenugetreturns the tag of the root menu item that was chosen, as the manual says; a choice in a pull-down menu endswmenugetunless its item has a select function. A hot key on an item without a select function chooses it if it is in the current menu; theM_EXITALLtag works from anywhere.- Filling the last character of the last form field ends
winpread, as Enter there does. The form shows the cursor while it runs. wpickstrlays the strings out in as many columns as fit the window.eroworecolof -1 sizes the window to the strings.wselstrchanges the string in place: the arrow keys or Space step through the choices, Enter takes one.wpickattrreturns -1 on Esc.wsetfill's function is called asfill(srow << 8 | scol, erow << 8 | ecol, ch, attr).sound_'s pitch is the timer divisor (1193180 / frequency).strcodeXORs with the key and leaves a byte alone where the result would be NUL, so strings stay strings.fcryptis a plain XOR, so running it twice restores a file. Neither matches the original CXL, so data encoded by a CXL program cannot be decoded.- Screen and window files (
scrntodisk,wintodisk) are four little-endian 16-bit words (start row, start column, end row, end column) followed by the character and attribute cells. - Help files are plain text. A topic starts with a line
*B number,name,*Pstarts a new page and*Eends the topic.^Name^is a cross-reference that Tab and Enter follow; it must be on the page shown. The default help window is 19 by 64, centered. cvticandcvtfcfields hold no decimal point;cvtcfplaces it byfracsize.
Example¶
examples/dos/cxldemo.c is a tour: a menu bar
with pull-down menus and a status line, overlapping, moving and hidden
windows, an address form with validation, pick lists of strings and
files, the colour picker and help from
cxldemo.hlp on F1.
tests/dos/README.md shows how to run it in
DOSBox, and tests/dos/cxl.c is the self-test that
run-tests.sh runs in emu2.