OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / TCXOS2.ZIP / TCXLOS2.TXT < prev next >

Wrap

Text File | 1991-11-05 | 432KB | 13,593 lines

The TesSeRact CXL User Interface Development System Version 5.52 -- March 15, 1991 TCXL-OS/2 for OS/2 Character Mode Copyright 1987-91, Innovative Data Concepts, Inc. All Rights Reserved Innovative Data Concepts, Inc. 122 North York Road Suite 5 Hatboro, PA 19040 Voice: 1-215-443-9705 Orders: 1-800-926-4551 FAX: 1-215-443-9753 TCXL is part of IDC's TesSeRact Development Tools series of programmer's products. Acknowledgements Thanks to my loving wife Anne Marie, without whom life would be nothing. A very special thanks to Tina, who keeps this place running. My good friend Michael Mohle' slaved over the code and made it all work. Michael has been a heavy-duty trooper throughout the development and enhancement of this product, and deserves every bit of thanks he can get. Most of TCXL's flexibility and portability is due to his years of experience in the industry. And we must not forget Mike Smedley, who developed the initial CXL product, and without whom TCXL would never have existed. Without beta testers, where are we in this business? I've had a great crew for TCXL, much too numerous to mention individually. But a few deserve extra kudos: Doug MacLean, who selflessly gave his time and effort as needed. Dave Seidel, who found more critters than we wanted him to, and received the "Golden Cockroach" award for his trouble. Ed Mulroy, who called at ungodly hours while writing batch files. Peter Schultz, for requesting enhancements, providing the code for them, and then reporting bugs in the way they worked because he changed his mind! Mike Burns, for finding a few problems that were causing us to lose our hair. And we must mention Gary Weinfurther, who kept finding those little gnats even after we thought the code was finished. What about Eric Irwin and Mark Engbretson, who worked so hard to find those last few inconsistencies. Last, but certainly not least, Richard Herzog and his hardware .... Thanks, everyone! Page ii TesSeRact CXL V5.52 Documentation This document; other accompanying written and disk-based notes and specifications; and all referenced and related program files accompanying this document are copyrighted by Innovative Data Concepts. For ordering information, see the ORDER.DOC file provided with this package. For shareware distribution requirements, see the VENDOR.DOC file. _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER The DOS versions of the TesSeRact Development Tools are distributed as shareware -- this means that we encourage users, subject to restrictions described in the License Agreement, to share copies of this program with friends, associates and bulletin boards. You may not share the registered version of The TesSeRact Development Tools; however, you may request a free shareware disk by completing the form in VENDOR.DOC. If you make copies of the shareware distribution versions of the TesSeRact Development Tools, you must include all files in the original distribution files, as well as the documentation archive. You are not permitted to distribute the TesSeRact Development Tools without this documentation. Innovative Data Concepts, Inc., is a member of the Association of Shareware Professionals. The ASP has established stringent standards for its members. ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a problem with an ASP member (other than technical support), ASP may be able to help. Please write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006. Trademarks SWAPSK, SWAPSP, SWAPTN, SWAPMT, SWAPMM, SWAPSH, SWAPDT, SWAPNG and The SWAP Utilities are trademarks of Innovative Data Concepts. TesSeRact and The TesSeRact Development Tools are trademarks of Innovative Data Concepts 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. 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 and Xenix are registered trademarks of Microsoft Corporation. Turbo C and Turbo C++ are registered trademarks of Borland International. UltraVision is a trademark of Personics, Inc. Unix is a registered trademark of American Telegraph and Telephone, Inc. Zortech is a trademark of Zortech Inc. TesSeRact CXL V5.52 Documentation Page iii Table of Contents Index of Functions................................................vii Alphabetical Index of Functions....................................xi General Information.....................................................1 Features Overview.......................................................2 General System Features.............................................2 TCXL-DOS Features...................................................3 Supported Standards For DOS.........................................3 Technical Support.......................................................4 Bug Fixes, Updates, Etc.............................................4 About Innovative Data Concepts..........................................4 IDC Products........................................................5 Using Library Functions.................................................5 Portability and Shorthand Notation..............................6 Naming Conventions..................................................7 Standard IDC Types..............................................8 IDC-specific type-aliases.......................................8 Common Function Pointer Types...................................8 Installation............................................................9 Converting Code From CXL 5.x........................................9 Converting Code From TCXL 5.51......................................9 Compiling and Linking...............................................9 Library Organization...............................................10 Future Planning....................................................11 Using the TCXL Systems.................................................12 OverView...........................................................12 Initialization Equates.........................................13 Initialization Routines........................................14 Menu System........................................................18 Menu System Equates............................................20 Menu System Example............................................22 Menu System Routines...........................................25 Menu and Item Definition...................................25 Menu Operation.............................................33 Menu Internals.............................................37 Entry System.......................................................38 Format Control Characters......................................42 Entry System Equates...........................................43 Entry System Example...........................................45 Entry System Routines..........................................47 Form and Field Definition..................................47 Entry Form Processing......................................52 Entry Field Processing.....................................55 Entry Internals............................................57 Help System........................................................58 Building Help Files............................................59 Help System Equates............................................60 Help System Routines...........................................61 Help Definition............................................61 Help Operation.............................................65 Help Internals.............................................69 Selection System...................................................70 Selection System Equates.......................................70 Selection System Routines......................................71 Selection Utilities........................................75 Selection Internals........................................77 Page iv TesSeRact CXL V5.52 Documentation Window System......................................................78 Window System Equates..........................................79 Window System Routines.........................................80 Error Handling Routines....................................80 General Window Control.....................................82 Active Window Movement.....................................91 Active Window Control......................................96 Active Border.............................................102 Active Shadow.............................................105 Active Cursor.............................................106 Line Drawing..............................................108 Active Window Output......................................111 Window Internals..........................................119 Input System......................................................121 Input System Routines.........................................121 Strings System....................................................128 Strings System Routines.......................................128 Trimming..................................................128 Changing..................................................129 Checksum..................................................130 Delete/Insert.............................................130 Inclusion.................................................132 Replacement...............................................133 Substrings................................................134 Justification.............................................135 Matching..................................................136 Miscellaneous.............................................137 Cursor Control System.............................................139 Cursor Equates................................................139 Cursor Control Routines.......................................140 Mouse Cursor..............................................140 Display Cursor............................................141 Mouse Control Routines........................................142 Format Control Subsystem..........................................144 National Language Support.....................................145 Format Control Equates........................................146 NLS Routines..................................................149 Format Control Routines.......................................150 Selection Engine Subsystem........................................156 Selection Equates.............................................156 Selection Engine Routines.....................................157 Display Subsystem.................................................158 Display Equates...............................................158 Display Routines..............................................160 Video Control.............................................160 Boxes, Clearing and Filling...............................161 Cursor Control............................................166 Attribute Control.........................................169 Video Input...............................................171 Video Output..............................................173 Event Subsystem...................................................178 Event Routines................................................178 Asynchronous Input........................................178 Input With No Echo........................................183 TCXL Keyboard Queue.......................................185 Utility Subsystem.................................................187 Utility Routines..............................................187 TesSeRact CXL V5.52 Documentation Page v Opsys Subsystem...................................................191 Opsys Routines................................................191 Information Subsystem.............................................195 Information Equates...........................................195 Information Routines..........................................195 Near/Far Subsystem................................................199 Near/Far Routines.............................................199 Memory Subsystem..................................................201 Memory Routines...............................................201 Printer Subsystem.................................................202 Printer Routines..............................................202 Appendix A - Text Attributes..........................................206 Appendix B - Keycode Table............................................207 Appendix C - Window Output Escape Codes...............................208 Appendix D - Format Control Characters................................209 Appendix E - Movement and Editing Keys................................212 Appendix F - Global Error Codes.......................................213 Appendix G - OS/2 Specific Information................................214 Notes about compilers.............................................214 Mid-Level Mouse Functions.........................................215 IBM Enhanced Keyboard Support.....................................217 Page vi TesSeRact CXL V5.52 Documentation Index of Functions TcxlInit.......................14 FldDis.........................57 TcxlVer........................14 FldReq.........................57 _TcxlTerm......................15 _FldPut........................57 TcxlKeyOff.....................15 _FldSet........................57 TcxlMemOff.....................15 HlpDef.........................61 TcxlMouOff.....................15 HlpOff.........................62 TcxlNlsOff.....................15 HlpKey.........................62 TcxlVuvOff.....................16 HlpTtl.........................63 TcxlCurOff.....................16 HlpWind........................64 MemFail........................16 HlpGet.........................65 WinFail........................17 HlpAdd.........................65 MSSetEnt.......................17 HlpCur.........................66 MSSetHlp.......................17 HlpDrop........................66 MSSetMnu.......................17 HlpSet.........................67 MSSetSel.......................17 HlpPush........................67 MnuBuild.......................25 HlpPop.........................68 MnuAct.........................26 HlpAct.........................68 MnuDef.........................27 HlpClr.........................68 MnuItm.........................28 _HlpErr........................69 MnuEnd.........................29 _HlpPag........................69 MnuTxt.........................30 SelAttr........................71 ItmFun.........................31 SelFile........................72 ItmTxt.........................32 SelStr.........................74 MnuGet.........................33 SelTxt.........................75 MnuCur.........................33 SelFree........................75 ItmCur.........................34 SelBarOn.......................76 ItmLoc.........................34 SelBarOff......................76 ItmNxt.........................34 SelDirOn.......................76 ItmDsp.........................35 SelDirOff......................76 ItmDis.........................35 SelParOn.......................76 ItmEna.........................36 SelParOff......................76 ItmGet.........................36 _Select........................77 ItmSet.........................37 Wperror........................80 _ItmKey........................37 WerrMsg........................81 _ItmPtr........................37 Werror.........................81 _ItmPut........................37 Wactiv.........................82 EntBuild.......................47 WcloseAll......................82 EntDef.........................48 Windowat.......................83 EntFld.........................48 WinLoc.........................83 EntDis.........................49 Wisactiv.......................84 EntKey.........................49 Wopen..........................84 EntOpt.........................50 WpopUp.........................85 EntSep.........................50 Wsave..........................86 EntTrm.........................51 Wrestore.......................86 FldKey.........................51 Wpush..........................86 FldFun.........................52 Wpop...........................86 EntGet.........................52 WsetEsc........................87 EntCur.........................53 WsetFil........................87 EntDsp.........................53 WsetFun........................88 EntFree........................54 WsetTab........................88 EntPush........................54 WsetTxt........................88 EntPop.........................55 Wunhide........................89 FldCur.........................55 Wunlink........................89 FldLoc.........................56 Wwprints.......................90 FldChg.........................56 Wcenter........................91 TesSeRact CXL V5.52 Documentation Page vii Wclose.........................91 WchkCol.......................119 Wcopy..........................92 WchkPos.......................120 Wdrag..........................92 WchkRow.......................120 Wdump..........................93 KwGetCf.......................121 Wgrow..........................93 KvGetCf.......................121 Whandle........................94 KwGetCh.......................122 Whide..........................94 KvGetCh.......................122 Wmove..........................94 KwGetFmt......................123 Wsize..........................95 KvGetFmt......................123 Wslide.........................95 KwGetSn.......................124 Wstretch.......................96 KvGetSn.......................124 WchgAtr........................96 KwGetSt.......................125 Wclear.........................97 KvGetSt.......................125 WclrEol........................97 KwGetYn.......................126 WclrEos........................97 KvGetYn.......................126 WclrWin........................98 KwScanf.......................127 Wdepth.........................98 KvScanf.......................127 WfilBox........................99 strbtrim......................128 WlinDel.......................100 strltrim......................128 WlinIns.......................100 strtrim.......................128 WscrBox.......................101 strrtrim......................128 WscrWin.......................101 strchg........................129 Wwidth........................102 strichg.......................129 Wborder.......................102 strschg.......................129 Wbprintc......................103 strischg......................129 Wmessage......................103 strchksum.....................130 Wtitle........................104 strichksum....................130 Wshadow.......................105 strdel........................130 Wshadoff......................105 stridel.......................130 WcurGet.......................106 strdela.......................131 WcurPut.......................106 stridela......................131 Wgotoxy.......................106 strins........................131 Wpgotoxy......................107 strinc........................132 WposGet.......................107 striinc.......................132 WdrwBox.......................108 strocc........................132 WdrwHor.......................109 striocc.......................132 WdrwVer.......................110 strsocc.......................133 WdupChrA......................111 strisocc......................133 WdupChr.......................111 strsrep.......................133 WdupStrA......................112 strisrep......................133 WdupStr.......................112 strmid........................134 Wprtc.........................113 strleft.......................134 Wputc.........................113 strright......................134 Wprts.........................114 strljust......................135 Wputs.........................114 strrjust......................135 Wprtns........................115 strrol........................135 Wputns........................115 strror........................135 Wputsw........................115 strshl........................136 Wprtf.........................116 strshr........................136 Wputf.........................116 strbmatch.....................136 WprtFmt.......................117 strmatch......................137 WputFmt.......................117 strblank......................137 WprtCen.......................118 strcode.......................137 WputCen.......................118 strsetsz......................138 Wprtrj........................119 struplow......................138 Wputrj........................119 MouHide.......................140 WchkBox.......................119 MouShow.......................140 Page viii TesSeRact CXL V5.52 Documentation MouPush.......................140 VsavBox.......................165 MouPop........................140 VlodBox.......................165 CurHide.......................141 VsavScr.......................165 CurShow.......................141 VlodScr.......................165 CurPush.......................141 Vsave.........................166 CurPop........................141 Vrestore......................166 CurSave.......................141 Vscroll.......................166 CurSize.......................141 VcurGet.......................166 NlsIsAlpha....................149 VcurHid.......................167 NlsIsPrint....................149 VcurPut.......................167 NlsIsLower....................149 VcurSet.......................167 NlsIsUpper....................149 VcurSiz.......................168 NlsToLower....................149 Vgotoxy.......................168 NlsToUpper....................149 VposGet.......................168 cvtic.........................150 VatrInv.......................169 cvtci.........................150 VatrMap.......................169 cvtfc.........................151 VatrRev.......................169 cvtcf.........................151 VatrSet.......................170 _FmtAttr......................151 VatrTxt.......................170 _FmtChar......................151 Vattrib.......................170 _FmtFill......................151 Vgetw.........................171 _FmtFunc......................152 Vgetc.........................171 _FmtGetc......................152 Vgets.........................171 _FmtGets......................152 Vgetb.........................172 _FmtInit......................152 Vgetv.........................172 _FmtMask......................152 Vgetsv........................172 _FmtOpts......................153 Vprintc.......................173 _FmtPuts......................153 Vputc.........................173 _FmtSeps......................153 Vprints.......................174 _FmtVali......................153 Vputs.........................174 _FmtClr.......................153 Vprintn.......................174 _FmtCpy.......................154 Vputn.........................174 _FmtCur.......................154 Vprintw.......................175 _FmtDec.......................154 Vputw.........................175 _FmtDel.......................154 Vprintb.......................175 _FmtIns.......................155 Vputb.........................175 _FmtPos.......................155 Vputv.........................176 _FmtSpa.......................155 Vputx.........................176 _NlsInit......................155 VputSpa.......................177 _NlsGet.......................155 Vputnca.......................177 _SelPag.......................157 KbndChg.......................178 _SelMou.......................157 KbndClr.......................179 VidMode.......................160 KusrClr.......................179 VidOfs........................160 KbndFre.......................179 VidParm.......................160 KusrFre.......................179 VposDec.......................161 KbndIdle......................179 VposInc.......................161 KbndMac.......................180 VsetLin.......................161 KusrMac.......................180 Vclear........................161 KbndMou.......................181 VclrBox.......................162 KbndPut.......................182 VclrEol.......................162 KbndSet.......................182 VclrScr.......................162 KusrSet.......................182 VdrwBox.......................163 KeyClear......................183 VdrwHor.......................163 KeyEvent......................183 VdrwVer.......................164 KeyGetc.......................183 VexpBox.......................164 KeyPeek.......................184 VfilBox.......................165 KeyStat.......................184 TesSeRact CXL V5.52 Documentation Page ix KeyTime.......................184 HdwNdp........................198 KeyWait.......................184 HdwMou........................198 KqueChk.......................185 HdwMdm........................198 KqueClr.......................185 HdwC40........................198 KqueGet.......................185 HdwC80........................198 KquePut.......................186 HdwM80........................198 KqueStr.......................186 HdwDrv........................198 Beep..........................187 HdwPar........................198 RandFile......................187 HdwSer........................198 Sound.........................187 MK_FP.........................199 SysDate.......................188 MK_FPT........................199 SysTime.......................188 _FarCpy.......................199 TabNxt........................189 _CpyFar.......................199 _Delay........................189 _FarGet.......................200 _StdOut.......................189 _GetFar.......................200 _StdOutS......................190 _FarPut.......................200 _Timer........................190 _PutFar.......................200 _WaitMs.......................190 _MemInit......................201 _CerrGet......................191 _MemTerm......................201 _CerrSet......................191 _LPputC.......................202 _CerrOut......................191 lcrlf.........................202 _CerrPush.....................191 lprintc.......................202 _CerrPop......................191 lprintf.......................203 _ChgDir.......................192 lprintn.......................203 _ChgDrv.......................192 lprintns......................203 _FilFnd.......................192 lprints.......................204 _FndFst.......................193 lprintsb......................204 _FndNxt.......................193 lprintsu......................204 _GetDir.......................193 scrndump......................205 _GetDtm.......................194 windump.......................205 _GetDrv.......................194 MSgoto........................215 _GetSys.......................194 MSlimit.......................215 _BioEqp.......................195 MSmove........................215 _InpByt.......................196 MSpress.......................215 _InpWrd.......................196 MSreles.......................216 _OutByt.......................196 MSreset.......................216 _OutWrd.......................196 MSspeed.......................216 _IntEna.......................196 MSstat........................216 _IntDis.......................196 MSupdat.......................216 BiosVer.......................196 KextOff.......................217 ClockCal......................197 KextOn........................217 MachId........................197 KfixOff.......................217 HdwFlg........................198 KfixOn........................217 HdwGam........................198 Page x TesSeRact CXL V5.52 Documentation Alphabetical Index of Functions _BioEqp.......................195 _NlsGet.......................155 _CerrGet......................191 _NlsInit......................155 _CerrOut......................191 _OutByt.......................196 _CerrPop......................191 _OutWrd.......................196 _CerrPush.....................191 _PutFar.......................200 _CerrSet......................191 _Select........................77 _ChgDir.......................192 _SelMou.......................157 _ChgDrv.......................192 _SelPag.......................157 _CpyFar.......................199 _StdOut.......................189 _Delay........................189 _StdOutS......................190 _FarCpy.......................199 _TcxlTerm......................15 _FarGet.......................200 _Timer........................190 _FarPut.......................200 _WaitMs.......................190 _FilFnd.......................192 Beep..........................187 _FldPut........................57 BiosVer.......................196 _FldSet........................57 ClockCal......................197 _FmtAttr......................151 CurHide.......................141 _FmtChar......................151 CurPop........................141 _FmtClr.......................153 CurPush.......................141 _FmtCpy.......................154 CurSave.......................141 _FmtCur.......................154 CurShow.......................141 _FmtDec.......................154 CurSize.......................141 _FmtDel.......................154 cvtcf.........................151 _FmtFill......................151 cvtci.........................150 _FmtFunc......................152 cvtfc.........................151 _FmtGetc......................152 cvtic.........................150 _FmtGets......................152 EntBuild.......................47 _FmtInit......................152 EntCur.........................53 _FmtIns.......................155 EntDef.........................48 _FmtMask......................152 EntDis.........................49 _FmtOpts......................153 EntDsp.........................53 _FmtPos.......................155 EntFld.........................48 _FmtPuts......................153 EntFree........................54 _FmtSeps......................153 EntGet.........................52 _FmtSpa.......................155 EntKey.........................49 _FmtVali......................153 EntOpt.........................50 _FndFst.......................193 EntPop.........................55 _FndNxt.......................193 EntPush........................54 _GetDir.......................193 EntSep.........................50 _GetDrv.......................194 EntTrm.........................51 _GetDtm.......................194 FldChg.........................56 _GetFar.......................200 FldCur.........................55 _GetSys.......................194 FldDis.........................57 _HlpErr........................69 FldFun.........................52 _HlpPag........................69 FldKey.........................51 _InpByt.......................196 FldLoc.........................56 _InpWrd.......................196 FldReq.........................57 _IntDis.......................196 HdwC40........................198 _IntEna.......................196 HdwC80........................198 _ItmKey........................37 HdwDrv........................198 _ItmPtr........................37 HdwFlg........................198 _ItmPut........................37 HdwGam........................198 _LPputC.......................202 HdwM80........................198 _MemInit......................201 HdwMdm........................198 _MemTerm......................201 HdwMou........................198 TesSeRact CXL V5.52 Documentation Page xi HdwNdp........................198 KvGetFmt......................123 HdwPar........................198 KvGetSn.......................124 HdwSer........................198 KvGetSt.......................125 HlpAct.........................68 KvGetYn.......................126 HlpAdd.........................65 KvScanf.......................127 HlpClr.........................68 KwGetCf.......................121 HlpCur.........................66 KwGetCh.......................122 HlpDef.........................61 KwGetFmt......................123 HlpDrop........................66 KwGetSn.......................124 HlpGet.........................65 KwGetSt.......................125 HlpKey.........................62 KwGetYn.......................126 HlpOff.........................62 KwScanf.......................127 HlpPop.........................68 lcrlf.........................202 HlpPush........................67 lprintc.......................202 HlpSet.........................67 lprintf.......................203 HlpTtl.........................63 lprintn.......................203 HlpWind........................64 lprintns......................203 ItmCur.........................34 lprints.......................204 ItmDis.........................35 lprintsb......................204 ItmDsp.........................35 lprintsu......................204 ItmEna.........................36 MachId........................197 ItmFun.........................31 MemFail........................16 ItmGet.........................36 MK_FP.........................199 ItmLoc.........................34 MK_FPT........................199 ItmNxt.........................34 MnuAct.........................26 ItmSet.........................37 MnuBuild.......................25 ItmTxt.........................32 MnuCur.........................33 KbndChg.......................178 MnuDef.........................27 KbndClr.......................179 MnuEnd.........................29 KbndFre.......................179 MnuGet.........................33 KbndIdle......................179 MnuItm.........................28 KbndMac.......................180 MnuTxt.........................30 KbndMou.......................181 MouHide.......................140 KbndPut.......................182 MouPop........................140 KbndSet.......................182 MouPush.......................140 KextOff.......................217 MouShow.......................140 KextOn........................217 MSgoto........................215 KeyClear......................183 MSlimit.......................215 KeyEvent......................183 MSmove........................215 KeyGetc.......................183 MSpress.......................215 KeyPeek.......................184 MSreles.......................216 KeyStat.......................184 MSreset.......................216 KeyTime.......................184 MSSetEnt.......................17 KeyWait.......................184 MSSetHlp.......................17 KfixOff.......................217 MSSetMnu.......................17 KfixOn........................217 MSSetSel.......................17 KqueChk.......................185 MSspeed.......................216 KqueClr.......................185 MSstat........................216 KqueGet.......................185 MSupdat.......................216 KquePut.......................186 NlsIsAlpha....................149 KqueStr.......................186 NlsIsLower....................149 KusrClr.......................179 NlsIsPrint....................149 KusrFre.......................179 NlsIsUpper....................149 KusrMac.......................180 NlsToLower....................149 KusrSet.......................182 NlsToUpper....................149 KvGetCf.......................121 RandFile......................187 KvGetCh.......................122 scrndump......................205 Page xii TesSeRact CXL V5.52 Documentation SelAttr........................71 TcxlMouOff.....................15 SelBarOff......................76 TcxlNlsOff.....................15 SelBarOn.......................76 TcxlVer........................14 SelDirOff......................76 TcxlVuvOff.....................16 SelDirOn.......................76 VatrInv.......................169 SelFile........................72 VatrMap.......................169 SelFree........................75 VatrRev.......................169 SelParOff......................76 VatrSet.......................170 SelParOn.......................76 VatrTxt.......................170 SelStr.........................74 Vattrib.......................170 SelTxt.........................75 Vclear........................161 Sound.........................187 VclrBox.......................162 strblank......................137 VclrEol.......................162 strbmatch.....................136 VclrScr.......................162 strbtrim......................128 VcurGet.......................166 strchg........................129 VcurHid.......................167 strchksum.....................130 VcurPut.......................167 strcode.......................137 VcurSet.......................167 strdel........................130 VcurSiz.......................168 strdela.......................131 VdrwBox.......................163 strichg.......................129 VdrwHor.......................163 strichksum....................130 VdrwVer.......................164 stridel.......................130 VexpBox.......................164 stridela......................131 VfilBox.......................165 striinc.......................132 Vgetb.........................172 strinc........................132 Vgetc.........................171 strins........................131 Vgets.........................171 striocc.......................132 Vgetsv........................172 strischg......................129 Vgetv.........................172 strisocc......................133 Vgetw.........................171 strisrep......................133 Vgotoxy.......................168 strleft.......................134 VidMode.......................160 strljust......................135 VidOfs........................160 strltrim......................128 VidParm.......................160 strmatch......................137 VlodBox.......................165 strmid........................134 VlodScr.......................165 strocc........................132 VposDec.......................161 strright......................134 VposGet.......................168 strrjust......................135 VposInc.......................161 strrol........................135 Vprintb.......................175 strror........................135 Vprintc.......................173 strrtrim......................128 Vprintn.......................174 strschg.......................129 Vprints.......................174 strsetsz......................138 Vprintw.......................175 strshl........................136 Vputb.........................175 strshr........................136 Vputc.........................173 strsocc.......................133 Vputn.........................174 strsrep.......................133 Vputnca.......................177 strtrim.......................128 Vputs.........................174 struplow......................138 VputSpa.......................177 SysDate.......................188 Vputv.........................176 SysTime.......................188 Vputw.........................175 TabNxt........................189 Vputx.........................176 TcxlCurOff.....................16 Vrestore......................166 TcxlInit.......................14 VsavBox.......................165 TcxlKeyOff.....................15 Vsave.........................166 TcxlMemOff.....................15 VsavScr.......................165 TesSeRact CXL V5.52 Documentation Page xiii Vscroll.......................166 Wprtrj........................119 VsetLin.......................161 Wprts.........................114 Wactiv.........................82 Wpush..........................86 Wborder.......................102 Wputc.........................113 Wbprintc......................103 WputCen.......................118 Wcenter........................91 Wputf.........................116 WchgAtr........................96 WputFmt.......................117 WchkBox.......................119 Wputns........................115 WchkCol.......................119 Wputrj........................119 WchkPos.......................120 Wputs.........................114 WchkRow.......................120 Wputsw........................115 Wclear.........................97 Wrestore.......................86 Wclose.........................91 Wsave..........................86 WcloseAll......................82 WscrBox.......................101 WclrEol........................97 WscrWin.......................101 WclrEos........................97 WsetEsc........................87 WclrWin........................98 WsetFil........................87 Wcopy..........................92 WsetFun........................88 WcurGet.......................106 WsetTab........................88 WcurPut.......................106 WsetTxt........................88 Wdepth.........................98 Wshadoff......................105 Wdrag..........................92 Wshadow.......................105 WdrwBox.......................108 Wsize..........................95 WdrwHor.......................109 Wslide.........................95 WdrwVer.......................110 Wstretch.......................96 Wdump..........................93 Wtitle........................104 WdupChr.......................111 Wunhide........................89 WdupChrA......................111 Wunlink........................89 WdupStr.......................112 Wwidth........................102 WdupStrA......................112 Wwprints.......................90 WerrMsg........................81 Werror.........................81 WfilBox........................99 Wgotoxy.......................106 Wgrow..........................93 Whandle........................94 Whide..........................94 Windowat.......................83 windump.......................205 WinFail........................17 WinLoc.........................83 Wisactiv.......................84 WlinDel.......................100 WlinIns.......................100 Wmessage......................103 Wmove..........................94 Wopen..........................84 Wperror........................80 Wpgotoxy......................107 Wpop...........................86 WpopUp.........................85 WposGet.......................107 Wprtc.........................113 WprtCen.......................118 Wprtf.........................116 WprtFmt.......................117 Wprtns........................115 Page xiv TesSeRact CXL V5.52 Documentation General Information The TCXL library is a supplement to the ANSI-compliant C compiler's standard run-time library. With more than 375 multipurpose functions, and available on a variety of hardware and software platforms, TCXL can significantly enhanced programmer productivity, while simultaneously improving the marketability of the final product. TCXL Version 5.52 is available for DOS, OS/2 and Unix, with versions for both VMS and 386 Protected Mode under development. The primary advantage to using TCXL to develop your software is that you can compile and link your code on one platform, and then bring your source code without modification to a different platform supported by TCXL, and have it compile/link/run successfully! In contrast with other programmer's packages available on multiple platforms, TCXL is not written in 100% C code. Writing all (or mostly) in C does make porting a library easier, but it certainly causes performance to suffer. TCXL is written in highly-optimized C code, with virtually all of its hardware-related functions written in assembler. The library has been designed in a hierarchical fashion, with different levels designed for development. TesSeRact CXL V5.52 Documentation Page 1 Features Overview General System Features »» Customized 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. »» 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. You may also tie each field to a hot-key, and move between fields using a mouse. With Version 5.52, you can disable fields, make them "required" for input, or even page through records of a database! »» Context-Sensitive Help Help files are indexed for speed and categories can be cross-referenced. Help can be applied at the global, window, menu item, and input field levels. »» Powerful Selection Capabilities TCXL has scrollable pick menus, that 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, and a built-in video attribute selector. »» Full-Featured Window Control Allows as many open windows as memory permits. Windows can be stacked, tiled, shadowed, moved, resized, and changed in many other ways. There are more than 75 functions designed to handle windowed output. »» User-defined Input Features TCXL's Input System provides a consistent interface between the hardware- dependent input devices and TCXL's output systems. This system features both formatted and unformatted user input, with varying levels of output control. »» Advanced String Manipulation There are nearly 40 string manipulation functions that perform searching, replacing, formatting, conversion, rotating, shifting, pattern matching, and other string operations. »» Hardware-Independent Display Control By separating the display from the video hardware, TCXL allows the programmer direct control of the display without device dependence. TCXL-DOS has several output methods built-in, including direct screen writing, direct screen writing with CGA snow elimination, and BIOS video writes. Support for the DESQview/Windows/TopView interface is automatic when writing direct to the video buffer areas. TCXL-Unix supports a variety of terminal interfaces. Page 2 TesSeRact CXL V5.52 Documentation »» Keyboard Management TCXL has built a hardware-independent interface for the keyboard as well. By using the built-in upper level keyboard management routines, applications can be quickly and easily moved between operating environments. Of course, low-level keyboard control is available for those who need this type of access. »» Automatic Mouse Support If you write your program using TCXL, the mouse will automatically be enabled in Menus, Entry Forms and Selection lists. No programmer knowledge or manipulation of mice is necessary! For those whose applications require more direct mouse control, TCXL can have button- presses translated into keystrokes and movements into arrow keys. Low- level functions are provided for directly manipulating Microsoft- compatible mice, and TCXL supports both two and three-button mice. <<Note! TCXL-Unix does not currently support the mouse; however, development is underway and TCXL-Unix will have identical mouse support in a future release!>> TCXL-DOS Features »» Nonstandard Video Sizes EGA 43 and VGA 50-line modes are fully supported and TCXL provides functions to directly change to and from these modes. TCXL's video functions are also compatible with nonstandard modes such as 132x25 and 120x43. »» Expanded/Extended Memory TCXL has a full set of routines for accessing Expanded Memory through the EMS specification, and for accessing Extended Memory through the XMS specification. TCXL will also recognize the presence of advanced memory management schemes such as VCPI and DPMI. »» National Language Support For international developers, TCXL 5.52 adds full support for DOS' international language character sets. The TCXL formatted entry routines automatically configure themselves for National Language Support, and correctly recognize the country, monetary units, yes/no prompts, and more. Supported Standards For DOS TCXL supports all the current memory management standards currently available. This includes the DOS Protected Mode Interface Specification (DPMI) Version 0.9, the Virtual Control Program Interface (VCPI) Version 1.0, the eXtended Memory Specification (XMS) Version 2.0, and the Expanded Memory Specification (EMS) Version 4.0. Details about these four standards are discussed in the chapter about the Memory Subsystem. In addition, TCXL provides direct support for Personics' UltraVision(TM) program. UltraVision is an EGA/VGA video control program with support for multiple screen fonts, multiple screen sizes and higher resolution. TCXL will automatically detect the presence of UltraVision, and provides low- level routines to manipulate the size of the video display (See Page (?)). For more information about UltraVision, call Personics at 1-800-445-3311 or 1-508-897-1575. TesSeRact CXL V5.52 Documentation Page 3 Technical Support The first stop for IDC Technical Support is CompuServe. Innovative Data Concepts has a support conference on the PCVENC forum, in Subtopic 6. All IDC shareware products are available for download from CompuServe in this library, and technical support is available in the message section. Contact us at 76702,1361 for technical questions, or 75300,564 for customer support. IDC also maintains a support conference on BIX -- JOIN ibm.pc/idc, or send BIXMail to c.rabinowitz. We also maintain a presence on the European CIX system -- JOIN tesseract/general, direct CIXMail to chipper. The next stop are the BBS networks. IDC maintains a support conference on RIME/RelayNet, and is active in the C Language Conference. If you have access to FidoNet, you can find us in the C Echo, as well as in the CXL Echo. If you have access to MCIMAIL, we can be reached at 315-5415. Many of our overseas distributors provide direct technical support to their customers. Contact them directly. If all else fails, send us a FAX at 1-215-443-9753, or give us a call at 1- 215-443-9705. We'll be happy to help. Bug Fixes, Updates, Etc. A bug is a bug is a bug. Anyone who calls it something else is just trying to hide it. Perfect software is impossible. And with a product as complex and varied as TCOMP, we don't expect to have uncovered everything (although we certainly have tried!). Interim source code fixes may be distributed through our network of BBS systems around the world. Contact IDC Technical Support for more details, or see the BBSLIST.DOC file that came with your product. About Innovative Data Concepts Innovative Data Concepts, Inc. is a rapidly-growing software firm, dedicated to developing, publishing, distributing and supporting affordable, state-of-the-art software for both professional programmers, as well as for general users. Chip Rabinowitz is IDC's Vice President of Research and Development, and is well-known among the industry for his technical expertise. He is an Assistant Sysop on the Computer Language Magazine Forum on CompuServe Information Service and also provides technical support for Borland International as a member of "Team Borland" on their CompuServe Forums, in the areas of Turbo C, Turbo Assembler, Turbo Debugger, SideKick ('Classic', SK Plus and SK 2.0), Quattro Pro and Paradox. Page 4 TesSeRact CXL V5.52 Documentation IDC Products The SWAP Utilities . . . make it possible to load many popular TSRs in less than 8K of your precious DOS memory. With a "High-DOS" memory manager, these resident programs require 0K of DOS memory. The technology used by the SWAP Utility programs may be applied to other resident programs. Developer's inquiries are welcome. Innovative Data Concepts is currently researching other applications of SWAP technology. If you have any suggestions/comments, please contact IDC. SWAPDOS . . . lets you switch between two large applications, keeping your place in one while working in the other. Swap the first application (and TSRs) drivers to EMS, XMS or disk, and load another program. Have Microsoft Word swapped to EMS, while looking at your Lotus 1-2-3 spreadsheet. The TesSeRact Ram Resident Development System . . . has been acclaimed by many to be the standard toolkit for TSR development. This toolkit provides developers with everything needed to create compatible TSRs that are well- behaved in today's complex environment. The TesSeRact CXL User Interface Development System has more than 375 multipurpose functions, designed to make building menus, data entry forms, and complete user interfaces, as simple as possible. TCXL is the cornerstone of IDC's new TesSeRact Programmer's Power Pak, which features data compression, device-independent printer control, and file management. Using Library Functions Every function in this library has a corresponding prototype in one of the distributed header files. In the function reference portion of this document, each routine is marked with the appropriate header file. The exception is TCXLDEF.H, which is automatically included when you include any other IDC header file. The TCXLDEF.H file also describes which headers #include other header files in a graphic manner. Note that all nested #include's are conditionalized, you your compiler will only thrash through each header file ONCE, no matter how many times you reference it within a file. The header files are system header files, rather than local files; i.e., they should be placed in the same directory as your standard include files, and are referenced using angle-brackets (< >) instead of quotes, as in previous versions. For example: #include <dos.h> #include <stdio.h> #include <TCXLwin.h> #include <TCXLinp.h> TesSeRact CXL V5.52 Documentation Page 5 Portability and Shorthand Notation Once you master the strong typing used by these routines, reading the code should be very simple. However, because the code has been designed for maximum portability, the C code must rely heavily on the pre-processor to handle all the differences between compilers and operating environments. Therefore, we strongly urge you to study typing and naming conventions described below, as well as the specific typedefs in TcxlDef.H. Once you get the hang of it, you should have little trouble. One of the first things you will notice when reading the source code is that virtually all the functions are prototyped as "CTYP". Do not be confused! CTYP does not stand for "C Language Type" -- it stands for "Call Type". CTYP is a typedef, and under DOS versions of our products, translates to the faster, and more efficient "pascal" calling convention instead of the normal "cdecl" convention, where available on the particular compiler. The pascal keyword is not part of ANSI, and is specific to DOS- based compilers. The following typedefs are used internally by the this library for code consistency, and to ensure that various preprocessor features are available on all systems. It it not necessary for your code to use these explicitly; in fact, even if a function is prototyped using "VOID", you may use the standard C "void" in your code without harm. #define CON const #define CTYP PAS /* compiler-dependent! */ #define GBL extern #define LCL static #define REG register #define SIZ(c) sizeof(c) #define TYP typedef #define UNS unsigned #define VOID void #define VOL volatile #define LOOP for(;;) /* endless loop */ #ifdef __cplusplus # define NOARG /* remove (void) cruft for C++ */ #else # define NOARG void /* leave (void) cruft for C */ #endif Page 6 TesSeRact CXL V5.52 Documentation Naming Conventions The TesSeRact Developers Tools uses a simple naming convention for all structures and typedefs. If, for example a structure is defined as "struct Kcod", it would be typedef'd as "KcodT", and a a pointer to an object would be "KcodP". There are a number of reasons for this convention; the primary onces are portability, maintainability, and consistency. As an example, see the following code fragment: #include <TCXLkey.h> union Kcod KbdCode; /* keycode union declaration */ KcodT KbdCode1; /* Identical declaration using typedef */ KcodP KbdPtr; /* pointer to keycode type */ ... KbdPtr = &KbdCode; /* Assign pointer to union */ KbdPtr = &KbdCode1; /* same thing */ We are aware, however, that there is a tendency for C programmers to resist change. With the coming of C++, the success of strongly-typed languages like Pascal, and the advent of multiple operating platforms, it is necessary for the modern programmer to write readable, portable, consistent code. If, however, you prefer to use "char *" instead of "ChrP" in your function declarations, your compiler won't complain. So go ahead. We have found, however, that after about a week, you won't want to go back. If you look at the typedefs that follow, you'll note that the object always ends with 'T', the pointer ends with 'P', indirect pointers end with 'I' and far pointers end with FP. All standard IDC types use this standard convention; therefore, simply looking at the way a variable is declared can describe simply how it will be used. TesSeRact CXL V5.52 Documentation Page 7 Standard IDC Types TYP VOID *AnyP, **AnyI; /* anonymous void pointer */ TYP VOID FAR *AnyFP; /* ... far-pointer */ TYP char ChrT, *ChrP, **ChrI; /* 8-bit char */ TYP ChrT FAR *ChrFP; /* ... far-pointer */ TYP ChrT *StrP, **StrI; /* NulTerm string */ TYP UNS char BytT, *BytP, **BytI; /* 8-bit unsigned byte */ TYP BytT FAR *BytFP; /* ... far-pointer */ TYP BytT FlgT, *FlgP, **FlgI; /* 8-bit Boolean flag */ TYP short IntT, *IntP, **IntI; /* 16-bit signed int */ TYP IntT FAR *IntFP; /* ... far-pointer */ TYP UNS short WrdT, *WrdP, **WrdI; /* 16-bit unsigned word */ TYP WrdT FAR *WrdFP; /* ... far-pointer */ TYP long LngT, *LngP, **LngI; /* 32-bit signed long */ TYP LngT FAR *LngFP; /* ... far-pointer */ TYP UNS long DwdT, *DwdP, **DwdI; /* 32-bit unsigned dword */ TYP DwdT FAR *DwdFP; /* ... far-pointer */ TYP float FltT, *FltP, **FltI; /* 32-bit real */ TYP double DblT, *DblP, **DblI; /* 64-bit real */ TYP WrdT LenT, *LenP, **LenI; /* alias for ANSI size_t */ TYP LngT PosT, *PosP, **PosI; /* alias for ANSI fpos_t */ TYP WrdT NdxT, *NdxP, **NdxI; /* unsigned array-indices */ TYP IntT ArgT; /* bytes/chars as ints */ IDC-specific type-aliases TYP BytT AtrT, *AtrP; /* video attribute */ TYP WrdT KeyT, *KeyP; /* keycode (char/scan) */ TYP IntT TagT, *TagP; /* item/field/help tag */ TYP IntT WndT, *WndP; /* window handle */ Common Function Pointer Types TYP VOID (CTYP *VfvCP)(NOARG); /* VOID (CTYP *function)(NOARG) */ TYP VOID (CTYP *VfcCP)(ChrT); /* VOID (CTYP *function)(ChrT) */ TYP VOID (CTYP *VfiCP)(IntT); /* VOID (CTYP *function)(IntT) */ TYP VOID (CTYP *CfcCP)(ChrT); /* ChrT (CTYP *function)(ChrT) */ TYP IntT (CTYP *IfiCP)(IntT); /* IntT (CTYP *function)(IntT) */ TYP IntT (CTYP *IfcpCP)(ChrP); /* IntT (CTYP *function)(ChrP) */ TYP WrdT (CTYP *WfipCP)(IntP); /* WrdT (CTYP *function)(IntP) */ TYP KeyT (CTYP *KfvCP)(NOARG); /* KeyT (CTYP *function)(NOARG) */ Page 8 TesSeRact CXL V5.52 Documentation Installation Since installation procedures will vary from platform to platform, see the installation supplement that came with your package, or read the INSTALL.DOC file on your distribution diskettes. Converting Code From CXL 5.x ««DOS ONLY»» To convert your existing CXL projects to use TCXL 5.52, we have provided RPL.EXE and CONVERT.BAT. See the instructions provided in your DOC directory for full details. Converting Code From TCXL 5.51 ««DOS ONLY»» To convert your existing TCXL 5.51 projects to use TCXL 5.52, we have provided RPL.EXE and UPG-552.BAT. See the instructions provided in your DOC directory for full details. Compiling and Linking Since compiling and linking are dependent on your hardware/software environment, as well as your particular compiler, these details are provided in the installation supplement that came with your package, or read the INSTALL.DOC file on your distribution diskettes. TesSeRact CXL V5.52 Documentation Page 9 Library Organization The TCXL library is organized into various systems and subsystems. A quick look at the library structure can be of assistance: User Level: Menu System Entry System Help System Selection System Service Level: Window System Input System Strings System Cursor Control System Interface Level: Format Control Subsystem Selection Engine Subsystem Display Subsystem Event Subsystem Utility Subsystem OpSys Subsystem Access Level: Information Subsystem Near/Far Subsystem Memory Subsystem Printer Subsystem Internal Level: Video Access Subsystem Keyboard Access Subsystem Mouse Access Subsystem The User Level of TCXL provides the highest level of user support, with the most insulation from the physical hardware. The routines at this level were designed to be built entirely upon the lower-level systems. These functions are restricted from calling the Access Level and Internal Level functions directly; all calls go through the Service and Interface Level functions. The functions available in the Service Level of the library are all utility functions that may or may not be needed in your application. These systems are restricted from calling "up" to the User Level, and "down" to the Internal Level. The Interface Level is actually the "glue" that holds the entire library together. There are three basic parts to the Interface Level, with two subsystems in each part. The Format Control and Selection Engine Subsystems provide an interface between the User Level routines and all Input/Output. The Display and Event Subsystems provide an interface between the Service Level and the Internal Level [note here that Format Control and Selection Engine also call the Display and Event Subsystems]. Finally, the Utility and OpSys Subsystems provide an interface between the programmer and the physical environment. Page 10 TesSeRact CXL V5.52 Documentation The Access Level consists of functions where a programmer would want direct access to the physical hardware; an example of this is Expanded Memory usage on DOS machines. The functions at Access Level are required in all implementations of TCXL, even when there is no equivalent functionality (such as far pointers in a flat memory environment). The Internal Level of TCXL is the direct access to the hardware that is used by the upper-level systems. The functions at the Internal Level of TCXL should never be called by user code. The functions at the Internal Level need not be physically present across platforms, since they are only called internally. This library organization has been designed for a specific purpose: To move TCXL to another hardware or software platform, we need only replace the Internal Level with appropriate routines, add or stub out the required Access Level functions, convert the OpSys Subsystem, and then modify the rest of the Interface Level for the new Internal Level Routines. Future Planning TCXL 5.52 is Innovative Data Concept's second release of this product. Needless to say, we have lots more planned. TCXL 6.0 is due to be released sometime in the 3rd Quarter of 1991, and will include things like a full event-driven interface, a configurable printer system, an interface to graphic interfaces, and more. With the release of version 5.52, TCXL has been ported to a number of different operating platforms in text mode. Along with the move to the event-driven systems in 6.0, we also plan on moving to various graphical user interfaces on our various hardware platforms. We are also planning on extending the product line horizontally, with things planned like a screen designer, virtual memory system, file management/indexing, etc. We will keep you apprised of new developments as they occur. TesSeRact CXL V5.52 Documentation Page 11 Using the TCXL Systems OverView In order to initialize the TCXL low-level routines, and correctly determine the configuration of the machine the program will run on, you MUST initially make a call to the function TcxlInit(). This function initializes the Internal Level and Access Level Subsystems. In a difference from previous versions under DOS, you may not initialize the various subsystems separately. TcxlInit() also sets up calls to the at_exit chain, which are necessary to successfully terminate your application cleanly. Prior to calling TcxlInit(), it is possible to disable support of some of TCXL's features and systems. For example, you might call TcxlMouOff() to disable mouse support; or TcxlNlsOff() to disable National Language Support. A full description of these initialization macros appear in the function descriptions later in this manual. Another pre-installation option is to set the debugging level. If you have compiled the library with debugging on (TCXLDBG=1) the TcxlDbg value is initialized to display a warning box and terminate on all memory allocation failures, as well as window error messages. By modifying TcxlDbg, you may have all window error messages just pop up a warning box, and then continue; or turn off these diagnostic errors. If the library is compiled without debugging information, the TcxlDbg value is ignored. TCXL also has various "STUB" routines, which can be used to reduce the size of your program if you do not use or want certain features, i.e., the memory system, or the mouse. These stubs provide entry points for the required functions that are called internally, but reduce the size of code. Look in the "\STB" directory for the various stub modules, and how to use them in conjunction with TCXL. Page 12 TesSeRact CXL V5.52 Documentation Initialization Equates _TcxlCtl Access Macros TcxlErr...........................................Error code TcxlDbg..........................................Debug-level TcxlSys...............................................System TcxlSvr.......................................System version TcxlCty.........................................Country-code TcxlEnv....................................Environment (DOS) TcxlCfg...................................Configuration bits TcxlDbg debug levels DBG_NUL....................................No error trapping DBG_MEM........................Error-exit of allocation fail DBG_WRN..........................Warning Box on Window Error DBG_WER...........................Error Exit on Window Error DBG_WIN.............................Both window debug levels TcxlSys values SYS_DOS.................................MS-DOS/PC-DOS/DR_DOS SYS_JDS............................................Japan DOS SYS_OS2.................................................OS/2 SYS_XNX.........................................MS/SCO Xenix SYS_UNX............................................AT&T Unix SYS_BSD.............................................BSD Unix SYS_AIX..............................................IBM AIX SYS_VMS..............................................DEC VMS TcxlEnv bits <MS-DOS Only> ENV_MOU................................................Mouse ENV_KEY....................................Enhanced keyboard ENV_UV...........................................UltraVision ENV_MEM................................TCXL memory subsystem ENV_ESA.............................................EISA bus ENV_MCA..............................................MCA bus ENV_NLS............................National-language support ENV_CUR.........................Save cursor position on exit TesSeRact CXL V5.52 Documentation Page 13 Initialization Routines --------------------------------------------------------------------------- TcxlInit Synopsis........Low-level Library Initialization. Header File.....TCXLdef.h Prototype.......VOID CTYP TcxlInit(NOARG); Source File.....UTL\TCXLINIT.C Arguments.......None Returns.........None Notes...........Within this function, the low-level Access Level and Internal Level are initialized. In future versions, all add-in modules will also be initialized here, as well as user-defined functions. This function also sets the _TcxlTerm() function as a termination function, using the compiler's atexit() procedure. Example.........#include <TCXLdef.h> int main(int argc, char **argv) { TcxlInit(); ProcessMain(); exit(0); } --------------------------------------------------------------------------- TcxlVer Synopsis........TCXL Version Number Header File.....TCXLdef.h Prototype.......WrdT TcxlVer(NOARG); Returns.........An unsigned integer, with the high byte equal to the major version of TCXL and the low byte equal to the minor version. Example.........printf("This is Version %d.%d of TCXL\n", TcxlVer() >> 8, TcxlVer & 0x00ff); displays This is Version 5.52 of TCXL Page 14 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- _TcxlTerm (Internal) Synopsis........Terminate TCXL Library Access Header File.....TCXLdef.h Prototype.......VOID CDC _TcxlTerm(NOARG); Source File.....UTL\TCXLINIT.C Notes...........For internal use only. Not to be called by user programs. --------------------------------------------------------------------------- TcxlKeyOff Synopsis........Disable Enhanced Keyboard Test Header File.....TCXLdef.h Prototype.......VOID TcxlKeyOff(NOARG); Notes...........This function may have no effect on some platforms. This is primarily designed to detect between machines that have support Enhanced Keyboard BIOS under DOS and OS/2. --------------------------------------------------------------------------- TcxlMemOff Synopsis........Disable Memory Subsystem Header File.....TCXLdef.h Prototype.......VOID TcxlMemOff(NOARG); Notes...........This function may have no effect on some platforms. This is primarily designed to detect the types of memory available on DOS machines. --------------------------------------------------------------------------- TcxlMouOff Synopsis........Disable Mouse Subsystem Header File.....TCXLdef.h Prototype.......VOID TcxlMouOff(NOARG); Notes...........This function may have no effect on some platforms. --------------------------------------------------------------------------- TcxlNlsOff Synopsis........Disable National Language Support Header File.....TCXLdef.h Prototype.......VOID TcxlNlsOff(NOARG); Notes...........This function may have no effect on some platforms. TesSeRact CXL V5.52 Documentation Page 15 --------------------------------------------------------------------------- TcxlVuvOff Synopsis........Disable UltraVision for DOS Support Header File.....TCXLdef.h Prototype.......VOID TcxlVuvOff(NOARG); Notes...........This function is only useful on DOS systems, but is maintained for compatibility across platforms. --------------------------------------------------------------------------- TcxlCurOff Synopsis........Do not restore cursor position when program terminates. Header File.....TCXLdef.h Prototype.......VOID TcxlCurOff(NOARG); Notes...........This function is only useful on DOS systems, but is maintained for compatibility across platforms. --------------------------------------------------------------------------- MemFail Synopsis........Debugging Popup for Memory Allocation Errors Header File.....TCXLdef.h Prototype.......VOID CTYP MemFail(ChrP Module, IntT LineNo); Source File.....WIN\WINDBG.C Arguments.......Module - Name of module that called MemFail() LineNo - Line number in module where error occurred. Returns.........None Notes...........Internal Debugging Call. Page 16 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WinFail Synopsis........Debugging Popup for Window Errors Header File.....TCXLdef.h Prototype.......VOID CTYP WinFail(ChrP Module, IntT LineNo); Source File.....WIN\WINDBG.C Arguments.......Module - Name of module that called MemFail() LineNo - Line number in module where error occurred. Returns.........If (TcxlDbg & DBG_WER) terminate application; otherwise, return ERR_ARG. Notes...........Internal Debugging Call. --------------------------------------------------------------------------- MSSetEnt MSSetHlp MSSetMnu MSSetSel Synopsis........Sets mouse support level. Header File.....TCXLinp.h Prototype.......VOID MSSetEnt(BytT x); VOID MSSetHlp(BytT x); VOID MSSetMnu(BytT x); VOID MSSetSel(BytT x); Arguments.......x - Mouse Support Level: MOU_NONE.No mouse support MOU_KEYS.Emulate arrow keys MOU_CURS.Free-moving visible cursor MOU_FULL.Full mouse support Returns.........None. Notes...........The default mouse support level in all systems is MOU_FULL. TesSeRact CXL V5.52 Documentation Page 17 Menu System Using the TCXL Menu System, you can create menus as simple as a single- level popup menu, or as complex as a multi-level pull-down bar menu system. No matter how complex your menus are, with TCXL you use the same basic calling sequence to define them. The basic format (optional calls are in brackets []) is: <MnuDef|MnuAct> MnuTxt MnuItm [ItmTxt] [ItmFun] [<MnuDef|MnuAct>] [MnuTxt] [MnuItm] [...] [MnuEnd] MnuEnd MnuGet Important note!!!! Previous versions of TCXL use MnuBeg() and MnuShow() for menu processing; for this reason, MnuShow() has been declared as an alias for compatibility purposes in TCXLmnu.h. MnuBeg(), which has a different prototype than the new MnuDef(), will cause your compiler to terminate during pre-processing with a nonsense error message. Either MnuDef() or MnuAct() is required to mark the start of a menu; MnuTxt() is used to define the area for individual item text descriptions; MnuItm() is required to define menu items; MnuEnd() marks the end of a menu; and MnuGet() 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. ItmTxt() and ItmFun() are optional functions. They allow you to attach specific features to a particular menu item. If you use either of these two functions, they must immediately follow the call to MnuItm() to which they pertain. Beginning with Version 5.52, you may also use a new function, MnuBuild() (Page 25), to create your menus. This function, described in more detail below and in the demonstration program, can be used to build an entire complex, nested, menu structure with one function call. All of the necessary information is stored in data structures, which makes for easier programmer's documentation, as well as easier maintenance. Page 18 TesSeRact CXL V5.52 Documentation After you define the menu structure and call MnuGet(), the user is allowed to make a selection. The following editing keys (editing keys are also listed in Appendix E) may be used by the user when processing the menu: Menu Movement Key Action ----------------- ------ 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 (and the current menu is a horizontal menu!), then it will be opened for processing. Enter....................selects the item that the selection bar is on. If 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 you 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. Each menu item can have a function and/or sub-menu attached to it. When the user selects the menu item, MnuGet() will first check for an attached sub-menu. If one exists, it will be processed. Then MnuGet() will check for a defined select function. If one exists, then MnuGet() 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 MnuGet(). This will work best on single-level menus, since MnuGet() only returns the tag ID of the root menu's selection, but sometimes gives you more flexibility. Please note that mouse support is automatically activated during menu processing, if a mouse has been detected during initialization. Also, be aware that the mouse is deactivated during before/after procedures, as well as when processing the menu's select functions. Programmers who wish to take advantage of the mouse in their own windows (not in one of the automatic systems of TCXL) will need to specifically enable the type of mouse support they want. TesSeRact CXL V5.52 Documentation Page 19 Menu System Equates _Mctl Access Macros MctlTop............................................Root menu MctlCur.........................................Current menu MctlMnu...........................................Menu level MctlItm...........................................Item level MctlTag.......................................Selected TagId _Mdf Access Macros MdfPrv(m)......................................Previous menu MdfTop(m).....................................Item-list head MdfBot(m).....................................Item-list tail MdfCur(m).......................................Current item MdfEng(m)........................................Page Engine MdfOpn(m)...................................."Open" function MdfTag(m)................................Selected item TagId MdfBeg(m).....................................Start position MdfBegW(m)..............................................Word MdfBegC(m)...............................................Col MdfBegR(m)...............................................Row MdfEnd(m).......................................End position MdfEndW(m)..............................................Word MdfEndC(m)...............................................Col MdfEndR(m)...............................................Row MdfPos(m)................................Item start position MdfPosW(m)..............................................Word MdfPosC(m)...............................................Col MdfPosR(m)...............................................Row MdfDsc(m)...............................Description/help pos MdfDscW(m)..............................................Word MdfDscC(m)...............................................Col MdfDscR(m)...............................................Row MdfLim(m)..................................Image size/limits MdfLimW(m)..............................................Word MdfLimC(m)..............................................Cols MdfLimR(m)..............................................Rows MdfFrm(m)..............................................Frame MdfFrmT(m)........................................Frame Type MdfFrmA(m)........................................Frame Attr MdfTyp(m)..........................................Type mask MdfWid(m)..........................................Bar width MdfOfs(m)........................................Text offset MdfWat(m)........................................Window attr MdfTat(m).....................................Text attribute MdfSat(m)...................................Select char attr MdfNat(m)....................................Non-select attr MdfBat(m)......................................Bar attribute MdfDat(m)............................Description/help attr*/ MdfFlg(m).....................................Internal flags MdfUsr(m)....................................User descriptor Page 20 TesSeRact CXL V5.52 Documentation _Idf Access Macros IdfPar(i)........................................Parent menu IdfSub(i).........................................Child menu IdfStr(i).....................................Selection text IdfTxt(i)...................................Description text IdfSel(i).................................."Select" function IdfBef(i).................................."Before" function IdfAft(i).................................."After" function IdfKey(i)............................................Hot key IdfTag(i).............................................Tag ID IdfHlp(i)...........................................Help tag IdfPos(i)...........................................Text pos IdfPosW(i)..............................................Word IdfPosC(i)...............................................Col IdfPosR(i)...............................................Row IdfChr(i)..................................Quick select char IdfMsk(i).......................................Feature mask IdfLen(i)........................................Text length IdfFlg(i).....................................Internal flags IdfUsr(i)....................................User descriptor MnuItm() item-feature mask ITM_NOR.......................Normal (none of the following) ITM_PUL..............................Pull-down menu attached ITM_NSL.......................................Not selectable ITM_AFT..............................Close menu after select ITM_ALL........................Close all menus when selected ITM_BEF.............................Close menu before select MnuEnd() menu type MNU_HOR...........................................Horizontal MNU_VER.............................................Vertical MNU_OMN......................................Omnidirectional MNU_PUL............................................Pull-down MNU_NQS..............................Disable quick selection MNU_SAV...............................Save last bar position MNU_DSP.......................Display if no selectable items MNU_USE............................Use current active window TesSeRact CXL V5.52 Documentation Page 21 Menu System Example /*========[ The TCXL Menu Demo, a simulated editor interface ]========* | Called from the [M]enuing item of the UserDemo.C main menu *--------------------------------------------------------------------*/ VOID CTYP MenuDemo(NOARG) { IntT s; IntT Lines; VcelFP VidArea; FlgT st; KbndIdle(UpdateClock); /* start clock display */ HlpPush(H_PULLDOWN); /* push help category */ _CerrPush(_IFFPCP(_AltCrit)); /* install alternate CritErr */ if(_VuvAct) /* draw editor display */ Lines = _VuvGet(); else Lines = VidDep; cvtic(&Rmargin[16], VidWid - 8, 3); VidArea = FarVsave(LGREY|_BLACK); st = CurSave(); /* save cursor-shown state */ redraw: /* come here to redraw the menu*/ if(atoi(&Rmargin[16]) > VidWid - 3) cvtic(&Rmargin[16], VidWid - 8, 3); DrawEditor(atoi(&Lmargin[16]), atoi(&Rmargin[16])); MnuDef(1, 1, 1, VidWid - 2, 5, /* start the menu */ CYAN, CYAN|_BLUE, NULL, 6); MnuItm(0, 2, "File", 'F', 19, /* define first item, */ ITM_PUL, NULL, 0, H_FILE); /* a pulldown menu */ MnuDef(2, 1, 11, 17, 0, LGREY|_BLUE, _BLUE, NULL, 8); MnuItm(0, 0, "Load", 'L', 20, 0, DoNothing, 0, H_LOAD); MnuItm(1, 0, "Save", 'S', 21, 0, DoNothing, 0, H_SAVE); MnuItm(2, 0, "Rename", 'R', 22, 0, DoNothing, 0, H_RENAME); MnuItm(3, 0, "New", 'N', 23, 0, DoNothing, 0, H_NEW); MnuItm(4, 0, "Directory F5", 'D', 24, 0, Directory, Key_F5, H_DIRECTORY); MnuItm(5, 0, "Execute F6", 'E', 25, 0, Execute, Key_F6, H_EXECUTE); MnuItm(6, 0, "OS Shell F7", 'O', 26, ITM_BEF, OsShell, Key_F7, H_OSSHELL); MnuItm(7, 0, "Quit", 'Q', 27, ITM_ALL, NULL, 0, H_QUIT); ItmFun(_VFVCP(QuitWindow), _VFVCP(QuitWindow)); MnuEnd(20, MNU_PUL|MNU_SAV, 15, 1, YELLOW|_BLUE, LCYAN|_BLUE, 0, YELLOW|_MAGENTA); Page 22 TesSeRact CXL V5.52 Documentation MnuItm(0, 15, "Editing", 'E', 28,/* second item, also a pulldown */ ITM_PUL, NULL, 0, H_EDITING); MnuDef(2, 14, 10, 28, 0, LGREY|_BLUE, _BLUE, NULL, 7); MnuItm(0, 0, "Cut", 'C', 29, 0, DoNothing, 0, H_NONE); MnuItm(1, 0, "Paste", 'P', 30, ITM_NSL, DoNothing, 0, H_NONE); MnuItm(2, 0, "cOpy", 'O', 31, ITM_NSL, DoNothing, 0, H_NONE); MnuItm(3, 0, "block Begin", 'B', 32, 0, ToggleBlock, 0, H_NONE); MnuItm(4, 0, "block End", 'E', 33, ITM_NSL, ToggleBlock, 0, H_NONE); MnuItm(5, 0, "Insert line", 'I', 34, 0, DoNothing, 0, H_NONE); MnuItm(6, 0, "Delete line", 'D', 35, 0, DoNothing, 0, H_NONE); MnuEnd(29, MNU_PUL|MNU_SAV, 13, 1, YELLOW|_BLUE, LCYAN|_BLUE, CYAN|_BLUE, YELLOW|_MAGENTA); MnuItm(0, 31, "Defaults", 'D', 36,/* third item, also a pulldown */ ITM_PUL, NULL, 0, H_DEFAULTS); MnuDef(2, 30, 13, 52, 0, LGREY|_BLUE, _BLUE, _VFVCP(SetupMenu), 8); MnuItm(0, 0, Lmargin, 'L', 37, ITM_ALL, RMargin, 0, H_NONE); MnuItm(1, 0, Rmargin, 'R', 38, ITM_ALL, RMargin, 0, H_NONE); MnuItm(2, 0, "Tab width 4", 'T', 39, 0, DoNothing, 0, H_NONE); MnuItm(4, 0, "tab eXpansion yes", 'X', 40, 0, ToggleYN, 0, H_NONE); MnuItm(5, 0, "Insert mode yes", 'I', 41, 0, ToggleYN, 0, H_NONE); MnuItm(6, 0, "iNdent mode yes", 'N', 42, 0, ToggleYN, 0, H_NONE); MnuItm(7, 0, "Word wrap mode no", 'W', 43, 0, ToggleYN, 0, H_NONE); MnuItm(9, 0, "Save defaults", 'S', 44, 0, DoNothing, 0, H_NONE); MnuEnd(37, MNU_PUL|MNU_SAV, 21, 1, YELLOW|_BLUE, LCYAN|_BLUE, 0, YELLOW|_MAGENTA); MnuItm(0, 47, "Run", 'R', 45, 0,/* fourth item, a popup menu */ _VFVCP(PopupDemo), 0, H_RUN); MnuItm(0, 59, "Options", 'O', 46,/* fifth item, another pulldown */ ITM_PUL, NULL, 0, H_OPTIONS); MnuDef(2, 56, 8, 77, 0, LGREY|_BLUE, _BLUE, NULL, 5); MnuItm(0, 0, "screen siZe", 'Z', 47, ITM_ALL, ChangeSize, 0, H_NONE); MnuItm(1, 0, "Backup files yes", 'B', 48, 0, ToggleYN, 0, H_NONE); MnuItm(2, 0, "bOxed display no", 'O', 49, 0, ToggleYN, 0, H_NONE); MnuItm(3, 0, "Load options", 'L', 50, 0, DoNothing, 0, H_NONE); MnuItm(4, 0, "Save options", 'S', 51, 0, DoNothing, 0, TesSeRact CXL V5.52 Documentation Page 23 H_NONE); MnuEnd(47, MNU_PUL|MNU_SAV, 20, 1, YELLOW|_BLUE, LCYAN|_BLUE, 0, YELLOW|_MAGENTA); MnuItm(0, 73, "Quit", 'Q', 52,/* sixth item, a pulldown with */ ITM_PUL, NULL, 0, H_NONE);/* an automatic popup window */ ItmFun(_VFVCP(QuitWindow), _VFVCP(QuitWindow)); MnuDef(2, 60, 7, 78, 0, LGREY|_BLUE, _BLUE, DispSureMsg, 2); MnuItm(2, 0, "No", 'N', 53, ITM_AFT, NULL, 0, H_NONE); MnuItm(3, 0, "Yes", 'Y', 54, ITM_ALL, NULL, 0, H_NONE); MnuEnd(53, MNU_PUL, 17, 7, YELLOW|_BLUE, LCYAN|_BLUE, WHITE|_BLUE, YELLOW|_MAGENTA); MnuEnd(19, MNU_HOR, 0, 0, /* define the end of the menu */ YELLOW|_BLUE, LCYAN|_BLUE, 0, YELLOW|_MAGENTA); s = MnuGet(); /* process the menu */ if(s == -1 && TcxlErr > W_ESCPRESS) ErrorExit(1); /* windowing error! */ Wclose(); /* close up windows */ Wclose(); if((s == 37) || (s == 38) || (s == 47) || (s >= 100)) goto redraw; if(_VuvAct) /* Ultravision */ { if(Lines != _VuvGet()) _VuvSet(Lines); } else /* ordinary BIOS */ { if(Lines != VidDep) VsetLin(Lines); } CurRest(st); /* restore cursor-shown state */ FarVrestore(VidArea); /* restore screen */ KbndIdle(NULL); /* kill the clock */ HlpDrop(); /* pop the help stack */ _CerrPop(); /* restore CritErr-handler */ MoveBarDn(); /* select next main-menu item */ } /* MenuDemo() */ Page 24 TesSeRact CXL V5.52 Documentation Menu System Routines Menu and Item Definition --------------------------------------------------------------------------- MnuBuild Synopsis........Build complete menu tree from defining set of Mbld and Ibld objects. Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuBuild(MbldP mp); Source File.....MNU\MNUBUILD.C Arguments.......mp - Pointer to Top Mbld structure. The Mbld and Ibld structures are organized based on the parameters used by MnuDef(), MnuItm(), ItmTxt() ItmFun() and MnuEnd(). For complete descriptions of these structures, and a detailed example of the way they can be used, see INC\TCXLmnu.h and DEMO\MENUDEMO.C. Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOITMDEF - No Menu Items Defined W_NOMNUBEG - No Menu Definition. W_INVTAGID - The specified Tag ID was invalid. It must match one of the Tag IDs in the current menu. W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........It is VERY important to check the return value from MnuBuild(); if any of the nested function calls fail, MnuBuild() will return an error to the caller. Calling MnuGet() at that point could be disastrous! TesSeRact CXL V5.52 Documentation Page 25 --------------------------------------------------------------------------- MnuAct Synopsis........Begin menu definition, using active window. Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuAct(IntT ni); Source File.....MNU\MNUACT.C Arguments.......ni - Number of items in menu Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOITMDEF - No Menu Items Defined Notes...........This is used in place of MnuDef(). This function differs from MnuDef() in that when the user processes the defined menu, the menu will assume whatever the active window is at the time. This (or MnuDef()) is one of the 4 functions that are required to process a menu. Page 26 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- MnuDef Synopsis........Begin menu definition, describe menu window. Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuDef(IntT sr, IntT sc, IntT er, IntT ec, BytT ft, AtrT fa, AtrT wa, VfvCP fo, IntT ni); Source File.....MNU\MNUDEF.C Arguments.......sr - Start row of menu's window sc - Start column of menu's window er - End row of menu's window ec - End column of menu's window ft - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Frame Attribute (See Appendix A) wa - Window Attribute (See Appendix A) fo - Function to be called when the menu's window is opened. An example would be to add a title, a shadow, etc. ni - Number of items in the menu Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOITMDEF - No Menu Items Defined Notes...........This function does not actually open any windows or menus, just defines them. This must be used in conjunction with MnuItm() and MnuEnd(). This (or MnuAct()) is one of the 4 functions that are required to process a menu. TesSeRact CXL V5.52 Documentation Page 27 --------------------------------------------------------------------------- MnuItm Synopsis........Defines a menu item Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuItm(BytT wr, BytT wc, ChrP ps, ChrT sc, TagT id, BytT fm, VfvCP fs, KeyT kc, TagT ht); File............MNU\MNUITM.C Arguments.......wr - Window Row wc - Window Column ps - Menu Item String sc - Quick Selection character. This is often the first letter of the menu item. id - Unique tag identifier for this menu item. A menu tag id may be assigned arbitrarily by the programmer, but some kind of design system should be implemented -- and may, in fact, be similar to the help tags. See the demonstration program for one implementation. fm - Feature Masks (Page 21) fs - Function to call when item is selected kc - Keycode of the key which will select this item from anywhere within the menu structure (See Appendix B for a list of keycodes). This allows the user to call this menu's select function even if not currently processing its menu. ht - Help Tag for this item Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOMNUBEG - No Menu Definition. See MnuDef() Notes...........This is one of the 4 functions that are required to process a menu. Page 28 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- MnuEnd Synopsis........Ends a menu definition Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuEnd(TagT id, BytT mt, BytT bw, BytT tp, AtrT ta, AtrT sa, AtrT na, AtrT ba); Source File.....MNU\MNUEND.C Arguments.......ti - Tag ID of the item the selection bar will start with mt - Menu Type (Page 21) bw - Width of the section bar (zero means selection string width) tp - Offset position from start of the selection bar that the menu item text will start. ta - Attribute for menu text (See Appendix A) sa - Attribute for Selection Character (See Appendix A) na - Attribute for non-selectable text (See Appendix A) ba - Attribute for the selection bar (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOITMDEF - No Menu Items Defined W_INVTAGID - The specified Tag ID was invalid. It must match one of the Tag IDs in the current menu. Notes...........This function defines specific features/attributes of that menu. This is one of the 4 functions that are required to process a menu. The Menu Type <mt> parameter is composed of a combination of: one of MNU_HOR (horizontal), MNU_VER (vertical) or MNU_OMN (omnidirectional -- both horizontal and vertical); plus one or more of MNU_PUL (pull-down), MNU_NQS (no quick- select) and/or MNU_SAV (save bar-position). If MNU_DSP is also used, a menu with no selectable items will be displayed without processing until [Esc] or a parent-menu hot-key is pressed. On horizontal menus, the <bw> parameter is the selection bar width, and <tp> is the offset from each item's position to it's selection text. If <bw> is zero, the bar width is set to the length of the item. On vertical menus, the selection bar width is the width of the menu window inside any frame, and <bw> is ignored. <tp> is still the offset from each item's position to its selection text. TesSeRact CXL V5.52 Documentation Page 29 --------------------------------------------------------------------------- MnuTxt Synopsis........Define text descriptions for current menu. Header File.....TCXLmnu.h Prototype.......IntT CTYP MnuTxt(BytT wr, BytT wc, AtrT at); Source File.....MNU\MNUTXT.C Arguments.......wr - Window Row for descriptions wc - Window Column for descriptions at - Attribute for display (see Appendix A). Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined Notes...........This function is new with TCXL 5.52, reducing the overhead of calling ItmTxt() several times with identical parameters. Page 30 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- ItmFun Synopsis........Assign before/after functions to current item. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmFun(VFvCP bf, VFvCP af); Source File.....MNU\ITMFUN.C Arguments.......bf - Before Function (NULL if not used) af - After Function (NULL if not used) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOITMDEF - No Menu Items Defined Notes...........The call to this function must appear immediately after the call to the MnuItm() 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 ItmFun() is to define a before function that opens a window and writes some text in it, and an after function which closes that window (there is an example of this in the demonstration program). 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. TesSeRact CXL V5.52 Documentation Page 31 --------------------------------------------------------------------------- ItmTxt Synopsis........Assign text description to menu item. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmTxt(ChrP ps); Source File.....MNU\ITMTXT.C Arguments.......ps - string to display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........This function was designed primarily to permit the easy implementation of Lotus-style menus, where the text descriptions are displayed underneath the menu and change each time the user moves to a new menu item. Note this is a changed prototype from TCXL 5.51. Page 32 TesSeRact CXL V5.52 Documentation Menu Operation --------------------------------------------------------------------------- MnuGet Synopsis........Processes the menu structure. Header File.....TCXLmnu.h Prototype.......TagT CTYP MnuGet(NOARG); Source File.....MNU\MNUGET.C Arguments.......None Returns.........The Tag ID of the menu item that was selected. ERR_NUL - Check TcxlErr for W_ESCPRESS! ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOMNUEND - No End Of Menu Specified. See MnuEnd(). W_ESCPRESS - The [Esc] Key Was Pressed From The Root Menu W_INVCOORD - Invalid Coordinates W_INVBTYPE - Invalid Border Type Notes...........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. --------------------------------------------------------------------------- MnuCur Synopsis........Current Menu Object Pointer Header File.....TCXLmnu.h Prototype.......MdfP MnuCur(NOARG); Arguments.......None Returns.........The address of the current menu's record. Notes...........Returns the address of the currently active menu's record. After this call, you may access any of the menu's elements. 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. TesSeRact CXL V5.52 Documentation Page 33 --------------------------------------------------------------------------- ItmCur Synopsis........Current Menu Item Object Pointer Header File.....TCXLmnu.h Prototype.......IdfP ItmCur(NOARG); Arguments.......None Returns.........The address of the current menu item's record. Notes...........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. --------------------------------------------------------------------------- ItmLoc Synopsis........Find Item Object referenced by passed tag. Header File.....TCXLmnu.h Prototype.......IdfP CTYP ItmLoc(TagT id); Source File.....MNU\ITMLOC.C Arguments.......id - The Tag ID of the menu item Returns.........The address of the item referenced NULL if not found --------------------------------------------------------------------------- ItmNxt Synopsis........Choose next selected item in menu. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmNxt(TagT id); Source File.....MNU\ITMNXT.C Arguments.......id - The Tag ID of the menu item Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........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. Page 34 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- ItmDsp Synopsis........Flag item for redisplay. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmDsp(TagT id); Source File.....MNU\ITMDSP.C Arguments.......id - The Tag ID of the menu item Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........Normally, this would be needed if you have changed the text, etc. All menu items in the current menu structure are checked for the redisplay flag each time a user selects an item. --------------------------------------------------------------------------- ItmDis Synopsis........Disables a menu item. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmDis(TagT id); Source File.....MNU\ITMDIS.C Arguments.......id - The Tag ID of the menu item Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........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 (See Appendix A) defined for nonselectable text. TesSeRact CXL V5.52 Documentation Page 35 --------------------------------------------------------------------------- ItmEna Synopsis........Enables a menu item. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmEna(TagT id); Source File.....MNU\ITMENA.C Arguments.......id - The Tag ID of the menu item Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........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 (See Appendix A) defined for selectable text. --------------------------------------------------------------------------- ItmGet Synopsis........Get selection text for specified tag. Header File.....TCXLmnu.h Prototype.......ChrP CTYP ItmGet(TagT id); Source File.....MNU\ITMGET.C Arguments.......id - The Tag ID of the menu item Returns.........The address of the item's selection text. NULL if not found Notes...........This function returns a pointer to the text referenced by the specified Tag. Page 36 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- ItmSet Synopsis........Change text of menu item. Header File.....TCXLmnu.h Prototype.......IntT CTYP ItmSet(TagT id, ChrP tp, FlgT df); Source File.....MNU\ITMSET.C Arguments.......id - The Tag ID of the menu item tp - Pointer to the new text df - redisplay item if TRUE Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOMNUDEF - No Menu Defined W_NOTFOUND - Tag ID Not Found Notes...........This function changes the text associated with the specified menu item, referenced by the passed Tag. Set the redisplay flag if <df> is TRUE. Menu Internals --------------------------------------------------------------------------- _ItmKey (Internal) Synopsis........Search back along menu structure for passed hotkey. Header File.....TCXLmnu.h Prototype.......IdfP CTYP _ItmKey(KeyT kc); --------------------------------------------------------------------------- _ItmPtr (Internal) Synopsis........Search back along menu structure for item with passed Tag ID. Header File.....TCXLmnu.h Prototype.......Idfp CTYP _ItmPtr(TagT id); --------------------------------------------------------------------------- _ItmPut (Internal) Synopsis........Display menu-item anywhere within current menu structure; use selection bar if <b> is true. Header File.....TCXLmnu.h Prototype.......VOID CTYP _ItmPut(IdfP ip, FlgT hb); TesSeRact CXL V5.52 Documentation Page 37 Entry System Using TCXL's multi-field Entry System is very similar to designing menus. There are certain functions associated with building an entry form, and they must be called in a particular order. The basic format (and again, all optional calls are in brackets) of all form structures is: EntDef EntFld [FldKey] [FldFun] EntFld [FldKey] [FldFun] ... [EntDis] [EntKey] [EntOpt] [EntSep] EntGet Just three functions are needed to process multi-field formatted input from windows. EntDef() is used to mark the beginning of the form; EntFld() is used to define the individual data entry fields, and EntGet() marks the end of the form and initiates user processing of the form. FldKey() and FldFun() are optional functions. FldKey() assigns a hotkey to the active field, while FldFun() allows you to add specific procedures to be called before and/or after processing of the field. If you use either of these two functions, they must immediately follow the call to FldDef() to which they pertain. Change from Previous Version!! The formatted input capabilities of the Entry System are identical to those of the KvGetFmt() and KwGetFmt() functions in the Input System. In fact, different from previous versions of this product, they use the same internal functions for operation. The major difference is that with the Entry System, you can edit back and forth between fields before finally accepting the entry form. Note that the Format Control Codes in Appendix D are valid (except where noted) with both the Input System and the Entry System. Beginning with Version 5.52, you may also use a new function, EntBuild() (Page 47), to create your entry forms. This function, described in more detail below and in the demonstration programs, can be used to build an entire entry form with one function call. All of the necessary information is stored in data structures, which makes for easier programmer's documentation, as well as easier maintenance. Page 38 TesSeRact CXL V5.52 Documentation In the Entry System, you may set a validation function for each field on the form. During processing, EntGet() will call this function after you leave the field to validate the information input.. You can use this function for validating, modifying, displaying error messages, or just about anything. This function must 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 the validation function returns non-zero, EntGet() forces the user to remain within the field and edit the incorrect information. Here's an example field validation function that checks for embedded spaces: IntT CTYP check_for_spaces(ChrP input_field) { IntT current_position = 1, error_position = 0; while(*input_field++ != ' ') /* search for end of text */ current_position++; while(*input_field == ' ') /* search to end of field for */ { /* non-space characters */ current_position++; input_field++; } if(*input_field!='\0') /* if at end of field, then */ error_position = current_position; /* field is invalid */ return(error_position); } Once you have defined all input fields with EntDef(), you call EntGet() 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. In addition, if you specify a "hotkey" to an Entry Field using FldKey(), you may also move directly to a particular field whenever that hotkey is pressed. Please note that mouse support is automatically activated during entry form processing, if a mouse has been detected during initialization. Clicking the mouse on that field will automatically move the cursor to that field for input. After the EntGet() function returns, all fields defined with EntDef() 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 EntGet() was called and TcxlErr will return W_ESCPRESS. TesSeRact CXL V5.52 Documentation Page 39 Sometimes, you may have a need to extend or modify the data entry keys used by EntGet() during processing of the fields. There is a function, EntKey(), that enables this. What EntKey() does is defines a function to be used as the alternate get-key function so that during EntGet() processing you can get a key, test it, change it, or do whatever else you like with it before you return it to EntGet(). It also lets you to specify a variable to receive the key that caused termination of the form. The call to EntKey() can be contained anywhere between EntDef() and EntGet(). Often, when dealing with database records, users would like to have [PgUp] mean previous record and [PgDn] mean next record. Let's also say 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: KeyT CTYP get_key(NOARG) { KeyT key; key=KeyGetc(); /* if key was [F10], change it to [Ctrl-Enter] */ if(key == Key_F10) { key= Key_C_Ent; EntTrm(Key_F10); } /* if key was [PgUp] or [PgDn], push key, return */ if(key == Key_PgUp || key == Key_PgDn) { KquePut(key); EntTrm(key); key = Key_C_Ent; } return(key); } Note here that we call the EntTrm() (See Page (?)) macro to pass back the actual key to the function that called EntGet. This key is returned in the pointer passed with you originally called EntGet. Multiple records with identical layouts may be "browsed", once EntDef(), EntFld() and EntDsp() have been initially called by updating the contents of the FdfStr(), etc., elements of the Fdf Field-definition objects and again calling EntDsp() for each new record. However, either EntFree() or EntGet() MUST be called to dispose of the form. If EntSav() is called BEFORE calling EntGet() for an entry form, the form will be preserved (not disposed of) and can then be reused for multiple records. EntFree() MUST then be called to dispose of the form after EntGet() returns. Page 40 TesSeRact CXL V5.52 Documentation The <fm> feature-mask argument to EntFld() is an ORed combination of the FLD_NUL ... FLD_DIS constants defined here. These special cases apply: If FLD_DIS (input disabled) is set, at least ONE field must be enabled. Obviously both FLD_DIS and FLD_REQ cannot be set for a field. FLD_REQ takes precedence and will override FLD_DIS as an initial setting. If a disabled field is made required by calling FldReq(), it will also be enabled. If FLD_REQ (input required) is set, the user will not be able to exit the form until the field is entered and validated. If a required field is disabled by calling FldDis(), it will also no longer be a required field (see above). If FLD_SUB (nested child form) is set, a user "before" function for the child form MUST be defined via a call to FldFun() following the EntFld() call for the parent field. Up to ENT_MAX (currently 8) levels of child forms can be nested. To define, display and process a child form, define a user "before" function for the parent field with FldFun(), that, at a minimum, performs the following sequence of calls before returning to EntGet() to resume processing of the parent field and form: EntPush() to preserve the parent form. Wopen() to define and open the child's window. EntDef() and EntFld(), etc., to define the child form and its component fields and make it current. EntGet() to display, process and dispose of the child form -OR- EntDsp() to display and EntFree() to dispose of the child form without processing. Wclose() to close the child's window. EntPop() to restore the parent form and make it current. After EntPop() returns, the parent field can be filled in or other appropriate action taken before returning to EntGet(). If the parent field is changed, FldChg() MUST be called to signal the change to EntGet(). The global EctlCur pointer and EntCur() are valid and the data objects exist ONLY when a current entry-form is defined (i.e., after EntDef() is called and before EntGet() or EntFree() returns). Between EntPush() and EntDef() calls for a child form, NO current form is defined and EctlCur is NULL! EntGet() disposes of the current form and frees all of its data objects before returning (unless EntSav() has been called) so there is NO current entry-form defined and EctlCur is NULL! The field-movement bits in FdfFlg(f) are ONLY valid within a user "before", "valid" or "after" function called by EntGet(). NO bits are set if a field is selected by the mouse in other than MOU_KEYS mode. When we describe these flags as "transient", we mean that the values they contain will be constantly changing during input. A similar usage is the ANSI "volatile" keyword, which means that the variables can change without notice, but accurately indicate the current state. TesSeRact CXL V5.52 Documentation Page 41 Using Format Control Characters The format control characters used by the Entry System and the Input System controls how each character is input and how large the input field will be. It consists of 1 or more format characters, and may optionally have displayed text in between any of the format control characters. You may use spaces in between the format control characters for readability of your code; however, these spaces will NOT be used for input. A complete list of valid format control characters are listed in Appendix D (case IS significant). All Format Control Characters are valid in both the Entry System and the Input System, including command toggles. In a change from previous versions of this product, decimal points are returned as part of the TCXL field string, when using the '9' or '$' control codes. Therefore, the numeric conversion routines cvt..(), have been changed to account for this. There are 4 conversion functions to convert numbers to/from TCXL fields (Page 150): cvtic().................convert integer to TCXL field string cvtci().................convert TCXL field string to integer cvtfc()..........convert floating point to TCXL field string cvtcf()..........convert TCXL field string to floating point To correctly use numeric fields, you must first convert your number to a TCXL field string with cvtic() or cvtfc(), and on return from the entry form, you should convert the result back to the correct type of number. Also, please note that decimal fields are now available in both the Entry System and the Input System. Page 42 TesSeRact CXL V5.52 Documentation Entry System Equates _Ectl Access Macros EctlCur...................................Current entry-form EctlStk(i)..................................Entry-form stack EctlLvl.....................................Entry-form level EctlTag..................................Current field TagId _Edf Access Macros EdfTop.......................................Field-list head EdfFld(i).................................Field-list element EdfBot.......................................Field-list tail EdfCur.........................................Current field EdfGet.........................................User getkey() EdfTrm..................................User last-key buffer EdfBfr...........................................Buffer-pool EdfPos...................................Field-position list EdfLen.....................................Field-length list EdfCnt...........................................Field-count EdfOrg...................................Window image origin EdfOrgW.................................................Word EdfCol...................................................Col EdfRow...................................................Row EdfCtl.........................................Control flags EdfFat.......................................Field attribute EdfHat...................................Highlight attribute EdfDat....................................Disabled attribute EdfUsr.......................................User descriptor _Fdf Access Macros FdfStr(f).......................................Input string FdfBfr(f).....................................Buffer pointer FdfFmt(f)......................................Format string FdfVal(f)..................................."Valid" function FdfBef(f).................................."Before" function FdfAft(f).................................."After" function FdfKey(f).............................................Hotkey FdfTag(f)........................................Field TagId FdfHlp(f).........................................Help TagId FdfPos(f)....................................Window position FdfPosW(f)..............................................Word FdfCol(f)................................................Col FdfRow(f)................................................Row FdfOpt(f).................................Format option bits FdfUse(f)..................................Format usage bits FdfCtl(f)................................Field-control flags FdfFlg(f)....................................Transient flags FdfLen(f).......................................Field length FdfExt(f).......................................Input extent FdfDot(f).....................................Decimal offset FdfUsr(f)....................................User descriptor TesSeRact CXL V5.52 Documentation Page 43 EntFld() <fm> feature-mask bits FLD_NUL..........................No special features defined FLD_LWR...........................Convert input to lowercase FLD_MIX..........................Convert input to mixed case FLD_UPR...........................Convert input to uppercase FLD_PAS................................Password - no display FLD_DEC........................................Decimal field FLD_CUR.......................................Currency field FLD_NWR...........................No auto-wrap to next field FLD_LJS..................................Left justify result FLD_RJS.................................Right justify result FLD_TRM..........................Trim end spaces from result FLD_SUB....................................Nested child form FLD_REQ.......................................Input required FLD_DIS.......................................Input disabled EntFld() <md> field edit-modes FLD_INI......................Initial - clear field for input FLD_CHG......................Change - display field for edit FLD_CND...................................Conditional-update Transient FdfFlg(f) flags FDF_MOV........................................Movement mask FDF_BEG.......................................To first field FDF_END........................................To last field FDF_PRV....................................To previous field FDF_NXT........................................To next field FDF_UP.................................Upward [if EdfDir ON] FDF_DWN..............................Downward [if EdfDir ON] Page 44 TesSeRact CXL V5.52 Documentation Entry System Example /*=======================[ The TCXL Entry Demo ]======================* | Called from the [E]ntry item of the UserDemo.C main menu *--------------------------------------------------------------------*/ VOID CTYP EntryDemo(NOARG) { REG IntT c, p = 0, i; KeyT k; VcelFP s; BytT m = 0; s = FarVsave(LGREY|_BLUE); /* save screen */ if(!WpopUp(CNT_CNT, 2, 8, 23, 70, 1, LCYAN|_BLUE, LCYAN|_BLUE)) ErrorExit(1); /* windowing error! */ AddShadow(); /* add shadow, title, notes */ Wtitle("[ TCXL Order Form ]", TTL_LFT, LCYAN|_BLUE); Wmessage("[ $50 Plus $3 S&H ]", BRD_TOP, 42, LCYAN|_BLUE); Wmessage(" [F10]=Finished ", BRD_BOT, 5, LCYAN|_BLUE); Wmessage(" [F9]=Today ", BRD_BOT, 25, LCYAN|_BLUE); Wmessage(" [Esc]=Abort ", BRD_BOT, 45, LCYAN|_BLUE); HlpPush(H_EDITKEYS); /* set help category */ do { EntDef(BLUE|_LGREY, WHITE|_LGREY,/* define the form */ DEMO_CNT); Wprts( 1, 3, WHITE|_BLUE, "Date");/* prompts and fields */ EntFld( 1, 16, date, "<01>#'/'<0123>#'/'##", FLD_NUL, 1, m, CheckDate, H_DATE); FldFun(NULL, DisplayDate);/* "before"/"after" functions */ FldKey(Key_A_D); /* hot-key */ Wprts( 3, 3, WHITE|_BLUE, "First Name"); EntFld( 3, 16, firstname, "MMMMMMMMMMMMMMM", FLD_NUL, 2, m, NULL, H_FIRSTNAME); FldKey(Key_A_F); Wprts( 3, 37, WHITE|_BLUE, "Initial"); EntFld( 3, 47, initial, "U'.'", FLD_NUL, 3, m, NULL, H_INITIAL); FldKey(Key_A_I); Wprts( 5, 3, WHITE|_BLUE, "Last Name"); EntFld( 5, 16, lastname, "MMMMMMMMMMMMMMMMMMMMMMMMM", FLD_NUL, 4, m, NULL, H_LASTNAME); FldKey(Key_A_L); Wprts( 7, 3, WHITE|_BLUE, "Company"); EntFld( 7, 16, company, "****************************************", FLD_MIX, 5, m, NULL, H_NONE); FldKey(Key_A_O); Wprts( 9, 3, WHITE|_BLUE, "Address"); EntFld( 9, 16, address, "****************************************", FLD_MIX, 6, m, NULL, H_NONE); FldKey(Key_A_A); Wprts(11, 3, WHITE|_BLUE, "City"); EntFld(11, 16, city, "MMMMMMMMMMMMMMMMMMMM", FLD_NUL, 7, m, NULL, H_CITY); TesSeRact CXL V5.52 Documentation Page 45 FldKey(Key_A_C); Wprts(11, 41, WHITE|_BLUE, "State"); EntFld(11, 50, state, "UU", FLD_NUL, 8, m, NULL, H_STATE); FldKey(Key_A_S); Wprts(13, 3, WHITE|_BLUE, "Zip Code"); EntFld(13, 16, zipcode, "#####'-'%%%%", FLD_NUL, 9, m, NULL, H_ZIPCODE); FldKey(Key_A_Z); Wprts(13, 31, WHITE|_BLUE, "Phone"); EntFld(13, 40, phone, "'('###') '###'-'####", FLD_NWR, 10, m, NULL, H_NONE); FldKey(Key_A_P); Wprts(15, 3, WHITE|_BLUE, "Compiler"); EntFld(15, 16, compiler, "***************", FLD_MIX, 11, m, NULL, H_COMPILER); FldFun(PickCompiler, NULL); FldKey(Key_A_O); Wprts(15, 37, WHITE|_BLUE, "Amount"); EntFld(15, 46, amtenc, "$$$$.$$", FLD_CUR, 12, m, NULL, H_AMOUNT); FldKey(Key_A_M); Wprts(17, 3, WHITE|_BLUE, "Comments"); EntFld(17, 16, comments, "***********************************\n" "***********************************", FLD_NUL, 13, m, NULL, H_NONE); FldKey(Key_A_N); EntKey(_KFVCP(GetKey), &k);/* alternate kbd get function */ if(0 >= EntGet(DmFld[0].Ftag))/* process the form. If [Esc] */ break; /* was pressed, don't bother */ /* with confirmation message. */ if(!WpopUp(CNT_CNT, 9, 20, 13, 64, 0, WHITE|_CYAN, WHITE|_CYAN)) ErrorExit(1); /* windowing error! */ if(k != Key_F10) /* if [F10] was pressed, don't */ { /* display confirmation message. */ AddShadow(); Wputc('\n'); /* Display confirmation message */ WputCen("Is this information correct? \033A\076Y\b"); KeyClear(); c = KwGetYn('Y'); } else c = 'Y'; if(c == 'Y') /* ask to print order */ { Wclear(); Wputc('\n'); WputCen("Would you like your order printed? \033A\076Y\b"); KeyClear(); p = KwGetYn('Y'); } Wclose(); if(p == 'Y') PrintOrder(); m = 1; /* Change to "update" mode */ } while(c != 'Y'); Page 46 TesSeRact CXL V5.52 Documentation HlpDrop(); /* clear help */ Wclose(); /* close window */ FarVrestore(s); /* restore screen, cursor */ CurHide(); MoveBarDn(); /* next selection on main menu */ } /* EntrDemo */ Entry System Routines Form and Field Definition --------------------------------------------------------------------------- EntBuild Synopsis........Build Data Entry Form from defining set of Ebld and Fbld objects. Header File.....TCXLent.h Prototype.......IntT CTYP EntBuild(EbldP ep); Source File.....ENT\ENTBUILD.C Arguments.......ep - Pointer to top Ebld structure. The Ebld structure is organized based on the parameters used by EntDef(), EntFld(), FldKey(), and FldFun(). For complete descriptions of these structures, and a detailed example of they way they can be used, see INC\TCXLent.h and DEMO\ENTRDEMO.C. Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOACTIVE - No Active Window W_NOFRMBEG - No Begin Of Form Specified, see EntDef() W_INVCOORD - Invalid Coordinates W_INVFORMT - Invalid Format String W_NOINPDEF - No Input Fields Defined Notes...........It is VERY important to check the return value from EntBuild()! TesSeRact CXL V5.52 Documentation Page 47 --------------------------------------------------------------------------- EntDef Synopsis Begin entry form definition. Header File.....TCXLent.h Prototype.......IntT CTYP EntDef(AtrT fa, AtrT ta, IntT nf); Source File.....ENT\ENTDEF.C Arguments.......fa - Field Attribute (See Appendix A) ta - Highlight Attribute (See Appendix A) nf - Number of fields Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Error TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Marks the beginning of a data input form, and specifies text attributes to be used by the form. The Field Attribute is used to display the entry fields themselves, while the Highlight Attribute is used to display the characters within the current field. --------------------------------------------------------------------------- EntFld Synopsis........Defines a window input field. Header File.....TCXLent.h Prototype.......IntT CTYP EntFld(BytT wr, BytT wc, ChrP ps, ChrP fs, WrdT fm, TagT id, BytT im, IfcpCP fv, TagT ht); Source File.....ENT\ENTFLD.C Arguments.......wr - Window Row for Start of Input wc - Window Column for Start of Input ps - String buffer to receive input fs - Field Format String (See Appendix D) fm - Feature Mask (Page 44) id - Tag Identifier for field im - Input Mode (Page 44) fv - Validate Function ht - Help Tag for this field Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Error TcxlErr contains: W_NOFRMBEG - No Begin Of Form Specified, see EntDef() W_INVCOORD - Invalid Coordinates W_INVFORMT - Invalid Format String Page 48 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- EntDis Synopsis........Assign disabled field attribute for current form. Header File.....TCXLent.h Prototype.......IntT CTYP EntDis(AtrT ds); Source File.....ENT\ENTDIS.C Arguments.......ds - Attribute to use when field is disabled. (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOFRMBEG - No Begin Of Form Specified, see EntDef() Notes...........The disabled attribute defaults to the normal field attribute. --------------------------------------------------------------------------- EntKey Synopsis........Assign alternate keyboard support. Header File.....TCXLent.h Prototype.......IntT CTYP EntKey(KfvCP gk, KeyP tk); Source File.....ENT\ENTKEY.C Arguments.......gk - Alternate getkey() function tk - Pointer to location to store termination key Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Form W_NOFRMBEG - No Begin Of Form Specified Notes...........Allows you to extend or modify the data entry keys used as the alternate get-key function so that during EntGet() processing you can get a key, test it, change it, or do whatever else you like with it before you return it to EntGet(). It also lets you specify a variable to receive the key that caused termination of the form. The call to EntKey() can be contained anywhere between EntDef() and EntGet(). TesSeRact CXL V5.52 Documentation Page 49 --------------------------------------------------------------------------- EntOpt Synopsis........Set global entry form options. Header File.....TCXLent.h Prototype.......IntT CTYP EntOpt(FlgT gi, FlgT ud); Source File.....ENT\ENTOPT.C Arguments.......gi - Global Insert Mode Enable ud - Global [Up]/[Down] Key Enable Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOFRMBEG - No Begin Of Form Specified Notes...........If <gi> is TRUE, all entry fields will have INSert mode turned on on entry to the field. In the default mode of FALSE, INSert mode is specifically turned OFF on entry to each field. If <ud> is TRUE, Up/Down arrows move the cursor to the field physically above/below the current field; if FALSE (the default), [Up] translates to [BackTab], while [Down] translates to [Tab]. --------------------------------------------------------------------------- EntSep Synopsis........Assign word-separator string Header File.....TCXLent.h Prototype.......VOID EntSep(ChrP ws); Arguments.......ws - New separation string Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOFRMBEG - No Form Defined Notes...........This function declares a new "word separation" string. The TCXL library has a built-in definition of the characters that will mark the end of a "word": ChrP _FmtSep = " ~`!@#$%^&*()-+=|\\[]{}:;'\",./<>?"; If your application requires a different separator string, you would call this function. Page 50 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- EntTrm Synopsis........Store alternate getkey termination keystroke. Header File.....INC\TCXLENT.H Prototype.......VOID EntTrm(KeyT kc); Macro...........#define EntTrm(kc) (*(EctlCur->etrm) = (kc)) Arguments.......kc - Termination Key Returns.........None. Notes...........See EntKey() for details on setting an alternate key handler. When a user-defined exit key is detected, call EntTrm() to store it in the last-key buffer, and return Key_C_Ent to signal an exit from the form. --------------------------------------------------------------------------- FldKey Synopsis........Assign user hotkey to current entry field. Header File.....TCXLent.h Prototype.......IntT CTYP FldKey(KeyT hk); Source File.....ENT\FLDKEY.C Arguments.......hk - Hotkey for field Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_NOINPDEF - No Input Fields Defined Notes...........This function assigns a "hot key" to the individual data entry field. The call to this function must appear immediately after the call to the EntFld() to which it relates. During user input, when the user enters the field, the before function gets called. TesSeRact CXL V5.52 Documentation Page 51 --------------------------------------------------------------------------- FldFun Synopsis........Assign before/after functions to current entry field. Header File.....TCXLent.h Prototype.......IntT CTYP FldFun(VfvCP bf, VfvCP af); Source File.....ENT\FLDFUN.C Arguments.......bf - Before function af - After function Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_NOINPDEF - No Input Fields Defined Notes...........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 EntFld() 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. Entry Form Processing --------------------------------------------------------------------------- EntGet Synopsis........Processes Entry Form Header File.....TCXLent.h Prototype.......TagT CTYP EntGet(TagT id); Source File.....ENT\ENTGET.C Arguments.......id - Start Field Returns.........Current field Tag ID; or ERR_ARG - Argument Failure TcxlErr contains: W_ESCPRESS - Escape key pressed W_NOACTIVE - No Active Window W_NOINPDEF - No Input Fields Defined Notes...........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. Page 52 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- EntCur Synopsis........Current Entry Form Object Header File.....TCXLent.h Prototype.......EdfP EntCur(NOARG); Arguments.......None Returns.........The address of the current form's record. Notes...........Returns the address of the currently active form's record. After this call, you may access any of the form's elements. Use caution when updating elements in the form's record. This function should only be called while the form to which it relates is being processed. --------------------------------------------------------------------------- EntDsp Synopsis........Display all fields on form. Header File.....TCXLent.h Prototype.......IntT CTYP EntDsp(NOARG); Source File.....ENT\ENTDSP.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure. TcxlErr contains: W_NOFRMBEG - No Form Defined W_NOINP2FEW - Not enough Input Fields Defined W_NOINPENA - No fields enabled Notes...........This function is generally used in conjunction with EntFree(), permitting "read-only"-style forms, suitable for paging through a database, for example. For more details, see the notes in TCXLent.h. TesSeRact CXL V5.52 Documentation Page 53 --------------------------------------------------------------------------- EntFree Synopsis........Dispose of current entry form. Header File.....TCXLent.h Prototype.......VOID CTYP EntFree(NOARG); Source File.....ENT\ENTFREE.C Arguments.......None Returns.........None Notes...........This function is generally used in conjunction with EntDsp(), permitting "read-only"-style forms, suitable for paging through a database, for example. For more details, see the notes in TCXLent.h. --------------------------------------------------------------------------- EntPush Synopsis........Save current entry form. Header File.....TCXLent.h Prototype.......IntT CTYP EntPush(NOARG); Source File.....ENT\ENTPUSH.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Error TcxlErr contains: W_NOFRMBEG - No Form Defined W_FRMSTKOV - Form stack overflow Notes...........This function, in conjunction with EntPop(), is used to create nested entry forms. See the discussion in TCXLent.h for more specific details. Make sure to ALWAYS check the return value from EntPush for ERR_MEM!! Page 54 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- EntPop Synopsis........Restore saved entry form. Header File.....TCXLent.h Prototype.......IntT CTYP EntPop(NOARG); Source File.....ENT\ENTPUSH.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOFRMBEG - No Form Defined W_FRMISDEF - Form already defined Notes...........This function, in conjunction with EntPush is used to create nested entry forms. See the discussion in TCXLent.h for more specific details. Entry Field Processing --------------------------------------------------------------------------- FldCur Synopsis........Current Field Object Header File.....TCXLent.h Prototype.......FdfP FldCur(NOARG); Arguments.......None Returns.........The address of the current entry field. Notes...........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. 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. Please use the macros defined in TCXLent.h when updating members of this structure -- while the structure may change in future versions, the macros will remain consistent. TesSeRact CXL V5.52 Documentation Page 55 --------------------------------------------------------------------------- FldLoc Synopsis........Return pointer to field in current form with passed Tag ID. Header File.....TCXLent.h Prototype.......FdfP CTYP FldLoc(TagT id); Source File.....ENT\FLDLOC.C Arguments.......id - Tag ID of the field to search for Returns.........The address of the current input field's record If an error occurs, then NULL is returned, and TcxlErr contains: W_NOACTIVE - No Active Window W_NOFRMDEF - No Form Defined W_NOTFOUND - No Defined Field Matches specified Tag Notes...........Searches for a defined field using the tag ID of the field, 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. 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. Please use the macros defined in TCXLent.h when updating members of this structure -- while the structure may change in future versions, the macros will remain consistent. --------------------------------------------------------------------------- FldChg Synopsis........Signal parent field was changed by child. Header File.....TCXLent.h Prototype.......VOID CTYP FldChg(NOARG); Source File.....ENT\FLDCHG.C Arguments.......None Returns.........None Notes...........This function is used to tell a parent form that the child has modified its current field. This would be used in conjunction with EntPush() and EntPop() to work with nested entry forms. Page 56 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- FldDis Synopsis........Disable/Enable entry field. Header File.....TCXLent.h Prototype.......VOID CTYP FldDis(FdfP fp, FlgT df); Source File.....ENT\FLDDIS.C Arguments.......fp - Entry field to enable/disable. df - If TRUE, disable field; else enable field. Returns.........None --------------------------------------------------------------------------- FldReq Synopsis........Make entry field required/optional. Header File.....TCXLent.h Prototype.......VOID CTYP FldReq(FdfP fp, FlgT rf); Source File.....ENT\FLDDIS.C Arguments.......fp - Entry field to enable/disable. df - If TRUE, require input; else field takes optional input. Returns.........None Entry Internals --------------------------------------------------------------------------- _FldPut (Internal) Synopsis........Display Entry Field with correct attribute. Header File.....TCXLent.h Prototype.......VOID CTYP _FldPut(FdfP f, FlgT h); --------------------------------------------------------------------------- _FldSet (Internal) Synopsis........Set up transient field control. Header File.....TCXLent.h Prototype.......VOID CTYP _FldSet(FdfP f); TesSeRact CXL V5.52 Documentation Page 57 Help System TCXL'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 HlpSet(). 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, 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 HlpCur(). When you need to retrieve it, you pop it back off of the stack using HlpPop(). 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 (or when the HlpGet() function is called) by the user, TCXL'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 KbndSet() 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 KbndSet() in the "open" function specified in the HlpDef() 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. Page 58 TesSeRact CXL V5.52 Documentation 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 HlpWind(). The HlpWind() function sets the screen coordinates to be used when opening the help window and can be called any time after HlpDef(). If you ever want to disengage the help system, just call HlpOff(). Building Help Files Creating help files is quite easy. You need to have an ASCII editor to create them with. You should have your editor set to expand tab characters to spaces. 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 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 HlpSet(). 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). TCXL 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. TesSeRact CXL V5.52 Documentation Page 59 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, MAKHLP.COM, which takes your ASCII help file as input, and outputs an indexed version of the same file. This new file is the actual help file that you specify in the HlpDef() function. Keep the ASCII help file around so you will be able to make modifications. Please note that the file format of the finished .HLP file has changed between Version 5.51 and 5.52, so all help files should be recompiled! The MAKHLP syntax is as follows: MakHlp [-tn] [-mNN] <ifil> <ofil> Where : -tNN.............Optional tab-width [2..32]. Default is 8 -mNN.............Optional maximum xref/page [48|64]. Default is 32. <ifil>...........Input ASCII help-text pathname. <ofil>...........Output compiled TCXL help-file pathname. Help System Equates Help Limits HLP_STK (16) .......................Default help-stack depth HLP_MAX (32) .......................Maximum xrefs per screen HLP_LEN (26) .....................Significant length of xref HLP_BFR (80) .........................Input line-buffer size Page 60 TesSeRact CXL V5.52 Documentation Help System Routines Help Definition --------------------------------------------------------------------------- HlpDef Synopsis........Defines the help system parameters. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpDef(ChrP hf, KeyT kc, AtrT wa, AtrT fa, AtrT ta, AtrT xa, AtrT ba, BytT ft, VfvCP fo); Source File.....HLP\HLPDEF.C Arguments.......fn - Filename for help file kc - Keycode of the help key wa - Help Window Attribute (See Appendix A). fa - Frame Attribute (See Appendix A). ta - Help Text Attribute (See Appendix A). Note that the window attribute and the text attribute are generally the same; the <wa> is used to determine what attribute the help window is cleared to when it is opened, and the <ta> is the attribute of normal text. xa - Cross-Reference Text Attribute (See Appendix A) ba - Selection Bar Attribute (See Appendix A) ft - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open fo - Function to call immediately upon opening the help window Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Error TcxlErr contains: W_NOHLPFIL - No Help File Name defined Notes...........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. The default help-window is <3,8> to <21,71>, 16 rows by 61 cols of help-text per page. This can't be changed without re-formatting the help file. Example.........HlpDef("TCXLDEMO.HLP", Key_F1, YELLOW|_RED, YELLOW|_RED, LRED|_RED, WHITE|_RED, RED|_LGREY, BOX_DBL, _VFVCP(PreHelp)); TesSeRact CXL V5.52 Documentation Page 61 --------------------------------------------------------------------------- HlpOff Synopsis........Undefine Help Header File.....TCXLhlp.h Prototype.......IntT HlpOff(NOARG); Source File.....HLP\HLPDEF.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help Notes...........Disengages the help system. This un-defines the help key, clears the help stack, and frees any memory allocated by the help system. --------------------------------------------------------------------------- HlpKey Synopsis........Define or Undefine Help Key Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpKey(KeyT kc); Source File.....HLP\HLPDEF.C Arguments.......kc - Key to use for Help Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help Notes...........If <kc> is zero (0x0000), undefine current help key; otherwise, assign current help key to <kc>. Page 62 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- HlpTtl Synopsis........Define new help-window title, replacing "[ Help ]". Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpTtl(ChrP ts, BytT tp, AtrT ta); Source File.....HLP\HLPDEF.C Arguments.......ts - New Title String tp - Title Position (One of the following) TTL_LFT..Left TTL_CNT..Center TTL_RGT..Right ta - Title Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help Notes...........Use this function to modify the default help window title. TesSeRact CXL V5.52 Documentation Page 63 --------------------------------------------------------------------------- HlpWind Synopsis........Define a new help window. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpWind(IntT sr, IntT sc, IntT er, IntT ec, BytT ft); Source File.....HPL\HLPWIND.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column ft - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help W_NIVBTYPE - Invalid Frame Type Notes...........Sets specific features to be used by the help window for when it opens. These are screen coordinates, and frame type. It does not actually open the help window. You can call HlpWind() anytime after calling HlpDef(). You can call HlpWind() as often as you like during your program. Page 64 TesSeRact CXL V5.52 Documentation Help Operation --------------------------------------------------------------------------- HlpGet Synopsis........Display the current help screen. Header File.....TCXLhlp.h Prototype.......VOID CTYP HlpGet(NOARG); Source File.....HLP\HLPGET.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help Notes...........This function displays the help window, with the current window's Help Category as the specified help text. This function is normally called when the default Help Key is pressed. You may also call this function directly from inside your program, and it will operate in the same fashion. --------------------------------------------------------------------------- HlpAdd Synopsis........Push current help category, then set help category. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpAdd(TagT ht); Source File.....HLP\HLPSET.C Arguments.......ht - Help Tag-ID Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Help Record Defined W_HLPSTKOV - Help Stack Overflow (Stack Full) Notes...........Adds the current help category to the help category stack, then sets the current help category to the specified help category. It's effectively the same as doing a HlpCur() followed by a HlpSet(). TesSeRact CXL V5.52 Documentation Page 65 --------------------------------------------------------------------------- HlpCur Synopsis........Push current help category. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpCur(NOARG); Source File.....HLP\HLPSET.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - no defined help. See HlpDef(). W_HLPSTKOV - help stack overflow (stack full). Notes...........Pushes the current help category onto the help category stack. The default stack can hold up to 16 help categories. --------------------------------------------------------------------------- HlpDrop Synopsis........Drop last pushed help category. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpDrop(NOARG); Source File.....HLP\HLPSET.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help W_HLPSTKUN - Help Stack Underflow (Stack Empty) Notes...........Pops the help category off of the top of the stack and into the void. The current help category is not affected. Page 66 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- HlpSet Synopsis........Set help category. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpSet(TagT ct); Source File.....HLP\HLPSET.C Arguments.......ct - Help Category Tag Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help Notes...........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. --------------------------------------------------------------------------- HlpPush Synopsis........Push help category onto help-stack. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpPush(TagT ct); Source File.....HLP\HLPSET.C Arguments.......ct - The help tag to push Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help W_HLPSTKUN - Help Stack Overflow (Stack Full) Notes...........Pushes the specified help category onto the help category stack. The current help category is not affected. The default help stack can hold up to 16 help categories. TesSeRact CXL V5.52 Documentation Page 67 --------------------------------------------------------------------------- HlpPop Synopsis........Pop help category off stack and make current. Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpPop(NOARG); Source File.....HLP\HLPSET.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Defined Help W_HLPSTKUN - Help Stack Underflow (Stack Empty) Notes...........Pops the help category off of the top of the stack and makes it the current help category. --------------------------------------------------------------------------- HlpAct Synopsis........Test whether help has been defined. Header File.....TCXLhlp.h Prototype.......FlgT HlpAct(NOARG); Arguments.......None Returns.........TRUE if help has been defined; FALSE otherwise. --------------------------------------------------------------------------- HlpClr Synopsis........Clears the help category stack Header File.....TCXLhlp.h Prototype.......IntT CTYP HlpClr(NOARG); Source File.....HLP\HLPDEF.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOHLPDEF - No Help Defined Page 68 TesSeRact CXL V5.52 Documentation Help Internals --------------------------------------------------------------------------- _HlpErr Synopsis........Display "not found" message in help window and wait for user. Header File.....TCXLhlp.h Prototype.......VOID CTYP _HlpErr(ChrP s); --------------------------------------------------------------------------- _HlpPag Synopsis........Display help-category with paging, cross-references, etc. Header File.....TCXLhlp.h Prototype.......VOID CTYP _HlpPag(NOARG); TesSeRact CXL V5.52 Documentation Page 69 Selection System TCXL's Selection System is a powerful tool to help users select information. SelFile(), SelStr() and SelTxt() all use the same low-level input routine, _Select(). SelAttr() is provided not only because of its obvious usefulness, but as an example of what can be accomplished using TCXL. To use the Selection System, you just need to call the appropriate routine. To select a file, for example, call SelFile(), specifying the size of the window to use, etc. Upon return, the pathname of the file you were attempting to select will be waiting! Although the structures and variables in the Selection System are internal only, two macros, SelPtr, SelNdx, are provided to allow users access to the currently-highlighted item. This would normally be used in a function bound to a special key that needed to know what item is currently selected. If you need access to the items that were selected after returning from the section function, use the global variables SelItm, SelNam and SelCur. Please note that mouse support is automatically activated during entry form processing, if a mouse has been detected during initialization. This means you can select an item with your mouse, and you can also scroll the window using the provided scroll bars. Selection System Equates _Sel Access Macros SelLst........................................Selection-list SelItm.................................Selected item-pointer SelNam..................................Selected item-buffer SelCur...................................Selected item-index SelFlg.........................................Control flags Highlight Access Macros SelNdx............................Index of current highlight SelPtr..........................Pointer to current highlight Selection Limits MAX_FIL (511)........................SelFile() maximum files MAX_NAM (81) ...........SelFile() maximum length of pathname SelFlg Options SEL_BAR..................................Frame scroll-bar ON SEL_DIR.............................SelFile() directories ON SEL_PAR........................SelFile() parent directory ON Page 70 TesSeRact CXL V5.52 Documentation Selection System Routines --------------------------------------------------------------------------- SelAttr Synopsis........Select attributes. Header File.....TCXLsel.h Prototype.......IntT CTYP SelAttr(IntT sr, IntT sc, BytT ft, AtrT fa, IntT ab, VfvCP fo); Source File.....SEL\SELATTR.C Arguments.......sr - Start Row sc - Start Column ft - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open fa - Beginning Attribute (current default) ab - Allow Blink? fo - Function to call when window is opened Returns.........The new attribute Notes...........This function will open a window and let the user interactively pick a text attribute (See Appendix A for a list of available attributes). The window is fixed in size, 19 rows by 68 columns. TesSeRact CXL V5.52 Documentation Page 71 --------------------------------------------------------------------------- SelFile Synopsis........Select a file name from sorted list. Header File.....TCXLsel.h Prototype.......ChrP CTYP SelFile(IntT sr, IntT sc, IntT er, IntT ec, BytT bt, AtrT ba, AtrT wa, AtrT sa, FlgT ti, ChrP fs, VfvCP fo); Source File.....SEL\SELFILE.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Border Attribute (See Appendix A) wa - Window Attribute (See Appendix A) sa - Selection Bar Attribute (See Appendix A) ti - Display Filespec Title On Upper Border? (0=no, 1=yes) fs - Filespec to match (ie, "*.*") fo - Function to call when window is opened Returns.........The address of the string containing the full drive:path\filename string of the selected file. If an error occurred, NULL will be returned and TcxlErr 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 Border Type W_STRLONG - Window Not Wide Enough To Hold Largest File Name W_NOMATCH - No Files Matched Input Filespec W_INVPATH - Invalid Path Or Path Not Found Page 72 TesSeRact CXL V5.52 Documentation Notes...........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, SelFile() will change to that directory and display the list of files/directories in it. After the selection is made, SelFile() will return the complete path name of the selected file. The file returned by SelFile() is stored in a global variable SelNam. This is allocated on the first call to SelFile(), and is not free()'d until the user explicitly calls SelFree(). If you pass a -1 as the end column coordinate, this function will adjust the width of the window to be one longer than the width of the longest string. Example.........SelFile(LeftRow, LeftCol - 18, LeftRow + 10, LeftCol + 39, 0, LCYAN|_RED, LGREY|_RED, RED|_LGREY, 1, "*.*", _VFVCP(AddShadow)); TesSeRact CXL V5.52 Documentation Page 73 --------------------------------------------------------------------------- SelStr Synopsis........Select a string from an array Header File.....TCXLsel.h Prototype.......IntT CTYP SelStr(IntT sr, IntT sc, IntT er,IntT ec, BytT bt, AtrT ba, AtrT wa, AtrT sa, ChrP as[], IntT ie, VfvCP fo); Source File.....SEL\SELSTR.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Border Attribute (See Appendix A) wa - Window Attribute (See Appendix A) sa - Selection Bar Attribute (See Appendix A) as - Base of array of string pointers ie - Initial Element to default to fo - Function to call when window is opened Returns.........The array subscript of the selected string. If an error occurred, then -1 (ERR_ARG) will be returned and TcxlErr will be set to one of the following: W_ESCPRESS - The [Esc] Key Was Pressed W_ALLOCERR - Memory Allocation Error W_INVCOORD - Invalid Window Coordinates W_INVBTYPE - Invalid Border Type W_STRLONG - Window Not Wide Enough To Hold Largest String W_INVPATH - Invalid Path Or Path Not Found Notes...........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, SelStr() will return the array subscript of the string that was selected. If you pass a -1 as the end column coordinate, this function will adjust the width of the window to be one longer than the width of the longest string. Page 74 TesSeRact CXL V5.52 Documentation Example.........SelStr(LeftRow,32, LeftRow + 5, -1, 0, LGREEN|_RED, LCYAN|_RED, RED|_LGREY, months, 0, _VFVCP(PrePick1)); --------------------------------------------------------------------------- SelTxt Synopsis........Select a text string within current window. Header File.....TCXLsel.h Prototype.......IntT CTYP SelTxt(BytT wr, BytT wc, AtrT at, ChrP as[], IntT ie); Source File.....SEL\SELTXT.C Arguments.......wr - Window Row to start selection wc - Window Column to start selection at - Attribute for selection text (See Appendix A) as - Base of array of string pointers ie - Initial Element to default to Returns.........The array subscript of the selected string. If an error occurred, then -1 (ERR_ARG) will be returned and TcxlErr will be set to one of the following: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed W_STRLONG - Window Not Wide Enough To Hold Largest String Notes...........Allows user to select one string from an array of strings via an in-place "menu". This function is the same as SelStr(), except that it puts the selection menu in the current active window, instead of creating a separate window for the selection. Example.........SelTxt(5, 27, LMAGENTA|_MAGENTA, prn_ports, 0); Selection Utilities --------------------------------------------------------------------------- SelFree Synopsis........Free global SelNam buffer after SelFile(). Header File.....TCXLsel.h Prototype.......VOID CTYP SelFree(NOARG); Source File.....SEL\SELFILE.C Arguments.......None Returns.........None TesSeRact CXL V5.52 Documentation Page 75 --------------------------------------------------------------------------- SelBarOn Synopsis........Turns on Scroll Bars on right edge of selection window. Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelBarOn(NOARG); --------------------------------------------------------------------------- SelBarOff Synopsis........Turns off Scroll Bars on right edge of selection window. Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelBarOff(NOARG); --------------------------------------------------------------------------- SelDirOn Synopsis........Enables display of directories in SelFile(). Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelDirOn(NOARG); --------------------------------------------------------------------------- SelDirOff Synopsis........Disables display of directories in SelFile(). Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelDirOff(NOARG); --------------------------------------------------------------------------- SelParOn Synopsis........Enables display of parent directory in SelFile(). Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelParOn(NOARG); --------------------------------------------------------------------------- SelParOff Synopsis........Disables display of parent directory in SelFile(). Should be called before Sel...(). Header File.....TCXLsel.h Prototype.......VOID SelParOff(NOARG); Page 76 TesSeRact CXL V5.52 Documentation Selection Internals --------------------------------------------------------------------------- _Select Synopsis........This is the generic selection system routine, called by SelFile(), SelStr() and SelTxt(). Header File.....TCXLsel.h Prototype.......IntT CTYP _Select(IntT sr, IntT sc, IntT er,IntT ec, BytT bt, AtrT ba, AtrT wa, AtrT sa, ChrP as[], IntT ie, VfvCP fo); Source File.....SEL\_SELECT.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Border Attribute (See Appendix A) wa - Window Attribute (See Appendix A) sa - Selection Bar Attribute (See Appendix A) as - Base of array of string pointers ie - Initial Element to default to fo - Function to call when window is opened Returns.........The array subscript of the selected string. If an error occurred, then -1 (ERR_ARG) will be returned and TcxlErr will be set to one of the following: W_ESCPRESS - The [Esc] Key Was Pressed W_ALLOCERR - Memory Allocation Error W_INVCOORD - Invalid Window Coordinates W_INVBTYPE - Invalid Border Type W_STRLONG - Window Not Wide Enough To Hold Largest String W_INVPATH - Invalid Path Or Path Not Found TesSeRact CXL V5.52 Documentation Page 77 Window System The Window System is the "heart" of the TCXL package. It is the largest of all the systems, and also the most varied. Functions are provided for window shapes, sizes, locations, appearances, and for text output. Using the Window System is simple. Call Wopen() to open a window. Use the Wput..() and Wprt..() functions for output. Use the Wset..() functions for setting control information. Wopen() returns a Window Handle, which is used by many of the functions in TCXL to determine which window to affect. Most of the output functions are designed to write to the active window, which is the window on "top". While TCXL provides limited functionality for writing to hidden or inactive windows (see the Wwprints() function), this is really not in the design of this package. With TCXL 6.0, we will have full virtual windows. Page 78 TesSeRact CXL V5.52 Documentation Window System Equates _Wctl Access Macros WctlAct........................................Active window WctlHid....................................Top hidden window WctlFun........................................Fill function WctlHdl..........................................Last handle WctlHlp........................................Help category WctlOpn...........................................Total open WctlEsc..........................................[Esc] check WctlTab............................................Tab width WctlFil............................................Fill char _Wdf Access Macros WdfPrv(w)....................................Previous window WdfNxt(w)........................................Next window WdfBfr(w).............................................Buffer WdfSbf(w)......................................Shadow buffer WdfTtl(w)..............................................Title WdfTtlS(w)............................................String WdfTtlP(w)..........................................Position WdfTtlA(w).........................................Attribute WdfHdl(w).............................................Handle WdfHlp(w)......................................Help category WdfBeg(w).....................................Start position WdfBegW(w)..............................................Word WdfBegC(w)...............................................Col WdfBegR(w)...............................................Row WdfEnd(w).......................................End position WdfEndW(w)..............................................Word WdfEndC(w)...............................................Col WdfEndR(w)...............................................Row WdfMin(w)...................................Minimum position WdfMinW(w)..............................................Word WdfMinC(w)...............................................Col WdfMinR(w)...............................................Row WdfMax(w)...................................Maximum position WdfMaxW(w)..............................................Word WdfMaxC(w)...............................................Col WdfMaxR(w)...............................................Row WdfPos(w)....................................Cursor position WdfPosW(w)..............................................Word WdfPosC(w)...............................................Col WdfPosR(w)...............................................Row WdfFrm(w).....................................Frame (border) WdfFrmT(w)..............................................Type WdfFrmA(w).........................................Attribute WdfDat(w)..................................Default attribute WdfCat(w)..................................Current attribute WdfSat(w)...................................Shadow attribute WdfUse(w).......................................Window usage WdfBrd(w)........................................Border flag TesSeRact CXL V5.52 Documentation Page 79 Frame (border) sides BRD_TOP..................................................Top BRD_BOT...............................................Bottom BRD_LFT.................................................Left BRD_RGT................................................Right Wcenter(), WpopUp() flags CNT_HOR...........................................Horizontal CNT_VER.............................................Vertical CNT_CNT.................................................Both Direction codes DIR_DWN.................................................Down DIR_UP....................................................Up DIR_LFT.................................................Left DIR_RGT................................................Right Wtitle() positions TTL_LFT.................................................Left TTL_CNT...............................................Center TTL_RGT................................................Right Window System Routines Error Handling Routines --------------------------------------------------------------------------- Wperror Synopsis........Display a popup error message window frame Header File.....TCXLwin.h Prototype.......IntT CTYP Wperror(ChrP mp); Source File.....WIN\WPERROR.C Arguments.......mp - The message you want displayed in the error window Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_STRLONG - error message string too long Notes...........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. Page 80 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WerrMsg Synopsis........Return an error message from last windowing function. Header File.....TCXLwin.h Prototype.......ChrP CTYP WerrMsg(NOARG); Source File.....WIN\WERRMSG.C Arguments.......None Returns.........A pointer to the error message associated with the current value of TcxlErr. Notes...........This function, reads the global error value stored in TcxlErr, and returns the literal error message that corresponds to it. This can be very useful in debugging programs that use TCXL's windowing functions. --------------------------------------------------------------------------- Werror Synopsis........Terminate with error message and beep to StdErr. Header File.....TCXLwin.h Prototype.......VOID CTYP Werror(NOARG); Source File.....WIN\WERRMSG.C Arguments.......None Returns.........None Notes...........This function terminates your application with a fatal error message, based on the value of TcxlErr. The video system is restored, the screen is cleared, and the error message is set to the Standard Error device (StdErr). TesSeRact CXL V5.52 Documentation Page 81 General Window Control --------------------------------------------------------------------------- Wactiv Synopsis........Activate window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wactiv(WndT wh); Source File.....WCT\WACTIV.C Arguments.......wh - Window Handle Returns.........ERR_NUL - No Error, or Window Already Active ERR_ARG - Argument Failure TcxlErr contains: W_NOTFOUND - Window Handle Not Found W_NOACTIVE - No Open Windows Notes...........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. Example --------------------------------------------------------------------------- WcloseAll Synopsis........Closes all open windows. Header File.....TCXLwin.h Prototype.......IntT CTYP WcloseAll(NOARG); Source File.....WCT\WCLOSEAL.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Page 82 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Windowat Synopsis........Tell which window is at passed coordinates. Header File.....TCXLwin.h Prototype.......WndT CTYP Windowat(IntT sr, IntT sc); Source File.....WCT\WINDOWAT.C Arguments.......sr - Screen Row sc - Screen Column Returns.........The window handle of the window at the given coordinates. ERR_NUL - Check TcxlErr for Error Code! ERR_ARG - Argument Failure TcxlErr contains: W_NOTFOUND - no window found at given screen coordinates Notes...........Returns the handle of the window at given screen row, column coordinates. --------------------------------------------------------------------------- WinLoc Synopsis........Return address of structure for given window. Header File.....TCXLwin.h Prototype.......WdfP CTYP WinLoc(WndT wh); Source File.....WCT\WINLOC.C Notes...........Finds the address of a window record using the specified window handle. This is used internally be several TCXL functions. Arguments.......wh - Window Handle Returns.........The address of the window control structure, or NULL if no record was found. TesSeRact CXL V5.52 Documentation Page 83 --------------------------------------------------------------------------- Wisactiv Synopsis........Test for active handle. Header File.....TCXLwin.h Prototype.......IntT Wisactiv(WndT a); Arguments.......a - Window Handle Returns.........TRUE if specified handle is active FALSE otherwise Notes...........Determines if the specified window is active. --------------------------------------------------------------------------- Wopen Synopsis........Open a window. Header File.....TCXLwin.h Prototype.......WndT CTYP Wopen(IntT sr, IntT sc, IntT er, IntT ec, BytT bt, AtrT ba, AtrT wa); Source File.....WCT\WOPEN.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column bt - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Border Attribute (See Appendix A) wa - Window Attribute (See Appendix A) Returns.........The window handle of the new window, or: ERR_ARG - Argument Failure TcxlErr contains: W_INVCOORD - Invalid Coordinates W_INVBTYPE - Invalid Border Type Notes...........Opens a screen window and makes it active. The cursor location will be initialized to window row 0, column 0. The text attribute (See Appendix A) will be initialized to the same attribute as the window. You can open as many windows as memory permits. Page 84 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WpopUp Synopsis........Open a window centered on the screen. Header File.....TCXLwin.h Prototype.......WndT CTYP WpopUp(IntT cf, IntT sr, IntT sc, IntT er, IntT ec, BytT bt, AtrT ba, AtrT wa); Source File.....WCT\WPOPUP.C Arguments.......cf - Centering Flag (One of the following) CNT_HOR..Horizontal CNT_VER..Vertical CNT_CNT..Both sr - Start Row sc - Start Column er - End Row ec - End Column bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] BOX_EXP..explode frame on open ba - Border Attribute (See Appendix A) wa - Window Attribute (See Appendix A) Returns.........The window handle of the new window, or: ERR_ARG - Argument Failure TcxlErr contains: W_INVCOORD - Invalid Coordinates W_INVBTYPE - Invalid Border Type Notes...........This function, like Wopen(), opens a screen window and makes it active. However, this function will automatically center the window on the screen; horizontally, vertically, or both. This function will detect the screen size, based on the initialization parameters, and react accordingly. For consistency, the parameter list for WpopUp() is identical to Wopen() except for the addition of the flag byte. However, the start/end positions are used only for size determination. WpopUp() is identical to calling Wopen() followed by Wcenter(). TesSeRact CXL V5.52 Documentation Page 85 --------------------------------------------------------------------------- Wsave Wrestore Synopsis........Save/Restore window from buffer Header File.....TCXLwin.h Prototype.......VcelP CTYP Wsave(IntT sr, IntT sc, IntT er, IntT ec); VOID CTYP Wrestore(VcelP wb); Source File.....WCT\WSAVE.C Arguments.......wb - Pointer to Window Buffer sr - Start Row sc - Start Column er - End Row ec - End Column Returns.........Address of newly-created window buffer, or NULL if not enough memory. Notes...........Saves a region of the screen and allocates memory to hold the buffer, or restores a previously saved region of the screen and frees the memory allocated by Wsave(). --------------------------------------------------------------------------- Wpush Wpop Synopsis........Save/Restore window to buffer Header File.....TCXLwin.h Prototype.......VOID CTYP Wpop(VcelP wb, IntT sr, IntT sc, IntT er, IntT ec); VcelP Wpush(IntT sr, IntT sc, IntT er, IntT ec); Arguments.......wb - Pointer to Window Buffer sr - Start Row sc - Start Column er - End Row ec - End Column Returns.........Address of newly-created window buffer, or NULL if not enough memory. Notes...........Saves a region of the screen and allocates memory to hold the buffer, or restores a previously saved region of the screen and frees the memory allocated by Wpush(). Wpush() is identical to Wsave(); Wpop() is identical to Wrestore() except it will restore the window to a new screen location. Page 86 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WsetEsc Synopsis........Enable/disable escape checking. Header File.....TCXLwin.h Prototype.......VOID CTYP WsetEsc(FlgT a); Source File.....WCT\WSETESC.C Notes...........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. Arguments.......a - FALSE means turn Esc Checking off, TRUE means turn it on. Returns.........None Example --------------------------------------------------------------------------- WsetFil Synopsis........Set window fill character Header File.....TCXLwin.h Prototype.......VOID WsetFil(ChrT a); Arguments.......a - Character to use as fill char Returns.........None Notes...........Specifies which character the windowing system will use for filling windows with. By default, it is a space (' '). TesSeRact CXL V5.52 Documentation Page 87 --------------------------------------------------------------------------- WsetFun Synopsis........Set fill function. Header File.....TCXLwin.h Prototype.......VOID WsetFun(VOID (CTYP *f)(WrdT, WrdT, ChrT, AtrT)); Arguments.......f - Replacement Fill Function Returns.........None Notes...........This function sets an alternate routine to "fill" a window when it is opened. See the default fill function, VfilBox(), for details on the prototype for this routine. --------------------------------------------------------------------------- WsetTab Synopsis........Set tab width. Header File.....TCXLwin.h Prototype.......VOID WsetTab(BytT a); Notes...........Modifies the tab width to be used when displaying tabs in the active window via the window TTY output functions (these are the Wput???() family of functions). The default tab width is 8. Arguments.......a - Tab Width (in columns) Returns.........None --------------------------------------------------------------------------- WsetTxt Synopsis........Set new window text attribute. Header File.....TCXLwin.h Prototype.......IntT CTYP WsetTxt(AtrT a); Source File.....WCT\WSETTXT.C Arguments.......a - Text Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Sets the current text attribute (See Appendix A) for the active window. The current text attribute is used by the window TTY output functions (these are the Wput???() family of functions) for displaying text inside the active window. Page 88 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wunhide Synopsis........Unhide a previously hidden window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wunhide(WndT wh); Source File.....WCT\WHIDE.C Arguments.......wh - Window Handle Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOTFOUND - Window Handle Not Found W_NOHIDDEN - No Hidden Windows W_NOTHIDD - Window Not Hidden Notes...........The unhidden window becomes the active window. --------------------------------------------------------------------------- Wunlink Synopsis........Unlink and free window from memory without screen change. Header File.....TCXLwin.h Prototype.......IntT CTYP Wunlink(WndT wh); Source File.....WCT\WUNLINK.C Arguments.......wh - Window Handle Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOTFOUND - Input Window Handle Was Not Found Notes...........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. If the passed window handle is zero, the current active window is unlinked. TesSeRact CXL V5.52 Documentation Page 89 --------------------------------------------------------------------------- Wwprints Synopsis........Display text in visible or non-visible window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wwprints(WndT wh, BytT wr, BytT wc, AtrT at, ChrP ps); Source File.....WIN\WWPRINTS.C Arguments.......wh - Window Handle wr - Window Row wc - Window Column at - Text Attribute (See Appendix A) ps - String to display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: 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) Notes...........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. Page 90 TesSeRact CXL V5.52 Documentation Active Window Movement --------------------------------------------------------------------------- Wcenter Synopsis........Center active window on screen. Header File.....TCXLwin.h Prototype.......IntT CTYP Wcenter(IntT cf); Source File.....WCT\WCENTER.C Arguments.......cf - Centering Flag (One of the following) CNT_HOR..Horizontal CNT_VER..Vertical CNT_CNT..Both Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window Notes...........Centers the active window on the screen, horizontally, vertically, or both. --------------------------------------------------------------------------- Wclose Synopsis........Close active window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wclose(NOARG); Source File.....WCT\WOPEN.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Closes the active window. If the window has a shadow, it will be closed as well. TesSeRact CXL V5.52 Documentation Page 91 --------------------------------------------------------------------------- Wcopy Synopsis........Make a copy of the current active window. Header File.....TCXLwin.h Prototype.......WndT CTYP Wcopy(IntT nr, IntT nc); Source File.....WCT\WCOPY.C Arguments.......nr - Start Row of duplicate window sc - Start Column of duplicate window Returns.........The window handle of the new window, or: ERR_ARG - Argument Failure TcxlErr contains: W_INVCOORD - invalid coordinates Notes...........Creates a new window duplicating the active window. The new window becomes the active window. --------------------------------------------------------------------------- Wdrag Synopsis........Smoothly drag a window one position in the specified direction. Header File.....TCXLwin.h Prototype.......IntT CTYP Wdrag(BytT df); Source File.....WCT\WDRAG.C Arguments.......df - Direction (One of the following) DIR_DWN..Down DIR_UP...Up DIR_LFT..Left DIR_RGT..Right Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_ALLOCERR - Memory Allocation Error Page 92 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wdump Synopsis........Dump active window to printer. Header File.....TCXLwin.h Prototype.......IntT CTYP Wdump(NOARG); Source File.....WCT\WDUMP.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Dumps the active window to the default printer (PRN). --------------------------------------------------------------------------- Wgrow Synopsis........Resize the active window to have new start position with same end position. Header File.....TCXLwin.h Prototype.......IntT CTYP Wgrow(IntT nr, IntT nc); Source File.....WCT\WGROW.C Arguments.......nr - New Lower-Left Row nc - New Lower-Left Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Adjusts the size of the active window by changing the screen coordinates of its upper-left corner. TesSeRact CXL V5.52 Documentation Page 93 --------------------------------------------------------------------------- Whandle Synopsis........Return the handle of the active window. Header File.....TCXLwin.h Prototype.......WndT CTYP Whandle(NOARG); Source File.....WCT\WHANDLE.C Arguments.......None Returns.........The handle of the active window, or zero if error; TcxlErr contains: W_NOACTIVE - No Active Window --------------------------------------------------------------------------- Whide Synopsis........Hide active window. Header File.....TCXLwin.h Prototype.......IntT CTYP Whide(NOARG); Source File.....WCT\WHIDE.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window Notes...........The next window becomes active. --------------------------------------------------------------------------- Wmove Synopsis........Moves the active window to a new location on the screen. Header File.....TCXLwin.h Prototype.......IntT CTYP Wmove(IntT sr, IntT sc); Source File.....WCT\WMOVE.C Arguments.......sr - New Start Row sc - New Start Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window Page 94 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wsize Synopsis........Resize the active window to have new end position with same start position. Header File.....TCXLwin.h Prototype.......IntT CTYP Wsize(IntT nr, IntT nc); Source File.....WCT\WSIZE.C Arguments.......nr - New Lower-Left Row nc - New Lower-Left Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Adjusts the size of the active window by changing the screen coordinates of its lower-right corner. --------------------------------------------------------------------------- Wslide Synopsis........Smoothly slides active window to new screen position. Header File.....TCXLwin.h Prototype.......IntT CTYP Wslide(IntT sr, IntT sc); Source File.....WCT\WSLIDE.C Arguments.......sr - New Start Row sc - New Start Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates TesSeRact CXL V5.52 Documentation Page 95 --------------------------------------------------------------------------- Wstretch Synopsis........Smoothly stretches active window to new screen position. Header File.....TCXLwin.h Prototype.......IntT CTYP Wstretch(IntT sr, IntT sc); Source File.....WCT\WSTRETCH.C Arguments.......sr - New Start Row sc - New Start Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_ALLOCERR - Memory Allocation Error W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Active Window Control --------------------------------------------------------------------------- WchgAtr Synopsis........Change attributes of active window. Header File.....TCXLwin.h Prototype.......IntT CTYP WchgAtr(AtrT ba, AtrT wa); Source File.....WIN\WCHGATR.C Arguments.......ba - New Border Attribute (See Appendix A) wa - New Window Attribute (See Appendix A) Returns.........ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Changes the text attribute of the active window. All text within the window will be changed also. Page 96 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wclear Synopsis........Clears the active window and homes the cursor. Header File.....TCXLwin.h Prototype.......IntT Wclear(NOARG); Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window --------------------------------------------------------------------------- WclrEol Synopsis........Clear to end of line. Header File.....TCXLwin.h Prototype.......IntT CTYP WclrEol(NOARG); Source File.....WIN\WCLREOL.C Notes...........Clears from the cursor to the end of the active window's line. The cursor's position is not updated. Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window --------------------------------------------------------------------------- WclrEos Synopsis........Clear to end of window. Header File.....TCXLwin.h Prototype.......IntT WclrEos(NOARG); Source File.....WIN\WCLREOS.C Arguments.......None Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Clears from the cursor to the end of the active window. The cursor's position is not updated. TesSeRact CXL V5.52 Documentation Page 97 --------------------------------------------------------------------------- WclrWin Synopsis........Clear active window. Header File.....TCXLwin.h Prototype.......IntT CTYP WclrWin(AtrT at); Source File.....WIN\WCLRWIN.C Arguments.......at - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Clears the active window using specified text attribute (See Appendix A), then homes the cursor. This is the same as calling WchgAtr(), followed by Wclear(). [NOTE! Under DOS, Wclear() is implemented as a macro that calls WclrWin().] --------------------------------------------------------------------------- Wdepth Synopsis........Depth of window. Header File.....TCXLwin.h Prototype.......IntT Wdepth(NOARG); Arguments.......None Returns.........Window depth Page 98 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WfilBox Synopsis........Fill a box in window. Header File.....TCXLwin.h Prototype.......IntT CTYP WfilBox(BytT sr, BytT sc, BytT er, BytT ec, ChrT ch, AtrT at); Source File.....WIN\WFILBOX.C Notes...........Fills in a region of active window with a specified character and attribute (See Appendix A). Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column ch - Character to use at - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Window Row TesSeRact CXL V5.52 Documentation Page 99 --------------------------------------------------------------------------- WlinDel WlinIns Synopsis........Delete/insert line. Header File.....TCXLwin.h Prototype.......IntT WlinDel(BytT wr, BytT di); IntT WlinIns(BytT wr, BytT di); Source File.....WIN\_WLINDI_.C Arguments.......wr - Window Row to delete/insert di - Direction (One of the following) DIR_DWN..Down DIR_UP...Up DIR_LFT..Left DIR_RGT..Right Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Window Row Notes...........Deletes or inserts 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. Page 100 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WscrBox Synopsis........Scroll a box. Header File.....TCXLwin.h Prototype.......IntT CTYP WscrBox(BytT sr, BytT sc, BytT er, BytT ec, BytT n, BytT d); Source File.....WIN\WSCRBOX.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column n - Number of lines to scroll d - Direction (Up or Down only!) (One of the following) DIR_DWN..Down DIR_UP...Up DIR_LFT..Left DIR_RGT..Right Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Window Coordinates Notes...........Scrolls a region of the active window up or down. --------------------------------------------------------------------------- WscrWin Synopsis........scroll a window. Header File.....TCXLwin.h Prototype.......IntT WscrWin(BytT n, BytT d); Source File.....WIN\WSCRWIN.C Arguments.......n - Number of lines to scroll d - Direction (Up or Down only!) (One of the following) DIR_DWN..Down DIR_UP...Up DIR_LFT..Left DIR_RGT..Right Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Scrolls text lines within the active window, up or down. TesSeRact CXL V5.52 Documentation Page 101 --------------------------------------------------------------------------- Wwidth Synopsis........Width of window. Header File.....TCXLwin.h Prototype.......IntT Wwidth(NOARG); Arguments.......None Returns.........Window width Active Border --------------------------------------------------------------------------- Wborder Synopsis........Change border type. Header File.....TCXLwin.h Prototype.......IntT CTYP Wborder(BytT bt); Source File.....WCT\WBORDER.C bt - Border Type (One of the following) Arguments....... BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVBTYPE - Invalid Border Type Notes...........Changes the active window's border type. If changing to or from a borderless window, the window's effective area will change as well, changing relative coordinates within the window. Page 102 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wbprintc Synopsis........Display character on window's border. Header File.....TCXLwin.h Prototype.......IntT CTYP Wbprintc(BytT bd, BytT of, AtrT at, ChrT ch); Source File.....WCT\WBPRINTC.C Arguments.......bd - Border Side (One of the following) BRD_TOP..Top BRD_BOT..Bottom BRD_LFT..Left BRD_RGT..Right of - Offset for display at - Text Attribute (See Appendix A) ch - Character to display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_NOBORDER - Window Has No Border W_INVCOORD - Border Offset Out Of Range --------------------------------------------------------------------------- Wmessage Synopsis........Display string on border. Header File.....TCXLwin.h Prototype.......IntT CTYP Wmessage(ChrP ps, BytT bo, BytT lo, AtrT at); Source File.....WCT\WMESSAGE.C Arguments.......ps - Message String bo - Border Sides (One of the following) BRD_TOP..Top BRD_BOT..Bottom BRD_LFT..Left BRD_RGT..Right lo - Left Offset to Display Message at - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_STRLONG - String Could Not Fit In Window W_NOBORDER - Window Has No Border Notes...........Displays text on the top or bottom border of the active window. TesSeRact CXL V5.52 Documentation Page 103 --------------------------------------------------------------------------- Wtitle Synopsis........Display a title on window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wtitle(ChrP ps, BytT tp, AtrT ta); Source File.....WCT\WTITLE.C Arguments.......ps - Title String tp - Title Position (One of the following) TTL_LFT..Left TTL_CNT..Center TTL_RGT..Right ta - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........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. If the passed pointer <ps> is NULL, the current title will be removed from the window. Page 104 TesSeRact CXL V5.52 Documentation Active Shadow --------------------------------------------------------------------------- Wshadow Wshadoff Synopsis........Add/remove shadow from active window. Header File.....TCXLwin.h Prototype.......IntT CTYP Wshadow(AtrT at); IntT CTYP Wshadoff(NOARG); Source File.....WCT\WSHADOFF.C WCT\WSHADOW.C Arguments.......at - Attribute for shadow (most effective is _BLACK | DGREY) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure ERR_MEM - Memory Allocation Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Add or remove the shadow from the active window, if one exists. 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). Wshadoff() 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. TesSeRact CXL V5.52 Documentation Page 105 Active Cursor --------------------------------------------------------------------------- WcurGet WcurPut Synopsis........Get/set cursor position. Header File.....TCXLwin.h Prototype.......VOID WcurGet(VposT rc); IntT WcurPut(VposT rc); Source File.....WCT\WCURGET.C Arguments.......rc - Vpos structure with Window coordinates Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Gets or sets the current cursor coordinates of the active window into the VposT structure. --------------------------------------------------------------------------- Wgotoxy Synopsis........Set window cursor coordinates. Header File.....TCXLwin.h Prototype.......IntT CTYP Wgotoxy(BytT wr, BytT wc); Source File.....WCT\WGOTOXY.C Arguments.......wr - Window Row wc - Window Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........This function moves the cursor in the active window to the passed row/column coordinates. Page 106 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wpgotoxy Synopsis........Set pseudo-window coordinates. Header File.....TCXLwin.h Prototype.......IntT CTYP Wpgotoxy(BytT wr, BytT wc); Source File.....WCT\WPGOTOXY.C Arguments.......wr - Window Row wc - Window Column Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window Notes...........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. --------------------------------------------------------------------------- WposGet Synopsis........Get cursor position. Header File.....TCXLwin.h Prototype.......VOID CTYP WposGet(IntP r, IntP c); Source File.....WCT\WPOSGET.C Arguments.......r - Window Row c - Window Column Returns.........The current row/column position of the active window. Notes...........Reads the current cursor coordinates of the active window. TesSeRact CXL V5.52 Documentation Page 107 Line Drawing --------------------------------------------------------------------------- WdrwBox Synopsis........Draw a box. Header File.....TCXLwin.h Prototype.......IntT CTYP WdrwBox(BytT sr, BytT sc, BytT er, BytT ec, BytT bt, AtrT ba); Source File.....WIN\WDRWBOX.C Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] ba - Border Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_NOBORDER - Window Has No Border W_INVCOORD - Border Offset Out Of Range Notes..........."Draws" a text box in the active window. Page 108 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WdrwHor Synopsis........Draw a horizontal line. Header File.....TCXLwin.h Prototype.......IntT CTYP WdrwHor(BytT sr, BytT sc, BytT nc, BytT bt, AtrT at); Source File.....WIN\WDRWHOR.C Arguments.......sr - Start Row sc - Start Columns nc - Number of Columns bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] at - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Text Line Too Long For Window W_INVBTYPE - Invalid Box Type Notes..........."Draws" a horizontal text line in active window using characters defined by given box type. If horizontal line crosses a vertical line, an appropriate intersection or corner will be used. TesSeRact CXL V5.52 Documentation Page 109 --------------------------------------------------------------------------- WdrwVer Synopsis........Draw a vertical line. Header File.....TCXLwin.h Prototype.......IntT CTYP WdrwVer(BytT sr, BytT sc, BytT n, BytT bt, AtrT at); Source File.....WIN\WDRWVER.C Arguments.......sr - Start Row sc - Start Columns n - Number of Rows bt - Border Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] at - Attribute (See Appendix A) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Text Line Too Long For Window W_INVBTYPE - Invalid Box Type Notes..........."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, an appropriate intersection or corner will be displayed. Page 110 TesSeRact CXL V5.52 Documentation Active Window Output There are two types of window-level output routines. The Wput???() routines are known as "TTY" output routines, because they write to the current position in the current window, using the current attribute. The Wprt???() functions, while performing the same functionality, take a position and attribute as parameters as well, and can output anywhere within the window. In addition, the Wput???() functions pay attention to the TCXL Control and Escape codes (see Appendix C), while the Wprt???() functions do not. --------------------------------------------------------------------------- WdupChrA WdupChr Synopsis........Displays character/attribute multiple times. Header File.....TCXLwin.h Prototype.......VOID CTYP WdupChrA(BytT wr, BytT wc, AtrT at, ChrT ch, IntT nd); VOID CTYP WdupChr(ChrT ch, IntT nd); Source File.....WIN\WDUPCHRA.C WIN\WDUPCHR.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ch - Character to Display nd - Number of times to display character Returns.........None Notes...........Displays a character a specified number of times in the active window. WdupChrA() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. WdupChr() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. TesSeRact CXL V5.52 Documentation Page 111 --------------------------------------------------------------------------- WdupStrA WdupStr Synopsis........Display string/attribute multiple times. Header File.....TCXLwin.h Prototype.......VOID CTYP WdupStrA(BytT wr, BytT wc, AtrT at, ChrP ps, IntT nd); VOID CTYP WdupStr(ChrP ps, IntT nd); Source File.....WIN\WDUPSTRA.C WIN\WDUPSTR.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ps - String to Display nd - Number of times to display string Returns.........None Notes...........Displays a string a specified number of times in the active window. WdupStrA() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. WdupStr() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. Page 112 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wprtc Wputc Synopsis........Display a character/attribute. Header File.....TCXLwin.h Prototype.......IntT CTYP Wprtc(BytT wr, BytT wc, AtrT at, ChrT ch); VOID CTYP Wputc(ChrT ch); Source File.....WIN\WPRTC.C WIN\WPUTC.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ch - Character to Display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Displays a character. Wprtc() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. Wputc() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. TesSeRact CXL V5.52 Documentation Page 113 --------------------------------------------------------------------------- Wprts Wputs Synopsis........Display a string/attribute. Header File.....TCXLwin.h Prototype.......IntT CTYP Wprts(BytT wr, BytT wc, AtrT at, ChrP ps); VOID CTYP Wputs(ChrP ps); Source File.....WIN\WPRTS.C WIN\WPUTS.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ps - String to Display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Displays a string. Wprts() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. Wputs() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. Page 114 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wprtns Wputns Synopsis........Display a padded string/attribute. Header File.....TCXLwin.h Prototype.......VOID CTYP Wprtns(BytT wr, BytT wc, AtrT at, ChrP ps, IntT wd); VOID CTYP Wputns(ChrP ps, IntT wd); Source File.....WIN\WPRTNS.C WIN\WPUTNS.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ps - String to Display wd - Width of Output String Returns.........None Notes...........Displays a string. The input width will determine how many characters are actually displayed. Wprtns() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. Wputns() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. --------------------------------------------------------------------------- Wputsw Synopsis........Display a string with line-wrap. Header File.....TCXLwin.h Prototype.......VOID CTYP Wputsw(ChrP ps); Source File.....WIN\WPUTSW.C Arguments.......ps - String to Display Returns.........None Notes...........Displays a string at the current window coordinates, using the current text attribute (See Appendix A). Words will be wrapped around to the next line if necessary. Control characters and escape sequences (See Appendix C) are recognized; Cursor position is updated. TesSeRact CXL V5.52 Documentation Page 115 --------------------------------------------------------------------------- Wprtf Wputf Synopsis........Display a formatted string/attribute. Header File.....TCXLwin.h Prototype.......IntT CDC Wprtf(BytT wr, BytT wc, AtrT at, ChrP fs, ...); IntT CDC Wputf(ChrP fs, ...); Source File.....WIN\WPRTF.C WIN\WPUTF.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) fs - Format String (See your compiler's documentation) ... - Additional Arguments Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates Notes...........Displays a formatted string to the active window. Works like the standard printf() function does. Wprtf() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. Wputf() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. Page 116 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- WprtFmt WputFmt Synopsis........Display a formatted string/attribute. Header File.....TCXLwin.h Prototype.......IntT CTYP WprtFmt(BytT wr, BytT wc, AtrT at, ChrP fs, ChrP ps); IntT CTYP WputFmt(ChrP fs, ChrP ps); Source File.....WIN\WPRTFMT.C WIN\WPUTFMT.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) fs - Format Control String (See Appendix D) ps - String to Display Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates W_INVFORMT - Invalid Format String W_STRLONG - String Could Not Fit In Window Notes...........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 '?'. WprtFmt() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. WputFmt() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. TesSeRact CXL V5.52 Documentation Page 117 --------------------------------------------------------------------------- WprtCen WputCen Synopsis........Displays a centered string/attribute. Header File.....TCXLwin.h Prototype.......IntT CTYP WprtCen(BytT wr, AtrT at, ChrP ps); IntT CTYP WputCen(ChrP ps); Source File.....WIN\WPRTCEN.C WIN\WPUTCEN.C Arguments.......wr - Window Row at - Attribute (See Appendix A) ps - String to Center Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates W_STRLONG - String Could Not Fit In Window Notes...........Centers a string in the active window. WprtCen() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. WputCen() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. Page 118 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Wprtrj Wputrj Synopsis........Display a string/attribute right-justified. Header File.....TCXLwin.h Prototype.......IntT CTYP Wprtrj(BytT wr, BytT wc, AtrT at, ChrP ps); IntT CTYP Wputrj(ChrP ps); Source File.....WIN\WPRTRJ.C WIN\WPUTRJ.C Arguments.......wr - Window Row wc - Window Column at - Attribute (See Appendix A) ps - String to Justify Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_INVCOORD - Invalid Coordinates W_STRLONG - String Could Not Fit In Window Notes...........Right justifies a string in the active window. Wprtrj() displays at the specified coordinates, using the specified attribute (See Appendix A); control characters and escape sequences are NOT recognized; cursor position is NOT updated. Wputrj() displays at the window's current text attribute; control characters and escape sequences (See Appendix C) are recognized; cursor position is updated. Window Internals --------------------------------------------------------------------------- WchkBox (Internal) Synopsis........Check for valid box coordinates Header File.....TCXLwin.h Prototype.......IntT CTYP WchkBox(BytT sr, BytT sc, BytT er, BytT ec); --------------------------------------------------------------------------- WchkCol (Internal) Synopsis........Check for valid column position. Header File.....TCXLwin.h Prototype.......IntT CTYP WchkCol(BytT wc); TesSeRact CXL V5.52 Documentation Page 119 --------------------------------------------------------------------------- WchkPos (Internal) Synopsis........Check for valid position. Header File.....TCXLwin.h Prototype.......IntT CTYP WchkPos(BytT wr, BytT wc); --------------------------------------------------------------------------- WchkRow (Internal) Synopsis........Check for valid row. Header File.....TCXLwin.h Prototype.......IntT CTYP WchkRow(BytT wr); Page 120 TesSeRact CXL V5.52 Documentation Input System The Input System is designed to provide a consistent interface between the keyboard/mouse and the display/window. By calling the functions in this section, keys are correctly translated, echoed to the appropriate location on the window and/or display, and buffered appropriately. Using the Line Input routines (KvGetFmt() and KwGetFmt()) is similar to using the Entry System. Some additional Format Control Characters are available; see Appendix D for details. There are two main types of input routines that echo to the display; we have the Kw...() series that echoes to the current active window, and the Kv...() series that writes to the default video device, using _StdOut() and _StdOuts(). The prototypes for the two types of routines are identical, and we will combine their descriptions by function. Input System Routines --------------------------------------------------------------------------- KwGetCf KvGetCf Synopsis........Get a character (via a format string) from the keyboard with echo. Header File.....TCXLinp.h Prototype.......IntT CTYP KwGetCf(ChrP v, ChrT d); IntT CTYP KvGetCf(ChrP v, ChrT d); Source File.....INP\KWGETCF.C INP\KVGETCF.C Arguments.......v - Valid Character String d - Default Selection Returns.........The ASCII value of the key pressed, or a zero if an error occurred. On error, TcxlErr contains: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed Notes...........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 current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. TesSeRact CXL V5.52 Documentation Page 121 --------------------------------------------------------------------------- KwGetCh KvGetCh Synopsis........Get a character from the keyboard, with echo. Header File.....TCXLinp.h Prototype.......ChrT CTYP KwGetCh(NOARG); ChrT CTYP KvGetCh(NOARG); Source File.....INP\KWGETCH.C INP\KVGETCH.C Arguments.......None. Returns.........The ASCII value of the key pressed, or a zero if an error occurred. On error, TcxlErr contains: W_NOACTIVE - No Active Window Notes...........Gets a character from the keyboard. Entered characters will be echoed to the active window using the current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. Page 122 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- KwGetFmt KvGetFmt Synopsis........Get a formatted string from the keyboard, with echo. Header File.....TCXLinp.h Prototype.......IntT CTYP KwGetFmt(ChrP s, ChrP f); IntT CTYP KvGetFmt(ChrP s, ChrP f); Source File.....INP\KWGETFMT.C INP\KVGETFMT.C Arguments.......s - Buffer To Receive Input String f - Format String (See Appendix D) Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed W_INVFORMT - Invalid Format String Notes...........Inputs a formatted string from the keyboard. Entered characters will be echoed to the active window using the current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. These functions provide 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. Using these functions is virtually the same as creating a single-field entry form, in the Entry System. These functions use the same primitives, but provide a convenient access to the high-level formatting routines. TesSeRact CXL V5.52 Documentation Page 123 --------------------------------------------------------------------------- KwGetSn KvGetSn Synopsis........Get a string from the keyboard, with maximum length, with echo. Header File.....TCXLinp.h Prototype.......IntT CTYP KwGetSn(ChrP s, IntT m); IntT CTYP KvGetSn(ChrP s, IntT m); Source File.....INP\KWGETSN.C INP\KVGETSN.C Arguments.......s - Buffer To Receive Input String m - Maximum Length of Input String Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed Notes...........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 current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. Page 124 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- KwGetSt KvGetSt Synopsis........Get a string from the keyboard, with echo. Header File.....TCXLinp.h Prototype.......IntT CTYP KwGetSt(ChrP ps); IntT CTYP KvGetSt(ChrP ps); Source File.....INP\KWGETST.C INP\KVGETST.C Arguments.......ps - Buffer To Receive Input String Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed Notes...........Gets a string from the keyboard. Entered characters will be echoed to the active window using the current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. TesSeRact CXL V5.52 Documentation Page 125 --------------------------------------------------------------------------- KwGetYn KvGetYn Synopsis........Get a Yes/No response from the keyboard, with echo. Header File.....TCXLinp.h Prototype.......ChrT CTYP KwGetYn(ChrT cd); ChrT CTYP KvGetYn(ChrT cd); Source File.....INP\KWGETYN.C INP\KVGETYN.C Arguments.......cd - The Default Value (0=No, 1=Yes) Returns.........'Y' if Yes was selected, an 'N' if No was selected, or a '\0' if the user pressed [Esc] and Escape checking was on. Notes...........Gets a [Y]es or [N]o response from the keyboard. Entered characters will be echoed to the active window using the current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. Please note that the "acceptable" values for this function are dependent on the NLS support provided under DOS. Examine the YnoT structure in FMT\_NLSINIT.C for specific country information. These functions always return 'Y' or 'N', no matter what language was detected with National Language Support. Page 126 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- KwScanf KvScanf Synopsis........Get a formatted input string, with echo. Header File.....TCXLinp.h Prototype.......IntT CDC KwScanf(ChrP fs, ...); IntT CDC KvScanf(ChrP fs, ...); Source File.....INP\KWSCANF.C INP\KVSCANF.C Arguments.......fs - Format String (see your compiler's documentation) ... - Additional Arguments Returns.........ERR_NUL - No Error ERR_ARG - Argument Failure TcxlErr contains: W_NOACTIVE - No Active Window W_ESCPRESS - The [Esc] Key Was Pressed Notes........... !!!!NOTE!!!! These functions are only available with the Turbo C versions of TCXL. Neither Microsoft C nor Zortech C/C++ provide the necessary vsscanf() function needed to implement this procedure. Inputs a formatted string from the keyboard. Entered characters will be echoed to the active window using the current text attribute (See Appendix A), or to the Standard Output device. Cursor position is updated. Escape checking is provided by default, but can be turned off with the WsetEsc() function. These functions work identical to the C library routine scanf(), except that input is done to the default window. TesSeRact CXL V5.52 Documentation Page 127 Strings System The Strings System supplements and augments the string-handling capabilities of your compiler's run-time library. Use it in good health. Strings System Routines Trimming --------------------------------------------------------------------------- strbtrim Synopsis........Trims both leading and trailing spaces off of a string. Header File.....TCXLstr.h Prototype.......ChrP strbtrim(ChrP s); Arguments.......s - String to Modify Returns.........The address of the input string. --------------------------------------------------------------------------- strltrim Synopsis........Trims the leading spaces off of a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strltrim(ChrP s); Source File.....STR\STRLTRIM.C Arguments.......s - String to Modify Returns.........Address of the modified string. --------------------------------------------------------------------------- strtrim strrtrim Synopsis........Trims the trailing spaces off of a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strtrim(ChrP s); ChrP strrtrim(ChrP s); Source File.....STR\STRTRIM.C Arguments.......s - String to Modify Returns.........Address of the modified string Page 128 TesSeRact CXL V5.52 Documentation Changing --------------------------------------------------------------------------- strchg strichg Synopsis........Finds all letters in a string matching one character and replaces them with another. strichg() ignores case when replacing. Header File.....TCXLstr.h Prototype.......IntT CTYP strchg(ChrP s, ChrT a, ChrT b); IntT CTYP strichg(ChrP s, ChrT a, ChrT b); Source File.....STR\STRCHG.C STR\STRICHG.C Arguments.......s - String to Search a - Character to Search For b - Character to Replace With Returns.........The number of matches found. --------------------------------------------------------------------------- strschg strischg Synopsis........Changes all occurrences of one string to another. strischg() ignores case when replacing. Header File.....TCXLstr.h Prototype.......ChrP CTYP strschg(ChrP s, ChrP a, ChrP b); ChrP CTYP strischg(ChrP s, ChrP a, ChrP b); Source File.....STR\STRSCHG.C STR\STRISCHG.C Arguments.......s - String to Search a - String to Search For b - String To Replace Found Strings With Returns.........The address of the modified string, or NULL if no matches were found. TesSeRact CXL V5.52 Documentation Page 129 Checksum --------------------------------------------------------------------------- strchksum strichksum Synopsis........Calculates the checksum of a string. Header File.....TCXLstr.h Prototype.......DwdT CTYP strchksum(ChrP s); DwdT CTYP strichksum(ChrP s); Source File.....STR\STRCHKSU.C STR\STRICHKS.C Arguments.......s - String to Checksum Returns.........The checksum of the input string. Notes...........Returns the checksum of a string. The checksum is calculated by adding up the ASCII values of each character in the string. If using strichksum(), all lower-case letters will be calculated as upper-case. Delete/Insert --------------------------------------------------------------------------- strdel stridel Synopsis........Deletes a substring from within a string. stridel() ignores case of letters. Header File.....TCXLstr.h Prototype.......ChrP CTYP strdel(ChrP a, ChrP s); ChrP CTYP stridel(ChrP a, ChrP s); Source File.....STR\STRDEL.C STR\STRIDEL.C Arguments.......a - Substring to Delete s - String to Delete From Returns.........Address of the modified string, or NULL if substring not found. Page 130 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- strdela stridela Synopsis........Deletes all occurrences of a substring from within a string. stridela() ignores case of letters. Header File.....TCXLstr.h Prototype.......ChrP CTYP strdela(ChrP a, ChrP s); ChrP CTYP stridela(ChrP a, ChrP s); Source File.....STR\STRDELA.C STR\STRIDELA.C Arguments.......a - Substring to Delete s - String to Delete From Returns.........Address of the modified string, or NULL if substring not found. --------------------------------------------------------------------------- strins Synopsis........Inserts one string into another. Header File.....TCXLstr.h Prototype.......ChrP CTYP strins(ChrP a, ChrP s, IntT p); Source File.....STR\STRINS.C Arguments.......a - String to Insert s - String to Receive Insertion p - Starting position Returns.........The address of the modified string. Notes...........Make sure the receiving buffer is large enough to hold the combined new string! TesSeRact CXL V5.52 Documentation Page 131 Inclusion --------------------------------------------------------------------------- strinc striinc Synopsis........Determines if and where one string is included within another. striinc() ignores case of letters. Header File.....TCXLstr.h Prototype.......ChrP CTYP strinc(ChrP a, ChrP s); ChrP CTYP striinc(ChrP a, ChrP s); Source File.....INC\STRINC.C INC\STRIINC.C Arguments.......a - String to search for s - String to search Returns.........A pointer to the location in 's' that contains 'a', or NULL if not found. --------------------------------------------------------------------------- strocc striocc Synopsis........Counts occurrences of a character in a string. striocc() ignores case of letters. Header File.....TCXLstr.h Prototype.......IntT CTYP strocc(ChrP s, ChrT c); IntT CTYP striocc(ChrP s, ChrT c); Source File.....INC\STROCC.C INC\STRIOCC.C Arguments.......s - String to Search c - Character to search for Returns.........The number of occurrences of the character in the string. Page 132 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- strsocc strisocc Synopsis........Counts occurrences of one string within another. strisocc() ignores case of letters. Header File.....TCXLstr.h Prototype.......IntT CTYP strsocc(ChrP a, ChrP s); IntT CTYP strisocc(ChrP a, ChrP s); Source File.....STR\STRSOCC.C STR\STRISOCC.C Arguments.......a - String to Search For s - String to Search Returns.........The number of times that string 'a' occurs in string 's'. Replacement --------------------------------------------------------------------------- strsrep strisrep Synopsis........Searches for, and replaces one string within another. strisrep() ignores case of letters. Header File.....TCXLstr.h Prototype.......ChrP CTYP strsrep(ChrP s, ChrP a, ChrP b); ChrP CTYP strisrep(ChrP s, ChrP a, ChrP b); Source File.....STR\STRSREP.C STR\STRISREP.C Arguments.......s - String to Search a - String to Search For b - String to Replace With Returns.........The address of the modified string, or NULL if the search string wasn't found. TesSeRact CXL V5.52 Documentation Page 133 Substrings --------------------------------------------------------------------------- strmid Synopsis........Create a new string from part of an input string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strmid(ChrP s, IntT p, IntT n); Source File.....STR\STRMID.C Arguments.......s - Input String p - Position to start copying n - Number of characters to copy Returns.........Address of the newly created string or a NULL if a memory allocation error occurred. Notes...........Takes a section from input string starting at given position and taking the given amount of characters creating a new string. Be sure to free() the string when or if you are finished with it. --------------------------------------------------------------------------- strleft strright Synopsis........Create a new string from left or right. Header File.....TCXLstr.h Prototype.......ChrP strleft(ChrP s, IntT n); ChrP strright(ChrP s, IntT n); Arguments.......s - Input String n - Number of Character to Copy Returns.........Address of the newly created string or a NULL if a memory allocation error occurred. Notes...........Takes a specified portion of a string from its left or right and creates a new string. Be sure to free() this string if or when you don't need it anymore. Page 134 TesSeRact CXL V5.52 Documentation Justification --------------------------------------------------------------------------- strljust strrjust Synopsis........Left or right justifies a text string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strljust(ChrP s); ChrP CTYP strrjust(ChrP s); Source File.....STR\STRLJUST.C STR\STRRJUST.C Arguments.......s - String to Justify Returns.........Address of the modified string. --------------------------------------------------------------------------- strrol strror Synopsis........Rotates a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strrol(ChrP s, IntT n); ChrP CTYP strror(ChrP s, IntT n); Source File.....STR\STRROL.C STR\STRROR.C Arguments.......s - String to Rotate n - Count to Rotate Returns.........Address of the modified string Notes...........Rotates a string specified number of characters left or right. The rotated characters wrap around to the opposite side of the string. TesSeRact CXL V5.52 Documentation Page 135 --------------------------------------------------------------------------- strshl strshr Synopsis........Shifts a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strshl(ChrP s, IntT n); ChrP CTYP strshr(ChrP s, IntT n); Source File.....STR\STRSHL.C STR\STRSHR.C Arguments.......s - String to Shift n - Character Count to Shift Returns.........Address of the Modified String Notes...........Shifts a string a specified number of characters left or right. Characters that shift past the beginning (or end) of the string "drop off" and spaces are added to the right (or left) of the string. Matching --------------------------------------------------------------------------- strbmatch Synopsis........Finds "best" match. Header File.....TCXLstr.h Prototype.......ChrP CTYP strbmatch(ChrP s, ChrP a[]); Source File.....STR\STRBMATC.C Arguments.......s - String to Match a - Array of pointers. The last pointer in the array must be NULL. Returns.........Address of the string in the array that best matched the given string. Page 136 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- strmatch Synopsis........Find match "score." Header File.....TCXLstr.h Prototype.......IntT CTYP strmatch(ChrP a, ChrP b); Source File.....STR\STRMATCH.C Arguments.......a - First String b - Second String Returns.........A match score. The higher the score, the better they match. The maximum possible score is strlen(a) + strlen(b). Miscellaneous --------------------------------------------------------------------------- strblank Synopsis........Determines if a given string is blank (whitespace). Header File.....TCXLstr.h Prototype.......IntT CTYP strblank(ChrP s); Source File.....STR\STRBLANK.C Arguments.......s - String to Check Returns.........TRUE if string is blank, FALSE otherwise --------------------------------------------------------------------------- strcode Synopsis........Encodes/decodes a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strcode(ChrP s, ChrP k); Source File.....STR\STRCODE.C Arguments.......s - String to encode k - Key String Returns.........The address of the input string Notes...........Call this function to encode a string, then call again using the same key to decode it. When reading or writing from a disk file, be sure to open the file in binary mode. TesSeRact CXL V5.52 Documentation Page 137 --------------------------------------------------------------------------- strsetsz Synopsis........Adjusts the length of a string. Header File.....TCXLstr.h Prototype.......ChrP CTYP strsetsz(ChrP s, IntT n); Source File.....STR\STRSETSZ.C Arguments.......s - Input String n - New Length Returns.........Address of the modified string. Notes...........Adjusts the length of a string, either by truncation or padding with spaces. Make sure the string is large enough to hold the entire buffer if it is expanded! --------------------------------------------------------------------------- struplow Synopsis........Converts a string to mixed upper & lowercase characters. Header File.....TCXLstr.h Prototype.......ChrP CTYP struplow(ChrP s); Source File.....STR\STRUPLOW.C Arguments.......s - String to Convert Returns.........Address of the modified string Notes...........Characters are forced to upper or lowercase depending upon the previous character in the string. Page 138 TesSeRact CXL V5.52 Documentation Cursor Control System The Cursor Control System provides access to hardware-specific display and mouse cursors, in a system-independent manner. Cursor Equates Mouse support level MOU_NONE....................................No mouse support MOU_KEYS..................................Emulate arrow keys MOU_CURS..........................Free-moving visible cursor MOU_FULL..................................Full mouse support Common Mouse Control Macros MOU_LBTN.........................................Left button MOU_RBTN........................................Right button MOU_MBTN.......................................Middle button MouLvl.........................................Current level MouInit..........................................Initialized Mou3btn.............................................3-button MouEnab..............................................Enabled MouDisa.............................................Disabled MouVisi.......................................Visible cursor MouHidd........................................Hidden cursor MouBtn....................................Button-status bits MouLbtn............................................Left down MouRbtn...........................................Right down MouMbtn..........................................Middle down MouBtnS..................................Saved Button-status MouLbtnS...........................................Left down MouRbtnS..........................................Right down MouMbtnS.........................................Middle down MouColS.........................................Saved column MouRowS............................................Saved row Cursor sizes for CurSize() CUR_NOR...................................Normal (underline) CUR_MID...........................................Half-block CUR_BLK...........................................Full-block Cursor states for CurPush() CUR_HID...............................................Hidden CUR_SHO................................................Shown CUR_MAX.....................................Max stack levels TesSeRact CXL V5.52 Documentation Page 139 Cursor Control Routines Mouse Cursor --------------------------------------------------------------------------- MouHide MouShow Synopsis........Conditional hide/show of the mouse cursor. Header File.....TCXLcur.h Prototype.......VOID PAS MouHide(NOARG); VOID PAS MouShow(NOARG); Source File.....CUR\MOUHIDE.ASM Arguments.......None. Returns.........None. Notes...........If mouse is enabled and the cursor is visible, MouHide() will hide the cursor; if the cursor is hidden and MOU_CURS or MOU_FULL, the cursor is conditionally shown. These functions maintain an internal count, so that repetitive calls to MouHide() do not cause the cursor to be displayed at the first MouShow() call; instead, the cursor is shown at the same level it was originally hidden. --------------------------------------------------------------------------- MouPush MouPop Synopsis........Push/Pop current mouse state on internal stack, clearing all status bits if the support level changed. Header File.....TCXLcur.h Prototype.......VOID CTYP MouPush(BytT s); VOID CTYP MouPop(NOARG); Source File.....CUR\MOUPUSH.C Arguments.......s - New Mouse State Returns.........None. Page 140 TesSeRact CXL V5.52 Documentation Display Cursor --------------------------------------------------------------------------- CurHide CurShow Synopsis........Hide/Show video display cursor. Header File.....TCXLcur.h Prototype.......VOID CTYP CurHide(NOARG); VOID CTYP CurShow(NOARG); Source File.....CUR\CURPUSH.C Arguments.......None. Returns.........None. --------------------------------------------------------------------------- CurPush CurPop Synopsis........Push/Pop current cursor state on internal stack, resetting all internal variables and visible cursor. Header File.....TCXLcur.h Prototype.......VOID CTYP CurPush(IntT h, IntT s, IntT r, IntT c); VOID CTYP CurPop(NOARG); Source File.....CUR\CURPUSH.C Arguments.......h - Hidden/Shown state s - Cursor Size r - Row position c - Column Position Returns.........None. --------------------------------------------------------------------------- CurSave CurSize Synopsis........Change cursor size or preserve cursor state. Header File.....TCXLcur.h Prototype.......VOID CurSave(NOARG); VOID CTYP CurSize(IntT s); Source File.....CUR\CURPUSH.C Arguments.......s - CUR_NOR, CUR_MID or CUR_BLK. Returns.........None TesSeRact CXL V5.52 Documentation Page 141 Mouse Control Routines --------------------------------------------------------------------------- MSclear Synopsis........Clear internal mouse button counts and update position. Header File.....TCXLmou.h Prototype.......VOID PAS MSclear(NOARG); Source File.....MOU\MOUHOME.ASM --------------------------------------------------------------------------- MSdelay Synopsis........Set mouse response-delay time. Header File.....TCXLmou.h Prototype.......VOID MSdelay(BytT d) Macro...........#define MSdelay(d) if(MouInit) MouDel = (d) Arguments.......d - Mouse response delay (default is 3) Returns.........None. --------------------------------------------------------------------------- MSdisab MSenab Synopsis........Disable/Enable global mouse support. Header File.....TCXLmou.h Prototype.......VOID MSdisab(NOARG); VOID MSenab(NOARG); Macro...........#define MSdisab() (MouFlg &= ~MOU_ENAB) #define MSenab() if(MouInit) MouFlg |= MOU_ENAB --------------------------------------------------------------------------- MShome Synopsis........Clear internal mouse button counts and home mouse to center of display Header File.....TCXLmou.h Prototype.......VOID PAS MShome(NOARG); Source File.....MOU\MOUHOME.ASM Page 142 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- MSkeys Synopsis........Assign keycodes to mouse buttons (used with MOU_KEYS and MOU_CURS only). Pass 0xFFFF to not set a particular key. Header File.....TCXLmou.h Prototype.......VOID PAS MSkeys(KeyT l, KeyT r, KeyT m); Source File.....MOU\MSKEYS.ASM Arguments.......l - Keycode for Left Button r - Keycode for Right Button m - Keycode for Middle Button Returns.........None. TesSeRact CXL V5.52 Documentation Page 143 Format Control Subsystem The Format Control Subsystem is used by both the Entry System and the Input System to handle keyboard input in formatted fields (KvGetFmt(), KwGetFmt(), and, of course, EntGet()). This subsystem is also the home of TCXL's National Language Support. There are 3 possible usage-states, and in the equates described below, they are marked as shown in each description. a) FMT_VID......Input with echo to default video. (VID) b) FMT_WIN......Input with echo or output to active window. (WIN) c) FMT_ENT......input/output within the data-entry system. (ENT) The format options are toggled on or off by "!..!" format-string sequences, where valid option characters, depending on usage-state are: Option Char VID WIN ENT '-' Decrement attribute X X '+' Increment attribute X X 'Aa' Set attribute 'a' X X FMT_LWR 'L' Convert to lower-case X X X FMT_MIX 'M' Convert to mixed-case X X X FMT_PAS 'P' Mask password field X X X FMT_UPR 'U' Convert to upper-case X X X FMT_CPY 'C' Copy strings to output X X FMT_ESC 'E' Detect [Esc] key X X FMT_RTN 'R' Detect [Enter] key X X Default initial option-state also depends on usage: a) FMT_VID - No options enabled. b) FMT_WIN - [Esc] detection enabled unless suppressed by WctlEsc. c) FMT_ENT - Both [Enter] and [Esc] detection enabled. For FMT_ENT usage, additional initial option values are set by the field feature-mask. Page 144 TesSeRact CXL V5.52 Documentation Input character validation is specified, one input position at a time, by one of the following format-string constructs: a) An inclusion-set, enclosed in '<>', where the input character must be a member of the set. b) An exclusion-set, enclosed in '[]', where the input character must NOT be a member of the set. c) A format-type character, where the input character must be one of those specified: 'A'....Alphabetic 'X'....Alphanumeric 'D'....Date 'Y'....Yes/No (NLS dependent) 'F'....Valid filename '#'....Numeric 'H'....Hexadecimal '%'....Numeric or space 'L'....Lower-case '*'....ASCII printable 'M'....Mixed-case '?'....Any character 'P'....Password '9'....Decimal numeric 'T'....Telephone '.'....Decimal point 'U'....Upper-case '$'....Decimal currency 'W'....Filename with wildcards Decimal fields specified by '9', '.' and '$' are formatted and handled only for FMT_ENT usage at present. Any 'L', 'M' and 'U' conversion specified by either format option or format-type character is done BEFORE validating an input character. Format-strings may also include quoted strings (which are copied to the output if FMT_CPY is in effect), NewLines to format multi-line fields, and spaces for readability. Any other character is invalid. National Language Support A quick word about TCXL's National Language Support is in order at this point. Most of the controlling information is stored in FMT\_NLSINIT.C. Most of the support for languages other than English is derived from the built-in support in DOS 3.3 and later, with some enhancements. This implementation REQUIRES MS/PC-DOS 3.30 or higher and will exit with an error at a lower DOS revision or if a DOS error occurs during startup (to allow programs to run under DOS versions prior to 3.30, call TcxlNlsOff() (Page 15) prior to calling TcxlInit()(Page 14). NLS defaults to United States/Canadian (English); however, if DOS 3.3 extended country support indicates a different country code, the current country information is used. TesSeRact CXL V5.52 Documentation Page 145 The NlsIs???() and NlsTo???() functions map extended ASCII (above 0x7F ONLY. They are only searched after an ASCII isupper(), etc., fails and are used to: a) translate characters between cases b) determine if a character is alphabetic or printable. The NLS case-map table is 256 bytes long. It contains 128 pairs of chars, which map any country-dependent upper/lower case non-ASCII characters above 0x7F, [0x80..0xFF]. Each pair consists of an uppercase, then a lowercase char, if any exist for the value of the pair, otherwise both chars are 0x00. It is searched AFTER an ASCII isupper(), etc. fails. _NlsInit() builds the table from the UCase table returned as part of the DOS Extended Country information. The NLS print-map is a NUL-terminated string of non-alphabetic, non-ASCII chars above 0x7F that are to be considered printable (punctuation, diacriticals, currency symbols, etc.). It is searched AFTER the complete case-map by NlsIsPrn(). MLS_ML_PRN defines a print-map for the IBM Multi- lingual code-page (850). It (or any user-defined, NUL-terminated print-map string of chars) may be assigned in place of the default US/CDN print-map any time after TcxlInit() is called via the NlsPrn access-macro. The default map contains: "\x9B\x9C\x9D\x9E\x9F\xA7\xAD\x00". National-language Access Macros NlsPag......................................Global code-page NlsCty..........................................Country-code NlsSym.......................................Currency symbol NlsSyl................................................Length NlsDsc.....................................Decimal separator NlsTsc...................................Thousands separator NlsDtc........................................Date separator NlsTmc........................................Time separator NlsNdp........................................Decimal places NlsLsc........................................List separator NlsYes..................................Uppercase 'Yes' char NlsNo ...................................Uppercase 'No' char NlsUpl.....................................Extended case-map NlsPrn....................................Extended print-map Format Control Equates FmtSet/FmtOpt option bits FMT_LWR............................'L' Convert to lower case FMT_MIX............................'M' Convert to mixed case FMT_UPR............................'U' Convert to upper case FMT_PAS.......................'P' Password -- masked display FMT_CPY............................'C' Copy to output (!ENT) FMT_ESC..............................'E' [Esc] detect (!ENT) FMT_RTN...............................'R' [CR] detect (!ENT) FMT_EOF........................................End-of-format FMT_FIN.........................End | 'R' - Done with format Page 146 TesSeRact CXL V5.52 Documentation FmtUse usage-bits FMT_VID...............................KvGetFmt(), etc. (VID) FMT_WIN...............................KwGetFmt(), etc. (WIN) FMT_ENT.................................EntFld(), etc. (ENT) FMT_USE...........................................Usage mask FMT_PUT..........................................Output mode FMT_DEC..................................Decimal field (ENT) FMT_CUR.................................Currency field (ENT) FMT_INP.................................Input to field (ENT) FMT_CHK.............................Validation pending (ENT) FMT_PND.......................Input/validation pending (ENT) FmtFlg transient-flag bits FMT_MOD...................................Display-mode (ENT) FMT_INI..............................................Initial FMT_CHG...............................................Change FMT_CND...................................Conditional-update FMT_DSP...............................Re-display field (ENT) FMT_INS.......................................Insert mode ON FMT_WRP.....................................Field-wrap (ENT) FMT_PRV................................End of previous field FMT_NXT..................................Start of next field TesSeRact CXL V5.52 Documentation Page 147 _FmtCtl Access Macros FmtSep.......................................Word-separators FmtGet........................................Input function FmtVal......................................"Valid" function FmtFmt.........................................Format string FmtPtr........................................Format pointer FmtBfr.........................................Buffer string FmtOrg.......................................Screen position FmtOrgW.................................................Word FmtOrgR..................................................Row FmtOrgC..................................................Col FmtPos.......................................Cursor position FmtPosW.................................................Word FmtRow...................................................Row FmtCol...................................................Col FmtLen..........................................Field length FmtOfs........................................Current offset FmtExt..........................................Input-extent FmtDot........................................Decimal offset FmtErr..........................................Error offset FmtChr..................................Field-fill character FmtMsk....................................Password mask char FmtAtr.......................................Field attribute FmtSet.......................................Initial options FmtOpt..........................................Option state FmtLwr............................................Lower case FmtMix............................................Mixed case FmtUpr............................................Upper case FmtPas.........................................Password mask FmtCpy........................................Copy to output FmtEsc..........................................[Esc] detect FmtRtn........................................[Enter] detect FmtEof.........................................End-of-format FmtFin......................................Done with format FmtUse...........................................Usage state FmtVid.......................................KvGetFmt(), etc FmtWin.......................................KwGetFmt(), etc FmtEnt.....................................EntDsp()/EntGet() FmtPut...........................................Output mode FmtDec.........................................Decimal field FmtCur........................................Currency field FmtInp.................................................Input FmtChk............................................Validation FmtPnd...............................................Pending FmtFlg.......................................Transient flags FmtMod..........................................Display mode FmtIni...............................................Initial FmtChg................................................Change FmtCnd...........................................Conditional FmtDsp......................................Re-display field FmtIns........................................Insert mode ON FmtWrp............................................Field-wrap FmtPrv..............................................Previous FmtNxt..................................................Next Page 148 TesSeRact CXL V5.52 Documentation NLS Routines --------------------------------------------------------------------------- NlsIsAlpha NlsIsPrint NlsIsLower NlsIsUpper Synopsis........Determines if the passed character is alphanumeric, printable, upper case or lower case. These functions correctly interpret international characters. Header File.....TCXLnls.h Prototype.......FlgT CTYP NlsIsAlpha(ChrT c); FlgT CTYP NlsIsPrint(ChrT c); FlgT CTYP NlsIsLower(ChrT c); FlgT CTYP NlsIsUpper(ChrT c); Source File.....FMT\NLSISALP.C Arguments.......c - Character to test Returns.........TRUE if passes test, FALSE otherwise. --------------------------------------------------------------------------- NlsToLower NlsToUpper Synopsis........Converts a character to upper or lower case, correctly interpreting international characters. Header File.....TCXLnls.h Prototype.......ChrT CTYP NlsToUpper(ChrT c); ChrT CTYP NlsToLower(ChrT c); Source File.....FMT\NLSISALP.C Arguments.......c - Character to convert. Returns.........Converted character. TesSeRact CXL V5.52 Documentation Page 149 Format Control Routines Please note that ALL of the routines in the Format Control Subsystem are internal, and not to be called by user programs. --------------------------------------------------------------------------- cvtic cvtci Synopsis........Convert Integer to TCXL field string, or convert string to integer. Header File.....TCXLfmt.h Prototype.......VOID CTYP cvtic(ChrP fp, IntT iv, IntT fs); IntT CTYP cvtci(ChrP fp); Source File.....FMT\CVTIC.C FMT\CVTCI.C Arguments.......fp - Buffer to hold field string iv - Integer value to convert fs - Field size (width) Returns.........cvtci() returns the value of the passed field string. Notes...........cvtic() will right justify the integer value in the buffer passed. The field size parameter should match the maximum number of digits of input permitted during EntGet processing. Make sure that memory has been allocated to <fp> to hold the entire field, as well as the trailing NULL. Page 150 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- cvtfc cvtcf Synopsis........Convert floating point value to TCXL field string, or convert string to floating point number. Header File.....TCXLfmt.h Prototype.......VOID CTYP cvtfc(ChrP p, DblT v, IntT w, IntT d); DblT CTYP cvtcf(ChrP p); Source File.....FMT\CVTFC.C FMT\CVTCF.C Arguments.......p - Buffer to hold field string v - Floating point value to convert w - Field size (width) Returns.........cvtcf() returns the value of the passed field string. Notes...........cvtfc() will right justify the floating point value in the buffer passed, padding with zeros to the number of decimal places specified. The field size parameter should match the maximum number of digits of input permitted during EntGet processing. Make sure that memory has been allocated to <p> to hold the entire field, as well as the trailing NULL. --------------------------------------------------------------------------- _FmtAttr (Internal) Synopsis........Assign a field attribute. Header File.....TCXLfmt.h Prototype.......VOID _FmtAttr(AtrT c); --------------------------------------------------------------------------- _FmtChar (Internal) Synopsis........Validate character <c> against TCXL format-string at FmtPtr. Header File.....TCXLfmt.h Prototype.......FlgT CTYP _FmtChar(ChrT c); Source File.....FMT\_FMTINIT.C --------------------------------------------------------------------------- _FmtFill (Internal) Synopsis........Assign field fill character. Header File.....TCXLfmt.h Prototype.......VOID _FmtFill(ChrT c); TesSeRact CXL V5.52 Documentation Page 151 --------------------------------------------------------------------------- _FmtFunc (Internal) Synopsis........Assign input function for formatted-field input. If <gf> is NULL, restore default input function [KeyGetc()]. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtFunc(KfvCP gf); Source File.....FMT\_FMTSEPS.C --------------------------------------------------------------------------- _FmtGetc (Internal) Synopsis........Return next input key and display TCXL format-string input- field with updated cursor position, performing all cursor- movement and validating input characters. Header File.....TCXLfmt.h Prototype.......KeyT CTYP _FmtGetc(NOARG); Source File.....FMT\_FMTGETC.C --------------------------------------------------------------------------- _FmtGets (Internal) Synopsis........Get input string to <s> with echo, following TCXL format string <f>. Return TRUE on [Enter] or null <s> and return FALSE on [Esc] ending the field. Header File.....TCXLfmt.h Prototype.......FlgT CTYP _FmtGets(ChrP s, ChrP f); Source File.....FMT\_FMTGETS.C --------------------------------------------------------------------------- _FmtInit (Internal) Synopsis........Verify TCXL format string <fs> for usage <us>. Return 0 on failure, else initialize globals in FmtCtl object and return field length. Header File.....TCXLfmt.h Prototype.......IntT CTYP _FmtInit(ChrP fs, BytT us); Source File.....FMT\_FMTINIT.C --------------------------------------------------------------------------- _FmtMask (Internal) Synopsis........Assign password mask character. Header File.....TCXLfmt.h Prototype.......VOID _FmtMask(ChrT c); Page 152 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- _FmtOpts (Internal) Synopsis........Toggle all TCXL "!..!" format-string options at FmtPtr, through tail '!' and update FmtPtr past tail '!'. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtOpts(NOARG); Source File.....FMT\_FMTINIT.C --------------------------------------------------------------------------- _FmtPuts (Internal) Synopsis........Display current field-buffer using TCXL format-string Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtPuts(NOARG); Source File.....FMT\_FMTPUTS.C --------------------------------------------------------------------------- _FmtSeps (Internal) Synopsis........Assign alternate word-separation string <ws>. If <ws> is NULL, restore default string. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtSeps(ChrP ws); Source File.....FMT\_FMTSEPS.C --------------------------------------------------------------------------- _FmtVali (Internal) Synopsis........Validate current TCXL format-string input-field. Header File.....TCXLfmt.h Prototype.......FlgT CTYP _FmtVali(NOARG); Source File.....FMT\_FMTVALI.C --------------------------------------------------------------------------- _FmtClr (Internal) Synopsis........Clear buffer from offset <o> to end and update global FmtExt. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtClr(IntT o); Source File.....FMT\_FMTCPY.C TesSeRact CXL V5.52 Documentation Page 153 --------------------------------------------------------------------------- _FmtCpy (Internal) Synopsis........Copy string <s> to cleared buffer, limiting length and set global FmtExt. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtCpy(ChrP s); Source File.....FMT\_FMTCPY.C --------------------------------------------------------------------------- _FmtCur (Internal) Synopsis........Display initial national-language currency-symbol prefix/suffix and update current cursor and/or screen positions. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtCur(NOARG); Source File.....FMT\_FMTDEC.C --------------------------------------------------------------------------- _FmtDec (Internal) Synopsis........Format decimal/currency field with blank-fill left of point, zero-fill right of point and national-language decimal/currency separator. Update global input-extent FmtExt. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtDec(NOARG); Source File.....FMT\_FMTDEC.C --------------------------------------------------------------------------- _FmtDel (Internal) Synopsis........Delete <n> chars from buffer at offset <o> and update global FmtExt. Also delete any spurious points from decimal fields. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtDel(IntT o, IntT n); Source File.....FMT\_FMTCPY.C Page 154 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- _FmtIns (Internal) Synopsis........Insert <n> blanks in buffer at offset <o> and update global FmtExt. Header File.....TCXLfmt.h Prototype.......VOID CTYP _FmtIns(IntT o, IntT n); Source File.....FMT\_FMTCPY.C --------------------------------------------------------------------------- _FmtPos (Internal) Synopsis........Update TCXL format-string pointer, cursor-position and buffer offset to next field input position at or past offset <o>. Return updated buffer offset. Header File.....TCXLfmt.h Prototype.......IntT CTYP _FmtPos(IntT o); Source File.....FMT\_FMTPOS.C --------------------------------------------------------------------------- _FmtSpa (Internal) Synopsis........Return TRUE if buffer is clear from offset <o>, else FALSE. Header File.....TCXLfmt.h Prototype.......FlgT CTYP _FmtSpa(IntT o); Source File.....FMT\_FMTCPY.C --------------------------------------------------------------------------- _NlsInit (Internal) Synopsis........Install National Language Support. Header File.....TCXLnls.h Prototype.......WrdT CTYP _NlsInit(NOARG); Source File.....FMT\_NLSINIT.C --------------------------------------------------------------------------- _NlsGet (Internal) Synopsis........Get DOS international language control block. Header File.....TCXLnls.h Prototype.......WrdT PAS _NlsGet(BytP b); Source File.....FMT\_NLSGET.ASM TesSeRact CXL V5.52 Documentation Page 155 Selection Engine Subsystem The Selection Engine Subsystem forms the heart of TCXL's user-level systems. It is used internally to manipulate both selection bars and mouse "hot" spots throughout the high level operations. Please note that this is for internal use, and not designed to be called by user programs. Selection Equates EngFlg and EngFut flag settings ENG_HOR...........................................Horizontal ENG_VER.............................................Vertical ENG_OMN.....................................Multidirectional ENG_BDR.........................................Mouse Arrows ENG_PGU.........................................PgUp Allowed ENG_PGD.........................................PgDn Allowed ENG_WRA..........................................Wrap cursor ENG_HOT......................................Mouse PgUp/PgDn ENG_NOA.................................No Arrow Translation _Elst Access Macros EngPos(e)................................Item position array EngPosI(e,i)...................................Item position EngRowI(e,i)........................................Item row EngColI(e,i).....................................Item column EngLen(e)..................................Item length array EngLenI(e,i).....................................Item length EngRet(e)..........................Pointer to return keycode EngRetP(e)............................Return keycode storage EngCnt(e)............................Number of items on page EngWid(e)..........................Number of columns on page EngCur(e)...............................Initial Item on page EngBef(e)........................Function to call before bar EngAft(e).........................Function to call after bar EngBln(e).............................Width of Selection Bar EngWat(e)........................Attribute of Current Window EngSat(e).........................Attribute of Selection Bar EngQat(e)........................Attribute of Quick-Sel Char EngFlg(e)........................Page Selection Engine Flags EngHor(e)...............................Horizontal Selection EngVer(e).................................Vertical Selection EngBoth(e)..................................Multidirectional EngBdr(e).............................Mouse Arrows on Border EngPgUp(e)..............................Previous Page Exists EngPgDn(e)..................................Next page Exists EngWrap(e).......................................Wrap cursor EngHot(e)..........................Mouse PgUp/PgDn on Border EngFut(e)...................................Additional Flags EngNoa(e)....................No left-to-up arrow translation Page 156 TesSeRact CXL V5.52 Documentation Selection Engine Routines --------------------------------------------------------------------------- _SelPag (Internal) Synopsis........Internal selection engine for all systems. Returns current item index, and the activating return keycode in the pointer sret. Header File.....TCXLeng.h.h Prototype.......IntT CTYP _SelPag(ElstP e); Source File.....ENG\_SELPAG.C --------------------------------------------------------------------------- _SelMou (Internal) Synopsis........Determine if mouse event occurred on item in passed location array. Return index into the array. Header File.....TCXLeng.h Prototype.......IntT CTYP _SelMou(VposP pos, BytP len, IntT cnt); Source File.....ENG\_SELMOU.C TesSeRact CXL V5.52 Documentation Page 157 Display Subsystem The display system is designed to be used for output to the video display that is NOT window-oriented. It is separated from the physical display, and it is also used by the Window System and the User Level systems. It is not necessary to call any functions provided in this system from most programs. There are User Level and Service Level functions to provide functionality that precludes the use of the functions here. Although the routines here are portable, they are one step closer to the display hardware, and therefore, should be avoided by most programs. The DOS-specific Ultravision Support functions are described in Appendix G. Display Equates Supported adapter types (MS-DOS) V_NONE..................................................None V_MDA ......................................Vanilla MDA/mono V_EGAMONO...........................................EGA/mono V_MCGAMONO.........................................MCGA/mono V_VGAMONO...........................................VGA/mono V_HGC ..............................................Hercules V_HGCPLUS......................................Hercules Plus V_INCOLOR...................................Hercules Incolor V_CGA ...........................................Vanilla CGA V_EGA .............................................EGA/color V_MCGA............................................MCGA/color V_VGA .............................................VGA/color VidParm() video parameters (MS-DOS) VP_DMA..................................Direct screen writes VP_CGA............................Direct writes, no CGA snow VP_BIO....................................BIOS screen writes VP_MON...........................Mono attribute translate on VP_COL..........................Mono attribute translate off VidFlg bits (MS-DOS) VF_MON............................................Monochrome VF_MAP...........................................Map to mono VF_CGA.....................................Suppress CGA snow VF_BIO........................................Use video BIOS VF_DQV............................DesqView/Windows installed Page 158 TesSeRact CXL V5.52 Documentation Box-border types BOX_SNG...........................................all single BOX_DBL...........................................all double BOX_VER............................horiz single, vert double BOX_HOR............................horiz double, vert single BOX_HVY..........................................heavy lines BOX_SPA......................................spaces [no box] BOX_EXP...........................exploding Wopen()/WpopUp() Video Cursor Object VcseW(x)........................................Overlay word VcseE(x)...........................................Stop line VcseB(x)..........................................Start line _Vctl Access Macros VidSeg........................................Buffer segment VidHdw..........................................Adapter type VidMod..........................................Display mode VidFlg.................................................Flags VidMon............................................Monochrome VidMap...........................................Map to mono VidCga..............................................CGA snow VidBio..............................................Use BIOS VidDqv..............................................DesQview VidPag..........................................Display page VidWid..........................................Columns wide VidDep.............................................Rows deep VidCur...........................................Cursor save VidPos.........................................Line-position VidPosW.................................................Word VidPosC...............................................Column VidPosR..................................................Row VidLen...........................................Line-length VidBfr...........................................Line-buffer VidBfrW(b)..................................Word (b => cell) VidBfrC(b)..............................................Char VidBfrA(b)..............................................Attr TesSeRact CXL V5.52 Documentation Page 159 Display Routines Video Control --------------------------------------------------------------------------- VidMode Synopsis........Get/Set display mode Header File.....TCXLvid.h Prototype.......BytT PAS VidMode(IntT m); Source File.....DSP\VIDMODE.ASM Arguments.......m - New Video Mode, or 0xFF to return current mode. Returns.........Current or New Video Mode Notes...........This function either gets the current video mode (if the passed parameter is 0xFF), or it sets the display mode to the passed parameter. In either case, the _VidCtl (See User's Guide) structure is updated. Please note that the "video mode" passed here is completely hardware/system dependent, and therefore this function should not be used when portability is a factor. --------------------------------------------------------------------------- VidOfs Synopsis........Calculate offset into screen buffer. Header File.....TCXLvid.h Prototype.......WrdT VidOfs(IntT r, IntT c); Arguments.......r - Screen Row c - Screen Column Returns.........The offset into the video display buffer of the passed cursor coordinates. --------------------------------------------------------------------------- VidParm Synopsis........Set video display parameters. Header File.....TCXLvid.h Prototype.......IntT CTYP VidParm(IntT p); Source File.....DSP\VIDPARM.C Arguments.......p - Video Display Parameter (VP_????) (See page 158) Returns.........Nonzero if invalid parameter. Page 160 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- VposDec VposInc Synopsis........Increments/Decrements both the row and column members of a VposT union. Header File.....TCXLvid.h Prototype.......VOID VposDec(VposT v); VOID VposInc(VposT v); Arguments.......v - A VposT object. Returns.........None. Notes...........Provided for portability purposes, where the VcelT object is not necessarily a Word. --------------------------------------------------------------------------- VsetLin Synopsis........Set screen lines. Header File.....TCXLvid.h Prototype.......IntT CTYP VsetLin(IntT n); Source File.....DSP\VSETLIN.C Arguments.......n - Number of lines (only 25, 43 and 50 are valid). Returns.........Nonzero if invalid line value. Notes...........Sets the number of lines on the display. If UltraVision (under DOS) has been detected, this function calls _VuvSet() (Page (?)). Boxes, Clearing and Filling --------------------------------------------------------------------------- Vclear Synopsis........Clears the screen using the passed text attribute (See Appendix A) and homes the cursor. Header File.....TCXLvid.h Prototype.......VOID CTYP Vclear(AtrT a); Source File.....DSP\VCLEAR.C Arguments.......a - Attribute (See Appendix A) Returns.........None. TesSeRact CXL V5.52 Documentation Page 161 --------------------------------------------------------------------------- VclrBox Synopsis........Clears a section of the screen using the text attribute (See Appendix A) at the current cursor position. Header File.....TCXLvid.h Prototype.......VOID CTYP VclrBox(VposT s, VposT e); Source File.....DSP\VCLRBOX.C Arguments.......s - Start Position e - End Position Returns.........None. --------------------------------------------------------------------------- VclrEol Synopsis........Clears to the end of the video line using the text attribute (See Appendix A) under the cursor. Header File.....TCXLvid.h Prototype.......VOID CTYP VclrEol(NOARG); Source File.....DSP\VCLREOL.C Arguments.......None. Returns.........None. --------------------------------------------------------------------------- VclrScr Synopsis........Clears the screen using the text attribute (See Appendix A) under the cursor, and homes the cursor. Header File.....TCXLvid.h Prototype.......VOID CTYP VclrScr(NOARG); Source File.....DSP\VCLRSCR.C Arguments.......None. Returns.........None. Page 162 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- VdrwBox Synopsis........"Draws" a text box on the screen. Header File.....TCXLvid.h Prototype.......VOID VdrwBox(VposT s, VposT e, BytT b, AtrT a); Source File.....DSP\VDRWBOX.C Arguments.......s - Start Position e - End Position b - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] a - Attribute (See Appendix A) Returns.........None. --------------------------------------------------------------------------- VdrwHor Synopsis........Draws a horizontal line on the screen Header File.....TCXLvid.h Prototype.......VOID CTYP VdrwHor(VposT s, IntT l, BytT c, AtrT a); Source File.....DSP\VDRWHOR.C Arguments.......s - Start Position l - Length c - Character to use a - Attribute (See Appendix A) Returns.........None. TesSeRact CXL V5.52 Documentation Page 163 --------------------------------------------------------------------------- VdrwVer Synopsis........Draws a vertical line on the screen Header File.....TCXLvid.h Prototype.......VOID CTYP VdrwVer(VposT s, IntT l, BytT c, AtrT a); Source File.....DSP\VDRWVER.C Arguments.......s - Start Position l - Length c - Character to use a - Attribute (See Appendix A) Returns.........None. --------------------------------------------------------------------------- VexpBox Synopsis........Draws and fill an exploding text box. Header File.....TCXLvid.h Prototype.......VOID VexpBox(VposT sp, VposT ep, BytT bt, AtrT ba, ChrT fc, AtrT fa); Source File.....DSP\VEXPBOX.C Arguments.......sp - Start Position ep - End Position bt - Frame Type (One of the following) BOX_SNG..all single BOX_DBL..all double BOX_VER..horiz single, vert double BOX_HOR..horiz double, vert single BOX_HVY..heavy lines BOX_SPA..spaces [no box] ba - Frame Attribute (See Appendix A) fc - Fill Character fa - Fill Attribute Returns.........None. Page 164 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- VfilBox Synopsis........Fills in a region of the screen with a specified character and attribute (See Appendix A). Header File.....TCXLvid.h Prototype.......VOID VfilBox(VposT s, VposT e, ChrT c, AtrT a); Source File.....DSP\VFILBOX.C Arguments.......s - Start Position e - End Position c - Character to fill a - Attribute (See Appendix A) Returns.........None. --------------------------------------------------------------------------- VsavBox VlodBox Synopsis........Save a box-image to disk, or retrieve a box-image from disk. Header File.....TCXLvid.h Prototype.......IntT VsavBox(VposT s, VposT e, ChrP f); IntT CTYP VlodBox(ChrP f); Source File.....DSP\VSAVBOX.C DSP\VLODBOX.C Arguments.......s - Start Position e - End Position f - Filename Returns.........Nonzero on error --------------------------------------------------------------------------- VsavScr VlodScr Synopsis........Saves or restores a screen from disk. Header File.....TCXLvid.h Prototype.......IntT VsavScr(ChrP f); IntT VlodScr(ChrP f); Source File.....DSP\_VSAVSCR.C Arguments.......f - Filename Returns.........Nonzero on error TesSeRact CXL V5.52 Documentation Page 165 --------------------------------------------------------------------------- Vsave Vrestore Synopsis........Save or restore current video display to memory. Header File.....TCXLvid.h Prototype.......VcelP Vsave(NOARG); VOID Vrestore(VcelP b); Source File.....DSP\_VSAVE_.C Arguments.......b - Previously Saved Buffer Returns.........Address of the buffer save area, or NULL if a memory allocation error occurred. --------------------------------------------------------------------------- Vscroll Synopsis........Scroll a region of the display up or down. Header File.....TCXLvid.h Prototype.......VOID Vscroll(IntT d, VposT s, VposT e, IntT n, AtrT a); Source File.....DSP\VSCROLL.ASM Arguments.......d - Direction (0=down, 1=up) s - Upper Left Corner e - Lower Right Corner n - Number of Lines to Scroll a - Attribute (See Appendix A) to clear area to Returns.........None. Cursor Control --------------------------------------------------------------------------- VcurGet Synopsis........Reads the current cursor location. Header File.....TCXLvid.h Prototype.......VOID VcurGet(VposT v); Source File.....DSP\VCURGET.ASM Arguments.......v - Position Returns.........None. Page 166 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- VcurHid Synopsis........Hide or show the video cursor, and return the current cursor state. Header File.....TCXLvid.h Prototype.......IntT CTYP VcurHid(IntT s); Source File.....DSP\VCURHID.C Arguments.......s - Hide if zero, Show if positive, just return state if negative. Returns.........FALSE if previously hidden, TRUE if previously shown. --------------------------------------------------------------------------- VcurPut Synopsis........Set a new cursor position. Header File.....TCXLvid.h Prototype.......VOID VcurPut(VposT v); Source File.....DSP\VCURGET.ASM Arguments.......v - New Position Returns.........None. --------------------------------------------------------------------------- VcurSet Synopsis........Set the cursor size/shape. Header File.....TCXLvid.h Prototype.......VOID CTYP VcurSet(IntT s); Source File.....DSP\VCURSET.C Arguments.......s - Underline cursor if zero, block cursor otherwise. Returns.........None. TesSeRact CXL V5.52 Documentation Page 167 --------------------------------------------------------------------------- VcurSiz Synopsis........Sets and gets the current cursor size/shape. Header File.....TCXLvid.h Prototype.......VOID VcurSiz(VcseT c); Source File.....DSP\VCURSIZ.ASM Arguments.......c - If 0:0, return cursor start/stop lines; otherwise, set cursor shape. Returns.........Current Cursor Size --------------------------------------------------------------------------- Vgotoxy Synopsis........Sets the cursor position to the passed row/col coordinate. Header File.....TCXLvid.h Prototype.......VOID PAS Vgotoxy(IntT r, IntT c); Source File.....DSP\VGOTOXY.ASM Arguments.......r - Row c - Column Returns.........None. --------------------------------------------------------------------------- VposGet Synopsis........Reads the current cursor location. Header File.....TCXLvid.h Prototype.......VOID PAS VposGet(IntP r, IntP c); Source File.....DSP\VPOSGET.C Arguments.......r - Row c - Column Returns.........The current cursor location Page 168 TesSeRact CXL V5.52 Documentation Attribute Control --------------------------------------------------------------------------- VatrInv Synopsis........Returns the inverse of the given text attribute (See Appendix A). Header File.....TCXLvid.h Prototype.......IntT PAS VatrInv(AtrT a); Source File.....DSP\VATRINV.ASM Arguments.......a - Attribute (See Appendix A) to Invert Returns.........Inverted Attribute --------------------------------------------------------------------------- VatrMap Synopsis........Translate color attribute to monochrome mapping. Header File.....TCXLvid.h Prototype.......IntT CTYP VatrMap(AtrT a); Source File.....DSP\VATRMAP.ASM Arguments.......a - Attribute (See Appendix A) to translate Returns.........Monochrome Equivalent Notes...........Translates a color text attribute (See Appendix A) into its approximate monochrome equivalent. All of TCXL's video functions (where described) automatically call this, so you would only need to call this for your own functions. --------------------------------------------------------------------------- VatrRev Synopsis........Reverse <n> attributes Header File.....TCXLvid.h Prototype.......VOID CTYP VatrRev(IntT n); Source File.....DSP\VATRREV.C Arguments.......n - Count of Characters to Reverse Returns.........None. Notes...........Reverses the attribute (See Appendix A) of the character under the current cursor position, and continues for the specified number of characters. TesSeRact CXL V5.52 Documentation Page 169 --------------------------------------------------------------------------- VatrSet Synopsis........Set <n> Attributes. Header File.....TCXLvid.h Prototype.......VOID CTYP VatrSet(AtrT a, IntT n); Source File.....DSP\VATRSET.C Arguments.......a - Attribute (See Appendix A) to set n - Count of Characters to Set Returns.........None. Notes...........Sets the attribute (See Appendix A) of the character under the current cursor location, and continues for the specified number of characters. --------------------------------------------------------------------------- VatrTxt Synopsis........Converts an attribute (See Appendix A) to it's text-based equivalent. Header File.....TCXLvid.h Prototype.......ChrP CTYP VatrTxt(AtrT a); Source File.....DSP\VATRTXT.C Arguments.......a - Attribute (See Appendix A) Returns.........Static string with color text. --------------------------------------------------------------------------- Vattrib Synopsis........Construct an attribute from it's component parts. Header File.....TCXLvid.h Prototype.......IntT Vattrib(IntT f, IntT b, IntT i, IntT h); Arguments.......f - Foreground Color b - Background Color i - Intensity h - Blink Bit Returns.........The new attribute code Notes...........Creates a text attribute (See Appendix A). It is usually much easier to create a create attribute using the attribute identifiers listed in Appendix A, but this provides an alternate method. Page 170 TesSeRact CXL V5.52 Documentation Video Input --------------------------------------------------------------------------- Vgetw Synopsis........Get char/attr from screen as a VcelT object Header File.....TCXLvid.h Prototype.......VOID Vgetw(IntT r, IntT c, VcelT x); Arguments.......r - Row c - Column Returns.........x - VcelT from screen. --------------------------------------------------------------------------- Vgetc Synopsis........Get char from screen. Header File.....TCXLvid.h Prototype.......VOID Vgetc(IntT r, IntT c, ChrT x); Arguments.......r - Row c - Column Returns.........x - VcelT from screen. --------------------------------------------------------------------------- Vgets Synopsis........Get chars from screen for specified length. Header File.....TCXLvid.h Prototype.......VOID CTYP Vgets(IntT r, IntT c, ChrP b, IntT l); Source File.....DIO\VGETS.C Arguments.......r - Row c - Column b - Buffer to receive array l - Length Returns.........None. TesSeRact CXL V5.52 Documentation Page 171 --------------------------------------------------------------------------- Vgetb Synopsis........Get char/attr array from screen for specified length. Header File.....TCXLvid.h Prototype.......VOID CTYP Vgetb(IntT r, IntT c, ChrP b, IntT l); Source File.....DIO\VGETB.C Arguments.......r - Row c - Column b - Buffer to receive array l - Length Returns.........None. --------------------------------------------------------------------------- Vgetv Synopsis........Get vertical array of VcelT objects for specified length. If <f> is TRUE, get row-wise array of <l> by 2 cells, else array of <l> by 1 cell. Header File.....TCXLvid.h Prototype.......VOID CTYP Vgetv(IntT r, IntT c, VcelP p, IntT l, FlgT f); Source File.....DIO\VGETV.C Arguments.......r - Row c - Column p - Buffer to receive array l - Length f - TRUE for 2-wide, FALSE for 1-wide Returns.........None. --------------------------------------------------------------------------- Vgetsv Synopsis........Get vertical column of chars only for specified length. Header File.....TCXLvid.h Prototype.......VOID CTYP Vgetsv(IntT r, IntT c, ChrP p, IntT l); Source File.....DIO\VGETSV.C Arguments.......r - Row c - Column p - Buffer to receive array l - Length Returns.........None. Page 172 TesSeRact CXL V5.52 Documentation Video Output There are two flavors of video output routines. The Vput??() functions go directly to the video hardware; while the Vprint?? functions conditionally hide the mouse, and map color attributes to monochrome if needed. The TCXL Window System routines call the Vput?? functions exclusively, since all mouse control and attribute mapping is duplicated there. In order to avoid confusion between the types of functions, the order of the parameters is different between the two series. --------------------------------------------------------------------------- Vprintc Vputc Synopsis........Put char/attr to screen. Header File.....TCXLvid.h Prototype.......VOID CTYP Vprintc(IntT r, IntT c, AtrT a, ChrT x); VOID CTYP Vputc(IntT r, IntT c, ChrT x, AtrT a); Source File.....DIO\VPRINTC.C DIO\VPUTC.C Arguments.......r - Row c - Column a - Attribute (See Appendix A) x - Character to Display Returns.........None. Notes...........Displays a character to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. Vprintc() hides the mouse cursor, if necessary, and performs character mapping. TesSeRact CXL V5.52 Documentation Page 173 --------------------------------------------------------------------------- Vprints Vputs Synopsis........Put string/attr to screen. Header File.....TCXLvid.h Prototype.......VOID CTYP Vprints(IntT r, IntT c, AtrT a, ChrP s); VOID CTYP Vputs(IntT r, IntT c, ChrP s, AtrT a); Source File.....DIO\VPRINTS.C DIO\VPUTS.C Arguments.......r - Row c - Column a - Attribute (See Appendix A) s - String to Display Returns.........None. Notes...........Displays a string to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. Vprints() hides the mouse cursor, if necessary, and performs character mapping. --------------------------------------------------------------------------- Vprintn Vputn Synopsis........Put filled string/attr to screen. Header File.....TCXLvid.h Prototype.......VOID CTYP Vprintn(IntT r, IntT c, AtrT a, ChrP s, IntT l); VOID CTYP Vputn(IntT r, IntT c, ChrP s, AtrT a, IntT l); Source File.....DIO\VPRINTN.C DIO\VPUTN.C Arguments.......r - Row c - Column a - Attribute (See Appendix A) s - String to Display l - Length to fill Returns.........None. Notes...........Displays a string, padded with spaces to the specified length, to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. Vprintn() hides the mouse cursor, if necessary, and performs character mapping. Page 174 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- Vprintw Vputw Synopsis........Put VcelT object to screen. Header File.....TCXLvid.h Prototype.......VOID Vprintw(IntT r, IntT c, VcelT x); VOID Vputw(IntT r, IntT c, VcelT x); Arguments.......r - Row c - Column a - Attribute (See Appendix A) s - String to Display l - Length to fill Returns.........None. Notes...........Displays a VcelT object to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. Vprintw() hides the mouse cursor, if necessary, and performs character mapping. --------------------------------------------------------------------------- Vprintb Vputb Synopsis........Put row array of VcelT objects to screen. Header File.....TCXLvid.h Prototype.......VOID CTYP Vprintb(IntT r, IntT c, VcelP b, IntT l); VOID CTYP Vputb(IntT r, IntT c, VcelP b, IntT l); Source File.....DIO\VPRINTB.C DIO\VPUTB.C Arguments.......r - Row c - Column b - Array of VcelT to display l - Length Returns.........None. Notes...........Displays an array of VcelT objects of the specified length, to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. Vprintb() hides the mouse cursor, if necessary, and performs character mapping. TesSeRact CXL V5.52 Documentation Page 175 --------------------------------------------------------------------------- Vputv Synopsis........Put column array of VcelT objects to screen. If <f> is TRUE, put row-wise array of <l> by 2 cells, else array of <l> by 1 cell. Header File.....TCXLvid.h Prototype.......VOID CTYP Vputv(IntT r, IntT c, VcelP p, IntT l, FlgT f); Source File.....DIO\VPUTV.C Arguments.......r - Row c - Column p - Array of VcelT to display l - Length f - TRUE for 2-wide, FALSE for 1-wide Returns.........None. Notes...........Displays an vertical array of VcelT objects of the specified length, to the screen at a specified location, using a specified attribute (See Appendix A). Does not recognize control characters and does not affect cursor position. --------------------------------------------------------------------------- Vputx Synopsis........Display VcelT object at specified position for specified count. If either element of the VcelT is zero, then only write the other byte. Header File.....TCXLvid.h Prototype.......VOID CTYP Vputx(IntT r, IntT c, VcelT x, IntT l); Source File.....DIO\VPUTX.C Arguments.......r - Row c - Column x - VcelT to display l - Length Returns.........None. Page 176 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- VputSpa Vputnca Synopsis........Displays <n> spaces (or char/attr pairs) to display. Header File.....TCXLvid.h Prototype.......VOID PAS VputSpa(IntT n); VOID PAS Vputnca(ChrT c, AtrT a, IntT n); Source File.....DIO\VPUTSPA.ASM DIO\VPUTNCA.ASM Arguments.......n - Number of spaces to display c - Character to display a - Attribute (see Appendix A) Returns.........None. Notes...........Displays the appropriate characters/attributes, updating the cursor position. Under DOS, these functions calls the video BIOS. TesSeRact CXL V5.52 Documentation Page 177 Event Subsystem The Event Subsystem is the "home" of TCXL's keyboard bindings, which provide functionality similar to keyboard macros; input direct from the keyboard and mouse that does not echo, and manages the internal key event queue. All upper-level TCXL functions call to the Event Subsystem for user input. Event Routines Asynchronous Input TCXL can maintain multiple key-binding stacks simultaneously (although only one is active at any time). The Kbnd..() functions are used to directly manipulate the global key bindings, while the Kusr..() functions are used to manipulate the additional binding stacks. This makes it possible to build all your key bindings during program initialization, and easily switch between the stacks internally, using the KbndChg() function. The KbndMou() function also makes it possible to trap mouse events at any location on the video display, regardless of which window/menu has the current input focus. --------------------------------------------------------------------------- KbndChg Synopsis........Exchange global binding stack-head with passed stack. Header File.....TCXLinp.h Prototype.......KbndP CTYP KbndChg(KbndP s); Source File.....EVT\KBNDSET.C Arguments.......s - New Key Binding Returns.........Old Key Binding Notes...........This function allows you to maintain multiple key binding lists and change back and forth between them. KbndChg() provides painless switching between various Key Binding lists. If the passed pointer is NULL, disable all keyboard bindings. Page 178 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- KbndClr KusrClr Synopsis........Removes bindings for the passed keycode. Header File.....TCXLinp.h Prototype.......IntT CTYP KbndClr(KeyT kc); IntT CTYP KusrClr(KeyT kc, KbndP kb); Source File.....EVT\KBNDSET.C EVT\KUSRSET.C Arguments.......kc - Keycode to unbind kb - Key Binding stack Returns.........0 on success, 1 if not found. --------------------------------------------------------------------------- KbndFre KusrFre Synopsis........Free key bindings from memory. Header File.....TCXLinp.h Prototype.......VOID CTYP KbndFre(NOARG); VOID CTYP KusrFre(KbndP kb); Source File.....EVT\KBNDSET.C EVT\KUSRSET.C Arguments.......kb - Key Binding stack Returns.........None. --------------------------------------------------------------------------- KbndIdle Synopsis........Bind function to keyboard idle loop. Header File.....TCXLinp.h Prototype.......VOID KbndIdle(VfvCP fi); Arguments.......fi - Idle Function Returns.........None. Notes...........This binds the passed function to the keyboard idle loop. During KeyGetc() processing, if no input is available, this routine is called. !!! WARNING !!! Do not attempt to update the display or windows every time this routine is called. Doing so will cause a mouse cursor to "flicker". Only update the display when needed. TesSeRact CXL V5.52 Documentation Page 179 --------------------------------------------------------------------------- KbndMac KusrMac Synopsis........Bind macro key string to keycode. Header File.....TCXLinp.h Prototype.......IntT CTYP KbndMac(KeyT kc, KcodP ks); IntT CTYP KusrMac(KeyT kc, KcodP ks, KbndP kb); Source File.....EVT\KBNDSET.C EVT\KUSRSET.C Arguments.......kc - Keycode to bind ks - Macro string kb - Key Binding stack Returns.........0 on success, 1 on allocation failure or circular reference. Page 180 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- KbndMou Synopsis........Bind function to passed mouse keycode and coordinates. Header File.....TCXLinp.h Prototype.......IntT CTYP KbndMou(KeyT kc, VfvCP fn, IntT r, IntT c, IntT l); Source File.....EVT\KBNDSET.C Arguments.......kc - Keycode to Bind. fn - Function to Call When Key is Pressed. r - Start row of mouse "hot spot" c - Start col of mouse "hot spot" l - Length of "hot spot" Returns.........0 on success, 1 on allocation failure. Notes...........This function adds a mouse "hot spot" to the video display. The <r,c> coordinates passed are video-relative, not window-relative, since this function will detect hotspots anywhere on the video display. This is similar to KbndSet, except there is no user-definable return-code; if a valid hot spot is found, the function is called, and then keyboard polling continues; if no hot spot is detected, the mouse event is passed back to the caller of KeyGetc(). If the bound function is executed, the complete keyboard binding stack is disabled and replaced by a NULL stack -- this is to prevent reentrancy. The bindings are restored after the bound function returns. Mouse "keycodes" are listed in INC\TCXLCOD.H. Make sure you use the full keycode; use Key_M_ClkL for a left button click, not Key_M_Clk. Note that Press/Release/Double-click keycodes are only returned when the mouse level is MOU_FULL. Works by intercepting any calls to TCXL input functions. During Input processing, the input function will determine if a key-binding exists; if so, the bound routine will be executed. If no binding exists, the Input System will continue processing as normal. TesSeRact CXL V5.52 Documentation Page 181 --------------------------------------------------------------------------- KbndPut Synopsis........Put bound key macro into TCXL key queue. Header File.....TCXLinp.h Prototype.......VOID CTYP KbndPut(KbndP p); Source File.....EVT\KBNDSET.C Arguments.......p - Key Binding Returns.........None. Notes...........This function is called automatically by KeyGetc() if a macro binding is detected. It should not be needed from user programs. --------------------------------------------------------------------------- KbndSet KusrSet Synopsis........Bind function and return keycode to passed keycode. Header File.....TCXLinp.h Prototype.......IntT CTYP KbndSet(KeyT kc, VfvCP fn, KeyT rc); IntT CTYP KusrSet(KeyT kc, VfvCP fn, KeyT rc, KbndP kb); Source File.....EVT\KBNDSET.C EVT\KUSRSET.C Arguments.......kc - Keycode to Bind. fn - Function to Call When Key is Pressed. rc - Keycode to Return to Caller After 'f' is Completed. If zero, then nothing will be returned, and execution will resume as if no key had been pressed. kb - Key Binding stack Returns.........0 on success, 1 on allocation failure. Notes...........Binds a keypress to a function call. Works by intercepting any calls to TCXL input functions. During Input processing, the input function will determine if a key- binding exists; if so, the bound routine will be executed, and the appropriate key will be returned to the calling function. If no binding exists, the Input System will continue processing as normal. Page 182 TesSeRact CXL V5.52 Documentation Input With No Echo --------------------------------------------------------------------------- KeyClear Synopsis........Clears the keyboard and mouse event buffers. Header File.....TCXLinp.h Prototype.......VOID CTYP KeyClear(NOARG); Source File.....EVT\KEYEVENT.C Arguments.......None. Returns.........None. --------------------------------------------------------------------------- KeyEvent Synopsis........Determines if a keyboard/mouse event occurred. Header File.....TCXLinp.h Prototype.......FlgT CTYP KeyEvent(NOARG); Source File.....EVT\KEYEVENT.C Arguments.......None. Returns.........TRUE if event pending, FALSE otherwise. Notes...........If no events are pending, calls the Idle function (if defined) as set by KbndIdle() (Page 179) --------------------------------------------------------------------------- KeyGetc Synopsis........Gets a keycode (ASCII/ScanCode) from the keyboard, mouse, and internal queue. Header File.....TCXLinp.h Prototype.......KeyT CTYP KeyGetc(NOARG); Source File.....EVT\KEYGETC.C Arguments.......None. Returns.........Keycode of the event. Notes...........Gets a keycode (ASCII/ScanCode) from the keyboard, mouse, and internal queue. If no events are pending, calls the Idle function (if defined) as set by KbndIdle() (Page 179) until an event occurs. TesSeRact CXL V5.52 Documentation Page 183 --------------------------------------------------------------------------- KeyPeek Synopsis........Look ahead at the next keystroke and return its value. Header File.....TCXLinp.h Prototype.......KeyT CTYP KeyPeek(NOARG); Source File.....EVT\KEYEVENT.C Arguments.......None. Returns.........KeyCode of the next key in buffer, or zero if nothing available. --------------------------------------------------------------------------- KeyStat Synopsis........Returns the status of the keyboard control keys. Header File.....TCXLinp.h Prototype.......WrdT CTYP KeyStat(NOARG); Source File.....EVT\KEYEVENT.C Arguments.......None. Returns.........Status Word of the Keyboard Flag --------------------------------------------------------------------------- KeyTime KeyWait Synopsis........Flushes the input buffers, and waits for a keyboard/mouse event. Header File.....TCXLinp.h Prototype.......KeyT CTYP KeyTime(IntT t); KeyT CTYP KeyWait(NOARG); Source File.....EVT\KEYTIME.C Arguments.......t - Timer Ticks to Wait Before Timing Out, or -1 to never time out. Returns.........KeyCode of the event, or -1 if timed out. Notes...........KeyTime() will time out and return after the passed number of timer ticks. KeyWait() will not return until an event occurs. Page 184 TesSeRact CXL V5.52 Documentation TCXL Keyboard Queue --------------------------------------------------------------------------- KqueChk Synopsis........This function determines if any keystrokes are waiting in the internal keyboard queue. Header File.....TCXLinp.h Prototype.......IntT KqueChk(NOARG); Arguments.......None Returns.........TRUE if keys are waiting, FALSE otherwise --------------------------------------------------------------------------- KqueClr Synopsis........Clears the internal keyboard queue. Header File.....TCXLinp.h Prototype.......VOID PAS KqueClr(NOARG); Source File.....EVT\KQUEPUT.ASM Arguments.......None. Returns.........None. --------------------------------------------------------------------------- KqueGet Synopsis........Returns the next keycode from the internal queue. Header File.....TCXLinp.h Prototype.......KeyT PAS KqueGet(NOARG); Source File.....EVT\KQUEPUT.ASM Arguments.......None. Returns.........Next keycode; 0 if no keys are in queue TesSeRact CXL V5.52 Documentation Page 185 --------------------------------------------------------------------------- KquePut Synopsis........Inserts the passed keystroke into the internal keyboard queue. Header File.....TCXLinp.h Prototype.......IntT PAS KquePut(KeyT k); Source File.....EVT\KQUEPUT.ASM Arguments.......k - Keystroke to Enqueue Returns.........0 on success, 1 if queue is full --------------------------------------------------------------------------- KqueStr Synopsis........Inserts the passed string into the internal keyboard queue. This is an ASCII-only string; scan codes are inserted based on KscnCod(), a DOS-only internal function. Header File.....TCXLinp.h Prototype.......IntT CTYP KqueStr(ChrP s); Source File.....EVT\KQUESTR.C Arguments.......s - String to Enqueue Returns.........0 on success, 1 if queue is full Page 186 TesSeRact CXL V5.52 Documentation Utility Subsystem Utility Routines The Utility Subsystem provides a series of useful routines for programmers. They are primarily designed for system-independent access to some useful functionality, that may or may not be provided directly by the hardware platform. --------------------------------------------------------------------------- Beep Synopsis........Sounds a beep in the speaker. Header File.....TCXLdef.h Prototype.......VOID Beep(NOARG); Arguments.......None. Returns.........None. --------------------------------------------------------------------------- RandFile Synopsis........Creates a random file name. Header File.....TCXLdef.h Prototype.......ChrP CTYP RandFile(NOARG); Source File.....UTL\RANDFILE.C Arguments.......None. Returns.........Address of the static string containing the random file name. --------------------------------------------------------------------------- Sound Synopsis........Sounds a tone of specified pitch and duration. Header File.....TCXLdef.h Prototype.......VOID CTYP Sound(WrdT pv, WrdT dt); Source File.....UTL\SOUND.C Arguments.......pv - Pitch (0-65535) dt - Duration (in timer ticks; 182=10 seconds) Returns.........None. TesSeRact CXL V5.52 Documentation Page 187 --------------------------------------------------------------------------- SysDate Synopsis........Returns a string containing the current system date. Header File.....TCXLdef.h Prototype.......ChrP CTYP SysDate(IntT d); Source File.....UTL\SYSDATE.C Arguments.......d - Date type code. One of the following: Code Example ---- ------- 0.December 3, 1988 1.3 Dec 88 2.12-3-88 3.12/3/88 4.3/12/88 5.12/03/88 Returns.........Address of the static string containing the system date. --------------------------------------------------------------------------- SysTime Synopsis........Returns a string containing the current system time. Header File.....TCXLdef.h Prototype.......ChrP CTYP SysTime(IntT t); Source File.....UTL\SYSTIME.C Arguments.......t - 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 Returns.........Address of the static string containing the system date. Page 188 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- TabNxt Synopsis........Calculates the next tab stop from given column and tab width. Header File.....TCXLdef.h Prototype.......IntT PAS TabNxt(IntT c, IntT w); Source File.....UTL\TABNXT.C Arguments.......c - Column w - Tab Width Returns.........The column of the next tab stop --------------------------------------------------------------------------- _Delay Synopsis........Delays program execution for a specified duration. Header File.....TCXLdef.h Prototype.......VOID PAS _Delay(WrdT d); Source File.....UTL\_DELAY.ASM Arguments.......d - Duration (In Timer Ticks; 182 = 10 seconds) Returns.........None. --------------------------------------------------------------------------- _StdOut Synopsis........Outputs a character to the Standard Output Device (stdout). Header File.....TCXLdef.h Prototype.......VOID PAS _StdOut(ChrT ch); Source File.....UTL\_STDOUT.ASM Arguments.......ch - Character to Output Returns.........None. TesSeRact CXL V5.52 Documentation Page 189 --------------------------------------------------------------------------- _StdOutS Synopsis........Outputs a string to the Standard Output Device (stdout). Header File.....TCXLdef.h Prototype.......VOID PAS _StdOutS(ChrP s); Source File.....UTL\_STDOUTS.C Arguments.......s - String to output. Returns.........None. --------------------------------------------------------------------------- _Timer Synopsis........Returns the value of the machine hardware timer. This value is incremented by one every 18.2 seconds. Header File.....TCXLdef.h Prototype.......DwdT PAS _Timer(NOARG); Source File.....UTL\_TIMER.ASM Arguments.......None. Returns.........Current value of the BIOS timer. --------------------------------------------------------------------------- _WaitMs Synopsis........This is a millisecond-resolution delay function. Waits for the specified number of milliseconds before returning control. Header File.....TCXLdef.h Prototype.......VOID PAS _WaitMs(IntT ms); Source File.....UTL\_WAITMS.ASM Arguments.......ms - Number of milliseconds to wait Page 190 TesSeRact CXL V5.52 Documentation Opsys Subsystem The routines in the Opsys Subsystem provide system-independent access to operating system functions. These routines, like those in the Utility Subsystem, can often provide programmers with useful routines across operating environments. Opsys Routines --------------------------------------------------------------------------- _CerrGet _CerrSet _CerrOut _CerrPush _CerrPop Synopsis........Critical Error Handler manipulation. Header File.....TCXLdos.h Prototype.......IffpCP PAS _CerrGet(NOARG); IntT PAS _CerrSet(IffpCP fa); VOID PAS _CerrOut(NOARG); IntT PAS _CerrPush(IffpCP fa); IntT PAS _CerrPop(NOARG); Source File.....OPS\_CRITERR.ASM Arguments.......fa - Critical Error Handler Routine Notes...........Under normal conditions, these routines should not be needed by users. A default critical error handler [_DefCrit] is installed by TcxlInit() when your program begins. This is a "bare-bones" error handler. If you want more detail provided, the library also contains an alternate critical error handler [_AltCrit] that provides more detail than you or your customers would ever want. To replace the current error handler with either _AltCrit() or one of your own design, use _CerrPush() with a pointer to your own handler. When you are finished using your own handler just call _CerrPop(). For more details on writing your own critical error handlers, see OPS\_ALTCRIT.C and OPS\_DEFCRIT.C. TesSeRact CXL V5.52 Documentation Page 191 --------------------------------------------------------------------------- _ChgDir Synopsis........Change Current Directory. Header File.....TCXLdos.h Prototype.......IntT PAS _ChgDir(ChrP p); Source File.....OPS\_CHDIR.ASM Arguments.......p - New Directory Name Returns.........0 on success, 1 on failure. --------------------------------------------------------------------------- _ChgDrv Synopsis........Change Current Drive. Header File.....TCXLdos.h Prototype.......IntT PAS _ChgDrv(ChrT d); Source File.....OPS\_CHDRV.ASM Arguments.......d - New Drive Letter Returns.........Last Drive in System as an upper-case letter --------------------------------------------------------------------------- _FilFnd Synopsis........Find file in current directory or along path, and return fully-qualified path name in passed buffer. Header File.....TCXLdos.h Prototype.......IntT CTYP _FilFnd(ChrP fn, ChrP bf); Source File.....OPS\_FILFND.C Arguments.......fn - Filename to find bf - Return buffer area Returns.........0 if found, and bf filled with pathname; else returns 1. Page 192 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- _FndFst _FndNxt Synopsis........File FindFirst/FindNext Routines. Header File.....TCXLdos.h Prototype.......FlgT PAS _FndFst(ChrP p, _FfbP f, IntT a); FlgT PAS _FndNxt(_FfbP f); Source File.....OPS\_FNDFST.ASM Arguments.......p - FileSpec to match f - FindFirst structure a - Attribute to match: FA_RDO...Read only FA_HID...Hidden FA_SYS...System FA_VOL...Volume label FA_DIR...Directory FA_ARC...Archive FA_DEV...Device Returns.........0 on success, 1 on failure. --------------------------------------------------------------------------- _GetDir Synopsis........Get Current Directory Routine. Header File.....TCXLdos.h Prototype.......IntT PAS _GetDir(ChrT d, ChrP p); Source File.....OPS\_GETDIR.ASM Arguments.......d - Drive Letter (0 means current drive) p - Return Buffer Returns.........Zero on success, or 1 for invalid drive. TesSeRact CXL V5.52 Documentation Page 193 --------------------------------------------------------------------------- _GetDtm Synopsis........Get system date/time and update global date/time object. Header File.....TCXLdos.h Prototype.......VOID PAS _GetDtm(NOARG); Source File.....OPS\_GETDTM.ASM Arguments.......None. The global date/time object may be accessed using the following macros: _DtmYr...Year _DtmMon..Month _DtmDay..Day of month _DtmDow..Day of week _DtmHr...Hour _DtmMin..Minute _DtmSec..Second _DtmDec..Hundredth Returns.........None. --------------------------------------------------------------------------- _GetDrv Synopsis........Get Current Drive Routine. Header File.....TCXLdos.h Prototype.......IntT PAS _GetDrv(NOARG); Source File.....OPS\_GETDRV.ASM Arguments.......None. Returns.........The current drive as an upper-case letter. --------------------------------------------------------------------------- _GetSys Synopsis........Get system version number. Header File.....TCXLdos.h Prototype.......WrdT PAS _GetSys(NOARG); Source File.....OPS\_GETSYS.ASM Arguments.......None Returns.........The operating system version number. This value is system- dependent. Page 194 TesSeRact CXL V5.52 Documentation Information Subsystem The routines provided in the Information Subsystem were originally designed for the IBM-PC/MS-DOS environment, although their functionality has been duplicated (where possible) on the different platforms TCXL has been moved to. Information Equates Machine ID's returned by Machid() IBMPC ................................................IBM PC IBMPCXT......................IBM PC/XT, Portable, old Compaq IBMPCJR.............................................IBM PCjr IBMPCAT..................IBM PC/AT, XT/286, PS/2 Model 50,60 IBMPCXT2 ..........................................IBM PC/XT IBMPS30....................................IBM PS/2 model 30 IBMCONV...................................IBM PC Convertible IBMPS80....................................IBM PS/2 model 80 SPERRYPC ..........................................Sperry PC CPQPORT..................................Old Compaq portable CPQPLUS......................................Old Compaq plus HP110 .......................................HP-110 portable HdwFlg() option flags HDW_GAM.........................................Game-adapter HDW_NDP.....................................Math-coprocessor HDW_MOU...........................................PS/2 mouse HDW_MDM...........................................PS/2 modem HDW_C40.........................................40-col color HDW_C80.........................................80-col color HDW_M80..........................................80-col mono Information Routines --------------------------------------------------------------------------- _BioEqp Synopsis........Initializes the global _HdwCtl object with hardware- specific equipment flag data. Header File.....TCXLhdw.h Prototype.......VOID PAS _BioEqp(NOARG); Source File.....HDW\_BIOEQP.ASM Arguments.......None. Returns.........None. TesSeRact CXL V5.52 Documentation Page 195 --------------------------------------------------------------------------- _InpByt _InpWrd _OutByt _OutWrd Synopsis........Read/Write from a hardware port. Header File.....TCXLdos.h Prototype.......BytT PAS _InpByt(WrdT p); WrdT PAS _InpWrd(WrdT p); VOID PAS _OutByt(WrdT p, BytT b); VOID PAS _OutWrd(WrdT p, WrdT w); Source File.....HDW\_INPBYT.ASM Arguments.......p - Port to Read/Write b - Value to write Returns.........The returned value. --------------------------------------------------------------------------- _IntEna _IntDis Synopsis........Enable/Disable hardware interrupts. Header File.....TCXLdos.h Prototype.......VOID PAS _IntEna(NOARG); VOID PAS _IntDis(NOARG); Source File.....HDW\_INTDIS.ASM Arguments.......None. Returns.........None. --------------------------------------------------------------------------- BiosVer Synopsis........Returns the machine's version date. May not return meaningful information on some machines. Header File.....TCXLhdw.h Prototype.......ChrP CTYP BiosVer(NOARG); Source File.....HDW\BIOSVER.C Arguments.......None. Returns.........The address of the static string containing the version date. Page 196 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- ClockCal Synopsis........Determines if a clock-calendar board is installed. This usually will only work with the clock-calendar boards in XT-style machines. Header File.....TCXLhdw.h Prototype.......FlgT CTYP ClockCal(NOARG); Source File.....HDW\CLOCKCAL.C Arguments.......None. Returns.........Nonzero if a clock-calendar board is present. --------------------------------------------------------------------------- MachId Synopsis........Returns the current machine type, if known. Header File.....TCXLhdw.h Prototype.......WrdT CTYP MachId(NOARG); Source File.....HDW\MACHID.C Arguments.......None. Returns.........The machine type. Under MS-DOS, this is the value of the machine ROM ID byte. TesSeRact CXL V5.52 Documentation Page 197 --------------------------------------------------------------------------- HdwFlg HdwGam HdwNdp HdwMou HdwMdm HdwC40 HdwC80 HdwM80 HdwDrv HdwPar HdwSer Synopsis........Return hardware configuration information. These do not work on all machines, under all configurations. Header File.....TCXLhdw.h Prototype.......BytT HdwFlg(NOARG); Arguments.......None. Returns.........HdwFlg - The full flag word of the hardware settings HdwGam - TRUE if game port is installed HdwNdp - TRUE if math coprocessor is installed HdwMou - TRUE if Mouse installed HdwMdm - TRUE if modem installed HdwC40 - TRUE if machine booted in 40x25 color HdwC80 - TRUE if machine booted in 80x25 color HdwM80 - TRUE if machine booted in 80x25 monochrome HdwDrv - The number of floppy disk drives installed HdwPar - The number of parallel ports installed HdwSer - The number of serial ports installed Page 198 TesSeRact CXL V5.52 Documentation Near/Far Subsystem The routines provided in the Near/Far Subsystem were originally designed for the IBM-PC/MS-DOS environment. Conversions between near and far pointers may not exist on all platforms; however, these routines will be available on all systems to provide full compatibility. Near/Far Routines --------------------------------------------------------------------------- MK_FP MK_FPT Synopsis........Create far pointers from component parts. Header File.....TCXLfar.h Arguments.......s - Segment Value o - Offset Value t - Type to cast return pointer Notes...........These macros are used to create far pointers from segment/offset combinations. MK_FP creates an anonymous pointer (void far *), while MK_FPT creates a "typed" far pointer, necessary in C++, since C++ does not permit assigning a VOID to a typed pointer. --------------------------------------------------------------------------- _FarCpy _CpyFar Synopsis........Copy data from one far pointer to another. Header File.....TCXLfar.h Source File.....HDW\_FARCPY.C Prototype.......VOID PAS _FarCpy(WrdT st, WrdT ot, WrdT sf, WrdT of, WrdT n); VOID PAS _CpyFar(BytFP t, BytFP f, WrdT n); Arguments.......st - Destination Segment ot - Destination Offset t - Far Pointer to Destination sf - Source Segment of - Source Offset f - Far Pointer to Source n - Number of Bytes to copy Returns.........None. TesSeRact CXL V5.52 Documentation Page 199 --------------------------------------------------------------------------- _FarGet _GetFar Synopsis........Copy from far pointer to standard pointer. Header File.....TCXLfar.h Source File.....HDW\_FARGET.ASM Prototype.......VOID PAS _FarGet(BytP p, WrdT s, WrdT o, WrdT n); VOID PAS _GetFar(BytP p, BytFP f, WrdT n); Arguments.......p - Destination Pointer s - Source Segment o - Source Offset f - Far Pointer to Source n - Number of Characters to copy Returns.........None. --------------------------------------------------------------------------- _FarPut _PutFar Synopsis........Copy from standard pointer to far pointer. Header File.....TCXLfar.h Source File.....HDW\_FARGET.ASM Prototype.......VOID PAS _FarGet(WrdT s, WrdT o, BytP p, WrdT n); VOID PAS _PutFar(BytFP t, BytP p, WrdT n); Arguments.......s - Destination Segment o - Destination Offset t - Far Pointer to Destination p - Source Pointer n - Number of Characters to copy Returns.........None. Page 200 TesSeRact CXL V5.52 Documentation Memory Subsystem The routines provided in the Memory Subsystem were originally designed for the IBM-PC/MS-DOS environment. Although Extended and Expanded memory have no analog in other environments, these routines will be available on all systems to provide full compatibility. Under Non-MS-DOS implementations of TCXL, all the Memory Subsystem allocation routines will fail. The function descriptions and prototype information for the expanded and extended memory functions are described in the Appendix G. Memory Routines --------------------------------------------------------------------------- _MemInit Synopsis........Initializes the Memory Subsystem. It is called automatically from inside TcxlInit(). Header File.....TCXLmem.h Prototype.......VOID PAS MemInit(NOARG); Source File.....MEM\MEMINIT.ASM Arguments.......None. Returns.........None. --------------------------------------------------------------------------- _MemTerm Synopsis........Unhook the memory subsystem. Header File.....TCXLmem.h Prototype.......VOID MemTerm(NOARG); Arguments.......None. Returns.........None. Notes...........This routine currently does nothing. It is provided for future compatibility. TesSeRact CXL V5.52 Documentation Page 201 Printer Subsystem Printer Routines --------------------------------------------------------------------------- _LPputC (Internal) Synopsis........This is an internal routine to output a character to the printer port, expanding a single "\n" to "\r\n". Header File.....TCXLprn.h Prototype.......VOID PAS _LPputC(IntT ch); Source File.....PRT\_LPPUTC.ASM Arguments.......ch - Char to Output Returns.........None. --------------------------------------------------------------------------- lcrlf Synopsis........Prints a carriage return and line feed on the printer (PRN). Header File.....tcxlprn.h Prototype.......VOID lcrlf(NOARG); Arguments.......None. Returns.........None. --------------------------------------------------------------------------- lprintc Synopsis........Prints a character on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID lprintc(IntT ch); Arguments.......ch - Character to print Returns.........None. Page 202 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- lprintf Synopsis........Sends formatted output to the printer (PRN). Works similar to the standard C printf() function. Header File.....TCXLprn.h Prototype.......VOID CDC lprintf(ChrP fs, ...); Source File.....PRT\LPRINTF.C Arguments.......fs - Format String ... - Additional Arguments Returns.........None. --------------------------------------------------------------------------- lprintn Synopsis........Prints a fixed width buffer on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP lprintn(ChrP ps, IntT nc); Source File.....PRT\LPRINTN.C Arguments.......ps - Buffer to Print nc - Number of Bytes to Print Returns.........None. --------------------------------------------------------------------------- lprintns Synopsis........Prints a string to a fixed width on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP lprintns(ChrP ps, IntT nc); Source File.....PRT\LPRINTNS.C Arguments.......ps - String to Print nc - Number of Characters to Print Returns.........None TesSeRact CXL V5.52 Documentation Page 203 --------------------------------------------------------------------------- lprints Synopsis........Prints a string on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP lprints(ChrP ps); Source File.....PRT\LPRINTS.C Arguments.......ps - String to Print Returns.........None. --------------------------------------------------------------------------- lprintsb Synopsis........Prints a bold-faced string on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP lprintsb(ChrP ps, IntT nr); Source File.....PRT\LPRINTSB.C Arguments.......ps - String to Print nr - Number of Repetitions Returns.........None --------------------------------------------------------------------------- lprintsu Synopsis........Prints an underlined string on the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP lprintsu(ChrP ps); Source File.....PRT\LPRINTSU.C Arguments.......ps - String to Print Returns.........None Page 204 TesSeRact CXL V5.52 Documentation --------------------------------------------------------------------------- scrndump Synopsis........Dumps the current screen to the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP scrndump(NOARG); Source File.....UTL\SCRNDUMP.C Arguments.......None. Returns.........None. --------------------------------------------------------------------------- windump Synopsis........Dumps a screen window to the printer (PRN). Header File.....TCXLprn.h Prototype.......VOID CTYP windump(IntT sr, IntT sc, IntT er, IntT ec); Arguments.......sr - Start Row sc - Start Column er - End Row ec - End Column Returns.........None. TesSeRact CXL V5.52 Documentation Page 205 Appendix A - Text Attributes Foreground Colors Background Colors Identifier Value Color Identifier Value Color -------------------------- -------------------------- BLACK 0x00 Black _BLACK 0x00 Black BLUE 0x01 Blue _BLUE 0x10 Blue GREEN 0x02 Green _GREEN 0x20 Green CYAN 0x03 Cyan _CYAN 0x30 Cyan RED 0x04 Red _RED 0x40 Red MAGENTA 0x05 Magenta _MAGENTA 0x50 Magenta BROWN 0x06 Brown _BROWN 0x60 Brown LGREY 0x07 Light Grey _LGREY 0x70 Light Grey DGREY 0x08 Dark Grey _DGREY 0x80 Dark Grey LBLUE 0x09 Light Blue _LBLUE 0x90 Light Blue LGREEN 0x0A Light Green _LGREEN 0xA0 Light Green LCYAN 0x0B Light Cyan _LCYAN 0xB0 Light Cyan LRED 0x0C Light Red _LRED 0xC0 Light Red LMAGENTA 0x0D Light Magenta _LMAGENTA 0xD0 Light Magenta YELLOW 0x0E Yellow _YELLOW 0xE0 Yellow WHITE 0x0F White _WHITE 0xF0 White INTENSE 0x08 Intensity Bit _BLINK 0x80 Blink/Int Bit Monochrome Colors Identifier Value Description -------------------------------- MONO_N 0x07 Normal MONO_I 0x0F Intense MONO_U 0x01 Underline MONO_IU 0x09 Intense Underline MONO_R 0x70 Reverse MONO_NB 0x87 Blink Normal MONO_IB 0x8F Blink Intense MONO_UB 0x81 Blink Underline MONO_IUB 0x89 Blink Intense Underline MONO_RB 0xF0 Blink Reverse MONO_INT 0x80 Blink Bit Page 206 TesSeRact CXL V5.52 Documentation Appendix B - Keycode Table (Note: All Keycodes are Hex values) Also See TCXLcod.H for Keyboard Mapping Equates Key Norm Shift Ctrl Alt Key Norm Shift Ctrl Alt ---- ---- ----- ---- ---- ---- ---- ----- ---- ---- A.....1E61..1E41...1E01..1E00 F1.......3B00..5400...5E00..6800 B.....3062..3042...3002..3000 F2.......3C00..5500...5F00..6900 C.....2E63..2E43...2E03..2E00 F3.......3D00..5600...6000..6A00 D.....2064..2044...2004..2000 F4.......3E00..5700...6100..6B00 E.....1265..1245...1205..1200 F5.......3F00..5800...6200..6C00 F.....2166..2146...2106..2100 F6.......4000..5900...6300..6D00 G.....2267..2247...2207..2200 F7.......4100..5A00...6400..6E00 H.....2368..2348...2308..2300 F8.......4200..5B00...6500..6F00 I.....1769..1749...1709..1700 F9.......4300..5C00...6600..7000 J.....246A..244A...240A..2400 F10......4400..5D00...6700..7100 K.....256B..254B...250B..2500 Enter....1C0D..1C0D...1C0A..N/A L.....266C..264C...260C..2600 Ins......5200..5230...N/A...N/A M.....326D..324D...320D..3200 Del......5300..532E...N/A...N/A N.....316E..314E...310E..3100 Esc......011B..011B...011B..N/A O.....186F..184F...180F..1800 Home.....4700..4737...7700..N/A P.....1970..1950...1910..1900 End......4F00..4F31...7500..N/A Q.....1071..1051...1011..1000 PgUp.....4900..4939...8400..N/A R.....1372..1352...1312..1300 PgDn.....5100..5133...7600..N/A S.....1F73..1F53...1F13..1F00 <Tab>....0F09..0F00...N/A...N/A T.....1474..1454...1414..1400 <BckSpc>.0E08..0E08...0E7F..N/A U.....1675..1655...1615..1600 <LfArr>..4B00..4B34...7300..N/A V.....2F76..2F56...2F16..2F00 <RtArr>..4D00..4D36...7400..N/A W.....1177..1157...1117..1100 <UpArr>..4800..4838...N/A...N/A X.....2D78..2D58...2D18..2D00 <DnArr>..5000..5032...N/A...N/A Y.....1579..1559...1519..1500 <Kpad 5>.N/A...4C35...N/A...N/A Z.....2C7A..2C5A...2C1A..2C00 <Grey *>.372A..N/A....7200..N/A 1.....0231..0221...N/A...7800 <Grey ->.4A2D..4A2D...N/A...N/A 2.....0332..0340...0300..7900 <Grey +>.4E2B..4E2B...N/A...N/A 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 TesSeRact CXL V5.52 Documentation Page 207 Appendix C - Window Output Escape Codes Escape Code Function ------ -------- +........increase text attribute -........decrease text attribute Ax.......set text attribute to (x) Fx.......set foreground text attribute to (x) Bx.......set background text attribute to (x) I........toggle intensity L........toggle blink X........reverse text attribute Rx.......set window row coordinate to (x) Cx.......set window column coordinate to (x) Ex.......erase (x): W....entire window, home cursor L....to end-of-line S....to end-of-window Dxy......display (x) character (y) times Window output Escape codes are only available in the window TTY output string functions. Valid functions are the entire Wput..() series of functions, incuding Wputs(), Wputf(), etc. 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 Wputf() format string, you can use the '%c' format specifier to supply the parameter from the list of variables. Example: Wputf("\033A%cNormal \033IBright\033I \033LBlink\033L" " \033XReverse\033X\n",CYAN|_BLUE); Wputf("\033R%c\033C%cRow %d, Col %d\n",3,5,3,5); Wputs("\033DA\014 = 'A' 12 times\n"); Page 208 TesSeRact CXL V5.52 Documentation Appendix D - Format Control Characters FCC Description --- ----------- TesSeRact CXL V5.52 Documentation Page 209 #........Allows numeric characters '0' thru '9'. %........Allows numeric characters '0' thru '9' and ' '. 9........Allows numeric characters '0' thru '9', '.', '-', and '+'. This field is for floating-point numeric input. The decimal does NOT need to appear in the format string, as in previous versions. The decimal IS returned as part of the input buffer. If the decimal point does not appear in this string, then the field will be treated as pure floating point, and the first time you press a decimal, the number of decimal places will be determined. $........Allows numeric characters '0' thru '9', '.', '-', and '+'. This field is for currency input. TCXL treats it as floating-point input ('9'), but the displayed field will show a '$'. This field format is valid only in an entry form, and uses the currency prefix/suffix/separator characters defined in _EntCtl. ?........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: \" Page 210 TesSeRact CXL V5.52 Documentation !........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 KvGetFmt() and KwGetFmt() only! Command Toggle Description ------- ----------- -........Decreases text attribute. Valid with KwGetFmt() only. +........Increases text attribute. Valid with KwGetFmt() only. C........Toggles copying of quoted characters to receiving buffer. 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. Default is on. L........Toggles lower-case conversion. When on, all input letters will be forced to lower-case. 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. 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. 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. Default is off. Examples: KvGetFmt(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'. KwGetFmt(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'. EntFld( 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'. TesSeRact CXL V5.52 Documentation Page 211 Appendix E - Movement and Editing Keys Field Editing 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) Menu Movement Key Action ----------------- ------ 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 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. Page 212 TesSeRact CXL V5.52 Documentation Appendix F - Global Error Codes ERR_MEM (-2) Allocation failure ERR_ARG (-1) Argument failure ERR_NUL 0 Successful return W_ESCPRESS 0x01 Escape Key Was Pressed W_ALLOCERR 0x02 Memory Allocation Error W_NOTFOUND 0x03 Record Not Found W_NOACTIVE 0x04 No Active Window W_INVCOORD 0x05 Invalid Coordinates W_INVFORMT 0x06 Invalid Format String W_NOINPDEF 0x07 No Input Fields Defined W_STRLONG 0x08 String Too Long For Window W_INVBTYPE 0x09 Invalid Border Type W_NOBORDER 0x0A No Window Border W_NOHIDDEN 0x0B No Hidden Windows W_NOTHIDD 0x0C Window Is Not Hidden W_NOSELECT 0x0D No Selectable Menu Items W_NOITMDEF 0x0E No Menu Items Defined W_NOMNUEND 0x0F No End Of Menu Specified W_NOMNUDEF 0x10 No Menu Defined W_NOMNUBEG 0x11 No Begin Of Menu Specified W_NOFRMDEF 0x12 No Form Defined W_NOFRMBEG 0x13 No Begin Of Form Specified W_NOHLPDEF 0x14 No Help Record Defined W_HLPSTKOV 0x15 Help Stack Overflow W_HLPSTKUN 0x16 Help Stack Underflow W_DOSERROR 0x17 DOS Error W_NOMATCH 0x18 No Files Matched Input Filespec W_INVTAGID 0x19 Invalid Tag Identifier W_INVPATH 0x1A Path Invalid Or Not Found W_FRMISDEF 0x1B Entry-form already defined W_FRMSTKOV 0x1C Form-stack overflow W_FRMSTKUN 0x1D Form-stack underflow W_NOHLPFIL 0x1E No help-file found W_INP2MANY 0x1F Too many entry-fields W_MNU2MANY 0x20 Too many menu-items W_INP2FEW 0x21 Not enough entry-fields W_NOINPENA 0x22 No enabled entry-field W_MNU2FEW 0x23 Not enough menu items TesSeRact CXL V5.52 Documentation Page 213 Appendix G - OS/2 Specific Information Notes about compilers TCXL-OS/2 currently supports Microsoft C, TopSpeed C/C++, Watcom C 8.5 and Zortech C/C++ 3.0. TCXL-OS/2 fully supports all TCXL-DOS functionality, with the following exceptions: There is no cricitical error handler support. There is no Ultravision support. The routines in the Memory and Information Subsystems have been stubbed out, and have no effect. Please note that the Watcom and Zortech compilers do not ship with the OS/2 header files; either the IBM or Microsoft OS/2 Programmer's Toolkit is required to recompile the library. This toolkit is not necessary to build your applications; just to rebuild the TCXL-OS/2 libraries. If you are using TopSpeed C/C++, you must copy OS2PM.H to OS2.H before rebuilding the TCXL Libraries. Page 214 TesSeRact CXL V5.52 Documentation Mid-Level Mouse Functions For normal purposes, it is not necessary for users to call the mid-level mouse functions. All mouse support is internal to the upper-level systems, and totally automatic. If it becomes necessary to call these low level functions, test your code carefully; we do not guarantee that full status information will be maintained once these functions are called. These functions are also dependent on mouse driver capabilities, and may not be portable to other operating environments/hardware platforms. --------------------------------------------------------------------------- MSgoto Synopsis........Absolutely position mouse cursor Header File.....TCXLmou.h Prototype.......VOID PAS MSgoto(IntT r, IntT c); Source File.....MOU\MSGOTO.ASM --------------------------------------------------------------------------- MSlimit Synopsis........Limit mouse cursor to specified screen area Header File.....TCXLmou.h Prototype.......VOID PAS MSlimit(IntT sr, IntT sc, IntT er, IntT ec); Source File.....MOU\MSLIMIT.ASM --------------------------------------------------------------------------- MSmove Synopsis........Read mouse driver motion counters into global _MouCtl object. Header File.....TCXLmou.h Prototype.......VOID PAS MSmove(NOARG); Source File.....MOU\MSMOVE.ASM --------------------------------------------------------------------------- MSpress Synopsis........Update global _MouCtl object with button press information. Header File.....TCXLmou.h Prototype.......VOID PAS MSpress(IntT b); Source File.....MOU\MSPRESS.ASM TesSeRact CXL V5.52 Documentation Page 215 --------------------------------------------------------------------------- MSreles Synopsis........Update global _MouCtl object with button release information. Header File.....TCXLmou.h Prototype.......VOID PAS MSreleas(IntT b); Source File.....MOU\MSPRESS.ASM --------------------------------------------------------------------------- MSreset Synopsis........Reset mouse hardware/software, maintaining mouse support level. Header File.....TCXLmou.h Prototype.......VOID POS MSreset(NOARG); Source File.....MOU\TCXLMOU.ASM --------------------------------------------------------------------------- MSspeed Synopsis........Reset mouse speed by adjusting mickey/pixel ratios. Header File.....TCXLmou.h Prototype.......VOID PAS MSspeed(IntT x, IntT y); Source File.....MOU\MSMOVE.ASM --------------------------------------------------------------------------- MSstat Synopsis........If mouse is enabled, get current position and button status bits to mouse control structure Header File.....TCXLmou.h Prototype.......VOID PAS MSstat(NOARG); Source File.....MOU\TCXLMOU.ASM --------------------------------------------------------------------------- MSupdat Synopsis........Call mouse driver to conditionally hide or show mouse cursor before update of passed screen area. Header File.....TCXLmou.h Prototype.......FlgT PAS MSupdat(FlgT hs, IntT sr, IntT sc, IntT er, IntT ec) Source File.....MOU\MSUPDAT.ASM Page 216 TesSeRact CXL V5.52 Documentation IBM Enhanced Keyboard Support --------------------------------------------------------------------------- KextOff KextOn KfixOff KfixOn Synopsis........If an enhanced (101-Key) keyboard is detected at startup time, the default action is to enable the extended keyboard BIOS and to translate all enhanced keycodes to their normal equivalents. KextOn() and KextOff() enable/disable the extended BIOS function calls, and KfixOn() and KfixOff() enable/disable the enhanced keycode translation. Header File.....TCXLinp.h Prototype.......VOID KextOff(NOARG); VOID KextOn(NOARG); VOID KfixOff(NOARG); VOID KfixOn(NOARG); Arguments.......None. Returns.........None. TesSeRact CXL V5.52 Documentation Page 217