C X L
The C Programmer's Extended Function Library
Version 5.1
September 1, 1989
by Mike Smedley
Copyright (c) 1987-1989 All Rights Reserved
Reference Manual
Table of Contents
Introduction................................1
General Information....................1
Features of the CXL Library............1
Registration Information...............3
How to Contact the Author..............6
Disclaimer.............................6
Trademarks.............................6
Using CXL Functions....................7
Global Variables............................8
_kbinfo................................8
_mouse.................................8
_vinfo.................................8
_winfo.................................9
Library Functions..........................11
attrib................................11
beep..................................11
biosver...............................11
box_..................................12
capsoff...............................12
capson................................13
cclrscrn..............................13
cgardbyte.............................13
cgardword.............................14
cgareadn..............................14
cgawrbyte.............................14
cgawriten.............................15
cgawrstr..............................15
cgawrword.............................16
chgonkey..............................16
clearkeys.............................17
clockcal..............................17
clreol_...............................17
clrscrn...............................18
clrwin................................18
cvaltype..............................18
cvtcf.................................19
cvtci.................................19
cvtfc.................................20
cvtic.................................20
cxlver................................21
delay_................................21
disktoscrn............................21
disktowin.............................22
EMS Functions.........................23
emsalloc..............................24
emsdealloc............................24
emsexist..............................25
emsframe..............................25
emsfree...............................25
emsmap................................26
emsread...............................26
emstotal..............................27
i
emsver................................27
emswrite..............................27
expmem................................28
extmem................................28
fcrypt................................29
fill_.................................29
freonkey..............................30
gameport..............................30
getchf................................30
getcursz..............................31
getns.................................31
getxch................................32
gotoxy_...............................32
hidecur...............................33
inputsf...............................33
kbclear...............................34
kbmhit................................34
kbput.................................34
kbputs................................35
kbstat................................36
lcrlf.................................36
lgcursor..............................36
lprintc...............................37
lprintf...............................37
lprintns..............................38
lprints...............................38
lprintsb..............................38
lprintsu..............................39
machid................................39
mapattr...............................40
mathchip..............................40
mode..................................40
msbclear..............................41
msbpress..............................41
msbreles..............................42
mscondoff.............................43
mscursor..............................43
msgotoxy..............................44
mshbounds.............................44
mshidecur.............................45
msinit................................45
msmotion..............................45
msshowcur.............................46
msspeed...............................46
msstatus..............................46
mssupport.............................47
msvbounds.............................48
numflop...............................48
numoff................................48
numon.................................49
numpar................................49
numser................................49
printc................................50
prints................................50
ii
putchat...............................51
randfile..............................51
readchat..............................51
readcur...............................52
revattr...............................52
revsattr..............................53
scancode..............................53
scrndump..............................54
scrntodisk............................54
setattr...............................54
setcursz..............................55
setkbloop.............................55
setlines..............................56
setonkey..............................56
setvparam.............................57
showcur...............................57
smcursor..............................58
sound_................................58
spc...................................58
srestore..............................59
ssave.................................59
strblank..............................60
strbmatch.............................60
strbtrim..............................61
strchg................................61
strchksum.............................62
strcode...............................62
strdel................................63
strdela...............................63
strichg...............................64
strichksum............................64
stridel...............................65
stridela..............................65
striinc...............................66
strinc................................66
strins................................67
striocc...............................67
strischg..............................68
strisocc..............................69
strisrep..............................69
strleft...............................70
strljust..............................70
strltrim..............................71
strmatch..............................71
strmid................................72
strocc................................72
strright..............................73
strrjust..............................73
strrol................................74
strror................................74
strschg...............................75
strsetsz..............................75
strshl................................76
strshr................................77
iii
strsocc...............................77
strsrep...............................78
strtrim...............................78
struplow..............................79
sysdate...............................79
systime...............................80
tabstop...............................80
timer.................................81
touplow...............................81
videoinit.............................82
vidmode...............................82
vidtype...............................83
wactiv................................83
waitkey...............................84
waitkeyt..............................84
wborder...............................85
wbox..................................85
wbprintc..............................86
wcclear...............................86
wcenters..............................87
wchgattr..............................87
wchkbox...............................88
wchkcol...............................88
wchkcoord.............................89
wchkrow...............................89
wclear................................90
wclose................................90
wcloseall.............................90
wclreol...............................91
wclreos...............................91
wcopy.................................91
wdelline..............................92
wdrag.................................93
wdump.................................93
wdupc.................................93
wdups.................................94
werrmsg...............................95
wfill.................................95
wfillch...............................96
wfindrec..............................96
wgetc.................................96
wgetchf...............................97
wgetns................................97
wgets.................................98
wgetyn................................99
wgotoxy...............................99
whandle..............................100
Context-Sensitive Help Functions.....100
whelpcat.............................102
whelpclr.............................103
whelpdef.............................103
whelpop..............................104
whelpopc.............................104
whelppcat............................105
iv
whelpush.............................105
whelpushc............................105
whelpundef...........................106
whelpwin.............................106
whide................................107
whline...............................107
windowat.............................108
windump..............................109
Multi-Field Input Functions..........109
winpbeg..............................112
winpdef..............................113
winpfba..............................114
winpfcurr............................114
winpffind............................115
winpkey..............................115
winpread.............................116
winputsf.............................117
winsline.............................117
wintodisk............................118
wisactiv.............................118
Bar Menu Functions...................119
wmenubeg.............................120
wmenubegc............................121
wmenuend.............................122
wmenuget.............................123
wmenuiba.............................123
wmenuicurr...........................124
wmenuidsab...........................124
wmenuienab...........................125
wmenuifind...........................125
wmenuinext...........................126
wmenuitem............................126
wmenuitxt............................128
wmenumcurr...........................128
wmessage.............................129
wmove................................129
wopen................................130
wperror..............................131
wpgotoxy.............................131
wpickfile............................132
wpickstr.............................133
wprintc..............................134
wprintf..............................134
wprints..............................135
wprintsf.............................135
wputc................................136
wputns...............................137
wputs................................137
wputsw...............................138
wreadcur.............................138
wrestore.............................139
wrjusts..............................139
wsave................................140
wscanf...............................140
v
wscroll..............................141
wscrollbox...........................141
wselstr..............................142
wsetesc..............................142
wshadoff.............................143
wshadow..............................143
wsize................................144
wslide...............................144
wtabwidth............................145
wtextattr............................145
wtitle...............................146
wunhide..............................146
wunlink..............................147
wvline...............................147
wwprints.............................148
Appendix A - Text Attribute Identifiers...150
Appendix B - Keycode Table................151
Appendix C - Window Output Escape Codes...153
Appendix D - Format Control Characters....154
Appendix E - Input Field Editing Keys.....157
vi
Introduction
General Information.
The CXL library is intended to be a supplement to your C compiler's
standard run-time library. It contains over 260 multi-purpose functions
which provide a variety of capabilities. It is available for several
popular C compilers including Microsoft C, QuickC, Turbo C, and Zortech
C/C++. These routines were written in 99% highly-optimized C code
ensuring maximum program speed, minimum program size, easy modification,
and increased portability. This release is an evaluation release
containing everything you need to write C programs using the small
memory model. The libraries for the other memory models are supplied
when you register.
Features of the CXL Library.
o Powerful windowing system. Allows as many open windows as
memory permits. Windows can be stacked, tiled, shadowed, moved,
resized, and changed in many other ways. There is a whole
assortment of various input and output functions to interract
with windows.
o Multi-field formatted data entry. You can create data entry
forms that consist of one or more input fields. You have full
control over user input and can tie validation functions into
each input field. Features alpha and numeric justification,
capitalization conversion, formatting characters, and a large
assortment of editing keys.
o Moving bar menus. You can easily create pop-up, pull-down, and
Lotus-style menus, as well as any other custom menu that you can
define. Features full mouse support, nonselectable items,
global hot keys, and more.
o Scrollable pick menus. Allow you to pick one item from a list
of items. Features full mouse support and scroll bars. There
is also a dedicated file picker that uses this feature to let
you pick from a list of files, very similar to the way that the
Turbo C and QuickC environments' file pickers work.
o Context-sensitive help system. Help files are indexed for
speed. Help categories can be cross-referenced. Help can be
applied at the global, window, menu item, and input field
levels.
o Several video output methods. These include direct screen
writing, direct screen writing with CGA snow elimination, video
BIOS writing, and DESQview video buffer writing. These will
allow you to be video compatible with virtually any video
adapter or multitasking environment.
1
o EGA 43 and VGA 50-line modes. CXL provides functions to
directly change to and from these modes. CXL's video functions
are also compatible with nonstandard modes such as 132x25 and
120x43.
o Extensive mouse support. Mouse movements can be translated into
keypresses, and several CXL functions have a "point-and-shoot"
type of mouse support that utilizes a free-moving mouse cursor.
There are also several functions for directly manipulating
Microsoft-compatible mice.
o Keyboard management routines. Allows you to tie keystrokes to
functions, stuff and clear the keyboard buffer, set and read the
keyboard shift/toggle keys, and specify a function to be called
while waiting for a keypress.
o Advanced string manipulation. There are a host of string
manipulation functions that perform searching, replacing,
formatting, conversion, rotating, shifting, pattern matching,
encryption, and other string operations.
o Several other functions for expanded memory (EMS) usage, file
encryption, date and time formatting, equipment detection,
printing, sound, and more.
2
Registration Information.
CXL is distributed as User-Supported software. You are free to copy and
distribute this software freely, however, if you find it of use to you,
you are encouraged to register your copy. Registering your copy of the
software helps the author continue to provide professional-quality
software at very reasonable prices.
The Basic Registration is $35.00 and includes the full library source
code, one library disk of your choice, batch files to build and update
the libraries, royalty-free use of library functions, unlimited
technical support, and low-cost upgrades. Library disks contain all
memory model libraries supported by your compiler. They are available
for Microsoft C/QuickC, Turbo C, and Zortech C/C++.
Since you will have the source code, you will be able to use it to build
any of the libraries for the supported compilers. However, if you don't
want to hassle with building libraries, pre-compiled library disks are
available for an additional $5.00 each (one library disk is included in
the Basic Registration).
All materials are shipped on 5.25-inch floppy diskettes, however, there
is a 3.5-inch floppy diskette service available for an additional $5.00.
This is a once-per-order charge that covers as many 3.5-inch floppy
disks as are needed to ship your order.
Non-U.S. orders need to include $5.00 extra to cover additional shipping
and handling charges. Checks and money orders must be drawn on a U.S.
bank. Please send all payments payable in U.S. Dollars.
Texas residents must add 8% for state sales tax.
Print the registration form, REGISTER.DOC, or include on a piece of
paper your name, address, phone number, and brand of compiler, and send
it along with your payment to:
Mike Smedley
P.O. Box 33603
San Antonio, TX 78265-3603
If by chance, you don't have the REGISTER.DOC file, a copy of the
registration form is included on the next page.
3
CXL REGISTRATION FORM
NAME: ______________________________________________________
COMPANY: ______________________________________________________
ADDRESS: ______________________________________________________
______________________________________________________
CITY: ______________________________________________________
STATE: ________________________ ZIP CODE: _________________
PHONE: ______________________________________________________
E-MAIL ADDRESS: _______________________________________________
WHERE DID YOU RECEIVE CXL? ____________________________________
________________________________________________________________
COMMENTS: _____________________________________________________
________________________________________________________________
Basic Registration @ $35.00 $__________
(Circle ONE library disk)
Microsoft Turbo Zortech
Additional Library Disks @ $5.00 Each __________
(Circle each ADDITIONAL library disk)
Microsoft Turbo Zortech
3.5-Inch Floppy Disk Service @ $5.00 __________
(Covers entire order)
Shipping outside U.S. @ $5.00 __________
(Payments MUST be in U.S. Dollars/U.S. Bank)
SUBTOTAL: $__________
Texas Residents Add 8% State Sales Tax
$35 = $2.80 | $40 = $3.20 | $45 = $3.60 __________
$50 = $4.00 | $55 = $4.40 | $60 = $4.80
5.1 TOTAL: $__________
Remit to: Mike Smedley
P.O. Box 33603
San Antonio, TX 78265-3603
4
5
How to Contact the Author.
Primary:
CXL Tech Support BBS - (512) 590-0460 1200-14400 HST 8-N-1
Alternate:
CompuServe - 71331,2244
GEnie - M.SMEDLEY
U.S. Mail - Mike Smedley
P.O. Box 33603
San Antonio, TX 78265-3603
Disclaimer.
The author, Mike Smedley, claims no responsibility for any damages
caused by the use or misuse of this product. This product is
distributed "as is" with no warranty expressed or implied. The author
will not be responsible for any losses incurred, either directly or
indirectly, by the use of this product. Use this product entirely at
your own risk. The author reserves the right to make modifications at
any time. Prices are subject to change without notice.
Trademarks.
CompuServe is a registered trademark of CompuServe Incorporated.
DESQview is a trademark of Quarterdeck Office Systems.
Epson is a registered trademark of Seiko Epson Corporation.
GEnie is a trademark of GE Information Services.
IBM is a registered trademark of International Business Machines.
LIM and EMS are trademarks of Lotus, Intel, and Microsoft Corporations.
Lotus is a registered trademark of Lotus Development Corporation.
Microsoft is a registered trademark of Microsoft Corporation.
Turbo C is a registered trademark of Borland International.
Zortech is a trademark of Zortech Inc.
6
Using CXL Functions.
For every CXL function you use, there should be a corresponding CXL
header file #included at the top of your program. The CXL header files
should follow your standard compiler header files. For example:
#include <dos.h>
#include <stdio.h>
#include "cxldef.h"
#include "cxlwin.h"
The basic command line compiler/linker commands to build your file
containing CXL functions are as follows:
Microsoft C:
cl myfile.c cxlmss.lib
Quick C:
qcl myfile.c cxlmss.lib
Turbo C:
tcc myfile.c cxltcs.lib
Zortech C/C++:
ztc myfile cxlzts.lib
To use CXL from the Turbo C integrated environment (TC.EXE), you need to
create a project file containing the name of the CXL library. You can
call it MYFILE.PRJ and it can consist of just one line:
myfile.c cxltcs.lib
Then when you run TC.EXE, set the project file name to MYFILE.PRJ and
press the Make key.
7
Global Variables
NAME
_kbinfo
DESCRIPTION
A record which holds keyboard information. The individual structure
elements are:
kbuf - pointer to head record in key buffer.
onkey - pointer to head record in onkey list.
kbloop - pointer to function to call while waiting for a
keypress. This variable should be set with the
setkbloop() function.
inmenu - inmenu flag used internally by the menuing and picking
functions to help control mouse support.
source - source of last keypress. 0=keyboard, 1=key buffer, and
2=mouse key emulation.
SYNOPSIS
#include "cxlkey.h"
struct _kbinfo_t _kbinfo;
------------------------------------------------------------------------
NAME
_mouse
DESCRIPTION
This variable is set by the msinit() and/or mssupport() function. It
contains MS_NONE by default. If msinit() detects a mouse, it will
set _mouse to MS_KEYS. Also see the function descriptions of
msinit() and mssupport().
SYNOPSIS
#include "cxlmou.h"
int _mouse;
------------------------------------------------------------------------
NAME
_vinfo
DESCRIPTION
The video information record. The videoinit() function is
responsible for setting most of the elements in this record. If you
don't call videoinit(), they will default to CGA settings. If you
modify any of these, you must modify them AFTER the call to
videoinit(). The one exception is _vinfo.dvcheck which, if used,
must be set BEFORE the call to videoinit(). The setvparam()
function should be used where possible. The individual structure
elements are:
videoseg - video buffer segment address. Default is 0xb800.
adapter - video adapter type. Default is V_CGA.
8
numrows - number of displayed rows. Default is 25.
numcols - number of displayed columns. Default is 80.
cheight - character height in pixels. Default is 8.
cwidth - character width in pixels. Default is 8.
mono - is it a monochrome video adapter? Default is 0.
mapattr - map color attribs to monochrome attribs? By default,
if a monochrome video adapter is detected by
videoinit(), then all color attributes will be mapped
to monochrome equivalents. To disable this automatic
mapping, set _vinfo.mapattr=0;. Default is 1.
cgasnow - is CGA snow present? To turn snow elimination on,
set _vinfo.cgasnow=1; and _vinfo.usebios=0;. Default
is 0.
usebios - use BIOS for video writes? To use BIOS for video
writes, set _vinfo.usebios=1; and _vinfo.cgasnow=0;.
Default is 0.
dvcheck - check for DESQview? To disable videoinit() from
checking for DESQview, set _vinfo.dvcheck=0; before
calling videoinit(). Default is 1.
dvexist - is DESQview present? Default is 0.
SYNOPSIS
#include "cxlvid.h"
struct _vinfo_t _vinfo;
------------------------------------------------------------------------
NAME
_winfo
DESCRIPTION
The window information record. The individual structure elements
are:
active - pointer to active window's record.
hidden - pointer to head hidden window's record.
menu - pointer to head menu's record.
cmenu - pointer to current menu's record.
helptr - pointer to help information record.
handle - last handle given to a window. Every time wopen()
creates a new window, it increments this value.
maxfiles - maximum number of files that can be displayed by
wpickfile(). Default is 500.
help - current help category number.
errno - error number from last windowing function. Most
windowing functions set this variable before
returning. The werrmsg() function returns a literal
representation of this value.
total - total number of open windows.
mlevel - system variable used by menu functions.
ilevel - system variable used by menu functions.
esc - check for [Esc] in input funcions? You should use the
wsetesc() function to set this value. Default is 1
(yes).
tabwidth - window TTY output tab width. You can use wtabwidth()
9
to set this value. Default is 8.
fillch - character to fill windows with. You should use
wfillch() to set this value. Default is ' '.
SYNOPSIS
#include "cxlwin.h"
struct _winfo_t _winfo;
10
Library Functions
NAME
attrib
DESCRIPTION
Creates a text attribute. It is usually much easier to create a
text attribute using the attribute identifiers listed in Appendix A,
but this provides an alternate method.
SYNOPSIS
#include "cxlvid.h"
int attrib(int fore,int back,int bright,int blink);
INPUTS
fore - foreground color code (0-7)
back - background color code (0-7)
bright - intensity (0-1)
blink - blinking (0-1)
RETURN VALUE
The new attribute code.
ALSO SEE
setattr wtextattr
EXAMPLE
prints(10,5,attrib(6,0,1,1),"Hello, world");
------------------------------------------------------------------------
NAME
beep
DESCRIPTION
Sounds a beep in the speaker.
SYNOPSIS
#include "cxldef.h"
void beep(void);
ALSO SEE
sound_
------------------------------------------------------------------------
NAME
biosver
DESCRIPTION
Returns the ROM BIOS version date.
SYNOPSIS
11
#include "cxldef.h"
char *biosver(void);
RETURN VALUE
The address of the static string containing the ROM BIOS version
date.
ALSO SEE
machid
------------------------------------------------------------------------
NAME
box_
DESCRIPTION
"Draws" a text box on the screen.
SYNOPSIS
#include "cxlvid.h"
void box_(int srow,int scol,int erow,int ecol,int btype,int attr);
INPUTS
srow - start row of box
scol - start column of box
erow - end row of box
ecol - end column of box
btype - box type. Can be one of the following:
0 - single line
1 - double line
2 - single horz, double vert line
3 - double horz, single vert line
4 - thick line
5 - no border (uses spaces for box chars)
attr - text attribute for border characters
ALSO SEE
fill_
EXAMPLE
box_(10,10,20,40,2,YELLOW|_BLACK);
------------------------------------------------------------------------
NAME
capsoff
DESCRIPTION
Toggles the CapsLock key off.
SYNOPSIS
#include "cxlkey.h"
void capsoff(void);
12
ALSO SEE
capson kbstat numoff numon
------------------------------------------------------------------------
NAME
capson
DESCRIPTION
Toggles the CapsLock key on.
SYNOPSIS
#include "cxlkey.h"
void capson(void);
ALSO SEE
capsoff kbstat numoff numon
------------------------------------------------------------------------
NAME
cclrscrn
DESCRIPTION
Clears the screen using given text attribute and homes the cursor.
SYNOPSIS
#include "cxlvid.h"
void cclrscrn(int attr);
INPUTS
attr - text attribute to use to clear the screen with
ALSO SEE
clreol_ clrscrn clrwin
EXAMPLE
cclrscrn(BLACK|_BLACK);
------------------------------------------------------------------------
NAME
cgardbyte
DESCRIPTION
Reads a byte from CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
int cgardbyte(char far *src);
INPUTS
src - far address to CGA video memory to read.
13
RETURN VALUE
The byte read.
ALSO SEE
cgardword cgareadn cgawrbyte cgawriten cgawrstr cgawrword
------------------------------------------------------------------------
NAME
cgardword
DESCRIPTION
Reads a word from CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
int cgardword(int far *src);
INPUTS
src - far address to CGA video memory to read.
RETURN VALUE
The word read.
ALSO SEE
cgardbyte cgareadn cgawrbyte cgawriten cgawrstr cgawrword
------------------------------------------------------------------------
NAME
cgareadn
DESCRIPTION
Reads n words from CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
void cgareadn(int far *src,int *dest,unsigned n);
INPUTS
src - far address to CGA video memory to read.
dest - address of buffer where words will be copied to.
n - number of words to read.
ALSO SEE
cgardbyte cgardword cgawrbyte cgawriten cgawrstr cgawrword
------------------------------------------------------------------------
NAME
cgawrbyte
DESCRIPTION
Writes a byte to CGA video memory without snow.
14
SYNOPSIS
#include "cxlvid.h"
void cgawrbyte(char far *dest,int chr);
INPUTS
dest - far address to CGA video memory to write to.
chr - the byte to write
ALSO SEE
cgardbyte cgardword cgareadn cgawriten cgawrstr cgawrword
------------------------------------------------------------------------
NAME
cgawriten
DESCRIPTION
Writes n words to CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
void cgawriten(int *src,int far *dest,unsigned n);
INPUTS
src - address of source buffer from which words will be read.
dest - far address to CGA video memory to write to.
n - number of words to write.
ALSO SEE
cgardbyte cgardword cgareadn cgawrbyte cgawrstr cgawrword
------------------------------------------------------------------------
NAME
cgawrstr
DESCRIPTION
Writes a string to CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
void cgawrstr(char far *dest,char *string,int attr);
INPUTS
dest - far address to CGA video memory to write to.
string - address of the string to be written.
attr - text attribute to be used for characters in string.
ALSO SEE
cgardbyte cgardword cgareadn cgawrbyte cgawriten cgawrword
------------------------------------------------------------------------
NAME
15
cgawrword
DESCRIPTION
Writes a word to CGA video memory without snow.
SYNOPSIS
#include "cxlvid.h"
void cgawrword(int far *dest,int chratr);
INPUTS
dest - far address to CGA video memory to write to.
chratr - word to be written in the form ((attr<<8)|ch).
ALSO SEE
cgardbyte cgardword cgareadn cgawrbyte cgawriten cgawrstr
------------------------------------------------------------------------
NAME
chgonkey
DESCRIPTION
The setonkey() function builds a linked list in memory that contains
each defined onkey. This function, chgonkey(), allows you to
maintain individual setonkey() lists and change back and forth
between them. You *could* use several setonkey() calls to define
and un-define keys where appropriate, but you would find that it is
a lot of trouble. chgonkey() provides painless switching between
onkey lists.
SYNOPSIS
#include "cxlkey.h"
struct _onkey_t *chgonkey(struct _onkey_t *kblist);
INPUTS
The address of the onkey list to change to. If you specify NULL,
then no onkeys will be visible.
RETURN VALUE
The address of the previous onkey list. Often you will want to save
this address so that you can restore it later.
ALSO SEE
freonkey setonkey
EXAMPLE
struct _onkey_t *k1,*k2;
setonkey(0x2100,do_alt_f,0);
/* [Alt-F] is defined */
setonkey(0x2300,do_alt_f,0);
/* [Alt-H] is defined */
k1=chgonkey(NULL);
/* [Alt-F] and [Alt-H] are disabled */
setonkey(0x1205,do_ctrl_e,0);
16
/* [Ctrl-E] is defined */
k2=chgonkey(k1);
/* [Ctrl-E] is disabled, [Alt-F] and [Alt-H] are reenabled */
freonkey();
/* [Alt-F] and [Alt-H] are disabled and freed from memory */
chgonkey(k2);
/* [Ctrl-E] is reenabled */
------------------------------------------------------------------------
NAME
clearkeys
DESCRIPTION
Clears the keyboard buffer.
SYNOPSIS
#include <conio.h>
#include "cxlkey.h"
void clearkeys(void);
ALSO SEE
kbclear waitkey
------------------------------------------------------------------------
NAME
clockcal
DESCRIPTION
Determines if a clock-calendar board is installed. This usually
will only work with the clock-calendar boards in XT-style machines.
SYNOPSIS
#include "cxldef.h"
int clockcal(void);
RETURN VALUE
Nonzero if a clock-calendar board is present.
------------------------------------------------------------------------
NAME
clreol_
DESCRIPTION
Clears to the end of line using the text attribute under the cursor.
SYNOPSIS
#include "cxlvid.h"
void clreol_(void);
ALSO SEE
cclrscrn clrscrn clrwin
17
------------------------------------------------------------------------
NAME
clrscrn
DESCRIPTION
Clears the screen using the text attribute under the cursor, and
homes the cursor.
SYNOPSIS
#include "cxlvid.h"
void clrscrn(void);
ALSO SEE
cclrscrn clreol_ clrwin
------------------------------------------------------------------------
NAME
clrwin
DESCRIPTION
Clears a window of the screen using the text attribute under the
cursor.
SYNOPSIS
#include "cxlvid.h"
void clrwin(int srow,int scol,int erow,int ecol);
INPUTS
srow - start row of window
scol - start column of window
erow - end row of window
ecol - end column of window
ALSO SEE
cclrscrn clreol_ clrscrn
------------------------------------------------------------------------
NAME
cvaltype
DESCRIPTION
Checks given character against a given CXL character type code, and
determines if that character is valid for that type. This function
is used internally by several CXL functions.
SYNOPSIS
#include "cxlstr.h"
int cvaltype(int ch,int ctype);
INPUTS
ch - character to test
18
ctype - character type code to compare with. See section on CXL
format strings for a list of valid character type codes.
See Appendix D for a list of character type codes which can
be used.
RETURN VALUE
-1 - invalid ctype was given
0 - character is not valid for given ctype
1 - character is valid for given ctype
EXAMPLE
printf("'A' is %sa valid character of type '#'\n",cvaltype('A','#')?
"":"not ");
printf("'7' is %sa valid character of type '#'\n",cvaltype('7','#')?
"":"not ");
------------------------------------------------------------------------
NAME
cvtcf
DESCRIPTION
Converts a CXL field string to a floating point number.
SYNOPSIS
#include "cxlstr.h"
double cvtcf(char *field,int wholesize,int fracsize);
INPUTS
field - address of CXL field string
wholesize - number of whole digits
fracsize - number of fractional digits
RETURN VALUE
A double precision floating point number.
ALSO SEE
cvtci cvtfc cvtic
EXAMPLE
double pi;
pi=cvtcf("314159",1,5);
printf("pi = %f\n",pi);
------------------------------------------------------------------------
NAME
cvtci
DESCRIPTION
Converts a CXL field string to an integer.
SYNOPSIS
#include "cxlstr.h"
19
int cvtci(char *field);
INPUTS
field - address of CXL field string
RETURN VALUE
An integer number.
ALSO SEE
cvtcf cvtfc cvtic
EXAMPLE
int i;
i=cvtci("32767");
printf("i = %d\n",i);
------------------------------------------------------------------------
NAME
cvtfc
DESCRIPTION
Converts a floating point number to a CXL field string.
SYNOPSIS
#include "cxlstr.h"
void cvtfc(char *field,double value,int wholesize,int fracsize);
INPUTS
field - address of buffer to receive field string
value - floating point number to convert
wholesize - number of whole digits
fracsize - number of fractional digits
ALSO SEE
cvtcf cvtci cvtic
EXAMPLE
char field[8];
cvtfc(field,3.14159,2,4);
printf("field = '%s'\n",field);
------------------------------------------------------------------------
NAME
cvtic
DESCRIPTION
Converts an integer to a CXL field string.
SYNOPSIS
#include "cxlstr.h"
void cvtic(char *field,int value,int size);
20
INPUTS
field - address of buffer to receive CXL field string
value - integer value to convert
size - field size
ALSO SEE
cvtcf cvtci cvtfc
EXAMPLE
char field[8];
cvtic(field,27,5);
printf("field = '%s'\n",field);
------------------------------------------------------------------------
NAME
cxlver
DESCRIPTION
Returns the CXL version number of the current CXL library in use.
SYNOPSIS
#include "cxldef.h"
char *cxlver(void);
RETURN VALUE
The address of the static string containing the CXL version number.
------------------------------------------------------------------------
NAME
delay_
DESCRIPTION
Delays program execution for a specified duration.
SYNOPSIS
#include "cxldef.h"
void delay_(unsigned duration);
INPUTS
duration - duration of delay (0-65535) ie. 182 = 10 seconds
ALSO SEE
timer waitkeyt
EXAMPLE
delay_(36); /* pause for 2 seconds */
------------------------------------------------------------------------
NAME
disktoscrn
21
DESCRIPTION
Copies a previously saved screen disk file to the screen.
SYNOPSIS
#include "cxlvid.h"
int disktoscrn(char *fname);
INPUTS
fname - address of the string containing file name to read from.
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
disktowin scrntodisk wintodisk
EXAMPLE
char fname[]="SCRN.DAT";
if(disktoscrn(fname)) {
printf("Error reading file: %s\n",fname);
exit(1);
}
------------------------------------------------------------------------
NAME
disktowin
DESCRIPTION
Copies a previously saved window disk file to the screen.
SYNOPSIS
#include "cxlvid.h"
int disktowin(char *fname);
INPUTS
fname - address of the string containing file name of file to read
from.
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
disktoscrn scrntodisk wintodisk
EXAMPLE
char fname[]="WIND.DAT";
if(disktowin(fname)) {
printf("Error reading file: %s\n",fname);
exit(1);
}
------------------------------------------------------------------------
22
EMS Functions
CXL contains several functions for simple management of expanded
memory. All of CXL's EMS functions are prefixed with 'ems'. For those
not familiar with expanded memory, here is a brief explanation.
The 8088 microprocessor is only able to address 1 Megabyte of memory.
When applications started needing more memory, Lotus, Intel, and
Microsoft developed the Expanded Memory Specification. This
specification allows access to more than 1 Megabyte of memory by mapping
16K 'windows' of memory on an expanded memory board in and out of an
unused area of DOS memory. The Expanded Memory Manager (EMM) is a
software driver that controls the mapping.
Physical pages are 16K blocks of memory which are located in an unused
area of DOS memory. There are typically 4 physical pages comprising a
64K contiguous area of mappable DOS memory. The EMS page frame base
address points to the beginning of the first physical page. Logical
pages are 16K blocks of memory on the expanded memory board. There can
be as many logical pages as the expanded memory board has, up to 8
Megabytes.
Every program that uses expanded memory must do the following:
1. determine if the EMM device driver is loaded
2. determine if there are enough free pages for its application
3. allocate pages of expanded memory
4. find out what the EMS page frame base address is
5. map logical pages onto physical pages
6. deallocate pages when finished with them
Here's an example of using CXL's EMS functions to perform these
procedures:
int handle1,handle2;
char buf[14];
if(!emsexist()) { /* Check for the EMM driver. */
printf("EMM not loaded\n");
exit(1);
}
handle1=emsalloc(2); /* Request 2 pages of EMS */
/* memory. */
handle2=emsalloc(2); /* Request 2 more pages. */
if(handle1==-1 || handle2==-1) { /* Test for allocation error. */
printf("EMS allocation error\n");
exit(1);
}
emsmap(handle1,0,0); /* Map logical page 0 of handle */
/* 1 to physical page 0. */
emswrite("Hello, world",0,13); /* Write a string at offset 0, */
/* automatically determines what*/
/* the page frame address is. */
emsmap(handle2,0,0); /* Map logical page 0 of handle */
/* 2 to physical page 0. */
23
emswrite("How are you?",0,13); /* Write a string at offset 0. */
emsmap(handle1,0,0); /* Map logical page 0 of handle */
/* 1 to physical page 0. */
emsread(buf,0,13); /* Read 13 bytes from offset 0 */
/* into buffer. */
printf("buf = %s\n",buf); /* Display buffer contents. */
emsmap(handle2,0,0); /* Map logical page 0 of handle */
/* 2 to physical page 0. */
emsread(buf,0,13); /* Read 13 bytes from offset 0 */
/* into buffer. */
printf("buf = %s\n",buf); /* Display buffer contents. */
emsdealloc(handle2); /* Deallocate pages belonging */
/* to handle 2. */
emsdealloc(handle1); /* Deallocate pages belonging */
/* to handle 1. */
------------------------------------------------------------------------
NAME
emsalloc
DESCRIPTION
Allocates pages of EMS memory.
SYNOPSIS
#include "cxlems.h"
int emsalloc(int numpages);
INPUTS
numpages - the number of pages (16K blocks) of memory requested.
For example, to allocate 512K of EMS memory, you would
request 512/16, or 32 pages.
RETURN VALUE
The EMS handle assigned to the allocated block of memory, or -1 if
an error occurred.
ALSO SEE
emsdealloc emsexist emsfree
------------------------------------------------------------------------
NAME
emsdealloc
DESCRIPTION
Deallocates previously allocated pages of EMS memory.
SYNOPSIS
#include "cxlems.h"
int emsdealloc(int handle);
INPUTS
handle - the EMS handle of the allocated EMS memory to deallocate
24
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
emsalloc emsexist
------------------------------------------------------------------------
NAME
emsexist
DESCRIPTION
Determines if the EMS device driver is loaded.
SYNOPSIS
#include "cxlems.h"
int emsexist(void);
RETURN VALUE
Nonzero if an EMS driver is loaded and functioning properly.
ALSO SEE
emsfree emstotal expmem
------------------------------------------------------------------------
NAME
emsframe
DESCRIPTION
Returns the EMS page frame base segment address.
SYNOPSIS
#include "cxlems.h"
unsigned emsframe(void);
RETURN VALUE
The EMS page frame base segment address, or zero if an error
occurred.
ALSO SEE
emsalloc emsexist emsmap
EXAMPLE
char far *p;
p=MK_FP(emsframe(),0);
printf("EMS memory starts at %Fp\n",p);
------------------------------------------------------------------------
NAME
emsfree
DESCRIPTION
25
Returns the number of free EMS pages (16K blocks).
SYNOPSIS
#include "cxlems.h"
unsigned emsfree(void);
RETURN VALUE
The number of free EMS pages.
ALSO SEE
emsalloc emsdealloc emstotal
------------------------------------------------------------------------
NAME
emsmap
DESCRIPTION
Maps a logical page of allocated EMS memory onto a physical page
address.
SYNOPSIS
#include "cxlems.h"
int emsmap(int handle,int lpage,int ppage);
INPUTS
handle - the EMS handle previosly assigned
lpage - the logical EMS page to map (0 - ?)
ppage - the physical DOS page to map to (0 - 3)
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
emsalloc emsdealloc emsframe
------------------------------------------------------------------------
NAME
emsread
DESCRIPTION
Reads bytes from one or more pages of allocated EMS memory. The
emsmap() function must be called prior to this function to make this
memory accessible. The source segment used will be the current EMS
page frame segment address and the destination segment will be your
program's data segment.
SYNOPSIS
#include "cxlems.h"
int emsread(char *dest,unsigned emsofs,unsigned numbytes);
INPUTS
dest - address of buffer to receive bytes read from EMS
26
emsofs - offset from the EMS page frame base segment address to
read the bytes from.
numbytes - the number of bytes to read
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
emsalloc emsdealloc emsmap emswrite
------------------------------------------------------------------------
NAME
emstotal
DESCRIPTION
Returns the total number of EMS memory pages (16K blocks) on the
system.
SYNOPSIS
#include "cxlems.h"
unsigned emstotal(void);
RETURN VALUE
The total number of EMS memory pages on the system.
ALSO SEE
emsalloc emsdealloc emsexist emsfree expmem
------------------------------------------------------------------------
NAME
emsver
DESCRIPTION
Returns the version of the EMS driver in use.
SYNOPSIS
#include "cxlems.h"
char *emsver(void);
RETURN VALUE
The address of the static string containing the EMS version number,
or NULL if an error occurred.
ALSO SEE
emsexist
------------------------------------------------------------------------
NAME
emswrite
DESCRIPTION
27
Writes bytes to one or more pages of EMS memory. The emsmap()
function must have been called prior to calling this function so
that the EMS memory will be available. The source segment will be
your program's data segment and the destination segment will be the
current EMS page frame segment address.
SYNOPSIS
#include "cxlems.h"
int emswrite(char *src,unsigned emsofs,unsigned numbytes);
INPUTS
src - address of buffer that contains the bytes to be written
emsofs - offset from EMS page frame base segment address to write
bytes to
numbytes - number of bytes to write
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
emsexist emsframe emsmap emsread
------------------------------------------------------------------------
NAME
expmem
DESCRIPTION
Determines the amount, if any, of expanded memory on the system. An
EMS driver does not have to be loaded to call this function.
SYNOPSIS
#include "cxldef.h"
unsigned expmem(void);
RETURN VALUE
The amount of expanded memory in kilobytes.
ALSO SEE
emsexist extmem
------------------------------------------------------------------------
NAME
extmem
DESCRIPTION
Determines the amount of extended memory on an AT-class machine.
SYNOPSIS
#include "cxldef.h"
unsigned extmem(void);
RETURN VALUE
28
The amount of extended memory in kilobytes.
ALSO SEE
expmem
------------------------------------------------------------------------
NAME
fcrypt
DESCRIPTION
Encrypts or decrypts a text or binary file using a modified XOR
encryption method. The same encryption key string must be used when
decrypting the file as when encrypting it.
SYNOPSIS
#include "cxldef.h"
int fcrypt(char *file,char *key);
INPUTS
file - address of filename string of file to encrypt or decrypt.
key - address of encryption key string. The string can contain any
ASCII characters (01 - FF). The longer the string is, the
better the encryption. Do not lose the key, or you won't see
your data again!
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
strcode
EXAMPLE
fcrypt("CXL.DOC","This is my encryption key string");
------------------------------------------------------------------------
NAME
fill_
DESCRIPTION
Fills in a region of the screen with a specified character and
attribute.
SYNOPSIS
#include "cxlvid.h"
void fill_(int srow,int scol,int erow,int ecol,int ch,int attr);
INPUTS
srow - start row
scol - start column
erow - end row
ecol - end column
ch - character to fill with
29
attr - attribute of character
ALSO SEE
attrib box_
EXAMPLE
fill_(5,15,16,42,'X',LRED|_MAGENTA);
------------------------------------------------------------------------
NAME
freonkey
DESCRIPTION
Frees all active onkey definitions from memory. After this call,
any keys defined using setonkey() will no longer be active.
SYNOPSIS
#include "cxlkey.h"
void freonkey(void);
ALSO SEE
chgonkey setonkey
------------------------------------------------------------------------
NAME
gameport
DESCRIPTION
Determines if a game port is installed.
SYNOPSIS
#include "cxldef.h"
int gameport(void);
RETURN VALUE
Nonzero if a game port is installed.
ALSO SEE
mathchip numflop numpar numser
------------------------------------------------------------------------
NAME
getchf
DESCRIPTION
Gets a character from the keyboard from a list of valid characters.
The case of the letters in the valid character list is ignored.
Provides Escape checking.
SYNOPSIS
#include "cxlkey.h"
30
int getchf(char *valid,int defchar);
INPUTS
valid - address of string containing list of valid characters
defchar - default selection in case [Enter] is pressed, or zero if
you don't want to have a default selection
RETURN VALUE
The character pressed, or zero if the [Esc] key was pressed. The
returned character will be uppercase.
ALSO SEE
getxch waitkey
EXAMPLE
int ch;
printf("Are you sure? ");
ch=getchf("YN",'Y');
if(!ch) printf("[Esc] was pressed\n");
------------------------------------------------------------------------
NAME
getcursz
DESCRIPTION
Returns the start and stop scan lines of cursor.
SYNOPSIS
#include "cxlvid.h"
void getcursz(int *sline,int *eline);
INPUTS
sline - address of integer to receive start scan line
eline - address of integer to receive stop scan line
ALSO SEE
setcursz
EXAMPLE
int sline,eline;
getcursz(&sline,&eline);
printf("Cursor start & stop scan lines: %d, %d\n",sline,eline);
------------------------------------------------------------------------
NAME
getns
DESCRIPTION
Inputs a string of a specified maximum length from the keyboard.
Provides Escape checking.
SYNOPSIS
31
#include "cxlkey.h"
int getns(char *str,int maxchars);
INPUTS
str - address of buffer to receive input string
maxchars - maximum length of the input string
RETURN VALUE
Nonzero if the [Esc] key was pressed during user input.
ALSO SEE
inputsf
EXAMPLE
char name[11];
printf("Enter your name: ");
if(getns(name,10))
printf("\n[Esc] was pressed\n");
else
printf("\nYour name is: %s\n",name);
------------------------------------------------------------------------
NAME
getxch
DESCRIPTION
Gets a key (ASCII code/scan code) from the keyboard. All CXL
functions that interract with the keyboard call this function for
input.
SYNOPSIS
#include "cxlkey.h"
unsigned getxch(void);
RETURN VALUE
The keycode of the pressed key. The keycode contains the scan code
of the keypress in the upper byte, and the ASCII character in the
lower byte. A list of keycodes is in Appendix B.
ALSO SEE
getchf
EXAMPLE
unsigned int keycode;
printf("Press a key: ");
keycode=getxch();
printf("%c\nkeycode = %#x, scancode = %d, ASCII code = %d\n"
,keycode,keycode,keycode>>8,keycode&0x00ff);
------------------------------------------------------------------------
NAME
gotoxy_
32
DESCRIPTION
Sets cursor coordinates on the screen.
SYNOPSIS
#include "cxlvid.h"
void gotoxy_(int row,int col);
INPUTS
row - cursor row (Y coordinate)
col - cursor column (X coordinate)
ALSO SEE
readcur
------------------------------------------------------------------------
NAME
hidecur
DESCRIPTION
Hides the cursor. Retains the cursor shape so that when showcur()
is called, the original cursor shape will be restored.
SYNOPSIS
#include "cxlvid.h"
void hidecur(void);
ALSO SEE
lgcursor setcursz showcur smcursor
------------------------------------------------------------------------
NAME
inputsf
DESCRIPTION
Inputs a formatted string from the keyboard. This function provides
an extremely powerful method of accept single-line input from the
user. You can limit input characters to certain characters of a
type, such as numbers, insert strings in between typed in
characters, create custom prompts, disable [Enter] until the field
is filled, and more. Provides Escape checking.
SYNOPSIS
#include "cxlkey.h"
int inputsf(char *str,char *fmt);
INPUTS
str - address of the buffer receive input string
fmt - address of the format string. See Appendix D for valid format
string characters.
RETURN VALUE
0 - no error
33
1 - [Esc] key was pressed
2 - invalid format string
ALSO SEE
getns
EXAMPLE
char buf[21];
if(inputsf(buf,"'Enter your name: '!M!AAAAAAAAAAAAAAAAAAAA")==1)
printf("\n[Esc] key was pressed\n");
else
printf("\nYour name is: %s\n",buf);
------------------------------------------------------------------------
NAME
kbclear
DESCRIPTION
Clears CXL's internal keyboard buffer.
SYNOPSIS
#include "cxlkey.h"
void kbclear(void);
ALSO SEE
clearkeys kbmhit kbput kbputs
------------------------------------------------------------------------
NAME
kbmhit
DESCRIPTION
Determines if a key has been pressed and is waiting to be got. Also
checks for mouse button presses. Replaces the kbhit() function.
SYNOPSIS
#include "cxlkey.h"
int kbmhit(void);
RETURN VALUE
Nonzero if a key is waiting to be got.
ALSO SEE
kbclear
------------------------------------------------------------------------
NAME
kbput
DESCRIPTION
Places a keystroke into CXL's internal keyboard buffer. This will
34
only affect CXL's keyboard input functions. This function is useful
for making keyboard scripts for demos, etc., or forcing user
keyboard input.
SYNOPSIS
#include "cxlkey.h"
int kbput(unsigned xch);
INPUTS
xch - keycode of keypress to place in buffer. The scan code will be
in the high byte and the ASCII code will be in the low byte.
See Appendix B for a list of keycodes which you can use.
RETURN VALUE
Nonzero if memory allocation error.
ALSO SEE
kbclear kbputs
EXAMPLE
kbput(0x011b); /* puts an [Esc] keypress into CXL's buffer */
------------------------------------------------------------------------
NAME
kbputs
DESCRIPTION
Places a string of characters into CXL's internal keyboard buffer.
This will only affect CXL's keyboard input functions. This function
is useful for making keyboard scripts for demos, etc., and forcing
user keyboard input.
SYNOPSIS
#include "cxlkey.h"
int kbputs(char *str);
INPUTS
str - address of string of characters to stuff into buffer
RETURN VALUE
Nonzero if memory allocation error.
ALSO SEE
kbclear kbput
EXAMPLE
char buf[21];
kbputs("Mike");
printf("Enter your name: ");
getns(buf,20);
------------------------------------------------------------------------
35
NAME
kbstat
DESCRIPTION
Returns the status of the keyboard control keys.
SYNOPSIS
#include "cxlkey.h"
unsigned kbstat(void);
RETURN VALUE
Status word of the keyboard flag. You can determine which key(s)
are being pressed/toggled by masking the status word (using the
bitwise '&' operator) with one of the following:
RSHIFT - right shift pressed
LSHIFT - left shift pressed
CTRL - [Ctrl] pressed
ALT - [Alt] pressed
SCRLOCK - [ScrollLock] toggled
NUMLOCK - [NumLock] toggled
CAPSLOCK - [CapsLock] toggled
INS - [Ins] toggled
ALSO SEE
capsoff capson numoff numon
EXAMPLE
printf("NumLock is %s\n",(kbstat()&NUMLOCK)?"on":"off");
------------------------------------------------------------------------
NAME
lcrlf
DESCRIPTION
Prints a carriage return and line feed on the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void lcrlf(void);
ALSO SEE
lprintc lprintf lprints
------------------------------------------------------------------------
NAME
lgcursor
DESCRIPTION
Makes the cursor large.
SYNOPSIS
#include "cxlvid.h"
36
void lgcursor(void);
ALSO SEE
hidecur setcursz showcur smcursor
------------------------------------------------------------------------
NAME
lprintc
DESCRIPTION
Prints a character on the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void lprintc(int ch);
INPUTS
ch - the character to print
ALSO SEE
lcrlf lprintf
EXAMPLE
lprintc(12); /* sends a form feed to the printer */
------------------------------------------------------------------------
NAME
lprintf
DESCRIPTION
Sends formatted output to the printer (PRN). Works similar to the
standard C printf() function.
SYNOPSIS
#include "cxlprn.h"
void lprintf(const char *format,...);
INPUTS
format - format string. Refer to the section on printf() in your
compiler's run-time library reference.
... - any additional arguments
ALSO SEE
lcrlf lprintc lprintns lprints
EXAMPLE
char s[]="Hello";
int i=5;
char c='Z';
lprintf("s = %s, i = %d, c = %c\n\f",s,i,c);
------------------------------------------------------------------------
37
NAME
lprintns
DESCRIPTION
Prints a string to a fixed width on the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void lprintns(char *str,int width);
INPUTS
str - the address of the string to print
width - width to print string, either by padding or truncating.
ALSO SEE
lcrlf lprintf lprints lprintsu
EXAMPLE
char string[]="Hello, world";
lprintns(string,5);
lprintf(".\n");
lprintns(string,20);
lprintf(".\n");
------------------------------------------------------------------------
NAME
lprints
DESCRIPTION
Prints a string on the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void lprints(char *str);
INPUTS
str - the address of the string to print
ALSO SEE
lcrlf lprintf lprintns lprintsu
EXAMPLE
lprints("Hello, world\n");
------------------------------------------------------------------------
NAME
lprintsb
DESCRIPTION
Prints a bold-faced string on the printer (PRN).
SYNOPSIS
38
#include "cxlprn.h"
void lprintsb(char *str,int reps);
INPUTS
str - address of the string to print
reps - number of strike repetitions (the more, the darker the print)
ALSO SEE
lcrlf lprintf lprintns lprints lprintsu
------------------------------------------------------------------------
NAME
lprintsu
DESCRIPTION
Prints an underlined string on the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void lprintsu(char *str);
INPUTS
str - address of the string to print
ALSO SEE
lcrlf lprintf lprintns lprints lprintsb
------------------------------------------------------------------------
NAME
machid
DESCRIPTION
Returns the value of the machine ROM ID byte.
SYNOPSIS
#include "cxldef.h"
int machid(void);
RETURN VALUE
The value of the machine ROM ID byte. Will usually be one of the
following values. Any other value is unknown.
IBMPC - IBM PC
IBMPCXT - IBM PC/XT
IBMPCJR - IBM PCjr
IBMPCAT - IBM PC/AT
IBMPCXT2 - IBM PC/XT-2
IBMCONV - IBM PC Convertible
SPERRYPC - Sperry PC
ALSO SEE
biosver
39
------------------------------------------------------------------------
NAME
mapattr
DESCRIPTION
Translates a color text attribute into its approximate monochrome
equivalent. All of CXL's video functions automatically call this,
so you would only need to call this for your own functions.
SYNOPSIS
#include "cxlvid.h"
int mapattr(int attr);
INPUTS
attr - the color text attribute to translate
RETURN VALUE
The monochrome equivalent of the color text attribute.
ALSO SEE
revsattr
EXAMPLE
int attr=LCYAN|_BLUE;
prints(0,0,attr,"In living color!");
_vinfo.mapattr=1; /* force monochrome attributes */
prints(1,0,mapattr(attr),"In dull monochrome....");
------------------------------------------------------------------------
NAME
mathchip
DESCRIPTION
Determines if a math coprocessor is installed.
SYNOPSIS
#include "cxldef.h"
int mathchip(void);
RETURN VALUE
Nonzero if a math coprocessor is installed.
ALSO SEE
gameport numflop numpar numser
EXAMPLE
printf("You do %shave a math coprocessor\n",mathchip()?"":"not ");
------------------------------------------------------------------------
NAME
mode
40
DESCRIPTION
Sets the video mode.
SYNOPSIS
#include "cxlvid.h"
void mode(int mode_code);
INPUTS
mode_code - video mode code
ALSO SEE
setlines vidmode vidtype
------------------------------------------------------------------------
NAME
msbclear
DESCRIPTION
Clears the mouse driver's "button presses" and "button releases"
counters (removes them from the queue).
SYNOPSIS
#include "cxlmou.h"
void msbclear(void);
ALSO SEE
kbmhit msbpress msbreles msinit msstatus
------------------------------------------------------------------------
NAME
msbpress
DESCRIPTION
Returns information about the specific button presses of mouse.
SYNOPSIS
#include "cxlmou.h"
void msbpress(int button,int *bstat,int *bcount,int *row,int *col);
INPUTS
button - button to check:
0 - left button
1 - right button
2 - middle button (if applicable)
bstat - address of integer to receive button status word. Possible
button status values are:
0 - no buttons pressed
1 - left button pressed
2 - right button pressed
4 - middle button pressed (if applicable)
3 - left & right buttons pressed
5 - left & middle buttons pressed (if applicable)
41
6 - middle & right buttons pressed (if applicable)
7 - all 3 buttons pressed (if applicable)
bcount - address of integer to receive number of times pressed since
last call
row - address of integer to receive row at time of button press
col - address of integer to receive column at time of button
press
ALSO SEE
msbclear msbreles msinit msstatus
EXAMPLE
int bstat,bcount,row,col;
msbpress(0,&bstat,&bcount,&row,&col);
------------------------------------------------------------------------
NAME
msbreles
DESCRIPTION
Returns informmation about specific button releases of mouse.
SYNOPSIS
#include "cxlmou.h"
void msbreles(int button,int *bstat,int *bcount,int *row,int *col);
INPUTS
button - button to check:
0 - left button
1 - right button
2 - middle button (if applicable)
bstat - address of integer to receive button status word. Possible
button status values are:
0 - no buttons pressed
1 - left button pressed
2 - right button pressed
4 - middle button pressed (if applicable)
3 - left & right buttons pressed
5 - left & middle buttons pressed (if applicable)
6 - middle & right buttons pressed (if applicable)
7 - all 3 buttons pressed (if applicable)
bcount - address of integer to receive number of times released
since last call
row - address of integer to receive row at time of button release
col - address of integer to receive column at time of button
release
ALSO SEE
msbclear msbpress msinit msstatus
EXAMPLE
int bstat,bcount,row,col;
msbreles(0,&bstat,&bcount,&row,&col);
42
------------------------------------------------------------------------
NAME
mscondoff
DESCRIPTION
Conditionally hides the mouse cursor depending on whether or not the
mouse cursor falls within the input screen coordinates.
SYNOPSIS
#include "cxlmou.h"
void mscondoff(int srow,int scol,int erow,int ecol);
INPUTS
srow - start row
scol - start column
erow - end row
ecol - end column
ALSO SEE
mshidecur msinit msshowcur
------------------------------------------------------------------------
NAME
mscursor
DESCRIPTION
Sets the mouse text cursor type. The mouse cursor can be a hardware
or softare cursor. The hardware cursor is the same as the normal
cursor you see when you are at the DOS prompt. Because the mouse's
hardware cursor is the same as the normal cursor, they can interfere
with each other, making this method impractical to use in most
cases. The software mouse cursor is a text box that can reveal the
underlying character. This is the cursor most used by programs
including other CXL mouse support functions.
SYNOPSIS
#include "cxlmou.h"
void mscursor(unsigned curtype,unsigned smask,unsigned cmask);
INPUTS
curtype - cursor type. 0=software, 1=hardware
smask - screen mask (software cursor) or start scan line (hardware
cursor). If using a software cursor, the screen mask
determines which of the characters attributes are
preserved. It is ANDed with the screen character and
attribute. The bit format for both smask and cmask are:
Bit Content
--- -------
0-7 - ASCII character code
8-10 - foreground color
11 - 0=intensity off, 1=intensity on
12-14 - background color
43
15 - 0=no blink, 1=blink
cmask - cursor mask (software cursor) or stop scan line (hardware
cursor). If using a software cursor, the cursor mask is
used to determine which of the characteristics are changed
by the cursor. The cmask is XORed with the result of
(smask AND character-attribute). The bit values for cmask
are the same as those for smask.
ALSO SEE
msinit msshowcur
EXAMPLE
mscursor(1,1,7); /* makes a full-block hardware cursor */
msshowcur();
------------------------------------------------------------------------
NAME
msgotoxy
DESCRIPTION
Sets the mouse cursor coordinates.
SYNOPSIS
#include "cxlmou.h"
void msgotoxy(int row,int col);
INPUTS
row - row (Y coordinate)
col - column (X coordinate)
ALSO SEE
msinit msstatus
EXAMPLE
msgotoxy(13,45); /* sets mouse cursor to row 13, column 45 */
------------------------------------------------------------------------
NAME
mshbounds
DESCRIPTION
Sets the mouse's upper and lower horizontal bounds.
SYNOPSIS
#include "cxlmou.h"
void mshbounds(int leftcol,int rightcol);
INPUTS
leftcol - left column boundary
rightcol - right column boundary
ALSO SEE
44
msinit msvbounds
EXAMPLE
mshbounds(5,45); /* restricts mouse cursor movement */
/* between columns 5 & 45 */
------------------------------------------------------------------------
NAME
mshidecur
DESCRIPTION
Hides the mouse cursor.
SYNOPSIS
#include "cxlmou.h"
void mshidecur(void);
ALSO SEE
msinit msshowcur
------------------------------------------------------------------------
NAME
msinit
DESCRIPTION
Determines if a mouse is present. If so, initializes mouse and sets
the global variable _mouse to MS_KEYS which causes mouse movements
to be translated to the keyboard arrow keys.
SYNOPSIS
#include "cxlmou.h"
int msinit(void);
RETURN VALUE
Nonzero if mouse is present.
ALSO SEE
mssupport
EXAMPLE
if(msinit())
printf("Mouse initialized\n");
else
printf("Mouse does not exist\n");
------------------------------------------------------------------------
NAME
msmotion
DESCRIPTION
Gets information about the movement of the mouse.
45
SYNOPSIS
#include "cxlmou.h"
void msmotion(int *rowcount,int *colcount);
INPUTS
rowcount - address of integer to receive number of rows moved
colcount - address of integer to receive number of columns moved
ALSO SEE
msinit msstatus
EXAMPLE
int rowcount,colcount;
msmotion(&rowcount,&colcount);
------------------------------------------------------------------------
NAME
msshowcur
DESCRIPTION
Reveals the hidden mouse cursor.
SYNOPSIS
#include "cxlmou.h"
void msshowcur(void);
ALSO SEE
mscursor mshidecur msinit
------------------------------------------------------------------------
NAME
msspeed
DESCRIPTION
Adjusts the mouse's speed by changing its sensitivity.
SYNOPSIS
#include "cxlmou.h"
void msspeed(int xratio,int yratio);
INPUTS
xratio - horizontal speed (higher numbers are slower)
yratio - vertical speed (higher numbers are slower)
ALSO SEE
msinit
------------------------------------------------------------------------
NAME
msstatus
46
DESCRIPTION
Returns the status of the mouse.
SYNOPSIS
#include "cxlmou.h"
void msstatus(int *bstat,int *row,int *col);
INPUTS
bstat - address of integer to receive button status word. Possible
button status values are:
0 - no buttons pressed
1 - left button pressed
2 - right button pressed
4 - middle button pressed (if applicable)
3 - left & right buttons pressed
5 - left & middle buttons pressed (if applicable)
6 - middle & right buttons pressed (if applicable)
7 - all 3 buttons pressed (if applicable)
row - address of integer to receive current row coordinate
col - address of integer to receive current column coordinate
ALSO SEE
msinit
EXAMPLE
int bstat,row,col;
msstatus(&bstat,&row,&col);
printf("The mouse cursor is at row %d, column %d\n",row,col);
------------------------------------------------------------------------
NAME
mssupport
DESCRIPTION
Selects the type of mouse support to be used by CXL functions which
support them. If no mouse exists, the call to this function is
ignored. This function should be called after msinit().
SYNOPSIS
#include "cxlmou.h"
void mssupport(int type);
INPUTS
type - type of mouse support. Can be one of the following:
MS_NONE - no mouse support
MS_KEYS - mouse movements are translated into keystrokes.
This is the default set by msinit() if it finds
a mouse driver present.
MS_CURS - point-and-shoot mouse cursor where supported
MS_FULL - full mouse support. If a CXL function supports
a point-and-shoot mouse cursor, then that will
be used, otherwise mouse movements will be
translated into keystrokes.
47
ALSO SEE
msinit
EXAMPLE
mssupport(MS_FULL);
------------------------------------------------------------------------
NAME
msvbounds
DESCRIPTION
Sets the mouse's left and right vertical bounds.
SYNOPSIS
#include "cxlmou.h"
void msvbounds(int toprow,int botrow);
INPUTS
toprow - top row boundary
botrow - bottom row boundary
ALSO SEE
mshbounds msinit
EXAMPLE
msvbounds(3,20); /* restricts mouse cursor movement */
/* between rows 3 and 20 */
------------------------------------------------------------------------
NAME
numflop
DESCRIPTION
Returns the number of floppy disk drives installed.
SYNOPSIS
#include "cxldef.h"
int numflop(void);
RETURN VALUE
The number of floppy disk drives installed
ALSO SEE
gameport mathchip numpar numser
EXAMPLE
printf("You have %d floppy drives installed\n",numflop());
------------------------------------------------------------------------
NAME
numoff
48
DESCRIPTION
Toggles the NumLock key off.
SYNOPSIS
#include "cxlkey.h"
void numoff(void);
ALSO SEE
capsoff kbstat numon
------------------------------------------------------------------------
NAME
numon
DESCRIPTION
Toggles the NumLock key on.
SYNOPSIS
#include "cxlkey.h"
void numon(void);
ALSO SEE
capson kbstat numoff
------------------------------------------------------------------------
NAME
numpar
DESCRIPTION
Returns the number of parallel ports.
SYNOPSIS
#include "cxldef.h"
int numpar(void);
RETURN VALUE
The number of parallel ports installed.
ALSO SEE
gameport mathchip numflop numser
EXAMPLE
printf("You have %d parallel ports\n",numpar());
------------------------------------------------------------------------
NAME
numser
DESCRIPTION
Returns the number of serial ports installed.
49
SYNOPSIS
#include "cxldef.h"
int numser(void);
RETURN VALUE
The number of serial ports installed.
ALSO SEE
gameport mathchip numflop numpar
EXAMPLE
printf("You have %d serial ports\n",numser());
------------------------------------------------------------------------
NAME
printc
DESCRIPTION
Displays a character to the screen at a specified location, using a
specified attribute. Does not recognize control characters. Does
not affect cursor position.
SYNOPSIS
#include "cxlvid.h"
void printc(int row,int col,int attr,int ch);
INPUTS
row - row to display character at
col - column to display character at
attr - text attribute for character
ch - character to print
ALSO SEE
attrib prints
EXAMPLE
printc(12,40,BLINK|LRED|_BLACK,'!');
------------------------------------------------------------------------
NAME
prints
DESCRIPTION
Displays a string on the screen at a specified location, using a
specified attribute. Does not affect cursor position.
SYNOPSIS
#include "cxlvid.h"
void prints(int row,int col,int attr,char *str);
INPUTS
row - row to display string at
50
col - column to display string at
attr - text attribute for characters displayed
str - address of string to display
ALSO SEE
attrib printc
EXAMPLE
prints(24,15,YELLOW|_BROWN,"Hello, world");
------------------------------------------------------------------------
NAME
putchat
DESCRIPTION
Puts a character and its attribute on the screen at current cursor
position using video BIOS calls.
SYNOPSIS
#include "cxlvid.h"
void putchat(int ch,int attr);
INPUTS
ch - character to display
attr - attribute to display character in
ALSO SEE
readchat
------------------------------------------------------------------------
NAME
randfile
DESCRIPTION
Creates a random file name.
SYNOPSIS
#include "cxldef.h"
char *randfile(void);
RETURN VALUE
Address of the static string containing the random file name.
EXAMPLE
printf("A random file name is: %s\n",randfile());
------------------------------------------------------------------------
NAME
readchat
DESCRIPTION
51
Reads the character and attribute under the cursor using video BIOS
calls.
SYNOPSIS
#include "cxlvid.h"
unsigned readchat(void);
RETURN VALUE
Unsigned integer containing the character in the low byte and
attribute in the high byte.
ALSO SEE
putchat revattr setattr
EXAMPLE
unsigned int chat;
chat=readchat();
printf("character value = %d, attribute value = %d\n",chat&0x00ff
,chat>>8);
------------------------------------------------------------------------
NAME
readcur
DESCRIPTION
Reads the current cursor location.
SYNOPSIS
#include "cxlvid.h"
void readcur(int *row,int *col);
INPUTS
row - address of integer to receive cursor row
col - address of integer to receive cursor column
ALSO SEE
gotoxy_
EXAMPLE
int row,col;
readcur(&row,&col);
printf("The cursor is at row %d, column %d\n",row,col);
------------------------------------------------------------------------
NAME
revattr
DESCRIPTION
Reverses the attribute of the character under the current cursor
position, and continues for the specified number of characters.
Uses video BIOS calls.
52
SYNOPSIS
#include "cxlvid.h"
void revattr(int count);
INPUTS
count - the number of characters to reverse the attribute of
ALSO SEE
readchat revsattr setattr
EXAMPLE
prints(0,0,LCYAN|_BLUE,"Hello, world");
gotoxy_(0,0);
revattr(5);
------------------------------------------------------------------------
NAME
revsattr
DESCRIPTION
Returns the inverse of the given text attribute.
SYNOPSIS
#include "cxlvid.h"
int revsattr(int attr);
INPUTS
attr - text attribute
RETURN VALUE
The inverted text attribute.
ALSO SEE
mapattr revattr
EXAMPLE
int attr=LMAGENTA|_RED;
prints(0,0,attr,"Normal");
prints(1,0,revsattr(attr),"Reverse");
------------------------------------------------------------------------
NAME
scancode
DESCRIPTION
Returns the common scan code of the specified character.
SYNOPSIS
#include "cxlkey.h"
int scancode(int ch);
INPUTS
53
ch - an ASCII character
RETURN VALUE
The common scan code of the specified character. The characters
'0' thru '9', '*', '-', '+', and '.' will return their scan code
from their regular keys, not their numeric keypad keys.
------------------------------------------------------------------------
NAME
scrndump
DESCRIPTION
Dumps the current screen to the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void scrndump(void);
ALSO SEE
scrntodisk ssave videoinit
------------------------------------------------------------------------
NAME
scrntodisk
DESCRIPTION
Copies the current screen to a disk file.
SYNOPSIS
#include "cxlvid.h"
int scrntodisk(char *fname);
INPUTS
fname - address of the string containing the filename of the file
to write to
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
disktoscrn scrndump ssave wintodisk
------------------------------------------------------------------------
NAME
setattr
DESCRIPTION
Sets the attribute of the character under the current cursor
location, and continues for the specified number of characters.
Uses video BIOS calls.
54
SYNOPSIS
#include "cxlvid.h"
void setattr(int attr,int count);
INPUTS
attr - attribute to set character
count - the number of characters to set the attribute of
ALSO SEE
attrib readchat revattr
EXAMPLE
prints(0,0,LCYAN|_BLUE,"Hello, world");
gotoxy_(0,0);
setattr(LMAGENTA|_RED,5);
------------------------------------------------------------------------
NAME
setcursz
DESCRIPTION
Sets the cursor size. This function is video adapter dependent.
SYNOPSIS
#include "cxlvid.h"
void setcursz(int sline,int eline);
INPUTS
sline - start line of cursor, 32 = no cursor
eline - end line of cursor
ALSO SEE
getcursz hidecur lgcursor showcur smcursor
EXAMPLE
setcursz(1,7); /* sets cursor to large block on color displays */
------------------------------------------------------------------------
NAME
setkbloop
DESCRIPTION
Most of the time your program is idle, it is waiting for a keypress.
This function allows you to set up a function that will be called
while waiting for a keypress. For example, you could update a
status line, or update a time clock continuously while waiting for a
keypress.
SYNOPSIS
#include "cxlkey.h"
void setkbloop(void (*func)(void));
55
INPUTS
func - address of the function to be called while waiting for
keypress or NULL to cancel the procedure.
ALSO SEE
waitkey waitkeyt
------------------------------------------------------------------------
NAME
setlines
DESCRIPTION
Sets the number of lines on the display. The videoinit() function
must have previously been called.
SYNOPSIS
#include "cxlvid.h"
int setlines(int numlines);
INPUTS
numlines - the number of lines to set the display to. Valid numbers
are:
25 - all video adapters
43 - EGA
50 - VGA
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
mode videoinit vidtype
EXAMPLE
printf("%s\n",setlines(43)?"You do not have an EGA card":
"You are now in EGA 43-line mode");
------------------------------------------------------------------------
NAME
setonkey
DESCRIPTION
Attaches/detaches a keypress to a function call. Works by
intercepting any calls to CXL keyboard input functions. Whenever
you use one of CXL's keyboard input functions, the input function
will check to see if the pressed key has been defined. If so, then
the input function will call the corresponding function. If not,
then the input function will pass on the keypress as normal.
SYNOPSIS
#include "cxlkey.h"
int setonkey(unsigned keycode,void (*func) (void),unsigned pass);
56
INPUTS
keycode - keycode of key to define. If the keycode was previously
defined, it will be re-defined. See Appendix B for a list
of keycodes.
func - address of the function to call upon keypress. If NULL is
specified for func, then the specified keycode will be
un-defined.
pass - keycode of key to pass back to caller after the onkey
function returns. This allows you to have one keypress
return the code for another. If pass==0, then the key
will not be passed back, and execution will resume where
the interruption occurred.
RETURN VALUE
Nonzero if a memory allocation error occurred.
ALSO SEE
chgonkey freonkey setkbloop
EXAMPLE
setonkey(0x011b,escape_routine,0);
------------------------------------------------------------------------
NAME
setvparam
DESCRIPTION
Sets video display parameters.
SYNOPSIS
#include "cxlvid.h"
int setvparam(int setting);
INPUTS
setting - video display parameter. Can be one of the following:
VP_DMA - turn on direct screen writes
VP_CGA - turn on direct screen writes w/CGA snow elimination
VP_BIOS - turn on BIOS screen writes
VP_MONO - turn on monochrome attribute translation
VP_COLOR - turn off monochrome attribute translation
RETURN VALUE
Nonzero if error.
ALSO SEE
videoinit vidtype
------------------------------------------------------------------------
NAME
showcur
DESCRIPTION
57
Reveals the hidden cursor, restoring it to its previous shape.
SYNOPSIS
#include "cxlvid.h"
void showcur(void);
ALSO SEE
hidecur lgcursor setcursz smcursor
------------------------------------------------------------------------
NAME
smcursor
DESCRIPTION
Makes the cursor small.
SYNOPSIS
#include "cxlvid.h"
void smcursor(void);
ALSO SEE
hidecur lgcursor setcursz showcur
------------------------------------------------------------------------
NAME
sound_
DESCRIPTION
Sounds a tone of specified pitch and duration.
SYNOPSIS
#include "cxldef.h"
void sound_(unsigned pitch,unsigned duration);
INPUTS
pitch - pitch of tone (0-65535)
duration - duration of tone (0-65535). ie. 182 = 10 seconds
ALSO SEE
beep
EXAMPLE
sound_(5000,36); /* sounds a tone for 2 seconds */
------------------------------------------------------------------------
NAME
spc
DESCRIPTION
Displays a specified number of spaces to the screen using the text
attribute of the character under the cursor.
58
SYNOPSIS
#include "cxlvid.h"
void spc(int num);
INPUTS
num - number of spaces to display
------------------------------------------------------------------------
NAME
srestore
DESCRIPTION
Restores a previously saved screen, and frees the memory allocated
by ssave().
SYNOPSIS
#include "cxlvid.h"
void srestore(int *sbuf);
INPUTS
sbuf - address of previously saved screen buffer
ALSO SEE
ssave
------------------------------------------------------------------------
NAME
ssave
DESCRIPTION
Saves the current screen to a buffer. To work with monochrome video
adapters, videoinit() must have previously been called.
SYNOPSIS
#include "cxlvid.h"
int *ssave(void);
RETURN VALUE
Address of newly created screen buffer or NULL if a memory
allocation error occurred.
ALSO SEE
scrntodisk srestore videoinit wsave
EXAMPLE
int *p;
if((p=ssave())==NULL) {
printf("Memory allocation error\n");
exit(1);
}
------------------------------------------------------------------------
59
NAME
strblank
DESCRIPTION
Determines if a given string is blank (whitespace).
SYNOPSIS
#include "cxlstr.h"
int strblank(char *str);
INPUTS
str - address of the string to check
RETURN VALUE
A zero if the string is not blank, otherwise it is.
EXAMPLE
char string1[]=" Hello ";
char string2[]=" \n \t \r ";
printf("string1 is %sblank\n",strblank(string1)?"":"not ");
printf("string2 is %sblank\n",strblank(string2)?"":"not ");
------------------------------------------------------------------------
NAME
strbmatch
DESCRIPTION
Returns the best match of a string in an array of strings.
SYNOPSIS
#include "cxlstr.h"
char *strbmatch(char *str,char *strarr[]);
INPUTS
str - address of string to match
strarr - address of array of string pointers. The last pointer in
the array must be NULL.
RETURN VALUE
Address of the string in the array that best matched the given
string.
ALSO SEE
strmatch
EXAMPLE
char *strings[]= { "Hello","There","Computer","World",NULL };
char str1[]="xhelpx";
printf("<%s> best matches <%s>\n",str1,strbmatch(str1,strings));
------------------------------------------------------------------------
NAME
60
strbtrim
DESCRIPTION
Trims both leading and trailing spaces off of a string.
SYNOPSIS
#include "cxlstr.h"
char *strbtrim(char *str);
INPUTS
The address of the string to modify.
RETURN VALUE
The address of the modified string.
ALSO SEE
strltrim strtrim
EXAMPLE
char str[]=" Hello ";
printf("Before: <%s>\n",str);
strbtrim(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strchg
DESCRIPTION
Finds all letters in a string matching one character and replaces
them with another.
SYNOPSIS
#include "cxlstr.h"
int strchg(char *str,int oldch,int newch);
INPUTS
str - address of string to search
oldch - character to search for
newch - character to replace with
RETURN VALUE
The number of matches found.
ALSO SEE
strichg
EXAMPLE
char str[]="Hello, world";
printf("Before: %s\n",str);
strchg(str,'l','z');
printf("After: %s\n",str);
61
------------------------------------------------------------------------
NAME
strchksum
DESCRIPTION
Returns the checksum of a string. The checksum is calculated by
adding up the ASCII values of each character in the string.
SYNOPSIS
#include "cxlstr.h"
unsigned long strchksum(char *str);
INPUTS
str - address of the string
RETURN VALUE
The checksum of the input string.
ALSO SEE
strichksum
EXAMPLE
printf("The checksum of <Hello> is %lu\n",strchksum("Hello"));
------------------------------------------------------------------------
NAME
strcode
DESCRIPTION
Encrypts/decrypts a string. Call this function to encrypt a string,
then call again using the same key to decrypt it. When reading or
writing from a disk file, be sure to open the file in binary mode.
SYNOPSIS
#include "cxlstr.h"
char *strcode(char *str,char *key);
INPUTS
str - the address of the string to encrypt/decrypt
key - the address of the key string to encrypt/decrypt with. The
string can consist of any valid characters (01-FF) and can be
of any length. Remember this key or your data will be lost
forever!
RETURN VALUE
The address of the encrypted/decrypted string.
ALSO SEE
fcrypt
EXAMPLE
char str[]="Hello, world";
62
printf("Before: %s\n",str);
strcode(str,"34&*#Mdq");
printf("Encrypted: %s\n",str);
strcode(str,"34&*#Mdq");
printf("Decrypted: %s\n",str);
------------------------------------------------------------------------
NAME
strdel
DESCRIPTION
Deletes a substring from within a string.
SYNOPSIS
#include "cxlstr.h"
char *strdel(char *substr,char *str);
INPUTS
substr - address of substring to delete
str - address of string to delete substring from
RETURN VALUE
A NULL if the substring was not found, or the address of the
modified string.
ALSO SEE
strdela stridel stridela strinc strins strmid
EXAMPLE
char str[]="Hello there, world";
printf("Before: %s\n",str);
strdel(" there",str);
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
strdela
DESCRIPTION
Deletes all occurrences of a substring from within a string.
SYNOPSIS
#include "cxlstr.h"
char *strdela(char *substr,char *str);
INPUTS
substr - the address of the substring to search for
str - the address of string to search
RETURN VALUE
The address of the modified string, or a NULL if no matches were
found.
63
ALSO SEE
strdel stridel stridela
EXAMPLE
char str[]="xyzHello, xyzworldxyz";
printf("Before: <%s>\n",str);
strdela("xyz",str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strichg
DESCRIPTION
Finds all letters in a string matching one character and replaces
them with another. Ignores case of letters.
SYNOPSIS
#include "cxlstr.h"
int strichg(char *str,int oldch,int newch);
INPUTS
str - address of string to search
oldch - character to search for
newch - character to replace oldch with
RETURN VALUE
The number of matches found.
ALSO SEE
strchg
EXAMPLE
char str[]="HelLo, worLd";
printf("Before: %s\n",str);
strichg(str,'l','l');
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
strichksum
DESCRIPTION
Returns the checksum of a string. The checksum is calculated by
adding up the ASCII values of each character in the string. All
lowercase letters will be counted as uppercase.
SYNOPSIS
#include "cxlstr.h"
unsigned long strichksum(char *str);
INPUTS
64
str - address of the string
RETURN VALUE
The checksum of the input string.
ALSO SEE
strchksum
EXAMPLE
printf("The checksum of <Hello> is %lu\n",strichksum("Hello"));
------------------------------------------------------------------------
NAME
stridel
DESCRIPTION
Deletes a substring from within a string. Ignores case of letters.
SYNOPSIS
#include "cxlstr.h"
char *stridel(char *substr,char *str);
INPUTS
substr - address of substring to delete
str - address of string to delete substring from
RETURN VALUE
A NULL if the substring was not found, or the address of the
modified string.
ALSO SEE
strdel strdela stridela striinc
EXAMPLE
char str[]="Hello tHeRe, world";
printf("Before: %s\n",str);
stridel(" ThErE",str);
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
stridela
DESCRIPTION
Deletes all occurrences of a substring from within a string.
Ignores case of letters.
SYNOPSIS
#include "cxlstr.h"
char *stridela(char *substr,char *str);
INPUTS
65
substr - the address of the substring to search for
str - the address of string to search
RETURN VALUE
The address of the modified string, or a NULL if no matches were
found.
ALSO SEE
strdel strdela stridel
EXAMPLE
char str[]="XyZHello, xYzworldXyZ";
printf("Before: <%s>\n",str);
strdela("xYz",str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
striinc
DESCRIPTION
Determines if and where one string is included within another.
Ignores case of letters.
SYNOPSIS
#include "cxlstr.h"
char *striinc(char *str1,char *str2);
INPUTS
str1 - address of the string to search for
str2 - address of the string to search
RETURN VALUE
The address where string1 is included in string2, or a NULL if
string1 is not included in string2.
ALSO SEE
strinc strmid
EXAMPLE
char str[]="Hello, world";
printf("<ElLo> is %sincluded in <%s>\n"
,striinc("ElLo",str)==NULL?"not ":"",str);
------------------------------------------------------------------------
NAME
strinc
DESCRIPTION
Determines if and where one string is included within another.
SYNOPSIS
66
#include "cxlstr.h"
char *strinc(char *str1,char *str2);
INPUTS
str1 - address of the string to search for
str2 - address of the string to search
RETURN VALUE
The address where string1 is included in string2, or a NULL if
string1 is not included in string2.
ALSO SEE
striinc strmid
EXAMPLE
char str[]="Hello, world";
printf("<ElLo> is %sincluded in <%s>\n"
,strinc("ElLo",str)==NULL?"not ":"",str);
------------------------------------------------------------------------
NAME
strins
DESCRIPTION
Inserts one string into another.
SYNOPSIS
#include "cxlstr.h"
char *strins(char *instr,char *str,int st_pos);
INPUTS
instr - the address of the string to insert
str - the address of the string to insert instr into. This area
must be large enough to hold the size of the modified
string.
st_pos - the starting position of where to insert
RETURN VALUE
The address of the modified string.
ALSO SEE
strdel strinc
EXAMPLE
char str[20]="Hello, world";
printf("Before: %s\n",str);
strins(" there",str,5);
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
striocc
67
DESCRIPTION
Returns the number of occurrences of a character in a string.
Ignores case of letters.
SYNOPSIS
#include "cxlstr.h"
int striocc(char *str,int ch);
INPUTS
str - address of the string to search
ch - the character to look for
RETURN VALUE
The number of occurrences of the character in the string.
ALSO SEE
strocc
EXAMPLE
char str[]="HelLo, world";
printf("There are %d occurrences of '%c' in <%s>\n"
,striocc(str,'l'),'l',str);
------------------------------------------------------------------------
NAME
strischg
DESCRIPTION
Changes all occurrences of one string to another. Ignores case of
letters.
SYNOPSIS
#include "cxlstr.h"
char *strischg(char *str,char *find,char *replace);
INPUTS
str - address of the string to search
find - address of the string to search for
replace - address of the string to replace found strings with
RETURN VALUE
The address of the modified string, or NULL if no matches were
found.
ALSO SEE
strisrep strschg strsrep
EXAMPLE
char str[]="xxxhElLoyyyHElLOzzz";
printf("Before: <%s>\n",str);
strischg(str,"HeLlO","goodbye");
printf("After: <%s>\n",str);
68
------------------------------------------------------------------------
NAME
strisocc
DESCRIPTION
Counts occurrences of one string within another. Ignores case of
letters.
SYNOPSIS
#include "cxlstr.h"
int strisocc(char *str1,char *str2);
INPUTS
str1 - address of string to search for
str2 - address of string to search
RETURN VALUE
The number of times that string str1 occurs in string str2.
ALSO SEE
strsocc
EXAMPLE
char str1[]="hello";
char str2[]="Hello1HELLO2HeLlO3hElLo";
printf("<%s> occurs in <%s> %d times\n",str1,str2
,strisocc(str1,str2));
------------------------------------------------------------------------
NAME
strisrep
DESCRIPTION
Searches for, and replaces one string within another. Ignores case
of letters.
SYNOPSIS
#include "cxlstr.h"
char *strisrep(char *str,char *search,char *replace);
INPUTS
str - address of string to search. This must have enough space
to hold the modified string.
search - address of string to search for
replace - address of string to replace search string with
RETURN VALUE
The address of the modified string, or NULL if the search string
wasn't found.
ALSO SEE
strischg strschg strsrep
69
EXAMPLE
char str[24]="This is a big string";
printf("Before: %s\n",str);
strisrep(str,"StR","th");
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
strleft
DESCRIPTION
Takes a specified portion of a string from its left and creates a
new string.
SYNOPSIS
#include "cxlstr.h"
char *strleft(char *str,int num_chars);
INPUTS
str - address of input string
num_chars - number of characters to copy
RETURN VALUE
Address of the newly created string or a NULL if a memory allocation
error occurred. Be sure to free() this string if or when you don't
need it anymore.
ALSO SEE
strmid strright strtrim
EXAMPLE
char *p,str[]="Hello, world";
printf("%s\n",p=strleft(str,5));
free(p);
------------------------------------------------------------------------
NAME
strljust
DESCRIPTION
Left justifies a text string.
SYNOPSIS
#include "cxlstr.h"
char *strljust(char *str);
INPUTS
str - address of the string to left justify
RETURN VALUE
Address of the modified string.
70
ALSO SEE
strrjust
EXAMPLE
char str[]=" Hello, world";
printf("Before: <%s>\n",str);
strljust(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strltrim
DESCRIPTION
Trims the leading spaces off of a string.
SYNOPSIS
#include "cxlstr.h"
char *strltrim(char *str);
INPUTS
str - address of the string to trim
RETURN VALUE
Address of the modified string.
ALSO SEE
strbtrim strright strsetsz strtrim
EXAMPLE
char str[]=" Hello, world";
printf("Before: <%s>\n",str);
strltrim(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strmatch
DESCRIPTION
Compares 2 strings and returns a match score.
SYNOPSIS
#include "cxlstr.h"
int strmatch(char *str1,char *str2);
INPUTS
str1 - address of first string
str2 - address of second string
RETURN VALUE
A match score. The higher the score, the better they match.
71
ALSO SEE
strbmatch
------------------------------------------------------------------------
NAME
strmid
DESCRIPTION
Takes a section from input string starting at given position and
taking the given amount of characters creating a new string.
SYNOPSIS
#include "cxlstr.h"
char *strmid(char *str,int st_pos,int num_chars);
INPUTS
str - address of input string
st_pos - position in input string to start copying characters
(starting at position 0)
num_chars - number of characters to copy
RETURN VALUE
Address of the newly created string or a NULL if a memory allocation
error occurred. Be sure to free() the string when or if you are
finished with it.
ALSO SEE
strleft strright
EXAMPLE
char *p,str[]="Hello there, world";
printf("%s\n",p=strmid(str,6,5));
free(p);
------------------------------------------------------------------------
NAME
strocc
DESCRIPTION
Returns the number of occurrences of a given character in a string.
SYNOPSIS
#include "cxlstr.h"
int strocc(char *str,int ch);
INPUTS
str - address of the string to search
ch - the character to look for
RETURN VALUE
The number of occurrences of the given character in the string.
72
ALSO SEE
striocc
EXAMPLE
char str[]="Hello, world";
printf("There are %d occurrences of '%c' in <%s>\n"
,strocc(str,'l'),'l',str);
------------------------------------------------------------------------
NAME
strright
DESCRIPTION
Takes a specifed portion from the right side of a string creating a
new string.
SYNOPSIS
#include <string.h>
#include "cxlstr.h"
char *strright(char *str,int num_chars);
INPUTS
str - address of input string
num_chars - number of characters to copy
RETURN VALUE
Address of the newly created string or a NULL if a memory allocation
error occurred. Be sure to free() the string when or if you are
finished with it.
ALSO SEE
strleft strltrim strmid
EXAMPLE
char *p,str[]="Hello, world";
printf("%s\n",p=strright(str,5));
free(p);
------------------------------------------------------------------------
NAME
strrjust
DESCRIPTION
Right justifies a text string.
SYNOPSIS
#include "cxlstr.h"
char *strrjust(char *str);
INPUTS
str - address of string to right justify
73
RETURN VALUE
Address of modified string.
ALSO SEE
strljust
EXAMPLE
char str[]="Hello, world ";
printf("Before: <%s>\n",str);
strrjust(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strrol
DESCRIPTION
Rotates a string specified number of characters left. The rotated
characters wrap around to the right side of the string.
SYNOPSIS
#include "cxlstr.h"
char *strrol(char *str,int count);
INPUTS
str - the address of the string to rotate
count - number of characters to rotate
RETURN VALUE
The address of the modified string.
ALSO SEE
strror strshl
EXAMPLE
char str[]="Hello, world";
printf("Before: <%s>\n",str);
strrol(str,3);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strror
DESCRIPTION
Rotates a string specified number of characters right. The rotated
characters wrap around to the left side of the string.
SYNOPSIS
#include "cxlstr.h"
char *strror(char *str,int count);
74
INPUTS
str - the address of the string to rotate
count - number of characters to rotate
RETURN VALUE
The address of the modified string.
ALSO SEE
strrol strshr
EXAMPLE
char str[]="Hello, world";
printf("Before: <%s>\n",str);
strror(str,3);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strschg
DESCRIPTION
Changes all occurrences of one string to another.
SYNOPSIS
#include "cxlstr.h"
char *strschg(char *str,char *find,char *replace);
INPUTS
str - address of the string to search
find - address of the string to search for
replace - address of the string to replace found strings with
RETURN VALUE
The address of the modified string, or NULL if no matches were
found.
ALSO SEE
strischg strisrep strsrep
EXAMPLE
char str[]="xxxhelloyyyhellozzz";
printf("Before: <%s>\n",str);
strschg(str,"hello","goodbye");
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strsetsz
DESCRIPTION
Adjusts the length of a string, either by truncation or padding with
spaces.
75
SYNOPSIS
#include "cxlstr.h"
char *strsetsz(char *str,int newsize);
INPUTS
str - address of the string to modify. This area must be large
enough to hold the string at its newsize length.
newsize - the new length of the string
RETURN VALUE
The address of the modified string.
ALSO SEE
strtrim
EXAMPLE
char str[22]="Hello, world";
printf("Before: <%s>\n",str);
strsetsz(str,20);
printf("Len=20: <%s>\n",str);
strsetsz(str,5);
printf("Len=5: <%s>\n",str);
------------------------------------------------------------------------
NAME
strshl
DESCRIPTION
Shifts a string a specified number of characters left. Characters
that shift past the beginning of the string "drop off" and spaces
are added to the right of the string.
SYNOPSIS
#include "cxlstr.h"
char *strshl(char *str,int count);
INPUTS
str - the address of the string to shift
count - number of characters to shift
RETURN VALUE
The address of the modifed string.
ALSO SEE
strrol strshr
EXAMPLE
char str[]="Hello, world";
printf("Before: <%s>\n",str);
strshl(str,3);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
76
NAME
strshr
DESCRIPTION
Shifts a string a specified number of characters right. Characters
that shift past the end of the string "drop off" and spaces are
added to the left of the string.
SYNOPSIS
#include "cxlstr.h"
char *strshr(char *str,int count);
INPUTS
str - the address of the string to shift
count - number of characters to shift
RETURN VALUE
The address of the modified string.
ALSO SEE
strror strshl
EXAMPLE
char str[]="Hello, world";
printf("Before: <%s>\n",str);
strshr(str,3);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
strsocc
DESCRIPTION
Counts the occurrences of one string within another.
SYNOPSIS
#include "cxlstr.h"
int strsocc(char *str1,char *str2);
INPUTS
str1 - address of string to search for
str2 - address of string to search
RETURN VALUE
The number of times that string str1 occurs in string str2.
ALSO SEE
strisocc
EXAMPLE
char str1[]="hello";
char str2[]="Hello1hello2HeLlO3hElLo";
printf("<%s> occurs in <%s> %d times\n",str1,str2
77
,strsocc(str1,str2));
------------------------------------------------------------------------
NAME
strsrep
DESCRIPTION
Searches for, and replaces one string within another.
SYNOPSIS
#include "cxlstr.h"
char *strsrep(char *str,char *search,char *replace);
INPUTS
str - address of string to search
search - address of string to search for
replace - address of string to replace search string with
RETURN VALUE
The address of the modified string, or NULL if the search string
wasn't found.
ALSO SEE
strischg strisrep strschg
EXAMPLE
char str[24]="This is a big string";
printf("Before: %s\n",str);
strsrep(str,"str","th");
printf("After: %s\n",str);
------------------------------------------------------------------------
NAME
strtrim
DESCRIPTION
Trims trailing spaces off of a string.
SYNOPSIS
#include "cxlstr.h"
char *strtrim(char *str);
INPUTS
str - address of the string to trim
RETURN VALUE
Address of the modified string.
ALSO SEE
strbtrim strleft strltrim strsetsz
EXAMPLE
78
char str[]="Hello, world ";
printf("Before: <%s>\n",str);
strtrim(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
struplow
DESCRIPTION
Converts a string to mixed upper & lowercase characters.
Characters are forced to upper or lowercase depending upon the
previous character in the string.
SYNOPSIS
#include "cxlstr.h"
char *struplow(char *str);
INPUTS
str - the address of the string to convert
RETURN VALUE
The address of the modified string.
ALSO SEE
touplow
EXAMPLE
char str[]="hElLo, wOrLd";
printf("Before: <%s>\n",str);
struplow(str);
printf("After: <%s>\n",str);
------------------------------------------------------------------------
NAME
sysdate
DESCRIPTION
Returns a string containing the current system date.
SYNOPSIS
#include "cxldef.h"
char *sysdate(int dtype);
INPUTS
dtype - date type code. Can be one of the following:
Code Example
---- -------
0 December 3, 1988
1 3 Dec 88
2 12-3-88
3 12/3/88
79
4 3/12/88
5 12/03/88
RETURN VALUE
The address of the static string containing the system date.
ALSO SEE
systime
EXAMPLE
printf("Today's date is %s\n",sysdate(0));
------------------------------------------------------------------------
NAME
systime
DESCRIPTION
Returns a string containing the current system time.
SYNOPSIS
#include "cxldef.h"
char *systime(int ttype);
INPUTS
ttype - time type code. Can be one of the following:
Code Example
---- -------
0 16:30:57.89
1 16:30:57
2 4:30 PM
3 4:30p
4 4:30
5 04:30
RETURN VALUE
The address of the static string containing the current system time.
ALSO SEE
sysdate
EXAMPLE
printf("The current time is %s\n",systime(2));
------------------------------------------------------------------------
NAME
tabstop
DESCRIPTION
Calculates a tab stop from given column and tab width.
SYNOPSIS
#include "cxldef.h"
80
int tabstop(int col,int tabwidth);
INPUTS
col - column
tabwidth - tab width
RETURN VALUE
The next tab stop column.
EXAMPLE
printf("The next tab stop after column 9 is column %d\n"
,tabstop(9,8));
------------------------------------------------------------------------
NAME
timer
DESCRIPTION
Returns the value of the BIOS timer. This value is incremented by
one every 18.2 seconds.
SYNOPSIS
#include "cxldef.h"
unsigned long timer(void);
RETURN VALUE
Current value of the BIOS timer.
ALSO SEE
delay_
EXAMPLE
printf("Time #1: %lu\n",timer());
delay_(36);
printf("Time #2: %lu\n",timer());
------------------------------------------------------------------------
NAME
touplow
DESCRIPTION
Converts a character to upper or lowercase depending on previous
character. This function is used internally by other CXL functions.
SYNOPSIS
#include "cxlstr.h"
int touplow(char *str,char *pos,int ch);
INPUTS
str - address of string
pos - address of current position in string
ch - character to convert
81
RETURN VALUE
The converted character.
ALSO SEE
struplow
EXAMPLE
char ch='w',str[20]="Hello, ";
printf("The character '%c' will be appended to <%s> as '%c'\n"
,ch,str,touplow(str,str+7,ch));
------------------------------------------------------------------------
NAME
videoinit
DESCRIPTION
Initializes CXL's video system. By default, all CXL functions
performing direct screen writes go to the CGA screen memory at
address B800:0000. If you want these functions to work correctly
with a monochrome video adapter or within a DESQview window, you
must call this function. This function sets the values in the global
structure variable _vinfo.
SYNOPSIS
#include "cxlvid.h"
int videoinit(void);
RETURN VALUE
Video adapter type. See the vidtype() description for all the
possible return values.
ALSO SEE
setvparam vidtype
------------------------------------------------------------------------
NAME
vidmode
DESCRIPTION
Returns the current video mode.
SYNOPSIS
#include "cxlvid.h"
int vidmode(void);
RETURN VALUE
The current video mode.
ALSO SEE
mode
------------------------------------------------------------------------
82
NAME
vidtype
DESCRIPTION
Determines the display adapter type.
SYNOPSIS
#include "cxlvid.h"
int vidtype(void);
RETURN VALUE
Video adapter type. Will be one of the following values:
V_NONE - no video adapter
V_MDA - Monochrome Display Adapter
V_EGAMONO - Enhanced Graphics Adapter in mono mode
V_MCGAMONO - Multi-Color Graphics Array adapter in mono mode
V_VGAMONO - Video Graphics Array adapter in mono mode
V_HGC - Hercules Graphics Card
V_HGCPLUS - Hercules Graphics Card Plus
V_INCOLOR - Hercules InColor Card
V_CGA - Color Graphics Adapter
V_EGA - Enhanced Graphics Adapter
V_MCGA - Multi-Color Graphics Array adapter
V_VGA - Video Graphics Array adapter
ALSO SEE
mode setvparam videoinit
------------------------------------------------------------------------
NAME
wactiv
DESCRIPTION
Activates a previously opened window, bringing it "in front" of all
the others. Many windowing functions can perform their operations
only on the active window. If a window is not active, you will need
to activate it before you can use it for these functions.
SYNOPSIS
#include "cxlwin.h"
int wactiv(WINDOW whandle);
INPUTS
whandle - the window handle of the window to activate
RETURN VALUE
W_NOERROR - no error
W_NOTFOUND - window handle not found
W_NOACTIVE - no open windows
ALSO SEE
wisactiv wopen
83
EXAMPLE
int w1,w2;
w1=wopen(10,10,20,40,0,LCYAN|_BLUE,LCYAN|_BLUE);
w2=wopen(0,0,15,35,1,LMAGENTA|_RED,LMAGENTA|_RED);
wactiv(w1);
------------------------------------------------------------------------
NAME
waitkey
DESCRIPTION
Clears the keyboard buffer and halts program execution until a key
is pressed.
SYNOPSIS
#include "cxlkey.h"
int waitkey(void);
RETURN VALUE
The ASCII value of the key pressed.
ALSO SEE
clearkeys getchf waitkeyt
EXAMPLE
printf("Press any key to continue....");
waitkey();
------------------------------------------------------------------------
NAME
waitkeyt
DESCRIPTION
Clears the keyboard buffer and halts program execution until a key
is pressed or the specified time limit expires.
SYNOPSIS
#include "cxlkey.h"
int waitkeyt(int duration);
INPUTS
duration - length of time to wait for keypress (ie. 182 = 10 secs.)
RETURN VALUE
The ASCII value of the key pressed or a -1 if the time limit
expired.
ALSO SEE
clearkeys delay_ getchf waitkey
EXAMPLE
printf("Press any key to continue....");
84
waitkeyt(91); /* time out after 5 seconds */
------------------------------------------------------------------------
NAME
wborder
DESCRIPTION
Changes the active window's border box type. If changing to or from
a borderless window, the window's effective area will change as
well, changing relative coordinates within the window.
SYNOPSIS
#include "cxlwin.h"
int wborder(int btype);
INPUTS
btype - box type. Can be one of the following:
0 - single line border
1 - double line border
2 - single horz, double vert line border
3 - double horz, single vert line border
4 - thick line border
5 - no border (uses spaces for border chars)
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVBTYPE - invalid box type
------------------------------------------------------------------------
NAME
wbox
DESCRIPTION
"Draws" a text box in the active window.
SYNOPSIS
#include "cxlwin.h"
int wbox(int wsrow,int wscol,int werow,int wecol,int btype,
int attr);
INPUTS
wsrow - window start row of box
wscol - window start column of box
werow - window end row of box
wecol - window end column of box
btype - box type. Can be one of the following:
0 - single line border
1 - double line border
2 - single horz, double vert line border
3 - double horz, single vert line border
4 - thick line border
85
5 - no border (uses spaces for border chars)
attr - text attribute to use for box characters
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wfill whline wvline
------------------------------------------------------------------------
NAME
wbprintc
DESCRIPTION
Displays a character on a window's border.
SYNOPSIS
#include "cxlwin.h"
int wbprintc(int bord,int offs,int attr,int ch);
INPUTS
bord - border code. Can be one of the following:
TP_BORD - top border
BT_BORD - bottom border
LT_BORD - left border
RT_BORD - right border
offs - offset from window border to display character at
attr - text attribute for displayed character
ch - the character to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_NOBORDER - window has no border
W_INVCOORD - border offset out of range
ALSO SEE
wmessage wprintc
EXAMPLE
wbprintc(RT_BORD,1,WHITE|_BLACK,'*');
------------------------------------------------------------------------
NAME
wcclear
DESCRIPTION
Clears the active window using specified text attribute, then homes
the cursor.
86
SYNOPSIS
#include "cxlwin.h"
int wcclear(int attr);
INPUTS
attr - text attribute to clear window with
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wclear wclreol wclreos wfillch
EXAMPLE
wcclear(BLACK|_BLACK);
------------------------------------------------------------------------
NAME
wcenters
DESCRIPTION
Displays a string centered in active window. Does not recognize
control characters. Does not update cursor position.
SYNOPSIS
#include "cxlwin.h"
int wcenters(int wrow,int attr,char *str);
INPUTS
wrow - window row to center string at
attr - text attribute to use for displayed characters
str - address of string to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
W_STRLONG - string too long to be centered in window
ALSO SEE
wprints wrjusts
EXAMPLE
wcenters(2,YELLOW|_LGREY,"Main Menu");
------------------------------------------------------------------------
NAME
wchgattr
DESCRIPTION
Changes the text attribute of the active window. All text within
87
the window will be changed also.
SYNOPSIS
#include "cxlwin.h"
int wchgattr(int battr,int wattr);
INPUTS
battr - the attribute to make the window's border
wattr - the attribute to make the window
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wtextattr
EXAMPLE
wchgattr(LMAGENTA|_RED,LCYAN|_BLUE);
------------------------------------------------------------------------
NAME
wchkbox
DESCRIPTION
Determines whether input window box coordinates are valid for use in
the active window.
SYNOPSIS
#include "cxlwin.h"
int wchkbox(int wsrow,int wscol,int werow,int wecol);
INPUTS
wsrow - window start row
wscol - window start column
werow - window end row
wecol - window end column
RETURN VALUE
Nonzero if input window box coordinates are invalid.
ALSO SEE
wchkcol wchkcoord wchkrow
------------------------------------------------------------------------
NAME
wchkcol
DESCRIPTION
Determines whether input window column coordinate is valid for use
in the active window.
88
SYNOPSIS
#include "cxlwin.h"
int wchkcol(int wcol);
INPUTS
wcol - window column
RETURN VALUE
Nonzero if input window column coordinate is invalid.
ALSO SEE
wchkbox wchkcoord wchkrow
------------------------------------------------------------------------
NAME
wchkcoord
DESCRIPTION
Determines whether input window row,column coordinates are valid for
use in the active window.
SYNOPSIS
#include "cxlwin.h"
int wchkcoord(int wrow,int wcol);
INPUTS
wrow - window row
wcol - window column
RETURN VALUE
Nonzero if input window coordinates are invalid.
ALSO SEE
wchkbox wchkcol wchkrow
------------------------------------------------------------------------
NAME
wchkrow
DESCRIPTION
Determines whether input window row is valid for use in the active
window.
SYNOPSIS
#include "cxlwin.h"
int wchkrow(int wrow);
INPUTS
wrow - window row
RETURN VALUE
Nonzero if input window row is invalid.
89
ALSO SEE
wchkbox wchkcol wchkcoord
------------------------------------------------------------------------
NAME
wclear
DESCRIPTION
Clears the active window, then homes the cursor.
SYNOPSIS
#include "cxlwin.h"
int wclear(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wcclear wclreol wclreos wfillch
------------------------------------------------------------------------
NAME
wclose
DESCRIPTION
Closes the active window. If the window has a shadow, it will be
closed as well.
SYNOPSIS
#include "cxlwin.h"
int wclose(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wcloseall wopen wunlink
------------------------------------------------------------------------
NAME
wcloseall
DESCRIPTION
Closes all open windows.
SYNOPSIS
#include "cxlwin.h"
int wcloseall(void);
90
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wclose wopen
------------------------------------------------------------------------
NAME
wclreol
DESCRIPTION
Clears from the cursor to the end of the active window's line. The
cursor's position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wclreol(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wclear wclreos wfillch
------------------------------------------------------------------------
NAME
wclreos
DESCRIPTION
Clears from the cursor to the end of the active window. The
cursor's position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wclreos(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wclear wclreol wfillch
------------------------------------------------------------------------
NAME
wcopy
DESCRIPTION
Creates a new window duplicating the active window. The new window
91
becomes the active window.
SYNOPSIS
#include "cxlwin.h"
WINDOW wcopy(int nsrow,int nscol);
INPUTS
nsrow - start row of where to place the duplicate window
nscol - start column of where to place the duplicate window
RETURN VALUE
The window handle of the new window. If an error occurred, a zero
will be returned and the global variable _winfo.errno will be set to
one of the following values:
W_ALLOCERR - memory allocation error
W_INVCOORD - invalid coordinates
ALSO SEE
wactiv wmove wopen
EXAMPLE
wopen(10,10,20,40,0,LCYAN|_BLUE,LCYAN|_BLUE);
wcopy(0,0);
------------------------------------------------------------------------
NAME
wdelline
DESCRIPTION
Deletes a line from the active window. Depending upon the input
scroll direction, the lines above or below the line to delete will
scroll to fill in the deleted line in, and a blank line will be
added. If what you really want to do is clear the line, you may
want to use wclreol() instead.
SYNOPSIS
#include "cxlwin.h"
int wdelline(int wrow,int direc);
INPUTS
wrow - window row to delete
direc - scroll direction. Can be one of the following:
D_UP - scroll up
D_DOWN - scroll down
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
ALSO SEE
wclreol winsline wscroll
92
EXAMPLE
wdelline(3,D_UP);
------------------------------------------------------------------------
NAME
wdrag
DESCRIPTION
Smoothly drag active window one row/column in given direction.
SYNOPSIS
#include "cxlwin.h"
int wdrag(int direction);
INPUTS
direction - direction to drag window. Can be one of these values:
D_UP - up
D_DOWN - down
D_LEFT - left
D_RIGHT - right
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ALLOCERR - memory allocation error
ALSO SEE
wmove wslide
------------------------------------------------------------------------
NAME
wdump
DESCRIPTION
Dumps the active window to the default printer (PRN).
SYNOPSIS
#include "cxlwin.h"
int wdump(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
windump
------------------------------------------------------------------------
NAME
wdupc
93
DESCRIPTION
Displays a character a specified number of times in the active
window. Characters will be displayed in the window's current text
attribute. Control characters are recognized. Cursor position is
updated.
SYNOPSIS
#include "cxlwin.h"
int wdupc(int ch,int count);
INPUTS
ch - character to be displayed
count - number of times to display character
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wdups wputc wtextattr
EXAMPLE
wdupc('X',5);
------------------------------------------------------------------------
NAME
wdups
DESCRIPTION
Displays a string a specified number of times in the active window.
Characters will be displayed in the window's current text attribute.
Control characters are recognized. Cursor position is updated.
SYNOPSIS
#include "cxlwin.h"
int wdups(char *str,int count);
INPUTS
str - character to be displayed
count - number of times to display character
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wdupc wputs wtextattr
EXAMPLE
wdups("Hello ",3);
------------------------------------------------------------------------
94
NAME
werrmsg
DESCRIPTION
Most of CXL's windowing functions set the global variable
_winfo.errno before returning to their caller. This function,
werrmsg(), reads _winfo.errno and returns the literal error message
that corresponds to it. This can be very useful in debugging
programs that use CXL's windowing functions. Check the individual
windowing function descriptions to find out which ones actually set
_winfo.errno.
SYNOPSIS
#include "cxlwin.h"
char *werrmsg(void);
RETURN VALUE
The address of the static string containing the error message that
corresponds to the window error code in _winfo.errno.
ALSO SEE
wperror
EXAMPLE
wgotoxy(255,255); /* invalid coordinates */
printf("Error = %s\n",werrmsg());
------------------------------------------------------------------------
NAME
wfill
DESCRIPTION
Fills in a region of active window with a specified character and
attribute.
SYNOPSIS
#include "cxlwin.h"
int wfill(int wsrow,int wscol,int werow,int wecol,int ch,int attr);
INPUTS
wsrow - window start row
wscol - window start column
werow - window end row
wecol - window end column
ch - character to fill with
attr - text attribute to use for fill
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
95
wbox
EXAMPLE
wfill(2,3,5,15,'Z',WHITE|_GREEN);
------------------------------------------------------------------------
NAME
wfillch
DESCRIPTION
Specifies which character the windowing system will use for filling
windows with. By default, it is a space (' ').
SYNOPSIS
#include "cxlwin.h"
void wfillch(int ch);
INPUTS
ch - character to fill with
EXAMPLE
wfillch('\260');
------------------------------------------------------------------------
NAME
wfindrec
DESCRIPTION
Finds the address of a window record using the specified window
handle. This is used internally be several CXL functions.
SYNOPSIS
#include "cxlwin.h"
struct _wrec_t *wfindrec(WINDOW whandle);
INPUTS
whandle - window handle of window record to find
RETURN VALUE
The address of the found window record, or NULL if no record was
found for the given handle.
------------------------------------------------------------------------
NAME
wgetc
DESCRIPTION
Gets a character from the keyboard. Entered character will be
echoed to the active window using the window's current text
attribute. Cursor position is updated.
96
SYNOPSIS
#include "cxlwin.h"
int wgetc(void);
RETURN VALUE
The ASCII value of the key pressed or a zero if an error occurred.
If error, the global variable _winfo.errno will be set to one of the
following:
W_NOACTIVE - no active window
ALSO SEE
wgetchf wscanf wtextattr
------------------------------------------------------------------------
NAME
wgetchf
DESCRIPTION
Gets a character from the keyboard. Allows input only of characters
listed in the string of valid characters. Entered characters will
be echoed to the active window using the text attribute set by the
wtextattr() function. Cursor position is updated. Escape checking
is provided by default. This can be turned off with the wsetesc()
function.
SYNOPSIS
#include "cxlwin.h"
int wgetchf(char *valid,int defchar);
INPUTS
valid - address of the string containing the valid characters
defchar - default selection in case [Enter] is pressed, or a zero
for none
RETURN VALUE
The ASCII value of the key pressed, or a zero if an error occurred.
Thre returned character will be uppercase. If error, the global
variable _winfo.errno will be set to one of the following:
W_NOACTIVE - no active window
W_ESCPRESS - [Esc] key was pressed
ALSO SEE
wgetc wgetyn wscanf wtextattr
EXAMPLE
int ch;
wputs("Quit, are you sure? ");
if((ch=wgetchf("YN",'N'))==0) wprintf("Error: %s\n",werrmsg());
------------------------------------------------------------------------
NAME
wgetns
97
DESCRIPTION
Gets a string from the keyboard, limiting the number of characters
input to the specified length. Entered characters will be echoed to
the active window using the text attribute set by the wtextattr()
function. Cursor position is updated. Escape checking is provided
by default. This can be turned off with the wsetesc() function.
SYNOPSIS
#include "cxlwin.h"
int wgetns(char *str,int maxlen);
INPUTS
str - address of the buffer to receive the input string
maxlen - the maximum length of the input string
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - [Esc] key was pressed
ALSO SEE
wgets winputsf wscanf wsetesc wtextattr
EXAMPLE
char buf[6];
wputs("Enter 5 characters: ");
if(wgetns(buf,5)) wprintf("Error: %s\n",werrmsg());
------------------------------------------------------------------------
NAME
wgets
DESCRIPTION
Gets a string from the keyboard. Entered characters will be echoed
to the active window in the text attribute set by the wtextattr()
function. Cursor position is updated.
SYNOPSIS
#include "cxlwin.h"
int wgets(char *str);
INPUTS
str - the address of the buffer to receive the input string
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wgetns winputsf wscanf wtextattr
EXAMPLE
char name[30];
98
wputs("Enter your name: ");
wgets(name);
------------------------------------------------------------------------
NAME
wgetyn
DESCRIPTION
Gets a [Y]es or [N]o response from the keyboard. When the user
chooses [Y]es or [N]o, the text "Yes" or "No" will be displayed at
the cursor location. Escape checking is provided by default. This
can be turned off with the wsetesc() function.
SYNOPSIS
#include "cxlwin.h"
int wgetyn(int cdefault);
INPUTS
cdefault - the response that will be automatically selected when the
[Enter] key is pressed. Zero = No, Nonzero = Yes.
RETURN VALUE
A 'Y' if Yes was selected, an 'N' if No was selected, or a '\0' if
the user pressed [Esc] and Escape checking was on.
ALSO SEE
wgetchf wsetesc
EXAMPLE
int choice;
wputs("Delete, are you sure? [Y,n]: ");
choice=wgetyn(1);
if(choice)
wprintf("\nYou selected: %c\n",choice);
else
wprintf("\n[Esc] was pressed\n");
------------------------------------------------------------------------
NAME
wgotoxy
DESCRIPTION
Sets cursor coordinates within the active window.
SYNOPSIS
#include "cxlwin.h"
int wgotoxy(int wrow,int wcol);
INPUTS
wrow - window row (Y coordinate)
wcol - window column (X coordinate)
99
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wpgotoxy wreadcur
------------------------------------------------------------------------
NAME
whandle
DESCRIPTION
Returns the window handle of the active window.
SYNOPSIS
#include "cxlwin.h"
WINDOW whandle(void);
RETURN VALUE
The handle of the active window or zero if error. If error, the
global variable _winfo.errno will be set to one of the following:
W_NOACTIVE - no active window
ALSO SEE
wactiv wisactiv
------------------------------------------------------------------------
Context-Sensitive Help Functions
CXL's context-sensitive help system operates on the principle of a
current help category and a help category stack. Both require some
explaining before you begin to use them.
The current help category is the one that will be used when the user
presses the help key. It can be set by one of several ways. The direct
way is for you to explicitly set it by calling whelpcat(). There are
also indirect ways that the current help category can be set. Windows,
input fields, and menu items each have individual help categories as
part of their record. If you were to activate a window which has its
own help category, then that would become the current help category.
During the processing of input fields and menus, each time you move to a
new field or menu item item, the current help category is set to the
whatever the field/item's help category is, even if that category is
zero (empty). This means that input forms and menus overwrite what was
in the current help category before the form/menu began processing.
To keep from losing the current help category during the processing of
forms and menus, you need to be able to save the current help category
during that period. This is where the help stack comes into the
picture. To save the current help category, you push it onto the stack
with whelpush(). When you need to retrieve it, you pop it back off of
100
the stack using whelpop(). The category popped off of the stack then
becomes the current help category. This help stack is a LIFO (Last In
First Out) stack and holds up to 20 help categories.
When the help key is pressed by the user, CXL's help processor will
search the help file for the current help category. If the current help
category is zero (empty), then the help category off top of the stack
will be used. This is where the help stack comes in handy. It allows
you to have a "background" help category for menu items and fields that
don't have help categories of their own. Before processing of the form
or menu, you simply push the background help category onto the stack.
When the help category is found in the help file, the corresponding help
text will be displayed on the screen in the help window. If there is
more than 1 page of text, the user can change between pages via the
[PgUp]/[PgDn] keys. If there are cross-reference items, the user can
use the arrow keys to move between them, and use [Enter] to select.
Pressing [Esc] will exit the help window.
During help processing, all keys attached to functions via setonkey()
will be disabled to avoid conflict with the help system. If you wish to
have defined keys available during help processing, you can define them
using setonkey() in the "open" function specified in the whelpdef()
function. If you define any keys in the "open" function, you will not
need to worry about freeing them as the help processor will free any
user-defined keys before exiting help.
The size and placement of the help window are adjustable. The help
window size by default is 19 rows by 64 columns centered on the screen.
This can be changed using whelpwin(). The whelpwin() function sets the
screen coordinates to be used when opening the help window and can be
called any time after whelpdef(). If you ever want to disengage the
help system, just call whelpundef().
Creating help files is quite easy. You need to have an ASCII editor to
create them with. Your help file can contain several help categories.
Here is an example of a couple of defined help categories:
*B 1,Help Category 1
help text help text help text
help text help text help text
help text help text help text
*P
help text help text help text
help text help text help text
help text help text help text
*E
*B 2,Help Category 2
help text help text help text
help text help text help text
help text help text help text
*P
help text help text help text
101
help text help text help text
help text help text help text
Also see: ^Help Category 1^
*E
The "*B" indicator specifies the beginning of a help category. The
format is "*B helpcatnumber[,helpcatname]". The help category number is
the number of the help category that you set using whelpcat(). There
should be only one space between the "*B" and the help category number.
The help category name is only required for cross-references. If there
are no cross-references to that help category, then you can leave the
helpcatname parameter out.
The "*P" indicator specifies a page break and is optional. You may have
as many page breaks as you'd like. The "*E" indicator specifies the end
of the help category. The "*B", "*P", and "*E" indicators must all
begin in the first column. These indicators and the help category name
are case insensitive (can be in lowercase, uppercase, or mixed).
CXL represents help categories as integers. When assigning help
category numbers in the help file, you should start at 1 and go up from
there. Help category 0 is reserved to represent an empty help category.
In the definition of Help Category 2, you will notice the cross-
reference to Help Category 1. All cross-referencing is done by
embedding the cross-reference category name (not number) inside carats
(^). If you need to display a carat inside the help file, use a double
carat (^^).
Any text contained outside of the "*B" and "*E" will be treated as
comments. If an "*E" is not found, then the end-of-file will be treated
as an "*E".
Now, you need to "compile" your ASCII help file into an indexed file.
There is utility, MAKEINDX.COM, which takes your ASCII help file as
input, and outputs an indexed version of of the same file. This new
file is the actual help file that you specify in the whelpdef()
function. Keep the ASCII help file around so you will be able to make
modifications.
------------------------------------------------------------------------
NAME
whelpcat
DESCRIPTION
Sets the current help category. If a window is active at the time,
it will also set that window's help category. The help category set
by calling this function is what will be used by the help processor
for searching the help file for help text.
SYNOPSIS
#include "cxlwin.h"
int whelpcat(int cat);
102
INPUTS
cat - help category number.
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no help record defined
ALSO SEE
whelpclr whelpdef whelpop whelppcat whelpush
------------------------------------------------------------------------
NAME
whelpclr
DESCRIPTION
Clears the help category stack.
SYNOPSIS
#include "cxlwin.h"
int whelpclr(void);
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no help defined
ALSO SEE
whelpdef whelpcat whelpop whelpush
------------------------------------------------------------------------
NAME
whelpdef
DESCRIPTION
Defines the help file, key, and window colors. After calling this
function, anytime the help key is pressed, the help processor will
search the help file for whatever the current help category is.
SYNOPSIS
#include "cxlwin.h"
int whelpdef(char *file,unsigned key,int winattr,int textattr,
int selattr,int barattr,void (*open)(void));
INPUTS
file - address of string containing help file name.
key - keycode of key to be used for help key. See Appendix B
for a list of keycodes that you can use.
winattr - attribute of the help window.
textattr - attribute of the text in the help window.
selattr - attribute of the cross-reference selection text.
barattr - attribute of the cross-reference selection bar.
open - address of the function to call immediately upon opening
of the help window. This can be used to call a function
103
that could add a window shadow, etc. If you do not need
to use this feature, specify NULL.
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOHLPDEF - you specified NULL for the help file name
ALSO SEE
whelpcat whelpundef whelpwin
EXAMPLE
whelpdef("CXLDEMO.HLP",0x3b00,LCYAN|_BLUE,GREEN|_BLUE,LGREEN|_BLUE
,BLUE|_LGREY,NULL);
------------------------------------------------------------------------
NAME
whelpop
DESCRIPTION
Pops the help category off of the top of the stack and makes it the
current help category.
SYNOPSIS
#include "cxlwin.h"
int whelpop(void);
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no defined help, see whelpdef().
W_HLPSTKUN - help stack underflow (stack empty).
ALSO SEE
whelpcat whelpclr whelpdef whelpopc whelpush whelpushc
------------------------------------------------------------------------
NAME
whelpopc
DESCRIPTION
Pops the help category off of the top of the stack and into the
void. The current help category is not affected.
SYNOPSIS
#include "cxlwin.h"
int whelpopc(void);
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no defined help, see whelpdef().
W_HLPSTKUN - help stack underflow (stack empty).
104
ALSO SEE
whelpcat whelpclr whelpdef whelpop whelpush whelpushc
------------------------------------------------------------------------
NAME
whelppcat
DESCRIPTION
Pushes the current help category onto the help category stack, then
sets the current help category to the specified help category. It's
effectively the same as doing a whelpush() followed by a whelpcat().
SYNOPSIS
#include "cxlwin.h"
int whelppcat(int cat);
INPUTS
cat - help category number of the help category you want to make
the current help category.
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no help record defined
W_HLPSTKOV - help stack overflow (stack full)
ALSO SEE
whelpcat whelpush whelpushc
------------------------------------------------------------------------
NAME
whelpush
DESCRIPTION
Pushes the current help category onto the help category stack. The
stack can hold up to 20 help categories.
SYNOPSIS
#include "cxlwin.h"
int whelpush(void);
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no defined help. See whelpdef().
W_HLPSTKOV - help stack overflow (stack full).
ALSO SEE
whelpcat whelpclr whelpdef whelpop whelppcat whelpushc
------------------------------------------------------------------------
NAME
whelpushc
105
DESCRIPTION
Pushes the specified help category onto the help category stack.
The current help category is not affected. The stack can hold up to
20 help categories.
SYNOPSIS
#include "cxlwin.h"
int whelpushc(int cat);
INPUTS
cat - help category number to push onto help category stack.
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no defined help. See whelpdef().
W_HLPSTKOV - help stack overflow (stack full).
ALSO SEE
whelpclr whelpdef whelpop whelpopc whelppcat whelpush
------------------------------------------------------------------------
NAME
whelpundef
DESCRIPTION
Disengages the help system. This un-defines the help key, clears
the help stack, and frees any memory allocated by the help system.
SYNOPSIS
#include "cxlwin.h"
int whelpundef(void);
RETURN VALUE
W_NOERROR - no error
W_NOHLPDEF - no help defined. See whelpdef().
ALSE SEE
whelpdef
------------------------------------------------------------------------
NAME
whelpwin
DESCRIPTION
Sets specific features to be used by the help window for when it
opens. These are screen coordinates, border type, and whether or not
to display a "Help" title on the upper window border. It does not
actually open the help window. You can call whelpwin() anytime
after calling whelpdef(). You can call whelpwin() as often as you
like during your program.
SYNOPSIS
106
#include "cxlwin.h"
int whelpwin(int srow,int scol,int erow,int ecol,int btype,
int title);
INPUTS
srow - start row to be used for help window
scol - start column to be used for help window
erow - end row to be used for help window
ecol - end column to be used for help window
btype - box type (0-5) to be used for help window
title - display "Help" title on top border? (0=no, 1=yes)
RETURN
W_NOERROR - no error
W_NOHLPDEF - no help defined, see whelpdef()
ALSO SEE
whelpdef
------------------------------------------------------------------------
NAME
whide
DESCRIPTION
Hides the active window. The next window becomes active.
SYNOPSIS
#include "cxlwin.h"
int whide(void);
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
ALSO SEE
whandle wunhide
------------------------------------------------------------------------
NAME
whline
DESCRIPTION
"Draws" a horizontal text line in active window using characters
defined by given box type. If horizontal line crosses a vertical
line of the same box type, an appropriate intersection or corner
will be used.
SYNOPSIS
#include "cxlwin.h"
int whline(int wsrow,int wscol,int count,int btype,int attr);
107
INPUTS
wsrow - window start row
wscol - window start column
count - number of line characters to display
btype - box type. Can be one of the following:
0 - single line
1 - double line
2 - single horz, double vert line
3 - double horz, single vert line
4 - thick line
5 - uses spaces for line chars
attr - text attribute to use for the line
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - text line too long for window
W_INVBTYPE - invalid box type
ALSO SEE
wvline
EXAMPLE
whline(1,0,5,LMAGENTA|_BLACK);
------------------------------------------------------------------------
NAME
windowat
DESCRIPTION
Returns the handle of the window at given screen row,column
coordinates.
SYNOPSIS
#include "cxlwin.h"
WINDOW windowat(int row,int col);
INPUTS
row - screen row
col - screen column
RETURN VALUE
The window handle of the window found at given coordinates. If an
error occurred, zero will be returned and _winfo.errno will be set
to one of the following:
W_NOACTIVE - no active window
W_NOTFOUND - no window found at given screen coordinates
ALSO SEE
whandle
------------------------------------------------------------------------
108
NAME
windump
DESCRIPTION
Dumps a screen window to the printer (PRN).
SYNOPSIS
#include "cxlprn.h"
void windump(int srow,int scol,int erow,int ecol);
INPUTS
srow - start row
scol - start column
erow - end row
ecol - end column
ALSO SEE
wdump
EXAMPLE
windump(0,0,9,79); /* prints top 10 lines of screen */
------------------------------------------------------------------------
Multi-Field Input Functions
Three functions are needed to process multi-field formatted input from
windows: winpbeg(), winpdef(), and winpread(). The winpbeg() function
marks the start of an input form. The winpdef() function defines an
input field and is called for each input field to be defined. The
winpread() function marks the end of the input form and processes all
defined fields. The formatted input capabilities are much like those of
the inputsf() and winputsf() functions. The major difference is that
with the winpbeg()/winpdef()/winpread() combination, you can edit back
and forth between fields before finally accepting the input.
For every input field you want to define, you must call winpdef(). This
will allocate memory to hold the input record information. The first two
parameters, wrow and wcol, specify where in the active window the field
will be loaded.
The next parameter, str, is the address of the string buffer to receive
the input data. The edited string will be terminated with a '\0'. This
means if your format string is "AAAAA", your receiving field must be
string[6] to hold the terminating '\0'. You can edit numeric
information as well. There are 4 conversion functions to convert numbers
to/from CXL fields:
cvtic() - convert integer to CXL field string
cvtci() - convert CXL field string to integer
cvtfc() - convert real number to CXL field string
cvtcf() - convert CXL field string to real number
The next parameter, format, is the input field format string. It
109
controls how each character is input and how large the input field will
be. It consists of 1 or more format characters, and may have displayed
text in between any of the format control characters. You may use
spaces in between the format control characters for readability. Valid
format control characters are listed in the "Formatted Keyboard Input
Functions" section. The case of the format control characters must be
as shown. You can also specify a decimal point in the field. Format
strings for winpdef() are just like those of inputsf() and winputsf()
except there are no command toggles.
The next parameter in the winpdef() function is fconv. These are
similar to the command toggles of inputsf() and winputsf() except that
the fconv character applies conversion to the whole field. Valid fconv
characters are:
0 - apply no conversion
'L' - convert letters to lowercase
'M' - convert letters to mixed upper & lowercase
'P' - password field (do not echo characters)
'U' - convert letters to uppercase
'9' - numeric field (right justify, space fill to the left of
the decimal; and left justify, zero fill to the right of
the decimal.
After the fconv parameter comes the mode parameter. This parameter
allows you to specify if the input field is going to create new data or
update old data. If the mode parameter is 0, then the input field
will be used for entering new data. If the mode parameter is nonzero,
then the input field will be used to update the old data contained in
the str parameter. If you specify 2 for mode, the cursor will appear
at the end of the line and if an editing key is pressed first, the field
will be used for updating, otherwise the field will be used to create
new information. If you do choose to update, then the length of the
input str will be adjusted to the field size either by truncation or
padding with spaces.
The next parameter in the winpdef() function is validate. This
parameter is the address of an optional field validation function. On
exit of each field, winpread() will call this function to validate it.
You can use this function for validating, modifying, displaying error
messages, or just about anything. This must function accept a pointer
to char for input and return either 0 for no error, or the position in
the field where the error occurred (starting with 1). If no validation
function is to be used, then specify NULL. Here's an example field
validation function that checks for embedded spaces:
int check_field_for_embedded_spaces(char *input_field)
{
int current_position=1,error_position=0;
/* search for end of text */
while(*input_field++!=' ') current_position++;
/* search to end of field for non-space characters */
while(*input_field==' ') {
110
current_position++;
input_field++;
}
/* if at not end of field, then field is invalid */
if(*input_field!='\0') error_position=current_position;
return(error_position);
}
The final parameter to winpdef(), help, is the help category number to
assign to this menu item. This is useful if you are using the
context-sensitive help system and you want to assign a different help
category to each field. If you do not need to use this feature, specify
0 for this parameter.
The winpdef() function will return one of the following values:
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_ALLOCERR - memory allocation error
W_NOFRMBEG - no begin of form specified (winpbeg() not called)
W_INVFORMT - invalid format string (syntax error)
Once you have defined all input fields with winpdef(), you call
winpread() to process them. The user is allowed to move around and edit
all of the fields. The input fields are validated on the fly and after
entering the last field. Valid editing keys are listed in Appendix E.
After the winpread() function returns, all fields defined with winpdef()
will be cleared. The receiving strings of all defined fields will now
contain the data entered. If Escape checking was on and [Esc] was
pressed, then all receiving strings will contain the values they held
before winpread() was called and W_ESCPRESS will be returned.
The general structure for defining input fields looks like:
winpbeg(...);
winpdef(...);
winpdef(...);
winpdef(...);
winpread();
Sometimes, you may have a need to extend or modify the data entry keys used
by winpread() during processing of the fields. There is a function,
winpkey(), that enables this. What winpkey() does is defines a function
to be used as the alternate get-key function so that during winpread()
processing you can get a key, test it, change it, or do whatever else
you like with it before you return it to winpread(). It also lets you
to specify a variable to receive the key that caused termination of the
form. The call to winpkey() can be contained anywhere between winpbeg()
and winpread().
Often, when dealing with database records, users would like to have
[PgUp] mean previous record and [PgDn] mean next record. Let's also say
111
that we want to use [F10] as the normal exit key instead of the
currently defined [Ctrl-Enter]. Here is an example of an alternate
get-key function would handle this:
unsigned get_key(int *done)
{
unsigned int key;
key=getxch();
/* if key was [F10], change it to [Ctrl-Enter] */
if(key=0x4400) key=0x1c0a;
/* if key was [PgUp] or [PgDn], set done flag on */
if(key==0x4900 || key==0x5100) *done=TRUE;
return(key);
}
In your code, where you define your form, you use winpkey() to tell CXL
of the alternate get-key function's existance and specify which variable
to hold the keypress of the termination key. Here's something how it
would look in your program:
unsigned key_that_terminated_form;
/*...define window, begin of form, and all fields...*/
winpkey(get_key,&key_that_terminated_form);
winpread();
switch(key_that_terminated_form) {
case 0x4900:
/* [PgUp] */
case 0x5100:
/* [PgDn] */
case 0x1c0d:
case 0x1c0a:
/* [Enter] or [Ctrl-Enter] (aka [F10]) */
case 0x011b:
/* [Esc] */
}
------------------------------------------------------------------------
NAME
winpbeg
DESCRIPTION
Marks the beginning of a data input form, and specifies text
attributes to be used by the form.
SYNOPSIS
#include "cxlwin.h"
int winpbeg(int fieldattr,int textattr);
INPUTS
fieldattr - field attribute
textattr - text attribute
112
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
ALSO SEE
winpdef winpread
------------------------------------------------------------------------
NAME
winpdef
DESCRIPTION
Defines a window input field.
SYNOPSIS
#include "cxlwin.h"
int winpdef(int wrow,int wcol,char *str,char *format,int fconv,
int mode,int (*validate) (char *),int help);
INPUTS
wrow - start of input, window's row coordinate
wcol - start of input, window's column coordinate
str - address of string buffer to receive input
format - address of field format string. See Appendix D for valid
format string characters.
fconv - input field conversion character. Applies conversion to
all characters in the input field. Can be one of the
following:
0 - apply no conversion
'L' - convert letters to lowercase
'M' - convert letters to mixed case
'P' - password field (no echo)
'U' - convert letters to uppercase
'9' - numeric field
mode - field mode
0 - initial data entry
1 - update existing data
2 - conditional update
validate - address of your user validation/modification function.
If you do not wish to have a field validation function,
then specify NULL.
help - help category number to be associated with this input
field. Specify 0 if no help category is to be assigned.
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOFRMBEG - no begin of form specified, see winpbeg()
W_INVCOORD - invalid coordinates
W_INVFORMT - invalid format string
ALSO SEE
113
winpbeg winpread
------------------------------------------------------------------------
NAME
winpfba
DESCRIPTION
Assigns "before" and "after" function pointers to the input field
just defined. The call to this function must appear immediately
after the call to the winpdef() to which it relates. During user
input, when the user enters the field, the before function gets
called. When the user leaves the validated field, the after
function gets called. This powerful feature allows you to do some
pretty advanced stuff with input fields, but must be used very
carefully.
SYNOPSIS
#include "cxlwin.h"
int winpfba(void (*before)(void),void (*after)(void));
INPUTS
before - address of the before function. If you do not wish to
define a before function, specify NULL.
after - address of the after function. If you do not wish to
define an after function, specify NULL.
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_NOFRMBEG - no begin of form defined. See winpbeg().
W_NOINPDEF - no input fields defined. See winpdef().
ALSO SEE
winpbeg winpdef winpread
------------------------------------------------------------------------
NAME
winpfcurr
DESCRIPTION
Returns the address of the current input field's record. After the
call to this function, you may access any of the current input
field's elements. See the definition of struct _field_t in the
CXLWIN.H file for all of the elements you may use. Use caution when
updating elements in the field's record. This function should only
be called while the input form to which it relates is being
processed.
SYNOPSIS
#include "cxlwin.h"
struct _field_t *winpfcurr(void);
114
RETURN VALUE
The address of the current input field's record. You can access
individual elements of the field's record by using this address and
the C pointer operator "->". This function is a macro with no error
checking, and will most likely return an invalid value if there
isn't an active form.
ALSO SEE
winpbeg winpdef winpffind winpread
EXAMPLE
printf("Length of current input field is: %d\n"
,winpfcurr()->lenfld);
------------------------------------------------------------------------
NAME
winpffind
DESCRIPTION
Searches for a defined field whose window coordinates match the
input coordinates, then returns the address of the field's record.
After the call to this function, you may access any of the found
input field's elements. See the definition of struct _field_t in
the CXLWIN.H file for all of the elements you may use. Use caution
when updating elements in the field's record. This function should
only be called during the processing of the input form to which it
relates.
SYNOPSIS
#include "cxlwin.h"
struct _field_t *winpffind(int wrow,int wcol);
INPUTS
wrow - window row of field to search for
wcol - window column of field to search for
RETURN VALUE
The address of the found field's record. You can access individual
elements of the field's record by using this address and the C
pointer operator "->". If an error occurred, then NULL will be
returned and _winfo.errno will be set to one of the following
values:
W_NOACTIVE - no active window
W_NOFRMDEF - no form defined. See winpbeg().
W_NOTFOUND - no defined field matches input window coordinates
ALSO SEE
winpbeg winpdef winpfcurr winpread
------------------------------------------------------------------------
NAME
winpkey
115
DESCRIPTION
Allows you to extend or modify the data entry keys used as the
alternate get-key function so that during winpread() processing you
can get a key, test it, change it, or do whatever else you like with
it before you return it to winpread(). It also lets you specify a
variable to receive the key that caused termination of the form. The
call to winpkey() can be contained anywhere between winpbeg() and
winpread().
SYNOPSIS
#include "cxlwin.h"
int winpkey(unsigned (*getkey)(int *),unsigned *termkey);
INPUTS
getkey - address of the function to be used as the alternate
get-key function.
termkey - address of the unsigned integer which will receive
the keycode of the key that will terminate the form.
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active form
W_NOFRMBEG - no begin of form specified. See winpbeg().
ALSO SEE
winpread
------------------------------------------------------------------------
NAME
winpread
DESCRIPTION
Marks the end of the defined input form and initiates processing of
the defined input fields. The user is allowed to edit back and
forth between the defined fields until the last field is entered.
Valid editing keys are listed in Appendix E.
SYNOPSIS
#include "cxlwin.h"
int winpread(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - [Esc] key was pressed (only if Escape checking was on)
W_NOINPDEF - no input fields defined
ALSO SEE
winpdef winpkey wsetesc
------------------------------------------------------------------------
NAME
116
winputsf
DESCRIPTION
Inputs a formatted string from the keyboard. Typed-in characters
will be echoed to the active window in the current text attribute.
This function provides an extremely powerful method of accept
single-line input from the user. You can limit input characters to
certain characters of a type, such as numbers, insert strings in
between typed in characters, create custom prompts, disable [Enter]
until the field is filled, and more. Provides Escape checking.
Updates cursor position.
SYNOPSIS
#include "cxlwin.h"
int winputsf(char *str,char *fmt);
INPUTS
str - address of the allocated space to receive string
fmt - address of the format string. See Appendix D for valid format
string characters.
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - [Esc] key was pressed
W_INVFORMT - invalid format string
ALSO SEE
wgetns wgets wscanf wsetesc wtextattr
EXAMPLE
char buf[10];
if(winputsf(buf,"'Enter phone nr: '!R--!'('!+!###!-!') '!+!###"
"!-!'-'!+!####")) wprintf("Error: %s\n",werrmsg());
------------------------------------------------------------------------
NAME
winsline
DESCRIPTION
Inserts a blank line in the active window. Depending upon the input
scroll direction, lines will shift up or down to make room for the
new line.
SYNOPSIS
#include "cxlwin.h"
int winsline(int wrow,int direc);
INPUTS
wrow - window row to insert at
direc - scroll direction:
D_UP - scroll up
D_DOWN - scroll down
117
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
ALSO SEE
wdelline wscroll
------------------------------------------------------------------------
NAME
wintodisk
DESCRIPTION
Copies a window of the screen to a disk file.
SYNOPSIS
#include "cxlvid.h"
int wintodisk(int srow,int scol,int erow,int ecol,char *fname);
INPUTS
srow - start row of window
scol - start column of window
erow - end row of window
ecol - end column of window
fname - address of the string containing the filename of the file to
write to
RETURN VALUE
Nonzero if an error occurred.
ALSO SEE
disktoscrn disktowin scrntodisk
EXAMPLE
wintodisk(10,10,20,40,"WINDOW.SAV");
------------------------------------------------------------------------
NAME
wisactiv
DESCRIPTION
Determines if the specified window is active.
SYNOPSIS
#include "cxlwin.h"
int wisactiv(WINDOW whandle);
INPUTS
whandle - the window handle of the window to check.
RETURN VALUE
Nonzero if specified window is active.
118
ALSO SEE
wactiv whandle
------------------------------------------------------------------------
Bar Menu Functions
To use CXL's menuing system, you must be familiar with the process of
defining menus. There are several functions associated with the
defining of menus. These functions must appear in your source code in a
certain order. Menu structures can be defined as simple as a one-level
pop-up menu, or as complex as a multi-level pull-down menu system. The
basic format of all menu structures is:
<wmenubeg|wmenubegc>
wmenuitem
[wmenuitxt]
[wmenuiba]
[<wmenubeg|wmenubegc>...]
[wmenuitem...]
wmenuend
wmenuget
Either wmenubeg() or wmenubegc() is required to mark the start of a
menu, wmenuitem() is required to define menu items, wmenuend() is
required to mark the end of a menu, and wmenuget() initiates user
processing of the entire menu structure.
Notice that you can also define entire menus underneath any individual
menu item. This allows you to easily create nested menus to aid in
building complex pull-down and multi-layered menuing systems. There is
no limit to how deep you can nest sub-menus, with the exception of
available memory.
When coding multi-level menu systems, it is a good idea to use indenting
as shown above to help you distinguish which menu items and menu-ends go
with which menu-begins.
wmenuitxt() and wmenuiba() are optional functions. They allow you to
add specific features to a menu item. If either of these 2 functions
are used, they must immediately follow the call to wmenuitem() to which
they pertain.
After you define the menu structure and call wmenuget(), the user is
allowed to make a selection. The following editing keys may be used by
the user when processing the menu:
LeftArrow - moves selection bar to item left.
RightArrow - moves selection bar to item right.
UpArrow - moves selection bar to item upwards.
DownArrow - moves selection bar to item downwards. If the current
menu item has a pull-down menu attached, then it will
be opened for processing.
Enter - selects the item that the selection bar is on. If
119
selected item has a sub-menu attached, then processing
of that menu will begin.
Home - moves selection bar to upper-leftmost item.
End - moves selection bar to lower-rightmost item.
Esc - if Escape checking is on, and your are in the root
menu, pressing this cancels input and returns a -1. If
inside a sub-menu, then you will just back up to the
previous menu.
You can also quick-select a menu item by pressing its highlighted
selection character, unless this feature is disabled.
CXL's menuing system also includes built-in mouse support. If you want
to use it, you need to call msinit() somewhere near the beginning of the
program. This will set the mouse support level to MS_KEYS, which allows
the mouse to emulate cursor keys. If you would like a point-and-shoot
selection capability where the user moves the mouse cursor around then
presses the button to select, you must set the mouse support level to
MS_CURS or MS_FULL via mssupport(). In either method of mouse support,
the left mouse button is equivalent to the [Enter] key, and the right
mouse button is equivalent to the [Esc] key.
Each menu item can have a function and/or sub-menu attached to it. When
the user selects the menu item, wmenuget() will first check for an
attached sub-menu. If one exists, it will be processed. Then
wmenuget() will check for a defined select function. If one exists,
then wmenuget() will call it.
This gives you two ways to handle a user selection. The first, as
you've seen, is to have a function attached to the menu item. For
example, if the menu item is "(A)dd Record" and it has a select function
called add_record(), then it will be called upon selecting that menu
item. The other way to handle a user selection is by using a
switch/case to test the return value from wmenuget(). This will only
work properly on single-level menus, but sometimes gives you more
flexibility.
------------------------------------------------------------------------
NAME
wmenubeg
DESCRIPTION
Starts a menu/sub-menu definition and describes the window which the
menu will reside in. This does not actually open any windows or
menus, just defines them. This must be used in conjuction with
wmenuitem() and wmenuend(). This is one of the 4 functions that are
required to process a menu.
SYNOPSIS
#include "cxlwin.h"
int wmenubeg(int srow,int scol,int erow,int ecol,int btype,
int battr,int wattr,void (*open)(void));
120
INPUTS
srow - screen start row of where menu's window will open
scol - screen start column of where menu's window will open
erow - screen end row of where menu's window will open
ecol - screen end column of where menu's window will open
btype - border type. Can be one of the following:
0 - single line
1 - double line
2 - single horizontal, double vertical line
3 - double horizontal, single vertical line
4 - thick line
5 - no border
battr - attribute to be used for the menu window's border. If
btype==5, then this value will be ignored.
wattr - attribute to be used for the menu's window.
open - address of the function to call upon opening of the menu's
window. If you want to add a title, shadow, etc. to the
menu's window after it opens, this lets you specify which
function to call to perform these tasks. Specify NULL if
you don't want to use this feature.
RETURN VALUE
W_NOERROR - no error
W_NOITMDEF - no menu items defined
W_ALLOCERR - memory allocation error
ALSO SEE
wmenubegc wmenuitem wmenuend wmenuget
EXAMPLE
wmenubeg(2,10,9,18,0,YELLOW,_BLUE,NULL);
------------------------------------------------------------------------
NAME
wmenubegc
DESCRIPTION
Starts a menu/sub-menu definition. This is used in place of
wmenubeg(). This function differs from wmenubeg() in that when the
user processes the defined menu, the menu will assume whatever the
active window is at the time.
SYNOPSIS
#include "cxlwin.h"
int wmenubegc(void);
RETURN VALUE
W_NOERROR - no error
W_NOITMDEF - no menu items defined
W_ALLOCERR - memory allocation error
ALSO SEE
wmenubeg wmenuitem wmenuend wmenuget
121
------------------------------------------------------------------------
NAME
wmenuend
DESCRIPTION
Ends a menu/sub-menu definition and defines specific
features/attributes of that menu. This is one of the 4 functions
that are required to process a menu.
SYNOPSIS
#include "cxlwin.h"
int wmenuend(int taginit,int menutype,int barwidth,int textpos,
int textattr,int scharattr,int noselattr,int barattr);
INPUTS
taginit - tag ID of the item that the selection bar will start at.
menutype - a mask which describes how the menu will act. Two or
more menutypes can be combined using the bitwise OR
operator '|'. For example, if the menu you are defining
is to be a pull-down menu, and you want to disable quick
selection, then you would specify M_PD|M_NOQS. Valid
menutypes are:
M_HORZ - horizontal menu
M_VERT - vertical menu
M_OMNI - omnidirectional menu
M_PD - pull-down menu
M_SAVE - save last bar position
M_NOQS - disable quick selection
barwidth - width of the selection bar. If zero is given, then the
selection bar will conform to the width of each menu
item. If a number greater than the width of the window
is given, then the barwidth will be adjusted to its
width.
textpos - offset position from the start of the selection bar that
the menu item text will start. If barwidth==0, then
textpos is ignored.
textattr - attribute to be used for menu text
scharattr - attribute to be used for the quick selection character
noselattr - attribute to be used for nonselectable text
barattr - attribute to be used for the selection bar
RETURN VALUE
W_NOERROR - no error
W_NOITMDEF - no menu items defined
W_INVTAGID - taginit was invalid. It must match one of the tagids
in the current menu.
ALSO SEE
wmenubeg wmenubegc wmenuget wmenuitem
EXAMPLE
wmenuend('F',M_VERT,20,2,YELLOW|_BLUE,LCYAN|_BLUE,LGREY|_BLUE
,BLUE|_LGREY);
122
------------------------------------------------------------------------
NAME
wmenuget
DESCRIPTION
Processes the defined menu structure. The user is allowed to move a
selection bar around to the various menu items. If mouse support is
on, then the user can use the mouse for selecting as well. If
sub-menus exists, then the user can select those also. Escape
checking is provided for when the user is in the root menu, however
if the user is in a sub-menu, pressing [Esc] will always return to
the next level up. This is one of the 4 functions that are required
to process a menu.
SYNOPSIS
#include "cxlwin.h"
int wmenuget(void);
RETURN VALUE
The tag ID of the menu item that was selected in the root menu. If
an error occurred, then -1 will be returned and the global variable
_winfo.errno will be set to one of the following:
W_NOMNUDEF - no menu defined
W_NOMNUEND - no end of menu specified. See wmenuend().
W_ESCPRESS - the [Esc] key was pressed from the root menu
W_ALLOCERR - memory allocation error
W_INVCOORD - invalid coordinates
W_INVBTYPE - invalid box type
ALSO SEE
wmenubeg wmenubegc wmenuend wmenuitem wsetesc
------------------------------------------------------------------------
NAME
wmenuiba
DESCRIPTION
Assigns "before" and "after" function pointers to the menu item just
defined. The call to this function must appear immediately after
the call to the wmenuitem() to which it relates. During the
processing of the menu, when the user moves to the item, the before
function gets called. When the user leaves the item, the after
function gets called. This powerful feature allows you to do some
advanced stuff with menus, but must be used very carefully. One
possible use of wmenuiba() is to define a before function that opens
a window and writes some text in it, and an after function which
closes that window. When the user moved to that menu item, the
window would open up and display text, then when the user left that
menu item, the window would automatically close.
SYNOPSIS
#include "cxlwin.h"
123
int wmenuiba(void (*before)(void),void (*after)(void));
INPUTS
before - address of the before function. If you do not wish to
define a before function, specify NULL.
after - address of the after function. If you do not wish to
define an after function, specify NULL.
RETURN VALUE
W_NOERROR - no error
W_NOITMDEF - no menu items defined. See wmenuitem().
ALSO SEE
wmenubeg wmenuend wmenuget wmenuitem wmenuitxt
------------------------------------------------------------------------
NAME
wmenuicurr
DESCRIPTION
Returns the address of the current menu item's record. After this
call, you may access any of the item's elements. This function
would most likely be called from a "select", "before", or "after"
function. See the struct _item_t definition in the CXLWIN.H file
for all the elements you may use.
SYNOPSIS
#include "cxlwin.h"
struct _item_t *wmenuicurr(void);
RETURN VALUE
The address of the current menu item's record.
ALSO SEE
wmenubeg wmenuend wmenuget wmenuifind wmenuitem wmenumcurr
EXAMPLE
printf("The current menu item's tagid = %d\n",wmenuicurr()->tagid);
------------------------------------------------------------------------
NAME
wmenuidsab
DESCRIPTION
This function disables a menu item by making it nonselectable. This
function would most likely be called from a "select", "before", or
"after" function. It will set a flag so that when the called
function returns to the menu, the disabled menu item will be
displayed in the text attribute defined for nonselectable text.
SYNOPSIS
#include "cxlwin.h"
124
int wmenuidsab(int tagid);
INPUTS
tagid - the tag ID of the menu item to disable
RETURN VALUE
W_NOERROR - no error
W_NOMNUDEF - no menu defined
W_NOTFOUND - tagid not found
ALSO SEE
wmenuienab wmenuinext
------------------------------------------------------------------------
NAME
wmenuienab
DESCRIPTION
This function enables a menu item by making it selectable. This
function would most likely be called from a "select", "before", or
"after" function. It will set a flag so that when the called
function returns to the menu, the enabled menu item will be
displayed in the text attribute defined for selectable text.
SYNOPSIS
#include "cxlwin.h"
int wmenuienab(int tagid);
INPUTS
tagid - the tag ID of the menu item to enable
RETURN VALUE
W_NOERROR - no error
W_NOMNUDEF - no menu defined
W_NOTFOUND - tagid not found
ALSO SEE
wmenuidsab wmenuinext
------------------------------------------------------------------------
NAME
wmenuifind
DESCRIPTION
Searches the menu tree structure for the record of the menu item
matching the input tag identifier, then returns the found record's
address. After the call to this function, you may access any of the
found menu item's elements. See the definition of struct _item_t in
the CXLWIN.H file for all of the elements you may use. Use caution
when updating elements in the menu item's record. This function
should only be called during the processing of the menu to which it
relates.
125
SYNOPSIS
#include "cxlwin.h"
struct _item_t *wmenuifind(int tagid);
INPUTS
tagid - the tag identifier of the menu item to find
RETURN VALUE
The address of the found menu item's record. You can access
individual elements of the menu item's record by using this address
and the C pointer operator "->". If an error occurred, then NULL
will be returned and _winfo.errno will be set to one of the
following values:
W_NOMNUDEF - no menu is defined. See wmenubeg().
W_NOTFOUND - input tag identifier not found
ALSO SEE
wmenubeg wmenuend wmenuget wmenuicurr wmenuitem
------------------------------------------------------------------------
NAME
wmenuinext
DESCRIPTION
Defines which menu item the selection bar will move to next. This
function would most likely be called from a "select", "before", or
"after" function. The selection bar does not actually move until
the called function returns to the menu.
SYNOPSIS
#include "cxlwin.h"
int wmenuinext(int tagid);
INPUTS
tagid - the tag ID of the menu item that you want the selection bar
to move to.
RETURN VALUE
W_NOERROR - no error
W_NOMNUDEF - no menu defined
W_NOTFOUND - tagid not found
ALSO SEE
wmenuidsab wmenuienab
------------------------------------------------------------------------
NAME
wmenuitem
DESCRIPTION
Defines a menu item. This is one of the 4 functions that are
required to process a menu.
126
SYNOPSIS
#include "cxlwin.h"
int wmenuitem(int wrow,int wcol,char *str,int schar,int tagid,
int fmask,void (*select)(void),unsigned hotkey,
int help);
INPUTS
wrow - window row
wcol - window column
str - address of menu item string
schar - quick selection character. This is often the first letter
of the menu item.
tagid - unique tag identifier of this particular menu item. This
is the value that wmenuget() returns upon its selection.
fmask - feature mask. Allows you to define one or more additional
features for this menu item. Valid features are:
M_HASPD - has a pull-down menu attached
M_NOSEL - menu item is not selectable
M_CLOSE - close this menu when item is selected. Menu's
window is closed after the selection function
returns.
M_CLOSB - close this menu when item is selected. Menu's
window is closed before the selection
function is called.
M_CLALL - close all menus when item is selected and the
selection function returns.
More than one feature can be specified by using the C
bitwise OR operator '|'. For example, if this item has a
pull-down menu attached and it is not selectable, you would
specify (M_HASPD|M_NOSEL). Specify 0 if you don't want to
define an fmask for this item.
select - address of the function to call upon selection of this menu
item. Specify NULL if you don't want to define a select
function.
hotkey - keycode of the key, which when pressed, will select this
menu item's function from anywhere within the menu
structure. This allows the user to call this menu item's
select function even if not currently processing its menu.
See Appendix B for a list of keycodes that you can use.
Specify 0 if you don't want to define a hotkey.
help - help category number to be associated with this item.
Specify 0 is you don't want to define a help category for
this item.
RETURN VALUE
W_NOERROR - no error
W_NOMNUBEG - no begin of menu specified. See wmenubeg().
W_ALLOCERR - memory allocation error
ALSO SEE
wmenubeg wmenubegc wmenuend wmenuget wmenuicurr wmenuitxt
EXAMPLE
wmenuitem(0,0,"Load F3",'L',1,M_CLOSE,load_file,0x3d00,0);
127
------------------------------------------------------------------------
NAME
wmenuitxt
DESCRIPTION
Adds a text description to a menu item. You can use this function
to create Lotus-style menus where the text descriptions are
displayed underneath the menu and change each time the user moves to
a new menu item.
SYNOPSIS
#include "cxlwin.h"
int wmenuitxt(int wrow,int wcol,int attr,char *str);
INPUTS
wrow - window row
wcol - window column
attr - text attribute
str - address of description string
RETURN VALUE
W_NOERROR - no error
W_NOITMDEF - no menu items defined
ALSO SEE
wmenuiba wmenuitem
EXAMPLE
wmenuitxt(1,0,LCYAN|_BLUE,"Quit program and return to DOS");
------------------------------------------------------------------------
NAME
wmenumcurr
DESCRIPTION
Returns the address of the currently active menu's record. After
this call, you may access any of the menu's elements. See the
definition of struct _menu_t in the CXLWIN.H file for all of the
elements you may use. Use caution when updating elements in the
menu's record. This function should only be called while the menu to
which it relates is being processed.
SYNOPSIS
#include "cxlwin.h"
struct _menu_t *wmenumcurr(void);
RETURN VALUE
The address of the current menu's record. After you get this
address, you can access the menu's elements via the C pointer
operator "->". There is no error return value - if you call this
function while not processing a menu, then you will more than likely
get an invalid address.
128
ALSO SEE
wmenubeg wmenuend wmenuget wmenuicurr wmenuitem
------------------------------------------------------------------------
NAME
wmessage
DESCRIPTION
Displays text on the top or bottom border of the active window.
SYNOPSIS
#include "cxlwin.h"
int wmessage(char *str,int border,int leftofs,int attr);
INPUTS
str - address of message string
border - window border code. Can be one of the following:
TP_BORD - top border
BT_BORD - bottom border
leftofs - offset from left border to display message at
attr - attribute of message text
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_STRLONG - string could not fit in window
W_NOBORDER - window has no border
ALSO SEE
wbprintc wtitle
EXAMPLE
wmessage("[ F1=Help ]",BT_BORD,2,YELLOW|_BLACK);
------------------------------------------------------------------------
NAME
wmove
DESCRIPTION
Moves the active window to a new location on the screen.
SYNOPSIS
#include "cxlwin.h"
int wmove(int nsrow,int nscol);
INPUTS
nsrow - new starting row of window
nscol - new starting column of window
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
129
W_NOACTIVE - no active window
ALSO SEE
wcopy wdrag wsize wslide
------------------------------------------------------------------------
NAME
wopen
DESCRIPTION
Opens a screen window and makes it active. The cursor location will
be initialized to window row 0, column 0. The text attribute will
be initialized to the same attribute as the window. You can open as
many windows as memory permits.
SYNOPSIS
#include "cxlwin.h"
WINDOW wopen(int srow,int scol,int erow,int ecol,int btype,
int battr,int wattr);
INPUTS
srow - starting row
scol - starting column
erow - ending row
ecol - ending column
btype - box type. Can be one of the following:
0 - single line border
1 - double line border
2 - single horz, double vert line border
3 - double horz, single vert line border
4 - thick line border
5 - no border (uses spaces for border chars). A
borderless window has a greater effective window
area than a window with a border.
battr - attribute of window's border.
wattr - attribute of window (and initially the text)
RETURN VALUE
The window handle of the new window or a zero if an error occurred.
If error, the global variable _winfo.errno will be set to one of the
following:
W_ALLOCERR - memory allocation error
W_INVCOORD - invalid coordinates
W_INVBTYPE - invalid box type
ALSO SEE
videoinit wactiv wclose wcloseall wfillch
EXAMPLE
wopen(10,10,20,40,0,LCYAN|_BLUE,LGREEN|_BLUE);
------------------------------------------------------------------------
130
NAME
wperror
DESCRIPTION
Opens an error window, displays an error message, sounds a beep,
waits for a keypress, then returns to caller. The error window is
opened in the general vicinity of the cursor position.
SYNOPSIS
#include "cxlwin.h"
int wperror(char *message);
INPUTS
message - address of the string containing the error message
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_STRLONG - error message string too long
ALSO SEE
werrmsg
EXAMPLE
wperror("Field cannot be blank!");
------------------------------------------------------------------------
NAME
wpgotoxy
DESCRIPTION
Sets cursor coordinates within the active window. If cursor
coordinates are out of the window, wpgotoxy() will try to wrap them
around to fit in the window.
SYNOPSIS
#include "cxlwin.h"
int wpgotoxy(int wrow,int wcol);
INPUTS
wrow - window row (Y coordinate)
wcol - window column (X coordinate)
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wgotoxy wreadcur
------------------------------------------------------------------------
131
NAME
wpickfile
DESCRIPTION
This function will open up a window and display as many
file/directory names in it as it can. The user can use a selection
bar to move through the file/directory names and select one. If all
of the file/directory names cannot fit in the window, scrolling and
paging is allowed. If the user selects a directory, wpickfile()
will change to that directory and display the list of
files/directories in it. After the selection is made, wpickfile()
will return the complete path name of the selected file.
SYNOPSIS
#include "cxlwin.h"
char *wpickfile(int srow,int scol,int erow,int ecol,int btype,
int bordattr,int winattr,int barattr,int title,
char *filespec,void (*open)(void));
INPUTS
srow - start row of pick window
scol - start column of pick window
erow - end row of pick window
ecol - end column of pick window. If ecol==-1, then the
window's width will conform to that of the longest
matching filename.
btype - window box type (0-5)
bordattr - border attribute
winattr - window attribute
barattr - selection bar attribute
title - display filespec title on upper border? (0=no, 1=yes)
filespec - match filespec (ie. "*.*")
open - address of the function to call upon each opening of the
file pick window. If you do not need to use this
feature, specify NULL.
RETURN VALUE
The address of the static string containing the full
drive:path\filename string of the selected file. If an error
occurred, NULL will be returned and _winfo.errno will be set to one
of the following:
W_ESCPRESS - the [Esc] key was pressed
W_ALLOCERR - memory allocation error
W_DOSERROR - DOS error (ie. invalid directory)
W_INVCOORD - invalid window coordinates
W_INVBTYPE - invalid box type
W_STRLONG - window not wide enough to hold largest file name
W_NOMATCH - no files matched input filespec
ALSO SEE
wpickstr wsetesc
EXAMPLE
char *fname;
132
fname=wpickfile(10,10,20,65,0,LCYAN|_BLUE,CYAN|_BLUE,BLUE|_LGREY,1
,"*.*",NULL);
printf("You selected: %s\n",fname);
------------------------------------------------------------------------
NAME
wpickstr
DESCRIPTION
This function will open up a window and display as many of the input
strings in it as it can. The user can use a selection bar to move
through the strings and select one. If all of the strings cannot
fit in the window, scrolling and paging is allowed. After the
selection is made, wpickstr() will return the array subsript of the
string that was selected.
SYNOPSIS
#include "cxlwin.h"
int wpickstr(int srow,int scol,int erow,int ecol,int btype,
int bordattr,int winattr,int barattr,char *strarr[],
int initelem,void (*open)(void));
INPUTS
srow - start row of pick window
scol - start column of pick window
erow - end row of pick window
ecol - end column of pick window. If ecol==-1, then the
window's width will conform to that of the longest string
in the input array.
btype - window box type (0-5)
bordattr - border attribute
winattr - window attribute
barattr - selection bar attribute
strarr - address of array of char pointers (strings) to select
from. The last pointer in the array MUST be NULL!
initelem - element of string to initialize selection bar to. If
given element is invalid, it will default to 0.
open - address of the function to call upon each opening of the
string pick window. If you do not need to use this
feature, specify NULL.
RETURN VALUE
The array subscript of the selected string. If an error occurred,
then -1 will be returned and _winfo.errno will be set to one of the
following:
W_ESCPRESS - the [Esc] key was pressed
W_INVCOORD - invalid window coordinates
W_INVBTYPE - invalid box type
W_STRLONG - window not wide enough to hold largest file name
ALSO SEE
wpickfile wselstr wsetesc
133
EXAMPLE
int i;
char *days[]= { "Sunday","Monday","Tuesday","Wednesday","Thursday",
"Friday","Saturday",NULL };
i=wpickstr(10,10,14,-1,0,YELLOW,LCYAN|_BLUE,BLUE|_LGREY,days,0,
NULL);
if(i!=-1) printf("You selected %s\n",days[i]);
------------------------------------------------------------------------
NAME
wprintc
DESCRIPTION
Displays a character in the active window. Control characters are
not recognized. Cursor position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wprintc(int row,int col,int attr,int ch);
INPUTS
row - window row to display character at
col - window column to display character at
attr - text attribute for character
ch - character
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wbprintc wprints wputc
EXAMPLE
wprintc(5,5,BLINK|LRED|_GREEN,'X');
------------------------------------------------------------------------
NAME
wprintf
DESCRIPTION
Displays a formatted string to the active window at the current
cursor position. Works like the standard printf() function does.
Recognizes control characters. Characters will be displayed in the
attribute set by the wtextattr() function. Updates cursor position.
Also recognizes CXL Escape sequences. See Appendix C for a list of
valid Escape codes.
SYNOPSIS
#include "cxlwin.h"
int wprintf(const char *format,...);
134
INPUTS
format - address of the format string. Refer to the your compiler's
run-time library reference manual for information on valid
format characters.
... - any additional arguments
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wputc wputns wputs wtabwidth wtextattr
EXAMPLE
int i=32767;
double d=3.14159;
char ch='X',*str="Hello, world";
wprintf("i = %d, d = %f, ch = %c, str = %s\n",i,d,ch,str);
------------------------------------------------------------------------
NAME
wprints
DESCRIPTION
Displays a string in the active window. Control characters are not
recognized. Cursor position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wprints(int wrow,int wcol,int attr,char *str);
INPUTS
wrow - window row to display string at
wcol - window column to display string at
attr - text attribute for displayed characters
str - address of string
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_STRLONG - string too long to fit on window line
ALSO SEE
wcenters wprintsf wputs wrjusts wwprints
EXAMPLE
wprints(10,15,BLINK|YELLOW|_BROWN,"Hello, world");
------------------------------------------------------------------------
NAME
wprintsf
135
DESCRIPTION
Displays a string to active window using a CXL format string. If a
character in a string doesn't match its format control character, it
will be displayed as a '?'. Control characters are not recognized.
Cursor position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wprintsf(int wrow,int wcol,int attr,char *format,char *str);
INPUTS
wrow - window row
wcol - window column
attr - text attribute
format - address of format string. Valid format string characters
are listed in Appendix D.
str - address of the string to display.
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVFORMT - invalid format string
W_STRLONG - there were more characters in the display string than
the format string would display.
ALSO SEE
wprints
EXAMPLE
char str1[]="5125900460",str2[]="(512) 590-2910";
wprintsf(3,5,LGREEN|_GREEN,"'('###') '###'-'####",str1);
wprintsf(4,5,LGREEN|_GREEN,"##############",str2);
------------------------------------------------------------------------
NAME
wputc
DESCRIPTION
Displays a character in the active window at current cursor position
using current text attribute. Recognizes control characters.
Updates cursor position.
SYNOPSIS
#include "cxlwin.h"
int wputc(int ch);
INPUTS
ch - the character to be displayed
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
136
ALSO SEE
wdupc wprintc wprintf wtabwidth wtextattr
------------------------------------------------------------------------
NAME
wputns
DESCRIPTION
Displays a string in the active window at the current cursor
location using current text attribute. The input width will
determine how many characters are actually displayed. Padding with
spaces or truncating of output will be used where neccessary.
Recognizes control characters. Updates cursor position.
SYNOPSIS
#include "cxlwin.h"
int wputns(char *str,int width);
INPUTS
str - address of the string to print
width - width to display output string at
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wprintf wputs wtextattr
EXAMPLE
wputns("Hello, world",5);
------------------------------------------------------------------------
NAME
wputs
DESCRIPTION
Displays a string in the active window at the current cursor
position using current text attribute. Recognizes control
characters. Updates cursor position. Also recognizes CXL Escape
sequences. See Appendix C for a list of valid Escape codes.
SYNOPSIS
#include "cxlwin.h"
int wputs(char *str);
INPUTS
str - the address of the string to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
137
ALSO SEE
wprintf wprints wputns wputsw wtabwidth wtextattr
EXAMPLE
wputs("\t\033LHello, \033Lworld!\n\n");
------------------------------------------------------------------------
NAME
wputsw
DESCRIPTION
Displays a string in active window at the current cursor position.
Words will be wrapped around to the next line if necessary.
Characters are displayed in the window's current text attribute.
Recognizes control characters. Updates cursor position. Also
recognizes CXL Escape sequences. See Appendix C for a list of valid
Escape codes.
SYNOPSIS
#include "cxlwin.h"
int wputsw(char *str);
INPUTS
str - the address of the string to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wprintf wputs wtextattr
EXAMPLE
wputsw("This is a very long string that will be wrapped around to "
"the next line.");
------------------------------------------------------------------------
NAME
wreadcur
DESCRIPTION
Reads the current cursor coordinates of the active window.
SYNOPSIS
#include "cxlwin.h"
int wreadcur(int *wrow,int *wcol);
INPUTS
wrow - address of integer to receive current window row
wcol - address of integer to receive current window column
RETURN VALUE
138
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wgotoxy
EXAMPLE
int wrow,wcol;
wreadcur(&wrow,&wcol);
------------------------------------------------------------------------
NAME
wrestore
DESCRIPTION
Restores a previously saved region of the screen screen and frees
the memory allocated by wsave().
SYNOPSIS
#include "cxlwin.h"
void wrestore(int *wbuf);
INPUTS
wbuf - address of previously wsave()d window.
ALSO SEE
srestore wsave
------------------------------------------------------------------------
NAME
wrjusts
DESCRIPTION
Displays a string right justified to specified column in the active
window. Does not recognize control characters. Does not update
cursor position.
SYNOPSIS
#include "cxlwin.h"
int wrjusts(int wrow,int wjcol,int attr,char *str);
INPUTS
wrow - window row to display string at
wjcol - window column that string will right justify to
attr - text attribute for displayed characters
str - address of string to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_STRLONG - string too long to fit in window at specified right
139
justification column.
ALSO SEE
wcenters wprints
------------------------------------------------------------------------
NAME
wsave
DESCRIPTION
Saves a region of the screen.
SYNOPSIS
#include "cxlwin.h"
int *wsave(int srow,int scol,int erow,int ecol);
INPUTS
srow - start row
scol - start column
erow - end row
ecol - end column
RETURN VALUE
Address of newly created window buffer or NULL if a memory
allocation error occurred.
ALSO SEE
ssave videoinit wintodisk wrestore
EXAMPLE
int *wbuf;
if((wbuf=wsave(10,10,20,40))==NULL)
printf("Memory allocation error\n");
------------------------------------------------------------------------
NAME
wscanf
DESCRIPTION
Inputs a formatted string from keyboard. Entered characters will
echo to the active window in the attribute set by the wtextattr()
function. Cursor position will be updated. Works like the standard
C library function scanf() does. This function is only supported by
the Turbo C version of CXL.
SYNOPSIS
#include "cxlwin.h"
int wscanf(const char *format,...);
INPUTS
format - format string. Refer to the section on scanf() in Turbo
C's run-time library reference manual.
140
... - any additional arguments
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wgetc wgetns wgets winputsf wtextattr
------------------------------------------------------------------------
NAME
wscroll
DESCRIPTION
Scrolls text lines within the active window, up or down.
SYNOPSIS
#include "cxlwin.h"
int wscroll(int count,int direc);
INPUTS
count - number of lines to scroll
direc - scroll direction:
D_UP - scroll up
D_DOWN - scroll down
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wdelline winsline wscrollbox
------------------------------------------------------------------------
NAME
wscrollbox
DESCRIPTION
Scrolls a region of the active window up or down.
SYNOPSIS
#include "cxlwin.h"
int wscrollbox(int wsrow,int wscol,int werow,int wecol,int count,
int direc);
INPUTS
wsrow - window start row
wscol - window start column
werow - window end row
wecol - window end column
count - number of lines to scroll
direc - direction of scroll:
141
D_UP - scroll up
D_DOWN - scroll down
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wdelline winsline wscroll
------------------------------------------------------------------------
NAME
wselstr
DESCRIPTION
Allows user to select one string from an array of strings via an
in-place "menu". Provides Escape checking.
SYNOPSIS
#include "cxlwin.h"
int wselstr(int wrow,int wcol,int attr,char *strarr[],int initelem);
INPUTS
wrow - window row to display selections at
wcol - window column to display selections at
attr - attribute for selection text
strarr - the array of string (char *) pointers which to pick from.
The last pointer in the array MUST be NULL!
initelem - element of string to initialize selection bar to. If
given element is invalid, it will default to 0.
RETURN VALUE
The array subscript of the string which was selected. If an error
occurred, then -1 will be returned and _winfo.errno will be set to
one of the following:
W_NOACTIVE - no active window
W_ESCPRESS - [Esc] key was pressed (if Escape checking was on)
ALSO SEE
wpickstr wsetesc
EXAMPLE
int i;
char *prn_ports[]= { "PRN","LPT1","LPT2","COM1","COM2",NULL };
wprints(0,0,LCYAN|_BLUE,"Select printer:");
i=wselstr(0,16,LMAGENTA|_BLUE,prn_ports,0);
if(i!=-1) wprintf("You selected %s\n",prn_ports[i]);
------------------------------------------------------------------------
NAME
wsetesc
142
DESCRIPTION
Sets the Escape checking status for window keyboard input functions
that utilize Escape checking. By default, Escape checking is on.
When the user presses [Esc] while Escape checking is off, the
keypress will be ignored. The exception to this is when inside a
context-sensitive help screen or when inside a sub-menu of a
multi-level menu system.
SYNOPSIS
#include "cxlwin.h"
void wsetesc(int option);
INPUTS
option - 0 = turn Escape checking off, 1 = turn Escape checking on
ALSO SEE
wgetchf wgetns winpread winputsf wmenuget wpickfile wpickstr
------------------------------------------------------------------------
NAME
wshadoff
DESCRIPTION
Removes the shadow from the active window, if one exists. This
function is only needed when you want to prematurely remove the
active window's shadow. The wclose() function automatically calls
wshadoff() when it closes a window.
SYNOPSIS
#include "cxlwin.h"
int wshadoff(void);
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
wclose wshadow
------------------------------------------------------------------------
NAME
wshadow
DESCRIPTION
Gives the active window a shadow. The shadow will be cast to the
right of the window and will be translucent (the characters
underneath the shadow will show through in the given attribute).
SYNOPSIS
#include "cxlwin.h"
int wshadow(int attr);
143
INPUTS
attr - attribute to use for the shadow and the characters underneath
it. The most realistic looking shadow will be achieved using
DGREY|_BLACK, but depending upon the contrast setting on your
monitor, underlying characters may not be visible. Several
commercial programs use a shadow attribute of LGREY|_BLACK
for this reason.
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ALLOCERR - memory allocation error
ALSO SEE
wshadoff
EXAMPLE
wshadow(DGREY|_BLACK);
------------------------------------------------------------------------
NAME
wsize
DESCRIPTION
Adjusts the size of the active window by changing the screen
coordinates of its lower-right corner.
SYNOPSIS
#include "cxlwin.h"
int wsize(int nerow,int necol);
INPUTS
nerow - new end row of window
necol - new end column of window
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
ALSO SEE
wcopy wmove
------------------------------------------------------------------------
NAME
wslide
DESCRIPTION
Smoothly slides active window to new screen position.
SYNOPSIS
144
#include "cxlwin.h"
int wslide(int nsrow,int nscol);
INPUTS
nsrow - new start row for window
nscol - new start column for window
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_ALLOCERR - memory allocation error
ALSO SEE
wdrag wmove
------------------------------------------------------------------------
NAME
wtabwidth
DESCRIPTION
Modifies the tab width to be used when displaying tabs in the active
window via the window TTY output functions. The default tab width
is 8.
SYNOPSIS
#include "cxlwin.h"
void wtabwidth(int tabwidth);
INPUTS
tabwidth - the new tab width
EXAMPLE
wputs("\n\tHello, world");
wtabwidth(4);
wputs("\n\tHello, world");
------------------------------------------------------------------------
NAME
wtextattr
DESCRIPTION
Sets the current text attribute for the active window. The current
text attribute is used by the window TTY output functions for
displaying text inside the active window.
SYNOPSIS
#include "cxlwin.h"
int wtextattr(int attr);
INPUTS
attr - the new text attribute
145
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
ALSO SEE
attrib wchgattr
EXAMPLE
wtextattr(LCYAN|_GREEN|BLINK);
wputs("Hello, world\n");
------------------------------------------------------------------------
NAME
wtitle
DESCRIPTION
Gives active window a title and displays title on top border line of
window. If active window has no border, then the window's record
will be updated, but no title will be visible.
SYNOPSIS
#include "cxlwin.h"
int wtitle(char *str,int tpos,int tattr);
INPUTS
str - address of title string or NULL to delete title
tpos - title position. If str==NULL then tpos is ignored. Valid
tpos values are:
TLEFT - left justified
TCENTER - centered
TRIGHT - right justified
tattr - attribute of window's title
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_ALLOCERR - memory allocation error
ALSO SEE
wmessage
EXAMPLE
wtitle("[ My Window ]",TCENTER,YELLOW|_BROWN);
------------------------------------------------------------------------
NAME
wunhide
DESCRIPTION
Unhides a previously hidden window. The unhidden window becomes the
active window.
146
SYNOPSIS
#include "cxlwin.h"
int wunhide(WINDOW whandle);
INPUTS
whandle - the handle of the window to unhide. If you want to unhide
the most recently hidden window, then specify 0.
RETURN VALUE
W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOTFOUND - window handle not found
W_NOHIDDEN - no hidden windows
W_NOTHIDD - window not hidden
ALSO SEE
whide
------------------------------------------------------------------------
NAME
wunlink
DESCRIPTION
Releases all memory allocated by a window, then unlinks it from the
window chain, making it no longer accessible. The screen is not
changed in any way.
SYNOPSIS
#include "cxlwin.h"
int wunlink(WINDOW w);
INPUTS
w - handle of the window to unlink
RETURN VALUE
W_NOERROR - no error
W_NOTFOUND - input window handle was not found
ALSO SEE
wclose
------------------------------------------------------------------------
NAME
wvline
DESCRIPTION
"Draws" a vertical text line in the active window using characters
defined by the given box type. If the vertical line crosses a
horizontal line of the same box type, an appropriate intersection or
corner will be displayed.
SYNOPSIS
147
#include "cxlwin.h"
int wvline(int wsrow,int wscol,int count,int btype,int attr);
INPUTS
wsrow - window start row
wscol - window start column
count - number of line characters to display
btype - box type. Can be one of the following:
0 - single line
1 - double line
2 - single horz, double vert line
3 - double horz, single vert line
4 - thick line
5 - uses spaces for line characters
attr - attribute to use for text line
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - entire text line could not fit in window
W_INVBTYPE - invalid box type
ALSO SEE
whline
------------------------------------------------------------------------
NAME
wwprints
DESCRIPTION
Prints a string to the specified window. The specified window can
be active, hidden, or blocked. Control characters are not
recognized. Cursor position is not updated.
SYNOPSIS
#include "cxlwin.h"
int wwprints(WINDOW whandle,int wrow,int wcol,int attr,char *str);
INPUTS
whandle - handle of window to display to
wrow - window row to write string to
wcol - window column to write string to
attr - text attribute for written characters
str - address of string to display
RETURN VALUE
W_NOERROR - no error
W_NOACTIVE - no active window
W_NOTFOUND - window handle not found
W_INVCOORD - invalid window coordinates
W_STRLONG - string too long (not all of string was displayed)
ALSO SEE
148
wprints
149
Appendix A - Text Attribute Identifiers
Foreground Colors Background Colors
Identifier Color Identifier Color
---------- ----- ---------- -----
BLACK - black _BLACK - black
BLUE - blue _BLUE - blue
GREEN - green _GREEN - green
CYAN - cyan _CYAN - cyan
RED - red _RED - red
MAGENTA - magenta _MAGENTA - magenta
BROWN - brown _BROWN - brown
LGREY - light grey _LGREY - light grey
DGREY - dark grey
LBLUE - light blue
LGREEN - light green
LCYAN - light cyan
LRED - light red
LMAGENTA - light magenta
YELLOW - yellow
WHITE - white
BLINK - blinking foreground
Example Usage:
BLINK|WHITE|_RED - blinking white on red
YELLOW|_BLUE - yellow on blue
LMAGENTA - light magenta on black
_BLUE - black on blue
150
Appendix B - Keycode Table
Key Norm Shift Ctrl Alt
---- ---- ----- ---- ---
A 1E61 1E41 1E01 1E00
B 3062 3042 3002 3000
C 2E63 2E42 2E03 2E00
D 2064 2044 2004 2000
E 1265 1245 1205 1200
F 2166 2146 2106 2100
G 2267 2247 2207 2200
H 2368 2348 2308 2300
I 1769 1749 1709 1700
J 246A 244A 240A 2400
K 256B 254B 250B 2500
L 266C 264C 260C 2600
M 326D 324D 320D 3200
N 316E 314E 310E 3100
O 186F 184F 180F 1800
P 1970 1950 1910 1900
Q 1071 1051 1011 1000
R 1372 1352 1312 1300
S 1F73 1F53 1F13 1F00
T 1474 1454 1414 1400
U 1675 1655 1615 1600
V 2F76 2F56 2F16 2F00
W 1177 1157 1117 1100
X 2D78 2D58 2D18 2D00
Y 1579 1559 1519 1500
Z 2C7A 2C5A 2C1A 2C00
1 0231 0221 N/A 7800
2 0332 0340 0300 7900
3 0433 0423 N/A 7A00
4 0534 0524 N/A 7B00
5 0635 0625 N/A 7C00
6 0736 075E 071E 7D00
7 0837 0826 N/A 7E00
8 0938 092A N/A 7F00
9 0A39 0A28 N/A 8000
0 0B30 0B29 N/A 8100
, 332C 333C N/A N/A
. 342E 343E N/A N/A
/ 352F 353F N/A N/A
; 273B 273A N/A N/A
' 2827 2822 N/A N/A
[ 1A5B 1A7B 1A1B N/A
] 1B5D 1B7D 1B1D N/A
` 2960 297E N/A N/A
- 0C2D 0C5F 0C1F 8200
= 0D3D 0D2B N/A 8300
\ 2B5C 2B7C 2B1C N/A
151
Key Norm Shift Ctrl Alt
---- ---- ----- ---- ---
F1 3B00 5400 5E00 6800
F2 3C00 5500 5F00 6900
F3 3D00 5600 6000 6A00
F4 3E00 5700 6100 6B00
F5 3F00 5800 6200 6C00
F6 4000 5900 6300 6D00
F7 4100 5A00 6400 6E00
F8 4200 5B00 6500 6F00
F9 4300 5C00 6600 7000
F10 4400 5D00 6700 7100
Enter 1C0D 1C0D 1C0A N/A
Ins 5200 5230 N/A N/A
Del 5300 532E N/A N/A
Esc 011B 011B 011B N/A
Home 4700 4737 7700 N/A
End 4F00 4F31 7500 N/A
PgUp 4900 4939 8400 N/A
PgDn 5100 5133 7600 N/A
<Tab> 0F09 0F00 N/A N/A
<BackSpace> 0E08 0E08 0E7F N/A
<LeftArrow> 4B00 4B34 7300 N/A
<RightArrow> 4D00 4D36 7400 N/A
<UpArrow> 4800 4838 N/A N/A
<DownArrow> 5000 5032 N/A N/A
<Keypad 5> N/A 4C35 N/A N/A
<Grey *> 372A N/A 7200 N/A
<Grey -> 4A2D 4A2D N/A N/A
<Grey +> 4E2B 4E2B N/A N/A
152
Appendix C - Window Output Escape Codes
Escape Code Function
----------- --------
+ - increase text attribute
- - decrease text attribute
A? - set text attribute to ?
F? - set foreground text attribute to ?
B? - set background text attribute to ?
I - toggle intensity
L - toggle blink
X - reverse text attribute
R? - set window row coordinate to ?
C? - set window column coordinate to ?
E? - erase ?:
W - entire window, home cursor
L - to end-of-line
S - to end-of-window
D?? - display ? character ? times
Window output Escape codes are only available in the window TTY output
string functions. Valid functions are wprintf(), wputs(), wputsw(), and
others. Also, the text inside help files can contain Escape codes
(excluding cross-reference items). The Escape code parameters MUST be
character (byte) size. Parameters should be input as binary. For
example, 5 would be '\005'. If you are using them from inside a
wprintf() format string, you can use the '%c' format specifier to supply
the parameter from the list of variables.
Example Usage:
wprintf("\033A%cNormal \033IBright\033I \033LBlink\033L"
" \033XReverse\033X\n",CYAN|_BLUE);
wprintf("\033R%c\033C%cRow %d, Col %d\n",3,5,3,5);
wputs("\033DA\014 = 'A' 12 times\n");
153
Appendix D - Format Control Characters
FCC Description
--- -----------
# Allows numeric characters '0' thru '9'.
% Allows numeric characters '0' thru '9' and ' '.
9 Allows numeric characters '0' thru '9', '.', '-', and '+'.
? Allows any character.
* Allows any printable character.
A Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '.
D Allows date characters '0' thru '9', '-', and '/'.
F Allows legal MS-DOS filename characters.
H Allows hexadecimal characters '0' thru '9', 'A' thru 'F',
and 'a' thru 'f'.
L Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '.
Input letters will be converted to lowercase.
M Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '.
Input letters will be converted to mixed case
P Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '.
Input letters will be displayed as spaces, which is useful
for entering passwords.
T Allows telephone number characters '0' thru '9', '(', ')',
'-', and ' '.
U Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '.
Input letters will be converted to uppercase.
W Allows legal MS-DOS filename characters, including
wildcards.
X Allows alphanumeric characters 'A' thru 'Z', 'a' thru 'z',
'0' thru '9', and ' '.
Y Allows yes/no response characters 'Y', 'N', 'y', and 'n'.
(space) Space characters can be used throughout a format string to
improve its readability.
< Start of inclusion set. An inclusion set allows you to
specify the only allowable characters for a position.
> End of inclusion set. Any characters listed between the
left and right angle brackets are part of the set.
[ Start of exclusion set. An exclusion set allows you to
specify characters that aren't allowed in that position.
] End of exclusion set. Any characters listed between the
left and right square brackets are part of the set.
' Start or end of quoted text that will be displayed either in
the input field or as you are typing. All characters in
between the start and end quotes will be displayed as text.
" Same as the single quote. Is useful if you need to actually
display a single quote as text. Note that in C, you must
represent the double quote as: \"
154
! Start and stop a command toggle sequence. Any characters
in between the start and stop exclamation points are treated
as command toggles. You can have as many command toggles
as you like between the exclamation points. Valid command
toggles are listed below. Command Toggles are valid with
inputsf() and winputsf() only!
Command
Toggle Description
------- -----------
- Decreases text attribute. Valid with winputsf() only.
+ Increases text attribute. Valid with winputsf() only.
C Toggles copying of quoted characters to receiving buffer.
The default is off.
E Toggles Escape checking. When on, if [Esc] is pressed, the
receiving buffer will be emptied and an error code will be
returned. The default for inputsf() is on. The default for
winputsf() is the value of the global variable _winfo.esc.
L Toggles lower-case conversion. When on, all input letters
will be forced to lower-case. The default is off.
M Toggles mixed-case conversion. When on, input letters will
be forced to upper-case for the first letter of each word
and lower-case for the remaining letters. The default is
off.
P Toggles password mode. When on, input characters will be
echoed to the screen as spaces. This is useful for password
fields. The default is off.
R Toggles Return checking. When off, if [Enter] is pressed,
it will be ignored. This is useful for forcing the user's
input. Default is on.
U Toggles upper-case conversion. When on, input letters will
be forced to upper-case. The default is off.
Examples:
inputsf(name,"'Enter name: ' !UR! XXXXX !R! XXXXXXXXXX");
Prompts for name, inputs string from keyboard converting characters to
uppercase as it goes, allows up to 15 alphanumeric characters as input.
The return key is disabled until at least 5 characters have been
entered. Input characters will be copied to the receiving buffer, name,
which must be large enough to hold all 16 characters - 15 for the input
string, and one for the terminating '\0'.
winputsf(phone," 'Enter phone: '!RC! '(' ### ') ' ### '-' ####");
Prompts for a full phone number including area code, allows only digit
characters and displays format punctuation as it goes. The entire field
must be filled before return can be pressed. All of the characters
except the prompt will be copied to the receiving buffer, phone. This
buffer must be large enough to hold 15 characters - 10 for the phone
number digits, 4 for the copied punctuation characters, and 1 for the
terminating '\0'.
155
winpdef( 1,16,date,"<01>#'/'<0123>#'/'<89>#",0,0,NULL,0);
Defines an input field that will accept a MMDDYY date. Note the use of
the inclusion set '<' and '>' characters to aid in allowing only valid
numbers. The receiving buffer, date, must be at least 7 characters to
hold the 6 date characters and the terminating '\0'.
156
Appendix E - Input Field Editing Keys
Key Action
--- ------
LeftArrow cursor left
RightArrow cursor right
UpArrow cursor up
DownArrow cursor down
Ctrl-LeftArrow word left
Ctrl-RightArrow word right
Tab field right
Shift-Tab field left
Enter process field
Ctrl-Enter process all fields
Decimal (.) move to right side of decimal point
Home beginning of field
End end of field line / end of field
Ctrl-Home beginning of first field
Ctrl-End end of last field
Ins toggle field insert mode
Del delete character at cursor
BackSpace delete character left
Ctrl-BackSpace delete word left
Ctrl-R restore field to original contents
Ctrl-T delete word right
Ctrl-U delete to end of field
Ctrl-Y delete to end of last field
Esc abort data entry (if Escape checking is on)
157
